graph_gt

Graph class and utilities built on the graph-tool library.

Graph is the central data structure for vasculature and network analyses in ClearMap. It wraps a graph_tool.Graph backend and adds:

• Spatial embedding — vertex coordinates in voxels (coordinates), physical units (coordinates_units), and atlas space (coordinates_atlas).

• Edge geometry — variable-length arrays stored along each edge that capture intermediate vertex positions, radii, and labels between branch points. Two storage modes are supported: 'graph' (a single flat array at graph level, indexed by per-edge start/end pairs) and 'edge' (variable-length vectors stored in each edge property). Convert between them with Graph.set_edge_geometry_type().

• Vessel typing — properties for artery/vein binary labels, signal intensity, radii in voxels and µm, distance to surface, and atlas annotation.

• Subgraph extraction — Graph.sub_graph() (vertex/edge masks), Graph.sub_slice() (axis-aligned spatial window), Graph.largest_component().

• Atlas annotation — Graph.annotate_properties() and Graph.transform_properties() apply arbitrary callables to vertex or edge properties in one pass.

• Morphological graph operations — binary dilation, erosion, opening, and closing on vertex and edge label arrays, propagating along graph topology.

• Persistence — Graph.save() / Graph.load() via the graph-tool .gt format.

Typical usage

Graphs are produced by graph_from_skeleton() and then simplified by cleaning and reduction

See also

ClearMap.Analysis.graphs.graph_processing

Graph construction, cleaning, reduction, and label tracing.

VesselGraphProcessor

Pipeline orchestrator that builds and annotates vasculature graphs.

class Graph(name=None, n_vertices=None, edges=None, directed=None, vertex_coordinates=None, vertex_radii=None, edge_coordinates=None, edge_radii=None, edge_geometries=None, shape=None, vertex_labels=None, edge_labels=None, annotation=None, base=None, edge_geometry_type='graph')

Bases: AnnotatedGraph

Graph class to handle graph construction and analysis.

Note

This is an interface from ClearMap graphs to graph_tool.

classmethod load(filename, ignore_vp=None, ignore_ep=None, ignore_gp=None)

classmethod partial_load(filename: str, *, exclude_edge_geometry_properties: bool = False, include_dict: Dict[str, Iterable[str]] | None = None, exclude_dict: Dict[str, Iterable[str]] | None = None, include: Iterable[str] | None = None, exclude: Iterable[str] | None = None)

Partially load a graph from a file, allowing for selective property inclusion/exclusion.

Five options are available, in order of precedence:

1. exclude_edge_geometry_properties: if True, all edge geometry properties (those starting with 'edge_geometry_') are excluded.

2. include_dict: a dictionary specifying which properties to include for each scope ('vertex', 'edge', 'graph').

3. exclude_dict: a dictionary specifying which properties to exclude for each scope.

4. include: a list of property names to include across all scopes.

5. exclude: a list of property names to exclude across all scopes.

Note

To inspect which properties are available in the file, use Graph.scan_gt_properties(filename, as_dict=True).

static scan_gt_properties(filename: str, as_dict: bool = False)

Scan the graph-tool file for its properties without loading the entire graph.

Parameters:

• filename (str) – The path to the graph-tool file.

• as_dict (bool) – If True, return a dictionary of property names. If False, return a list of tuples (scope, name, dtype).

add_edge(edge)

add_edge_property(name, source=None, dtype=None)

add_graph_property(name, source, dtype=None)

add_vertex(n_vertices=None, vertex=None)

add_vertex_property(name, source=None, dtype=None)

annotate_properties(annotation, vertex_properties=None, edge_properties=None, edge_geometry_properties=None)

axis_indices(axis=None, as_list=False)

copy(from_disk=False, path='')

define_edge_geometry_indices_graph(indices)

define_edge_property(name, source, edge=None, dtype=None)

define_graph_property(name, source, dtype=None)

define_vertex_property(name, source, vertex=None, dtype=None)

edge(edge)

edge_annotation(edge=None)

edge_close_binary(label, steps=1)

edge_connectivity(order='src_vertex')

edge_coordinates(edge=None)

edge_dilate_binary(label, steps=1)

edge_erode_binary(label, steps=1)

edge_geometry(name='coordinates', edge=None, as_list=True, return_indices=False, reshape=True, ndim=None)

edge_geometry_from_edge_property(edge_property_name, edge_geometry_name=None)

edge_geometry_indices()

edge_geometry_lengths(name='coordinates')

edge_geometry_property(name)

edge_geometry_property_name(name='coordinates', prefix='edge_geometry')

edge_graph(return_edge_map=False)

edge_index(edge)

edge_indices()

edge_iterator()

edge_open_binary(label, steps=1)

