syglass package

Module contents

class syglass.Block(data, offset)

Bases: object

Instances of this class represent blocks of volumetric image data. These blocks can be retrieved from Project objects using a number of functions such as get_block() and get_block_by_point().

Block objects have two fields: data and offset. The data field contains a 4D numpy array whose dimensions represent z, y, x, and channel respectively. The offset field is a 1D numpy array of length 3 whose values represent the offset in voxels between the origin of the entire image volume and the origin of the block, where the origin is the bottom-left corner in either case.

class syglass.Project(project_impl)

Bases: object

Instances of this class represent syGlass projects. Instances can be created by calling syglass.get_project() with the string path to the project’s .syg file.

add_label_to_surface(label_name: str, surface_name: str, experiment: str = 'default') → None

Add a label to a surface.

Parameters:

  • label_name – the name of the label to apply

  • surface_name – the name of the surface to apply to label to

  • experiment – the name of the experiment in which to apply the label

add_new_experiment(experiment: str = 'default') → None

Creates a new, empty experiment.

Parameters:

experiment – the name of the newly made experiment

copy_experiment(source: str, destination: str) → None

Creates a copy of an existing experiment.

Parameters:

  • source – the name of experiment to make a copy of

  • destination – the name of the newly copied experiment

copy_shader_settings_from_project(source: Project) → None

Copy the shader settings from one project to another.

Parameters:

source – the project from which to copy the settings from

create_label(label_name: str, experiment: str = 'default') → None

Create a new label to apply to surfaces.

Parameters:

  • label_name – the name of the new label

  • experiment – the experiment in which to add the label to

delete_all_surfaces(experiment: str = 'default') → None

Deletes all surfaces in an experiment

Parameters:

experiment – the experiment to delete all surfaces from

delete_counting_points(experiment: str = 'default') → None

Deletes counting points associated with given experiment.

Parameters:

experiment – the name of the experiment from which to delete counting points

delete_experiment(experiment: str = 'default') → None

Deletes the selected experiment.

Parameters:

experiment – the name of the experiment to be deleted

delete_label(label_name: str, experiment: str = 'default') → None

Delete a label, removing it from all surfaces that have it

Parameters:

  • label_name – the name of the label to delete

  • experiment – the experiment in which to delete the label from

delete_multi_tracking_series(experiment: str = 'default') → None

Deletes all multi-tracking series associated with given experiment.

Parameters:

experiment – the name of the experiment from which to delete onion series

delete_multivariate_data(experiment: str = 'default') → None

Deletes multivariate data associated with given experiment.

Parameters:

experiment – the name of the experiment from which to delete multivariate data

delete_surface(surface_name: str, experiment: str = 'default') → None

Deletes a surface from an experiment

Parameters:

  • surface_name – the name of the surface to delete

  • experiment – the name of the experiment where the surface is

delete_tracking_points(experiment: str = 'default') → None

Deletes all tracking points associated with given experiment.

Parameters:

experiment – the name of the experiment from which to delete tracking points

dvid_delete_label(label: str, experiment: str = 'default') → None

Deletes label associated with given experiment.

Parameters:

  • label – the name of the label

  • experiment – the name of the experiment from which to delete label

get_block(timepoint: int, resolution_level: int, index: int) → Block

Returns a block of the project’s volumetric data as a Block object. To ensure that the block index you pass to this function is valid, you may use the function get_resoultion_map() to get a list containing the number of blocks at each resolution level.

Parameters:

  • timepoint – the timepoint from which to retrieve a block (0 for static volumes)

  • resolution_level – the resolution level from which to retrieve a block

  • index – the index of the target block within the given resolution level

Returns:

a block of the project’s volumetric data as a Block object

get_block_by_point(timepoint: int, resolution_level: int, point: ndarray) → Block

Returns the block of the project’s volumetric data that contains the given point as a Block object. The point passed to this function should be a numpy array of length three with elements representing the z, y, and x coordinates respectively. When using this function to query blocks containing annotation points from syGlass, always use the highest resolution level; the coordinates of these points are recorded with respect to the full resolution.

