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.

pymaid.connect_catmaid(**kwargs)	Connect to CATMAID server using environmental variables.
pymaid.CatmaidInstance(server, api_token[, ...])	Class representing connection to a CATMAID project.
pymaid.CatmaidInstance.copy()	Returns a copy of this CatmaidInstance.
pymaid.CatmaidInstance.clear_cache()	Clear cache.
pymaid.CatmaidInstance.fetch(url[, post, ...])	Fetch data from given URL(s).
pymaid.CatmaidInstance.load_cache(filename)	Load cache from file.
pymaid.CatmaidInstance.make_url(*args, **GET)	Generates URL.
pymaid.CatmaidInstance.setup_cache([...])	Set up a cache for responses from the CATMAID server.
pymaid.CatmaidInstance.save_cache([filename])	Save cache to file.

Fetching data

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

Neurons

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).
pymaid.get_skids_by_annotation(annotations)	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.
pymaid.get_skeleton_ids([created_by, ...])	Get all skeleton IDs from the project matching given filters.

Neuron labels

pymaid.neuron_label.NeuronLabeller([...])	Class for calculating neurons' labels, as used in the CATMAID frontend.
pymaid.neuron_label.SkeletonId()	LabelComponent which adds a skeleton ID modelling a neuron to its label.
pymaid.neuron_label.NeuronName()	LabelComponent which adds a neuron's name to its label.
pymaid.neuron_label.Annotations([...])	LabelComponent which adds annotations to a neuron's label.
pymaid.neuron_label.ThinNeuron([...])	Class containing some very basic information about a neuron as needed by NeuronLabeller.

Annotations

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).
pymaid.get_annotation_id(annotations[, ...])	Retrieve the annotation ID for single or list of annotation(s).
pymaid.get_entity_graph([types, by_name, ...])	Get a networkx DiGraph of semantic objects.

Nodes

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.

Tags

Functions to fetch node tags:

pymaid.get_label_list([remote_instance])	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.

Connectivity

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.
pymaid.get_user_list([remote_instance])	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.

Volumes

Functions to fetch volumes (meshes):

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

Retrieves volume (mesh).

Landmarks

Functions to fetch data about landmarks.

pymaid.get_landmarks([with_locations, ...])	Get all landmarks from CATMAID, optionall with locations associated with them.
pymaid.get_landmark_groups([with_locations, ...])	Get the landmark groups, optionally with IDs of their members and locations.
pymaid.LandmarkMatcher(landmarks, ...)	Class for finding matching pairs of landmark locations between two groups.
pymaid.CrossProjectLandmarkMatcher(this_lms, ...)	Class for finding matching pairs of landmark locations between two instances.

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 metadata

Functions to fetch information about the image stacks CATMAID knows about.

pymaid.get_stacks([remote_instance])	Get summary of all stacks in the project.
pymaid.get_stack_info(stack[, remote_instance])	Get information about an image stack.
pymaid.get_mirror_info(stack, mirror[, ...])	Get information about a stack mirror.

Image data (tiles and N5 volumes)

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)
>>> from pymaid.stack import Stack
>>> help(Stack)

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.
pymaid.stack.Stack(stack_info[, mirror])	Class representing a CATMAID stack of images.

Misc

Functions to fetch miscellaneous data:

pymaid.clear_cache()	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!

Neurons

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.

Annotations

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

Nodes

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.

Connectivity

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.

Tags

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

Volumes

Upload volumes:

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

Upload volume/mesh to CatmaidInstance.

CatmaidNeuron/List

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:

pymaid.CatmaidNeuron.copy([deepcopy])	Return a copy of this neuron.
pymaid.CatmaidNeuron.downsample([factor, ...])	Downsample the neuron by given factor.
pymaid.CatmaidNeuron.plot3d(**kwargs)	Plot neuron using navis.plot3d().
pymaid.CatmaidNeuron.plot2d(**kwargs)	Plot neuron using navis.plot2d().
pymaid.CatmaidNeuron.prune_by_strahler(to_prune)	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.
pymaid.CatmaidNeuron.prune_proximal_to(node)	Remove nodes proximal to given node.
pymaid.CatmaidNeuron.prune_by_longest_neurite([...])	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.
pymaid.CatmaidNeuron.reload([remote_instance])	Reload neuron from server.
pymaid.CatmaidNeuron.resample(resample_to[, ...])	Resample neuron to given resolution.
pymaid.CatmaidNeuron.summary([add_props])	Get a summary of this neuron.

CatmaidNeuronList-specific

Methods specific to CatmaidNeuronLists:

pymaid.CatmaidNeuronList.to_selection([save_to])	Generate JSON file which can be loaded in CATMAID selection tables.
pymaid.CatmaidNeuronList.from_selection(fname)	Generate NeuronList from CATMAID JSON file.
pymaid.CatmaidNeuronList.has_annotation(x[, ...])	Filter neurons by their annotations.
pymaid.CatmaidNeuronList.head([N])	Return summary for top N neurons.
pymaid.CatmaidNeuronList.tail([N])	Return summary for bottom N neurons.
pymaid.CatmaidNeuronList.itertuples()	Helper to mimic pandas.DataFrame.itertuples().
pymaid.CatmaidNeuronList.remove_duplicates([...])	Remove duplicate neurons from list.
pymaid.CatmaidNeuronList.sample([N])	Return random subset of neurons.
pymaid.CatmaidNeuronList.summary([N, add_props])	Get summary over all neurons in this NeuronList.
pymaid.CatmaidNeuronList.mean()	Return mean numeric and boolean values over all neurons.
pymaid.CatmaidNeuronList.sum()	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:

Morphology

pymaid.remove_tagged_branches(x, tag[, how, ...])	Removes branches with a given treenode tag (e.g. not a branch).
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.

Analysis

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.

Analyses

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.

Filtering

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.

Utility

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.
pymaid.set_loggers([level])	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.