catpy.client module

class catpy.client.AbstractCatmaidClient

Bases: object

Abstract parent class for CatmaidClient and CatmaidClientApplications.

Users should not subclass this; it is provided purely as a convenience for type checking.

Methods

get(relative_url[, params, raw])	Get data from a running instance of CATMAID.
post(relative_url[, data, raw])	Post data to a running instance of CATMAID.

fetch

fetch(relative_url, method=u'GET', data=None, raw=False, **kwargs)

get(relative_url, params=None, raw=False, **kwargs)

Get data from a running instance of CATMAID.

Parameters:

relative_url : str or tuple of str

URL to send the request to, relative to the base_url. If a tuple is passed, its elements will be joined with ‘/’.

params: dict or str, optional

JSON-like key/value data to be included in the get URL (defaults to empty)

raw: bool, optional

Whether to return the response as a string regardless of its content-type (by default, JSON responses will be parsed)

kwargs

Extra keyword arguments to pass to requests.Session.get()

Returns:

dict or str

Data returned from CATMAID: type depends on the ‘raw’ parameter.

post(relative_url, data=None, raw=False, **kwargs)

Post data to a running instance of CATMAID.

Parameters:

relative_url : str or tuple of str

URL to send the request to, relative to the base_url. If a tuple is passed, its elements will be joined with ‘/’.

data: dict or str, optional

JSON-like key/value data to be included in the request as a payload (defaults to empty)

raw: bool, optional

Whether to return the response as a string regardless of its content-type (by default, JSON responses will be parsed)

kwargs

Extra keyword arguments to pass to requests.Session.post()

Returns:

dict or str

Data returned from CATMAID: type depends on the ‘raw’ parameter.

class catpy.client.CatmaidClient(base_url, token=None, auth_name=None, auth_pass=None, project_id=None)

Bases: catpy.client.AbstractCatmaidClient

Python object handling authentication, request pooling etc. for requests made to a CATMAID server.

Users creating their own interface should not subclass this, but instead subclass CatmaidClientApplication, which wraps a CatmaidClient object. This composition approach eases testing and sharing CatmaidClient instances among different interfaces.

Methods

fetch(relative_url[, method, data, raw])	Interact with the CATMAID server in a manner very similar to the javascript CATMAID.fetch API.
from_json(credentials)	Return a CatmaidClient instance with credentials matching those in a JSON file.
get(relative_url[, params, raw])	Get data from a running instance of CATMAID.
post(relative_url[, data, raw])	Post data to a running instance of CATMAID.
set_api_token(token)	Set CatmaidClient to use the given API token in place.
set_http_auth(username, password)	Set HTTP authorization for CatmaidClient in place.

fetch(relative_url, method=u'GET', data=None, raw=False, **kwargs)

Interact with the CATMAID server in a manner very similar to the javascript CATMAID.fetch API.

Parameters:

relative_url : str or tuple of str

URL to send the request to, relative to the base_url. If a tuple is passed, its elements will be joined with ‘/’.

method: {‘GET’, ‘POST’}, optional

HTTP method to use (the default is ‘GET’)

data: dict or str, optional

JSON-like key/value data to be included in the request as a payload (defaults to empty)

raw: bool, optional

Whether to return the response as a string regardless of its content-type (by default, JSON responses will be parsed)

kwargs

Extra keyword arguments to pass to requests.Session.get/post(), depending on method

Returns:

dict or list or str

Data returned from CATMAID. JSON responses will be parsed unless raw is True; all other responses will be returned as strings.

classmethod from_json(credentials)

Return a CatmaidClient instance with credentials matching those in a JSON file. Should have the property base_url as a minimum.

If HTTP authentication is required, should have the properties auth_name and auth_pass.

If you intend to use an authorized CATMAID account (required for some endpoints), should have the property token.

Can optionally include the property project_id.

Parameters:

credentials : str or dict

Path to the JSON credentials file, or a dict representing the object

Returns:

CatmaidClient

Instance of the API, authenticated with the encoded credentials

set_api_token(token)

Set CatmaidClient to use the given API token in place.

Parameters:

token : str

API token associated with your CATMAID account

Returns:

CatmaidClient

Reference to the same, now-authenticated CatmaidClient instance

set_http_auth(username, password)

Set HTTP authorization for CatmaidClient in place.

