neurocaps.analysis.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, **kwargs)[source]#

Project CAPs onto Surface Plots.

Plot CAPs on cortical surface in fsLR space. First, projects CAPs onto parcellation to create NifTI statistical maps by replacing parcellation labels with their corresponding CAP (cluster centroid) values. Then uses neuromap’s transforms.mni152_to_fslr for coordinate system transformation and surfplot’s Plot for plotting. If CAPs where already converted to NifTI (self.caps2niftis()) and transformed to fsLR GifTI files externally, these can be provided using the fslr_giftis_dict parameter and will be converted to a suitable format for surfplot’s Plot function by using neuromap’s transforms.fslr_to_fslr function. Note, if groups were given when the CAP class was initialized, surface plots will be generated per CAP for all groups.

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. Uses Nilearn’s image.smooth.

  • 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. This parameter should be used if the statistical CAP NIfTI files (can be obtained using self.caps2niftis()) were converted to GifTI files using a tool such as Connectome Workbench. The dictionary structure is:

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

    ”GroupName” can be “All Subjects” or any specific group name. CAP-Name is the name of the CAP. This parameter allows plotting without re-running the analysis. Initialize the CAP class and use this method if using this parameter.

  • 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: This method is applied before the fwhm.

  • progress_bar (bool, default=False) –

    If True, displays a progress bar.

    Added in version 0.21.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

Note

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 and that is in MNI space. Additionally, the following approach is taken to map the 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
On this page