siibra.volumes.parcellationmap
Provides spatial representations for parcellations and regions.
Exceptions
Inappropriate argument value (of correct type). |
|
Inappropriate argument value (of correct type). |
|
Inappropriate argument value (of correct type). |
|
Unspecified run-time error. |
|
Unspecified run-time error. |
Classes
Parent class encapsulating commonalities of the basic siibra concept like atlas, parcellation, space, region. |
Module Contents
- exception siibra.volumes.parcellationmap.ConflictingArgumentException
Inappropriate argument value (of correct type).
- exception siibra.volumes.parcellationmap.ExcessiveArgumentException
Inappropriate argument value (of correct type).
- exception siibra.volumes.parcellationmap.InsufficientArgumentException
Inappropriate argument value (of correct type).
- exception siibra.volumes.parcellationmap.NoVolumeFound
Unspecified run-time error.
- exception siibra.volumes.parcellationmap.NonUniqueIndexError
Unspecified run-time error.
- class siibra.volumes.parcellationmap.AssignImageResult
- class siibra.volumes.parcellationmap.Assignment
- centroid: Tuple[numpy.ndarray] | siibra.locations.point.Point
- fragment: str
- input_structure: int
- map_value: numpy.ndarray
- volume: int
- class siibra.volumes.parcellationmap.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] = []