Skip to content

statebuilder.ngl_components

Classes:

Functions:

AnnotationLayer

Bases: LayerWithSource

Methods:

add_annotations(annotations)

Add annotations to the layer.

Parameters:

  • annotations (list) –

    The annotations to add.

Returns:

  • self –

    The AnnotationLayer object with added annotations.

add_boxes(data, point_a_column, point_b_column, segment_column=None, description_column=None, tag_column=None, tag_bools=None, data_resolution=None)

Add point annotations to the layer.

Parameters:

  • data (DataFrame) –

    The DataFrame containing the point annotations.

  • point_a_column (str) –

    The column name for the start point coordinates of the box. Can be a prefix for a split column name with _x, _y, _z as suffixes.

  • point_b_column (str) –

    The column name for the end point coordinates of the box Can be a prefix for a split column name with _x, _y, _z as suffixes.

  • segment_column (str, default: None ) –

    The column name for the segment IDs. Default is None.

  • description_column (str, default: None ) –

    The column name for the segment descriptions. Default is None.

  • data_resolution (list, default: None ) –

    The resolution of the data. Default is None.

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

    The column name for the tags. Default is None. Row values should be strings. Nones and NAs will be skipped.

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

    List of column names to treat as a tag, with values being booleans indicating whether the tag is present or not. Default is None.

  • data_resolution (list, default: None ) –

    The resolution of the data. If None, follows from layer resolution. Default is None.

Returns:

add_ellipsoids(data, center_column, radii_column, segment_column=None, description_column=None, tag_column=None, tag_bools=None, data_resolution=None)

Add point annotations to the layer.

Parameters:

  • data (DataFrame) –

    The DataFrame containing the point annotations.

  • center_column (str) –

    The column name for the center point coordinates. Can be a prefix for a split column name with _x, _y, _z as suffixes.

  • radii_column (str) –

    The column name for the radius values. Can be a prefix for a split column name with _x, _y, _z as suffixes.

  • segment_column (str, default: None ) –

    The column name for the segment IDs. Default is None.

  • description_column (str, default: None ) –

    The column name for the segment descriptions. Default is None.

  • data_resolution (list, default: None ) –

    The resolution of the data. Default is None.

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

    The column name for the tags. Default is None. Row values should be strings. Nones and NAs will be skipped.

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

    List of column names to treat as a tag, with values being booleans indicating whether the tag is present or not. Default is None.

  • data_resolution (list, default: None ) –

    The resolution of the data. If None, follows from layer resolution. Default is None.

Returns:

add_lines(data, point_a_column, point_b_column, segment_column=None, description_column=None, tag_column=None, tag_bools=None, data_resolution=None)

Add point annotations to the layer.

Parameters:

  • data (DataFrame) –

    The DataFrame containing the point annotations.

  • point_a_column (str) –

    The column name for the start point coordinates. Can be a prefix for a split column name with _x, _y, _z as suffixes.

  • point_b_column (str) –

    The column name for the end point coordinates. Can be a prefix for a split column name with _x, _y, _z as suffixes.

  • segment_column (str, default: None ) –

    The column name for the segment IDs. Default is None.

  • description_column (str, default: None ) –

    The column name for the segment descriptions. Default is None.

  • data_resolution (list, default: None ) –

    The resolution of the data. Default is None.

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

    The column name for the tags. Default is None. Row values should be strings. Nones and NAs will be skipped.

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

    List of column names to treat as a tag, with values being booleans indicating whether the tag is present or not. Default is None.

  • data_resolution (list, default: None ) –

    The resolution of the data. If None, follows from layer resolution. Default is None.

Returns:

add_points(data, point_column=None, segment_column=None, description_column=None, tag_column=None, tag_bools=None, data_resolution=None)

Add point annotations to the layer.

