DirichletInitVolumetricAtlas#

class hypercoil.init.atlas.DirichletInitVolumetricAtlas(mask_source: str | Callable, n_labels: Dict[str, int], conc: float | None = 100.0, name: str | None = None, init: Dict[str, DirichletInitialiser] | None = None, *, key: jax.random.PRNGKey, **params)[source]#

Volumetric atlas object created from random samples of a Dirichlet distribution. Each spatial location’s parcel assignment is a categorical distribution sampled from a Dirichlet distribution. For a surface-based Dirichlet atlas, use DirichletInitSurfaceAtlas.

Parameters:
mask_source

Source of data used to create an overall mask for the atlas.

n_labelsdict(int)

Number of labels to initialise for the atlas.

concfloat

If this is provided and init is not, then the Dirichlet distributions used to sample assignments of spatial locations to parcels are defined with the same concentration parameter, conc, for each parcel.

initdict(Dirichlet)

The Dirichlet distribution used for parcel assignment initialisation. If this is not provided, then a distribution with equal concentrations will be created using the conc parameter.

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.

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_dataNone

Nothing here. The field exists for consistency with other atlas classes.

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.