neurocaps.analysis.CAP.caps2niftis

CAP.caps2niftis(output_dir, suffix_file_name=None, fwhm=None, knn_dict=None)

Standalone Method to Convert CAPs to NifTI Statistical Maps.

Projects CAPs onto parcellation 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_title (str or None, default=None) -- Appended to the name of the saved file.

• 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.image.smooth_img.

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

  Use KNN (k-nearest neighbors) interpolation to fill in non-background coordinates that are assigned zero. This is primarily used as a fix for when a custom parcellation does not project well from volumetric to surface space. This method involves resampling a reference volumetric parcellation that projects well onto surface space (Schaefer or AAL), to the target parcellation specified in the "maps" sub-key in self.parcel_approach. The background coordinates are extracted from the reference parcellation and are used to obtain the non-background coordinates that are set to zero in the target parcellation. These coordinates are then replaced with the value of the nearest neighbor, determined by the sub-key "k". The following sub-keys are recognized:

  • "k": An integer that determines the number of nearest neighbors to consider, with the majority vote determining the new value. If not specified, the default is 1.

  • "reference_atlas": A string specifying the atlas to use as a reference to determine the background indices to not interpolate. Options includes "Schaefer" or "AAL". If not specified the default will be "Schaefer".

  • "resolution_mm": An integer (1 or 2) that determines the resolution of the Schaefer parcellation. If not specified, the default is 1. Only used when "reference_atlas" is "Schaefer".

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

  This method is applied before the fwhm.

  Added in version 0.18.0: "reference_atlas"

  Changed in version 0.18.0: "remove_subcortical" key changed to "remove_labels" and default of "k" changed 1 to 3

Returns:

NifTI1Image -- NifTI statistical map.

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[np.where(atlas_fdata == target_array[indx])] = value