bsb.topology package

Submodules

bsb.topology.partition module

Module for the Partition configuration nodes and its dependencies.

class bsb.topology.partition.AllenStructure(*args, _parent=None, _key=None, **kwargs)

Bases: NrrdVoxels

Partition based on the Allen Institute for Brain Science mouse brain region ontology, later referred as Allen Mouse Brain Region Hierarchy (AMBRH)

classmethod find_structure(id)

Find an Allen structure by name, acronym or ID.

Parameters:

id (str | int | float) – Query for the name, acronym or ID of the Allen structure.

Returns:

Allen structure node of the Allen ontology tree.

Return type:

dict

Raises:

NodeNotFoundError

get_node_name()

classmethod get_structure_idset(find)

Return the set of IDs that make up the requested Allen structure.

Parameters:

find (str | int) – Acronym or ID of the Allen structure.

Returns:

Set of IDs

Return type:

numpy.ndarray

classmethod get_structure_mask(find)

Returns the mask data delineated by the Allen structure.

Parameters:

find (str | int) – Acronym, Name or ID of the Allen structure.

Returns:

A boolean of the mask filtered based on the Allen structure.

Return type:

Callable[numpy.ndarray]

classmethod get_structure_mask_condition(find)

Return a lambda that when applied to the mask data, returns a mask that delineates the Allen structure.

Parameters:

find (str | int) – Acronym, Name or ID of the Allen structure.

Returns:

Masking lambda

Return type:

Callable[numpy.ndarray]

mask_only: bool

Flag to indicate no voxel data needs to be stored.

mask_source: NrrdDependencyNode

Path to the NRRD file containing the volumetric annotation data of the Partition.

struct_id: int

Id of the region to filter within the annotation volume according to the AMBRH.

If struct_id is set, then struct_name should not be set.

struct_name: str

Name or acronym of the region to filter within the annotation volume according to the AMBRH.

If struct_name is set, then struct_id should not be set.

voxel_size: int

Size of each voxel.

class bsb.topology.partition.Layer(*args, _parent=None, _key=None, **kwargs)

Bases: Rhomboid

Partition that occupies the full space of its containing region except on a defined axis, where it is limited.

This creates a stratum within the region along the chosen axis.

axis: Literal['x', 'y', 'z']

Axis along which the layer will be limited.

get_layout(hint)

Given a Layout as hint to begin from, create a Layout object that describes how this partition would like to be laid out.

Parameters:

hint (bsb.topology._layout.Layout) – The layout space that this partition should place itself in.

Returns:

The layout describing the space this partition takes up.

Return type:

bsb.topology._layout.Layout

get_node_name()

thickness: float

Thickness of the layer along its axis.

class bsb.topology.partition.NrrdVoxels(*args, _parent=None, _key=None, **kwargs)

Bases: Voxels

Voxel partition whose voxelset is loaded from an NRRD file.

By default it includes all the nonzero voxels in the file, but other masking conditions can be specified. Additionally, data can be associated to each voxel by inclusion of (multiple) source NRRD files.

get_mask()

Get the mask to apply on the sources’ data of the partition.

Returns:

A tuple of arrays, one for each dimension of the mask, containing the indices of the non-zero elements in that dimension.

get_node_name()

get_voxelset()

Creates a VoxelSet of the sources of the Partition that matches its mask.

Returns:

VoxelSet of the Partition sources.

keys: list[str]

List of names to assign to each source of the Partition.

mask_only: bool

Flag to indicate no voxel data needs to be stored.

mask_source: NrrdDependencyNode

Path to the NRRD file containing the volumetric annotation data of the Partition.

mask_value: int

Integer value to filter in mask_source (if it is set, otherwise sources/source) to create a mask of the voxel set(s) used as input.

source: NrrdDependencyNode

Path to the NRRD file containing volumetric data to associate with the partition.

If source is set, then sources should not be set.

sources: NrrdDependencyNode

