Skip to content

Complete API Reference

This page contains the complete API reference for all ossify functions and classes in a single document. For a more organized view, see the individual module pages:

Complete Module Documentation

Modules:

  • algorithms –
  • base –
  • data_layers –
  • file_io –
  • graph_functions –
  • plot –
  • sync_classes –
  • translate –
  • utils –

Classes:

Functions:

  • import_legacy_meshwork –

    Import a legacy MeshWork file as a Cell object. Requires h5py, which can be installed with pip install ossify[legacy].

  • load_cell –

    Load a neuronal object from a file path or file object.

  • load_cell_from_client –

    Import an "L2" skeleton and spatial graph using the CAVE skeleton service.

  • save_cell –

    Save Cell to a file path or file object.

Cell(name=None, morphsync=None, meta=None, annotation_layers=None)

Methods:

  • add_graph –

    Add the core graph layer to a MeshWork object.

  • add_layer –

    Add a initialized layer to the MorphSync.

  • add_mesh –

    Add a mesh layer to the MorphSync.

  • add_point_annotations –

    Add point annotations to the MeshWork object. This is intended for annotations which are typically sparse and represent specific features, unlike general point clouds that represent the morphology of the cell.

  • add_point_layer –

    Add point layer to the MeshWork object. This is intended for general point clouds that represent the morphology of the cell, unlike annotations which are typically sparse and represent specific features.

  • add_skeleton –

    Add a skeleton layer to the MorphSync.

  • apply_mask –

    Create a new Cell with vertices masked out.

  • copy –

    Create a deep copy of the Cell.

  • describe –

    Generate a hierarchical summary description of the cell and its layers.

  • get_features –

    Map feature columns from various sources to a target layer.

  • mask_context –

    Create a masked version of the MeshWork object in a context state.

  • remove_annotation –

    Remove an annotation layer from the Cell.

  • remove_layer –

    Remove a morphological layer from the Cell.

  • transform –

    Apply a spatial transformation to all spatial layers in the Cell.

Attributes:

a property

Alias for annotations.

annotations property

Annotation Manager for the cell, holding all annotation layers.

features property

Return a DataFrame listing all feature columns across all layers. Each feature is a row, with the layer name and feature name as columns.

g property

Alias for graph.

graph property

Graph layer for the cell, if present. Otherwise, None.

l property

Alias for layers.

layers property

Get the non-annotation layers of the cell.

m property

Alias for mesh.

mesh property

Mesh layer for the cell, if present. Otherwise, None.

meta property

Get the metadata associated with the cell.

name property

Get the name of the cell (typically a segment id)

s property

Alias for skeleton.

skeleton property

Skeleton layer for the cell, if present. Otherwise, None.

add_graph(vertices, edges=None, features=None, *, vertex_index=None, spatial_columns=None, linkage=None)

Add the core graph layer to a MeshWork object. Additional graph layers can be used, but they must be added separately and with unique names.

Parameters:

Returns:

add_layer(layer)

Add a initialized layer to the MorphSync.

Parameters:

Raises:

  • ValueError –

    If the layer already exists or if the layer type is incorrect.

add_mesh(vertices, faces=None, features=None, *, vertex_index=None, linkage=None, spatial_columns=None)

Add a mesh layer to the MorphSync.

Parameters:

  • vertices (Union[ndarray, DataFrame, MeshLayer]) –

    The vertices of the mesh, or a MeshLayer object.

  • faces (Union[ndarray, DataFrame], default: None ) –

    The faces of the mesh. If faces are provided as a dataframe, faces should be in dataframe indices.

  • features (Optional[Union[dict, DataFrame]], default: None ) –

    Additional features for the mesh. If passed as dictionary, the key is the feature name and the values are an array of feature values.

  • vertex_index (Optional[Union[str, ndarray]], default: None ) –

    The column to use as a vertex index for the mesh, if vertices are a dataframe.

  • linkage (Optional[Link], default: None ) –

    The linkage information for the mesh.

  • spatial_columns (Optional[list], default: None ) –

    The spatial columns for the mesh, if vertices are a dataframe.

Returns:

add_point_annotations(name, vertices=None, spatial_columns=None, *, vertex_index=None, features=None, linkage=None, vertices_from_linkage=False)

Add point annotations to the MeshWork object. This is intended for annotations which are typically sparse and represent specific features, unlike general point clouds that represent the morphology of the cell.

Parameters:

  • name (str) –

    The name of the annotation layer.

  • vertices (Union[ndarray, DataFrame], default: None ) –

    The vertices of the annotation layer.

  • spatial_columns (Optional[list], default: None ) –

    The spatial columns for the annotation layer.

  • vertex_index (Optional[Union[str, ndarray]], default: None ) –

    The vertex index for the annotation layer.

  • features (Optional[Union[dict, DataFrame]], default: None ) –

    The features for the annotation layer.

  • linkage (Optional[Link], default: None ) –

    The linkage information for the annotation layer. Typically, you will define the target vertices for annotations.

  • vertices_from_linkage (bool, default: False ) –

    If True, the vertices will be inferred from the linkage mapping rather than the provided vertices. This is useful if you want to create an annotation layer that directly maps to another layer without providing separate vertex coordinates.

Returns:

add_point_layer(name, vertices, spatial_columns=None, *, vertex_index=None, features=None, linkage=None)

Add point layer to the MeshWork object. This is intended for general point clouds that represent the morphology of the cell, unlike annotations which are typically sparse and represent specific features.

Parameters:

  • name (str) –

    The name of the point layer.

  • vertices (Union[ndarray, DataFrame]) –

    The vertices of the point layer.

  • spatial_columns (Optional[list], default: None ) –

    The spatial columns for the point layer.

  • vertex_index (Optional[Union[str, ndarray]], default: None ) –

    The vertex index for the annotation layer.

  • features (Optional[Union[dict, DataFrame]], default: None ) –

    The features for the annotation layer.

  • linkage (Optional[Link], default: None ) –

    The linkage information for the annotation layer. Typically, you will define the target vertices for annotations.

Returns:

add_skeleton(vertices, edges=None, features=None, root=None, *, vertex_index=None, linkage=None, spatial_columns=None, inherited_properties=None)

Add a skeleton layer to the MorphSync.

Parameters:

  • vertices (Union[ndarray, DataFrame, SkeletonLayer]) –

    The vertices of the skeleton, or a SkeletonLayer object.

  • edges (Union[ndarray, DataFrame], default: None ) –

    The edges of the skeleton.

  • features (Optional[Union[dict, DataFrame]], default: None ) –

    The features for the skeleton.

  • root (Optional[int], default: None ) –

    The root vertex for the skeleton, required of the edges are not already consistent with a single root.

  • vertex_index (Optional[Union[str, ndarray]], default: None ) –

    The vertex index for the skeleton.

  • linkage (Optional[Link], default: None ) –

    The linkage information for the skeleton. Typically, you will define the source vertices for the skeleton if using a graph-to-skeleton mapping.

  • spatial_columns (Optional[list], default: None ) –

    The spatial columns for the skeleton, if vertices are a dataframe.

Returns:

apply_mask(layer, mask, as_positional=False)

Create a new Cell with vertices masked out.

Parameters:

  • layer (str) –

    The layer name that the mask is based on.

  • mask (ndarray) –

    The mask to apply. Values that are True are preserved, while values that are False are discarded. Can be a boolean array or an array of vertices.

  • as_positional (bool, default: False ) –

    If mask is an array of vertices, this sets whether indices are in dataframe indices or as_positional indices.

Returns:

copy()

Create a deep copy of the Cell.

describe(html=False)

Generate a hierarchical summary description of the cell and its layers.

Provides a tree-like overview including: - Cell name and basic info - Layers section with expandable details - Annotations section with expandable details

Parameters:

  • html (bool, default: False ) –

    If True, create expandable HTML widgets in Jupyter. If False, print formatted string (default).

Returns:

  • None –

    Always returns None (prints text or displays HTML widgets)

Examples:

>>> cell.describe()  # Prints formatted string
>>> cell.describe(html=True)  # Shows HTML widgets in Jupyter

get_features(features, target_layer, source_layers=None, agg='median')

Map feature columns from various sources to a target layer.

Parameters:

  • features (Union[str, list]) –

    The features to map from the source layer.

  • target_layer (str) –

    The target layer to map all features to.

  • source_layers (Optional[Union[str, list]], default: None ) –

    The source layers to map the features from. Unnecessary if features are unique.

  • agg (Union[str, dict], default: 'median' ) –

    The aggregation method to use when mapping the features. Anything pandas groupby.agg takes, as well as "majority" which will is a majority vote across the mapped indices via the stats.mode function.

Returns:

  • DataFrame –

    The mapped features for the target layer.

mask_context(layer, mask)

Create a masked version of the MeshWork object in a context state.

Parameters:

  • layer (str) –

    The name of the layer to which the mask applies.

  • mask (array or None) –

    A boolean array with the same number of elements as mesh vertices. True elements are kept, False are masked out.

Example

with mesh.mask_context("layer_name", mask) as masked_mesh: result = my_favorite_function(masked_mesh)

remove_annotation(name)

Remove an annotation layer from the Cell.

Parameters:

  • name (str) –

    The name of the annotation to remove

Returns:

  • Self –

    The Cell object for method chaining

Raises:

remove_layer(name)

Remove a morphological layer from the Cell.

Parameters:

  • name (str) –

    The name of the layer to remove

Returns:

  • Self –

    The Cell object for method chaining

Raises:

  • ValueError –

    If the layer does not exist or is a core layer that cannot be removed

transform(transform, inplace=False)

Apply a spatial transformation to all spatial layers in the Cell.

