confusius.qc¶

Compute the coefficient of variation (CV).

CV is the ratio of the temporal standard deviation to the temporal mean, computed voxel-wise. It is the inverse of tSNR and provides a normalized measure of temporal variability that is independent of signal magnitude.

Parameters:

• signals ¶

  ((time, ...) xarray.DataArray) –

  Signals to compute CV from. Must have a time dimension. Additional dimensions represent spatial locations (e.g., space, z/y/x).

Returns:

• DataArray –

  Spatial map of CV values with the time dimension reduced. Voxels with zero temporal mean yield inf (or NaN if the standard deviation is also zero). The returned array has long_name="Coefficient of variation", units="a.u.", and cmap="viridis" in its attrs.

Raises:

• ValueError –

  If signals has no time dimension or if the time dimension has only 1 timepoint.

Examples:

>>> import numpy as np
>>> import xarray as xr
>>> from confusius.qc import compute_cv
>>> rng = np.random.default_rng(42)
>>> data = rng.standard_normal((100, 50)) + 10.0
>>> signals = xr.DataArray(
...     data,
...     dims=["time", "space"],
...     coords={"time": np.arange(100) * 0.1},
... )
>>> cv = compute_cv(signals)
>>> cv.shape
(50,)

Compute the DVARS metric.

DVARS (D referring to temporal derivative, VARS to RMS variance) measures how much the intensity at one time point changes relative to the previous time point. The standardized version accounts for the expected variance given the temporal autocorrelation structure of the data.

This function was adapted from nipype.algorithms.confounds.compute_dvars.

Parameters:

• signals ¶

  ((time, ...) xarray.DataArray) –

  Signals to compute DVARS from. Must have a time dimension. Any additional dimensions (e.g., pose, z, y, x) are flattened to a single space dimension before computation.

• standardize ¶

  (bool, default: True ) –

  Whether to computed the standardized DVARS. When True, the DVARS values are standardized by the expected standard deviation given the AR(1) structure of the data. When False, return non-standardized DVARS (raw RMS of temporal differences).

• normalization_factor ¶

  (float or None, default: 1000 ) –

  Normalization factor applied to the median signal intensity. If None, no normalization is performed. Note that standardized DVARS is invariant to intensity normalization.

• remove_zero_variance ¶

  (bool, default: True ) –

  Whether to exclude signals with near-zero variance. Zero-variance signals can artificially reduce the median during intensity normalization and should typically be removed.

• variance_tolerance ¶

  (float, default: 0.0 ) –

  Tolerance for identifying zero-variance signals. Signals with robust standard deviation (IQR/1.349) less than or equal to this value are considered to have zero variance.

Returns:

• (time,) xarray.DataArray –

  DVARS values with time coordinates matching input. When standardized is True, returns standardized DVARS. The first element is set to the minimum DVARS value (following FSL convention).

Examples:

>>> import numpy as np
>>> import xarray as xr
>>> from confusius.qc import compute_dvars
>>> # Generate synthetic 2D signals: 100 time points, 50 voxels
>>> rng = np.random.default_rng(42)
>>> data = rng.standard_normal((100, 50))
>>> # Add AR(1) structure
>>> for t in range(1, 100):
...     data[t] = 0.5 * data[t - 1] + 0.5 * data[t]
>>> signals = xr.DataArray(
...     data,
...     dims=["time", "space"],
...     coords={"time": np.arange(100) * 0.1},
... )
>>> # Compute standardized DVARS (default)
>>> dvars_stdz = compute_dvars(signals)
>>> dvars_stdz.shape
(100,)
>>> # Compute non-standardized DVARS
>>> dvars_nstd = compute_dvars(signals, standardize=False)
>>> dvars_nstd.shape
(100,)

Compute the temporal signal-to-noise ratio (tSNR).

tSNR is defined as the ratio of the temporal mean to the temporal standard deviation, computed voxel-wise. It provides a spatial map of signal stability over time: higher tSNR indicates a more stable signal relative to its mean.

Parameters:

• signals ¶

  ((time, ...) xarray.DataArray) –

  Signals to compute tSNR from. Must have a time dimension. Additional dimensions represent spatial locations (e.g., space, z/y/x).

Returns:

• DataArray –

  Spatial map of tSNR values with the time dimension reduced. Voxels with zero temporal standard deviation (constant signals) yield inf. The returned array has long_name="Temporal signal-to-noise ratio", units="a.u.", and cmap="viridis" in its attrs.

Raises:

• ValueError –

  If signals has no time dimension or if the time dimension has only 1 timepoint.

Examples:

>>> import numpy as np
>>> import xarray as xr
>>> from confusius.qc import compute_tsnr
>>> rng = np.random.default_rng(42)
>>> data = rng.standard_normal((100, 50)) + 10.0
>>> signals = xr.DataArray(
...     data,
...     dims=["time", "space"],
...     coords={"time": np.arange(100) * 0.1},
... )
>>> tsnr = compute_tsnr(signals)
>>> tsnr.shape
(50,)