Parameters:

  • data (DataFrame or ndarray) –

    The DataFrame containing the point annotations or an Nx3 array. If using an array, there is no way to set segment IDs, descriptions, or tags.

  • point_column (str, default: None ) –

    The column name for the point coordinates. Can be a prefix for a split column name with _x, _y, _z as suffixes.

  • segment_column (str, default: None ) –

    The column name for the segment IDs. Default is None.

  • description_column (str, default: None ) –

    The column name for the segment descriptions. Default is None.

  • tag_column (str, default: None ) –

    The column name for segment descripion. Default is None.

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

    The column name for the tags. Default is None. Row values should be strings. Nones and NAs will be skipped.

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

    List of column names to treat as a tag, with values being booleans indicating whether the tag is present or not. Default is None.

  • data_resolution (list, default: None ) –

    The resolution of the data. If None, follows from layer resolution. Default is None.

Returns:

add_shader(shader)

Add a shader to the layer.

Parameters:

  • shader (str) –

    The shader to add.

apply_to_neuroglancer(viewer)

Can be a viewer or a viewer.txn()-context state

set_linked_segmentation(layer)

Add a linked segmentation layer to the annotation layer.

Parameters:

  • layer (str or SegmentationLayer) –

    The linked segmentation layer or the string value of its name.

CoordSpace

Coordinate space for Neuroglancer.

Parameters:

  • resolution (list[int]) –

    The resolution of the coordinate space. Default is None, which will raise an error if not set.

  • units (str or list[str]) –

    The units of the coordinate space. Default is "nm". If a single string is provided, it will be repeated for each dimension.

  • names (list[str]) –

    The names of the dimensions. Default is ["x", "y", "z"]. If the length of names does not match the length of resolution, an error will be raised.

CoordSpaceTransform

Coordinate space transform for Neuroglancer.

Parameters:

  • output_dimensions (list[int] or CoordSpace) –

    The output dimensions of the transform. If a list, it will be converted to a CoordSpace. Default is None, which will create a transform with no output dimensions.

  • input_dimensions (list[int] or CoordSpace) –

    The input dimensions of the transform. If a list, it will be converted to a CoordSpace. Default is None, which will create a transform with no input dimensions.

  • matrix (list[list[float]]) –

    The transformation matrix. Default is None, which will create an identity matrix. The matrix should be a 4x4 list of lists, where the last row is [0, 0, 0, 1]. If None, an identity matrix will be created based on the output dimensions.

DataMap

Class to defer mapping of dataframes to a ViewerState or Layer.

Parameters:

  • key (str) –

    The key to use for the datamap, which is used to label data when using the map or with_map classes. If no key is provided, a default key of "None" is used and assumed if no dictionary is provided later.

ImageLayer

Bases: LayerWithSource

Configuration for a Neuroglancer image layer.

Parameters:

  • name (str) –

    The name of the layer. Default is "img".

  • source (Source or list of Source) –

    The source of the image data. Can be a Source object or a list of Source objects.

  • shader (str) –

    The shader to use for rendering the image. Default is None, which will use the default shader.

  • color (list) –

    The color to use for the image layer. Default is None, which will use the default color.

  • opacity (float) –

    The opacity of the image layer. Default is 1.0.

  • blend (str) –

    The blending mode for the image layer. Default is None, which will use the default blend mode.

  • volume_rendering_mode (str) –

    The volume rendering mode for the image layer. Default is None, which will use the default mode.

  • volume_rendering_gain (float) –

    The gain for volume rendering. Default is None, which will use the default gain.

  • volume_rendering_depth_samples (int) –

    The number of depth samples for volume rendering. Default is None, which will use the default number of samples.

  • cross_section_render_scale (float) –

    The scale for cross-section rendering. Default is None, which will use the default scale.

  • pick –

    Whether to allow cursor interaction with meshes and skeletons. Default is True.

Methods:

add_from_client(client)

Add an image layer source from caveclient.

Parameters:

  • client (CAVEclient) –

    The CAVEclient object.

Returns:

add_shader(shader)

Add a shader to the layer.

Parameters

shader : str
    The shader to add.

apply_to_neuroglancer(viewer)

Can be a viewer or a viewer.txn()-context state

