syconn.reps package

Submodules

• syconn.reps.super_segmentation_dataset module

• syconn.reps.super_segmentation_object module

• syconn.reps.super_segmentation_helper module

• syconn.reps.segmentation module

• syconn.reps.segmentation_helper module

• syconn.reps.super_segmentation module

• syconn.reps.rep_helper module

syconn.reps.super_segmentation_dataset module

class syconn.reps.super_segmentation_dataset.SuperSegmentationDataset(working_dir=None, version=None, ssd_type='ssv', version_dict=None, sv_mapping=None, scaling=None, config=None, sso_caching=False, sso_locking=False, create=False, sd_lookup=None, cache_properties=None, overwrite=False)

Bases: syconn.reps.rep_helper.SegmentationBase

This class represents a set of agglomerated supervoxels, which themselves are represented by SegmentationObject.

Examples

After successfully executing syconn.exec.exec_init.run_create_neuron_ssd(), and subsequent analysis steps (see the SyConn/scripts/example_run/start.py) it is possible to load SSV properties via load_cached_data() with the following keys (the ordering of the arrays corresponds to ssv_ids):

• ‘id’: ID array, identical to ssv_ids. All other properties have the same ordering as this array, i.e. if SSV with ID 1234 has index 42 in the ‘id’-array you will find its properties at index 42 in all other cache-arrays.

• ‘bounding_box’: Bounding box of every SSV.

• ‘size’: Number voxels of each SSV.

• ‘rep_coord’: Representative coordinates for each SSV.

• ‘sv’: Supervoxel IDs for every SSV.

• ‘sample_locations’: Lists of rendering locations for each SSV. Each entry is a list (length corresponds to the number of supervoxels) of coordinate arrays for the corresponding SSV.

• ‘celltype_cnn_e3’: Celltype classifications based on the elektronn3 CMN.

• ‘celltype_cnn_e3_probas’: Celltype logits for the different types as an array of shape (M, C; M: Number of predicted random multi-view sets, C: Number of classes). In the example run there are currently 9 predicted classes: STN=0, DA=1, MSN=2, LMAN=3, HVC=4, GP=5, FS=6, TAN=7, INT=8.

• ‘syn_ssv’: Synapse IDs assigned to each SSV.

• ‘syn_sign_ratio’: Area-weighted atio of symmetric synapses, see syn_sign_ratio().

• ‘sj’: Synaptic junction object IDs which were mapped to each SSV. These are used for view rendering and also to generate the ‘syn_ssv’ objects in combination with contact sites (see corresponding section in the documentation).

• ‘mapping_sj_ids’: Synaptic junction objects which overlap with the respective SSVs.

• ‘mapping_sj_ratios’: Overlap ratio of the synaptic junctions.

• ‘vc’: Vesicle clouds mapped to each SSV.

• ‘mapping_vc_ids’: Vesicle cloud objects which overlap with the respective SSVs.

• ‘mapping_vc_ratios’: Overlap ratio of the vesicle clouds.

• ‘mi’: Mitochondria mapped to each SSV.

• ‘mapping_mi_ids’: Mitochondria objects which overlap with the respective SSVs.

• ‘mapping_mi_ratios’: Overlap ratio of the mitochondria.

The following lines initialize the SuperSegmentationDataset of the example run and explore some of the existing attributes:

import numpy as np
from syconn.reps.super_segmentation import *
ssd = SuperSegmentationDataset(working_dir='~/SyConn/example_cube1/')
n_synapses = [len(ssv.syn_ssv) for ssv in ssd.ssvs]
path_length = [ssv.total_edge_length() for ssv in ssd.ssvs]  # in nanometers
syn_densities = np.array(n_synapses) / np.array(path_length)
print(np.mean(syn_densities), np.std(syn_densities))

We can make use of the cached arrays to obtain the total number of synapses per cell type as follows:

celltypes = ssd.load_numpy_data('celltype_cnn_e3')
n_synapses = np.array([len(el) for el in ssd.load_numpy_data('syn_ssv')])
n_synapes_per_type = {ct: np.sum(n_synapses[celltypes==ct]) for ct in range(np.max(celltypes)}
print(n_synapes_per_type)

sso_caching

WIP, enables caching mechanisms in SuperSegmentationObjects returned via get_super_segmentation_object

sso_locking

If True, locking is enabled for SSV files.

apply_mergelist(sv_mapping)

See assemble_from_mergelist().

Parameters

sv_mapping (Union[Dict[int, int], str]) – Supervoxel agglomeration.

property config: syconn.handler.config.DynConfig

Config. object which contains all dataset-sepcific parameters.

Return type

DynConfig

create_mapping_lookup_reverse()

Create data structure for efficient look-ups from supervoxel ID to cell ID, see syconn.backend.storage.BinarySearchStore.

enable_property_cache(property_keys)

Add properties to cache.

Parameters

property_keys (List[str]) – Property keys. Numpy cache arrays must exist.

get_segmentationdataset(obj_type)

Return type

SegmentationDataset

get_super_segmentation_object(obj_id, new_mapping=False, caching=None, create=False)

Factory method for `bj_id might be a single ID or list of IDs.

Parameters

• obj_id (Union[int, Iterable[int]]) – ID of the super-supervoxel which should be instantiated. Can also be an iterable.

• new_mapping (bool) – If True, the returned SuperSegmentationObject object will be built on the supervoxel agglomeration stored in mapping_dict.

• caching (Optional[bool]) – Enable caching of various attributes.

• create (bool) – If True, creates the directory of the super-supervoxel inside the folder structure of this dataset.

Notes

• Set the default value of caching to False, PS 20Feb2019

Return type

Union[SuperSegmentationObject, List[SuperSegmentationObject]]

Returns

SuperSegmentationObject(s) corresponding to the given obj_id (int or Iterable[int]).

load_mapping_dict()

Load the mapping dictionary from the .pkl file.

load_numpy_data(prop_name, allow_nonexisting=True, suppress_warning=False)

Parameters

• prop_name (str) – Identifier for requested cache array. Ordering of the array is the same as ssv_ids.

• allow_nonexisting (bool) – If False, will fail for missing numpy files.

• suppress_warning (bool) – Do not print a warning if property does not exist.

Return type

Optional[ndarray]

Returns

Numpy array of cached property.

load_version_dict()

Load the version dictionary from the .pkl file.

property mapping_dict: Dict[int, numpy.ndarray]

Dictionary which contains the supervoxel IDs for every super-supervoxel.

Return type

Dict[int, ndarray]

property mapping_dict_exists: bool

Checks if the mapping dictionary exists (uper-supervoxel ID to sueprvoxel IDs).

Return type

bool

property mapping_dict_path: str

Path to the mapping dictionary pkl file.

Return type

str

property mapping_lookup_reverse: syconn.backend.storage.BinarySearchStore

Return type

BinarySearchStore

property mapping_lookup_reverse_path: str

Path to data structure that stores the lookup from supervoxel ID to cell ID.

Return type

str

property path: str

Full path to dataset directory.

Return type

str

save_dataset_deep(extract_only=False, attr_keys=(), n_jobs=None, nb_cpus=None, use_batchjob=True, new_mapping=True)

Saves attributes of all SSVs within the given SSD and computes properties like size and representative coordinate. The order of ssv_ids may change each run. Populates the sv_ids attribute of all SSVs. See save_dataset_deep().

Parameters

• extract_only (bool) – Only cache attributes attr_keys from attribute dict. This will add suffix ‘_sel’ to the numpy cache array file names (-> updates will not apply to the load_cached_data() method).

• attr_keys (Iterable[str]) – Attributes to cache, only used if extract_only=True.

• n_jobs (Optional[int]) – Currently requires any string to enable batch job system, will be replaced by a global flag soon.

• nb_cpus (Optional[int]) – CPUs per worker.

• use_batchjob – Use batchjob processing instead of local multiprocessing.

• new_mapping (bool) – Whether to apply new mapping (see mapping_dict()).

Returns:

save_dataset_shallow(overwrite=False)

Saves version_dict, mapping_dict.

Parameters

overwrite (bool) – Do not replace existing files.

save_mapping_dict()

Save the mapping dictionary to a .pkl file.

save_version_dict()

Save the version dictionary to a .pkl file.

property scaling: numpy.ndarray

Voxel size in nanometers (XYZ). Default is taken from the config.yml file and accessible via config.

Return type

ndarray

property ssv_ids: numpy.ndarray

Super-supervoxel IDs which are part of this SuperSegmentationDataset object.

Return type

ndarray

property ssvs: Generator[syconn.reps.super_segmentation_object.SuperSegmentationObject, None, None]

Generator of SuperSegmentationObject objects which are part of this SuperSegmentationDataset object.

Yields

SuperSegmentationObject

Return type

Generator[SuperSegmentationObject, None, None]

store_path_densities_seg_objs(obj_type, compartments_of_interest=None, ax_pred_key='axoness_avg10000', overwrite=False, nb_cpus=None)

Stores path densities of all the cells in this dataset. Same ordering as ssv_ids.

Parameters

• obj_type (str) – Key to any available sub-cellular structure.

• compartments_of_interest (Optional[list]) – Which compartments to take into account for calculation. axon: 1, dendrite: 0, soma: 2

• ax_pred_key (Optional[str]) – Key of compartment prediction stored in skeleton, only used if compartments_of_interest was set. Defaults to ‘axoness_avg10000’.

• overwrite (Optional[bool]) – Overwrite the <obj_type>_path_densities.npy file. Defaults to False.

• nb_cpus (Optional[int]) – CPUs per worker. Defaults to None.

store_total_edge_lengths(ax_pred_key='axoness_avg10000', overwrite=False, nb_cpus=None)

Stores total edge lengths of all the cells in this dataset in nanometers. Same ordering as ssv_ids.

Parameters

• ax_pred_key (Optional[str]) – Key of compartment prediction stored in skeleton

• overwrite (Optional[bool]) – Overwrite the total_edge_lengths.npy file. Defaults to False.

• nb_cpus (Optional[int]) – CPUs per worker. Defaults to None.

sv2ssv_ids(ids, nb_cpus=1)

Use mapping_lookup_reverse to query the cell ID for a given array of supervoxel IDs. IDs that are not in sv_ids will not be added to the output dict.

Parameters

• ids (ndarray) – Unique IDs to find the corresponding cell ID.

• nb_cpus –

Return type

Dict[int, int]

Returns

Dictionary with supervoxel ID as key and cell ID as value.

property sv_ids: numpy.ndarray

Flat array of supervoxel IDs which are part of the cells (ssv_ids) in this SuperSegmentationDataset object.

Return type

ndarray

property type: str

The type of the underlying supervoxel objects. See SuperSegmentationObject.

Return type

str

property version: str

Indicates the version of the dataset. The version is part of the dataset’s folder name.

Return type

str

property version_dict_exists: bool

Checks whether the version dictionary exists at version_dict_path.

Return type

bool

property version_dict_path: str

Path to version dictionary file.

Return type

str

property working_dir: str

Working directory.

Return type

str

syconn.reps.super_segmentation_dataset.copy_ssvs2new_SSD_simple(ssvs, new_version, target_wd=None, n_jobs=1, safe=True)

Creates a new SSD specified with new_version and a copy of the given SSVs. Usually used for generating distinct GT SSDs. Based on the common super-supervoxel dataset (as specified in the config.yml file, default:

version=ssv_0).

Parameters

• ssvs (List[SuperSegmentationObject]) – Source SuperSegmentationObjects taken from default SSD in working directory.

• new_version (str) – Version of the new SSV SuperSegmentationDataset where SSVs will be copied to.

• target_wd (Optional[str]) – Path to working directory. If None, the one set in gloabal_params is used.

• n_jobs (int) – Number of jobs used.

• safe (bool) – If True, will not overwrite existing data.

Returns:

syconn.reps.super_segmentation_dataset.exctract_ssv_morphology_embedding(args)

Helper function to infer local morphology embeddings of a cell reconstruction. See predict_views_embedding() for details.

Parameters

*args – ssv_obj_ids: Cell reconstruction IDs, args[1:4] used to initialize the SuperSegmentationDataset, pred_key_appendix: addition to the default key for storing the embeddings.

syconn.reps.super_segmentation_dataset.filter_ssd_by_total_pathlength(ssd, min_edge_length)

Filter cells concurrently.

Parameters

• ssd (SuperSegmentationDataset) – Cell reconstruction dataset.

• min_edge_length (float) – Minim skeleton edge length in µm.

Return type

ndarray

Returns

Array of SuperSegmentationObject that have a total skeleton edge length > min_edge_length.

syconn.reps.super_segmentation_dataset.get_path_density_seg_obj(args)

Retrieves the path density of sub-cellular structures of ssvs.

Parameters

*args – obj_type: Key to any available sub-cellular structure, args[0], ssv_ids: Cell reconstructin ids, args[1], compartments_of_interest: Which compartments to take into account for calculation, args[2]. axon: 1, dendrite: 0, soma: 2, en-passant bouton: 3, terminal bouton: 4, ax_pred_key: Key of compartment prediction stored in skeleton, only used if compartments_of_interest was set. .

Return type

ndarray

Returns

Average volume per path length (um^3 / um) for the ssvs

syconn.reps.super_segmentation_dataset.get_total_edge_lengths(ssv_ids, ax_pred_key)

Retrieves the total edge lengths of the super-supervoxels’ skeleton in nanometers. The compartments used to compute the edge lengths are axon: 1, axon terminals: 3, 4, dendrite: 0, soma: 2.

Parameters

• ids (ssv) –

• ax_pred_key (str) – Key of compartment prediction stored in skeleton

Return type

ndarray

Returns

Sum of all edge lengths (L2 norm) in skeleton.

syconn.reps.super_segmentation_dataset.load_voxels_downsampled(sso, downsampling=(2, 2, 1), nb_threads=10)

syconn.reps.super_segmentation_dataset.save_dataset_deep(ssd, extract_only=False, attr_keys=(), n_jobs=None, nb_cpus=None, use_batchjob=True, new_mapping=True, overwrite=False)

Saves attributes of all SSVs within the given SSD and computes properties like size and representative coordinate. id.npy order may change after repeated runs.

Parameters

• ssd (SuperSegmentationDataset) – SuperSegmentationDataset

• extract_only (bool) – Only cache attributes (see`attr_keys` from attribute dict. This will add a suffix _sel to the numpy cache array file names (-> updates will not apply to the load_cached_data method).

• attr_keys (Iterable) – Attributes to cache, only used if extract_only=True

• n_jobs (Optional[int]) – Currently requires any string to enable batch job system, will be replaced by a global flag soon.

• nb_cpus (Optional[int]) – CPUs per worker.

• use_batchjob – Use batchjob processing instead of local multiprocessing.

• new_mapping (bool) – Whether to apply new mapping (see ssd.mapping_dict).If True, Will use ssd.load_mapping_dict to populate sv_ids attribute of all SuperSegmentationObject.

• overwrite – Remove existing SSD folder, if False and a folder already exists it raises FileExistsError.

syconn.reps.super_segmentation_object module

class syconn.reps.super_segmentation_object.SuperSegmentationObject(ssv_id, version=None, version_dict=None, working_dir=None, create=False, sv_ids=None, scaling=None, object_caching=True, voxel_caching=True, mesh_caching=True, view_caching=False, config=None, nb_cpus=1, enable_locking=False, enable_locking_so=False, ssd_type=None, ssd=None, sv_graph=None)

Bases: syconn.reps.rep_helper.SegmentationBase

Class instances represent individual neuron reconstructions, defined by a list of agglomerated supervoxels (see SegmentationObject).

Examples

This class can be used to create a cell reconstruction object after successful executing run_create_neuron_ssd() as follows:

from syconn import global_params
# import SuperSegmentationObject and SuperSegmentationDataset
from syconn.reps.super_segmentation import *
# set the current working directory SyConn-wide
global_params.wd = '~/SyConn/example_cube1/'

ssd = SuperSegmentationDataset()
cell_reconstr_ids = ssd.ssv_ids
# call constructor explicitly ...
cell = SuperSegmentationObject(cell_reconstr_ids[0])
# ... or via the SuperSegmentationDataset - both contain the same data
cell = ssd.get_super_segmentation_object(cell_reconstr_ids[0])
# inspect existing attributes
cell.load_attr_dict()
print(cell.attr_dict.keys())

To cache SegmentationObject attributes use the cache_properties argument during initialization of the SegmentationDataset and pass it on to the SuperSegmentationDataset instantiation:

sd_mi = SegmentationDataset(obj_type=’mi’, cache_properties=[‘rep_coord’]) ssd = SuperSegmentationDataset(sd_lookup=dict(mi=sd_mi)) ssv = ssd.get_super_segmentation_object(ssd.ssv_ids[0]) # SegmentationObject from mis don’t require loading rep_coord # from its storage file. for mi in ssv.mis:

rc = mi.rep_coord # normally this requires to load the attribute dict storage file.

Subsequent analysis steps (see the SyConn/scripts/example_run/start.py) augment the cell reconstruction with more properties:

# to iterate over all cell reconstructions use the generator:
for cell in ssd.ssvs:
    # e.g. collect some analysis results
    cell.load_attr_dict()
    n_synapses = len(cell.syn_ssv)
    celltype = cell.attr_dict["celltype_cnn_e3"]
    ...
    # write out cell mesh
    cell.mesh2kzip('~/cell{}_mesh.k.zip'.format(cell.id))
    # write out cell mesh and meshes of all existing cell organelles
    cell.meshes2kzip('~/cell{}_meshes.k.zip'.format(cell.id))
    # color the cell mesh according to a semantic prediction
    cell.semseg2mesh(semseg_key='spiness', dest_path='~/cell{}_spines.k.zip'.format(cell.id))

See also SyConn/docs/api.md (WIP).

attr_dict

Attribute dictionary which serves as a general-purpose container. Accessed via the AttributeDict interface. After successfully executing syconn.exec.exec_init.run_create_neuron_ssd() and subsequent analysis steps (see the SyConn/scripts/example_run/start.py) the following keys are present in attr_dict:

• ‘id’: ID array, identical to ssv_ids. All other properties have the same ordering as this array, i.e. if SSV with ID 1234 has index 42 in the ‘id’-array you will find its properties at index 42 in all other cache-arrays.

• ‘bounding_box’: Bounding box of every SSV.

• ‘size’: Number voxels of each SSV.

• ‘rep_coord’: Representative coordinates for each SSV.

• ‘sv’: Supervoxel IDs for every SSV.

• ‘sample_locations’: Lists of rendering locations for each SSV. Each entry is a list (length corresponds to the number of supervoxels) of coordinate arrays for the corresponding SSV.

• ‘celltype_cnn_e3’: Celltype classifications based on the elektronn3 CMN.

• ‘celltype_cnn_e3_probas’: Celltype logits for the different types as an array of shape (M, C; M: Number of predicted random multi-view sets, C: Number of classes). In the example run there are currently 9 predicted classes: STN=0, DA=1, MSN=2, LMAN=3, HVC=4, GP=5, FS=6, TAN=7, INT=8.

• ‘syn_ssv’: Synapse IDs assigned to each SSV.

• ‘syn_sign_ratio’: Area-weighted atio of symmetric synapses, see syn_sign_ratio().

• ‘sj’: Synaptic junction object IDs which were mapped to each SSV. These are used for view rendering and also to generate the ‘syn_ssv’ objects in combination with contact sites (see corresponding section in the documentation).

• ‘mapping_sj_ids’: Synaptic junction objects which overlap with the respective SSVs.

• ‘mapping_sj_ratios’: Overlap ratio of the synaptic junctions.

• ‘vc’: Vesicle clouds mapped to each SSV.

• ‘mapping_vc_ids’: Vesicle cloud objects which overlap with the respective SSVs.

• ‘mapping_vc_ratios’: Overlap ratio of the vesicle clouds.

• ‘mi’: Mitochondria mapped to each SSV.

• ‘mapping_mi_ids’: Mitochondria objects which overlap with the respective SSVs.

• ‘mapping_mi_ratios’: Overlap ratio of the mitochondria.

skeleton

The skeleton representation of this super-supervoxel. Keys which are currently in use:

• ‘nodes’: Array of the node coordinates (in nanometers).

• ‘edges’: Edges between nodes.

• ‘diameters’: Estimated cell diameter at every node.

• various node properties, e.g. ‘axoness’ and ‘axoness_avg10000’. Check the

available keys sso.skeleton.keys() of an initialized SuperSegmentationObject object sso after loading the skeleton (sso.load_skeleton()).

enable_locking_so

Locking flag for all syconn.reps.segmentation.SegmentationObject assigned to this object (e.g. SV, mitochondria, vesicle clouds, …)

nb_cpus

Number of cpus for parallel jobs. will only be used in some processing steps.

view_dict

A dictionary for caching 2D projection views. Those are stored as a numpy array of shape (M, N, CH, x, y). M: Length of sample_locations and has the same ordering; N: Number of views per location; CH: Number of channels (1 for glia prediction containing only the cell shape and 4 for neuron analysis containing cell and cell organelle shapes. Stored at view_path and accessed via the CompressedStorage interface.

version_dict

A dictionary which contains the versions of other dataset types which share the same working directory. Defaults to the Versions entry in the config.yml file.

aggregate_segmentation_object_mappings(obj_types, save=False)

Aggregates mapping information of cellular organelles from the SSV’s supervoxels. After this step, apply_mapping_decision() can be called to apply final assignments.

Examples

A mitochondrion can extend over multiple supervoxels, so it will overlap with all of them partially. Here, the overlap information of all supervoxels assigned to this SSV will be aggregated.

Parameters

• obj_types (List[str]) – Cell organelles types to process.

• save (bool) – Save :yp:attr:`~attribute_dict` at the end.

apply_mapping_decision(obj_type, correct_for_background=True, lower_ratio=None, upper_ratio=None, sizethreshold=None, save=True)

Applies mapping decision of cellular organelles to this SSV object. A SegmentationObject in question is assigned to this SuperSegmentationObject if they share the highest overlap. For more details see SyConn/docs/object_mapping.md. Default parameters for the mapping will be taken from the config.yml file.

Parameters

• obj_type (str) – Type of SegmentationObject which are to be mapped.

• correct_for_background (bool) – Ignore background ID during mapping

• lower_ratio (Optional[float]) – Minimum overlap s.t. objects are mapped.

• upper_ratio (Optional[float]) – Maximum ratio s.t. objects are mapped.

• sizethreshold (Optional[float]) – Minimum voxel size of an object, objects below will be ignored.

• save (bool) – If True, attr_dict will be saved.

Returns:

property attr_dict_exists: bool

Checks if a attribute dictionary file exists at attr_dict_path.

Return type

bool

Returns

True if the attribute dictionary file exists.

property attr_dict_path: str

Path to the attribute storage. attr_dict can be loaded from here.

Return type

str

attr_exists(attr_key)

Checks if an attribute exists for this SSV object.

Parameters

attr_key (str) – Attribute key.

Return type

bool

Returns

True if the key exists in attr_dict.

attr_for_coords(coords, attr_keys, radius_nm=None, k=1)

TODO: move to super_segmentation_helper.py Query skeleton node attributes at given coordinates. Supports any attribute stored in self.skeleton. If radius_nm is given, will assign majority attribute value.

Parameters

• coords (np.array) – Voxel coordinates, unscaled! [N, 3]

• radius_nm (Optional[float]) – If None, will only use attribute of nearest node, otherwise majority attribute value is used.

• attr_keys (List[str]) – Attribute identifier

• k (int) – Number of nearest neighbors, only if radius_nm is None.

Returns

Same length as coords. For every coordinate in coords returns the majority label within radius_nm or [-1] if Key does not exist.

Return type

list

average_node_axoness_views(**kwargs)

Apply a sliding window averaging along the axon predictions stored at the nodes of the skeleton. See _average_node_axoness_views() for details. Will call save_skeleton().

Parameters

**kwargs – Key word arguments used in _average_node_axoness_views().

axoness2mesh(dest_path, k=1, pred_key_appendix='')

Deprecated. See semseg2mesh(). Write the per-location CMN axon predictions (img2scalar) to a kzip file.

Parameters

• dest_path – Path to the kzip file.

• k – Number of nearest neighbors used for the majority vote.

• pred_key_appendix – Key to load specific predictions.

axoness_for_coords(coords, radius_nm=4000, pred_type='axoness')

Dies not need to be axoness, it supports any attribut stored in self.skeleton.

Parameters

• coords – np.array Voxel coordinates, unscaled! [N, 3]

• radius_nm – float

• pred_type – str

Returns: np.array

Same length as coords. For every coordinate in coords returns the majority label within radius_nm

property bounding_box: List[numpy.ndarray]

Return type

List[ndarray]

calculate_bounding_box()

Calculates bounding_box (and size).

calculate_size()

Calculates size.

calculate_skeleton(force=False, **kwargs)

Merges existing supervoxel skeletons (allow_ssv_skel_gen=False) or calculates them from scratch using create_sso_skeletons_wrapper() otherwise (requires allow_ssv_skel_gen=True). Skeleton will be saved at skeleton_path.

Parameters

force (bool) – Skips load_skeleton() if force=True.

celltype(key=None)

Returns the cell type classification result. Default: CMN model, if key is specified returns the corresponding value loaded by lookup_in_attribute_dict(). :type key: Optional[str] :param key: Key where classification result is stored.

Return type

int

Returns

Cell type classification.

certainty_celltype(pred_key=None)

_probas Certainty estimate of the celltype prediction:

1. If is_logit is True, Generate pseudo-probabilities from the input using softmax.

2. Sum the evidence per class and (re-)normalize.

3. Compute the entropy, scale it with the maximum entropy (equal probabilities) and subtract it from 1.

Notes

See certainty_estimate()

Parameters

pred_key (Optional[str]) – Key of classification results (one C-class probability vector for every multi-view sample). pred_key + '_probas' must exist in attr_dict.

Return type

float

Returns

Certainty measure based on the entropy of the cell type logits.

clear_cache()

Clears the following, cached data:

• voxels

• voxels_xy_downsampled

• sample_locations

• _objects

• _views

• skeleton

• _meshes

cnn_axoness2skel(**kwargs)

property compartment_meshes: dict

Compartment mesh storage.

Return type

dict

Returns

A dictionary which contains the meshes of each compartment.

property config: syconn.handler.config.DynConfig

The configuration object which contain all dataset-specific parameters. See DynConfig.

Return type

DynConfig

Returns

The configuration object.

copy2dir(dest_dir, safe=True)

Copies the content at ssv_dir to another directory.

Examples

To copy the data of this SSV object (ssv_orig) to another yet not existing SSV (ssv_target). call ssv_orig.copy2dir(ssv_target.ssv_dir). All files contained in the directory py:attr:~ssv_dir of ssv_orig will be copied to ssv_target.ssv_dir.

Parameters

• dest_dir (str) – Destination directory where all files contained in py:attr:~ssv_dir will be copied to.

• safe (bool) – If True, will not overwrite existing data.

property dense_kzip_ids: Dict[str, int]

?

Return type

Dict[str, int]

property edgelist_path: str

Identifier of SSV graph

Return type

str

export2kzip(dest_path, attr_keys=('skeleton',), rag=None, sv_color=None, individual_sv_meshes=True, object_meshes=None, synssv_instead_sj=True)

Writes the SSO to a KNOSSOS loadable kzip including the mergelist (mergelist2kzip()), its meshes (meshes2kzip()), data set specific information and additional data (attr_keys). 0 to 255. Saved SSO can also be re-loaded as an SSO instance via init_sso_from_kzip().

Notes

Will not invoke load_attr_dict().

Parameters

• dest_path (str) – Path to destination kzip file.

• attr_keys (Iterable[str]) – Currently allowed: ‘sample_locations’, ‘skeleton’, ‘attr_dict’, ‘rag’.

• rag (Optional[Graph]) – SV graph of SSV with uint nodes.

• sv_color (Optional[ndarray]) – Cell supervoxel colors. Array with RGBA (0…255) values or None to use default values (see mesh2kzip()).

• individual_sv_meshes (bool) – Export meshes of cell supervoxels individually.

• object_meshes (Optional[tuple]) – Defaults to subcellular organelles defined in config.yml (‘process_cell_organelles’).

• synssv_instead_sj (bool) – If True, will use ‘syn_ssv’ objects instead of ‘sj’.

get_seg_dataset(obj_type)

Factory method for SegmentationDataset of type obj_type.

Parameters

obj_type (str) – Type of requested SegmentationDataset.

Return type

SegmentationDataset

Returns

The SegmentationDataset of type obj_type sharing the same working directory as this SSV object.

get_seg_obj(obj_type, obj_id)

Factory method for SegmentationObject of type obj_type.

Parameters

• obj_type (str) – Type of requested SegmentationObject.

• obj_id (int) – ID of the requested object.

Return type

SegmentationObject

Returns

The SegmentationObject of type obj_type sharing the same working directory as this SSV object.

get_seg_objects(obj_type)

Factory method for SegmentationObject`s of type `obj_type.

Parameters

obj_type (str) – Type of requested :class:`~syconn.reps.segmentation.SegmentationObject`s.

Return type

List[SegmentationObject]

Returns

The SegmentationObject`s of type `obj_type sharing the same working directory as this SSV object.

get_spine_compartments(semseg_key='spiness', k=1, min_spine_cc_size=None, dest_folder=None)

Retrieve connected components of vertex spine predictions.

Parameters

• semseg_key (str) – Key of the used semantic segmentation.

• k (int) – Number of nearest neighbors for majority label vote (smoothing of classification results).

• min_spine_cc_size (Optional[int]) – Minimum number of vertices to consider a connected component a valid object.

• dest_folder (Optional[str]) – Default is None, else provide a path (str) to a folder. The mean location and size of the head and neck connected components will be stored as numpy array file (npy).

Return type

Tuple[ndarray, ndarray, ndarray, ndarray]

Returns

Neck locations, neck sizes, head locations, head sizes. Location and size arrays have the same ordering.

gliapred2mergelist(dest_path=None, thresh=None, pred_key_appendix='')

gliapred2mesh(dest_path=None, thresh=None, pred_key_appendix='')

gliaprobas2mesh(dest_path=None, pred_key_appendix='')

gliasplit(recompute=False, thresh=None, verbose=False, pred_key_appendix='')

gliasplit2mesh(dest_path=None, pred_key_appendix='')

Parameters

• dest_path –

• pred_key_appendix –

Returns:

property id: int

Default value is the smalles SV ID which is part of this cell reconstruction.

Return type

int

Returns

Globally unique identifier of this object.

property identifier: str

Identifier used to create the folder name of the :class: ~syconn.reps.super_segmentation_dataset.SuperSegmentationDataset this object belongs to.

Return type

str

label_dict(data_type='vertex')

Dictionary which stores various predictions. Currently used keys:

• ‘vertex’: Labels associated with the mesh vertices. The ordering is the same as the vertex order in self.mesh[1].

Uses the CompressedStorage interface.

Parameters

data_type – Key for the stored labels.

Return type

CompressedStorage

Returns

The stored array.

load_attr_dict()

Load the attribute dictionary of this SSV object stored at ssv_dir.

Return type

int

load_mesh(mesh_type)

Load mesh of a specific type, e.g. ‘mi’, ‘sv’ (cell supervoxel), ‘sj’ (connected components of the original synaptic junction predictions), ‘syn_ssv’ (overlap of ‘sj’ with cell contact sites), ‘syn_ssv_sym’ and ‘syn_ssv_asym’ (only if syn-type predictions are available).

Parameters

mesh_type – Type of SegmentationObject used for mesh retrieval.

Returns

indices, vertices, normals

Return type

Three flat arrays

Raises

ValueError: If mesh_type does not exist in _meshes.

load_skeleton()

Loads skeleton and will compute it if it does not exist yet (requires allow_ssv_skel_gen=True).

Return type

bool

Returns

True if successfully loaded/generated skeleton, else False.

load_so_attributes(obj_type, attr_keys)

Collect attributes from SegmentationObject of type obj_type. The attribute value ordering for each key is the same as svs.

Parameters

• obj_type (str) – Type of SegmentationObject.

• attr_keys (List[str]) – Keys of desired properties. Must exist for the requested obj_type.

Returns

Attribute values for each key in attr_keys.

load_sv_edgelist()

Load the edges within the supervoxel graph.

Return type

List[Tuple[int, int]]

Returns

Edge list representing the supervoxel graph.

load_sv_graph()

Load the supervoxel graph (node objects will be of type SegmentationObject) of this SSV object.

It is generated from the supervoxel ID graph stored in _sv_graph or the edge list stored at edgelist_path.

Return type

Graph

Returns

The supervoxel graph with SegmentationObject nodes.

load_views(view_key=None, woglia=True, raw_only=False, force_reload=False, nb_cpus=None, ignore_missing=False, index_views=False)

Load views which are stored in view_dict or if not present attempts to retrieve data from view_path given the key view_key, i.e. this operates on SSV level. If the given key does not exist on SuperSegmentationObject level or is None, attempts to load the views from the underlying :class:`~syconn.reps.segmentation.SegmentationObject`s.

Parameters

• view_key (Optional[str]) – The key used for the look-up.

• woglia (bool) – If True, will load the views render from the glia-free agglomeration.

• raw_only (bool) – If True, will only return the cell shape channel in the views.

• force_reload (bool) – If True will force reloading the SV views.

• nb_cpus (Optional[int]) – Number of CPUs.

• ignore_missing (bool) – If True, it will not raise KeyError if SV does not exist.

• index_views (bool) – Views which contain the indices of the vertices at the respective pixels. Used as look-up to map the predicted semantic labels onto the mesh vertices.

Return type

ndarray

Returns

Concatenated views for each SV in self.svs with shape [N_LOCS, N_CH, N_VIEWS, X, Y].

load_voxels_downsampled(downsampling=(2, 2, 1), nb_threads=10)

Load all voxels of this SSV object.

Parameters

• downsampling (tuple) – The downsampling of the returned voxels.

• nb_threads (int) – Number of threads.

Return type

ndarray

Returns

List of downsampled voxel coordinates.

lookup_in_attribute_dict(attr_key)

Returns the value to attr_key stored in attr_dict or None if the key is not existent.

Parameters

attr_key (str) – Attribute key.

Return type

Optional[Any]

Returns

Value to the key attr_key.

majority_vote(prop_key, max_dist)

Smooths (average using sliding window of 2 times max_dist and majority vote) property prediction in annotation.

Parameters

• prop_key (str) – Property to average.

• max_dist (float) – Maximum distance (in nm) for sliding window used in majority voting.

Returns:

Return type

ndarray

mergelist2kzip(dest_path=None)

property mesh: Optional[Union[Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray], List[numpy.ndarray], Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]]]

Mesh of all cell supervoxels.

Return type

Union[Tuple[ndarray, ndarray, ndarray], List[ndarray], Tuple[ndarray, ndarray, ndarray, ndarray], None]

mesh2file(dest_path=None, center=None, color=None, scale=None, obj_type='sv')

Writes mesh to file (e.g. .ply, .stl, .obj) via the ‘openmesh’ library. If possible, writes it as binary.

Parameters

• dest_path – str

• center – np.array scaled center coordinates (in nm).

• color – np.array Either single color (1D; will be applied to all vertices) or per-vertex color array (2D).

• scale – float Multiplies vertex locations after centering.

• obj_type – str Defines the object type which is used for loading the mesh via load_mesh().

mesh2kzip(dest_path=None, obj_type='sv', ext_color=None, **kwargs)

Writes mesh of SSV to kzip as .ply file.

Parameters

• dest_path (Optional[str]) –

• obj_type (str) – str ‘sv’ for cell surface, ‘mi’: mitochondria, ‘vc’: vesicle clouds, ‘sj’: synaptic junctions

• ext_color (Optional[ndarray]) – np.array of scalar If scalar, it has to be an integer between 0 and 255. If array, it has to be of type uint/int and of shape (N, 4) while N is the number of vertices of the SSV cell surface mesh: N = len(self.mesh[1].reshape((-1, 3)))

Returns:

property mesh_caching: bool

If True, mesh data is cached.

Return type

bool

property mesh_dc_path: str

Identifier of mesh storage

Return type

str

mesh_exists(obj_type)

Checks if the mesh of SegmentationObject`s of type `obj_type exists in the MeshStorage located at mesh_dc_path.

Parameters

obj_type (str) – Type of requested :class:`~syconn.reps.segmentation.SegmentationObject`s.

Return type

bool

Returns

True if the mesh exists.

meshes2kzip(dest_path=None, sv_color=None, synssv_instead_sj=True, object_types=None, **kwargs)

Writes SV, mito, vesicle cloud and synaptic junction meshes to k.zip.

Parameters

• dest_path (Optional[str]) – str

• sv_color (Optional[ndarray]) – np.array array with RGBA values or None to use default values (see mesh2kzip()).

• synssv_instead_sj (bool) – bool

• object_types (Optional[List[str]]) – List[str] Objects to export.

Returns:

property mi_ids: numpy.ndarray

All mitochondria (mi) supervoxel IDs which are assigned to this cell reconstruction.

Return type

ndarray

property mi_mesh: Optional[Union[Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray], List[numpy.ndarray], Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]]]

Mesh of all mitochondria (mi) supervoxels.

Return type

Union[Tuple[ndarray, ndarray, ndarray], List[ndarray], Tuple[ndarray, ndarray, ndarray, ndarray], None]

property mis: List[syconn.reps.segmentation.SegmentationObject]

All mitochondria (mi) SegmentationObjects objects which are assigned to this cell reconstruction.

Return type

List[SegmentationObject]

morphembed2mesh(dest_path, pred_key='latent_morph', whiten=True)

Write morphology embedding as RGB to k.zip file.

Parameters

• dest_path –

• pred_key –

• whiten –

Returns:

property object_caching: bool

If True, :class:`~syconn.reps.segmentation.SegmentationObject`s which are part of this cell reconstruction are cached.

Return type

bool

property objects_dense_kzip_path: str

Identifier of cell organell overlays

Return type

str

partition_cc(max_nb_sv=None, lo_first_n=None)

Splits the supervoxel graph of this SSV into subgraphs. Default values are generated from config.

Parameters

• max_nb_sv (Optional[int]) – Number of supervoxels per sub-graph. This defines the sub-graph context.

• lo_first_n (Optional[int]) – Do not use first n traversed nodes for new bfs traversals. This allows to partition the original supervoxel graph of size N into N//lo_first_n sub-graphs.

Returns:

Return type

List[List[Any]]

path_density_seg_obj(obj_type, compartments_of_interest=None, ax_pred_key='axoness_avg10000')

Parameters

• obj_type (str) – Key to any available sub-cellular structure.

• compartments_of_interest (Optional[List[int]]) – Which compartments to take into account for calculation. axon: 1, dendrite: 0, soma: 2

• ax_pred_key (str) – Key of compartment prediction stored in skeleton, only used if compartments_of_interest was set.

Return type

float

Returns

Average volume per path length (um^3 / um).

pklskel2kzip()

predict_cell_morphology_pts(**kwargs)

Store local cell morphology with key ‘latent_morph’ (+ pred_key_appendix) in the SSV skeleton.

Parameters

**kwargs –

predict_celltype_multiview(model, pred_key_appendix, model_tnet=None, view_props=None, onthefly_views=False, overwrite=True, model_props=None, verbose=False, save_to_attr_dict=True)

Infer celltype classification via model (stored as celltype_cnn_e3 and celltype_cnn_e3_probas in the attr_dict) and an optional cell morphology embedding via model_tnet (stored as latent_morph_ct).

Parameters

• model – nn.Module

• pred_key_appendix – str

• model_tnet – Optional[nn.Module]

• view_props – Optional[dict] Dictionary which contains view properties. If None, default defined in config will be used.

• onthefly_views – bool

• overwrite –

• model_props – Model properties. See config.yml for an example.

• verbose (bool) –

• save_to_attr_dict (bool) – Save prediction in attr_dict.

predict_semseg(m, semseg_key, nb_views=None, verbose=False, raw_view_key=None, save=False, ws=None, comp_window=None, add_cellobjects=True, bs=10)

Generates label views based on input model and stores it under the key ‘semseg_key’, either within the SSV’s SVs or in an extra view-storage according to input parameters: Default situation (nb_views and raw_view_key is None):

semseg_key = ‘spiness’, nb_views=None This will load the raw views stored at the SSV’s SVs.

Non-default (nb_views or raw_view_key is not None):

semseg_key = ‘spiness4’, nb_views=4 This requires to run ‘self._render_rawviews(nb_views=4)’ This method then has to be called like:

‘self.predict_semseg(m, ‘spiness4’, nb_views=4)’

Parameters

• semseg_key (str) –

• nb_views (Optional[int]) –

• k (int) –

• verbose (bool) –

• raw_view_key (str) – Key used for storing view array within SSO directory. Default: ‘raw{}’.format(nb_views) If key does not exist, views will be re-rendered with properties defined in config or as given in the kwargs ws, nb_views and comp_window.

• save (bool) – If True, views will be saved.

• ws (tuple[int]) – Window size in pixels [y, x]

• comp_window (float) – Physical extent in nm of the view-window along y (see ws to infer pixel size)

• add_cellobjects (Union[bool, Iterable]) – Add cell objects. Either bool or list of structures used to render. Only used when raw_view_key or nb_views is None - then views are rendered on-the-fly.

• bs (int) – Batch size during inference.

predict_views_axoness(model, verbose=False, pred_key_appendix='')

predict_views_embedding(model, pred_key_appendix='', view_key=None)

This will save a latent vector which captures a local morphology fingerprint for every skeleton node location as :py:attr:`~skeleton`[‘latent_morph’] based on the nearest rendering location.

Notes

• This method requires existing views. For on the fly view rendering use view_embedding_of_sso_nocache()

Parameters

• model –

• pred_key_appendix –

• view_key – str View identifier, e.g. if views have been pre-rendered and are stored in self.view_dict

Returns:

predict_views_gliaSV(model, verbose=True, pred_key_appendix='')

preprocess()

Process object mapping (requires the prior assignment of object candidates), cache object meshes and calculate the SSV skeleton.

property rag: networkx.classes.graph.Graph

The region adjacency graph (defining the supervoxel graph) of this SSV object.

Return type

Graph

Returns

Supervoxel graph with nodes of type SegmentationObject.

render_indexviews(nb_views=2, save=True, force_recompute=False, verbose=False, view_key=None, ws=None, comp_window=None)

Render SSV raw views in case non-default number of views is required. Will be stored in SSV view dict. Default raw/index/prediction views are stored decentralized in corresponding SVs.

Parameters

• nb_views – int

• save – bool

• force_recompute – bool

• verbose – bool

• view_key – Optional[str] key used for storing view array. Default: ‘index{}’.format(nb_views)

• ws – Tuple[int] Window size in pixels [y, x]

• comp_window – float Physical extent in nm of the view-window along y (see ws to infer pixel size)

Returns: np.array

render_ortho_views_vis(dest_folder=None, colors=None, ws=(2048, 2048), obj_to_render=('sv',))

render_views(add_cellobjects=False, verbose=False, overwrite=True, cellobjects_only=False, woglia=True, skip_indexviews=False)

Renders views for each SV based on SSV context and stores them on SV level. Usually only used once: for initial glia or axoness prediction. The results will be saved distributed at each class:~syconn.reps.segmentation.SegmentationObject of this object. It is not cached in view_dict nor view_path. Used during initial glia, compartment and cell type predictions. See _render_rawviews() for how to store views in the SSV storage, which is e.g. used during GT generation.

Parameters

• add_cellobjects (bool) – Add cellular organelle channels in the 2D projection views.

• verbose (bool) – Log additional information.

• overwrite (bool) – Re-render at all rendering locations.

• cellobjects_only (bool) – Render only cellular organelle channels. Currently not in use.

• woglia (bool) – If True, will load the views render from the glia-free agglomeration.

• skip_indexviews (bool) – Index views will not be generated, used for initial SSV glia-removal rendering.

property rep_coord: numpy.ndarray

Representative coordinate of this SSV object. Will be the representative coordinate of the first supervoxel in svs.

Return type

ndarray

Returns

1D array of the coordinate (XYZ).

sample_locations(force=False, cache=True, verbose=False, ds_factor=None)

Parameters

• force – bool force resampling of locations

• cache – bool save sample location in SSO attribute dict

• verbose – bool

• ds_factor – float Downscaling factor to generate locations

Returns: list of array

Sample coordinates for each SV in self.svs.

save_attr_dict()

Save the SSV’s attribute dictionary.

save_attributes(attr_keys, attr_values)

Writes attributes to attribute dict on file system. Does not care about self.attr_dict.

Parameters

• attr_keys (tuple) – tuple of str

• attr_values (tuple) – tuple of items

save_objects_to_kzip_dense(obj_types, dest_path=None)

Export cellular organelles as coordinates with size, shape and overlap properties in a KNOSSOS compatible format.

Parameters

• obj_types (List[str]) – Type identifiers of the supervoxel objects which are exported.

• dest_path (Optional[str]) – Path to the destination file. If None, result will be stored at objects_dense_kzip_path:

save_objects_to_kzip_sparse(obj_types=None, dest_path=None)

Export cellular organelles as coordinates with size, shape and overlap properties in a KNOSSOS compatible format.

Parameters

• obj_types (Optional[Iterable[str]]) – Type identifiers of the supervoxel objects which are exported.

• dest_path (Optional[str]) – Path to the destination file. If None, results will be stored at skeleton_kzip_path:

save_skeleton(to_kzip=False, to_object=True)

Saves skeleton to default locations as .pkl and optionally as .k.zip.

Parameters

• to_kzip – Stores skeleton as a KNOSSOS compatible xml inside a k.zip file.

• to_object – Stores skeleton as a dictionary in a pickle file.

save_skeleton_to_kzip(dest_path=None, name='skeleton', additional_keys=None, comments=None)

Parameters

• dest_path (Optional[str]) – Destination path for k.zip file.

• name (str) – identifier / name of saved skeleton which appears in KNOSSOS

• additional_keys (Optional[List[str]]) – Additional skeleton keys which are converted into

• the (KNOSSOS skeleton node properties. Will always attempt to write out) –

• 'axoness' (keys) –

• 'meta'. ('cell_type' and) –

• comments (Union[ndarray, List[str], None]) – np.ndarray of strings or list of strings of length N where N

• into (equals the number of skeleton nodes. Comments will be converted) –

• comments. (KNOSSOS skeleton node) –

Returns

Saves KNOSSOS compatible k.zip file containing the SSV skeleton and its node properties.

save_views(views, view_key='views')

This will only save views on SSV level and not for each individual SV!

Parameters

• views (ndarray) – The view array.

• view_key (str) – The key used for the look-up.

Returns:

property scaling: numpy.ndarray

Voxel size in nanometers (XYZ). Default is taken from the config.yml file and accessible via config.

Return type

ndarray

semseg2mesh(semseg_key, dest_path=None, nb_views=None, k=1, force_recompute=False, index_view_key=None)

Generates vertex labels and stores it in the SSV’s label storage under the key semseg_key.

Examples

Default situation:

semseg_key = 'spiness', nb_views=None This will load the index and label views stored at the SSV’s SVs.

Non-default:

semseg_key = 'spiness4', nb_views=4 This requires to run self._render_rawviews(nb_views=4), self.render_indexviews(nb_views=4) and predict_semseg(MODEL, 'spiness4', nb_views=4). This method then has to be called like: self.semseg2mesh('spiness4', nb_views=4)

Parameters

• semseg_key (str) – Key used to retrieve the semantic segmentation results.

• dest_path (Optional[str]) – Path where the mesh will be stored as .ply in a k.zip.

• nb_views (Optional[int]) – Number of views used

• k (int) – Number of nearest vertices to average over. If k=0 unpredicted vertices will be treated as ‘unpredicted’ class.

• force_recompute (bool) – Force recompute.

• index_view_key (Optional[str]) – Key usedc to retrieve the index views.

Returns:

semseg_for_coords(coords, semseg_key, k=5, ds_vertices=20, ignore_labels=None)

Get the semantic segmentation with key semseg_key from the k nearest vertices at every coordinate in coords.

Parameters

• coords (ndarray) – np.array Voxel coordinates, unscaled! [N, 3]

• semseg_key (str) – str

• k (int) – int Number of nearest neighbors (NN) during k-NN classification

• ds_vertices (int) – int striding factor for vertices, uses max(1, ds_vertices // 10) if len(vertices) < 5e6.

• ignore_labels (Optional[Iterable[int]]) – List[int] Vertices with labels in ignore_labels will be ignored during majority vote, e.g. used to exclude unpredicted vertices.

Returns: np.array

Same length as coords. For every coordinate in coords returns the majority label based on its k-nearest neighbors.

property shape: numpy.ndarray

The XYZ extent of this SSV object in voxels.

Return type

ndarray

Returns

The shape/extent of thiss SSV object in voxels (XYZ).

shortestpath2soma(coordinates, axoness_key=None)

Computes the shortest path to the soma along skeleton. Cell compartment predictions must exist in self.skeleton['axoness_avg10000'], see run_semsegaxoness_mapping(). Requires a populated skeleton, e.g. via load_skeleton().

Parameters

• coordinates (ndarray) – Starting coordinates in voxel coordinates; shape of (N, 3).

• axoness_key (Optional[str]) – Key to axon prediction stored in skeleton.

Raises

KeyError – If axon prediction does not exist.

Examples

To get the shortest paths between all synapses and the soma use:

from syconn.reps.super_segmentation import *
from syconn import global_params

global_params.wd = '~/SyConn/example_cube1/'
ssd = SuperSegmentationDataset()
# get any cell reconstruction
ssv = ssd.get_super_segmentation_object(ssd.ssv_ids[0])
# get synapse coordinates in voxels.
syns = np.array([syn.rep_coord for syn in ssv.syn_ssv])
shortest_paths = ssv.shortestpath2soma(syns)

Return type

List[float]

Returns

The shortest path in nanometers for each start coordinate.

property size: int

Returns: The number of voxels associated with this SSV object.

Return type

int

property sj_ids: numpy.ndarray

All synaptic junction (sj) supervoxel IDs which are assigned to this cell reconstruction.

Return type

ndarray

property sj_mesh: Optional[Union[Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray], List[numpy.ndarray], Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]]]

Mesh of all synaptic junction (sj) supervoxels. These objects are based on the original synapse prediction and might contain merger.

Return type

Union[Tuple[ndarray, ndarray, ndarray], List[ndarray], Tuple[ndarray, ndarray, ndarray, ndarray], None]

property sjs: List[syconn.reps.segmentation.SegmentationObject]

All synaptic junction (sj) SegmentationObjects objects which are assigned to this cell reconstruction. These objects are based on the initial synapse predictions and may contain synapse-synapse merger. See syn_ssv for merger-free inter-neuron synapses.

Return type

List[SegmentationObject]

property skeleton_kzip_path: str

Path to the skeleton storage.

Return type

str

property skeleton_kzip_path_views: str

Path to the skeleton storage.

Return type

str

property skeleton_path: str

Identifier of SSV skeleton

Return type

str

skelproperty2mesh(key, dest_path=None, k=1)

property ssd_dir: str

Path to the SuperSegmentationDataset directory this object belongs to.

Return type

str

property ssd_kwargs: dict

Return type

dict

property ssv_dir: str

Path to the folder where the data of this super-supervoxel is stored.

Return type

str

property ssv_kwargs: dict

Return type

dict

property sv_graph_uint: networkx.classes.graph.Graph

Return type

Graph

property sv_ids: numpy.ndarray

All cell supervoxel IDs which are assigned to this cell reconstruction.

Return type

ndarray

svprobas2mergelist(key='glia_probas', dest_path=None)

property svs: List[syconn.reps.segmentation.SegmentationObject]

All cell SegmentationObjects objects which are assigned to this cell reconstruction.

Return type

List[SegmentationObject]

syn_sign_ratio(weighted=True, recompute=True, comp_types=None, comp_types_partner=None)

Ratio of symmetric synapses (between 0 and 1; -1 if no synapse objects) between functional compartments specified via comp_types and comp_types_partner.

Notes

Bouton predictions are converted into axon label, i.e. 3 (en-passant) -> 1 and 4 (terminal) -> 1.

Parameters

• weighted (bool) – Compute synapse-area weighted ratio.

• recompute (bool) – Ignore existing value.

• comp_types (Optional[List[int]]) – All synapses that are formed on any of the functional compartment types given in comp_types are used for computing the ratio (0: dendrite, 1: axon, 2: soma). Default: [1, ].

• comp_types_partner (Optional[List[int]]) – Compartment type of the partner cell. Default: [0, ].

Return type

float

Returns

(Area-weighted) ratio of symmetric synapses or -1 if no synapses.

property syn_ssv: List[syconn.reps.segmentation.SegmentationObject]

All synaptic junctions SegmentationObject objects which are between super-supervoxels (syn_ssv) and assigned to this cell reconstruction. These objects are generated as an agglomeration of ‘syn’ objects, which themselves have been generation as a combination of synaptic junction (sj) and contact site (cs) objects to remove merges in the sj objects.

Return type

List[SegmentationObject]

property syn_ssv_mesh: Optional[Union[Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray], List[numpy.ndarray], Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]]]

Mesh of all inter-neuron synapses junction (syn_ssv) supervoxels. These objects are generated as a combination of contact sites and synaptic junctions (sj).

Return type

Union[Tuple[ndarray, ndarray, ndarray], List[ndarray], Tuple[ndarray, ndarray, ndarray, ndarray], None]

total_edge_length(compartments_of_interest=None, ax_pred_key='axoness_avg10000')

Total edge length of the super-supervoxel skeleton in nanometers.

Parameters

• compartments_of_interest (Optional[List[int]]) – Which compartments to take into account for calculation. axon: 1, dendrite: 0, soma: 2.

• ax_pred_key (str) – Key of compartment prediction stored in skeleton, only used if compartments_of_interest was set.

Return type

Union[ndarray, float]

Returns

Sum of all edge lengths (L2 norm) in skeleton.

property type: str

‘ssv’.

Return type

str

Returns

String identifier of the object type.

Type

The type of this super-sueprvoxel. Default

typedsyns2mesh(dest_path=None, rewrite=False)

Generates typed meshes of ‘syn_ssv’ and stores it at mesh_dc_path (keys: 'syn_ssv_sym' and 'syn_ssv_asym') and writes it to dest_path (if given). Accessed with the respective keys via load_mesh.

Synapse types are looked up in the ‘syn_ssv’ AttributeDicts and treated as follows:

• excitatory / asymmetric: 1

• inhibitory / symmetric: -1

Parameters

• dest_path (Optional[str]) – Optional output path for the synapse meshes.

• rewrite (bool) – Ignore existing meshes in _meshes or at mesh_dc_path.

property vc_ids: numpy.ndarray

All vesicle cloud (vc) supervoxel IDs which are assigned to this cell reconstruction.

Return type

ndarray

property vc_mesh: Optional[Union[Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray], List[numpy.ndarray], Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]]]

Mesh of all vesicle clouds (vc) supervoxels.

Return type

Union[Tuple[ndarray, ndarray, ndarray], List[ndarray], Tuple[ndarray, ndarray, ndarray, ndarray], None]

property vcs: List[syconn.reps.segmentation.SegmentationObject]

All vesicle cloud (vc) SegmentationObjects objects which are assigned to this cell reconstruction.

Return type

List[SegmentationObject]

property version: str

Version of the ~SuperSegmentationDataset this object belongs to. Can be any character or string like ‘0’ or ‘axongroundtruth’.

Return type

str

Returns

String identifier of the object’s version.

property view_caching: bool

If True, view data is cached.

Return type

bool

view_existence(woglia=True, index_views=False, view_key=None)

Checks whether a specific set of views exists for this object.

Parameters

• woglia (bool) – If True, will load the views render from the glia-free agglomeration.

• index_views (bool) – Views which contain the indices of the vertices at the respective pixels. Used as look-up to map the predicted semantic labels onto the mesh vertices.

• view_key (Optional[str]) – The key used for the look-up.

Return type

List[bool]

Returns

True if the specified views exist.

property view_path: str

Identifier of view storage

Return type

str

property vlabel_dc_path: str

Identifier of vertex label storage

Return type

str

property voxel_caching: bool

If True, voxel data is cached.

Return type

bool

property voxels: Optional[numpy.ndarray]

Voxels associated with this SSV object.

Return type

Optional[ndarray]

Returns

3D binary array indicating voxel locations.

property voxels_xy_downsampled: Optional[numpy.ndarray]

Return type

Optional[ndarray]

weighted_graph(add_node_attr=())

Creates a Euclidean distance (in nanometers) weighted graph representation of the skeleton of this SSV object. The node IDs represent the index in the 'node' array part of skeleton. Weights are stored as ‘weight’ in the graph, this allows to use e.g. nx.single_source_dijkstra_path(..).

Parameters

add_node_attr (Iterable[str]) – To-be-added node attributes. Must exist in

:param : py:attr`~skeleton`.

Return type

Graph

Returns

The skeleton of this SSV object as a networkx graph.

property working_dir: str

Working directory.

Return type

str

write_axpred_rfc(dest_path=None, k=1)

write_gliapred_cnn(dest_path=None)

write_locations2kzip(dest_path=None)

write_svmeshes2kzip(dest_path=None, **kwargs)

Write individual cell supervoxel (‘sv’) meshes in ply format to kzip file.

Parameters

dest_path (Optional[str]) – Target file name.

syconn.reps.super_segmentation_object.celltype_predictor(args)

Parameters

args –

Returns:

Return type

Iterable

syconn.reps.super_segmentation_object.render_sampled_sos_cc(sos, ws=(256, 128), verbose=False, woglia=True, render_first_only=0, add_cellobjects=True, overwrite=False, cellobjects_only=False, index_views=False, enable_locking=True)

Renders for each SV views at sampled locations (number is dependent on SV mesh size with scaling fact) from combined mesh of all SV.

Parameters

• sos – list of SegmentationObject

• ws – tuple

• verbose – bool

• woglia – bool without glia components

• render_first_only – int

• add_cellobjects – bool

• overwrite – bool

• cellobjects_only – bool

• index_views – bool

• enable_locking – bool enable system locking when writing views

Returns:

syconn.reps.super_segmentation_object.render_so(so, ws=(256, 128), add_cellobjects=True, verbose=False)

Render super voxel views located at given locations. Does not write views to so.views_path

Parameters

• so – SegmentationObject super voxel ID

• ws – tuple of int Rendering windows size

• add_cellobjects – bool

• verbose – bool

Returns: np.array

views

syconn.reps.super_segmentation_object.semsegaxoness2skel(sso, map_properties, pred_key, max_dist)

Populate the following two skeleton keys:

• “{}_avg{}”.format(pred_key, max_dist)

• “{}_avg{}_comp_maj”.format(pred_key, max_dist)

Parameters

• sso (SuperSegmentationObject) – SuperSegmentationObject.

• map_properties (dict) – Properties used to map the vertex predictions to the skeleton nodes.

• pred_key (str) – Used for retrieving vertex labels and to store the mapped node labels in the skeleton.

• max_dist (int) – Distance used for majority vote in majorityvote_skeleton_property.

Notes

• Node predictions will be zero if no mesh vertices are available or no nodes exist.

Returns:

syconn.reps.super_segmentation_object.semsegaxoness_predictor(args)

Predicts axoness and stores resulting labels at vertex dictionary.

Parameters

args – (ssv_ids, view_props, nb_cpus, map_properties, pred_key, max_dist)

Return type

List[int]

Returns

IDs of missing/failed SSVs.

syconn.reps.super_segmentation_object.semsegspiness_predictor(args)

Predicts spiness and stores resulting labels at vertex dictionary.

Parameters

args – (ssv_ids, view_props, nb_cpus, kwargs_semseg2mesh, kwargs_semsegforcoords)

Returns:

Return type

List[int]

syconn.reps.super_segmentation_helper module

syconn.reps.super_segmentation_helper.assemble_from_mergelist(ssd, mergelist)

Creates mapping_dict and save_dataset_shallow().

Will overwrite existing mapping dict, id changer and version files.

Parameters

• ssd (SuperSegmentationDataset) – SuperSegmentationDataset.

• mergelist (Union[Dict[int, int], str]) – Supervoxel agglomeration.

syconn.reps.super_segmentation_helper.average_node_axoness_views(sso, pred_key=None, pred_key_appendix='', max_dist=10000, return_res=False, use_cache=False)

Averages the axoness prediction along skeleton with maximum path length of ‘max_dist’. Therefore, view indices were mapped to every skeleton node and collected while traversing the skeleton. The majority of the set of their predictions will be assigned to the source node. By default, will create ‘axoness_preds_cnn’ attribute in SSV attribute dict and save new skeleton attribute with key "%s_views_avg%d" % (pred_key, max_dist). This method will not call sso.save_skeleton().

Parameters

• sso (super_segmentation.SuperSegmentationObject) –

• pred_key (Optional[str]) – Key for the stored SV predictions.

• pred_key_appendix (str) – If pred_key is None, it will be set to pred_key = "axoness_preds_cnn%s" % pred_key_appendix

• max_dist (int) –

• return_res (bool) –

• use_cache (bool) – Write intermediate SV predictions in SSV attribute dict to disk.

Returns:

syconn.reps.super_segmentation_helper.celltype_of_sso_nocache(sso, model, ws, nb_views, comp_window, nb_views_model=20, pred_key_appendix='', verbose=False, overwrite=True, use_syntype=True, da_equals_tan=True, n_classes=7, save_to_attr_dict=True)

Renders raw views at rendering locations determined by comp_window and according to given view properties without storing them on the file system. Views will be predicted with the given model. By default, resulting predictions and probabilities are stored as ‘celltype_cnn_e3’ and ‘celltype_cnn_e3_probas’ in the attribute dictionary.

Parameters

• sso –

• model –

• ws – Window size in pixels [y, x]

• nb_views – Number of views rendered at each rendering location.

• nb_views_model (int) – bootstrap sample size of view locations for model prediction

• comp_window – Physical extent in nm of the view-window along y (see ws to infer pixel size)

• pred_key_appendix (str) –

• verbose (bool) – Adds progress bars for view generation.

• overwrite (bool) –

• use_syntype (bool) – Use type of presynaptic synapses.

• da_equals_tan (bool) – Merge DA and TAN classes. n_classes must be 7 if True.

• n_classes (int) – Number of out classes of the model. Must be 7 if da_equals_tan is True.

• save_to_attr_dict (bool) – Save prediction in attr_dict.

Returns:

syconn.reps.super_segmentation_helper.cnn_axoness2skel(sso, pred_key_appendix='', k=1, force_reload=False, save_skel=True, use_cache=False)

By default, will create ‘axoness_preds_cnn’ attribute in SSV attribute dict and save new skeleton attributes with keys “axoness” and “axoness_probas”.

Parameters

• sso (super_segmentation.SuperSegmentationObject) – SuperSegmentationObject

• pred_key_appendix (str) – str

• k (int) – int

• force_reload (bool) – bool Reload SV predictions.

• save_skel (bool) – bool Save SSV skeleton with prediction attributes

• use_cache (bool) – bool Write intermediate SV predictions in SSV attribute dict to disk

Returns:

syconn.reps.super_segmentation_helper.compartments_graph(ssv, axoness_key)

Creates a axon, dendrite and soma graph based on the skeleton node CMN predictions.

Parameters

• ssv (super_segmentation.SuperSegmentationObject) – Cell reconstruction. Its skeleton must exist and must contain keys

• 'edges' –

• axoness_key. ('nodes' and) –

• axoness_key (str) – Key used to retrieve axon predictions in ssv.skeleton (0: dendrite, 1: axon, 2: soma). Converts labels 3 (en-passant bouton) and 4 (terminal bouton) into 1 (axon).

Return type

Tuple[Graph, Graph, Graph]

Returns

Three graphs for dendrite, axon and soma compartment respectively.

syconn.reps.super_segmentation_helper.convert_coord(coord_list, scal)

Parameters

• coord_list –

• scal –

Returns:

syconn.reps.super_segmentation_helper.create_new_skeleton(sv_id, sso)

Parameters

• sv_id –

• sso –

Returns:

syconn.reps.super_segmentation_helper.create_new_skeleton_sv_fast(args)

Create a sparse supervoxel skeleton. Initial skeleton must exist. Similar to create_new_skeleton() but used as multi-process helper method in from_sso_to_netkx_fast().

Parameters

args – Supervoxel ID (int) and sparse flag (bool).

Returns

Node coordinates [in voxels], diameter estimation per node, edges.

Return type

Three arrays

syconn.reps.super_segmentation_helper.create_sso_skeleton_fast(sso, pruning_thresh=800, sparsify=True, max_dist_thresh=600, dot_prod_thresh=0.0, max_dist_thresh_iter2=600)

Creates the super-supervoxel skeleton. NOTE: If the underlying RAG does not connect close-by SVs it will be slower than create_sso_skeleton(). The latter will recursively add the shortest edge between two different SVs. This method will add edges between supervoxels which are connected in the supervoxel graph. To use multi-processing set ssv.nb_cpus > 1.

Parameters

• sso – Super Segmentation Object

• pruning_thresh – int Threshold for pruning step (in NM). Removes branches below this path length, see prune_stub_branches().

• sparsify – bool will sparsify if True otherwise not

• max_dist_thresh – float Maximum distance in NM of two adjacent edges in order to prune the node in-between. Initial sparsening via skeleton_optimization().

• dot_prod_thresh – float Dot product value of two adjacent edges. Above this value, the node in-between will be pruned. Used in sparsify_skeleton_fast() after first sparsening and pruning.

• max_dist_thresh_iter2 – float Maximum distance in NM of two adjacent edges in order to prune the node in-between. Used in sparsify_skeleton_fast() after first sparsening and pruning.

Returns

The cell reconstruction with sparse skeleton (as MST) and radius estimates.

syconn.reps.super_segmentation_helper.create_sso_skeletons_wrapper(ssvs, dest_paths=None, nb_cpus=None, map_myelin=False, save=True)

Used within SuperSegmentationObject() to generate a skeleton representation of the cell. If global_params.config.allow_ssv_skel_gen = True, the skeleton will be created using a sampling procedure based on the cell surface, i.e. the resulting skeleton might fall out of the cell’s segmentation and its nodes will always be close to the cell surface. If global_params.config.allow_ssv_skel_gen = False, supervoxel skeleton must already exist and those will be pruned, stitched and finally a per-node diameter estimation will be performed. This method will invoke ssv.save_skeleton and the results will also be available in every object of ssvs via ssv.skeleton.

Parameters

• ssvs (List[ForwardRef]) – An iterable of cell reconstruction objects.

• dest_paths (Optional[str]) – Paths to kzips for each object in ssvs.

• nb_cpus (Optional[int]) – Number of CPUs used for every ssv in ssvs.

• map_myelin (bool) –

  Map myelin predictions at every ssv.skeleton["nodes"] stored as ``ssv.skeleton["myelin"] with map_myelin2coords(). The myelin predictions are smoothed via a sliding window majority vote (see majorityvote_skeleton_property()) with a traversal distance

  of 10 micrometers.

• save (bool) – Write generated skeleton.

syconn.reps.super_segmentation_helper.extract_spinehead_volume_mesh(sso, ctx_vol=(200, 200, 100))

# problematic if the same node was assigned different synapses..

Calculate the volume of spine heads based on a watershed procedure on the cell segmentation. Spine head predictions on the cell mesh are used as starting point. Vertex predictions are then mapped to voxels within at least 2*ctx_vol + synapse_boundinb_box. The watershed seeds are extracted from local maxima of the cell mask’s distance transform. Each seed is assigned the majority label of its k-nearest vertices. Results are stored in attr_dict with the key spinehead_vol.

Notes

• ‘spine_headvol’ in µm^3.

• Segmentation mask is downsampled to z voxel size. i.e. a volume of shape (50, 50, 25) with (10, 10, 20) nm^3 voxels will be reduced to (25, 25, 25) voxels.

• Requires a predicted cell mesh, i.e. ‘spiness’ must be present in label_dict('vertex')['spiness'].

• If the results have to be stored, call sso.save_attr_dict()

Parameters

• sso (super_segmentation.SuperSegmentationObject) – Cell object.

• ctx_vol – Additional volume around the spine head synapse rep. coord used to calculate the volume estimation, i.e. the inspected volume is 2*ctx_vol.

syconn.reps.super_segmentation_helper.find_incomplete_ssv_skeletons(ssd, n_cores=None)

syconn.reps.super_segmentation_helper.find_incomplete_ssv_views(ssd, woglia, n_cores=None)

syconn.reps.super_segmentation_helper.find_missing_sv_attributes_in_ssv(ssd, attr_key, n_cores=None)

syconn.reps.super_segmentation_helper.from_netkx_to_arr(skel_nx)

Parameters

skel_nx (Graph) –

Returns:

Return type

Tuple[ndarray, ndarray, ndarray]

syconn.reps.super_segmentation_helper.from_netkx_to_sso(sso, skel_nx)

Parameters

• sso –

• skel_nx –

Returns:

syconn.reps.super_segmentation_helper.from_sso_to_netkx_fast(sso, sparsify=True, max_edge_length=1500.0)

Stitches the SV skeletons using the supervoxel graph sso.rag.

Parameters

• sso – SuperSegmentationObject

• sparsify – bool Sparsify SV skeletons before stitching

• max_edge_length – float Maximum edge length in nanometers.

Returns: nx.Graph

syconn.reps.super_segmentation_helper.get_pca_view_hists(sso, t_net, pca)

syconn.reps.super_segmentation_helper.get_sso_axoness_from_coord(sso, coord, k=5)

Finds k nearest neighbor nodes within sso skeleton and returns majority class of dendrite (0), axon (1) or soma (2).

Parameters

• sso – SuperSegmentationObject

• coord – np.array unscaled coordinate

• k – int Number of nearest neighbors on which the majority vote is computed.

Returns: int

syconn.reps.super_segmentation_helper.glia_pred_exists(so)

syconn.reps.super_segmentation_helper.gliapred_sso_nocache(sso, model, verbose=True)

Perform a multi-view based astrocyte inference. Result will be stored as ‘glia_probas’ in the attribute dicts of every sso.svs, e.g. access the probabilities of the first cell supervoxel via sso.svs[0].attr_dict['glia_probas'].

Parameters

• sso (SuperSegmentationObject) – Cell reconstruction object.

• model – Pytorch model.

• verbose (bool) – Print additional output.

syconn.reps.super_segmentation_helper.label_array_for_sso_skel(sso, comment_converter)

Converts skeleton node comments from annotation.xml in sso.skeleton_kzip_path (see SkeletonAnnotation class from knossos utils) to a label array of length (and same ordering) as sso.skeleton[“nodes”]. If comment was unspecified, it will get label -1

Parameters

• sso – SuperSegmentationObject

• comment_converter – dict Key: Comment, Value: integer label

Returns: np.array

Label array of len(sso.skeleton[“nodes”])

syconn.reps.super_segmentation_helper.load_voxels_downsampled(sso, downsampling=(2, 2, 1), nb_threads=10)

syconn.reps.super_segmentation_helper.majority_vote(anno, prop, max_dist)

Smoothes (average using sliding window of 2 times max_dist and majority vote) property prediction in annotation, whereas for axoness somata are untouched. :param anno: SkeletonAnnotation :param prop: str

which property to average

Parameters

max_dist – int maximum distance (in nm) for sliding window used in majority voting

Returns:

syconn.reps.super_segmentation_helper.majority_vote_compartments(sso, ax_pred_key='axoness')

By default, will save new skeleton attribute with key ax_pred_key + “_comp_maj”. Will not call sso.save_skeleton().

Parameters

• sso (SuperSegmentationObject) – SuperSegmentationObject

• ax_pred_key (str) – Key for the axoness predictions stored in sso.skeleton

Returns:

syconn.reps.super_segmentation_helper.majorityvote_skeleton_property(sso, prop_key, max_dist=10000, return_res=False)

Applies a sliding window majority vote along the skeleton of a given SuperSegmentationObject. Will not call sso.save_skeleton().

Parameters

• sso (super_segmentation.SuperSegmentationObject) – The cell reconstruction object.

• prop_key (str) – Key of the property which will be processed.

• max_dist (int) – Maximum traversal distance along L2-distance weighted graph.

• return_res (bool) – If True, majority result will be returned.

Return type

ndarray

Returns

The majority vote of the requested property.

syconn.reps.super_segmentation_helper.map_myelin2coords(coords, cube_edge_avg=array([11, 11, 5]), thresh_proba=127, thresh_majority=0.5, mag=4)

Retrieves a myelin prediction at every location in coords. The classification is the majority label within a cube of size cube_edge_avg around the respective location. Voxel-wise myelin predictions are found by thresholding the probability for myelinated voxels at thresh stored in the KnossosDataset at global_params.config.working_dir+'/knossosdatasets/myelin/'.

Examples

The entire myelin prediction for a single cell reconstruction including a smoothing via majorityvote_skeleton_property() is implemented as follows:

from syconn import global_params
from syconn.reps.super_segmentation import *
from syconn.reps.super_segmentation_helper import map_myelin2coords, majorityvote_skeleton_property

# init. example data set
global_params.wd = '~/SyConn/example_cube1/'

# initialize example cell reconstruction
ssd = SuperSegmentationDataset()
ssv = list(ssd.ssvs)[0]
ssv.load_skeleton()

# get myelin predictions
myelinated = map_myelin2coords(ssv.skeleton["nodes"], mag=4)
ssv.skeleton["myelin"] = myelinated
# this will generate a smoothed version at ``ssv.skeleton["myelin_avg10000"]``
majorityvote_skeleton_property(ssv, "myelin")
# store results as a KNOSSOS readable k.zip file
ssv.save_skeleton_to_kzip(dest_path='~/{}_myelin.k.zip'.format(ssv.id),
    additional_keys=['myelin', 'myelin_avg10000'])

Parameters

• coords (ndarray) – Coordinates used to retrieve myelin predictions. In voxel coordinates (mag=1).

• cube_edge_avg (ndarray) – Cube size used for averaging myelin predictions for each location. The loaded data cube will always have the extent given by cube_edge_avg, regardless of the value of mag.

• thresh_proba (float) – Classification threshold in uint8 values (0..255).

• thresh_majority (float) – Majority ratio for myelin (between 0..1), i.e. thresh_majority=0.1 means that 10% myelin voxels within cube_edge_avg will flag the corresponding locations as myelinated.

• mag (int) – Data mag. level used to retrieve the prediction results.

Returns

no myelin, 1: myelinated neuron) at every coordinate.

Return type

Myelin prediction (0

syconn.reps.super_segmentation_helper.nodes_in_pathlength(anno, max_path_len)

Find nodes reachable in max_path_len from source node, calculated for every node in anno. :param anno: AnnotationObject :param max_path_len: float

Maximum distance from source node

Returns: list of lists containing reachable nodes in max_path_len where

outer list has length len(anno.getNodes())

syconn.reps.super_segmentation_helper.pred_sv_chunk_semseg(args)

Helper method to predict the 2D projects of supervoxels.

Parameters

args – Paths to the supervoxel storages which are processed, model, supervoxel and prediction parameters.

Returns:

syconn.reps.super_segmentation_helper.pred_svs_semseg(model, views, pred_key=None, svs=None, return_pred=False, nb_cpus=1, verbose=False, bs=10)

Predicts views of a list of SVs and saves them via SV.save_views. Efficient helper function for chunked predictions, therefore requires pre-loaded views.

Parameters

• model –

• views – List[np.array] N_SV each with np.array of shape [N_LOCS, N_CH, N_VIEWS, X, Y] as uint8 scaled from 0 to 255

• pred_key – str

• svs – Optional[list[SegmentationObject]]

• return_pred – Optional[bool]

• nb_cpus – int number CPUs for saving the SV views

• verbose – bool

• bs (int) – Batch size during inference.

Returns: list[np.array]

if ‘return_pred=True’ it returns the label views of input

syconn.reps.super_segmentation_helper.predict_sso_celltype(sso, model, nb_views_model=20, use_syntype=True, overwrite=False, pred_key_appendix='', da_equals_tan=True, n_classes=7, save_to_attr_dict=True)

Celltype prediction based on local views and synapse type ratio feature. Uses on file system cached views (also used for axon and spine prediction). See celltype_of_sso_nocache for ‘on-the-fly’ prediction, which renders views from scratch given their window size etc. sso_views_to_modelinput() is used to create the random view subsets. The final prediction is the majority class of all subset predictions.

Parameters

• sso (super_segmentation.SuperSegmentationObject) – SuperSegmentationObject

• model (Any) – nn.Module

• nb_views_model (int) – int

• use_syntype – bool

• overwrite (bool) – bool Use the type of the pre-synapses.

• pred_key_appendix – str

• da_equals_tan (bool) – Merge DA and TAN classes. n_classes must be 7 if True.

• n_classes (int) – Number of out classes of the model. Must be 7 if da_equals_tan is True.

• save_to_attr_dict (bool) – Save prediction in attr_dict.

Returns:

syconn.reps.super_segmentation_helper.predict_views_semseg(views, model, batch_size=10, verbose=False)

Predicts a view array of shape [N_LOCS, N_CH, N_VIEWS, X, Y] with N_LOCS locations each with N_VIEWS perspectives, N_CH different channels (e.g. shape of cell, mitochondria, synaptic junctions and vesicle clouds).

Parameters

• views – np.array shape of [N_LOCS, N_CH, N_VIEWS, X, Y] as uint8 scaled from 0 to 255

• model – pytorch model

• batch_size – int

• verbose – bool

Returns:

syconn.reps.super_segmentation_helper.prune_stub_branches(sso=None, nx_g=None, scal=None, len_thres=1000, preserve_annotations=True)

Removes short stub branches, that are often added by annotators but

hardly represent true morphology.

Parameters

• sso – SuperSegmentationObject

• nx_g – network kx graph

• scal – array of size 3 the scaled up factor

• len_thres – int threshold of the length below which it will be pruned

• preserve_annotations – bool

Returns: pruned MST

syconn.reps.super_segmentation_helper.radius_correction_found_vertices(sso, plump_factor=1, num_found_vertices=10)

Algorithm finds two nearest vertices and takes the median of the distances for every node.

Parameters

• sso (super_segmentation.SuperSegmentationObject) – SuperSegmentationObject

• plump_factor (int) – int multiplication factor for the radius

• num_found_vertices (int) – int number of closest vertices queried for the node

Returns: skeleton with diameters estimated

syconn.reps.super_segmentation_helper.save_view_pca_proj(sso, t_net, pca, dest_dir, ls=20, s=6.0, special_points=(), special_markers=(), special_kwargs=())

syconn.reps.super_segmentation_helper.semseg2mesh(sso, semseg_key, nb_views=None, dest_path=None, k=1, colors=None, force_recompute=False, index_view_key=None)

Maps semantic segmentation to SSV mesh.

Notes

• k>0 should only be used if a prediction for all vertices is absolutely required. Filtering of background and unpredicted vertices should be favored if time complexity is critical.

Parameters

• sso – The cell reconstruction.

• semseg_key – The key of the views which contain the semantic segmentation results, i.e. pixel-wise labels.

• index_view_key – Key of the views which hold the vertex indices at every pixel. If index_view_key is set, nb_views is ignored.

• nb_views – Number of views used for the prediction. Required for loading the correct index views if index_view_key is not set.

• dest_path – Colored mesh will be written to k.zip and not returned.

• k – Number of nearest vertices to average over. If k=0 unpredicted vertices will be treated as ‘unpredicted’ class.

• colors – Array with as many entries as the maximum label of ‘semseg_key’ predictions with values between 0 and 255 (will be interpreted as uint8). If it is None, the majority label according to kNN will be returned instead. Note to add a color for unpredicted vertices if k==0; here illustrated with by the spine prediction example: if k=0: [neck, head, shaft, other, background, unpredicted] else: [neck, head, shaft, other, background].

• force_recompute – Force re-mapping of the predicted labels to the mesh vertices.

Returns

indices, vertices, normals, color

syconn.reps.super_segmentation_helper.semseg2mesh_counter(index_arr, label_arr, bg_label, count_arr)

Count the labels in label_arr of every ID in index_arr.

Parameters

• index_arr (ndarray) – Flat array of contiguous vertex IDs. Order must match label_arr.

• label_arr (ndarray) – Semantic segmentation prediction results as flat array. Order must match index_arr. Maximum value must be below bg_label.

• bg_label (int) – Background label, will not be counted.

• count_arr (ndarray) – Zero-initialized array storing the per-vertex counted labels as given in label_arr. Must have shape (M, bg_label) where M is the number of vertices of the underyling mesh.

Return type

ndarray

Returns

Array filled with the per-vertex label counts.

syconn.reps.super_segmentation_helper.semseg_of_sso_nocache(sso, model, semseg_key, ws, nb_views, comp_window, k=1, dest_path=None, verbose=False, add_cellobjects=True, bs=10)

Renders raw and index views at rendering locations determined by comp_window and according to given view properties without storing them on the file system. Views will be predicted with the given model and maps prediction results onto mesh. Vertex labels are stored on file system and can be accessed via sso.label_dict(‘vertex’)[semseg_key]. If sso._sample_locations is None it generate_rendering_locs(verts, comp_window / 3) will be called to generate rendering locations.

Examples

Given a cell reconstruction exported as kzip (see ) at cell_kzip_fn the compartment prediction (axon boutons, dendrite, soma) can be started via the following script:

# set working directory to obtain models
global_params.wd = '~/SyConn/example_cube1/'

# get model for compartment detection
m = get_semseg_axon_model()
view_props = global_params.config['compartments']['view_properties_semsegax']
view_props["verbose"] = True

# load SSO instance from k.zip file
sso = init_sso_from_kzip(cell_kzip_fn, sso_id=1)

# run prediction and store result in new kzip
cell_kzip_fn_axon = cell_kzip_fn[:-6] + '_axon.k.zip'
semseg_of_sso_nocache(sso, dest_path=cell_kzip_fn_axon, model=m,
                      **view_props)

See also the example scripts at:

$ python SyConn/examples/semseg_axon.py
$ python SyConn/examples/semseg_spine.py

Parameters

• sso – Cell reconstruction object.

• model – The elektronn3 model used for the prediction.

• semseg_key (str) – The key which is used to store the resulting prediction.

• ws (Tuple[int, int]) – Window size in pixels [y, x]

• nb_views (int) – Number of views rendered at each rendering location.

• comp_window (float) – Physical extent in nm of the view-window along y (see ws to infer pixel size)

• k (int) – Number of nearest vertices to average over. If k=0 unpredicted vertices will be treated as ‘unpredicted’ class.

• dest_path (Optional[str]) – location of kzip in which colored vertices (according to semantic segmentation prediction) are stored.

• verbose (bool) – Adds progress bars for view generation.

• add_cellobjects (Union[bool, Iterable]) – Add cell objects. Either bool or list of structures used to render. Only used when raw_view_key or nb_views is None - then views are rendered on-the-fly.

• bs (int) – Batch size during inference.

Returns:

syconn.reps.super_segmentation_helper.skelnode_comment_dict(sso)

syconn.reps.super_segmentation_helper.sparsify_skeleton_fast(g, scal=None, dot_prod_thresh=0.8, max_dist_thresh=500, min_dist_thresh=50, verbose=False)

Reduces nodes in the skeleton.

Parameters

• g (Graph) – networkx graph of the sso skel. Requires ‘position’ attribute.

• scal (Optional[ndarray]) – Scale factor; equal to the physical voxel size (nm).

• dot_prod_thresh (float) – the ‘straightness’ of the edges.

• max_dist_thresh (Union[int, float]) – Maximum distance desired between every node.

• min_dist_thresh (Union[int, float]) – Minimum distance desired between every node.

• verbose (bool) – Log additional output.

Returns: sso containing the sparse skeleton.

Return type

Graph

syconn.reps.super_segmentation_helper.sso_svgraph2kzip(dest_path, sso)

Store SV graph in KNOSSOS compatible kzip.

Parameters

• dest_path (str) – Path to k.zip.

• sso (SuperSegmentationObject) – Cell object.

syconn.reps.super_segmentation_helper.sso_views_to_modelinput(sso, nb_views, view_key=None)

Converts the 2D projections views of an SuperSegmentationObject into random subsets of views each of size nb_views. Used for cell type inference.

Parameters

• sso (super_segmentation.SuperSegmentationObject) – Cell reconstruction object.

• nb_views (int) – Number of views in each view subset.

• view_key (Optional[str]) – Key of the stored views.

Returns: An array of random view subsets of all 2D projections contained in the

cell reconstruction. Shape: (#subsets, 4 channels, nb_views, 128, 256)

Return type

ndarray

syconn.reps.super_segmentation_helper.syn_sign_ratio_celltype(ssv, weighted=True, recompute=False, comp_types=None, save=False)

Ratio of symmetric synapses (between 0 and 1; -1 if no synapse objects) on specified functional compartments (comp_types) of the cell reconstruction. Does not include compartment information of the partner cell. See syn_sign_ratio()

for this.

Notes

• Bouton predictions are converted into axon label, i.e. 3 -> 1 (en-passant) and 4 -> 1 (terminal).

• The compartment predictions are collected after the first access of this attribute during the celltype prediction. The key ‘partner_axoness’ is not available within `` self.syn_ssv`` until _collect_properties_from_ssv_partners_thread() is called (see run_matrix_export()).

• The compartment type of the other cell cannot be inferred at this point. Think about adding the property collection before celltype prediction -> would allow more detailed filtering of the synapses, but adds an additional round of property collection.

Parameters

• ssv (super_segmentation.SuperSegmentationObject) – The cell reconstruction.

• weighted (bool) – Compute synapse-area weighted ratio.

• recompute (bool) – Ignore existing value.

• comp_types (Optional[List[int]]) –

  All synapses that are formed between any of the functional compartment types given in comp_types on the cell reconstruction are used for computing the ratio (0: dendrite, 1: axon, 2:

  soma). Default: [1, ].

• save (bool) – Save ratio to attribute dict. The key ‘syn_sign_ratio_celltype’ or ‘syn_sign_ratio_celltype_weighted’ if weighted is True, is combined with the compartment types comp_types via ratio_key += '_' + "_".join([str(el) for el in comp_types])

Return type

float

Returns

(Area-weighted) ratio of symmetric synapses or -1 if no synapses.

syconn.reps.super_segmentation_helper.view_embedding_of_sso_nocache(sso, model, ws, nb_views, comp_window, pred_key_appendix='', verbose=False, overwrite=True, add_cellobjects=True)

Renders raw views at rendering locations determined by comp_window and according to given view properties without storing them on the file system. Views will be predicted with the given model. See predict_views_embedding in super_segmentation_object for an alternative which uses file-system cached views. By default, resulting predictions are stored as latent_morph.

Parameters

• sso (SuperSegmentationObject) –

• model (torch.nn.Module) –

• ws (Tuple[int, int]) – Window size in pixels [y, x]

• nb_views (int) – Number of views rendered at each rendering location.

• comp_window (Union[int, float]) – Physical extent in nm of the view-window along y (see ws to infer pixel size).

• pred_key_appendix (str) –

• verbose (bool) – Adds progress bars for view generation.

• overwrite (bool) – Overwrite existing views in temporary view dictionary. Key: 'tmp_views' + pred_key_appendix.

• add_cellobjects (Union[bool, Iterable]) – Add cell objects. Either bool or list of structures used to render. Only used when raw_view_key or nb_views is None - then views are rendered on-the-fly.

syconn.reps.super_segmentation_helper.views2tripletinput(views)

syconn.reps.super_segmentation_helper.write_axpred_cnn(ssv, pred_key_appendix, dest_path=None, k=1)

syconn.reps.segmentation module

class syconn.reps.segmentation.SegmentationDataset(obj_type, version=None, working_dir=None, scaling=None, version_dict=None, create=False, config=None, n_folders_fs=None, cache_properties=None)

Bases: syconn.reps.rep_helper.SegmentationBase

This class represents a set of supervoxels.

Examples

To initialize the SegmentationDataset for cell supervoxels you need to call sd_cell = SegmentationDataset('sv'). This requires an initialized working directory, for this please refer to DynConfig or see:

$ python SyConn/scripts/example_runs/start.py

After successfully executing init_cell_subcell_sds, cell supervoxel properties can be loaded from numpy arrays via the following keys:

• ‘id’: ID array, identical to ids.

• ‘bounding_box’: Bounding box of every SV.

• ‘size’: Number voxels of each SV.

• ‘rep_coord’: Representative coordinates for each SV.

• ‘mesh_area’: Surface area as computed from the object mesh triangles.

• ‘mapping_sj_ids’: Synaptic junction objects which overlap with the respective SVs.

• ‘mapping_sj_ratios’: Overlap ratio of the synaptic junctions.

• ‘mapping_vc_ids’: Vesicle cloud objects which overlap with the respective SVs.

• ‘mapping_vc_ratios’: Overlap ratio of the vesicle clouds.

• ‘mapping_mi_ids’: Mitochondria objects which overlap with the respective SVs.

• ‘mapping_mi_ratios’: Overlap ratio of the mitochondria.

If astrocyte separation is performed, the following attributes will be stored as numpy array as well:

• ‘glia_probas’: Glia probabilities as array of shape (N, 2; N: Rendering locations, 2: 0-index=neuron, 1-index=glia).

The ‘mapping’ attributes are only computed for cell supervoxels and not for cellular organelles (e.g. ‘mi’, ‘vc’, etc.; see config['process_cell_organelles']).

For the SegmentationDataset of type ‘syn_ssv’ (which represent the actual synapses between two cell reconstructions), the following properties are stored as numpy arrays:

• ‘id’: ID array, identical to ids.

• ‘bounding_box’: Bounding box of every SV.

• ‘size’: Number voxels of each SV.

• ‘rep_coord’: Representative coordinates of each SV.

• ‘mesh_area’: Surface area as computed from the object mesh triangles.

• ‘mesh_bb’: Bounding box of the object meshes (in nanometers). Approximately the same as scaled ‘bounding_box’.

• ‘latent_morph’: Latent morphology vector at each rendering location; predicted by the tCMN.

• ‘neuron_partners’: IDs of the two SuperSegmentationObject forming the synapse. The ordering of the subsequent ‘partner’ attributes is identical to ‘neuron_partners’, e.g. ‘neuron_partners’=[3, 49] and ‘partner_celltypes’=[0, 1] means that SSV with ID 3 is an excitatory axon targeting the MSN SSV with ID 49.

• ‘partner_celltypes’: Celltypes of the two SSVs.

• ‘partner_spiness’: Spine predictions (0: neck, 1: head, 2: shaft, 3: other) of the two sites.

• ‘partner_axoness’: Compartment predictions (0: dendrite, 1: axon, 2: soma, 3: en-passant bouton, 4: terminal bouton) of the two sites.

• ‘syn_prob’: Synapse probability as inferred by the RFC (see corresponding section the documentation).

• ‘asym_prop’: Mean probability of the ‘syn_ssv’ object voxels for the asymmetric type. See _extract_synapse_type_thread() .

• ‘sym_prop’: Mean probability of the ‘syn_ssv’ object voxels for the symmetric type. See _extract_synapse_type_thread() .

• ‘syn_type_sym_ratio’: sym_prop / float(asym_prop + sym_prop). See _extract_synapse_type_thread() .

• ‘syn_sign’: Synaptic “sign” (-1: symmetric, +1: asymmetric). For threshold see config['cell_objects']['sym_thresh'] .

• ‘cs_ids’: Contact site IDs associated with each ‘syn_ssv’ synapse.

property config: syconn.handler.config.DynConfig

The configuration object which contain all dataset-specific parameters. See DynConfig.

Return type

DynConfig

Returns

The configuration object.

enable_property_cache(property_keys)

Add properties to cache.

Parameters

property_keys (Iterable[str]) – Property keys. Numpy cache arrays must exist.

property exists: bool

Checks whether path exists.

Return type

bool

get_segmentation_object(obj_id, create=False, **kwargs)

Factory method for SegmentationObject which are part of this dataset.

Parameters

• obj_id (Union[int, List[int]]) – Supervoxel ID.

• create (bool) – If True, creates the folder hierarchy down to the requested supervoxel.

Return type

Union[SegmentationObject, List[SegmentationObject]]

Returns

The requested SegmentationObject object.

get_segmentationdataset(obj_type)

Factory method for SegmentationDataset which are part of this dataset.

Parameters

obj_type (str) – Dataset of supervoxels with type obj_type.

Return type

SegmentationDataset

Returns

The requested SegmentationDataset object.

get_volume(source='total')

Calculate the RAG volume.

Parameters

source (str) – Allowed sources: ‘total’ (all SVs contained in SegmentationDataset(‘sv’)), ‘neuron’ (use glia-free RAG), ‘glia’ (use glia RAG).

Return type

float

Returns

Volume in mm^3.

property ids: numpy.ndarray

Returns: All supervoxel IDs which are part of this dataset.

Return type

ndarray

iter_so_dir_paths()

Iterator over all possible SegmentationObject storage base directories.

Notes

In contrast to so_dir_paths this iterator may return paths to storages that do not exist, in the case that no object fell into its ID bucket.

Return type

Iterator[str]

Returns

Path to ID storage base folder.

load_numpy_data(prop_name, allow_nonexisting=True)

Load cached array. The ordering of the returned array will correspond to ids.

Parameters

• prop_name – Identifier of the requested cache array.

• allow_nonexisting (bool) – If False, will fail for missing numpy files.

Return type

ndarray

Returns

numpy array of property prop_name.

load_version_dict()

Load the version dictionary from the .pkl file.

property n_folders_fs: int

Returns: The number of folders in this SegmentationDataset directory tree.

Return type

int

property path: str

Returns: The path to this SegmentationDataset.

Return type

str

property path_ids: str

Path to the cache array of the object IDs.

Return type

str

Returns

Path to the numpy file.

property path_rep_coords: str

Path to the cache array of the object representative coordinates.

Return type

str

Returns

Path to the numpy file.

property path_sizes: str

Path to the cache array of the object voxel sizes.

Return type

str

Returns

Path to the numpy file.

property rep_coords: numpy.ndarray

Returns: Representative coordinates of all supervoxel which are part of this dataset. The ordering of the returned array will correspond to ids.

Return type

ndarray

save_version_dict()

Save the version dictionary to the .pkl file.

property scaling: numpy.ndarray

Returns: Voxel size in nanometers (XYZ).

Return type

ndarray

property sizes: numpy.ndarray

Returns: A size array of all supervoxel which are part of this dataset. The ordering of the returned array will correspond to ids.

Return type

ndarray

property so_dir_paths: List[str]

Sorted paths to all supervoxel object directories in the directory tree so_storage_path.

Return type

List[str]

property so_storage_path: str

Path to the root folder.

Return type

str

property so_storage_path_base: str

Name of the base of the root folder ('so_storage').

Return type

str

property soid2ix

property sos: Generator[syconn.reps.segmentation.SegmentationObject, None, None]

Generator for all SegmentationObject objects associated with this dataset.

Yields

SegmentationObject

Return type

Generator[SegmentationObject, None, None]

property type: str

The type of SegmentationDataset.

Return type

str

Returns

String identifier of the object type.

property version: str

Returns: String identifier of the version.

Return type

str

property version_dict_exists: bool

Checks whether version_dict_path exists.

Return type

bool

property version_dict_path: str

Path to the version dictionary pickle file.

Return type

str

Returns

Path to the pickle file.

property working_dir: str

Returns: The working directory of this SegmentationDataset.

Return type

str

class syconn.reps.segmentation.SegmentationObject(obj_id, obj_type='sv', version=None, working_dir=None, rep_coord=None, size=None, scaling=None, create=False, voxel_caching=True, mesh_caching=False, view_caching=False, config=None, n_folders_fs=None, enable_locking=True, skeleton_caching=True, mesh=None)

Bases: syconn.reps.rep_helper.SegmentationBase

Represents individual supervoxels. Used for cell shape (‘sv’), cell organelles, e.g. mitochondria (‘mi’), vesicle clouds (‘vc’) and synaptic junctions (‘sj’).

Examples

Can be used to initialized single SegmentationObject object of a specific type, is also returned by get_segmentation_object():

from syconn.reps.segmentation import SegmentationObject, SegmentationDataset
cell_sv = SegmentationObject(obj_id=.., obj_type='sv', working_dir='..')
cell_sv.load_attr_dict()  # populates `cell_sv.attr_dict`

cell_sd = SegmentationDataset(obj_type='sv', working_dir='..')
cell_sv_from_sd = cell_sd.get_segmentation_object(obj_id=cell_sv.id)
cell_sv_from_sd.load_attr_dict()

keys1 = set(cell_sv.attr_dict.keys())
keys2 = set(cell_sv_from_sd.attr_dict.keys())
print(keys1 == keys2)

attr_dict

Attribute dictionary which serves as a general-purpose container. Accessed via the AttributeDict interface.

enable_locking

If True, enables file locking.

property attr_dict_exists: bool

Checks if a attribute dictionary file exists at attr_dict_path.

Return type

bool

Returns

True if the attribute dictionary file exists.

property attr_dict_path: str

Path to the attribute storage.

Return type

str

attr_exists(attr_key)

Checks if attr_key exists in either attr_dict or at attr_dict_path.

Parameters

attr_key (str) – Attribute key to look for.

Return type

bool

Returns

True if attribute exists, False otherwise.

axoness_preds(pred_key_appendix='')

Axon prediction (0: dendrite, 1: axon, 2: soma) based on img2scalar CMN.

Parameters

pred_key_appendix (str) – Identifier for specific axon predictions. Only used during development.

Return type

ndarray

Returns

The axon prediction of this supervoxel at every sample_locations.

axoness_probas(pred_key_appendix='')

Axon probability (0: dendrite, 1: axon, 2: soma) based on img2scalar CMN. Probability underlying the attribute axoness_preds. Only valid if type is sv.

Parameters

pred_key_appendix (str) – Identifier for specific axon predictions. Only used during development.

Return type

ndarray

Returns

The axon probabilities of this supervoxel at every sample_locations.

property bounding_box: numpy.ndarray

Return type

ndarray

calculate_bounding_box(voxel_dc=None)

Calculate supervoxel bounding_box.

Parameters

voxel_dc (Optional[Dict[int, ndarray]]) – Pre-loaded dictionary which contains the voxel data of this object.

calculate_rep_coord(voxel_dc=None)

Calculate/loads supervoxel representative coordinate.

Parameters

voxel_dc (Optional[Dict[int, ndarray]]) – Pre-loaded dictionary which contains the voxel data of this object.

calculate_size(voxel_dc=None)

Calculate supervoxel object size.

Parameters

voxel_dc (Union[VoxelStorageDyn, VoxelStorage, None]) – Pre-loaded dictionary which contains the voxel data of this object.

clear_cache()

Clears the following, cached data:

• voxels

• voxel_list

• views

• skeleton

property config: syconn.handler.config.DynConfig

Config. object which contains all dataset-sepcific parameters.

Return type

DynConfig

copy2dir(dest_dir, safe=True)

Examples

To copy the content of this SV object (sv_orig) to the destination of another (e.g. yet not existing) SV (sv_target), call sv_orig.copy2dir(sv_target.segobj_dir). All files contained in the directory py:attr:~segobj_dir of sv_orig will be copied to sv_target.segobj_dir.

Parameters

• dest_dir – Destination directory where all files contained in py:attr:~segobj_dir will be copied to.

• safe – If True, will not overwrite existing data.

property cs_partner: Optional[List[int]]

Contact site specific attribute. :rtype: Optional[List[int]] :returns: None if object is not of type ‘cs’, else return the IDs to the two

supervoxels which are part of the contact site.

property dataset: syconn.reps.segmentation.SegmentationDataset

Factory method for the ~syconn.reps.segmentation.SegmentationDataset this object belongs to.

Return type

SegmentationDataset

glia_pred(thresh, pred_key_appendix='')

SV glia prediction (0: neuron, 1: glia). Only valid if type is sv.

Parameters

• thresh (float) – Classification threshold.

• pred_key_appendix (str) – Identifier for specific glia predictions. Only used during development.

Return type

int

Returns

The glia prediction of this supervoxel.

glia_proba(pred_key_appendix='')

SV glia probability (0: neuron, 1: glia). Only valid if type is sv.

Parameters

pred_key_appendix (str) – Identifier for specific glia predictions. Only used during development.

Return type

float

Returns

The glia prediction of this supervoxel.

property id: int

Returns: Globally unique identifier of this object.

Return type

int

property identifier: str

Identifier used to create the folder name of the ~syconn.reps.segmentation.SegmentationDataset.

Return type

str

load_attr_dict()

Loader method of attr_dict.

Return type

int

Returns

0 if successful, -1 if attribute dictionary storage does not exist.

load_attributes(attr_keys)

Reads attributes from attribute storage. It will ignore self.attr_dict and will always pull it from the storage. Does not throw KeyError, but returns None for missing keys.

Parameters

attr_keys (List[str]) – List of attribute keys which will be loaded from

:param attr_dict_path.:

Return type

List[Any]

Returns

Attribute values corresponding to attr_keys

load_skeleton(recompute=False)

Loader method of skeleton.

Parameters

recompute (bool) – Recompute the skeleton. Currently not implemented.

Return type

dict

Returns

Dict of flat arrays of indices, vertices, diameters and attributes.

load_views(woglia=True, raw_only=False, ignore_missing=False, index_views=False, view_key=None)

Loader method of views.

Parameters

• woglia (bool) – If True, looks for views without glia, i.e. after astrocyte separation.

• index_views (bool) – If True, refers to index views.

• view_key (Optional[str]) – Identifier of the requested views.

• raw_only (bool) – If True, ignores cell organelles projections.

• ignore_missing (bool) – If True, will not throw ValueError if views do not exist.

Returns

Views with requested properties.

load_voxel_list()

Loader method of voxel_list.

Returns

Sparse, 2-dimensional array of voxel coordinates.

load_voxel_list_downsampled(downsampling=(2, 2, 1))

load_voxel_list_downsampled_adapt(downsampling=(2, 2, 1))

load_voxels(voxel_dc=None)

Loader method of voxels.

Parameters

voxel_dc (Union[VoxelStorageDyn, VoxelStorage, None]) – Pre-loaded dictionary which contains the voxel data of this object.

Return type

ndarray

Returns

3D array of the all voxels which belong to this supervoxel.

load_voxels_downsampled(downsampling=(2, 2, 1))

property locations_path: str

Path to the rendering location storage.

Return type

str

lookup_in_attribute_dict(attr_key)

Returns

Parameters

attr_key (str) – Attribute key to look for.

Return type

Any

Returns

Value of attr_key in attr_dict or None if it does not exist. If key does not exist in attr_dict, tries to load from attr_dict_path.

mergelist2kzip(dest_path)

Writes the supervoxel agglomeration to a KNOSSOS compatible format.

Parameters

dest_path (str) – Path to k.zip file.

property mesh: Union[Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray], List[numpy.ndarray], Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]]

Mesh of this object. :returns: indices, vertices, normals. :rtype: Three flat arrays

mesh2kzip(dest_path, ext_color=None, ply_name='')

Write mesh to k.zip.

Parameters

• dest_path (str) – Path to the k.zip file which contains the mesh.

• ext_color (Union[Tuple[int, int, int, int], List, ndarray, None]) – If set to 0 no color will be written out. Use to adapt color inKnossos.

• ply_name (str) – Name of the ply file in the k.zip, must not end with .ply.

property mesh_area: float

Returns: Mesh surface area in um^2

Return type

float

property mesh_bb: numpy.ndarray

Bounding box of the object meshes (in nanometers). Approximately the same as scaled ‘bounding_box’.

Return type

ndarray

property mesh_caching: bool

If True, mesh data is cached.

Return type

bool

property mesh_exists: bool

Returns: True if mesh exists.

Return type

bool

mesh_from_scratch(ds=None, **kwargs)

Calculate the mesh based on get_object_mesh().

Parameters

• ds (Optional[Tuple[int, int, int]]) – Downsampling of the object’s voxel data.

• **kwargs – Key word arguments passed to triangulation().

Returns:

Return type

List[ndarray]

property mesh_path: str

Path to the mesh storage.

Return type

str

property mesh_size: float

Length of bounding box diagonal (BBD).

Return type

float

Returns

Diagonal length of the mesh bounding box in nanometers.

property n_folders_fs: int

Number of folders used to store the data of Defines the hierarchy of the folder structure organized by :class:`~SegmentationDataset.

Return type

int

Returns

The number of (leaf-) folders used for storing supervoxel data.

property rep_coord: numpy.ndarray

Representative coordinate of this SSV object. Will be the rep_coord of the first supervoxel in svs.

Return type

ndarray

Returns

1D array of the coordinate (XYZ).

sample_locations(force=False, save=True, ds_factor=None)

Getter method for the rendering locations of this supervoxel. Only valid for cell fragments, i.e. type must be sv.

Parameters

• force – Overwrite existing data.

• save – If True, saves the result at locations_path. Uses

:param CompressedStorage.: :param ds_factor: Down sampling factor used to generate the rendering locations.

Returns

Array of rendering locations (XYZ) with shape (N, 3) in nanometers!

property sample_locations_exist: bool

Returns: True if rendering locations have been stored at locations_path.

Return type

bool

save_attr_dict()

Saves attr_dict to attr:~attr_dict_path. Already existing dictionary will be updated.

save_attributes(attr_keys, attr_values)

Writes attributes to attribute storage. Ignores attr_dict. Values have to be serializable and will be written via the AttributeDict interface.

Parameters

• attr_keys (List[str]) – List of attribute keys which will be written to attr_dict_path.

• attr_values (List[Any]) – List of attribute values which will be written to attr_dict_path.

save_kzip(path, kd=None, write_id=None)

Write supervoxel segmentation to k.zip.

Parameters

• path (str) –

• kd (Optional[KnossosDataset]) –

• write_id (Optional[int]) – Supervoxel ID.

save_skeleton(overwrite=False)

Save method of skeleton.

Parameters

overwrite (bool) – Overwrite existing skeleton entry.

Returns

Flat arrays of indices, vertices, normals.

save_views(views, woglia=True, cellobjects_only=False, index_views=False, view_key=None, enable_locking=None)

Saves views according to its properties. If view_key is given it has to be a special type of view, e.g. spine predictions. If in this case any other kwarg is not set to default it will raise an error.

Parameters

• woglia (bool) – If True, looks for views without glia, i.e. after astrocyte separation.

• index_views (bool) – If True, refers to index views.

• view_key (Optional[str]) – Identifier of the requested views.

• views (ndarray) – View array.

• cellobjects_only (bool) – Only render cell organelles (deprecated).

• enable_locking (Optional[bool]) – Enable file locking.

property scaling

Voxel size in nanometers (XYZ). Default is taken from the config.yml file and accessible via self.config.

property segds_dir: str

Path to the ~syconn.reps.segmentation.SegmentationDataset directory.

Return type

str

property segobj_dir: str

Path to the folder where the data of this supervoxel is stored.

Return type

str

property shape: numpy.ndarray

The XYZ extent of this SSV object in voxels.

Return type

ndarray

Returns

The shape/extent of thiss SSV object in voxels (XYZ).

property size: int

Returns: Number of voxels.

Return type

int

property skeleton: dict

The skeleton representation of this supervoxel.

Returns

“nodes”, estimated node “diameters” and “edges”.

Return type

Dict of at least three numpy arrays

property skeleton_caching

If True, skeleton data is cached.

property skeleton_dict_path: str

Returns: Path to skeleton storage.

Return type

str

property skeleton_exists: bool

Returns: True if skeleton exists.

Return type

bool

property skeleton_path: str

Path to the skeleton storage.

Return type

str

property so_storage_path: str

Path to entry folder of the directory tree where all supervoxel data of the corresponding ~syconn.reps.segmentation.SegmentationDataset is located.

Return type

str

property so_storage_path_base: str

Base folder name.

Return type

str

split_component(dist, new_sd, new_id)

Parameters

• dist –

• new_sd –

• new_id –

Returns:

total_edge_length()

Total edge length of the supervoxel skeleton in nanometers.

Return type

Union[ndarray, float]

Returns

Sum of all edge lengths (L2 norm) in skeleton.

property type: str

The type of the supervoxel.

Examples

Keys which are currently used:

• ‘mi’: Mitochondria.

• ‘vc’: Vesicle clouds.

• ‘sj’: Synaptic junction.

• ‘syn_ssv’: Synapses between two

• ‘syn’: Synapse fragment between two SegmentationObject objects.

• ‘cs’: Contact site.

Can be used to initialized single SegmentationObject object of a specific type or the corresponding dataset collection handled with the SegmentationDataset class:

from syconn.reps.segmentation import SegmentationObject, SegmentationDataset
cell_sv = SegmentationObject(obj_id=.., obj_type='sv', working_dir='..')
cell_sv.load_attr_dict()  # populates `cell_sv.attr_dict`

cell_sd = SegmentationDataset(obj_type='sv', working_dir='..')
cell_sv_from_sd = cell_sd.get_segmentation_object(obj_id=cell_sv.id)
cell_sv_from_sd.load_attr_dict()

keys1 = set(cell_sv.attr_dict.keys())
keys2 = set(cell_sv_from_sd.attr_dict.keys())
print(keys1 == keys2)

Return type

str

Returns

String identifier.

property version: str

Version of the SegmentationDataset this object belongs to.

Return type

str

Returns

String identifier of the object’s version.

property view_caching

If True, view data is cached.

view_path(woglia=True, index_views=False, view_key=None)

Path to the view storage.

Return type

str

views(woglia, index_views=False, view_key=None)

Getter method for the views of this supervoxel. Only valid for cell fragments, i.e. type must be sv.

Parameters

• woglia (bool) – If True, looks for views without glia, i.e. after astrocyte separation.

• index_views (bool) – If True, refers to index views.

• view_key (Optional[str]) – Identifier of the requested views.

Return type

Union[ndarray, int]

Returns

The requested view array or -1 if it does not exist.

views_exist(woglia, index_views=False, view_key=None)

True if rendering locations have been stored at view_path().

Parameters

• woglia (bool) – If True, looks for views without glia, i.e. after astrocyte separation.

• index_views (bool) – If True, refers to index views.

• view_key (Optional[str]) – Identifier of the requested views.

Return type

bool

property voxel_caching: bool

If True, voxel data is cached after loading.

Return type

bool

property voxel_list: numpy.ndarray

Voxels associated with this SSV object.

Return type

ndarray

Returns

2D array with sparse voxel coordinates.

property voxel_path: str

Path to the voxel storage. See VoxelStorageDyn for details.

Return type

str

property voxels: numpy.ndarray

Voxels associated with this SSV object.

Return type

ndarray

Returns

3D binary array indicating voxel locations.

property voxels_exist: bool

Return type

bool

property working_dir: str

Working directory.

Return type

str

syconn.reps.segmentation_helper module

syconn.reps.segmentation_helper.acquire_obj_ids(sd)

Acquires all obj ids present in the dataset. Loads id array if available. Assembles id list by iterating over all voxel / attribute dicts, otherwise (very slow).

syconn.reps.segmentation_helper.calc_center_of_mass(point_arr)

Parameters

point_arr (ndarray) – Array of points (in nm or at least isotropic).

Return type

ndarray

Returns

Closest point in point_arr to its center of mass.

syconn.reps.segmentation_helper.find_missing_sv_attributes(sd, attr_key, n_cores=20)

Parameters

• sd (SegmentationDataset) –

• attr_key (str) – str

• n_cores (int) – int

Returns:

syconn.reps.segmentation_helper.find_missing_sv_skeletons(svs, n_cores=20)

syconn.reps.segmentation_helper.find_missing_sv_views(sd, woglia, n_cores=20)

syconn.reps.segmentation_helper.generate_skeleton_sv(so)

Poor man’s solution to generate a SV “skeleton”. Used for glia predictions.

Parameters

so (SegmentationObject) –

Return type

Dict[str, ndarray]

Returns

Dictionary with keys “nodes”, “edges” and “diameters” (all 1).

syconn.reps.segmentation_helper.get_sd_load_distribution(sd, use_vxsize=True)

Get the load distribution (number of objects per storage) of the SegmentationDataset’s AttributeDicts.

Parameters

• sd (SegmentationDataset) – SegmentationDataset

• use_vxsize (bool) –

Return type

ndarray

Returns

Load array.

syconn.reps.segmentation_helper.glia_pred_so(so, thresh, pred_key_appendix)

Perform the glia classification of a cell supervoxel (0: neuron, 1: glia).

Parameters

• so (SegmentationObject) – The cell supervoxel object.

• thresh (float) – Threshold used for the classification.

• pred_key_appendix (str) – Additional prediction key.

Returns:

Return type

int

syconn.reps.segmentation_helper.glia_proba_so(so, pred_key_appendix)

Get mean glia probability of a cell supervoxel (0: neuron, 1: glia).

Parameters

• so (SegmentationObject) – The cell supervoxel object.

• pred_key_appendix (str) – Additional prediction key.

Returns:

Return type

float

syconn.reps.segmentation_helper.load_mesh(so, recompute=False)

Load mesh of SegmentationObject. TODO: Currently ignores potential color/label array.

Parameters

• so (SegmentationObject) – SegmentationObject

• recompute (bool) – bool

Return type

Union[Tuple[ndarray, ndarray, ndarray], List[ndarray], Tuple[ndarray, ndarray, ndarray, ndarray]]

Returns

indices, vertices, normals; all flattened

syconn.reps.segmentation_helper.load_skeleton(so, recompute=False)

Parameters

• so (SegmentationObject) – SegmentationObject

• recompute (bool) – Compute skeleton, will not store it in SkeletonStorage.

Return type

dict

Returns

Dictionary with “nodes”, “diameters” and “edges”.

syconn.reps.segmentation_helper.load_so_attr_bulk(sos, attr_keys, use_new_subfold=True, allow_missing=False)

Bulk loader for SegmentationObject (SO) meshes. Minimizes IO by loading IDs from the same storage at the same time. Returns a single dict if only one attr_key is provided or a dict of dicts if many. This method will also check if the requested attribute(s) already exist in the object’s attr_dict. This means using cache_properties when initializing SegmentationDataset might be beneficial to avoid exhaustive file reads in case sos is large.

Parameters

• sos (List[ForwardRef]) – SegmentationObjects

• attr_keys (Union[str, Iterable[str]]) – Attribute key(s).

• use_new_subfold (bool) – Use new sub-folder structure

• allow_missing (bool) – If True, sets attribute value to None if missing. If False and missing, raise KeyError.

Returns

attr_key of) dict. with key: ID, value: attribute value