edge_propagate(label, value, steps=1)

edge_property(name, edge=None, as_array=True)

edge_property_map(name)

edge_radii(edge=None) → ndarray

Deprecated since version Use: edge_radii_voxels() or edge_radii_um() explicitly.

edge_radii_um(edge=None) → ndarray

Edge radii in physical units (µm).

Raises:

KeyError – If radius_units have not been propagated to edges yet.

edge_radii_voxels(edge=None) → ndarray

Edge radii in voxels (aggregated from vertex radii during reduce_graph).

Raises:

KeyError – If radii have not been propagated to edges yet.

edge_source_label(vertex_label, as_array=True)

edge_target_label(vertex_label, as_array=True)

edge_to_vertex_label(edge_label, method='max', as_array=True)

edge_to_vertex_label_or(edge_label)

expand_vertex_filter(vertex_filter, steps=1)

export_vertex_properties(output_path: str | Path, v_props: list[str] | None = None)

Export vertex properties as a pandas DataFrame. The export format will be determined by the file extension.

Parameters:

• v_props (list of str) – The vertex properties to export.

• output_path (str | Path) – The output file path.

first_edge()

first_vertex()

get_edges(eprops=[])

graph_property(name)

graph_property_map(name)

has_edge_geometry(name='coordinates')

has_edge_property(prop_name: str)

has_graph_property(prop_name: str)

has_vertex_property(prop_name: str)

info()

is_edge_geometry_consistent(verbose=False)

label_components(return_vertex_counts=False)

largest_component(view=False)

prune_edge_geometry()

Remove the unused edge geometries from the graph. This computes the new indices and remaps the edge geometry properties to the new indices.

remap_edge_geometry_properties(new_indices)

Remap all properties in self.edge_geometry_properties (edge_geometry_<>) to the new indices i.e.,

copy every edge-geometry_<> array so old ranges → new ranges

Parameters:

new_indices (np.ndarray) – The new indices to remap the edge geometry properties to.

remove_edge(edge)

remove_edge_geometry(name=None)

remove_edge_property(name)

remove_graph_property(name)

remove_isolated_edges()

remove_isolated_vertices()

remove_self_loops()

remove_vertex(vertex)

remove_vertex_property(name)

save(filename: str | Path)

set_edge_annotation(annotation, edge=None, dtype='int32')

set_edge_coordinates(coordinates, edge=None)

set_edge_geometry(name, values, indices=None, edge=None)

Set the given edge geometry property for the graph.

Warning

edge is not supported for 'graph' edge geometry type.

Parameters:

• name (str) – The name of the original vertex or edge property to set as edge geometry. As an edge geometry property, the name will be prefixed with 'edge_geometry_*' (e.g. 'edge_geometry_coordinates').

• values (list or np.ndarray) – The values to set as edge geometry.

• indices (np.ndarray or None) – How to slice the values to map to edges.

• edge (gt.Edge or int, optional) – The edge to set the geometry for. If None, the geometry is set for all edges. Not supported when edge_geometry_type is 'graph'.

set_edge_geometry_edge_properties(original_graph, edge_geometry_edge_properties, indices, edge_to_edge_map)

set_edge_geometry_type(edge_geometry_type)

set_edge_geometry_vertex_properties(original_graph, edge_geometry_vertex_properties, branch_indices, indices)

Set the edge geometry properties from the vertex properties of the original graph.

Note

The property is processed only if it exists in the original graph and is not already set as an edge geometry property in the current graph.

Parameters:

• original_graph

• edge_geometry_vertex_properties

• branch_indices

• indices

Returns

set_edge_property(name, source, edge=None)

set_edge_radii(radii, edge=None)

set_graph_property(name, source)

set_vertex_annotation(annotation, vertex=None, dtype='int32')

set_vertex_coordinates(coordinates, vertex=None, dtype=<class 'float'>)

set_vertex_property(name, source, vertex=None)

set_vertex_radii(radii, vertex=None)

set_vertex_radius(vertex, radius)

sub_graph(vertex_filter=None, edge_filter=None, view=False)

Construct a subgraph using graph-tool filtering, returning either a view or a pruned copy.

Parameters:

• vertex_filter (None or array-like or gt.PropertyMap) – Vertex selection mask or property map. Commonly a 1-D boolean numpy array of length n_vertices. True means the vertex is retained in the view.

• edge_filter (None or array-like or gt.PropertyMap) – Edge selection mask or property map. Commonly a 1-D boolean numpy array of length n_edges. True means the edge is retained in the view.

• view (bool) – If True, return a Graph wrapping a gt.GraphView (no pruning/copy). If False, materialise a pruned copy via gt.Graph(gv, prune=True).

Returns

Graph