Parameters:

username : str

HTTP authorization username

password : str

HTTP authorization password

Returns:

CatmaidClient

Reference to the same, now-authenticated CatmaidClient instance

class catpy.client.CatmaidUrl(base_url, project_id, stack_group_id=None, stack_id=None, scale=0, x=None, y=None, z=None, tool=None, active_skeleton_id=None, active_node_id=None)

Bases: object

Methods

add_stack(stack_id[, scale])	Parameters:
from_catmaid(catmaid_client[, …])	Instantiate CatmaidUrl based on a CATMAID interface instance.
from_url(url)	Instantiate CatmaidUrl based on a URL pulled from a running CATMAID instance.
set_stack_group(stack_group_id[, scale])	Parameters:

open

add_stack(stack_id, scale=None)

Parameters:

stack_id : int

scale : float

Returns:

CatmaidUrl

A reference to itself, for chaining

classmethod from_catmaid(catmaid_client, stack_group_id=None, stack_id=None, scale=0, x=None, y=None, z=None, tool=None, active_skeleton_id=None, active_node_id=None)

Instantiate CatmaidUrl based on a CATMAID interface instance.

Parameters:

catmaid_client : CatmaidClient or catpy.applications.base.CatmaidClientApplication

stack_group_id : int

stack_id : int

scale : float

x : float

x coordinate in project (real) space

y : float

y coordinate in project (real) space

z : float

z coordinate in project (real) space

tool : str

active_skeleton_id : int

active_node_id : int

Returns:

CatmaidUrl

classmethod from_url(url)

Instantiate CatmaidUrl based on a URL pulled from a running CATMAID instance.

Parameters:

url : str

Returns:

CatmaidUrl

open()

set_stack_group(stack_group_id, scale=None)

Parameters:

stack_group_id : int

scale : float

Returns:

CatmaidUrl

A reference to itself, for chaining

tracing_tool_name = u'tracingtool'

class catpy.client.ConnectorRelation

Bases: enum.Enum

Enum describing the link between a treenode and connector, i.e. the treenode is ____ to the connector.

The enum’s name is CATMAID’s concept of “relation name”: what is returned in the relation field of the <pid>/connectors/types/ response.

The enum’s value is the name field of the <pid>/connectors/types/ response.

The mappings from relation name to relation ID are project-specific and must be fetched from CATMAID.

abutting = u'Abutting'

attached_to = u'Attachment'

close_to = u'Close to'

desmosome_with = u'Desmosome'

gapjunction_with = u'Gap junction'

is_synaptic

other = u''

postsynaptic_to = u'Postsynaptic'

presynaptic_to = u'Presynaptic'

tightjunction_with = u'Tight junction'

type

class catpy.client.ConnectorRelationType

Bases: enum.Enum

ABUTTING = u'Abutting'

ATTACHMENT = u'Attachment'

DESMOSOME = u'Desmosome'

GAP_JUNCTION = u'Gap junction'

OTHER = u''

SPATIAL = u'Spatial'

SYNAPTIC = u'Synaptic'

TIGHT_JUNCTION = u'Tight junction'

from_relation = <bound method EnumMeta.from_relation of <enum 'ConnectorRelationType'>>

class catpy.client.CoordinateTransformer(resolution=None, translation=None, orientation=<StackOrientation.XY: 0>, scale_z=False)

Bases: object

Methods

from_catmaid(catmaid_client, stack_id)	Return a CoordinateTransformer for a particular CATMAID stack.
project_to_stack(project_coords)	Take a point in project space and transform it into stack space.
project_to_stack_array(arr[, dims])	Take an array of points in project space and transform them into stack space.
stack_to_project(stack_coords)	Take a point in stack space and transform it into project space.
stack_to_project_array(arr[, dims])	Take an array of points in stack space and transform them into project space.
stack_to_scaled(stack_coords, tgt_zoom[, …])	Convert a point in stack space into a point in stack space at a different zoom level.
stack_to_scaled_array(arr, tgt_zoom[, …])	Take an array of points in stack space into scale them to a different zoom level.
stack_to_scaled_coord(dim, stack_coord, tgt_zoom)	Convert a stack coordinate in a single dimension into a pixel coordinate at the given zoom level.

project_to_stack_coord
stack_to_project_coord

classmethod from_catmaid(catmaid_client, stack_id)

