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 | ~nibabel.cifti2.cifti2.Cifti2Image, 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, list[str], ndarray, ndarray]

Parcellate cifti data (.dtseries.nii) using a given atlas. Atlases for many different parameter combinations are available and will be downloaded on demand (see References). 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 (cortical only): https://github.com/ThomasYeoLab/CBIG

Parameters:

• dtseries (str or nibabel.cifti2.cifti2.Cifti2Image) – string containing a path or nibabel cifti image object

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

• resolution (int) – Number of parcels in the atlas. Only used with Schaefer atlas. 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).

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

• node_labelslist of str

  Label name for each parcel.

• vertex_labelsnp.ndarray

  ROI index for each vertex in the CIFTI file.

• rgbalist of tuple

  RGBA colour for each parcel.

Return type:

np.ndarray or tuple

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”