API Reference

Connecting to a Server

Connections to servers are represented by a CatmaidInstance object. You can either initialize it directly or store credentials as environmental variables and use connect_catmaid() to do that for you.


Connect to CATMAID server using environmental variables.

pymaid.CatmaidInstance(server, api_token[, ...])

Class representing connection to a CATMAID project.


Returns a copy of this CatmaidInstance.


Clear cache.

pymaid.CatmaidInstance.fetch(url[, post, ...])

Fetch data from given URL(s).


Load cache from file.

pymaid.CatmaidInstance.make_url(*args, **GET)

Generates URL.


Set up a cache for responses from the CATMAID server.


Save cache to file.

Fetching data

This section contains functions to pull data from a CATMAID server.


Functions related to searching for neurons and fetching their 3D skeletons:

pymaid.find_neurons([names, annotations, ...])

Find neurons matching given search criteria.

pymaid.get_arbor(x[, node_flag, ...])

Retrieve skeleton data for a list of skeleton ids.

pymaid.get_names(x[, remote_instance])

Retrieve neuron names for a list of skeleton ids.

pymaid.get_neuron(x[, with_connectors, ...])

Retrieve 3D skeleton data as CatmaidNeuron/List.

pymaid.get_neuron_id(x[, remote_instance])

Get neuron ID(s) for given skeleton(s).

pymaid.get_neurons_in_volume(volumes[, ...])

Retrieves neurons with processes within CATMAID volumes.

pymaid.get_origin(x[, chunk_size, ...])

Get origin of given neuron(s).


Retrieve the neurons annotated with given annotation(s).

pymaid.get_skids_by_name(names[, ...])

Retrieve the all neurons with matching name.

pymaid.get_skids_by_origin(source_ids, ...)

Get skeleton IDs by origin.

pymaid.get_skeleton_change(x[, chunk_size, ...])

Get split and merge history of skeletons.


Functions to fetch annotations:

pymaid.get_annotated(x[, ...])

Retrieve entities (neurons + annotations) with given annotation(s).

pymaid.get_annotations(x[, remote_instance])

Retrieve annotations for a list of skeleton ids.

pymaid.get_annotation_details(x[, ...])

Retrieve annotations for a set of neuron.

pymaid.get_user_annotations(x[, remote_instance])

Retrieve annotations used by given user(s).


Functions to fetch nodes and connectors:

pymaid.find_nodes([tags, node_ids, ...])

Get nodes by tag (label), ID or associated skeleton.

pymaid.get_connectors_in_bbox(bbox[, unit, ...])

Retrieves connectors within given bounding box.

pymaid.get_skid_from_node(node_ids[, ...])

Retrieve skeleton IDs from a list of nodes.

pymaid.get_node_details(x[, chunk_size, ...])

Retrieve detailed info for nodes and/or connectors.

pymaid.get_nodes_in_volume(*x[, ...])

Retrieve nodes and connectors in given bounding box.

pymaid.get_node_location(x[, sort, ...])

Retrieves location for a set of nodes or connectors.

pymaid.get_node_table(x[, include_details, ...])

Retrieve node table(s) for a list of neurons.

pymaid.get_node_info(x[, remote_instance])

Retrieve info for a set of nodes.


Functions to fetch node tags:


Retrieves all labels (node tags only) in a project.

pymaid.get_node_tags(node_ids, node_type[, ...])

Retrieve tags for a set of nodes OR connectors.


Functions to fetch connectivity data:

pymaid.adjacency_matrix(sources[, targets, ...])

Generate adjacency matrix between source and target neurons.

pymaid.adjacency_from_connectors(source[, ...])

Regenerate adjacency matrices from neurons' connectors.

pymaid.cn_table_from_connectors(x[, ...])

Generate connectivity table from neurons' connectors.

pymaid.get_connectivity_counts(x[, ...])

Fetch number of connections of a given type for a set of neurons.

pymaid.get_connectors(x[, relation_type, ...])

Retrieve connectors based on a set of filters.

pymaid.get_connector_details(x[, ...])

Retrieve details on sets of connectors.

pymaid.get_connectors_between(a, b[, ...])

Retrieve connectors between sets of neurons.

pymaid.get_connector_links(x[, with_tags, ...])

Retrieve connectors links for a set of neurons.

pymaid.get_connectors_in_bbox(bbox[, unit, ...])

Retrieves connectors within given bounding box.

pymaid.get_edges(x[, remote_instance])

Retrieve edges between sets of neurons.

pymaid.get_partners(x[, threshold, ...])

Retrieve partners connected by synapses, gap junctions or attachments.

pymaid.get_partners_in_volume(x, volume[, ...])

Retrieve the synaptic/gap junction partners within a CATMAID Volume.

pymaid.get_nth_partners(x[, n_circles, ...])

Retrieve Nth partners.