Parameters:

  • transform (Union[ndarray, callable]) –

    If an array, must be the same shape as the vertices of the layer(s). If a callable, must take in a (N, 3) array and return a (N, 3) array.

  • inplace (bool, default: False ) –

    If True, modify the current Cell. If False, return a new Cell.

Returns:

  • Self –

    The transformed Cell.

GraphLayer(name, vertices, edges, spatial_columns=None, *, vertex_index=None, features=None, morphsync=None, linkage=None, existing=False)

Bases: PointMixin, EdgeMixin

Methods:

  • __getitem__ –

    Passthrough to nodes dataframe

  • add_feature –

    Add a new vertex feature to the layer.

  • apply_mask –

    Apply a mask on the current layer. Returns a new object with the masked morphsync.

  • copy –

    Create a deep copy of the current object.

  • describe –

    Generate a compact description of the layer including vertices, features, and links.

  • distance_between –

    Get the distance between two sets of vertices in the skeleton.

  • drop_features –

    Drop features from the DataFrame.

  • get_feature –

    Get a feature array from the features DataFrame.

  • get_unmapped_vertices –

    Identify vertices in this layer that have no mapping to specified target layers.

  • iloc –

    Passthrough to layer.nodes.iloc

  • loc –

    Passthrough to layer.nodes.loc

  • map_annotations_to_feature –

    Aggregate a point annotation to a feature on the layer.

  • map_features_to_layer –

    Map features from one layer to another.

  • map_index_to_layer –

    Map each vertex index from the current layer to a single index in the specified layer.

  • map_index_to_layer_region –

    Map each vertex index from the current layer to a list of all appropriate vertices in the target layer.

  • map_mask_to_layer –

    Map a boolean mask from the current layer to the specified layer.

  • map_region_to_layer –

    Map each vertex index from the current layer to the specified layer.

  • mask_context –

    Context manager to temporarily apply a mask via the current layer.

  • mask_out_unmapped –

    Create a new object with unmapped vertices removed.

  • path_between –

    Get the shortest path between two vertices in the skeleton.

  • proximity_mapping –

    Get a DataFrame of all vertices within a certain distance of each other.

Attributes:

  • bbox (array) –

    Get the axis-aligned bounding box (min, max) of the data layer's vertices.

  • csgraph (csr_matrix) –

    Get the compressed sparse graph representation of the layer with Euclidean edge weights.

  • csgraph_binary (csr_matrix) –

    Get the unweighted compressed sparse graph representation of the layer.

  • csgraph_binary_undirected (csr_matrix) –

    Get the unweighted and undirected compressed sparse graph representation of the layer.

  • csgraph_undirected (csr_matrix) –

    Get the undirected compressed sparse graph representation of the layer with Euclidean edge weights.

  • edge_df (DataFrame) –

    Get the edges of the layer as a DataFrame.

  • edges (ndarray) –

    Get the edges of the layer in dataframe indices.

  • edges_positional (ndarray) –

    Get the edges of the layer in positional indices.

  • feature_names (list) –

    Get the list of column names associated with features (non-spatial columns).

  • features (DataFrame) –

    Get the features DataFrame.

  • half_edge_length (ndarray) –

    Get the sum length of half-edges from a vertices to all parents and children.

  • kdtree (KDTree) –

    Get the KDTree for the data layer's vertices for efficient spatial queries. See scipy.spatial.KDTree for documentation.

  • layer (Facet) –

    Get the morphsync layer associated with the data layer.

  • n_vertices (int) –

    Get the number of vertices in the data layer.

  • name (str) –

    Layer name.

  • nodes (DataFrame) –

    Get the complete DataFrame of vertices and all associated data, including both spatial columns and features.

  • spatial_columns (list) –

    Get the list of column names associated with the x, y, and z positions.

  • vertex_df (DataFrame) –

    Get the Nx3 vertex positions of the data layer as an indexed DataFrame.

  • vertex_index (ndarray) –

    Get vertex indices as a numpy array.

  • vertex_index_map (dict) –

    Get a dictionary mapping vertex indices to their positional indices.

  • vertices (ndarray) –

    Get the Nx3 vertex positions of the data layer.

bbox property

Get the axis-aligned bounding box (min, max) of the data layer's vertices.

csgraph property

Get the compressed sparse graph representation of the layer with Euclidean edge weights.

csgraph_binary property

Get the unweighted compressed sparse graph representation of the layer.

csgraph_binary_undirected property

Get the unweighted and undirected compressed sparse graph representation of the layer.

csgraph_undirected property

Get the undirected compressed sparse graph representation of the layer with Euclidean edge weights.

edge_df property

Get the edges of the layer as a DataFrame.

edges property

Get the edges of the layer in dataframe indices.

edges_positional property

Get the edges of the layer in positional indices.

feature_names property

Get the list of column names associated with features (non-spatial columns).

features property

Get the features DataFrame.

half_edge_length property

Get the sum length of half-edges from a vertices to all parents and children.

Returns:

  • ndarray –

    Array of half-edge lengths for each vertex.

kdtree property

Get the KDTree for the data layer's vertices for efficient spatial queries. See scipy.spatial.KDTree for documentation.

layer property

Get the morphsync layer associated with the data layer.

n_vertices property

Get the number of vertices in the data layer.

name property

Layer name.

nodes property

Get the complete DataFrame of vertices and all associated data, including both spatial columns and features.

spatial_columns property

Get the list of column names associated with the x, y, and z positions.

vertex_df property

Get the Nx3 vertex positions of the data layer as an indexed DataFrame.

vertex_index property

Get vertex indices as a numpy array.

vertex_index_map property

Get a dictionary mapping vertex indices to their positional indices.

vertices property

Get the Nx3 vertex positions of the data layer.

__getitem__(key)

Passthrough to nodes dataframe

add_feature(feature, name=None)

Add a new vertex feature to the layer.

Parameters:

  • feature (Union[list, ndarray, dict, DataFrame]) –

    The feature data to add. If an array or list, it should follow the vertex order.

  • name (Optional[str], default: None ) –

    The name of the feature column (required if feature is a list or np.ndarray).

Returns:

  • Self –

    The updated DataLayer instance.

apply_mask(mask, as_positional=False, self_only=False)

Apply a mask on the current layer. Returns a new object with the masked morphsync. If the object is associated with a CellSync, a new CellSync will be created, otherwise a new object of the same class will be returned.

Properties

mask: np.ndarray The mask to apply, either in boolean, vertex index, or positional index form. as_positional: bool If providing indices, specify if they are positional indices (True) or vertex indices (False). self_only: bool If True, only apply the mask to the current object and not to any associated CellSync.

Returns:

  • masked_object Union[Self, "CellSync"] –

    Either a new object of the same class or a new CellSync will be returned.

copy()

Create a deep copy of the current object.

Returns:

  • Union[Self, Cell] –

    A new object of the same class without the CellSync.

describe()

Generate a compact description of the layer including vertices, features, and links.

Provides information about: - Layer name and type - Vertex count (and edges/faces for applicable layer types) - feature names - Links to other layers

Returns:

  • None –

    Always returns None (prints formatted text)

distance_between(sources=None, targets=None, as_positional=False, limit=None)

Get the distance between two sets of vertices in the skeleton.

Parameters:

  • sources (Optional[ndarray], default: None ) –

    The source vertices. If None, all vertices are used.

  • targets (Optional[ndarray], default: None ) –

    The target vertices. If None, all vertices are used.

  • as_positional –

    Whether the input vertices are positional (i.e., masks or indices). Must be the same for sources and targets.

  • limit (Optional[float], default: None ) –

    The maximum distance to consider in the graph distance lookup. If None, no limit is applied. Distances above this will be set to infinity.

Returns:

  • ndarray –

    The distance between each source and target vertex, of dimensions len(sources) x len(targets).

drop_features(features)

Drop features from the DataFrame.

Parameters:

  • features (Union[str, list]) –

    The feature column name or list of names to drop.

Returns:

  • Self –

    The updated DataLayer instance.

get_feature(key)

Get a feature array from the features DataFrame.

Parameters:

  • key (str) –

    Column name of the feature to retrieve.

Returns:

  • ndarray –

    Array of feature values for all vertices.

get_unmapped_vertices(target_layers=None)

Identify vertices in this layer that have no mapping to specified target layers.

Parameters:

  • target_layers (Optional[Union[str, List[str]]], default: None ) –

    Target layer name(s) to check mappings against. If None, checks all other layers in the morphsync object except the current layer.

Returns:

  • ndarray –

    Vertices in this layer that have null mappings to any of the target layers.

iloc(key)

Passthrough to layer.nodes.iloc

loc(key)

Passthrough to layer.nodes.loc

map_annotations_to_feature(annotation, distance_threshold, agg='count', chunk_size=1000, validate=False)

Aggregate a point annotation to a feature on the layer.

Parameters:

  • annotation (str) –

    The name of the annotation layer to aggregate.

  • distance_threshold (float) –

    Maximum distance to consider for aggregation.

  • agg (Union[str, dict], default: 'count' ) –

    Aggregation method. Can be 'count' or dict of aggregation functions. Default 'count'.

  • chunk_size (int, default: 1000 ) –

    Size of processing chunks for memory efficiency. Default 1000.

  • validate (bool, default: False ) –

    Whether to validate mapping consistency. Default False.

  • agg_direction (str) –

    Direction along the skeleton to consider for aggregation. Options are 'undirected', 'upstream', 'downstream'. "undirected" considers all neighbors within the distance threshold. "upstream" considers only neighbors towards the root. "downstream" considers only neighbors away from the root. Default is 'undirected'.

Returns:

  • Union[Series, DataFrame] –

    Aggregated annotation values. Series for 'count', DataFrame for dict aggregations.

map_features_to_layer(features, layer, agg='mean')

Map features from one layer to another.

