comet.cifti

comet.cifti.get_networks(labels: list[str]) → tuple[list[str], ndarray, list[str], dict[str, int]]

Extract network information for Schaefer-Yeo parcellations.

Parameters:

labels (list of str) – Atlas parcel labels obtained from cifti.parcellate().

Returns:

• networks (list of str) – Network label per parcel (length N).

• ids (np.ndarray) – Integer network ids per parcel (length N).

• hemisphere (list of str) – Hemisphere label per parcel (‘LH’ or ‘RH’; length N).

• network_map (dict[str, int]) – Mapping from network name to integer id.

Raises:

ValueError – If network labels cannot be inferred from the atlas labels.

comet.cifti.parcellate(dtseries: str | ~numpy.ndarray | ~nibabel.cifti2.cifti2.Cifti2Image | None = None, atlas: str = 'schaefer', resolution: int = 100, subcortical: None | str = None, networks: int = 7, kong: bool = False, standardize: bool = True, method=<function mean>, return_labels: bool = False, debug: bool = False) → ndarray | tuple[ndarray | None, list[str], ndarray]

Parcellate cifti data (.dtseries.nii) using a given atlas. Atlases for many different parameter combinations are available and will be downloaded on demand. If the atlas for the parameter combination is not available, a ValueError is raised.

References

• Schaefer, Glasser, Gordon (+ Tian subcortical): https://github.com/yetianmed/subcortex

• Schaefer + Yan (cortical only): https://github.com/ThomasYeoLab/CBIG

Note: Any cortical atlas can be used on its own or combined with any Tian scale. Combinations

without an available file are assembled at runtime from the cortical atlas plus the Tian subcortical block reused from the Gordon+Tian atlas.

Parameters:

• dtseries (str, np.ndarray nibabel.cifti2.cifti2.Cifti2Image) – string containing a path, array containing vertex data, or nibabel cifti image object

• atlas (string) – Name of the atlas to use for parcellation. Available options are: - “schaefer”: Schaefer et al. (2018) atlas - “yan”: Yan et al. (2023) homotopic atlas - “glasser”: Glasser et al. (2016) atlas - “gordon”: Gordon et al. (2016) atlas

• resolution (int) – Number of parcels in the atlas. Only used with the Schaefer and Yan atlases. Available options are: 100, 200, 300, 400, 500, 600, 700, 800, 900, 1000.

• subcortical (None or string) – If a string containing the scale is provided, the Tian subcortical parcels are included. Available options are: None, ‘S1’ (16 ROIs), ‘S2’ (32 ROIs), ‘S3’ (50 ROIs), ‘S4’ (54 ROIs). Works with every atlas at any scale: None gives a cortical-only parcellation, a scale appends the Tian structures (keyed first). Cortical parcel counts: schaefer/yan = resolution, glasser = 360, gordon = 333.

• networks (int) – Number of networks in the atlas. Only used with Schaefer atlas. Available options are: 7, 17

• kong (bool) – Use the Kong 2022 version of the Schaefer atlas (only for Schaefer cortical atlas with 17 networks). Reference: https://doi.org/10.1093/cercor/bhab101

• standardize (bool) – Standardize the time series to zero (temporal) mean and unit variance before parcellation.

• method (function) – Aggregation function to use for parcellation. Default (and the only tested function) is np.mean.

• debug (bool) – Flag to provide additional debugging information. Default is False.

Returns:

ts_parc –

If return_labels is False (default):

• ts_parc(T, P) np.ndarray

  Parcellated time series data.

If return_labels is True:

• ts_parc(T, P) np.ndarray

  Parcellated time series data. None if no input data was provided.

• node_labelslist of str

  Label name for each parcel.

• vertex_labelsnp.ndarray

  ROI index for each vertex in the CIFTI file.

Return type:

np.ndarray or tuple

comet.cifti.subcortical_plot(node_values: ndarray | list[float] | None = None, scale: str = 'S1', surface: str | None = 'inflated', view_names: tuple[str, ...] = ('lateral', 'medial'), ncols: int | None = None, colwise: bool = True, cmap: str = 'viridis', nan_color: str = 'lightgray', nan_alpha: float = 0.0, surface_color: str = 'lightgray', surface_alpha: float = 0.1, smooth_iter: int = 20, smooth_relaxation: float = 0.2, distance: float = 600.0, size: list[int] | None = None, labelsize: int = 18, colorbar: None | str = 'bottom', colorbar_label: str | None = None, interactive: bool = True, fname: str | None = None)

Plot Tian subcortical structures for scale S1 to S4.

If node_values contains cortex + subcortex values from parcellate(..., subcortical=scale), the first N values are used automatically, where N is the number of Tian meshes for that scale. The combined atlases place the subcortical parcels in the leading columns, and both the parcels and the meshes are ordered by Tian region id, so the i-th value maps to the i-th mesh.

comet.cifti.surface_plot(node_values: ndarray | None = None, vertex_labels: ndarray | None = None, hemi: str = 'both', surface: str = 'inflated', view_names: tuple[str, str] = ('medial', 'lateral'), ncols: int | None = None, colwise: bool = True, cmap: str = 'viridis', border_color: None | str = None, border_width: int = 5, distance: float = 400.0, size: list[int] | None = None, labelsize: int = 18, colorbar: None | str = 'bottom', colorbar_label: str | None = None, interactive: bool = True, fname: str | None = None)

Plot cortical hemispheres with optional parcel border overlays.

Parameters:

• node_values (ndarray or None) – Parcel-level values (1D). If None, only surfaces are shown.

• vertex_labels (ndarray or None) – Vertex-to-parcel labels for both hemispheres (length 64984).

• hemi ({"left", "right", "both"}) – Hemisphere(s) to render.

• surface (str) – Surface type. Valid options are: - “midthickness_orig” - “midthickness_mni” - “inflated” - “very_inflated” - “super_inflated” - “sphere”

• view_names (tuple containing one or multiple strings) – Views to render per hemisphere. Options are: - “lateral” - “medial” - “anterior” - “posterior” - “superior” - “inferior”

• ncols (int or None) – Number of subplot columns.

• colwise (bool) – If True (default), fill subplots column-wise, else fill row-wise.

• cmap (str) – Colormap for node values.

• border_color (str or None) – Border color. If None, no border overlay is added.

• border_mode ({"lines", "mask"}) – Border rendering mode. “lines” draws smooth edge lines (default). “mask” uses the legacy vertex-mask overlay method.

• border_line_smoothing (int) – Number of Chaikin smoothing iterations for line borders. Only used when border_mode="lines".

• border_line_decimate (int) – Keep every Nth point along each border polyline before smoothing. Use 1 to keep all points. Only used when border_mode="lines".

• distance (float) – Camera distance.

• size (tuple[int, int] or None) – Plotter window size.

• colorbar ({"bottom", "right", None}) – Shared colorbar placement outside data panels. If None, no colorbar is shown.

• colorbar_label (str or None) – Label for the colorbar.

• interactive (bool) – Show the plot in an interactive window (default is True).

• fname (string or None) – Save the plot (will consider manipulations done in the interactive window). The name should contain the desired file type with the options being: - Raster: “.png”, “.jpeg”, “.jpg”, “.bmp”, “.tif”, “.tiff” - Vectorised: “.svg”, “.eps”, “.ps”, “.pdf”, “.tex”