API Documentation¶

Atlas¶

Access to VoxelBrain.

https://nip.humanbrainproject.eu/documentation/user-manual.html#voxel-brain

class voxcell.nexus.voxelbrain.Atlas[source]¶

Helper class for atlas access.

abstract fetch_data(data_type)[source]¶: Fetch data_type NRRD.

abstract fetch_hierarchy()[source]¶: Fetch brain region hierarchy JSON.

get_region_mask(value, attr='acronym', with_descendants=True, ignore_case=False, memcache=False)[source]¶: Get VoxelData with 0/1 mask indicating regions matching value.

load_data(data_type, cls=<class 'voxcell.voxel_data.VoxelData'>, memcache=False)[source]¶: Load atlas data layer.

load_region_map(memcache=False)[source]¶: Load brain region hierarchy as RegionMap.

static open(url, cache_dir=None)[source]¶: Get Atlas object to access atlas stored at URL.

class voxcell.nexus.voxelbrain.LocalAtlas(dirpath)[source]¶

Helper class for locally stored atlas.

fetch_data(data_type)[source]¶: Return filepath to data_type NRRD.

fetch_hierarchy()[source]¶: Return filepath to brain region hierarchy JSON.

fetch_metadata()[source]¶: Return filepath to metadata JSON.

get_layer(layer_index)[source]¶

Retrieve the identifiers of a specified layer in laminar brain region.

Given a layer of an annotated brain volume, the function returns the set of identifiers of all regions included in this layer.

Note: this function relies on the existence of the files

hierarchy.json
metadata.json

The content of metadata.json must be of the following form:

{
    ...
    "layers": {
        "names": [
            "layer 1", "layer 2/3", "layer 4", "layer 5", "layer 6", "Olfactory areas"
        ],
        "queries": ["@.*1$", "@.*2/3$", "@.*4$", "@.*5$", ".*6[a|b]?$", "OLF"],
        "attribute": "acronym"
    },
    ...
}

The strings of the queries list are in one-to-one correspondence with layer names. The layer names list is a user-defined string list which can vary depending on which hierarchy.json is used and which brain region is under scrutiny. Each query string is used to retrieve the region identifiers of the corresponding layer by means of the Atlas RegionMap object instantiated from the hierarchy.json file. The syntax of a query string is the same as the one in use for RegionMap.find: if the string starts with the symbol ‘@’, the remainder is interpreted as a regular expression. Otherwise it is a plain string value and RegionMap.find looks for a character-wise full match. The value of attribute is acronym or name. This unique value applies for every query string.

Returns: tuple (name, ids) where name is the name of the layer (str) with index

layer_index and ids is the set of region identifiers of every region in this layer according to hierarchy.json.

Raises: VoxcellError

if the hierarchy file or the metadata file doesn’t exist.
if metadata.json doesn’t contain the key “layers”
if the value of “layers” doesn’t contain all the required keys:
“names”, “queries” and “attribute”.
if the value of “names” or “ids” is not a list, or if these objects are two lists
of different lengths.

get_layer_volume(memcache=False)[source]¶

Get VoxelData whose voxels are labeled with the layer indices of brain_regions voxels.

Layer indices range from 1 to number of layers - 1. The layers of the atlas are defined within metadata.json as a list of RegionMap.find query strings.

If two layer definitions in metadata.json involve the same region identifier, the voxels bearing this identifier will be labled with the largest layer index.

Parameters:: memcache – If True, use cache, Otherwise re-compute the layer volume. Defaults to False.
Returns:: VoxelData object with the same shape and same metadata as brain_regions. Voxels have uint8 labels (char type) and each voxel label corresponds to the voxel layer index.

get_layers()[source]¶

Retrieve and cache the identifiers of each layer of a laminar brain region.

For each layer of an annotated brain volume, the function returns the set of identifiers of all regions included in this layer.

Note: this function relies on the existence of the files

hierarchy.json
metadata.json

See get_layer for the description of the metadata.json file.