Parameters:

  • features (Union[str, list]) –

    The features to map from the source layer.

  • layer (str) –

    The target layer to map the features to.

  • agg (Union[str, dict], default: 'mean' ) –

    The aggregation method to use when mapping the features. This can take anything pandas groupby.agg takes, as well as "majority" which will is a majority vote across the mapped indices via the stats.mode function.

Returns:

  • DataFrame –

    The mapped features for the target layer. Vertices with no mapping will have NaN values.

map_index_to_layer(layer, source_index=None, as_positional=False, validate=False)

Map each vertex index from the current layer to a single index in the specified layer.

Parameters:

  • layer (str) –

    The target layer to map the index to.

  • source_index (Optional[ndarray], default: None ) –

    The source index to map from. If None, all vertices are used. Can also be a boolean array.

  • as_positional (bool, default: False ) –

    Whether to treat source_index and mapped index as positional (i_th element of the array) or as a dataframe index.

  • validate (bool, default: False ) –

    Whether to raise an error is the mapping is ambiguous, i.e. it is not clear which target index to use.

Returns:

  • ndarray –

    The mapped indices in the target layer. There will be exactly one target index for each source index, no matter how many viable target indices there are. If as_positional is True, the mapping is based on the position of the vertices not the dataframe index.

map_index_to_layer_region(layer, source_index=None, as_positional=False)

Map each vertex index from the current layer to a list of all appropriate vertices in the target layer.

Parameters:

  • layer (str) –

    The target layer to map the index to.

  • source_index (Optional[ndarray], default: None ) –

    The source indices to map from. If None, all vertices are used. Can also be a boolean array.

  • as_positional (bool, default: False ) –

    Whether to treat source_index and mapped index as positional (i_th element of the array) or as a dataframe index.

Returns:

  • dict –

    A dictionary mapping each source index to a list of all mapped target indices.

map_mask_to_layer(layer, mask=None)

Map a boolean mask from the current layer to the specified layer.

Parameters:

  • layer (str) –

    The target layer to map the index to.

  • mask (Optional[ndarray], default: None ) –

    The boolean mask to map from. If None, all vertices are used.

Returns:

  • ndarray –

    The mapped boolean mask in the target layer. There may be multiple target indices for each source index, depending on the region mapping. If as_positional is True, the mapping is based on the position of the vertices not the dataframe index.

map_region_to_layer(layer, source_index=None, as_positional=False)

Map each vertex index from the current layer to the specified layer.

Parameters:

  • layer (str) –

    The target layer to map the index to.

  • source_index (Optional[ndarray], default: None ) –

    The source indices to map from. If None, all vertices are used. Can also be a boolean array.

  • as_positional (bool, default: False ) –

    Whether to treat source_index and mapped index as positional (i_th element of the array) or as a dataframe index.

Returns:

  • ndarray –

    All mapped indices in the target layer. Not necessarily the same length as the source indices, because it maps a region to another region. If as_positional is True, the mapping is based on the position of the vertices not the dataframe index.

mask_context(mask)

Context manager to temporarily apply a mask via the current layer.

Parameters:

  • mask (ndarray) –

    The mask to apply, either in boolean, vertex index, or positional index form.

Yields:

  • Self –

    A new object of the same class with the mask applied.

Example

with cell.skeleton.mask_context(mask) as masked_cell: masked_path_length = masked_cell.mesh.surface_area()

mask_out_unmapped(target_layers=None, self_only=False)

Create a new object with unmapped vertices removed.

This function identifies vertices that have null mappings to specified target layers and creates a masked version of the object with those vertices removed.

Parameters:

  • target_layers (Optional[Union[str, List[str]]], default: None ) –

    Target layer name(s) to check mappings against. If None, checks all other layers in the morphsync object except the current layer.

  • self_only (bool, default: False ) –

    If True, only apply mask to current layer. If False, apply to entire Cell. Default False.

Returns:

  • Union[Self, Cell] –

    New object with unmapped vertices removed.

Examples:

>>> # Remove skeleton vertices that don't map to mesh
>>> clean_skeleton = skeleton.mask_out_unmapped("mesh")

>>> # Remove vertices that don't map to multiple layers
>>> clean_skeleton = skeleton.mask_out_unmapped(["mesh", "annotations"])

>>> # Clean up only the current layer, not the whole cell
>>> clean_skeleton = skeleton.mask_out_unmapped("mesh", self_only=True)

>>> # Remove vertices that don't map to ANY other layer
>>> clean_skeleton = skeleton.mask_out_unmapped()

path_between(source, target, as_positional=False, as_vertices=False)

Get the shortest path between two vertices in the skeleton.

Parameters:

  • source (int) –

    The source vertex.

  • target (int) –

    The target vertex.

  • as_positional –

    Whether the input vertices are positional (i.e., masks or indices). Must be the same for sources and targets.

  • as_vertices –

    Whether to return the path as vertex IDs or 3d positions.

Returns:

  • ndarray –

    The shortest path between each source and target vertex, indices if as_positional is False, or nx3 array if as_vertices is True.

proximity_mapping(distance_threshold, chunk_size=1000, agg_direction='undirected')

Get a DataFrame of all vertices within a certain distance of each other.

Parameters:

  • distance_threshold (float) –

    Maximum distance to consider for proximity.

  • chunk_size (int, default: 1000 ) –

    Size of processing chunks for memory efficiency. Default 1000.

  • agg_direction (Literal['undirected', 'upstream', 'downstream'], default: 'undirected' ) –

    Direction along the skeleton to consider for proximity. Options are 'undirected', 'upstream', 'downstream'. "undirected" considers all neighbors within the distance threshold. "upstream" considers only neighbors towards the root. "downstream" considers only neighbors away from the root. Default is 'undirected'.

Returns:

  • DataFrame –

    DataFrame with columns 'idx' and 'prox_idx' indicating pairs of proximal vertices.

LayerManager(managed_layers=None, validation='any', context='layer', initial_layers=None)

Unified manager for both morphological layers and annotations with flexible validation.

Initialize the unified layer manager.

Parameters:

  • managed_layers (dict, default: None ) –

    Dictionary to store layers in. If None, creates new dict.

  • validation (str or callable, default: 'any' ) –

    Type validation mode: - 'any': Accept any layer type - 'point_cloud_only': Only accept PointCloudLayer - callable: Custom validation function

  • context (str, default: 'layer' ) –

    Context name for error messages ('layer', 'annotation', etc.)

  • initial_layers (list, default: None ) –

    Initial layers to add (with validation)

Methods:

  • __contains__ –

    Check if a layer exists by name.

  • __iter__ –

    Iterate over managed layers in order.

  • describe –

    Generate a detailed description of all managed layers.

  • get –

    Get a layer by name with optional default.

Attributes:

  • names (list) –

    Return a list of managed layer names.

names property

Return a list of managed layer names.

__contains__(name)

Check if a layer exists by name.

__iter__()

Iterate over managed layers in order.

describe()

Generate a detailed description of all managed layers.

Shows each layer with its metrics, features, and links - same level of detail as individual layer describe() methods.

Returns:

  • None –

    Always returns None (prints formatted text)

get(name, default=None)

Get a layer by name with optional default.

Represents the linkage mapping information.

Parameters:

  • mapping (Union[list[int], str]) –

    The mapping information between the source and target layers. The mapping will have the same length as the source vertices and the values will be the corresponding target vertex indices. If map_value_is_index is True, the mapping values should the dataframe index for target vertices (i.e. df.index), if False they are the positional indices (0-N). If a string, the mapping is the column name in the target's vertex dataframe.

  • source (Optional[str], default: None ) –

    The name of the source layer, typically the one with more vertices than the target. E.g. a graph or mesh to a skeleton, or a graph or skeleton to point annotations. If not provided, will be set to the layer name of the object this is being added to. Either source or target can be undefined, but not both.

  • target (Optional[str], default: None ) –

    The name of the target layer, typically the one with fewer vertices. E.g. a skeleton from a graph or mesh, or point annotations from a skeleton. If not provided, will be set to the layer name of the object this is being added to. Either source or target can be undefined, but not both.

  • map_value_is_index (bool, default: True ) –

    If True, assumes the values in the list or the mapping are a non-positional dataframe index.

Methods:

mapping_to_index(vertex_data)

Map positional values to index values

MeshLayer(name, vertices, faces, spatial_columns=None, *, vertex_index=None, features=None, morphsync=None, linkage=None, existing=False)

Bases: FaceMixin, PointMixin

Methods:

  • __getitem__ –

    Passthrough to nodes dataframe

  • add_feature –

    Add a new vertex feature to the layer.

  • apply_mask –

    Apply a mask on the current layer. Returns a new object with the masked morphsync.

  • copy –

    Create a deep copy of the current object.

  • describe –

    Generate a compact description of the layer including vertices, features, and links.

  • drop_features –

    Drop features from the DataFrame.

  • get_feature –

    Get a feature array from the features DataFrame.

  • get_unmapped_vertices –

    Identify vertices in this layer that have no mapping to specified target layers.

  • iloc –

    Passthrough to layer.nodes.iloc

  • loc –

    Passthrough to layer.nodes.loc

  • map_features_to_layer –

    Map features from one layer to another.

  • map_index_to_layer –

    Map each vertex index from the current layer to a single index in the specified layer.

  • map_index_to_layer_region –

    Map each vertex index from the current layer to a list of all appropriate vertices in the target layer.

  • map_mask_to_layer –

    Map a boolean mask from the current layer to the specified layer.

  • map_region_to_layer –

    Map each vertex index from the current layer to the specified layer.

  • mask_context –

    Context manager to temporarily apply a mask via the current layer.

  • mask_out_unmapped –

    Create a new object with unmapped vertices removed.

  • surface_area –

    Calculate the surface area of the mesh, or a subset of vertices.

