DiscreteVolumetricAtlas

class hypercoil.init.atlas.DiscreteVolumetricAtlas(ref_pointer: str, clear_cache: bool = True, name: str | None = None)

Discrete atlas container object. Use for atlases stored in single-volume images with non-overlapping, discrete-valued parcels. It is assumed that a value of 0 in the reference image corresponds to no label.

Parameters:

ref_pointer

Path to a NIfTI file containing 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:

refnb.Nifti1Image

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 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]

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.