CAP.caps2surf#

CAP.caps2surf(output_dir=None, suffix_title=None, suffix_filename=None, show_figs=True, fwhm=None, fslr_density='32k', method='linear', save_stat_maps=False, fslr_giftis_dict=None, knn_dict=None, progress_bar=False, as_pickle=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:

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

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

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

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

  • fwhm (float or None, defualt=None) – Strength of spatial smoothing to apply (in millimeters) to the statistical map prior to interpolating from MNI152 space to fsLR surface space.

  • fslr_density ({"4k", "8k", "32k", "164k"}, default="32k") – Density of the fsLR surface when converting from MNI152 space to fsLR surface. Options are “32k” or “164k”. If using fslr_giftis_dict options are “4k”, “8k”, “32k”, and “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”.

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

  • fslr_giftis_dict (dict or None, default=None) –

    Dictionary specifying precomputed GifTI files in fsLR space for plotting statistical maps.

    {"GroupName": {"CAP-Name": {"lh": "path/to/left_hemisphere_gifti", "rh": "path/to/right_hemisphere_gifti"}

  • knn_dict (dict[str, 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 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 or array (Default=None). The label IDs as integers of the regions in the parcellation to not interpolate.

    Note

    KNN interpolation is applied before fwhm.

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

  • as_pickle (bool, default=False) –

    When output_dir is specified, plots are saved as pickle files, which can be further modified, instead of png images.

    Added in version 0.26.5.

  • **kwargs –

    Additional parameters to pass to modify certain plot parameters. Options include:

    • dpi: int, default=300 – Dots per inch for the plot.

    • title_pad: int, default=-3 – Padding for the plot title.

    • cmap: str or callable, default=”cold_hot” – Colormap to be used for the plot.

    • cbar_kws: dict, default={“location”: “bottom”, “n_ticks”: 3} – Customize colorbar. Refer to _add_colorbars for surfplot.plotting.Plot in Surfplot’s Plot Documentation for valid parameters.

    • alpha: float, default=1 – Transparency level of the colorbar.

    • as_outline: bool, default=False – Plots only an outline of contiguous vertices with the same value.

    • outline_alpha: float, default=1 – Transparency level of the colorbar for outline if as_outline is True.

    • zero_transparent: bool, default=True – Turns vertices with a value of 0 transparent.

    • size: tuple, default=(500, 400) – Size of the plot in pixels.

    • layout: str, default=”grid” – Layout of the plot.

    • zoom: float, default=1.5 – Zoom level for the plot.

    • views: {“lateral”, “medial”} or list[{"lateral", "medial}], default=[“lateral”, “medial”] – Views to be displayed in the plot.

    • brightness: float, default=0.5 – Brightness level of the plot.

    • figsize: tuple or None, default=None – Size of the figure.

    • scale: tuple, default=(2, 2) – Scale factors for the plot.

    • surface: {“inflated”, “veryinflated”}, default=”inflated” – The surface atlas that is used for plotting. Options are “inflated” or “veryinflated”.

    • color_range: tuple or None, default=None – The minimum and maximum value to display in plots. For instance, (-1, 1) where minimum value is first. If None, the minimum and maximum values from the image will be used.

    • bbox_inches: str or None, default=”tight” – Alters size of the whitespace in the saved image.

Returns:

self

Important

Parcellation Approach: parcel_approach must have the “maps” subkey containing the path to th 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.

Additionally, this funcition assumes that the parcellation map is in volumetric MNI space unless fslr_giftis_dict is defined, then this function assumes the maps are in surface space.

On this page