Attributes:

  • as_trimesh (Trimesh) –

    Return the mesh as a trimesh.Trimesh object. Note that Trimesh works entirely in positional vertices.

  • as_tuple (Tuple[ndarray, ndarray]) –

    Tuple of (vertices, faces_positional) expected by many mesh-processing algorithms.

  • bbox (array) –

    Get the axis-aligned bounding box (min, max) of the data layer's vertices.

  • csgraph (csr_matrix) –

    Generate a compressed sparse graph representation of the mesh as a network.

  • edges (ndarray) –

    Return the edge indices of the mesh in raw indices. Note that for each connected vertex pair u,v, there are both edges (u,v) and (v,u).

  • edges_positional (ndarray) –

    Return the edge indices of the mesh in positional indices. Note that for each connected vertex pair u,v, there are both edges (u,v) and (v,u).

  • faces (ndarray) –

    Return the triangle face indices of the mesh in raw indices.

  • faces_positional (ndarray) –

    Return the triangle face indices of the mesh in positional indices.

  • feature_names (list) –

    Get the list of column names associated with features (non-spatial columns).

  • features (DataFrame) –

    Get the features DataFrame.

  • kdtree (KDTree) –

    Get the KDTree for the data layer's vertices for efficient spatial queries. See scipy.spatial.KDTree for documentation.

  • layer (Facet) –

    Get the morphsync layer associated with the data layer.

  • n_vertices (int) –

    Get the number of vertices in the data layer.

  • name (str) –

    Layer name.

  • nodes (DataFrame) –

    Get the complete DataFrame of vertices and all associated data, including both spatial columns and features.

  • spatial_columns (list) –

    Get the list of column names associated with the x, y, and z positions.

  • vertex_df (DataFrame) –

    Get the Nx3 vertex positions of the data layer as an indexed DataFrame.

  • vertex_index (ndarray) –

    Get vertex indices as a numpy array.

  • vertex_index_map (dict) –

    Get a dictionary mapping vertex indices to their positional indices.

  • vertices (ndarray) –

    Get the Nx3 vertex positions of the data layer.

as_trimesh property

Return the mesh as a trimesh.Trimesh object. Note that Trimesh works entirely in positional vertices.

as_tuple property

Tuple of (vertices, faces_positional) expected by many mesh-processing algorithms.

bbox property

Get the axis-aligned bounding box (min, max) of the data layer's vertices.

csgraph property

Generate a compressed sparse graph representation of the mesh as a network.

edges property

Return the edge indices of the mesh in raw indices. Note that for each connected vertex pair u,v, there are both edges (u,v) and (v,u).

edges_positional property

Return the edge indices of the mesh in positional indices. Note that for each connected vertex pair u,v, there are both edges (u,v) and (v,u).

faces property

Return the triangle face indices of the mesh in raw indices.

faces_positional property

Return the triangle face indices of the mesh in positional indices.

feature_names property

Get the list of column names associated with features (non-spatial columns).

features property

Get the features DataFrame.

kdtree property

Get the KDTree for the data layer's vertices for efficient spatial queries. See scipy.spatial.KDTree for documentation.

layer property

Get the morphsync layer associated with the data layer.

n_vertices property

Get the number of vertices in the data layer.

name property

Layer name.

nodes property

Get the complete DataFrame of vertices and all associated data, including both spatial columns and features.

spatial_columns property

Get the list of column names associated with the x, y, and z positions.

vertex_df property

Get the Nx3 vertex positions of the data layer as an indexed DataFrame.

vertex_index property

Get vertex indices as a numpy array.

vertex_index_map property

Get a dictionary mapping vertex indices to their positional indices.

vertices property

Get the Nx3 vertex positions of the data layer.

__getitem__(key)

Passthrough to nodes dataframe

add_feature(feature, name=None)

Add a new vertex feature to the layer.

Parameters:

  • feature (Union[list, ndarray, dict, DataFrame]) –

    The feature data to add. If an array or list, it should follow the vertex order.

  • name (Optional[str], default: None ) –

    The name of the feature column (required if feature is a list or np.ndarray).

Returns:

  • Self –

    The updated DataLayer instance.

apply_mask(mask, as_positional=False, self_only=False)

Apply a mask on the current layer. Returns a new object with the masked morphsync. If the object is associated with a CellSync, a new CellSync will be created, otherwise a new object of the same class will be returned.

Properties

mask: np.ndarray The mask to apply, either in boolean, vertex index, or positional index form. as_positional: bool If providing indices, specify if they are positional indices (True) or vertex indices (False). self_only: bool If True, only apply the mask to the current object and not to any associated CellSync.

Returns:

  • masked_object Union[Self, "CellSync"] –

    Either a new object of the same class or a new CellSync will be returned.

copy()

Create a deep copy of the current object.

Returns:

  • Union[Self, Cell] –

    A new object of the same class without the CellSync.

describe()

Generate a compact description of the layer including vertices, features, and links.

Provides information about: - Layer name and type - Vertex count (and edges/faces for applicable layer types) - feature names - Links to other layers

Returns:

  • None –

    Always returns None (prints formatted text)

drop_features(features)

Drop features from the DataFrame.

Parameters:

  • features (Union[str, list]) –

    The feature column name or list of names to drop.

Returns:

  • Self –

    The updated DataLayer instance.

get_feature(key)

Get a feature array from the features DataFrame.

Parameters:

  • key (str) –

    Column name of the feature to retrieve.

Returns:

  • ndarray –

    Array of feature values for all vertices.

get_unmapped_vertices(target_layers=None)

Identify vertices in this layer that have no mapping to specified target layers.

Parameters:

  • target_layers (Optional[Union[str, List[str]]], default: None ) –

    Target layer name(s) to check mappings against. If None, checks all other layers in the morphsync object except the current layer.

Returns:

  • ndarray –

    Vertices in this layer that have null mappings to any of the target layers.

iloc(key)

Passthrough to layer.nodes.iloc

loc(key)

Passthrough to layer.nodes.loc

map_features_to_layer(features, layer, agg='mean')

Map features from one layer to another.

Parameters:

  • features (Union[str, list]) –

    The features to map from the source layer.

  • layer (str) –

    The target layer to map the features to.

  • agg (Union[str, dict], default: 'mean' ) –

    The aggregation method to use when mapping the features. This can take anything pandas groupby.agg takes, as well as "majority" which will is a majority vote across the mapped indices via the stats.mode function.

Returns:

  • DataFrame –

    The mapped features for the target layer. Vertices with no mapping will have NaN values.

map_index_to_layer(layer, source_index=None, as_positional=False, validate=False)

Map each vertex index from the current layer to a single index in the specified layer.

Parameters:

  • layer (str) –

    The target layer to map the index to.

  • source_index (Optional[ndarray], default: None ) –

    The source index to map from. If None, all vertices are used. Can also be a boolean array.

  • as_positional (bool, default: False ) –

    Whether to treat source_index and mapped index as positional (i_th element of the array) or as a dataframe index.

  • validate (bool, default: False ) –

    Whether to raise an error is the mapping is ambiguous, i.e. it is not clear which target index to use.

Returns:

  • ndarray –

    The mapped indices in the target layer. There will be exactly one target index for each source index, no matter how many viable target indices there are. If as_positional is True, the mapping is based on the position of the vertices not the dataframe index.

map_index_to_layer_region(layer, source_index=None, as_positional=False)

Map each vertex index from the current layer to a list of all appropriate vertices in the target layer.

Parameters:

  • layer (str) –

    The target layer to map the index to.

  • source_index (Optional[ndarray], default: None ) –

    The source indices to map from. If None, all vertices are used. Can also be a boolean array.

  • as_positional (bool, default: False ) –

    Whether to treat source_index and mapped index as positional (i_th element of the array) or as a dataframe index.

Returns:

  • dict –

    A dictionary mapping each source index to a list of all mapped target indices.

map_mask_to_layer(layer, mask=None)

Map a boolean mask from the current layer to the specified layer.

Parameters:

  • layer (str) –

    The target layer to map the index to.

  • mask (Optional[ndarray], default: None ) –

    The boolean mask to map from. If None, all vertices are used.

Returns:

  • ndarray –

    The mapped boolean mask in the target layer. There may be multiple target indices for each source index, depending on the region mapping. If as_positional is True, the mapping is based on the position of the vertices not the dataframe index.

map_region_to_layer(layer, source_index=None, as_positional=False)

Map each vertex index from the current layer to the specified layer.

Parameters:

  • layer (str) –

    The target layer to map the index to.

  • source_index (Optional[ndarray], default: None ) –

    The source indices to map from. If None, all vertices are used. Can also be a boolean array.

  • as_positional (bool, default: False ) –

    Whether to treat source_index and mapped index as positional (i_th element of the array) or as a dataframe index.

Returns:

  • ndarray –

    All mapped indices in the target layer. Not necessarily the same length as the source indices, because it maps a region to another region. If as_positional is True, the mapping is based on the position of the vertices not the dataframe index.

mask_context(mask)

Context manager to temporarily apply a mask via the current layer.

Parameters:

  • mask (ndarray) –

    The mask to apply, either in boolean, vertex index, or positional index form.

Yields:

  • Self –

    A new object of the same class with the mask applied.

Example

with cell.skeleton.mask_context(mask) as masked_cell: masked_path_length = masked_cell.mesh.surface_area()

mask_out_unmapped(target_layers=None, self_only=False)

Create a new object with unmapped vertices removed.

This function identifies vertices that have null mappings to specified target layers and creates a masked version of the object with those vertices removed.

Parameters:

  • target_layers (Optional[Union[str, List[str]]], default: None ) –

    Target layer name(s) to check mappings against. If None, checks all other layers in the morphsync object except the current layer.

  • self_only (bool, default: False ) –

    If True, only apply mask to current layer. If False, apply to entire Cell. Default False.

Returns:

  • Union[Self, Cell] –

    New object with unmapped vertices removed.

