siibra.volumes.parcellationmap
Provides spatial representations for parcellations and regions.
Module Contents
Classes
Parent class encapsulating commonalities of the basic siibra concept like atlas, parcellation, space, region. |
|
Functions
|
Add a custom labelled parcellation map to siibra from a labelled NIfTI file. |
- class siibra.volumes.parcellationmap.AssignImageResult
- class siibra.volumes.parcellationmap.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.parcellationmap.MapAssignment
- centroid: Tuple[numpy.ndarray] | siibra.locations.point.Point
- fragment: str
- input_structure: int
- map_value: numpy.ndarray
- volume: int
- siibra.volumes.parcellationmap.from_volume(name: str, volume: siibra.volumes.volume.Volume | List[siibra.volumes.volume.Volume], regionnames: List[str], regionlabels: List[int], parcellation_spec: str | siibra.core.parcellation.Parcellation = None) Map
Add a custom labelled parcellation map to siibra from a labelled NIfTI file.
- Parameters:
name (str) – Human-readable name of the parcellation.
volume (Volume, or a list of Volumes.) –
space_spec (str, Space) – Specification of the reference space (space object, name, keyword, or id - e.g. ‘mni152’).
regionnames (list[str]) – List of human-readable names of the mapped regions.
regionlabels (list[int]) – List of integer labels in the nifti file corresponding to the list of regions.
parcellation (str or Parcellation. Optional.) – If the related parcellation already defined or preconfigured in siibra.