Return a CoordinateTransformer for a particular CATMAID stack.

Parameters:

catmaid_client : AbstractCatmaidClient

Object capable of interfacing with Catmaid

stack_id : int

Returns:

CoordinateTransformer

project_to_stack(project_coords)

Take a point in project space and transform it into stack space.

Parameters:

project_coords : dict

x, y, and/or z coordinates in project / real space

Returns:

dict

coordinates transformed into stack / voxel space

project_to_stack_array(arr, dims=u'xyz')

Take an array of points in project space and transform them into stack space.

Currently, this is a convenience method only; it does not yet utilise array operations.

Parameters:

arr : array-like

M by 3 array containing M coordinates in project / real space in 3 dimensions

dims : str

Order of dimensions in columns, default ‘xyz’

Returns:

np.ndarray

M by 3 array containing M coordinates in stack / voxel space in 3 dimensions

project_to_stack_coord(proj_dim, project_coord)

stack_to_project(stack_coords)

Take a point in stack space and transform it into project space.

Parameters:

stack_coords : dict

x, y, and/or z coordinates in stack / voxel space

Returns:

dict

coordinates transformed into project / real space

stack_to_project_array(arr, dims=u'xyz')

Take an array of points in stack space and transform them into project space.

Currently, this is a convenience method only; it does not yet utilise array operations.

Parameters:

arr : array-like

M by N array containing M coordinates in stack / voxel space in N dimensions

dims : array-like or str

Order of dimensions in columns, default ‘xyz’

Returns:

np.ndarray

M by N array containing M coordinates in project / real space in N dimensions

stack_to_project_coord(stack_dim, stack_coord)

stack_to_scaled(stack_coords, tgt_zoom, src_zoom=0)

Convert a point in stack space into a point in stack space at a different zoom level.

Whether z coordinates are scaled is controlled by the scale_z constructor argument/ instance variable.

Parameters:

stack_coords : dict

x, y, and/or z coordinates in stack / voxel space

tgt_zoom : float

Desired zoom level out of the output coordinates

src_zoom : float

Zoom level of the given coordinates (default 0)

Returns:

dict

Rescaled coordinates

stack_to_scaled_array(arr, tgt_zoom, src_zoom=0, dims=u'xyz')

Take an array of points in stack space into scale them to a different zoom level.

Whether z coordinates are scaled is controlled by the scale_z constructor argument/ instance variable.

Parameters:

arr : np.ndarray

M by N array containing M coordinates in stack / voxel space in N dimensions

tgt_zoom : float

Desired zoom level out of the output coordinates

src_zoom : float

Zoom level of the given coordinates (default 0)

dims : str

Order of dimensions in columns, default (x, y, z)

Returns:

np.ndarray

stack_to_scaled_coord(dim, stack_coord, tgt_zoom, src_zoom=0)

Convert a stack coordinate in a single dimension into a pixel coordinate at the given zoom level.

Whether z coordinates are scaled is controlled by the scale_z constructor argument/ instance variable.

Parameters:

dim : {‘x’, ‘y’, ‘z’}

Which dimension to act in

stack_coord : float

tgt_zoom : float

Desired zoom level out of the output coordinate

src_zoom : float

Zoom level of the given coordinate (default 0)

Returns:

float

class catpy.client.StackOrientation

Bases: enum.IntEnum

Can be iterated over or indexed like the lower-case string representation of the orientation

XY = 0

XZ = 1

ZY = 2

from_str = <bound method EnumMeta.from_str of <enum 'StackOrientation'>>

from_value = <bound method EnumMeta.from_value of <enum 'StackOrientation'>>

exception catpy.client.WrappedCatmaidException(message, response)

Bases: exceptions.Exception

exception_keys = frozenset([u'traceback', u'type', u'error'])

classmethod raise_on_error(response)

spacer = u' '

catpy.client.get_typed(d, key, constructor=None, default=None)

like dict.get, but if the response/default is not None, pass it to the given constructor.

Parameters:

d : dict

key : hashable

constructor : callable

default

catpy.client.make_url(base_url, *args)

Given any number of URL components, join them as if they were a path regardless of trailing and prepending slashes

Examples

>>> make_url('google.com', 'mail')
'google.com/mail'

>>> make_url('google.com/', '/mail')
'google.com/mail'