List of paths to NRRD files containing volumetric data to associate with the Partition.

If sources is set, then source should not be set.

sparse: bool

Boolean flag to expect a sparse or dense mask.

If the mask selects most voxels, use dense, otherwise use sparse.

strict: bool

Boolean flag to check the sources and the mask sizes.

When the flag is True, sources and mask should have exactly the same sizes; otherwise, sources sizes should be greater than mask sizes.

voxel_size: int

Size of each voxel.

class bsb.topology.partition.Partition(*args, _parent=None, _key=None, **kwargs)

Bases: ABC

Abstract class to describe spatial containers for network pieces.

abstractmethod chunk_to_voxels(chunk)

Voxelize the partition’s occupation in this chunk. Required to fill the partition with cells by the placement module.

Parameters:

chunk (bsb.storage._chunks.Chunk) – The chunk to calculate voxels for.

Returns:

The set of voxels that together make up the shape of this partition in this chunk.

Return type:

bsb.voxels.VoxelSet

property data

abstractmethod get_layout(hint)

Given a Layout as hint to begin from, create a Layout object that describes how this partition would like to be laid out.

Parameters:

hint (bsb.topology._layout.Layout) – The layout space that this partition should place itself in.

Returns:

The layout describing the space this partition takes up.

Return type:

bsb.topology._layout.Layout

get_node_name()

name: str

Base implementation of all the different configuration attributes.

Call the factory function attr() instead.

property region

abstractmethod rotate(rotation)

Rotate the partition by the given rotation object.

Parameters:

rotation (scipy.spatial.transform.Rotation) – Rotation object.

Raises:

exceptions.LayoutError if the rotation needs to be rejected.

scaffold: Scaffold

abstractmethod scale(factors)

Scale up/down the partition according to the given factors.

Parameters:

factors (numpy.ndarray) – Scaling factors, XYZ.

Raises:

exceptions.LayoutError if the scaling needs to be rejected.

abstractmethod surface(chunk=None)

Calculate the surface of the partition in μm^2.

Parameters:

chunk (bsb.storage._chunks.Chunk) – If given, limit the surface of the partition inside of the chunk.

Returns:

Surface of the partition (in the chunk)

Return type:

float

abstractmethod to_chunks(chunk_size)

Calculate all the chunks this partition occupies when cut into chunk_sized pieces.

Parameters:

chunk_size (numpy.ndarray) – Size per chunk (in μm). The slicing always starts at [0, 0, 0].

Returns:

Chunks occupied by this partition

Return type:

list[bsb.storage._chunks.Chunk]

to_voxels()

Voxelize the partition’s occupation.

abstractmethod translate(offset)

Translate the partition by the given offset.

Parameters:

offset (numpy.ndarray) – Offset, XYZ.

Raises:

exceptions.LayoutError if the translation needs to be rejected.

type

Base implementation of all the different configuration attributes.

Call the factory function attr() instead.

abstractmethod volume(chunk=None)

Calculate the volume of the partition in μm^3.

Parameters:

chunk (bsb.storage._chunks.Chunk) – If given, limit the volume of the partition inside of the chunk.

Returns:

Volume of the partition (in the chunk)

Return type:

float

class bsb.topology.partition.Rhomboid(*args, _parent=None, _key=None, **kwargs)

Bases: Partition

Rectangular cuboid partition defined according to its origin and dimensions.

can_move: bool

Boolean flag to authorize the translation of the partition.

can_rotate: bool

Boolean flag to authorize the rotation of the partition.

can_scale: bool

Boolean flag to authorize rescaling of the partition dimensions.

chunk_to_voxels(chunk)

Return an approximation of this partition intersected with a chunk as a list of voxels.

Default implementation creates a parallelepiped intersection between the LDC, MDC and chunk data.

dimensions: list[float]

Sizes of the partition for each axis.

get_dependencies()

Return other partitions or regions that need to be laid out before this.