Returns: tuple (names, ids) where names is a list of layer names where ids is a list

of sets and. Each set contains the identifiers (ints) of the corresponding layer name (str).

Raises: VoxcellError

if the hierarchy file or the metadata file doesn’t exist.
if metadata.json doesn’t contain the key “layers”
if the value of “layers” doesn’t contain all the required keys:
“names”, “queries” and “attribute”.
if the value of “names” or “ids” is not a list, or if these objects are two lists
of different lengths.

load_metadata(memcache=False)[source]¶: Load brain region metadata as dict.

class voxcell.nexus.voxelbrain.VoxelBrainAtlas(url, cache_dir)[source]¶

Helper class for VoxelBrain atlas.

fetch_data(data_type)[source]¶: Fetch data_type NRRD.

fetch_hierarchy()[source]¶: Fetch brain region hierarchy JSON.

Traits¶

Library to handle traits fields and collections and the logic to assign them.

A “trait” is a set of properties and their values. A “traits collection” is a group of traits. It’s represented as a pandas DataFrame object where each trait is a row and each property is a column. For example:

   sclass      mtype
INH         Pyramidal
EXC         Pyramidal
INH         Martinotti

A “probability distribution” specifies the probability of each trait in a collection being assigned to a given cell. A “distributions collection” is a group of distributions. It’s represented as a pandas DataFrame object where each trait is a row and each distribution is a column. For example:

   1    2     3
0.25  0.5  0.5   0.0
0.75  0.5  0.25  0.1
0.0   0.0  0.25  0.9

The distribution number 3 in the above table indicates 10% chances of picking the trait 1 (an excitatory Pyramidal cell) and 90% of picking trait 2 (an inhibitory Martinotti cell).

class voxcell.traits.SpatialDistribution(field, distributions, traits)[source]¶

Encapsulates the data relative to the 3D probability distributions of traits.

Parameters:

field – VoxelData where every voxel is an index in the distributions list -1 means unavailable data.
distributions – a distributions collection, see module docstring
traits – a traits collection, see module docstring

assign(positions)[source]¶

For every cell in positions, chooses a property from a spatial distribution.

Parameters:: positions – list of positions for soma centers (x, y, z).
Returns:: An array with the same length as positions where each value is an index into spatial_dist.traits

assign_conditional(positions, preassigned)[source]¶

For every cell in positions, choose a property from a spatial distribution.

For every cell in positions, choose a property from a spatial distribution, but taking into account a pre-assigned values of related properties.

Parameters:

positions – list of positions for soma centers (x, y, z).
preassigned – pandas.DataFrame or pandas.Series with the pre-assigned values.

Returns:

An array with the same length as positions where each value is an index into spatial_dist.traits

For those positions whose value could not be determined, -1 is used.

collect(positions, preassigned=None, names=None)[source]¶

For every cell in positions, chose trait values from a spatial distribution.

For every cell in positions, chose trait values from a spatial distribution, taking into account a pre-assigned values of related properties (if specified).

Parameters:

positions – list of positions for soma centers (x, y, z).
preassigned – pandas.DataFrame or pandas.Series with the pre-assigned values.
names – names of the properties to collect. If not specified use all in traits.

Returns:

A pandas DataFrame with one row for each index and one column for each value of names

collect_traits(chosen, names=None)[source]¶

Return the trait values corresponding to an array of indices.

Parameters:

chosen – array of indices into the traits dataframe
names – names of the properties to collect. If not specified use all in traits.

Returns:

A pandas DataFrame with one row for each index and one column for each value of names

drop_duplicates(decimals=None)[source]¶

Return a new SpatialDistribution with duplicate distributions removed.

Parameters:: decimals – Number of decimal places to round each column to beforehand.

classmethod from_probability_field(probs_field, name, positive_value, negative_value)[source]¶

Creates a binary SpatialDistribution object from a single probability field.

Parameters:

probs_field – A VoxelData where every voxel is a float representing the probability of an attribute value being assigned to a cell in that voxel. For voxels with unknown values -1 is used.
name – name of the trait.
positive_value – value of the trait that corresponds to probs_field.
negative_value – value of the trait that corresponds to the probability field complementary to probs_field.

Returns:

A SpatialDistribution object

get_probability_field(attribute, value)[source]¶

Extract the probability of a particular attribute value from a spatial distribution.

Voxels where the probability is missing will contain a probability value of -1.

Returns:: A VoxelData with the same shape as sdist.field where every voxel is a float representing the probability of an attribute value being assigned to a cell in that voxel. For voxels with unknown values -1 is used.

reduce(attribute)[source]¶

Return a SpatialDistribution with only the given attribute.

Given a spatial distribution, extract an equivalent one where all of the properties of the traits collection have been removed except for a specific one.

For example, taking the traits collection:

   sclass      mtype
INH         Pyramidal
EXC         Pyramidal
INH         Martinotti

and the distributions collection:

Ignoring all properties except ‘sclass’ would give the simplified traits collection:

   sclass
0  INH
1  EXC

and the distributions collection:

   0
0  0.6
1  0.4

Note that because for every distribution we are creating a new one, the indexes of any associated field are still valid.

Returns:: An SpatialDistribution object

split(attributes)[source]¶

Split a distribution in two or more.

Split a distribution in two or more so that each one only references traits with the same value for certain attributes. Each resulting distribution is renormalised.

this may be generating distributions that are empty but that should not be a problem

Note that because for every distribution we are creating a new one, the indexes of any associated field are still valid.

Returns:: A dictionary where the keys are tuples with the values of the attributes found in the traits_collection and the values are the resulting SpatialDistribution objects.

CellCollection¶

Cell collection access / writer.

class voxcell.cell_collection.CellCollection(population_name='default', orientation_format='quaternions')[source]¶

Encapsulates all the data related to a collection of cells that compose a circuit.

Multi-dimensional properties (such as positions and orientations) are attributes. General properties are a in a pandas DataFrame object “properties”.

add_properties(new_properties, overwrite=True)[source]¶

Adds new columns to the properties DataFrame.

Parameters:

new_properties – a pandas DataFrame object
overwrite – if True, overwrites columns with the same name.
Otherwise –
raised. (a VoxcellError is) –

as_dataframe()[source]¶: Return a dataframe with all cell properties.

classmethod from_dataframe(df)[source]¶: Return a CellCollection object from a dataframe of cell properties.

classmethod load(filename)[source]¶

Loads CellCollection from a file.

Parameters:: filename – filepath to cells file. If it ends with ‘.mvd3’ then it is treated as MVD3 circuit, otherwise as SONATA.
Returns:: loaded cells
Return type:: CellCollection

classmethod load_mvd2(filename)[source]¶

Load a cell collection from mvd2 HDF5.

This method is a copy of loadMVD2 from bluepy/v2/impl/cells_mvd.py

Parameters:: filename (str) – fullpath to filename to read
Returns:: CellCollection object

classmethod load_mvd3(filename)[source]¶

Load a cell collection from mvd3 HDF5.

Parameters:: filename (str) – fullpath to filename to read
Returns:: CellCollection object

classmethod load_sonata(filename, population_name=None)[source]¶

Loads a cell collection from sonata HDF5.

Parameters:: filename (str) – fullpath to filename to read
Returns:: CellCollection object

property orientation_format¶: Return the format of the orientation either “eulers” or “quaternions”.

remove_unassigned_cells()[source]¶: Remove cells with one or more unassigned property.

save(filename)[source]¶

Saves this cell collection to HDF5 file in MVD3 or SONATA format.

Parameters:: filename – filepath to write. If it ends with ‘.mvd3’ then it is treated as MVD3, otherwise as SONATA.

save_mvd3(filename)[source]¶

Save this cell collection to mvd3 HDF5.

Parameters:: filename (str) – fullpath to filename to write

save_sonata(filename, forced_library=None, mode='w')[source]¶

Save this cell collection to sonata HDF5.

Parameters:

filename (str) – fullpath to filename to write
forced_library (iterable of str) – names of properties that are
@library (forced to become part of the) –
mode (str) – mode used to create/open file; passed directly to h5py.File: ‘w’ overwrites, ‘a’ appends

Note

Only properties that contain strings can be included in the @library
when forced_library is None, properties that are categorical are included in the @library, unless their number of unique values is more than half of all the values

size()[source]¶

Return the size of the CellCollection.

If the positions, orientations or properties are filled with values it checks the sizes of these objects and then return the size of the CellCollection.

VoxelData¶

Access to volumetric data.

class voxcell.voxel_data.OrientationField(*args, **kwargs)[source]¶

Volumetric data with rotation per voxel.

See also

Orientation Field File Format in the documentation

lookup(positions)[source]¶

Orientations corresponding to the given positions.

Parameters:: positions – list of positions (x, y, z).
Returns:: Numpy array with the rotation matrices corresponding to each position.

class voxcell.voxel_data.ROIMask(*args, **kwargs)[source]¶: Volumetric data defining 0/1 mask.

See also

Mask Image for Region of Interest (ROI) in the documentation

class voxcell.voxel_data.ValueToIndexVoxels(values)[source]¶

Efficient access to indices of unique values of the values array.

Useful for when one has an “annotations volume” or “brain region volume” that has regions indicated by unique values, and these are used to create masks. Often, it’s faster to avoid mask creation, and use indices directly

Example

# To calculate the cell count based on densities of a certain ID in the brain_regions volume vtiv = ValueToIndexVoxels(brain_regions.raw) density_copy = vtiv.ravel(density.raw.copy()) indices = vtiv.value_to_1d_indices(value=id_) cell_count = np.sum(density_copy[indices]) * voxel_volume)

property index_dtype¶: Return the dytpe of the index values.

property index_size¶: Return the size of the unique index values.

ravel(voxel_data)[source]¶: Ensure voxel_data matches the layout that the 1D indices can be used.

unravel(raveled_voxel_array)[source]¶: Ensure raveled_voxel_array is reshaped with the contiguous order used to be raveled.

value_to_1d_indices(value)[source]¶

Return the indices array corresponding to the ‘value’.

Note: These are 1D indices, so the assumption is they are applied to a volume who has been ValueToIndexVoxels::ravel(volume)

value_to_indices(values)[source]¶

Return the ND-indices array corresponding to the ‘values’.

This can be convenient to get the positions of the given values in the VoxelData space:: raw = np.array([[11, 12], [21, 22]]) v = VoxelData(raw, voxel_dimensions=(2, 3), offset=np.array([2, 2])) vtiv = ValueToIndexVoxels(v.raw) positions = v.indices_to_positions(vtiv.value_to_indices(11))
Note: The given ‘values’ can be given as one scalar value or as a list of values. In both: case a list of ND-indices will be returned.

property values¶: Unique values that are found in the original volume.

class voxcell.voxel_data.VoxelData(raw, voxel_dimensions, offset=None)[source]¶

Wrap volumetric data and some basic metadata.

property bbox¶: Bounding box.

clip(bbox, na_value=0, inplace=False)[source]¶

Assign na_value to voxels outside of axis-aligned bounding box.

Parameters:

bbox – bounding box in real-world coordinates
na_value – value to use for voxels outside of bbox
inplace (bool) – modify data inplace

Returns:

None if inplace is True, new VoxelData otherwise

compact(na_values=(0,), inplace=False)[source]¶

Reduce size of raw data by clipping N/A values.

Parameters:

na_values (tuple) – values to clip
inplace (bool) – modify data inplace

Returns:

None if inplace is True, new VoxelData otherwise

count(values)[source]¶

Number of voxels with value from the given list.

values could be a single value or an iterable.

filter(predicate, inplace=False)[source]¶

Set values for voxel positions not satisfying predicate to zero.

Parameters:

predicate – N x k [float] -> N x 1 [bool]
inplace (bool) – modify data inplace

