Graphs

class castalign.graph.Graph(name='')[source]

Bases: object

Store 3D image nodes and transforms between node spaces.

Nodes can store image data directly or reference another node’s image. Edges store transforms between node coordinate systems.

__init__(name='')[source]

Create an empty graph.

Parameters:: name (str, optional) – Graph name.

save(filename=None)[source]

Save the graph.

Parameters:: filename (str or path-like or None, optional) – Output path. If omitted, uses self.filename.
Return type:: None

Notes

If no extension is provided, .db is appended.

classmethod load(filename)[source]

Load a graph.

Parameters:: filename (str or path-like) – Input graph file.
Returns:: Loaded graph.
Return type:: Graph

add_node(name, image=None, compression='normal', metadata=None)[source]

Add a node, optionally with image data or an image reference.

Setting the image to be a reference (the name of another node with image data) can be used if the image data for this node can be computed from that of another node. For instance, one node might be identical to another node but have a different voxel size (see example).

Parameters:

name (str) – New node name.
image (ndarray or str or None, optional) –
- ndarray: 2D or 3D image (2D is interpreted as (1, Y, X)).
- str: name of another existing node with an image.
- None: no image attached.
compression ({‘low’, ‘normal’, ‘high’, ‘label’}, optional) – Compression level for stored ndarray image data.
metadata (object, optional) – Per-node metadata.

Return type:

None

Examples

>>> g.add_node("session1", image=session1_vol)
>>> g.add_node("session1_1umvoxels", image="session1")
>>> g.add_edge("session1", "session1_1umvoxels", RescaleParametric(z=1, x=.3, y=.3))

remove_node(name)[source]

Remove a node and all incident edges.

Parameters:: name (str) – Node name to remove.
Return type:: None

replace_node_image(name, image=None, compression='normal')[source]

Replace or remove a node image without changing graph connections.

Parameters:

name (str) – Node name.
image (ndarray or str or None, optional) – New image volume, reference node name, or None to remove image. 2D input is promoted to (1, Y, X).
compression ({‘low’, ‘normal’, ‘high’, ‘label’}, optional) – Compression level for stored ndarray image data.

Return type:

None

add_edge(frm, to, transform, update=False)[source]

Add or update a transform edge between two nodes.

Parameters:

frm (str) – Source node.
to (str) – Destination node.
transform (transform.Transform) – Transform from frm to to.
update (bool, optional) – If False, edge must not exist yet. If True, edge must already exist and is replaced.

Return type:

None

remove_edge(frm, to)[source]

Remove an edge and its reverse edge if present.

Parameters:

frm (str) – Source node.
to (str) – Destination node.

Return type:

None

connected_components()[source]

Find connected components in the graph.

This does not yet support directed graphs, i.e., graphs which contain non-invertable transforms.

Returns:: One set per connected component.
Return type:: list of set[str]

unload()[source]

Clear memory by unloading the node images, keeping only the compressed forms.

Return type:: None

get_chain(frm, to)[source]

Return a node path from frm to to.

This returns the node chain used to compose transforms between nodes. The returned values are node names (not transforms).

Parameters:

frm (str) – Start node.
to (str) – End node.

Returns:

Path nodes excluding frm and ending at to. Returns [] when frm == to.

Return type:

list[str]

Raises:

RuntimeError – If no path exists between the two nodes.

get_transform(frm, to)[source]

Return a transform from frm to to.

The transform is composed along the shortest path from frm to to (returned by get_chain()), applying each edge transform in path order.

Parameters:

frm (str) – Source node.
to (str) – Destination node.

Returns:

Composed transform from frm to to. Returns Identity() when frm == to.

Return type:

transform.Transform

has_transform(frm, to)[source]

Check whether a transform path exists between two nodes.

This is equivalent to determining whether get_transform() raises an error.

Parameters:

frm (str) – Source node.
to (str) – Destination node.

Returns:

True if a transform can be composed.

Return type:

bool

get_image(node)[source]

Get image data for a node.

Parameters:: node (str) – Node name.
Returns:: Node image data.
Return type:: ndarray

Notes

If the node image is a reference ("ref:other_node"), the referenced image is transformed into this node’s space and returned.

visualise(filename=None, nearby=None)[source]

Render a Graphviz visualization of the graph.

Parameters:

filename (str or path-like or None, optional) – Output filename stem. If None, a temporary file is used.
nearby (str or None, optional) – If provided, only draw edges connected to this node.

Return type:

None

Notes

This requires the “graphviz” package to be installed.

castalign.graph.load(fn, version=None)[source]

Load a Graph or Transform from file.

Parameters:

fn (str or path-like) – Input file path.
version (int or None, optional) – Transform file format version, used only when fn is a transform text file.

Returns:

Loaded object.

Return type:

Graph or transform.Transform

Examples

>>> g = load("my_graph.db") # Loads a graph
>>> t = load("my_transform.txt") # Loads a transform

castalign.graph.TransformGraph: alias of Graph