Parameters:

  • timepoint – the timepoint from which to retrieve a block (0 for static volumes)

  • resolution_level – the resolution level from which to retrieve a block

  • point – a numpy array of length 3 representing the target point

Returns:

the block of the project’s volumetric data that contains the given point as a Block object

get_block_size() → ndarray

Returns the dimensions in voxels of one block of the project’s volumetric data. The returned array has length 3, with each element describing the z-, y-, and x-dimension respectively.

Returns:

the dimensions in voxels of one block of the project’s volumetric data

get_channel_count() → int

Returns the integer number of channels the project’s volumetric data contains. The result can be assumed to be in the range [0, 4], as syGlass projects support at most 4 channels.

Returns:

the integer number of channels in the project’s volumetric data

get_citation() → str

Get the stored citation for the project.

Returns:

the stored citation as a string

get_counting_points(experiment: str = 'default') → Dict[str, ndarray]

Returns a dictionary containing all of the counting points associated with the given experiment. If no experiment is given, the default experiment is assumed. The dictionary has keys "Red", "Orange", "Yellow", "Green", "Cyan", "Blue", and "Violet", which map to numpy arrays containing zyx points. The coordinates of these points are in voxels and are relative to the highest resolution level.

Parameters:

experiment – the name of the experiment from which to retrieve counting points

Returns:

a dictionary containing all of the experiment’s counting points, their locations, and their colors

get_current_experiment() → str

Gets the current active experiment.

Returns:

the current experiment name

get_custom_block(timepoint: int, resolution_level: int, offset: ndarray, dimensions: ndarray) → Block

Returns a Block object of custom offset and dimensions. Rather than pulling a block directly from the syGlass project, this pulls as many blocks as necessary and stitches them together into a block fitting the given description. The offset and dimensions arguments should be 1D numpy arrays of length 3, with each element representing z, y, and x respectively.

Parameters:

  • timepoint – the timepoint from which to retrieve a block (0 for static volumes)

  • resolution_level – the resolution level from which to retrieve a block

  • offset – the distance from the bottom-left corner of the volume to the bottom-left corner of the block

  • dimensions – the desired dimensions for the block

Returns:

a Block object of custom offset and dimensions

get_data_type() → ProjectDataType

Returns a variant of the ProjectDataType enum describing the type of the project’s volumetric data.

Returns:

a ProjectDataType variant describing the type of the project’s volumetric data

get_distance_measurements(experiment: str = 'default') → array

Returns a numpy array containing all distance measurements associated with the given experiment. Each measurement is represented as a list of points. If no experiment is given, the default experiment is assumed. The coordinates of these points are in voxels and are relative to the highest resolution level.

Parameters:

experiment – the name of the experiment from which to retrieve counting points

Returns:

a numpy array containing all of the experiment’s lists of measurement points

get_experiments() → List[str]

Returns a list of all the experiments in the current project.

Returns:

a list containing all experiment names in the project

get_is_signed() → bool

Returns True if the project is signed, and False otherwise. Signed projects are immutable because they have been designated as read-only. Changes made to metadata and annotations of signed projects are reverted automatically when the last reference to the project is destroyed.

Returns:

a boolean indicating whether the project is signed

get_labels(experiment: str = 'default') → List[str]

Returns all the labels that exist in the given experiment

Parameters:

experiment – the experiment from which to get the labels from

Returns:

a list containing all labels in the experiment

get_mask(roi_index: int, experiment: str = 'default') → Block

Returns a given mask of the project’s volumetric data as a Block object. Currently does not support time series data and only supports 8 bit and 16 bit data types for now.

Parameters:

  • roi_index – the index of which roi mask to be retreived

  • experiment – the name of the current experiment

Returns:

the mask of the project’s volumetric data stored in a Block object

get_max_roi_point(roi_index: int, experiment: str = 'default') → ndarray

Returns the max point of an ROI given its index. The coordinates of these points are in voxels and their origin is with respect to the center of the volume.

Parameters:

  • roi_index – the index of which roi to be retreived

  • experiment – the name of the current experiment

Returns:

the max point of the ROI as a numpy array [z,y,x]

get_mesh_colors(experiment: str = 'default') → Dict[str, Tuple[int, int, int, int]]

