neurocaps.analysis.CAP.caps2niftis

CAP.caps2niftis(output_dir, suffix_filename=None, fwhm=None, knn_dict=None, progress_bar=False)

Standalone Method to Convert CAPs to NifTI Statistical Maps.

Projects CAPs onto the parcellation in self.parcel_approach to create NifTI statistical maps by replacing parcellation labels with their corresponding CAP (cluster centroid) values. Creates compressed NifTI (.nii.gz) files. One image is generated per CAP. Note, if groups were given when the CAP class was initialized, separate NifTI images will be generated per CAP for all groups.

Parameters:

• output_dir (os.PathLike) -- Directory to save nii.gz files. The directory will be created if it does not exist.

• suffix_filename (str or None, default=None) --

  Appended to the name of the saved file.

  Changed in version 0.19.0: suffix_file_name to suffix_filename

• fwhm (float or None, default=None) -- Strength of spatial smoothing to apply (in millimeters) to the statistical map prior to interpolating from MNI152 space to fsLR surface space. Uses Nilearn's image.smooth_img.

• knn_dict (dict[str, Union[int, bool]], default=None) --

  Use KNN (k-nearest neighbors) interpolation with reference atlas masking to fill in non-background coordinates that are assigned zero. Useful when custom parcellation does not project well from volumetric to surface space. The following sub-keys are recognized:

  • "k": An integer. Determines the number of nearest neighbors to consider. Default is 1.

  • "reference_atlas": A string. Specifies the atlas to use for reference masking ("AAL" or "Schaefer"). Default is "Schaefer".

  • "resolution_mm": An integer (1 or 2). Spatial resolution of the Schaefer parcellation (in millimeters). Default is 1.

  • "remove_labels": A list or array. The label IDs as integers of the regions in the parcellation to not interpolate.

  Note: This method is applied before the fwhm.

• progress_bar (bool, default=False) --

  If True, displays a progress bar.

  Added in version 0.21.5.

Returns:

self

Added in version 0.19.3.

Note

Assumption: This function assumes that the background label for the parcellation is zero. Additionaly, the following approach is used to map each CAP onto the parcellation.

atlas = nib.load(atlas_file)
atlas_fdata = atlas.get_fdata()
# Create array of zeroes with same dimensions as atlas
atlas_array = np.zeros_like(atlas_fdata)

# Get array containing all labels in parcellation in order
target_array = sorted(np.unique(atlas_fdata))

# Start at 1 to avoid assigment to the background label
for indx, value in enumerate(cap_vector, start=1):
    atlas_array[atlas_fdata == target_array[indx]] = value