pymaid.get_paths(sources, targets[, n_hops, ...])

Fetch paths between two sets of neurons.

User stats

Functions to fetch user stats:

pymaid.get_contributor_statistics(x[, ...])

Retrieve contributor statistics for given skeleton ids.

pymaid.get_history([start_date, end_date, ...])

Retrieves CATMAID project history.

pymaid.get_logs([operations, entries, ...])

Retrieve logs (same data as in log widget).

pymaid.get_transactions([range_start, ...])

Retrieve individual transactions with server.

pymaid.get_team_contributions(teams[, ...])

Get contributions by teams (nodes, reviews, connectors, time invested).

pymaid.get_time_invested(x[, mode, by, ...])

Calculate the time spent working on a set of neurons.


Get list of users.

pymaid.get_user_contributions(x[, teams, ...])

Return number of nodes and synapses contributed by each user.

pymaid.get_user_stats([start_date, ...])

Get user stats similar to the pie chart statistics widget in CATMAID.


Functions to fetch volumes (meshes):

pymaid.get_volume([volume_name, color, ...])

Retrieves volume (mesh).

Reconstruction samplers

Functions for reconstruction samplers:

pymaid.get_sampler([x, remote_instance])

Get list of reconstruction samplers.

pymaid.get_sampler_domains(sampler[, ...])

Get list of domains for given sampler.

pymaid.get_sampler_counts(x[, remote_instance])

Get number of reconstruction samplers for a set of neurons.

Image data (tiles)

Functions to fetch and process image data. Note that this is not imported at top level but has to be imported explicitly:

>>> from pymaid import tiles
>>> help(tiles.crop_neuron)

pymaid.tiles.TileLoader(bbox, stack_id[, ...])

Load tiles from CATMAID, stitch into image and render output.

pymaid.tiles.crop_neuron(x, output[, ...])

Crop and save EM tiles following a neuron's segments.


Functions to fetch miscellaneous data:


Clear cache of global CatmaidInstance.

pymaid.has_soma(x[, tag, min_rad, ...])

Check if neuron(s) has soma.

pymaid.get_cable_lengths(x[, chunk_size, ...])

Get cable lengths directly from Catmaid Server.

pymaid.get_import_info(x[, with_nodes, ...])

Get count of imported nodes for given neuron(s).

pymaid.get_review(x[, remote_instance])

Retrieve review status for a set of neurons.

pymaid.get_review_details(x[, remote_instance])

Retrieve review status (reviewer + timestamp) by node for given neuron.

pymaid.url_to_coordinates(coords, stack_id)

Generate URL to a location.

Uploading data

Functions to push data to a CATMAID server. Use these with caution!


Upload, rename, move or delete neurons:

pymaid.delete_neuron(x[, no_prompt, ...])

Completely delete neurons.

pymaid.differential_upload(x[, skeleton_id, ...])

Upload only changes made to a neuron.

pymaid.push_new_root(new_root[, no_prompt, ...])

Reroot neuron on server.

pymaid.rename_neurons(x, new_names[, ...])

Rename neuron(s).

pymaid.replace_skeleton(x[, skeleton_id, ...])

Replace skeleton in CatmaidInstance.

pymaid.join_skeletons(x[, winner, ...])

Join multiple skeletons by minimizing the length of the newly added edges (minimum spanning tree).

pymaid.transfer_neuron(x, source_instance, ...)

Copy neuron(s) from one CatmaidInstance to another.

pymaid.update_radii(radii[, chunk_size, ...])

Change radii [nm] of given nodes.

pymaid.upload_neuron(x[, import_tags, ...])

Export (upload) neurons to CatmaidInstance.


Edit neuron annotations:

pymaid.add_annotations(x, annotations[, ...])

Add annotation(s) to a list of neuron(s).

pymaid.add_meta_annotations(to_annotate, to_add)

Add meta-annotation(s) to annotation(s).

pymaid.remove_annotations(x, annotations[, ...])

Remove annotation(s) from a list of neuron(s).

pymaid.remove_meta_annotations(remove_from, ...)

Remove meta-annotation(s) from annotation(s).


Edit nodes:

pymaid.add_node(coords[, parent_id, radius, ...])

Create single (!) node at given location.

pymaid.delete_nodes(node_ids, node_type[, ...])

Delete given nodes or connectors.

pymaid.join_nodes(winner_node, looser_node)

Join two skeletons by nodes.

pymaid.move_nodes(new_locs, node_type[, ...])

Update location of given nodes or connectors.

pymaid.set_nodes_reviewed(x[, remote_instance])

Set a list of nodes as reviewed.

pymaid.update_node_confidence(confidences[, ...])

Change node confidences.


Edit connectors and connector links:

pymaid.add_connector(coords[, ...])

Create connector(s) at given location.

pymaid.link_connector(links[, remote_instance])

