stat_tools

subcortexmesh.stat_tools.slm_analysis(inputdir: str | Path, metric: str | Sequence[str], roilabel: str | Sequence[str], model: brainstat._typing.ArrayLike, contrast: brainstat._typing.ArrayLike, mask: brainstat._typing.ArrayLike = None, correction: str | Sequence[str] | None = None, thetalim: float = 0.01, drlim: float = 0.1, two_tailed: bool = True, cluster_threshold: float = 0.001, smooth: float | None = None, sub_list: Sequence[str] | None = None)[source]

Vertex-wise analysis with random field theory cluster correction

This function is a wrapper for BrainStat’s SLM (Standard Linear regression models) modelling functions, which fit linear or linear mixed models with surface-based values, with random field theory cluster correction. You may refer to their tutorial to understand the model and contrast arguments: https://brainstat.readthedocs.io/en/master/python/tutorials/tutorial_1.html

slm_analysis() automatically collates surface-based measures in template space from a surface_metrics/ folder produced by mesh_metrics() (or equivalent folder), in alphanumeric order of the subjects’ subfolders, and fits them as the “surf” argument in BrainStat. The model returns t-statistics, p-values,and Random field theory clusters map for a selected contrast.

Note for SLM: The first surface is used as “template” given it works for template-space surfaces.

Parameters:

  • inputdir (str, Path) – The surface_metrics/ directory where the surface-based metrics were outputted (using mesh_metrics()) or a directory with the same tree structure (subject folders, each with metrics .vtk files inside).

  • roilabel (str, Sequence) – The name or array of names for the region(s)-of-interest to analyse: ‘left-cerebellum-cortex’, ‘right-cerebellum-cortex’, ‘left-pallidum’, ‘right-pallidum’, ‘left-putamen’, ‘right-putamen’, ‘left-thalamus’, ‘right-thalamus’,’left-amygdala’, ‘right-amygdala’, ‘left-hippocampus’, ‘right-hippocampus’, ‘left-accumbens-area’,’right-accumbens-area’,’left-caudate’, ‘right-caudate’, ‘left-ventraldc’, ‘right-ventraldc’, and ‘brain-stem’.

  • model (brainstat.stats.terms.FixedEffect, brainstat.stats.terms.MixedEffect) – The linear model to be fitted of dimensions (observations, predictors).

  • contrast (array-like) – Vector of contrasts from the observations.

  • mask (array-like, optional) – A mask containing True for vertices to include in the analysis, by default None.

  • correction (str, Sequence, optional) – String or sequence of strings. If it contains “rft” a random field theory multiple comparisons correction will be run. If it contains “fdr” a false discovery rate multiple comparisons correction will be run. Both may be provided. By default None.

  • thetalim (float, optional) – Lower limit on variance coefficients in standard deviations, by default 0.01.

  • drlim (float, optional) – Step of ratio of variance coefficients in standard deviations, by default 0.1.

  • two_tailed (bool, optional) – Determines whether to return two-tailed or one-tailed p-values. Note that multivariate analyses can only be two-tailed, by default True.

  • cluster_threshold (float, optional) – P-value threshold or statistic threshold for defining clusters in random field theory, by default 0.001.

  • smooth (float, optional) – The full-maximum half-width (FMHW) value that will be applied for smoothing of the surface-based measure along the surface. Default is None.

  • sub_list (str, Sequence) – An optional list of subject IDs to determine whose surface is to be included in the analysis. Surfaces whose path does not contain a subject ID from the list will be ignored. If not specified, all surfaces found will be included.

Returns:

BrainStat SLM object containing the statistical outputs.

Return type:

slm_model

subcortexmesh.stat_tools.slm_plot(slm, stat: str, threshold: float | None = None, cmap: str = None, clim: Tuple[float, float] | None = None, smooth_mesh: int | None = 0, mode: str = 'anatomical', flatmode_filepath: str | Path = 'flat_plot.png')[source]

Plot SLM result maps on their respective surface.

Authors: Charly H.A. Billaud, Nicolas P.M. Lavarde

Parameters:

  • slm (SLM object) – BrainStat SLM object containing the statistical outputs.

  • stat (str) –

    Map to plot from the SLM object:

    • ’t’ for the t-statistics map

    • ’t_fdr’ for the t-statistics map filtered based on significance after false discovery rate (FDR) (use threshold argument)

    • ’t_rft’ for the t-statistics map filtered based on significance of random field theory (RFT) cluster-wise p-values (use threshold argument)

    • ’p_fdr’ for the FDR-adjusted p-value map

    • ’p_rft’ for the p-value map filtered based on significance of random field theory (RFT) cluster-wise p-values (use threshold argument)

    • ’clusters’ for the identified clusters

  • threshold (float, optional) – Thresholding value in which vertices are to be plotted (plots values below the set threshold for t_fdr, t_rft, p_fdr_, p_rft, and clusters; above the absolute threshold for t).

  • cmap (str) – Name of the color map to be assigned to the background volume, as listed in matplotlib’s colormaps. Default is “RdBu_r” if the plot shows both negative and positive effects, ‘Blues_r’ or negative only, ‘Reds’ for positive only.

  • clim (Tuple, optional) – Sequence of float stating the minimum and maximum value of the color bar. Default is minimum and maximum value. It is not applied for the clusters maps as colour values follow cluster IDs.

  • smooth_mesh (int, optional) – Number of iterations of cosmetic smoothing to make the surface appear smoother. Default is 0.

  • mode (str, optional) – Rendering mode for all regions merged (see merge_all() for the example output): ‘flat’ (2D PNG grid via vis_merged_flat), or ‘anatomical’ (interactive spread viewer via vis_merged). Argument ignored if individual ROIs are provided.

  • flatmode_filepath (str, Path, optional) – Output path for the PNG when all ROIs merged are provided and mode=’flat’. Default is ‘flat_plot.png’.