Return type

(Dict. with key

syconn.reps.segmentation_helper.load_so_meshes_bulk(sos, use_new_subfold=True, cache_decomp=True)

Bulk loader for SegmentationObject (SO) meshes. Minimizes IO by loading IDs from the same storage at the same time. This will not assign the _mesh attribute!

Parameters

• sos (Union[List[ForwardRef], Iterable[ForwardRef]]) – SegmentationObjects

• use_new_subfold (bool) – Use new sub-folder structure

• cache_decomp – Cache decompressed meshes.

Returns

ID, value: mesh

Return type

Dictionary, key

syconn.reps.segmentation_helper.load_so_voxels_bulk(sos, use_new_subfold=True, cache_decomp=True)

Parameters

• sos (List[ForwardRef]) –

• use_new_subfold (bool) –

• cache_decomp –

Returns:

syconn.reps.segmentation_helper.load_voxel_list(so)

Helper function to load voxels of a SegmentationObject.

Parameters

so (SegmentationObject) – SegmentationObject.

Returns: np.array

2D array of coordinates to all voxels in SegmentationObject.

Return type

ndarray

syconn.reps.segmentation_helper.load_voxel_list_downsampled(so, downsampling=(2, 2, 1))

TODO: refactor, probably more efficient implementation possible.

Parameters

• so – SegmentationObject

• downsampling – Tuple[int]

Returns:

syconn.reps.segmentation_helper.load_voxel_list_downsampled_adapt(so, downsampling=(2, 2, 1))

syconn.reps.segmentation_helper.load_voxels_depr(so, voxel_dc=None)

Helper function to load voxels of a SegmentationObject as 3D array. Also calculates size and bounding box and assigns it to so._size and so._bounding_box respectively.

Parameters

• so (SegmentationObject) – SegmentationObject

• voxel_dc (Optional[VoxelStorage]) – VoxelStorage

Returns: np.array

3D binary mask array, 0: background, 1: supervoxel locations.

Return type

ndarray

syconn.reps.segmentation_helper.load_voxels_downsampled(so, ds=(2, 2, 1))

Return type

Union[ndarray, List]

syconn.reps.segmentation_helper.prepare_so_attr_cache(sd, so_ids, attr_keys)

Parameters

• sd (SegmentationDataset) – SegmentationDataset.

• so_ids (ndarray) – SegmentationObject IDs for which to collect the attributes.

• attr_keys (List[str]) – Attribute keys to collect. Corresponding numyp arrays must exist.

Return type

Dict[str, dict]

Returns

Dictionary with attr_keys as keys and an attribute dictionary as values for the IDs so_ids, e.g. attr_cache[attr_keys[0]][so_ids[0]] will return the attribute value of type attr_keys[0] for the first SegmentatonObect in so_ids.

syconn.reps.segmentation_helper.save_skeleton(so, overwrite=False)

Parameters

• so (SegmentationObject) –

• overwrite (bool) –

Returns:

syconn.reps.segmentation_helper.save_voxels(so, bin_arr, offset, overwrite=False)

Helper function to save SegmentationObject voxels.

Parameters

• so (SegmentationObject) – SegmentationObject

• bin_arr (ndarray) – np.array Binary mask array, 0: background, 1: supervoxel locations.

• offset (ndarray) – np.array

• overwrite (bool) – bool

Returns:

syconn.reps.segmentation_helper.sv_attr_exists(args)

syconn.reps.segmentation_helper.sv_skeleton_missing(sv)

syconn.reps.segmentation_helper.sv_view_exists(args)

syconn.reps.super_segmentation module

syconn.reps.rep_helper module

class syconn.reps.rep_helper.SegmentationBase

Bases: object

syconn.reps.rep_helper.assign_rep_values(target_coords, rep_coords, rep_values, nb_cpus=- 1, return_ixs=False)

Assigns values corresponding to representative coordinates to every target coordinate.

Parameters

• target_coords (np.array) – [N, 3]

• rep_coords (np.array) – [M ,3]

• rep_values (np.array) – [M, Z] any type of values for each rep_coord.

• nb_cpus (int) –

• return_ixs (bool) – returns indices of k-closest rep_coord for every target coordinate

Returns

np.array [N, Z]

representation values for every vertex

syconn.reps.rep_helper.colorcode_vertices(vertices, rep_coords, rep_values, colors=None, nb_cpus=- 1, k=1, return_color=True)

Assigns all vertices the kNN majority label from rep_coords/rep_values and if return_color is True assigns those a color. Helper function to colorcode a set of coordinates (vertices) by known labels (rep_coords, rep_values).

Parameters

• vertices (np.array) – [N, 3]

• rep_coords (np.array) – [M ,3]

• rep_values (np.array) – [M, 1] int values to be color coded for each vertex; used as indices for colors

• colors (list) – color for each rep_value

• nb_cpus (int) –

• k (int) – Number of nearest neighbors (average prediction)

• return_color (bool) – If false it returns the majority vote for each index

Returns

np.array [N, 4]

rgba values for every vertex from 0 to 255

syconn.reps.rep_helper.get_unique_subfold_ixs(n_folders)

Returns unique IDs each associated with a unique storage dict

Parameters

n_folders (int) –

Returns

np.ndarray

syconn.reps.rep_helper.ix_from_subfold(subfold, n_folders)

Parameters

• subfold –

• n_folders –

Returns

Return type

int

syconn.reps.rep_helper.ix_from_subfold_OLD(subfold, n_folders)

Parameters

subfold (str) –

Returns

Return type

int

syconn.reps.rep_helper.ix_from_subfold_new(subfold, n_folders)

Parameters

subfold (str) –

Returns

Return type

int

syconn.reps.rep_helper.knossos_ml_from_ccs(cc_ixs, ccs, coords=None, comments=None)

Converts list of connected components (i.e. list of SV IDs) into knossos merge list string.

Parameters

• cc_ixs (Union[List[int], ndarray]) – Connected component IDs, i.e. super-supervoxel IDs.

• ccs (List[List[int]]) – Supervoxel IDs for every connected component.

• coords (Optional[ndarray]) – Coordinates to each connected component (in voxels).

• comments (Optional[List[str]]) – Comments for each connected component.

Return type

str

Returns

A KNOSSOS compatible merge list in string representation.

syconn.reps.rep_helper.knossos_ml_from_sso(sso, comment=None)

Converts the sueprvoxels which are part of the sso into a KNOSSOS compatible merge list string.

Parameters

• sso (SuperSegmentationObject) – SuperSegmentationObject object.

• comment (Optional[str]) – Comment.

Returns

A KNOSSOS compatible merge list in string representation.

syconn.reps.rep_helper.knossos_ml_from_svixs(sv_ixs, coords=None, comments=None)

Generate a KNOSSOS merge list of an array of supervoxels with optional coordinates and comments.

Parameters

• sv_ixs (Union[ndarray, List]) – Supervoxel IDs.

• coords (Union[ndarray, List[ndarray], None]) – Representative coordinates of each supervoxel (in voxels).

• comments (Union[ndarray, List[str], None]) – Comments for each supervoxel.

Return type

str

Returns

A KNOSSOS compatible merge list in string representation.

syconn.reps.rep_helper.subfold_from_ix(ix, n_folders, old_version=False)

# TODO: remove ‘old_version’ as soon as possible, currently there is one usage

Parameters

• ix (int) –

• n_folders (int) –

Returns

Return type

str

syconn.reps.rep_helper.subfold_from_ix_OLD(ix, n_folders, old_version=False)

# TODO: remove ‘old_version’ as soon as possible, currently there is one usage

Parameters

• ix (int) –

• n_folders (int) –

Returns

Return type

str

syconn.reps.rep_helper.subfold_from_ix_SSO(ix)

Parameters

ix (int) –

Returns

Return type

str

syconn.reps.rep_helper.subfold_from_ix_new(ix, n_folders)

Parameters

• ix (int) –

• n_folders (int) –

Returns

Return type

str

syconn.reps.rep_helper.surface_samples(coords, bin_sizes=(2000, 2000, 2000), max_nb_samples=5000, r=1000)

‘TODO: optimization required – maybe use simple downsampling instead of histogram Sample locations from density grid given by coordinates and bin sizes. At each grid center, collects coordinates within the given radius to calculate the center of mass which yields the sample location.

Parameters

• coords (np.array) –

• bin_sizes (np.array) –

• max_nb_samples (int | None) –

• r (int) –

Return type

ndarray

Returns

np.array