9.2.1. Data¶

Parcellations, coordinates and masks.

class junifer.data.CoordinatesRegistry(*args, **kwargs)¶

Class for coordinates data registry.

This class is a singleton and is used for managing available coordinates data in a centralized manner.

Initialize the class.

deregister(name)¶

De-register a custom user coordinates.

Parameters:

namestr: The name of the coordinates.

get(coords, target_data, extra_input=None)¶

Get coordinates, tailored for the target data.

Parameters:

coordsstr: The name of the coordinates.
target_datadict: The corresponding item of the data object to which the coordinates will be applied.
extra_inputdict, optional: The other fields in the data object. Useful for accessing other data kinds that needs to be used in the computation of coordinates (default None).

Returns:

numpy.ndarray: The coordinates.
list of str: The names of the VOIs.

Raises:

RuntimeError: If warping specification required for warping using ANTs, is not found.
ValueError: If extra_input is None when target_data’s space is native.

load(name)¶

Load coordinates.

Parameters:

namestr: The name of the coordinates.

Returns:

numpy.ndarray: The coordinates.
list of str: The names of the VOIs.
str: The space of the coordinates.

Raises:

ValueError: If name is invalid.

register(name, coordinates, voi_names, space, overwrite=False)¶

Parameters:

namestr: The name of the coordinates.
coordinatesnumpy.ndarray: The coordinates. This should be a 2-dimensional array with three columns. Each row corresponds to a volume-of-interest (VOI) and each column corresponds to a spatial dimension (i.e. x, y, and z-coordinates).
voi_nameslist of str: The names of the VOIs.
spacestr: The space of the coordinates, e.g., “MNI”.
overwritebool, optional: If True, overwrite an existing list of coordinates with the same name. Does not apply to built-in coordinates (default False).

Raises:

ValueError: If the coordinates name is already registered and overwrite=False or if the coordinates name is a built-in coordinates or if the coordinates is not a 2D array or if coordinate value does not have 3 components or if the voi_names shape does not match the coordinates shape.
TypeError: If coordinates is not a numpy.ndarray.

class junifer.data.MaskRegistry(*args, **kwargs)¶

Class for mask data registry.

This class is a singleton and is used for managing available mask data in a centralized manner.

Initialize the class.

deregister(name)¶

De-register a custom user mask.

Parameters:

namestr: The name of the mask.

get(masks, target_data, extra_input=None)¶

Get mask, tailored for the target image.

Parameters:

masksstr, dict or list of dict or str: The name(s) of the mask(s), or the name(s) of callable mask(s) and parameters of the mask(s) as a dictionary. Several masks can be passed as a list.
target_datadict: The corresponding item of the data object to which the mask will be applied.
extra_inputdict, optional: The other fields in the data object. Useful for accessing other data kinds that needs to be used in the computation of masks (default None).

Returns:

Nifti1Image: The mask image.

Raises:

ValueError: If extra key is provided in addition to mask name in masks or if no mask is provided or if masks = "inherit" and mask key for the target_data is not found or if callable parameters are passed to non-callable mask or if parameters are passed to nilearn.masking.intersect_masks() when there is only one mask or if extra_input is None when target_data’s space is native.

load(name, resolution=None, path_only=False)¶

Load mask.

Parameters:

namestr: The name of the mask.
resolutionfloat, optional: The desired resolution of the mask to load. If it is not available, the closest resolution will be loaded. Preferably, use a resolution higher than the desired one. By default, will load the highest one (default None).
path_onlybool, optional: If True, the mask image will not be loaded (default False).

Returns:

Nifti1Image, callable() or None: Loaded mask image.
pathlib.Path or None: File path to the mask image.
str: The space of the mask.

Raises:

ValueError: If the name is invalid or if the mask family is invalid.

register(name, mask_path, space, overwrite=False)¶

Parameters:

namestr: The name of the mask.
mask_pathstr or pathlib.Path: The path to the mask file.
spacestr: The space of the mask, for e.g., “MNI152NLin6Asym”.
overwritebool, optional: If True, overwrite an existing mask with the same name. Does not apply to built-in mask (default False).

Raises:

ValueError: If the mask name is already registered and overwrite=False or if the mask name is a built-in mask.

class junifer.data.ParcellationRegistry(*args, **kwargs)¶

Class for parcellation data registry.

This class is a singleton and is used for managing available parcellation data in a centralized manner.

Initialize the class.

deregister(name)¶

De-register a custom user parcellation.

Parameters:

namestr: The name of the parcellation.

get(parcellations, target_data, extra_input=None)¶

Get parcellation, tailored for the target image.

Parameters:

parcellationsstr or list of str: The name(s) of the parcellation(s).
target_datadict: The corresponding item of the data object to which the parcellation will be applied.
extra_inputdict, optional: The other fields in the data object. Useful for accessing other data kinds that needs to be used in the computation of parcellations (default None).

Returns:

Nifti1Image: The parcellation image.
list of str: Parcellation labels.

Raises:

ValueError: If extra_input is None when target_data’s space is native.

load(name, target_space, parcellations_dir=None, resolution=None, path_only=False)¶

Load parcellation and labels.

If it is a built-in parcellation and the file is not present in the parcellations_dir directory, it will be downloaded.

Parameters:

namestr: The name of the parcellation.
target_spacestr: The desired space of the parcellation.
parcellations_dirstr or pathlib.Path, optional: Path where the parcellations files are stored. The default location is “$HOME/junifer/data/parcellations” (default None).
resolutionfloat, optional: The desired resolution of the parcellation to load. If it is not available, the closest resolution will be loaded. Preferably, use a resolution higher than the desired one. By default, will load the highest one (default None).
path_onlybool, optional: If True, the parcellation image will not be loaded (default False).

Returns:

Nifti1Image or None: Loaded parcellation image.
list of str: Parcellation labels.
pathlib.Path: File path to the parcellation image.
str: The space of the parcellation.

Raises:

ValueError: If name is invalid or if the parcellation values and labels don’t have equal dimension or if the value range is invalid.

register(name, parcellation_path, parcels_labels, space, overwrite=False)¶

Parameters:

namestr: The name of the parcellation.
parcellation_pathstr or pathlib.Path: The path to the parcellation file.
parcels_labelslist of str: The list of labels for the parcellation.
spacestr: The template space of the parcellation, e.g., “MNI152NLin6Asym”.
overwritebool, optional: If True, overwrite an existing parcellation with the same name. Does not apply to built-in parcellations (default False).

Raises:

ValueError: If the parcellation name is already registered and overwrite=False or if the parcellation name is a built-in parcellation.

junifer.data.deregister_data(kind, name)¶

De-register name from kind.

Parameters:

kind{“coordinates”, “parcellation”, “mask”}: Kind of data to register.
namestr: The name to de-register.

Raises:

ValueError: If kind is invalid value.

junifer.data.get_data(kind, names, target_data, extra_input=None)¶

Get tailored kind for target_data.

Parameters:

kind{“coordinates”, “parcellation”, “mask”}: Kind of data to fetch and apply.
namesstr or dict or list of str / dict: The registered name(s) of the data.
target_datadict: The corresponding item of the data object to which the data will be applied.
extra_inputdict, optional: The other fields in the data object. Useful for accessing other data types that need to be used in the computation of data (default None).

Returns:

tuple of numpy.ndarray, list of str; tuple of nibabel.nifti1.Nifti1Image, list of str; nibabel.nifti1.Nifti1Image

Raises:

ValueError: If kind is invalid value.

junifer.data.get_template(space, target_img, extra_input=None, template_type='T1w')¶

Get template for the space, tailored for the target image.

Parameters:

spacestr: The name of the template space.
target_imgNifti1Image: The corresponding image for which the template space will be loaded. This is used to obtain the best matching resolution.
extra_inputdict, optional: The other fields in the data object. Useful for accessing other data types (default None).
template_type{“T1w”, “brain”, “gm”, “wm”, “csf”}, optional: The template type to retrieve (default “T1w”).

Returns:

Nifti1Image: The template image.

Raises:

ValueError: If space or template_type is invalid.
RuntimeError: If required template is not found.

junifer.data.get_xfm(src, dst, xfms_dir=None)¶

Fetch warp files to convert from src to dst.

Parameters:

srcstr: The template space to transform from.
dststr: The template space to transform to.
xfms_dirstr or pathlib.Path, optional: Path where the retrieved transformation files are stored. The default location is “$HOME/junifer/data/xfms” (default None).

Returns:

pathlib.Path: The path to the transformation file.

Raises:

RuntimeError: If there is a problem cloning the xfm dataset or if there is a problem fetching the xfm file.

junifer.data.list_data(kind)¶

List available data for kind.

Parameters:

kind{“coordinates”, “parcellation”, “mask”}: Kind of data registry to list.

Returns:

list of str: Available data for the registry.

Raises:

ValueError: If kind is invalid value.

junifer.data.load_data(kind, name, **kwargs)¶

Load kind named name.

Parameters:

kind{“coordinates”, “parcellation”, “mask”}: Kind of data to load.
namestr: The registered name of the data.
**kwargs: Keyword arguments are passed to respective registry class method.

Returns:

tuple of numpy.ndarray, list of str, str; tuple of nibabel.nifti1.Nifti1Image or None, list of str, pathlib.Path, str; tuple of nibabel.nifti1.Nifti1Image or callable() or None, pathlib.Path or None, str

Raises:

ValueError: If kind is invalid value.

junifer.data.register_data(kind, name, space, overwrite=False, **kwargs)¶

Parameters:

kind{“coordinates”, “parcellation”, “mask”}: Kind of data to register.
namestr: The name to register.
spacestr: The template space of the data.
overwritebool, optional: If True, overwrite an existing data with the same name.
**kwargs: Keyword arguments are passed to respective registry class method.

Raises:

ValueError: If kind is invalid value.