Examples:

>>> # Remove skeleton vertices that don't map to mesh
>>> clean_skeleton = skeleton.mask_out_unmapped("mesh")

>>> # Remove vertices that don't map to multiple layers
>>> clean_skeleton = skeleton.mask_out_unmapped(["mesh", "annotations"])

>>> # Clean up only the current layer, not the whole cell
>>> clean_skeleton = skeleton.mask_out_unmapped("mesh", self_only=True)

>>> # Remove vertices that don't map to ANY other layer
>>> clean_skeleton = skeleton.mask_out_unmapped()

surface_area(vertices=None, as_positional=True, inclusive=False)

Calculate the surface area of the mesh, or a subset of vertices.

Parameters:

  • vertices (Optional[ndarray], default: None ) –

    Vertex indices to calculate surface area for. If None, uses entire mesh.

  • as_positional (bool, default: True ) –

    Whether the input vertices are positional indices or vertex indices. Default True.

  • inclusive (bool, default: False ) –

    Whether to include faces that are covered by any vertex (True) or only those fully covered (False). Default False.

Returns:

  • float –

    The surface area of the mesh or the subset of vertices.

PointCloudLayer(name, vertices, spatial_columns=None, *, vertex_index=None, features=None, morphsync=None, linkage=None, existing=False)

Bases: PointMixin

Methods:

  • __getitem__ –

    Passthrough to nodes dataframe

  • add_feature –

    Add a new vertex feature to the layer.

  • apply_mask –

    Apply a mask on the current layer. Returns a new object with the masked morphsync.

  • copy –

    Create a deep copy of the current object.

  • describe –

    Generate a compact description of the layer including vertices, features, and links.

  • distance_between –

    Get the distance between each pair of vertices in the point cloud along the skeleton.

  • distance_to_root –

    Get the distance to the root for each vertex in the point cloud along the skeleton, or for a subset of vertices.

  • drop_features –

    Drop features from the DataFrame.

  • filter –

    Filter point cloud by a mask on a specific layer.

  • get_feature –

    Get a feature array from the features DataFrame.

  • get_unmapped_vertices –

    Identify vertices in this layer that have no mapping to specified target layers.

  • iloc –

    Passthrough to layer.nodes.iloc

  • loc –

    Passthrough to layer.nodes.loc

  • map_features_to_layer –

    Map features from one layer to another.

  • map_index_to_layer –

    Map each vertex index from the current layer to a single index in the specified layer.

  • map_index_to_layer_region –

    Map each vertex index from the current layer to a list of all appropriate vertices in the target layer.

  • map_mask_to_layer –

    Map a boolean mask from the current layer to the specified layer.

  • map_region_to_layer –

    Map each vertex index from the current layer to the specified layer.

  • mask_context –

    Context manager to temporarily apply a mask via the current layer.

  • mask_out_unmapped –

    Create a new object with unmapped vertices removed.

Attributes:

  • bbox (array) –

    Get the axis-aligned bounding box (min, max) of the data layer's vertices.

  • feature_names (list) –

    Get the list of column names associated with features (non-spatial columns).

  • features (DataFrame) –

    Get the features DataFrame.

  • kdtree (KDTree) –

    Get the KDTree for the data layer's vertices for efficient spatial queries. See scipy.spatial.KDTree for documentation.

  • layer (Facet) –

    Get the morphsync layer associated with the data layer.

  • layer_name (str) –

    Get the name of the layer.

  • n_vertices (int) –

    Get the number of vertices in the data layer.

  • name (str) –

    Layer name.

  • nodes (DataFrame) –

    Get the complete DataFrame of vertices and all associated data, including both spatial columns and features.

  • spatial_columns (list) –

    Get the list of column names associated with the x, y, and z positions.

  • vertex_df (DataFrame) –

    Get the Nx3 vertex positions of the data layer as an indexed DataFrame.

  • vertex_index (ndarray) –

    Get vertex indices as a numpy array.

  • vertex_index_map (dict) –

    Get a dictionary mapping vertex indices to their positional indices.

  • vertices (ndarray) –

    Get the Nx3 vertex positions of the data layer.

bbox property

Get the axis-aligned bounding box (min, max) of the data layer's vertices.

feature_names property

Get the list of column names associated with features (non-spatial columns).

features property

Get the features DataFrame.

kdtree property

Get the KDTree for the data layer's vertices for efficient spatial queries. See scipy.spatial.KDTree for documentation.

layer property

Get the morphsync layer associated with the data layer.

layer_name property

Get the name of the layer.

n_vertices property

Get the number of vertices in the data layer.

name property

Layer name.

nodes property

Get the complete DataFrame of vertices and all associated data, including both spatial columns and features.

spatial_columns property

Get the list of column names associated with the x, y, and z positions.

vertex_df property

Get the Nx3 vertex positions of the data layer as an indexed DataFrame.

vertex_index property

Get vertex indices as a numpy array.

vertex_index_map property

Get a dictionary mapping vertex indices to their positional indices.

vertices property

Get the Nx3 vertex positions of the data layer.

__getitem__(key)

Passthrough to nodes dataframe

add_feature(feature, name=None)

Add a new vertex feature to the layer.

Parameters:

  • feature (Union[list, ndarray, dict, DataFrame]) –

    The feature data to add. If an array or list, it should follow the vertex order.

  • name (Optional[str], default: None ) –

    The name of the feature column (required if feature is a list or np.ndarray).

Returns:

  • Self –

    The updated DataLayer instance.

apply_mask(mask, as_positional=False, self_only=False)

Apply a mask on the current layer. Returns a new object with the masked morphsync. If the object is associated with a CellSync, a new CellSync will be created, otherwise a new object of the same class will be returned.

Properties

mask: np.ndarray The mask to apply, either in boolean, vertex index, or positional index form. as_positional: bool If providing indices, specify if they are positional indices (True) or vertex indices (False). self_only: bool If True, only apply the mask to the current object and not to any associated CellSync.

Returns:

  • masked_object Union[Self, "CellSync"] –

    Either a new object of the same class or a new CellSync will be returned.

copy()

Create a deep copy of the current object.

Returns:

  • Union[Self, Cell] –

    A new object of the same class without the CellSync.

describe()

Generate a compact description of the layer including vertices, features, and links.

Provides information about: - Layer name and type - Vertex count (and edges/faces for applicable layer types) - feature names - Links to other layers

Returns:

  • None –

    Always returns None (prints formatted text)

distance_between(vertices=None, as_positional=False, via='skeleton', limit=None)

Get the distance between each pair of vertices in the point cloud along the skeleton.

Parameters:

  • vertices (Optional[ndarray], default: None ) –

    The vertices to get the distance between. If None, all vertices are used.

  • as_positional (bool, default: False ) –

    If True, the vertices are treated as positional indices. If False, they are treated as vertex features. By default False.

  • via (Literal['skeleton', 'graph', 'mesh'], default: 'skeleton' ) –

    The method to use for calculating distances. Can be "skeleton", "graph", or "mesh". Default is "skeleton".

  • limit (Optional[float], default: None ) –

    The maximum distance to consider when calculating distances. If None, no limit is applied.

Returns:

  • ndarray –

    The distance between each pair of vertices.

distance_to_root(vertices=None, as_positional=False)

Get the distance to the root for each vertex in the point cloud along the skeleton, or for a subset of vertices.

Parameters:

  • vertices (Optional[ndarray], default: None ) –

    The vertices to get the distance to the root for. If None, all vertices are used.

  • as_positional (bool, default: False ) –

    If True, the vertices are treated as positional indices. If False, they are treated as vertex features. By default False.

Returns:

  • ndarray –

    The distance to the root for each vertex.

drop_features(features)

Drop features from the DataFrame.

Parameters:

  • features (Union[str, list]) –

    The feature column name or list of names to drop.

Returns:

  • Self –

    The updated DataLayer instance.

filter(mask, layer)

Filter point cloud by a mask on a specific layer.

Parameters:

  • mask (ndarray) –

    The mask to filter by. Either an explicit mask array or a boolean mask.

  • layer (str) –

    The layer that the mask is associated with.

Returns:

  • DataFrame –

    The dataframe filtered by the mask.

get_feature(key)

Get a feature array from the features DataFrame.

Parameters:

  • key (str) –

    Column name of the feature to retrieve.

Returns:

  • ndarray –

    Array of feature values for all vertices.

get_unmapped_vertices(target_layers=None)

Identify vertices in this layer that have no mapping to specified target layers.

Parameters:

  • target_layers (Optional[Union[str, List[str]]], default: None ) –

    Target layer name(s) to check mappings against. If None, checks all other layers in the morphsync object except the current layer.

Returns:

  • ndarray –

    Vertices in this layer that have null mappings to any of the target layers.

iloc(key)

Passthrough to layer.nodes.iloc

loc(key)

Passthrough to layer.nodes.loc

map_features_to_layer(features, layer, agg='mean')

Map features from one layer to another.

Parameters:

  • features (Union[str, list]) –

    The features to map from the source layer.

  • layer (str) –

    The target layer to map the features to.

  • agg (Union[str, dict], default: 'mean' ) –

    The aggregation method to use when mapping the features. This can take anything pandas groupby.agg takes, as well as "majority" which will is a majority vote across the mapped indices via the stats.mode function.

Returns:

  • DataFrame –

    The mapped features for the target layer. Vertices with no mapping will have NaN values.

map_index_to_layer(layer, source_index=None, as_positional=False, validate=False)

Map each vertex index from the current layer to a single index in the specified layer.

Parameters:

  • layer (str) –

    The target layer to map the index to.

  • source_index (Optional[ndarray], default: None ) –

    The source index to map from. If None, all vertices are used. Can also be a boolean array.

  • as_positional (bool, default: False ) –

    Whether to treat source_index and mapped index as positional (i_th element of the array) or as a dataframe index.

  • validate (bool, default: False ) –

    Whether to raise an error is the mapping is ambiguous, i.e. it is not clear which target index to use.

