CAP.caps2surf#

CAP.caps2surf(fslr_density='32k', method='linear', output_dir=None, plot_output_format='png', suffix_filename=None, suffix_title=None, save_stat_maps=False, knn_dict=None, show_figs=True, progress_bar=False, **kwargs)[source]#

Project CAPs onto Surface Plots.

Projects CAPs onto the parcellation defined in parcel_approach to create NIfTI statistical maps. Then transforms these maps from volumetric to surface space and generates visualizations. One surface plot image is generated per CAP and separate images are produced per group.

Parameters:

  • fslr_density ({"32k", "164k"}, default="32k") – Density of the fsLR surface when converting from MNI152 space to fsLR surface. Options are “32k” or “164k”.

  • method ({"linear", "nearest"}, default="linear") – Interpolation method to use when converting from MNI152 space to fsLR surface or from fsLR to fsLR. Options are “linear” or “nearest”.

  • output_dir (str or None, default=None) – Directory to save plots as png files. The directory will be created if it does not exist. If None, plots will not be saved.

  • plot_output_format (str, default=”png”) –

    The format to save plots in when output_dir is specified. Options are “png” or “pkl” (which can be further modified). Note that “pickle” is also accepted.

    Changed in version 0.33.0: Replaces as_pickle and accepts a string value.

  • suffix_filename (str or None, default=None) – Appended to the filename of each saved plot if output_dir is provided.

  • suffix_title (str or None, default=None) – Appended to the title of each plot.

  • save_stat_maps (bool, default=False) – If True, saves the statistical map for each CAP for all groups as a Nifti1Image if output_dir is provided.

  • knn_dict (dict[str, int | list[int] | bool], 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.

  • show_figs (bool, default=True) – Display figures.

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

  • **kwargs – Additional keyword arguments for customizing plots. See neurocaps.utils.PlotDefaults.caps2surf() for all available options and their default values (See PlotDefaults Documentation for caps2surf)

Returns:

self

Important

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

Assumptions: This function assumes that the background label for the parcellation is zero. During extraction of the numerical labels from the parcellation map, 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.

Space: Additionally, this funcition assumes that the parcellation map is in MNI volumetric space.

On this page