siibra.volumes
Package handling variety of volumes
Submodules
Classes
Helper class that provides a standard way to create an ABC using |
|
One or more surface mesh fragments in Gifti format. |
|
A mesh labeling, specified by a gifti file. |
|
Parent class encapsulating commonalities of the basic siibra concept like atlas, parcellation, space, region. |
|
A surface mesh provided as neuroglancer precomputed mesh. |
|
Helper class that provides a standard way to create an ABC using |
|
Helper class that provides a standard way to create an ABC using |
|
Helper class that provides a standard way to create an ABC using |
Functions
Preload preconfigured parcellation maps. |
Package Contents
- class siibra.volumes.FreesurferAnnot(url: str | dict)
Helper class that provides a standard way to create an ABC using inheritance.
- property boundingbox: siibra.locations.boundingbox.BoundingBox
- Abstractmethod:
- property fragments
- class siibra.volumes.GiftiMesh(url: str | Dict[str, str], volume=None)
One or more surface mesh fragments in Gifti format.
- fetch(fragment: str = None, **kwargs)
Returns the mesh as a dictionary with two numpy arrays.
- Parameters:
fragment (str, default: None) –
A fragment name can be specified to choose from multiple fragments.
Note
If not specified, multiple fragments will be merged into one mesh. In such a case, the verts and faces arrays of different fragments are appended to one another.
- Returns:
‘verts’: An Nx3 array of vertex coordinates,
’faces’: an Mx3 array of face definitions using row indices of the vertex array
- Return type:
- fetch_iter()
Iterator returning all submeshes
- Returns:
‘verts’: An Nx3 array of vertex coordinates,
’faces’: an Mx3 array of face definitions using row indices of the vertex array
’name’: Name of the of the mesh variant
- Return type:
- property boundingbox: siibra.locations.boundingbox.BoundingBox
- Abstractmethod:
- property fragments
- property variants
- volume = None
- class siibra.volumes.GiftiSurfaceLabeling(url: str | dict)
A mesh labeling, specified by a gifti file.
- fetch(fragment: str = None, **kwargs)
Returns a 1D numpy array of label indices.
- property boundingbox: siibra.locations.boundingbox.BoundingBox
- Abstractmethod:
- class siibra.volumes.Map(identifier: str, name: str, space_spec: dict, parcellation_spec: dict, indices: Dict[str, Dict], volumes: list = [], shortname: str = '', description: str = '', modality: str = None, publications: list = [], datasets: list = [], prerelease: bool = False)
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.
- assign(item: siibra.locations.point.Point | siibra.locations.pointset.PointSet | nibabel.Nifti1Image, minsize_voxel=1, lower_threshold=0.0, **kwargs)
Assign an input image to brain regions.
The input image is assumed to be defined in the same coordinate space as this parcellation map.
- Parameters:
item (Point, PointSet, Nifti1Image) – A spatial object defined in the same physical reference space as this parcellation map, which could be a point, set of points, or image. 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:
assignments (pandas.DataFrame) – 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)
components (Nifti1Image or None) – If the input was an image, this is a labelled volume mapping the detected components in the input image, where pixel values correspond to the “component” column of the assignment table. If the input was a Point or PointSet, returns None.
- colorize(values: dict, **kwargs) nibabel.Nifti1Image
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().
- 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) nibabel.Nifti1Image
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:
Nifti1Image
- 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:
- 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
- volumes: List[siibra.volumes.volume.Volume] = []
- class siibra.volumes.NeuroglancerMesh(resource: str | dict, volume=None)
A surface mesh provided as neuroglancer precomputed mesh.
- fetch(label: int, fragment: str)
Fetches a particular mesh. Each mesh is a dictionary with keys:
- Parameters:
label (int) – Label of the volume
fragment (str, default: None) –
A fragment name can be specified to choose from multiple fragments.
Note
If not specified, multiple fragments will be merged into one mesh. In such a case, the verts and faces arrays of different fragments are appended to one another.
- Returns:
‘verts’: An Nx3 array of vertex coordinates (in nanometer)
’faces’: an MX3 array containing connection data of vertices
’name’: Name of the of the mesh variant
- Return type:
- property boundingbox: siibra.locations.boundingbox.BoundingBox
- Abstractmethod:
- volume = None
- class siibra.volumes.NeuroglancerProvider(url: str | Dict[str, str])
Helper class that provides a standard way to create an ABC using inheritance.
- fetch(fragment: str = None, resolution_mm: float = None, voi: siibra.locations.boundingbox.BoundingBox = None, **kwargs) nibabel.Nifti1Image
Fetch 3D image data from neuroglancer volume.
- Parameters:
fragment (str, optional) – The name of a fragment volume to fetch, if any. For example, some volumes are split into left and right hemisphere fragments. See
fragments()resolution_mm (float) – Specify the resolution
voi (BoundingBox) – optional specification of a volume of interest to fetch.
- property boundingbox
Return the bounding box in physical coordinates of the union of fragments in this neuroglancer volume.
- class siibra.volumes.NiftiProvider(src: str | Dict[str, str] | nibabel.Nifti1Image)
Helper class that provides a standard way to create an ABC using inheritance.
- fetch(fragment: str = None, voi: siibra.locations.boundingbox.BoundingBox = None, label: int = None)
Loads and returns a Nifti1Image object
- Parameters:
fragment (str) – Optional name of a fragment volume to fetch, if any. For example, some volumes are split into left and right hemisphere fragments. see
fragments()voi (BoundingBox) – optional specification of a volume of interest to fetch.
label (int, default: None) – Optional: a label index can be provided. Then the mask of the 3D volume will be returned, where voxels matching this label are marked as “1”.
- find_peaks(min_distance_mm=5)
Find peaks in the image data.
- Parameters:
min_distance_mm (float) – Minimum distance between peaks in mm
Returns –
-------- –
PointSet –
- get_shape(resolution_mm=None)
- is_float()
- property boundingbox
Return the bounding box in physical coordinates of the union of fragments in this nifti volume.
- property fragments
- class siibra.volumes.ZippedFreesurferAnnot(url: str | dict)
Helper class that provides a standard way to create an ABC using inheritance.
- property boundingbox: siibra.locations.boundingbox.BoundingBox
- Abstractmethod:
- property fragments
- siibra.volumes.warm_cache()
Preload preconfigured parcellation maps.