Returns:

  • ndarray –

    The mapped indices in the target layer. There will be exactly one target index for each source index, no matter how many viable target indices there are. If as_positional is True, the mapping is based on the position of the vertices not the dataframe index.

map_index_to_layer_region(layer, source_index=None, as_positional=False)

Map each vertex index from the current layer to a list of all appropriate vertices in the target layer.

Parameters:

  • layer (str) –

    The target layer to map the index to.

  • source_index (Optional[ndarray], default: None ) –

    The source indices to map from. If None, all vertices are used. Can also be a boolean array.

  • as_positional (bool, default: False ) –

    Whether to treat source_index and mapped index as positional (i_th element of the array) or as a dataframe index.

Returns:

  • dict –

    A dictionary mapping each source index to a list of all mapped target indices.

map_mask_to_layer(layer, mask=None)

Map a boolean mask from the current layer to the specified layer.

Parameters:

  • layer (str) –

    The target layer to map the index to.

  • mask (Optional[ndarray], default: None ) –

    The boolean mask to map from. If None, all vertices are used.

Returns:

  • ndarray –

    The mapped boolean mask in the target layer. There may be multiple target indices for each source index, depending on the region mapping. If as_positional is True, the mapping is based on the position of the vertices not the dataframe index.

map_region_to_layer(layer, source_index=None, as_positional=False)

Map each vertex index from the current layer to the specified layer.

Parameters:

  • layer (str) –

    The target layer to map the index to.

  • source_index (Optional[ndarray], default: None ) –

    The source indices to map from. If None, all vertices are used. Can also be a boolean array.

  • as_positional (bool, default: False ) –

    Whether to treat source_index and mapped index as positional (i_th element of the array) or as a dataframe index.

Returns:

  • ndarray –

    All mapped indices in the target layer. Not necessarily the same length as the source indices, because it maps a region to another region. If as_positional is True, the mapping is based on the position of the vertices not the dataframe index.

mask_context(mask)

Context manager to temporarily apply a mask via the current layer.

Parameters:

  • mask (ndarray) –

    The mask to apply, either in boolean, vertex index, or positional index form.

Yields:

  • Self –

    A new object of the same class with the mask applied.

Example

with cell.skeleton.mask_context(mask) as masked_cell: masked_path_length = masked_cell.mesh.surface_area()

mask_out_unmapped(target_layers=None, self_only=False)

Create a new object with unmapped vertices removed.

This function identifies vertices that have null mappings to specified target layers and creates a masked version of the object with those vertices removed.

Parameters:

  • target_layers (Optional[Union[str, List[str]]], default: None ) –

    Target layer name(s) to check mappings against. If None, checks all other layers in the morphsync object except the current layer.

  • self_only (bool, default: False ) –

    If True, only apply mask to current layer. If False, apply to entire Cell. Default False.

Returns:

  • Union[Self, Cell] –

    New object with unmapped vertices removed.

Examples:

>>> # Remove skeleton vertices that don't map to mesh
>>> clean_skeleton = skeleton.mask_out_unmapped("mesh")

>>> # Remove vertices that don't map to multiple layers
>>> clean_skeleton = skeleton.mask_out_unmapped(["mesh", "annotations"])

>>> # Clean up only the current layer, not the whole cell
>>> clean_skeleton = skeleton.mask_out_unmapped("mesh", self_only=True)

>>> # Remove vertices that don't map to ANY other layer
>>> clean_skeleton = skeleton.mask_out_unmapped()

SkeletonLayer(name, vertices, edges, spatial_columns=None, root=None, *, vertex_index=None, features=None, morphsync=None, linkage=None, inherited_properties=None)

Bases: GraphLayer

Methods:

  • __getitem__ –

    Passthrough to nodes dataframe

  • add_feature –

    Add a new vertex feature to the layer.

  • apply_mask –

    Apply a mask on the current layer. Returns a new object with the masked morphsync.

  • cable_length –

    The net cable length of the subgraph formed by given vertices. If no vertices are provided, the entire graph is used.

  • child_vertices –

    Get mapping from vertices to their child nodes.

  • copy –

    Create a deep copy of the current object.

  • cover_paths_specific –

    Get cover paths starting from specific source vertices.

  • describe –

    Generate a compact description of the layer including vertices, features, and links.

  • distance_between –

    Get the distance between two sets of vertices in the skeleton.

  • distance_to_root –

    Get the distance to the root for each vertex in the skeleton, or for a subset of vertices.

  • downstream_vertices –

    Get all vertices downstream of a specified vertex

  • drop_features –

    Drop features from the DataFrame.

  • expand_to_segment –

    For each vertex in vertices, get the corresponding segment.

  • get_feature –

    Get a feature array from the features DataFrame.

  • get_unmapped_vertices –

    Identify vertices in this layer that have no mapping to specified target layers.

  • hops_to_root –

    Distance to root in number of hops between vertices. Always works on the base graph, whether the root is masked out or not.

  • iloc –

    Passthrough to layer.nodes.iloc

  • loc –

    Passthrough to layer.nodes.loc

  • lowest_common_ancestor –

    Get the lowest common ancestor of two vertices in the skeleton.

  • map_annotations_to_feature –

    Aggregates a point annotation to a feature on the layer based on a maximum proximity.

  • map_features_to_layer –

    Map features from one layer to another.

  • map_index_to_layer –

    Map each vertex index from the current layer to a single index in the specified layer.

  • map_index_to_layer_region –

    Map each vertex index from the current layer to a list of all appropriate vertices in the target layer.

  • map_mask_to_layer –

    Map a boolean mask from the current layer to the specified layer.

  • map_region_to_layer –

    Map each vertex index from the current layer to the specified layer.

  • mask_context –

    Context manager to temporarily apply a mask via the current layer.

  • mask_out_unmapped –

    Create a new object with unmapped vertices removed.

  • path_between –

    Get the shortest path between two vertices in the skeleton.

  • proximity_mapping –

    Get a DataFrame of all vertices within a certain distance of each other.

  • reroot –

    Reroot to a new index. Important: that this will reset any inherited properties from an unmasked skeleton!

  • segments_capped –

    Get segments that are capped at a maximum length.

Attributes:

as_tuple property

Get the vertices and (positional) edges of the graph as a tuple, which is a common input to many functions.

base_csgraph property

Get the base sparse graph from original unmasked skeleton.

Returns:

  • csr_matrix –

    Base compressed sparse graph with Euclidean edge weights.

base_csgraph_binary property

Get the base binary sparse graph from original unmasked skeleton.

Returns:

  • csr_matrix –

    Base compressed sparse graph with binary edge weights.

base_parent_array property

Get the base parent array from original unmasked skeleton.

Returns:

  • ndarray –

    Base parent node array from original skeleton.

base_root property

Get the base root from original unmasked skeleton.

Returns:

  • int –

    Base root index from original skeleton.

base_root_positional property

Get the base root positional index from original unmasked skeleton.

Returns:

  • int –

    Base root positional index from original skeleton.

base_vertex_index property

Get the base vertex index from original unmasked skeleton.

Returns:

bbox property

Get the axis-aligned bounding box (min, max) of the data layer's vertices.

branch_points property

List of branch points of the skeleton based on vertex index

branch_points_positional property

List of branch points of the skeleton based on positional index

branch_points_undirected property

List of branch points of the skeleton based on vertex index potentially including root if a leaf node

branch_points_undirected_positional property

List of branch points of the skeleton based on positional index potentially including root if a leaf node

cover_paths property

A collection of unbranched paths from each end point toward the root. Each path ends when it hits a vertex that's already been visited in a previous path. Paths are represented in dataframe indices.

cover_paths_positional property

A collection of unbranched paths from each end point toward the root. Each path ends when it hits a vertex that's already been visited in a previous path. Paths are represented in positional indices.

csgraph property

Get the compressed sparse graph representation of the layer with Euclidean edge weights.

csgraph_binary property

Get the unweighted compressed sparse graph representation of the layer.

csgraph_binary_undirected property

Get the unweighted and undirected compressed sparse graph representation of the layer.

csgraph_undirected property

Get the undirected compressed sparse graph representation of the layer with Euclidean edge weights.

edge_df property

Get the edges of the layer as a DataFrame.

edges property

Get the edges of the layer in dataframe indices.

edges_positional property

Get the edges of the layer in positional indices.

end_points property

List of end points of the skeleton based on vertex index

end_points_positional property

List of end points of the skeleton based on positional index

end_points_undirected property

List of end points of the skeleton based on vertex index potentially including root if a leaf node

end_points_undirected_positional property

List of end points of the skeleton based on positional index potentially including root if a leaf node

feature_names property

Get the list of column names associated with features (non-spatial columns).

features property

Get the features DataFrame.

half_edge_length property

Get the sum length of half-edges from a vertices to all parents and children.

Returns:

  • ndarray –

    Array of half-edge lengths for each vertex.

kdtree property

Get the KDTree for the data layer's vertices for efficient spatial queries. See scipy.spatial.KDTree for documentation.

layer property

Get the morphsync layer associated with the data layer.

n_branch_points property

Number of branch points in the skeleton

n_end_points property

Number of end points in the skeleton

n_topo_points property

Number of topological points in the skeleton

n_vertices property

Get the number of vertices in the data layer.

name property

Layer name.

nodes property

Get the complete DataFrame of vertices and all associated data, including both spatial columns and features.

parent_node_array property

Get the parent node array for the skeleton, or -1 for a missing parent.

parentless_nodes property

List of nodes by vertex index that do not have any parents, including any root node.

parentless_nodes_positional property

List of nodes by positional index that do not have any parents, including any root node.

