neurocaps.analysis.CAP.caps2surf

CAP.caps2surf(output_dir=None, suffix_title=None, show_figs=True, fwhm=None, fslr_density='32k', method='linear', save_stat_maps=False, fslr_giftis_dict=None, knn_dict=None, **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 (os.PathLike 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 as well as the name of the saved file 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.

Changed in version 0.16.0: changed from save_stat_map to save_stat_maps.
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 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 "AAL" or "Schaefer". 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" key added

Changed in version 0.18.0: "remove_subcortical" key changed to "remove_labels"
kwargs (dict) --
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. For this parameter, you can use pre-made color palettes or create custom ones. Below is a list of valid options:
  - Strings to call nilearn.plotting.cm._cmap_d fuction.
  - matplotlib.colors.LinearSegmentedColormap to generate custom colormaps.
- cbar_kws: dict, default={"location": "bottom", "n_ticks": 3}
  Customize colorbar. Refer to _add_colorbars at for valid kwargs in surfplot.plotting.Plot documentation listed in the Note section.
- alpha: float, default=1
  Transparency level of the colorbar.
- 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.
- as_outline: bool, default=False
  Plots only an outline of contiguous vertices with the same value.
- 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:

NifTI1Image -- NifTI statistical map.
surfplot.plotting.Plot -- An instance of surfplot.plotting.Plot.

Note

Parcellation Approach: parcel_approach must have the "maps" sub-key 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[np.where(atlas_fdata == target_array[indx])] = value