Layer

Bases: ABC

Methods:

  • map –

    Map the layer to a datamap.

  • to_dict –

    Convert the layer to a dictionary.

Attributes:

is_static property

Check if the layer is static.

map(datamap, inplace=False)

Map the layer to a datamap.

Parameters:

  • datamap (dict) –

    The datamap to map the layer to.

  • inplace (bool, default: False ) –

    Whether to modify the layer in place or return a new layer. Default is False.

to_dict(with_name=True)

Convert the layer to a dictionary.

Parameters:

  • with_name (bool, default: True ) –

    Whether to include the name, visibility, and archived states of the layer in the dictionary, by default True. These are not typically included until the layer is part of a state, but adding them in allows the resulting data to be passed to a viewer state string.

  • datamap –

    A dictionary with keys being names of DataMap parameters and values being the data to be passed. Must be provided if the layer has any datamaps registered.

Returns:

  • dict –

    The layer as a dictionary.

LayerWithSource

Bases: Layer

Methods:

add_source(source, resolution=None)

Add a source to the layer.

Parameters:

  • source (str or Source) –

    The source to add.

  • resolution (list or ArrayLike, default: None ) –

    The resolution of the source. Default is None.

RawLayer

Bases: Layer

Configuration for a Neuroglancer raw layer from a data source

Methods:

  • remap_sources –

    Remap the sources in the layer's JSON data using the provided source map.

remap_sources(source_map)

Remap the sources in the layer's JSON data using the provided source map.

Parameters:

  • source_map (dict) –

    A mapping from old source paths to new source identifiers.

Returns:

  • Self –

    The updated layer with remapped sources.

SegmentationLayer

Bases: LayerWithSource

Configuration for a Neuroglancer segmentation layer.

Parameters:

  • name (str) –

    The name of the layer. Default is "seg".

  • source (Source or str) –

    The source of the segmentation data. Can be a Source object or a string URL.

  • segments (list or dict or VisibleSegments) –

    The segments to display in the layer. Can be a list of segment IDs, a dictionary with segment IDs as keys and visibility as values, or a VisibleSegments object.

  • color (list) –

    The color to use for the segments. Default is None, which will use the default color.

  • hide_segment_zero (bool) –

    Whether to hide segment zero, which is typically treated as "no segmentation". Default is True.

  • selected_alpha (float) –

    The transparency value for selected segments in the 2d views. Default is 0.2.

  • not_selected_alpha (float) –

    The transparency value for unselected segments in the 2d views. Default is 0.0.

  • alpha_3d (float) –

    The transparency value for segments in the 3d view. Default is 0.9.

  • mesh_silhouette (float) –

    The silhouette rendering value for the mesh. Default is 0.0.

  • segment_colors (dict) –

    A dictionary mapping segment IDs to colors. Default is None, which will use the default colors.

  • shader (str) –

    The shader to use for rendering the skeletons if a skeleton source is provided. Default is None, which will use the default shader.

  • pick –

    Whether to allow cursor interaction with meshes and skeletons. Default is True.

Methods:

add_default_skeleton_shader()

Add a default skeleton shader with desaturated axons to the layer.

add_from_client(client, add_skeleton_source=True)

Add a segmentation layer source from caveclient.

Parameters:

  • client (CAVEclient) –

    The CAVEclient object.

Returns:

add_segment_colors(segment_colors)

Add segment colors to the layer.

Parameters:

  • segment_colors (dict) –

    The segment colors to add.

Returns:

add_segment_properties(data, client, id_column='pt_root_id', label_column=None, description_column=None, string_columns=None, number_columns=None, tag_value_columns=None, tag_bool_columns=None, tag_descriptions=None, allow_disambiguation=True, label_separator='_', label_format_map=None, prepend_col_name=False, random_columns=None, random_column_prefix=None, dry_run=False)

Upload segment properties and add to the layer. If you already have a segment properties cloud path, use add_source to add it to the layer.