get_layout(hint)

Given a Layout as hint to begin from, create a Layout object that describes how this partition would like to be laid out.

Parameters:

hint (bsb.topology._layout.Layout) – The layout space that this partition should place itself in.

Returns:

The layout describing the space this partition takes up.

Return type:

bsb.topology._layout.Layout

get_node_name()

property ldc

Return the lowest coordinate of the partition.

property mdc

Return the highest coordinate of the partition.

orientation: list[float]

Base implementation of all the different configuration attributes.

Call the factory function attr() instead.

origin: list[float]

Coordinate of the origin of the partition.

rotate(rot)

Rotate the partition by the given rotation object.

Parameters:

rotation (scipy.spatial.transform.Rotation) – Rotation object.

Raises:

exceptions.LayoutError if the rotation needs to be rejected.

scale(factors)

Scale up/down the partition according to the given factors.

Parameters:

factors (numpy.ndarray) – Scaling factors, XYZ.

Raises:

exceptions.LayoutError if the scaling needs to be rejected.

surface(chunk=None)

Calculate the surface of the partition in μm^2.

Parameters:

chunk (bsb.storage._chunks.Chunk) – If given, limit the surface of the partition inside of the chunk.

Returns:

Surface of the partition (in the chunk)

Return type:

float

to_chunks(chunk_size)

Calculate all the chunks this partition occupies when cut into chunk_sized pieces.

Parameters:

chunk_size (numpy.ndarray) – Size per chunk (in μm). The slicing always starts at [0, 0, 0].

Returns:

Chunks occupied by this partition

Return type:

list[bsb.storage._chunks.Chunk]

translate(translation)

Translate the partition by the given offset.

Parameters:

offset (numpy.ndarray) – Offset, XYZ.

Raises:

exceptions.LayoutError if the translation needs to be rejected.

volume(chunk=None)

Calculate the volume of the partition in μm^3.

Parameters:

chunk (bsb.storage._chunks.Chunk) – If given, limit the volume of the partition inside of the chunk.

Returns:

Volume of the partition (in the chunk)

Return type:

float

class bsb.topology.partition.Voxels(*args, _parent=None, _key=None, **kwargs)

Bases: Partition, ABC

Partition based on a set of voxels.

chunk_to_voxels(chunk)

Voxelize the partition’s occupation in this chunk. Required to fill the partition with cells by the placement module.

Parameters:

chunk (bsb.storage._chunks.Chunk) – The chunk to calculate voxels for.

Returns:

The set of voxels that together make up the shape of this partition in this chunk.

Return type:

bsb.voxels.VoxelSet

get_layout(hint)

Given a Layout as hint to begin from, create a Layout object that describes how this partition would like to be laid out.

Parameters:

hint (bsb.topology._layout.Layout) – The layout space that this partition should place itself in.

Returns:

The layout describing the space this partition takes up.

Return type:

bsb.topology._layout.Layout

get_node_name()

abstractmethod get_voxelset()

rotate(rotation)

Rotate the partition by the given rotation object.

Parameters:

rotation (scipy.spatial.transform.Rotation) – Rotation object.

Raises:

exceptions.LayoutError if the rotation needs to be rejected.

scale(factor)

Scale up/down the partition according to the given factors.

Parameters:

factors (numpy.ndarray) – Scaling factors, XYZ.

Raises:

exceptions.LayoutError if the scaling needs to be rejected.

surface(chunk=None)

Calculate the surface of the partition in μm^2.

Parameters:

chunk (bsb.storage._chunks.Chunk) – If given, limit the surface of the partition inside of the chunk.

Returns:

Surface of the partition (in the chunk)

Return type:

float

to_chunks(chunk_size)

Calculate all the chunks this partition occupies when cut into chunk_sized pieces.

Parameters:

chunk_size (numpy.ndarray) – Size per chunk (in μm). The slicing always starts at [0, 0, 0].

