pymaid.CatmaidInstance¶

class pymaid.CatmaidInstance(server, api_token, http_user=None, http_password=None, project_id=1, max_threads=10, make_global=True, caching=True)[source]¶

Class representing connection to a CATMAID project.

Holds base url, credentials and project ID. Fetches data and takes care of caching results. When initialised, a CatmaidInstance is made the “global” default connection for fetching data (see set_global argument). Alternatively, pymaid functions accept a remote_instance argument that lets you pass a CatmaidInstance explicitly.

server¶

The url for a CATMAID server.

Type:: str

api_token¶

API token - see CATMAID documentation on how to get it. If your CATMAID service is public and does not require a token set to None.

Type:: str | None

http_user¶

Use this if your server requires a basic HTTP authentication before it lets you through to CATMAID.

Type:: str | None, optional

http_password¶

Use this if your server requires a basic HTTP authentication before it lets you through to CATMAID.

Type:: str | None, optional

project_id¶

ID of your project. Default = 1.

Type:: int, optional

max_threads¶

Maximum parallel threads to be used. Note that some functions (e.g. pymaid.get_skid_from_node()) override this parameter. If this is set too high, you might experience connection errors when fetching data.

Type:: int | None

set_global¶

If True, this instance will be set as global (default) CatmaidInstance. This overrides pre-existing global instances.

Type:: bool, optional

caching¶

If True, will cache server responses for this session. Use CatmaidInstance.setup_cache() to set size or time limit.

Type:: bool, optional

Examples

Initialise a CatmaidInstance. Note that HTTP_USER and HTTP_PASSWORD are only necessary if your server requires HTTP authentification.

>>> rm = pymaid.CatmaidInstance('https://your.catmaid.server.org/',
...                             api_token='TOKEN')
INFO  : Global CATMAID instance set. (pymaid.fetch)

If your server requires HTTP authentification, just pass user and password as http_user and http_password:

>>> rm = pymaid.CatmaidInstance('https://your.catmaid.server.org/',
...                             api_token='TOKEN')
INFO  : Global CATMAID instance set. (pymaid.fetch)

>>> rm = pymaid.CatmaidInstance('https://your.catmaid.server.org/',
...                             api_token='TOKEN')
INFO  : Global CATMAID instance set. (pymaid.fetch)

As you instanciate a CatmaidInstance, it is made the default (“global”) remote instance and you don’t need to worry about it anymore.

By default, a CatmaidInstance will refer to the first project on your server. To illustrate, let’s assume you have two projects and you want to fetch data from both:

>>> p1 = pymaid.CatmaidInstance('https://your.catmaid.server.org/',
...                             api_token='TOKEN')
>>> # Make copy of CatmaidInstance and change project ID
>>> p2 = p1.copy()
>>> p2.project_id = 2
>>> # Fetch a neuron from project 1 and another from project 2 by
>>> # passing the CatmaidInstance explicitly via `remote_instance`
>>> n1 = pymaid.get_neuron(16, remote_instance=p1)
>>> n2 = pymaid.get_neuron(233007, remote_instance=p2)

Manually make one CatmaidInstance the global one.

>>> p2.make_global()

Ordinarily, you would use one of the wrapper functions to fetch data from the server (e.g. pymaid.get_neuron()). If however you want to get the raw data, here is how:

>>> # 1. Fetch raw skeleton data for a single neuron
>>> rm = pymaid.CatmaidInstance('https://your.catmaid.server.org/',
...                             api_token='TOKEN')
>>> skeleton_id = 16
>>> url = rm._get_compact_details_url(skeleton_id)
>>> raw_data = rm.fetch(url)
>>> # 2. Query for neurons matching given criteria using GET request
>>> GET = {'nodecount_gt': 1000, # min node size
...        'created_by': 16}     # user ID
>>> url = rm._get_list_skeletons_url(**GET)
>>> raw_data = rm.fetch(url)
>>> # 3. Fetch contributions using POST request
>>> url = rm._get_contributions_url()
>>> POST = {'skids[0]': 16, 'skids[1]': 2333007}
>>> raw_data = rm.fetch(url, POST)

__init__(server, api_token, http_user=None, http_password=None, project_id=1, max_threads=10, make_global=True, caching=True)[source]¶

Methods

`__init__`(server, api_token[, http_user, ...])
`clear_cache`()	Clear cache.
`copy`()	Returns a copy of this CatmaidInstance.
`fetch`(url[, post, files, on_error, desc, ...])	Fetch data from given URL(s).
`from_environment`(**kwargs)	Construct CatmaidInstance from environment variables.
`load_cache`(filename)	Load cache from file.
`make_global`()	Sets this variable as global by attaching it as `sys.module`
`make_url`(args, *GET)	Generates URL.
`save_cache`([filename])	Save cache to file.
`setup_cache`([caching, size_limit, time_limit])	Set up a cache for responses from the CATMAID server.
`update_credentials`()	Update session headers.

Attributes

`api_token`
`available_projects`	List of projects hosted on your server.
`cache_size`	Size of cache in mb.
`catmaid_version`	Version of CATMAID your server is running.
`http_password`
`http_user`
`image_stacks`	Image stacks available under this project id.
`max_threads`
`user_permissions`	List per-project permissions and groups of user with given token.