Parameters:

  • data (DataFrame) –

    The DataFrame containing the segment properties.

  • client (CAVEclient) –

    The CAVEclient object needed to upload .

  • id_column (str, default: 'pt_root_id' ) –

    The column name for the segment IDs. Default is 'pt_root_id'.

  • label_column (str or list, default: None ) –

    The column name(s) for the segment labels. Default is None.

  • description_column (str, default: None ) –

    The column name for the segment descriptions. Default is None.

  • string_columns (list, default: None ) –

    The column names for string properties. Default is None.

  • number_columns (list, default: None ) –

    The column names for number properties. Default is None.

  • tag_value_columns (list, default: None ) –

    The column names for tag value properties. Default is None.

  • tag_bool_columns (list, default: None ) –

    The column names for tag boolean properties. Default is None.

  • tag_descriptions (list, default: None ) –

    The descriptions for the tags. Default is None.

  • allow_disambiguation (bool, default: True ) –

    Whether to allow disambiguation of segment IDs. Default is True.

  • label_separator (str, default: '_' ) –

    The separator for label formatting. Default is "_".

  • label_format_map (str, default: None ) –

    The format map for labels. Default is None.

  • prepend_col_name (bool, default: False ) –

    Whether to prepend the column name to the label. Default is False.

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

    Number of random columns to add. Default is None.

  • random_column_prefix (str, default: None ) –

    Name prefix of the random columns. Default is None.

  • dry_run (bool, default: False ) –

    If dry run is true, build but do not actually upload and instead use a placeholder source text. Default is False.

Returns:

add_segments(segments, visible=None)

Add segment ids to the layer.

Parameters:

  • segments (list or dict or VisibleSegments) –

    The segments to add. If a dict, the keys are the segment IDs and the values are the boolean visibility.

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

    The visibility of the segments, assumed to be True if not provided. Should be the same length as segments, and segments should be a list of the same length.

Returns:

add_segments_from_data(data, segment_column, visible_column=None, color_column=None)

Create a SegmentationLayer from a DataFrame.

Parameters:

  • data (DataFrame) –

    The DataFrame containing the segmentation data.

  • name (str) –

    The name of the layer. Default is "seg".

  • color (str) –

    The color to use.

  • shader (str) –

    The shader to use.

Returns:

add_shader(shader)

Add a shader to the layer.

Parameters:

  • shader (str) –

    The shader to add.

apply_to_neuroglancer(viewer)

Can be a viewer or a viewer.txn()-context state

set_view_options(selected_alpha=None, not_selected_alpha=None, alpha_3d=None, mesh_silhouette=None)

Set the view options for the layer.

Parameters:

  • selected_alpha (float, default: None ) –

    The alpha value for selected segments. Default is 0.2.

  • not_selected_alpha (float, default: None ) –

    The alpha value for not selected segments. Default is 0.0.

  • alpha_3d (float, default: None ) –

    The alpha value for 3D segments. Default is 0.9.

  • mesh_silhouette (float, default: None ) –

    The silhouette value for the mesh. Default is 0.0.

Returns:

Source

Configuration for a Neuroglancer data source.

Parameters:

  • url (str) –

    The URL of the data source.

  • resolution (list) –

    The resolution of the data source. Default is None.

  • transform (CoordSpaceTransform) –

    The coordinate space transform for the data source. Default is None, which will create a transform based on the resolution.

  • subsources (dict) –

    A dictionary of subsources for the data source (e.g. meshes, skeletons, etc). Default is None, which includes all subsources.

  • enable_default_subsources (bool) –

    Whether to enable default subsources. Default is True, which includes all default subsources.

Methods:

to_neuroglancer()

Convert the Source to a neuroglancer-python object.

UnmappedDataError

Bases: Exception

Exception raised when a layer is not fully mapped to a datamap.

segments_to_neuroglancer(segments)

Convert a flat or mixed-visibility segment list to Neuroglancer.

source_to_neuroglancer(source, resolution=None, image_layer=False)

Convert a possibly multi-url source to a Neuroglancer-compatible format.