CAP.caps2niftis#

CAP.caps2niftis(output_dir, suffix_filename=None, knn_dict=None, progress_bar=False)[source]#

Convert CAPs to NIfTI Statistical Maps.

Projects CAPs onto the parcellation in defined in parcel_approach to create compressed NIfTI (.nii.gz) statistical maps. One image is generated per CAP and separate images are generated per group.

Parameters:

  • output_dir (str) – 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.

  • knn_dict (dict[str, int | list[int] | str ], default=None) –

    Use KNN (k-nearest neighbors) interpolation with reference atlas masking (which is native to volume space) to fill in non-background coordinates that are assigned zero. Useful when a “Custom” parcellation does not project well from volumetric to surface space (typically cortical parcellations converted into volumetric format). The following subkeys are recognized:

    • ”k”: An integer (Default=1). Determines the number of nearest neighbors to consider.

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

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

    • ”remove_labels”: A list (Default=None). The label IDs as integers of the regions in the parcellation to not interpolate.

    • ”method”: A string (Default=”majority_vote”). Method used to assign new values to non-background voxels (“majority_vote” or “distance_weighted”). For majority vote, the most frequently appearing value among “k” choices (or chosen neighbors) is, while the distance weighted approach uses inverse distance weighting (1/distance) to estimate the new averaged value for the non-background voxel.

  • progress_bar (bool, default=False) – If True, displays a progress bar.

Returns:

self

Important

Parcellation Approach: parcel_approach must have the “maps” subkey containing the path to the parcellation NIfTI file.

Assumption: This function assumes that the background label for the parcellation is zero. When the numerical labels from the parcellation map are extracted, the first element (assumed to be zero/the background label after sorting) is skipped. Then the remaining sorted labels are iterated over to map each element of the CAP cluster centroid onto the corresponding non-zero label IDs in the parcellation.

On this page