Returns a dict of all the surface names mapping to their colors. The colors are formatted as a 4 element tuple containing R,G,B,A values ranging from 0-255.

Parameters:

experiment – the name of the experiment where the surfaces exist

Returns:

a dict of surface names to rgba color values

get_min_roi_point(roi_index: int, experiment: str = 'default') → ndarray

Returns the minimum point of an ROI given its index. The coordinates of these points are in voxels and their origin is with respect to the center of the volume.

Parameters:

  • roi_index – the index of which roi to be retreived

  • experiment – the name of the current experiment

Returns:

the minimum point of the ROI as a numpy array [z,y,x]

get_multitracking_points(experiment: str = 'default') → Dict[str, list]

Returns a dictionary containing all of the multi tracking points associated with the given experiment. If no experiment is given, the default experiment is assumed. The dictionary has keys "Red", "Orange", "Yellow", "Green", "Cyan", "Blue", and "Violet", The color keys map to lists containing [zyx points,frame number,series number]. The coordinates of these points are in voxels and are relative to the highest resolution level.

Parameters:

experiment – the name of the experiment from which to retrieve counting points

Returns:

a dictionary containing all of the experiment’s multi tracking zyx points, their colors, their frame numbers, and their series number

get_name() → str

Returns the string name of the project.

Returns:

the name of the project as a string

get_number_of_counting_points(experiment: str = 'default') → int

Returns the number of points associated with the given experiment.

Parameters:

experiment – the name of the experiment from which to retrieve counting points

Returns:

the number of counting points as an integer

get_number_of_measurements(experiment: str = 'default') → int

Returns the number of measurements associated with the given experiment.

Parameters:

experiment – the name of the experiment from which to retrieve measurements

Returns:

the number of measurements as an integer

get_number_of_multi_tracking_series(experiment: str = 'default') → int

Returns the number of multi-tracking series associated with the given experiment.

Parameters:

experiment – the name of the experiment from which to retrieve multi-tracking series

Returns:

the number of multi-tracking series as an integer

get_number_of_multivariate_data_points(experiment: str = 'default') → int

Returns the number of multivariate data points associated with the given experiment.

Parameters:

experiment – the name of the experiment from which to retrieve multivariate data points

Returns:

the number of multivariate data points as an integer

get_number_of_tracing_nodes(experiment: str = 'default') → int

Returns the number of tracing nodes associated with the given experiment.

Parameters:

experiment – the name of the experiment from which to retrieve tracing nodes

Returns:

the number of tracing nodes as an integer

get_number_of_tracking_points(experiment: str = 'default') → int

Returns the number of tracking points associated with the given experiment.

Parameters:

experiment – the name of the experiment from which to retrieve tracking points

Returns:

the number of tracking points as an integer

get_path_to_syg_file() → str

Returns the full path to the syg file of the current project.

Returns:

the full path to the syg file

get_resolution_map() → ndarray

Returns a list of resolution levels and the number of blocks within each. The length of the returned list is the number of resolution levels in the project. The value at each resolution level is the number of blocks that resolution level contains.

Returns:

a list of resolution levels and the number of blocks within each

get_roi_data(roi_index: int, experiment: str = 'default') → Block

Returns a given ROI of the project’s volumetric data as a Block object.

Parameters:

  • roi_index – the index of which ROI to be retreived

  • experiment – the name of the current experiment

Returns:

the volumetric data of the ROI as a Block object

get_roi_dimensions(roi_index: int, experiment: str = 'default') → ndarray

Returns the dimensions of an ROI given its index.

Parameters:

  • roi_index – the index of which roi to be retreived

  • experiment – the name of the current experiment

Returns:

the dimensions of the ROI as a numpy array [z,y,x]

get_roi_offset(roi_index: int, experiment: str = 'default') → ndarray

Returns the offset in voxels of a ROI given its index. The ROI offset is the distance from the bottom-left corner of the volume to the bottom-left corner of the ROI.

Parameters:

  • roi_index – the index of which ROI to be retreived

  • experiment – the name of the current experiment

Returns:

the offset of the ROI as a numpy array [z,y,x]

get_size(resolution_level: int) → ndarray

