atlasmixins: Atlas mixins

Mixins for designing atlas classes.

~ReferenceMixin

class hypercoil.init.atlasmixins._VolumeObjectReferenceMixin

Use to load a reference into an atlas class.

For use when a NIfTI image object is already provided as the ref_pointer argument.

class hypercoil.init.atlasmixins._SurfaceObjectReferenceMixin

Use to load a reference into an atlas class.

For use when a CIfTI image object is already provided as the ref_pointer argument.

class hypercoil.init.atlasmixins._VolumeSingleReferenceMixin

Use to load a reference into an atlas class.

For use when the ref_pointer object references a single path to a volumetric image on disk.

class hypercoil.init.atlasmixins._SurfaceSingleReferenceMixin

Use to load a reference into an atlas class.

For use when the ref_pointer object references a single path to a surface image on disk.

class hypercoil.init.atlasmixins._VolumeMultiReferenceMixin

Use to load a reference into an atlas class.

For use when the ref_pointer object is an iterable of paths to volumetric images on disk.

class hypercoil.init.atlasmixins._PhantomReferenceMixin

Use to load a reference into an atlas class.

For use when the data content of the reference is unimportant, for instance when instances of the atlas class are to be initialised from a distribution rather than from an existing reference. The reference is still used for inferring dimensions of the atlas and input images.

~MaskMixin

class hypercoil.init.atlasmixins._LogicMaskMixin

Use to create an overall mask that specifies atlas inclusion status of spatial locations.

For use when the mask source is either a path on the file system containing Boolean-valued data or a nested logical expression tree (comprising operation nodes such as MaskIntersection or MaskThreshold with filesystem paths as leaf nodes).

class hypercoil.init.atlasmixins._CortexSubcortexCIfTIMaskMixin

Use to create an overall mask that specifies atlas inclusion status of spatial locations.

For use when creating a CIfTI atlas with separate cortical and subcortical compartments, and when the provided mask source indicates medial wall regions of the cortical surface marked for exclusion from the atlas.

class hypercoil.init.atlasmixins._FromNullMaskMixin

Use to create an overall mask that specifies atlas inclusion status of spatial locations.

For use when automatically creating a mask by excluding all background- or null-valued (typically 0-valued) spatial locations from the reference. For single-volume references (typically discrete-valued), this mixin creates a mask that includes all locations not labelled as background. For multi-volume references (often continuous-valued), this mixin creates a mask that includes all locations that are greater than or equal to the provided source parameter after taking the sum across volumes.

~CompartmentMixin

class hypercoil.init.atlasmixins._SingleCompartmentMixin

Use to isolate spatial subcompartments of the overall atlas such that each has separate label sets.

For use when no isolation is desired, and the entire atlased region is a single compartment.

class hypercoil.init.atlasmixins._MultiCompartmentMixin

Use to isolate spatial subcompartments of the overall atlas such that each has separate label sets.

For use when isolation into multiple compartments is desired. With this mixin, each extra keyword argument passed to the atlas constructor is interpreted as a name-mask path pair defining an atlas compartment.

class hypercoil.init.atlasmixins._CortexSubcortexCIfTICompartmentMixin

Use to isolate spatial subcompartments of the overall atlas such that each has separate label sets.

For use when creating a CIfTI-based atlas with separate subcompartments for the left and right cortical hemispheres and for subcortical locations.

~LabelMixin

class hypercoil.init.atlasmixins._DiscreteLabelMixin

Use to decode label sets present in an atlas and to create a linear map representation of the atlas.

For use when the label sets are encoded as discrete values in a single reference volume or surface.

class hypercoil.init.atlasmixins._ContinuousLabelMixin

Use to decode label sets present in an atlas and to create a linear map representation of the atlas.

For use when the label sets are encoded across multiple volumes. This is necessary for continuous-valued atlases or atlases with overlapping labels, but is also a valid encoding scheme for discrete-valued atlases. If the reference uses a single volume or surface, use DiscreteLabelMixin instead.

class hypercoil.init.atlasmixins._DirichletLabelMixin

Use to decode label sets present in an atlas and to create a linear map representation of the atlas.

For use when the linear map is to be initialised from a Dirichlet distribution rather than a reference. This requires the prior existence of a dictionary attribute called compartment_labels for the Atlas object, whose key-value pairs associate to each atlas compartment an integer number of labels. It additionally requires a second key-value mapping init, whose entries associate to each atlas compartment the Dirichlet distribution from which that compartment’s parcel assignment probability distributions are to be sampled. These mappings can be instantiated in the atlas class’s constructor method, potentially from user arguments.

~MeshMixin

class hypercoil.init.atlasmixins._VolumetricMeshMixin

Used to establish a coordinate system over the linear map representations of the atlas.

For use when the atlas reference comprises evenly spaced volumetric samples (i.e., voxels).

class hypercoil.init.atlasmixins._VertexCIfTIMeshMixin

Used to establish a coordinate system over the linear map representations of the atlas.

For use when the atlas reference is a CIfTI that includes some samples associated to cortical surface meshes. This mixin establishes a spherical topology for cortical samples and a Euclidean topology for subcortical samples.

~ConvMixin

class hypercoil.init.atlasmixins._EvenlySampledConvMixin

Used to spatially convolve atlas parcels for smoothing.

This mixin is currently unsupported and likely will not function without substantial extra code, although it is likely to perform better under many conditions. Its use is not currently advised.

class hypercoil.init.atlasmixins._SpatialConvMixin

Used to spatially convolve atlas parcels for smoothing.

For use when a coordinate mesh is available for the atlas and either Euclidean or spherical topologies are assigned to each of its compartments.

Abstractions

class hypercoil.init.atlasmixins.Reference(pointer: 'Any', model_axes: "Union[Sequence[int], Literal['cifti']]", dataobj: 'Optional[Tensor]' = None, imobj_from_pointer: 'Optional[Callable]' = None, dataobj_from_imobj: 'Optional[Callable]' = None)

Attributes:

affine

axobj

Thanks to Chris Markiewicz for tutorials that shaped this implementation.

data

dataobj

header

model_axobj

model_shape

model_zooms

modelobj

ndim

nifti_header

other_axes

shape

zooms

Methods

cache_dataobj
cache_modelobj
cifti_model_axes
dataobj_from_imobj
imobj_from_pointer
load_imobj
purge_cache

class hypercoil.init.atlasmixins.Mask(mask_array: 'Tensor')

Attributes:

data

shape

size

Methods

map_to_masked

class hypercoil.init.atlasmixins.Compartment(name: 'str', slice_index: 'int', slice_size: 'int', mask_array: 'Optional[Tensor]' = None)

Attributes:

data

mask_array

shape

size

Methods

dynamic_slice_map
map_to_masked

class hypercoil.init.atlasmixins.CompartmentSet(compartment_dict: 'Dict[str, Tensor]')

Methods

map_to_contiguous()

dynamic_slice_map
get
items
keys
values