Returns:

Chunks occupied by this partition

Return type:

list[bsb.storage._chunks.Chunk]

translate(offset)

Translate the partition by the given offset.

Parameters:

offset (numpy.ndarray) – Offset, XYZ.

Raises:

exceptions.LayoutError if the translation needs to be rejected.

volume(chunk=None)

Calculate the volume of the partition in μm^3.

Parameters:

chunk (bsb.storage._chunks.Chunk) – If given, limit the volume of the partition inside of the chunk.

Returns:

Volume of the partition (in the chunk)

Return type:

float

property voxelset

bsb.topology.region module

Module for the Region types.

class bsb.topology.region.Region(*args, _parent=None, _key=None, **kwargs)

Bases: ABC

Base region.

When arranging will simply call arrange/layout on its children but won’t cause any changes itself.

children: list[Region | Partition]

Reference to Regions or Partitions belonging to this region.

property data

do_layout(hint)

get_dependencies()

get_layout(hint)

get_node_name()

name: str

Base implementation of all the different configuration attributes.

Call the factory function attr() instead.

abstractmethod rotate(rotation)

scaffold: Scaffold

abstractmethod scale(factors)

abstractmethod translate(offset)

type

Base implementation of all the different configuration attributes.

Call the factory function attr() instead.

class bsb.topology.region.RegionGroup(*args, _parent=None, _key=None, **kwargs)

Bases: Region

Base implementation of Region.

Any transformation on the region will be directly applied to its children (Regions or Partitions).

get_node_name()

rotate(rotation)

scale(factors)

translate(offset)

class bsb.topology.region.Stack(*args, _parent=None, _key=None, **kwargs)

Bases: RegionGroup

Stack components on top of each other and adjust its own height accordingly.

anchor: Region | Partition

Reference to one child of the stack, which origin will become the origin of the stack.

axis: Literal['x'] | Literal['y'] | Literal['z']

Axis along which the stack’s children will be stacked.

get_layout(hint)

get_node_name()

rotate(rotation)

scale(factors)

translate(offset)

bsb.topology.layout module

class bsb.topology._layout.Layout(data, owner=None, children=None, frozen=False)

Bases: object

Container class for all types of partition data.

The layout swaps the data of the partition with temporary layout associated data, and tries out experimental changes to the partition data, if the layout process fails, the original partition data is reinstated.

accept()

property children

copy()

property data

swap()

class bsb.topology._layout.PartitionData

Bases: ABC

The partition data is a class that stores the description of a partition for a partition.

This allows the Partition interface to define mutating operations such as translate, rotate, scale; for a dry-run we only have to swap out the actual data with temporary data, and the mutation is prevented.

abstractmethod copy()

class bsb.topology._layout.RhomboidData(ldc, mdc)

Bases: PartitionData

copy()

Copy this boundary to a new instance.

property depth

property dimensions

property height

property width

property x

property y

property z

bsb.topology._layout.box_layout(ldc, mdc)

Module contents

Topology module.

bsb.topology.create_topology(regions, ldc, mdc)

Create a topology from group of regions. Will check for root regions, if there’s not exactly 1 root region a RegionGroup will be created as new root.

Parameters:

• regions (Iterable) – Any iterable of regions.

• ldc – Least dominant corner of the topology. Forms the suggested outer bounds of the topology together with the mdc.

• mdc – Most dominant corner of the topology. Forms the suggested outer bounds of the topology together with the mdc.

bsb.topology.get_partitions(regions)

Get all the partitions belonging to the group of regions and their subregions.

Parameters:

regions (Iterable) – Any iterable of regions.

bsb.topology.get_root_regions(regions)

Get all the root regions, not belonging to any other region in the given group.

Parameters:

regions (Iterable) – Any iterable of regions.

bsb.topology.is_partition(obj)

Checks if an object is a partition.

bsb.topology.is_region(obj)

Checks if an object is a region.