`BaseAtlas`#

class hypercoil.init.atlas.BaseAtlas(ref_pointer: Any, mask_source: Any, clear_cache: bool = True, name: str | None = None, **params)[source]#

Atlas object encoding linear mappings from voxels to labels. Base class inherited by discrete and continuous atlas containers.

Several atlas classes are included to cover frequent scenarios, but users can also create their own atlas class compositionally using the available mixins. Each atlas class must implement the following methods:

_load_reference: Implemented by a ~ReferenceMixin class.
_create_mask: Implemented by a ~MaskMixin class.
_compartment_names_dict: Implemented by a ~CompartmentMixin class.
_create_compartments: Implemented by a ~CompartmentMixin class.
_configure_decoders: Implemented by a ~LabelMixin class.
_populate_map_from_ref: Implemented by a ~LabelMixin class.
_init_coors: Implemented by a ~MeshMixin class.
_configure_sigma: Implemented by a ~ConvMixin class.
_convolve: Implemented by a ~ConvMixin class.

Abstractly, atlas creation proceeds through the following steps:

Loading a reference that contains the atlas data;
Creating an overall mask that indicates regions of space that are candidates for inclusion in the atlas
Defining isolated subcompartments of the atlas (for instance, left and right cortical hemispheres)
Decoding the sets of labels that are present in each subcompartment
Creating a linear map representation of each subcompartment’s atlas
Establishing a coordinate system over each linear map

Parameters:

ref_pointer: Pointer to a reference path, image, or object used to instantiate the atlas.
mask_source: Source of data used to create an overall mask for the atlas.
dtype: Datatype for non-Boolean (non-mask) and non-Long (non-label) tensors created as part of the atlas.
device: Device on which all tensors created as part of the atlas reside.
clear_cachebool (True): Indicates that data loaded in from the reference should be cleared away when atlas creation is complete.

Attributes:

ref: The reference whose pointer was provided at construction time.
maskbool tensor: Boolean tensor indicating the inclusion status of each spatial location in the atlas.
compartmentsdict(bool tensor): Boolean tensor indicating the spatial extent of each atlas subcompartment.
decoderdict(long tensor): Numerical identity of the parcel in each row of a subcompartment’s map tensor.
mapsdict(tensor): Assignment of each spatial location in each subcompartment to a set of regions.
coorsdict(tensor): Spatial position of each location in the atlas.
topologydict(str): Type of topology (spherical or Euclidean) over each compartment.
cached_ref_datandarray: Data loaded from the reference to enable construction. By default, this is purged when construction is complete.

Methods

__call__([compartments, normalise, sigma, ...])

Compute transformed maps for selected atlas subcompartments.

Methods Documentation

__call__(compartments: bool | Sequence[str] = True, normalise: bool = False, sigma: float | None = None, noise: Callable | None = None, max_bin: int = 10000, spherical_scale: float = 1, truncate: float | None = None) → Dict[str, Tensor][source]#

Compute transformed maps for selected atlas subcompartments.

Parameters:

compartmentsiterable, False, or True (default True): Compartments for which transformed maps should be computed. If this is set to False, then a single transformed map is returned for the combined compartment containing all spatial locations. If this is set to True, then a transformed map is returned for every defined compartment.
normalisebool (default False): Indicates that maps should be spatially normalised such that the sum over all assignments to a parcel is equal to 1. When the map is used as a linear transformation, this option results in computation of a weighted average over each parcel.
sigmafloat or None (default None): If this is not None, then spatial smoothing using a Gaussian kernel is applied over each parcel’s assignments. Distances are established by the atlas’s coordinate system and the topology of each compartment. The value of sigma establishes the width of the Gaussian kernel.
noisecallable or None: If this is a callable, then it should be a mapping from a tensor to another tensor of the same dimensions. After spatial smoothing but before normalisation, this callable is applied to each map tensor to inject noise.
max_binint (default 10000): Because spatial smoothing has substantial memory overhead, this flag sets a ceiling on the number of spatial locations to be smoothed at a time.
spherical_scalefloat (default 1): During spatial smoothing, the Gaussian kernel is scaled by this value for spherical coordinate systems only. This enables the use of different kernel widths for spherical and Euclidean coordinates.
truncatefloat: Maximum distance at which data points are convolved together during smoothing.

Returns:

dict(tensor): Dictionary of transformed maps for each specified atlas compartment.

BaseAtlas#

`BaseAtlas`#