Returns:

None if inplace is True, new VoxelData otherwise

indices_to_positions(indices)[source]¶

Return positions within given voxels.

Use fractional indices to obtain positions within voxels (for example, index (0.5, 0.5) would give the center of voxel (0, 0)).

classmethod load_nrrd(nrrd_path)[source]¶

Read volumetric data from a nrrd file.

Parameters:: nrrd_path (str|pathlib.Path) – path to the nrrd file.

lookup(positions, outer_value=None)[source]¶

Find the values in raw corresponding to the given positions.

Parameters:

positions – list of positions (x, y, z).
outer_value – value to be returned for positions outside the atlas space. If None, a VoxcellError is raised in that case.

Returns:

Numpy array with the values of the voxels corresponding to each position.

property ndim¶: Number of dimensions.

property payload_shape¶: Shape of the data stored per voxel.

positions_to_indices(positions, strict=True, keep_fraction=False)[source]¶

Take positions, and the index of the voxel to which they belong.

Parameters:

positions (np.array of Nx3) – positions in voxel volume
strict (bool) – raise VoxcellError if any of the positions are out of bounds
keep_fraction (bool) – keep the fractional portion of the positions

Returns:

np.array(Nx3) with the voxels coordinates corresponding to each position.

static reduce(function, iterable)[source]¶

Return a VoxelData by reducing the raw contents of the VoxelData objects in iterable.

Note: if iterable contains only one item, a copy is returned (but function is not applied)

Parameters:

function (Callable[[np.array, np.array], np.array]) – the function to be applied to numpy arrays
iterable (Sequence[VoxelData]) – a sequence of VoxelData objects

save_nrrd(nrrd_path, encoding=None)[source]¶

Save a VoxelData to an nrrd file.

Parameters:

nrrd_path (string|pathlib.Path) – full path to nrrd file
encoding (string) – encoding option to save as

property shape¶: Number of voxels in each dimension.

volume(values)[source]¶

Total volume of voxels with value from the given list.

values could be a single value or an iterable.

property voxel_volume¶: Voxel volume.

with_data(raw)[source]¶: Return VoxelData of the same shape with different data.

voxcell.voxel_data.values_to_hemisphere(values)[source]¶

Convert integer values 0, 1, 2 to “undefined”, “left” and “right” hemisphere labels.

It can be used to convert the values retrieved with VoxelData.lookup.

Parameters:: values – numpy array containing the values to be converted.
Returns:: Numpy array with the converted values.
Raises:: VoxcellError – if any of the values is invalid.

See also

Scalar Image File Format in the documentation

voxcell.voxel_data.values_to_region_attribute(values, region_map, attr='acronym')[source]¶

Convert region ids to the corresponding region attribute.

It can be used to convert the values retrieved with VoxelData.lookup().

Parameters:

values (np.array) – array containing the values to be converted.
region_map (RegionMap) – instance used to map values to region acronyms.
attr (str) – attribute name to lookup.

Returns:

Numpy array with the converted values.

Raises:

VoxcellError – if the attribute or any region id is not found.

See also

Scalar Image File Format in the documentation

Utils¶

Helper mathematical functions.

voxcell.math_utils.angles_to_matrices(angles, axis)[source]¶

Convert rotation angles around axis to 3x3 rotation matrices.

Parameters:

angles – (N,) array of rotation angles (radian)
axis – one of (‘x’, ‘y’, ‘z’)

Returns:

(N, 3, 3) array of rotation matrices.

voxcell.math_utils.clip(mask, aabb)[source]¶

Take a numpy array and clip it to an axis-aligned bounding box.

Parameters:

mask – numpy array
aabb – tuple of two sets of coordinates indicating, respectively, the lowest and highest values for each dimension

Returns:

A new numpy array containing the same values as mask for the space defined by aabb

voxcell.math_utils.euler2mat(az, ay, ax)[source]¶

Build 3x3 rotation matrices from az, ay, ax rotation angles (in that order).

Parameters:

az – rotation angles around Z (Nx1 NumPy array; radians)
ay – rotation angles around Y (Nx1 NumPy array; radians)
ax – rotation angles around X (Nx1 NumPy array; radians)

Returns:

List with 3x3 rotation matrices corresponding to each of N angle triplets.

voxcell.math_utils.gcd(a, b)[source]¶: Return greatest common divisor.

voxcell.math_utils.is_diagonal(matrix)[source]¶: Check if the matrix is diagonal.

voxcell.math_utils.isin(a, values)[source]¶

Naive NumPy.isin analogue.

For our usecases (>10^9 non-unique elements in a, <10^2 unique elements in tested values), NumPy.isin() takes same amount of time, but is 3x more memory-hungry.

voxcell.math_utils.lcm(a, b)[source]¶: Return lowest common multiple.

voxcell.math_utils.lcmm(args)[source]¶: Return lcm of args.

voxcell.math_utils.mat2euler(mm)[source]¶

Decompose 3x3 rotation matrices into az, ay, ax rotation angles (in that order).

Parameters:: matrices. (List with 3x3 rotation) –
Returns:: rotation angles around Z (Nx1 NumPy array; radians) ay: rotation angles around Y (Nx1 NumPy array; radians) ax: rotation angles around X (Nx1 NumPy array; radians)
Return type:: az

voxcell.math_utils.minimum_aabb(mask)[source]¶

Calculate the minimum axis-aligned bounding box for a volume mask.

Returns:: A tuple containing the minimum x,y,z and maximum x,y,z

voxcell.math_utils.normalize(vs)[source]¶: Normalize array along last axis.

voxcell.math_utils.positions_minimum_aabb(positions)[source]¶

Calculate the minimum axis-aligned bounding box for a list of positions.

Returns:: A tuple containing the minimum x,y,z and maximum x,y,z

voxcell.math_utils.voxel_intersection(line_segment, data, return_sub_segments=False)[source]¶

Find voxels intersected by a given segment and cut the segment according to these voxels.

Parameters:

line_segment – The segment with the following form: [[x0, y0, z0], [x1, y1, z1]].
data – The VoxelData object.
return_sub_segments – If true the sub segments are also returned with the voxel indices.

Returns:

List of 3D indices. If return_sub_segments is True, the coordinates of the sub-segment points are returned.

Quaternions to matrices and vice versa.

voxcell.quaternion.matrices_to_quaternions(matrices)[source]¶

Build quaternions from an array of 3x3 rotation matrices.

Based on multibranch algorithm described here: http://www.euclideanspace.com/maths/geometry/rotations/conversions/matrixToQuaternion/index.htm

Parameters:: matrices – A Nx3x3 numpy array containing N rotation matrices.
Returns:: A Nx4 numpy array containing a unit quaternion for each rotation matrix. The quaternion components are stored as (x, y, z, w)

voxcell.quaternion.quaternions_to_matrices(q)[source]¶

Build 3x3 rotation matrices from an array of quaternions.

Based on algorigthm described here: http://www.euclideanspace.com/maths/geometry/rotations/conversions/quaternionToMatrix/index.htm

Parameters:

q – A Nx4 numpy array containing a quaternion for each rotation matrix.
as (The quaternion components are stored) –

Returns:

A Nx3x3 numpy array containing N rotation matrices.

Region hierarchy tree.

class voxcell.region_map.Matcher(value, ignore_case=False)[source]¶: Helper class for value search.

class voxcell.region_map.RegionMap[source]¶

Region ID <-> attribute mapping.

as_dataframe()[source]¶

Converts a region_map to a dataframe.

Returns:: pd.DataFrame with an index of the id of the node, and columns based on the data within the map, and a parent_id

Note: the ‘root’ node should have a parent value of -1

as_dict()[source]¶: Converts a region_map to a dict.

find(value, attr, ignore_case=False, with_descendants=False)[source]¶

Find IDs of the regions matching a given attribute.

Parameters:

value – attribute value to match
attr (str) – attribute of interest
ignore_case (bool) – ignore case (when comparing strings)
with_descendants (bool) – collect region IDs downwards the “lineage”

If value starts with ‘@’ symbol, value[1:] is used a regular expression. Any substring matching the regular expression would be matched; please used ‘^’ and ‘$’ for “starts with” or “ends with” restrictions.

Regular expressions can be used together with ignore_case.

Returns:

set of IDs of the regions matching the attribute - otherwise: set of region IDs matching the attribute + all their children recursively

Return type:

if with_descendants=False

Example

>>> rmap.find("@layer 1", attr='name', ignore_case=True, with_descendants=True)
set([1, 2, 4, 5])

classmethod from_dataframe(hierarchy_df)[source]¶

Converts a DataFrame to a region_map.

Note: the ‘root’ node should have a parent value of -1.

Note: if it is possible to cast all non-null values of a column with float dtype to int,: then it will be done.

classmethod from_dict(d)[source]¶: Construct RegionMap from a hierarchical dictionary.

get(_id, attr, with_ascendants=False)[source]¶

Get attribute value associated with region ID.

Parameters:

_id (int) – region ID of interest
attr (str) – attribute of interest
with_ascendants (bool) – collect attribute value upwards the “lineage”

Returns:

attribute value for given region ID - otherwise: list of values starting from the “bottom” hierarchy level towards “top”

Return type:

if with_ascendants=False

Raises:

- VoxcellError if either region ID or attribute key are can not be found –

Example

>>> rmap.get(315, 'name')
'Isocortex'

is_leaf_id(_id)[source]¶

Indicate whether or not the input identifier is a leaf of the hierarchy tree.

A leaf identifier is the identifier of a region with no children.

Parameters:: _id (int) – region identifier, i.e., an ‘id’ value in hierarchy.json.
Returns:: True, if is a leaf, False otherwise.
Raises:: VoxcellError if the identifier cannot be found. –

Example

>>> rmap.is_leaf_id(399)
True
>>> rmap.is_leaf_id(-10)
VoxcellError: Region ID not found: -10

classmethod load_json(filepath)[source]¶: Construct RegionMap from JSON file.

Note

If top-most object contains ‘msg’ field, Allen Brain Institute JSON layout is assumed.

Library to build, transform and handle fields of vectors and orientations.

A vector field is a volumetric dataset that expresses a 3D vector for each voxel. Vector fields are represented as 4D numpy arrays. The first three dimensions of the array represent space, the last dimension is always of size 3 and contains the three components (i, j, k) of the vector for that voxel.

An orientation field is a volumetric dataset that expresses a rotation matrix for each voxel. Orientation fields are represented as 5D numpy arrays. The first three dimensions of the array represent space, the fourth and fifth dimensions contain a 3x3 rotation matrix.

Note that although 3D is our main target, most of these functions should behave correctly for lower and higher dimensionality levels.

voxcell.vector_fields.combine_vector_fields(fields)[source]¶

Given a list of vector fields return an orientation field.

The vectors from the fields are treated as a new base and will be stored as column vectors so that the matrices of the resulting field (one per voxel) can be used to premultiply vectors for rotation.

Parameters:: fields – a list of vector fields. All of the fields are expected to have the same shape (AxBxCx3)
Returns:: A 5D numpy array representing an orientation field

voxcell.vector_fields.gaussian_filter(vf, sigma)[source]¶

Apply a gaussian filter to a vector field.

Note that filter is applied without normalizing the input or output.

Parameters:

vf – Vector field
sigma – scalar. Standard deviation for Gaussian kernel.

Returns:

The resulting vector field not normalized.

voxcell.vector_fields.join_vector_fields(vf0, *vfs)[source]¶

Performs an union of several vector fields.

A voxel on a vector field is considered “empty” if all of its components are zero.

Parameters:

vf0 – first vector field.
vfs – rest of vector fields. All of them must have the same shape.

voxcell.vector_fields.split_orientation_field(field)[source]¶: Given an orientation field return a list of vector fields.