Returns the dimensions in voxels of the project’s volumetric data at the given resolution. The returned array has length 3, with each element describing the z-, y-, and x-dimension respectively. To get the size of the smallest resolution level of the volume, pass 0 to this function. Larger values will query higher resolution levels. The highest resolution level in a project can be found by taking len(project.get_resolution_map()) - 1.

Parameters:

resolution_level – the target resolution level as an integer

Returns:

the dimensions in voxels of the project’s volumetric data at the given resolution

get_surface_labels(surface_name: str, experiment: str = 'default') → List[str]

Returns a list of all labels currently applied on a surface.

Parameters:

  • surface_name – the name of the surface to get the labels of

  • experiment – the name of the experiment in which the labels exist

Returns:

a list containing all labels applied on the surface in the experiment

get_surface_names_and_sizes(experiment: str = 'default') → Dict[str, Tuple[int, int]]

Returns a dict of all the surface names mapping to their size. The size is represented as a tuple of two ints. The two ints are their vertices and faces respectively.

Parameters:

experiment – the name of the experiment where the surfaces exist

Returns:

a dict of surface names to vertices and faces count

get_timepoint_count() → int

Returns the integer number of timepoints or frames in the project’s volumetric data. For static volumes, this is always 1. For time-series data, it is always > 1.

Returns:

the integer number of timepoints in the project’s volumetric data

get_voxel_dimensions() → ndarray

Returns the physical dimensions of the voxels in the project’s volumetric data as a numpy array. The returned array has length 3, with each element describing the z-, y-, and x-dimension respectively. The unit associated with these dimensions can be retrieved using get_voxel_unit().

Returns:

the physical dimensions of the voxels in the project’s volumetric data

get_voxel_unit() → str

Gets a string describing the unit of the project’s voxel dimensions, e.g. "nm".

Returns:

a string describing the unit of the project’s voxel dimensions

import_mask(mask: ndarray, roi_index: int, experiment: str = 'default') → None

Imports a mask containing less than 255 labels to apply to an ROI.

Parameters:

  • mask – a numpy array containing the mask labels for an ROI [z,y,x,channel count]

  • roi_index – the index of which roi mask to be set

  • experiment – the name of the current experiment

import_meshes(list_of_OBJ_paths: List[str], experiment: str = 'default') → None

Imports a collection of OBJ files into a project. :param list_of_OBJ_paths: list of file paths, one for each OBJ file to import

import_swcs(list_of_SWC_paths: List[str], experiment: str = 'default') → None

Imports a collection of SWC files into a project. :param list_of_SWC_paths: list of file paths, one for each SWC file to import

randomize_mesh_colors(experiment: str = 'default') → None

Randomizes the colors of meshes in a project.

Parameters:

experiment – the name of the experiment where the meshes exist

remove_label_from_surface(label_name: str, surface_name: str, experiment: str = 'default') → None

Remove a label from a surface

Parameters:

  • label_name – the name of the label to remove

  • surface_name – the name of the surface to remove to label from

  • experiment – the name of the experiment in which to remove the label

rename_mesh(old_name: str, new_name: str, experiment: str = 'default') → None

Renames a mesh in the experiment.

Parameters:

  • old_name – the current name of the mesh

  • new_name – the name to rename the mesh to

  • experiment – the name of the experiment where the mesh exists

save_tracings(experiment: str = 'default', directory: str = './', base_name: str = 'output.swc') → None

Saves all of the tracings, in the SWC file format, to a directory. Read more about the SWC format here: http://research.mssm.edu/cnic/swc.html

Parameters:

  • experiment – the name of the experiment from which to retrieve counting points

  • directory – path where the tracing files will be saved

Returns:

a dictionary containing all of the experiment’s counting points, their locations, and their colors

set_citation(citation: str) → None

Set the stored citation for the project.

Parameters:

citation – the citation to store as a string

set_counting_points(counting_points: Mapping[str, ndarray], experiment: str = 'default') → None

Takes a dictionary containing all of the counting points to be associated with the given experiment. If no experiment is given, the default experiment is assumed. The dictionary should have keys "Red", "Orange", "Yellow", "Green", "Cyan", "Blue", and "Violet", which map to numpy arrays containing zyx points. The coordinates of these points should be in voxels, relative to the highest resolution level.