Link connectors with nodes.


Edit tags:

pymaid.add_tags(node_list, tags, node_type)

Add or edit tag(s) for a list of node(s) or connector(s).

pymaid.delete_tags(node_list, tags, node_type)

Remove tag(s) for a list of node(s) or connector(s).


Upload volumes:

pymaid.upload_volume(x, name[, comments, ...])

Upload volume/mesh to CatmaidInstance.


Neuron/List objects representing neurons and lists thereof:

pymaid.CatmaidNeuron(x[, remote_instance, units])

Catmaid neuron object holding neuron data (nodes, connectors, name, etc) and providing quick access to various PyMaid functions.

pymaid.CatmaidNeuronList(x[, make_copy])

Compilation of CatmaidNeuron that allow quick access to neurons' attributes/functions.

CatmaidNeuron are a subclasses of <navis https://navis.readthedocs.io/en/latest/>_ TreeNeuron and as such can be used with navis functions.

CatmaidNeuron/List methods

Methods common to both CatmaidNeurons and CatmaidNeuronLists:


Return a copy of this neuron.

pymaid.CatmaidNeuron.downsample([factor, ...])

Downsample the neuron by given factor.


Plot neuron using navis.plot3d().


Plot neuron using navis.plot2d().


Prune neuron based on Strahler order.

pymaid.CatmaidNeuron.prune_by_volume(v[, ...])

Prune neuron by intersection with given volume(s).

pymaid.CatmaidNeuron.prune_distal_to(node[, ...])

Cut off nodes distal to given nodes.


Remove nodes proximal to given node.


Prune neuron down to the longest neurite.

pymaid.CatmaidNeuron.prune_twigs(size[, ...])

Prune terminal twigs under a given size.

pymaid.CatmaidNeuron.reroot(new_root[, inplace])

Reroot neuron to given node ID or node tag.


Reload neuron from server.

pymaid.CatmaidNeuron.resample(resample_to[, ...])

Resample neuron to given resolution.


Get a summary of this neuron.


Methods specific to CatmaidNeuronLists:


Generate JSON file which can be loaded in CATMAID selection tables.


Generate NeuronList from CATMAID JSON file.

pymaid.CatmaidNeuronList.has_annotation(x[, ...])

Filter neurons by their annotations.


Return summary for top N neurons.


Return summary for bottom N neurons.


Helper to mimic pandas.DataFrame.itertuples().


Remove duplicate neurons from list.


Return random subset of neurons.

pymaid.CatmaidNeuronList.summary([N, add_props])

Get summary over all neurons in this NeuronList.


Return mean numeric and boolean values over all neurons.


Return sum numeric and boolean values over all neurons.

pymaid.CatmaidNeuronList.sort_values(key[, ...])

Sort neurons by given key.

Working with Neurons

As said previously, CatmaidNeuron can be used with <navis https://navis.readthedocs.io/en/latest/>_. This includes functions to manipulate (e.g. prune, subset, resample), analyze (e.g. strahler index, synapse flow) or plot neurons.

In addition, pymaid has a few more CATMAID-specific functions:


pymaid.remove_tagged_branches(x, tag[, how, ...])

Removes branches with a given treenode tag (e.g.

pymaid.time_machine(x, target[, inplace, ...])

Reverses time and make neurons young again!

pymaid.prune_by_length(x[, min_length, ...])

Remove segments of given length.

pymaid.union_neurons(*x[, limit, ...])

Generate the union of a set of neurons.


Various morphology metrics:

pymaid.arbor_confidence(x[, confidences, ...])

Calculate along-the-arbor confidence for each treenode.

Predicting connectivity

Function to predict connectivity:

pymaid.predict_connectivity(source, target)

Calculate potential synapses from source onto target neurons.


Functions to analyse connectivity:

pymaid.cluster_by_connectivity(x[, ...])

Cluster neurons based on connectivity.

pymaid.cluster_by_synapse_placement(x[, ...])

Cluster neurons based on their synapse placement.

pymaid.ClustResults(mat[, labels, mat_type])

Class to handle, analyze and plot similarity/distance matrices.

pymaid.connection_density(s, t[, method, ...])

Calculate connection density.

pymaid.sparseness(x[, which])

Calculate sparseness.


Functions to filter connectivity data:

pymaid.filter_connectivity(x, restrict_to[, ...])

Filter connectivity data by volume or skeleton data.

pymaid.shared_partners(a, b[, upstream, ...])

Return shared partners between neuron(s) A and B.


Various utility functions.

pymaid.eval_skids(x[, remote_instance, ...])

Extract skeleton IDs from input.

pymaid.set_pbars([hide, leave, jupyter])

Set global progress bar behaviors.


Helper function to set levels for all associated module loggers.

pymaid.shorten_name(x[, max_len])

Shorten a neuron name by iteratively removing non-essential bits.