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).

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.