root property

Get the root node index.

Returns:

  • Optional[int] –

    Root node index, or None if no root is set.

root_location property

Get the spatial coordinates of the root node.

Returns:

  • Optional[ndarray] –

    3D coordinates of the root node, or None if no root is set.

root_positional property

Get the root node positional index.

Returns:

  • Optional[int] –

    Root node positional index, or None if no root is set.

segment_map property

Get the mapping from each vertex to its segment index

segments property

Get the segments of the layer, a list of arrays where each array represents an unbranched span from end point or branch point to the upstring branch point or root (non-inclusive). Segments are presented in dataframe indices.

segments_plus property

Segments plus their parent node in dataframe indices.

Returns:

  • List[ndarray] –

    List of segment arrays including parent nodes in dataframe indices.

segments_plus_positional property

Segments plus their parent node in positional indices.

Returns:

  • List[ndarray] –

    List of segment arrays including parent nodes in positional indices.

segments_positional property

Get the segments of the layer, a list of arrays where each array represents an unbranched span from end point or branch point to the upstring branch point or root (non-inclusive). Segments are presented in positional indices.

Returns:

  • List[ndarray] –

    List of segment arrays in positional indices.

spatial_columns property

Get the list of column names associated with the x, y, and z positions.

topo_points property

All vertices not along a segment: branch points, end points, and root node

topo_points_positional property

All vertices not along a segment: branch points, end points, and root node

vertex_df property

Get the Nx3 vertex positions of the data layer as an indexed DataFrame.

vertex_index property

Get vertex indices as a numpy array.

vertex_index_map property

Get a dictionary mapping vertex indices to their positional indices.

vertices property

Get the Nx3 vertex positions of the data layer.

__getitem__(key)

Passthrough to nodes dataframe

add_feature(feature, name=None)

Add a new vertex feature to the layer.

Parameters:

  • feature (Union[list, ndarray, dict, DataFrame]) –

    The feature data to add. If an array or list, it should follow the vertex order.

  • name (Optional[str], default: None ) –

    The name of the feature column (required if feature is a list or np.ndarray).

Returns:

  • Self –

    The updated DataLayer instance.

apply_mask(mask, as_positional=False, self_only=False)

Apply a mask on the current layer. Returns a new object with the masked morphsync. If the object is associated with a CellSync, a new CellSync will be created, otherwise a new object of the same class will be returned.

Properties

mask: np.ndarray The mask to apply, either in boolean, vertex index, or positional index form. as_positional: bool If providing indices, specify if they are positional indices (True) or vertex indices (False). self_only: bool If True, only apply the mask to the current object and not to any associated CellSync.

Returns:

  • masked_object Union[Self, "CellSync"] –

    Either a new object of the same class or a new CellSync will be returned.

cable_length(vertices=None, as_positional=False)

The net cable length of the subgraph formed by given vertices. If no vertices are provided, the entire graph is used.

Parameters:

  • vertices (Optional[Union[list, ndarray]], default: None ) –

    The vertices to include in the subgraph. If None, the entire graph is used.

  • as_positional (bool, default: False ) –

    Whether the vertices are positional indices. If False, they are treated as vertex features.

Returns:

  • float –

    The net cable length of the subgraph.

child_vertices(vertices=None, as_positional=False)

Get mapping from vertices to their child nodes.

Parameters:

  • vertices (Union[ndarray, List[int]], default: None ) –

    The vertices to get the child nodes for.

  • as_positional (bool, default: False ) –

    Whether the vertices are positional indices. If False, they are treated as vertex features.

Returns:

  • dict –

    A dictionary mapping each vertex to its child nodes.

copy()

Create a deep copy of the current object.

Returns:

  • Union[Self, Cell] –

    A new object of the same class without the CellSync.

cover_paths_specific(sources, as_positional=False)

Get cover paths starting from specific source vertices.

Parameters:

  • sources (Union[ndarray, list]) –

    The source vertices to start the cover paths from.

  • as_positional (bool, default: False ) –

    Whether the sources are positional indices. If False, they are treated as vertex features.

Returns:

  • list –

    A list of cover paths, each path is a list of vertex indices, ordered as the typical cover_paths method.

describe()

Generate a compact description of the layer including vertices, features, and links.

Provides information about: - Layer name and type - Vertex count (and edges/faces for applicable layer types) - feature names - Links to other layers

Returns:

  • None –

    Always returns None (prints formatted text)

distance_between(sources=None, targets=None, as_positional=False, limit=None)

Get the distance between two sets of vertices in the skeleton.

Parameters:

  • sources (Optional[ndarray], default: None ) –

    The source vertices. If None, all vertices are used.

  • targets (Optional[ndarray], default: None ) –

    The target vertices. If None, all vertices are used.

  • as_positional –

    Whether the input vertices are positional (i.e., masks or indices). Must be the same for sources and targets.

  • limit (Optional[float], default: None ) –

    The maximum distance to consider in the graph distance lookup. If None, no limit is applied. Distances above this will be set to infinity.

Returns:

  • ndarray –

    The distance between each source and target vertex, of dimensions len(sources) x len(targets).

distance_to_root(vertices=None, as_positional=False)

Get the distance to the root for each vertex in the skeleton, or for a subset of vertices. Always uses the original skeleton topology, so that root is inherited from the original root even if it is currently masked out. E.g. if you mask an axon only, you can still get distance to the root soma even if the soma is not in your current object.

Parameters:

  • vertices (Optional[ndarray], default: None ) –

    The vertices to get the distance from the root for. If None, all vertices are used.

  • as_positional (bool, default: False ) –

    If True, the vertices are treated as positional indices. If False, they are treated as vertex features.

Returns:

  • ndarray –

    The distance from the root for each vertex.

downstream_vertices(vertex, inclusive=False, as_positional=False)

Get all vertices downstream of a specified vertex

Parameters:

  • vertex (Union[int, ndarray]) –

    The vertex to get the downstream vertices for.

  • inclusive –

    Whether to include the specified vertex in the downstream vertices.

  • as_positional (bool, default: False ) –

    Whether the vertex is a positional index. If False, it is treated as a vertex feature.

Returns:

  • ndarray –

    The downstream vertices, following the same mode as the as_positional parameter.

drop_features(features)

Drop features from the DataFrame.

Parameters:

  • features (Union[str, list]) –

    The feature column name or list of names to drop.

Returns:

  • Self –

    The updated DataLayer instance.

expand_to_segment(vertices, as_positional=False)

For each vertex in vertices, get the corresponding segment.

Parameters:

  • vertices (Union[ndarray, List[int]]) –

    Vertices to expand to their segments.

  • as_positional (bool, default: False ) –

    Whether vertices are positional indices. Default False.

Returns:

  • List[ndarray] –

    List of segments corresponding to input vertices.

get_feature(key)

Get a feature array from the features DataFrame.

Parameters:

  • key (str) –

    Column name of the feature to retrieve.

Returns:

  • ndarray –

    Array of feature values for all vertices.

get_unmapped_vertices(target_layers=None)

Identify vertices in this layer that have no mapping to specified target layers.

Parameters:

  • target_layers (Optional[Union[str, List[str]]], default: None ) –

    Target layer name(s) to check mappings against. If None, checks all other layers in the morphsync object except the current layer.

Returns:

  • ndarray –

    Vertices in this layer that have null mappings to any of the target layers.

hops_to_root(vertices=None, as_positional=False)

Distance to root in number of hops between vertices. Always works on the base graph, whether the root is masked out or not.

Parameters:

  • vertices (Optional[ndarray], default: None ) –

    The vertices to get the distance from the root for. If None, all vertices are used.

  • as_positional (bool, default: False ) –

    If True, the vertices are treated as positional indices. If False, they are treated as vertex features.

Returns:

  • ndarray –

    The distance from the root for each vertex.

iloc(key)

Passthrough to layer.nodes.iloc

loc(key)

Passthrough to layer.nodes.loc

lowest_common_ancestor(u, v, as_positional=False)

Get the lowest common ancestor of two vertices in the skeleton.

Parameters:

  • u (int) –

    The first vertex.

  • v (int) –

    The second vertex.

  • as_positional (bool, default: False ) –

    Whether the vertices are positional indices. If False, they are treated as vertex features.

Returns:

  • Optional[int] –

    The lowest common ancestor of the two vertices, or None if not found.

map_annotations_to_feature(annotation, distance_threshold, agg='count', chunk_size=1000, validate=False, agg_direction='undirected')

Aggregates a point annotation to a feature on the layer based on a maximum proximity.

Parameters:

  • annotation (str) –

    The name of the annotation to project.

  • distance_threshold (float) –

    The maximum distance to consider for projecting annotations.

  • agg (Union[Literal['count', 'density'], dict], default: 'count' ) –

    The aggregation method to use. Can be "count", or a dict specifying custom aggregations on the annotations properties as per the groupby.agg method. * "count" returns how many annotations are within the given radius. * "density" returns the count of annotations divided by the subgraph path length measured in half-edge-lengths per vertex. * To make a new feature called "aggregate_feature" that is the median "size" of a point annotation, it would be {"aggregate_feature": ('size', 'median')}. Multiple features can be specified at the same time in this manner.

  • chunk_size (int, default: 1000 ) –

    The size of chunks to process at a time, which limits memory consumption. Defaults to 1000.

Returns:

  • Series or DataFrame –

    A series (with 'count' or 'density') or dataframe (with dictionary agg) containing the projected annotation values for each vertex.

map_features_to_layer(features, layer, agg='mean')

Map features from one layer to another.

Parameters:

  • features (Union[str, list]) –

    The features to map from the source layer.

  • layer (str) –

    The target layer to map the features to.

  • agg (Union[str, dict], default: 'mean' ) –

    The aggregation method to use when mapping the features. This can take anything pandas groupby.agg takes, as well as "majority" which will is a majority vote across the mapped indices via the stats.mode function.

