siibra.volumes
Package handling variety of volumes and volume operations
Subpackages
Submodules
Package Contents
Classes
Parent class encapsulating commonalities of the basic siibra concept like atlas, parcellation, space, region. |
|
A volume is a specific mesh or 3D array, |
Functions
|
Builds a siibra volume from an array and an affine matrix. |
|
Builds a nifti volume from a filename. |
|
Builds a nifti volume from a Nifti image. |
|
Get the kernel density estimate as a volume from the points using their |
Attributes
- class siibra.volumes.Map(identifier: str, name: str, space_spec: dict, parcellation_spec: dict, indices: Dict[str, List[Dict]], volumes: list = [], shortname: str = '', description: str = '', modality: str = None, publications: list = [], datasets: list = [])
Parent class encapsulating commonalities of the basic siibra concept like atlas, parcellation, space, region. These concepts have an id, name, and key, and they are bootstrapped from metadata stored in an online resources. Typically, they are linked with one or more datasets that can be retrieved from the same or another online resource, providing data files or additional metadata descriptions on request.
- property affine
- property formats
- property fragments
- property is_labelled
- property labels
The set of all label indices defined in this map, including “None” if not defined for one or more regions.
- property maptype: siibra.commons.MapType
- property parcellation
- property provides_image
- property provides_mesh
- property regions
- property space
- property species: siibra.commons.Species
- __iter__()
- __len__()
- assign(item: siibra.locations.location.Location, minsize_voxel=1, lower_threshold=0.0, **kwargs) pandas.DataFrame
Assign an input Location to brain regions.
The input is assumed to be defined in the same coordinate space as this parcellation map.
- Parameters:
item (Location) – A spatial object defined in the same physical reference space as this parcellation map, which could be a point, set of points, or image volume. If it is an image, it will be resampled to the same voxel space if its affine transformation differs from that of the parcellation map. Resampling will use linear interpolation for float image types, otherwise nearest neighbor.
minsize_voxel (int, default: 1) – Minimum voxel size of image components to be taken into account.
lower_threshold (float, default: 0) – Lower threshold on values in the statistical map. Values smaller than this threshold will be excluded from the assignment computation.
- Returns:
A table of associated regions and their scores per component found in the input image, or per coordinate provided. The scores are:
Value: Maximum value of the voxels in the map covered by an
input coordinate or input image signal component. - Pearson correlation coefficient between the brain region map and an input image signal component (NaN for exact coordinates) - Contains: Percentage of the brain region map contained in an input image signal component, measured from their binarized masks as the ratio between the volume of their intersection and the volume of the brain region (NaN for exact coordinates) - Contained: Percentage of an input image signal component contained in the brain region map, measured from their binary masks as the ratio between the volume of their intersection and the volume of the input image signal component (NaN for exact coordinates)
- Return type:
- colorize(values: dict, **kwargs) siibra.volumes.volume.Volume
Colorize the map with the provided regional values.
- Parameters:
values (dict) – Dictionary mapping regions to values
- Return type:
Nifti1Image
- compress(**kwargs)
Converts this map into a labelled 3D parcellation map, obtained by taking the voxelwise maximum across the mapped volumes and fragments, and re-labelling regions sequentially.
Paramaters
**kwargs: Takes the fetch arguments of its space’s template.
- rtype:
parcellationmap.Map
- compute_centroids() Dict[str, siibra.locations.point.Point]
Compute a dictionary of the centroids of all regions in this map.
- Returns:
Region names as keys and computed centroids as items.
- Return type:
Dict[str, point.Point]
- fetch(region_or_index: str | siibra.core.region.Region | siibra.commons.MapIndex = None, *, index: siibra.commons.MapIndex = None, region: str | siibra.core.region.Region = None, **kwargs)
Fetches one particular volume of this parcellation map.
If there’s only one volume, this is the default, otherwise further specification is requested: - the volume index, - the MapIndex (which results in a regional map being returned)
You might also consider fetch_iter() to iterate the volumes, or compress() to produce a single-volume parcellation map.
- Parameters:
region_or_index (str, Region, MapIndex) – Lazy match the specification.
index (MapIndex) – Explicit specification of the map index, typically resulting in a regional map (mask or statistical map) to be returned. Note that supplying ‘region’ will result in retrieving the map index of that region automatically.
region (str, Region) – Specification of a region name, resulting in a regional map (mask or statistical map) to be returned.
**kwargs –
resolution_mm: resolution in millimeters
format: the format of the volume, like “mesh” or “nii”
voi: a BoundingBox of interest
Not all keyword arguments are supported for volume formats. Format is restricted by available formats (check formats property).
- Return type:
An image or mesh
- fetch_iter(**kwargs)
Returns an iterator to fetch all mapped volumes sequentially.
All arguments are passed on to function Map.fetch(). By default, it will go through all fragments as well.
- find_indices(region: str | siibra.core.region.Region)
Returns the volume/label indices in this map which match the given region specification.
- get_colormap(region_specs: Iterable = None)
Generate a matplotlib colormap from known rgb values of label indices.
- Parameters:
region_specs (iterable(regions), optional) – Optional parameter to only color the desired regions.
- Return type:
ListedColormap
- get_index(region: str | siibra.core.region.Region)
Returns the unique index corresponding to the specified region.
Tip
Use find_indices() method for a less strict search returning all matches.
- Parameters:
- Return type:
- Raises:
NonUniqueIndexError – If not unique or not defined in this parcellation map.
- get_region(label: int = None, volume: int = 0, index: siibra.commons.MapIndex = None)
Returns the region mapped by the given index, if any.
Tip
Use get_index() or find_indices() methods to obtain the MapIndex.
- get_resampled_template(**fetch_kwargs) siibra.volumes.volume.Volume
Resample the reference space template to fetched map image. Uses nilearn.image.resample_to_img to resample the template.
- Parameters:
**fetch_kwargs (takes the arguments of Map.fetch()) –
- Return type:
- sample_locations(regionspec, numpoints: int)
Sample 3D locations inside a given region.
The probability distribution is approximated from the region mask based on the squared distance transform.
- to_sparse()
Creates a SparseMap object from this parcellation map object.
- Return type:
- class siibra.volumes.Volume(space_spec: dict, providers: List[siibra.volumes.providers.provider.VolumeProvider], name: str = '', variant: str = None, datasets: List[TypeDataset] = [])
A volume is a specific mesh or 3D array, which can be accessible via multiple providers in different formats.
- property formats: Set[str]
- property name
Allows derived classes to implement a lazy name specification.
- property providers
- property provides_image
- property provides_mesh
- property space
- property species
- IMAGE_FORMATS = ['nii', 'zip/nii', 'neuroglancer/precomputed']
- MESH_FORMATS = ['neuroglancer/precompmesh', 'neuroglancer/precompmesh/surface', 'gii-mesh', 'gii-label']
- SUPPORTED_FORMATS
- __eq__(other: Volume)
Required to provide comparison and making the object hashable
- __hash__()
Return hash(self).
- __repr__()
Return repr(self).
- __str__()
Return str(self).
- draw_samples(N: int, sample_size: int = 100, e: float = 1, sigma_mm=None, invert=False, **kwargs)
Draw samples from the volume, by interpreting its values as an unnormalized empirical probability distribtution. Any keyword arguments are passed over to fetch()
- evaluate_points(points: siibra.locations.point.Point | siibra.locations.pointset.PointSet, outside_value: int | float = 0, **fetch_kwargs) numpy.ndarray
Evaluate the image at the positions of the given points.
Note
Uses nearest neighbor interpolation. Other interpolation schemes are not yet implemented.
Note
If points are not on the same space as the map, they will be warped to the space of the volume.
- Parameters:
- Returns:
values – The values of the volume at the voxels points correspond to.
- Return type:
- Raises:
SpaceWarpingFailedError – If warping of the points fails.
- fetch(format: str = None, **kwargs)
Fetch a volumetric or surface representation from one of the providers.
- Parameters:
format (str, default=None) –
Requested format. If None, the first supported format matching in self.formats is tried, starting with volumetric formats. It can be explicitly specified as:
’surface’ or ‘mesh’ to fetch a surface format
’volumetric’ or ‘voxel’ to fetch a volumetric format
supported format types, see SUPPORTED_FORMATS. This includes
’nii’, ‘zip/nii’, ‘neuroglancer/precomputed’, ‘gii-mesh’, ‘neuroglancer/precompmesh’, ‘gii-label’
- Returns:
An image (Nifti1Image) or mesh (Dict[‘verts’
- Return type:
ndarray, ‘faces’: ndarray, ‘labels’: ndarray])
- fetch_connected_components(**kwargs)
Provide an iterator over masks of connected components in the volume
- find_peaks(mindist=5, sigma_mm=0, **kwargs)
Find local peaks in the volume. Additional keyword arguments are passed over to fetch()
- get_boundingbox(clip: bool = True, background: float = 0.0, **fetch_kwargs) siibra.locations.boundingbox.BoundingBox
Obtain the bounding box in physical coordinates of this volume.
- Parameters:
clip (bool, default: True) – Whether to clip the background of the volume.
background (float, default: 0.0) – The background value to clip. .. note:: To use it, clip must be True.
fetch_kwargs – key word arguments that are used for fetchin volumes, such as voi or resolution_mm. Currently, only possible for Neuroglancer volumes except for format.
- Raises:
RuntimeError – If the volume provider does not have a bounding box calculator.
- intersection(other: siibra.core.structure.BrainStructure, **fetch_kwargs) siibra.core.structure.BrainStructure
Compute the intersection of a location with this volume. This will fetch actual image data. Any additional arguments are passed to fetch.
- abstract transform(affine: numpy.ndarray, space=None)
Returns a new location obtained by transforming the reference coordinates of this one with the given affine matrix.
- Parameters:
affine (numpy 4x4 ndarray) – affine matrix
space (reference space (id, name, or Space)) – Target reference space which is reached after applying the transform. Note that the consistency of this cannot be checked and is up to the user.
- union(other: siibra.locations.location.Location)
Reassigned at the locations module level for static typing and to avoid circular imports. See siibra.locations.__init__.reassign_union()
- warp(space)
Generates a new location by warping the current one into another reference space.
- siibra.volumes.from_array(data: numpy.ndarray, affine: numpy.ndarray, space: str | Dict[str, str], name: str) Volume
Builds a siibra volume from an array and an affine matrix.
- siibra.volumes.from_file(filename: str, space: str, name: str) Volume
Builds a nifti volume from a filename.
- siibra.volumes.from_nifti(nifti: nibabel.Nifti1Image, space: str, name: str) Volume
Builds a nifti volume from a Nifti image.
- siibra.volumes.from_pointset(points: siibra.locations.pointset.PointSet, label: int = None, target: Volume = None, normalize=True, **kwargs) Volume
Get the kernel density estimate as a volume from the points using their average uncertainty on target volume.
- Parameters:
points (pointset.PointSet) –
label (int, default: None) – If None, finds the KDE for all points. Otherwise, selects the points labelled with this integer value.
target (Volume, default: None) – If None, the template of the space points are defined on will be used.
normalize (bool, default: True) –
- Raises:
RuntimeError – If no points with labels found
- siibra.volumes.logger