Parameters:

  • counting_points – a dictionary containing the location and color of each counting point

  • experiment – the name of the experiment from which to retrieve counting points

set_current_experiment(experiment: str = 'default') → None

Sets the current active experiment.

Parameters:

experiment – the name of the experiment to make active

set_distance_measurements(measurement_points: ndarray, experiment: str = 'default') → None

Takes a numpy array containing lists of points to be added to the project as measurements in the given experiment. Each list of points will define a distance measurement inside of syGlass. If no experiment is given, the default experiment is assumed.

Parameters:

  • measurement_points – a numpy array containing lists of x,y,z locations for each measurement.

  • experiment – the name of the experiment to associate measurement points with.

set_mesh_label_opacity(label: str, opacity: float, experiment: str = 'default') → None

Sets the opacity of a mesh label in the experiment.

Parameters:

  • label – the name of the label to set the opacity of

  • opacity – a float value representing opacity

  • experiment – the name of the experiment where the label exists

set_multitracking_points(multi_points: Mapping[str, list], experiment: str = 'default') → None

Takes a dictionary containing all of the multitracking points to be associated with the given experiment. If no experiment is given, the default experiment is assumed. The dictionary should have keys "Red", "Orange", "Yellow", "Green", "Cyan", "Blue", and "Violet", which map to lists containing [zyx points,frame number,series number].The coordinates of these points should be in voxels, relative to the highest resolution level.

Parameters:

  • multi_points – a dictionary containing zyx point, timepoint, series number and color of each multitracking point

  • experiment – the name of the experiment from which to retrieve multitracking points

set_sample_weight(sample_weight: float) → None

Sets the weight, in grams, of the entire imaged sample.

Parameters:

sample_weight – the weight to set the sample weight to

set_surface_color(surface_name: str, color: Tuple[int, int, int, int], experiment: str = 'default') → None

Sets the color of a surface.

Parameters:

  • surface_name – the name of the surface to set the color of

  • color – the color to set the surface represented as a 4-sized tuple where the elements range from 0-255 and follow the order r,g,b,a

  • experiment – the name of the experiment where the surface is

set_voxel_dimensions(voxel_dimensions: ndarray) → None

Sets the physical dimensions of the voxels in the project’s volumetric data. A numpy array of length 3 should be passed to this function, with each element representing the z-, y-, and x-dimension respectively.

Parameters:

voxel_dimensions – the new physical dimensions for the voxels in the project’s volumetric data

set_voxel_unit(voxel_unit: str) → None

Set the string description for the unit of the project’s voxel dimensions, e.g. "nm".

Parameters:

voxel_unit – a string description for the unit of the project’s voxel dimensions

class syglass.ProjectCreationSettings

Bases: object

Instances of this class represent configurations of project creation settings.

TODO: Document each of these attributes here. Note that if target_data_type is changed, downsample_range must be changed accordingly. See Project.get_data_type() for examples of valid data type strings.

class syglass.ProjectDataType(value)

Bases: Enum

Enum of the data types supported by syGlass. Calling get_data_type() on a Project will return one of these variants.

FLOAT = 4
HALF_FLOAT = 3
UINT16 = 1
UINT32 = 2
UINT8 = 0
syglass.create_project(reference_files: Iterable[str], destination: str, settings: ProjectCreationSettings) → Project
Parameters:

  • reference_files – one file from each series containing the volumetric image data, e.g. TIFF files

  • destination – a string path where the project should be saved

  • settings – an instance of ProjectCreationSettings configured with the desired attributes

Returns:

a Project object created from the given files

syglass.get_project(path: str) → Project

Given a string path to a valid .syg file, returns a Project object that represents that syGlass project.

Parameters:

path – the string path to the project’s .syg file

Returns:

a Project object representing the given syGlass project

syglass.is_project(path: str) → bool

Given a string path, returns True if that path points to a valid syGlass project and False otherwise.

Parameters:

path – a string path to a file

Returns:

a boolean indicating whether the path points to a valid syGlass project