A graph restricted by the provided filters.

Notes

Edge geometry handling:

• If the resulting graph has edges and the source graph has edge geometry, prune_edge_geometry() is called to compact edge-geometry arrays to the retained edge set.

• If the resulting graph has no edges, edge geometry is removed (remove_edge_geometry()).

sub_slice(slicing, view=False, coordinates=None, cut_edges='exclusive')

Slice the graph by an axis-aligned spatial selection, with optional boundary-edge policy.

The slice is defined by applying slicing to per-vertex coordinates (by default the 'coordinates' vertex property). This produces an initial vertex mask V0.

Two boundary policies are supported via cut_edges:

• 'exclusive' (default): return the induced subgraph on V0 (retain an edge only if both endpoints are in V0).

• 'inclusive': retain an edge if at least one endpoint is in V0, then expand the vertex set to include both endpoints of every retained edge.

Parameters:

• slicing (tuple of slice or int) – A slicing spec accepted by ClearMap.IO.IO.slc.unpack_slicing (slices/ints per axis).

• view (bool) – If True, return a lightweight gt.GraphView-backed wrapper. If False, return a pruned copy (see sub_graph()).

• coordinates (None or str or np.ndarray) –

  Coordinate source to slice against:

  • None: uses self.vertex_coordinates().

  • str: name of a vertex property to use.

  • np.ndarray: explicit (N, ndim) coordinates array.

• cut_edges (str) – Boundary edge policy: 'exclusive' or 'inclusive'.

Returns

Graph

The sliced graph (view or pruned copy). If edge geometry exists and edges are retained, geometry is compacted via prune_edge_geometry() in sub_graph().

sub_slice_edge_filter(slicing, coordinates=None)

sub_slice_vertex_filter(slicing, coordinates=None)

transform_properties(transformation, vertex_properties=None, edge_properties=None, edge_geometry_properties=None, verbose=False)

vertex(vertex)

vertex_annotation(vertex=None)

vertex_close_binary(label, steps=1)

vertex_coloring()

vertex_coordinates(vertex=None, axis=None)

vertex_degree(index)

vertex_degrees()

vertex_dilate_binary(label, steps=1)

vertex_edges(vertex)

vertex_edges_iterator(vertex)

vertex_erode_binary(label, steps=1)

vertex_in_degree(index)

vertex_in_degrees()

vertex_in_edges(vertex)

vertex_in_edges_iterator(vertex)

vertex_in_neighbours(index)

vertex_index(vertex)

vertex_indices()

vertex_iterator()

vertex_neighbours(index)

vertex_open_binary(label, steps=1)

vertex_out_degree(index)

vertex_out_degrees()

vertex_out_edges(vertex)

vertex_out_edges_iterator(vertex)

vertex_out_neighbours(index)

vertex_propagate(label, value, steps=1)

vertex_property(name, vertex=None, as_array=True)

Warning

This risks creating a copy of the vertex property map if as_array is True.

Parameters:

• name

• vertex

• as_array

Returns

vertex_property_map(name)

vertex_radii(vertex=None) → ndarray

Deprecated since version Use: vertex_radii_voxels() or vertex_radii_units() explicitly. This method returns voxel radii and will be removed in a future version.

vertex_radii_units(vertex=None) → ndarray

Vertex radii in physical units (µm).

Raises:

KeyError – If radius_units have not been measured yet. Call _measure_radii() with a valid spacing array first. For voxel units use vertex_radii_voxels().

vertex_radii_voxels(vertex=None) → ndarray

Vertex radii in voxels.

Raises:

KeyError – If radii have not been measured yet. Call _measure_radii() first. For physical units use vertex_radii_units().

vertex_to_edge_label(vertex_label, method=None)

view(vertex_filter=None, edge_filter=None)

DEFAULT_N_DIMS = 3

SCOPES = ('vertex', 'edge', 'graph')

property base

property directed

property edge_geometry_properties

property edge_geometry_property_names

property edge_geometry_type

Type for storing edge properties

Returns

type‘graph’ or ‘edge’

‘graph’Stores edge coordinates in a graph property array and

start end indices in edges.

‘edge’Stores the edge coordinates in variable length vectors in

each edge.

property edge_properties

property edges

property graph_properties

property has_edge_coordinates

property has_edge_radii

property has_edge_radii_um: bool

True if µm radii have been propagated to edges.

property has_vertex_coordinates

property has_vertex_radii

property is_view

property n_edges

Number of edges in the graph.

property n_vertices

Number of vertices in the graph.

property ndim

property shape

The shape of the space in which the graph is embedded.

Returns

shapetuple of int

The shape of the graph space.

property vertex_properties

property vertices

load(filename)

save(filename, graph)