9.2.1. Parcellations#

Functions for parcellation manipulation.

junifer.data.parcellations.get_parcellation(parcellation, target_data, extra_input=None)#

Get parcellation, tailored for the target image.

Parameters:

parcellationlist 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:

RuntimeError: If warp / transformation file extension is not “.mat” or “.h5”.
ValueError: If extra_input is None when target_data’s space is native.

junifer.data.parcellations.list_parcellations()#

List all the available parcellations.

Returns:

list of str: A list with all available parcellations.

junifer.data.parcellations.load_parcellation(name, parcellations_dir=None, resolution=None, path_only=False)#

Load a brain parcellation (including a label file).

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. Check valid options by calling list_parcellations().
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.

junifer.data.parcellations.merge_parcellations(parcellations_list, parcellations_names, labels_lists)#

Merge all parcellations from a list into one parcellation.

Parameters:

parcellations_listlist of niimg-like object: List of parcellations to merge.
parcellations_names: list of str: List of names for parcellations at the corresponding indices.
labels_listslist of list of str: A list of lists. Each list in the list contains the labels for the parcellation at the corresponding index.

Returns:

parcellationniimg-like object: The parcellation that results from merging the list of input parcellations.
labelslist of str: List of labels for the resultant parcellation.

junifer.data.parcellations.register_parcellation(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, for 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 is set to False or if the parcellation name is a built-in parcellation.

9.2.2. Coordinates#

Functions for coordinates manipulation.

junifer.data.coordinates.get_coordinates(coords, target_data, extra_input=None)#

Get coordinates, tailored for the target image.

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 warp / transformation file extension is not “.mat” or “.h5”.
ValueError: If extra_input is None when target_data’s space is native.

junifer.data.coordinates.list_coordinates()#

List all the available coordinates (VOIs).

Returns:

list of str: A list with all available coordinates names.

junifer.data.coordinates.load_coordinates(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.

junifer.data.coordinates.register_coordinates(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, for 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 is set to 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.

9.2.3. Masks#

Functions for mask manipulation.

junifer.data.masks.compute_brain_mask(target_data, extra_input=None, mask_type='brain', threshold=0.5)#

Compute the whole-brain, grey-matter or white-matter mask.

This mask is calculated using the template space and resolution as found in the target_data.

Parameters:

target_datadict

The corresponding item of the data object for which mask will be loaded.

extra_inputdict, optional

The other fields in the data object. Useful for accessing other data types (default None).

mask_type{“brain”, “gm”, “wm”}, optional

Type of mask to be computed:

“brain” : whole-brain mask
“gm” : grey-matter mask
“wm” : white-matter mask

(default “brain”).

thresholdfloat, optional

The value under which the template is cut off (default 0.5).

Returns:

Nifti1Image: The mask (3D image).

Raises:

ValueError: If mask_type is invalid or if extra_input is None when target_data’s space is native.

junifer.data.masks.get_mask(masks, target_data, extra_input=None)#

Get mask, tailored for the target image.

Parameters:

masksstr, dict or list of dict or str: The name of the mask, or the name of a callable mask and the parameters of the mask 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:

RuntimeError: If warp / transformation file extension is not “.mat” or “.h5”.
ValueError: If extra key is provided in addition to mask name in masks or if no mask is provided or if masks = "inherit" but extra_input is None or mask_item is None or mask_items’s value is not in extra_input 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.

junifer.data.masks.list_masks()#

List all the available masks.

Returns:

list of str: A list with all available masks names.

junifer.data.masks.load_mask(name, resolution=None, path_only=False)#

Load a mask.

Parameters:

namestr: The name of the mask. Check valid options by calling list_masks().
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 of if the mask family is invalid.

junifer.data.masks.register_mask(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 is set to False or if the mask name is a built-in mask.

9.2.4. Template Spaces#

Functions for template space manipulation.

junifer.data.template_spaces.get_template(space, target_data, 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_datadict: The corresponding item of the data object for which the template space will be loaded.
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.template_spaces.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 fetching files.