Returns:

  • DataFrame –

    The mapped features for the target layer. Vertices with no mapping will have NaN values.

map_index_to_layer(layer, source_index=None, as_positional=False, validate=False)

Map each vertex index from the current layer to a single index in the specified layer.

Parameters:

  • layer (str) –

    The target layer to map the index to.

  • source_index (Optional[ndarray], default: None ) –

    The source index to map from. If None, all vertices are used. Can also be a boolean array.

  • as_positional (bool, default: False ) –

    Whether to treat source_index and mapped index as positional (i_th element of the array) or as a dataframe index.

  • validate (bool, default: False ) –

    Whether to raise an error is the mapping is ambiguous, i.e. it is not clear which target index to use.

Returns:

  • ndarray –

    The mapped indices in the target layer. There will be exactly one target index for each source index, no matter how many viable target indices there are. If as_positional is True, the mapping is based on the position of the vertices not the dataframe index.

map_index_to_layer_region(layer, source_index=None, as_positional=False)

Map each vertex index from the current layer to a list of all appropriate vertices in the target layer.

Parameters:

  • layer (str) –

    The target layer to map the index to.

  • source_index (Optional[ndarray], default: None ) –

    The source indices to map from. If None, all vertices are used. Can also be a boolean array.

  • as_positional (bool, default: False ) –

    Whether to treat source_index and mapped index as positional (i_th element of the array) or as a dataframe index.

Returns:

  • dict –

    A dictionary mapping each source index to a list of all mapped target indices.

map_mask_to_layer(layer, mask=None)

Map a boolean mask from the current layer to the specified layer.

Parameters:

  • layer (str) –

    The target layer to map the index to.

  • mask (Optional[ndarray], default: None ) –

    The boolean mask to map from. If None, all vertices are used.

Returns:

  • ndarray –

    The mapped boolean mask in the target layer. There may be multiple target indices for each source index, depending on the region mapping. If as_positional is True, the mapping is based on the position of the vertices not the dataframe index.

map_region_to_layer(layer, source_index=None, as_positional=False)

Map each vertex index from the current layer to the specified layer.

Parameters:

  • layer (str) –

    The target layer to map the index to.

  • source_index (Optional[ndarray], default: None ) –

    The source indices to map from. If None, all vertices are used. Can also be a boolean array.

  • as_positional (bool, default: False ) –

    Whether to treat source_index and mapped index as positional (i_th element of the array) or as a dataframe index.

Returns:

  • ndarray –

    All mapped indices in the target layer. Not necessarily the same length as the source indices, because it maps a region to another region. If as_positional is True, the mapping is based on the position of the vertices not the dataframe index.

mask_context(mask)

Context manager to temporarily apply a mask via the current layer.

Parameters:

  • mask (ndarray) –

    The mask to apply, either in boolean, vertex index, or positional index form.

Yields:

  • Self –

    A new object of the same class with the mask applied.

Example

with cell.skeleton.mask_context(mask) as masked_cell: masked_path_length = masked_cell.mesh.surface_area()

mask_out_unmapped(target_layers=None, self_only=False)

Create a new object with unmapped vertices removed.

This function identifies vertices that have null mappings to specified target layers and creates a masked version of the object with those vertices removed.

Parameters:

  • target_layers (Optional[Union[str, List[str]]], default: None ) –

    Target layer name(s) to check mappings against. If None, checks all other layers in the morphsync object except the current layer.

  • self_only (bool, default: False ) –

    If True, only apply mask to current layer. If False, apply to entire Cell. Default False.

Returns:

  • Union[Self, Cell] –

    New object with unmapped vertices removed.

Examples:

>>> # Remove skeleton vertices that don't map to mesh
>>> clean_skeleton = skeleton.mask_out_unmapped("mesh")

>>> # Remove vertices that don't map to multiple layers
>>> clean_skeleton = skeleton.mask_out_unmapped(["mesh", "annotations"])

>>> # Clean up only the current layer, not the whole cell
>>> clean_skeleton = skeleton.mask_out_unmapped("mesh", self_only=True)

>>> # Remove vertices that don't map to ANY other layer
>>> clean_skeleton = skeleton.mask_out_unmapped()

path_between(source, target, as_positional=False, as_vertices=False)

Get the shortest path between two vertices in the skeleton.

Parameters:

  • source (int) –

    The source vertex.

  • target (int) –

    The target vertex.

  • as_positional –

    Whether the input vertices are positional (i.e., masks or indices). Must be the same for sources and targets.

  • as_vertices –

    Whether to return the path as vertex IDs or 3d positions.

Returns:

  • ndarray –

    The shortest path between each source and target vertex, indices if as_positional is False, or nx3 array if as_vertices is True.

proximity_mapping(distance_threshold, chunk_size=1000, agg_direction='undirected')

Get a DataFrame of all vertices within a certain distance of each other.

Parameters:

  • distance_threshold (float) –

    Maximum distance to consider for proximity.

  • chunk_size (int, default: 1000 ) –

    Size of processing chunks for memory efficiency. Default 1000.

  • agg_direction (Literal['undirected', 'upstream', 'downstream'], default: 'undirected' ) –

    Direction along the skeleton to consider for proximity. Options are 'undirected', 'upstream', 'downstream'. "undirected" considers all neighbors within the distance threshold. "upstream" considers only neighbors towards the root. "downstream" considers only neighbors away from the root. Default is 'undirected'.

Returns:

  • DataFrame –

    DataFrame with columns 'idx' and 'prox_idx' indicating pairs of proximal vertices.

reroot(new_root, as_positional=False)

Reroot to a new index. Important: that this will reset any inherited properties from an unmasked skeleton!

Parameters:

  • new_root (int) –

    The new root index to set.

  • as_positional –

    Whether the new root is a positional index. If False, the new root is treated as a vertex feature.

Returns:

segments_capped(max_length, positional=True)

Get segments that are capped at a maximum length.

Parameters:

  • max_length (float) –

    The maximum length of each segment.

  • positional (bool, default: True ) –

    Whether to return segments in positional indices. Default True.

import_legacy_meshwork(filename, l2_skeleton=True, as_pcg_skel=False)

Import a legacy MeshWork file as a Cell object. Requires h5py, which can be installed with pip install ossify[legacy].

Parameters:

  • filename (Union[str, BinaryIO]) –

    The path to the MeshWork file or an open binary file object.

  • l2_skeleton (bool, default: True ) –

    Whether to import the skeleton as a level 2 skeleton (True, puts "mesh" data into cell.graph) or as a mesh (False, puts "mesh" data into cell.mesh).

  • as_pcg_skel (bool, default: False ) –

    Whether to process the skeleton to remap typical pcg-skel built skeleton annotations like segment properties and volume properties into features. Volume properties are mapped to graph features (since they are associated with L2 graph vertices) while segment properties are mapped to skeleton features.

Returns:

  • tuple[Cell, ndarray] –

    The imported Cell object and a boolean mask indicating which mesh vertices correspond to skeleton nodes. Note the mask is not pre-applied, since masking removes data in ossify. You can apply the mask with cell.graph.apply_mask(mask) (if l2_skeleton is True) or cell.mesh.apply_mask(mask) (if l2_skeleton is False).

load_cell(source)

Load a neuronal object from a file path or file object.

Parameters:

  • source (Union[str, BinaryIO]) –

    The path to the file/cloudpath or an open binary file object.

Returns:

  • Cell –

    The loaded Cell object.

load_cell_from_client(root_id, client, *, synapses=False, reference_tables=None, reference_suffixes=None, restore_graph=False, restore_properties=True, synapse_spatial_point='ctr_pt_position', include_partner_root_id=False, timestamp=None, omit_self_synapses=True, skeleton_version=4)

Import an "L2" skeleton and spatial graph using the CAVE skeleton service.

Parameters:

  • root_id (int) –

    The root ID of the cell to import.

  • client (CAVEclientFull) –

    The CAVE client to use for data retrieval.

  • synapses (bool, default: False ) –

    Whether to include synapse information in the imported cell. Default is False.

  • reference_tables (Optional[list[str]], default: None ) –

    A list of table names to include as reference tables for synapse annotation. These will be merged into the synapse DataFrame if synapses=True.

  • restore_graph (bool, default: False ) –

    Whether to restore the complete spatial graph for the imported cell. Default is False. Setting to True will include all graph edges, but can take longer to process.

  • restore_properties (bool, default: True ) –

    Whether to restore all graph vertex properties of the imported cell. Default is False.

  • synapse_spatial_point (str, default: 'ctr_pt_position' ) –

    The spatial point column name for synapses. Default is "ctr_pt_position".

  • include_partner_root_id (bool, default: False ) –

    Whether to include the synaptic partner root ID from the imported cell. Default is False. If including partner root id, you are encouraged to set a timestamp to ensure consistent results. Otherwise, querying different cells at different points in time can result in different results for partner root ids.

  • timestamp (Optional[datetime], default: None ) –

    The timestamp to use for the query. If not provided, the latest timestamp the root id is valid will be used.

  • omit_self_synapses (bool, default: True ) –

    Whether to omit self-synapses from the imported cell. Default is True, since most are false detections.

  • skeleton_version (int, default: 4 ) –

    The skeleton service data version to use for the query. Default is 4.

Returns:

  • Cell –

    The imported cell object.

save_cell(cell, file=None, allow_overwrite=False)

Save Cell to a file path or file object.

Parameters:

  • cell (Cell) –

    The Cell object to save.

  • file (Union[str, PathLike, BinaryIO, None], default: None ) –

    File path, path-like object, open binary file object, or None (uses ".osy" as a string).

  • allow_overwrite (bool, default: False ) –

    Whether to allow overwriting existing files.