Quality Control¶

Quality control (QC) in fUSI aims to identify problematic time points, assess spatial signal quality across the brain, and flag acquisitions that may need to be discarded or corrected before downstream analysis.

ConfUSIus provides three QC metrics, divided into two categories:

DVARS¶

DVARS (temporal Derivative of VARianceS) measures how much the signal intensity changes between consecutive time points, averaged across all brain voxels¹. A spike in DVARS typically indicates a motion event, a scanner artifact, or another transient disturbance that corrupted one or more volumes.

By default, ConfUSIus computes the standardized DVARS², which accounts for the temporal autocorrelation structure of the data and is therefore more comparable across acquisitions. Standardized DVARS is approximately 1 for a stationary recording; values significantly above 1 indicate outlier volumes.

Usage¶

DVARS is computed from any (time, ...) DataArray—spatial dimensions are flattened internally. Using brain-masked signals is recommended to exclude background voxels that inflate the variance estimate:

import xarray as xr
import confusius as cf
from confusius.qc import compute_dvars

pwd = cf.load("sub-01_task-awake_pwd.zarr")
brain_mask = cf.load("brain_mask.zarr")

# Extract brain voxel time-series first.
signals = pwd.fusi.extract.with_mask(brain_mask)

# Compute standardized DVARS (default).
dvars = compute_dvars(signals)
# dvars has dims (time,).

Visualizing and Thresholding¶

DVARS is a time series and is best examined as a line plot. Flagged frames can be marked for quick visual inspection:

import matplotlib.pyplot as plt

threshold = 3
flagged = dvars > threshold

fig, ax = plt.subplots(figsize=(10, 3))
dvars.plot(ax=ax, linewidth=0.8, label="Standardized DVARS")
dvars[flagged].plot(ax=ax, marker="o", linestyle="", color="red", ms=3, label="Flagged frames")
ax.axhline(threshold, color="red", linestyle="--", label=f"Threshold ({threshold})")
ax.legend()

print(f"{flagged.sum().item()} outlier frames detected out of {len(dvars)} total.")

Simply dropping flagged frames introduces discontinuities in the time series and can bias downstream connectivity estimates. The recommended approach is to pass the outlier mask to the scrubbing step in the signal cleaning pipeline—see Signal Processing for details.

Carpet Plot¶

A carpet plot (also known as a grayplot or Power plot) displays the voxel intensity time series as a 2D raster image—time on the x-axis, voxels on the y-axis—making it easy to spot global signal disturbances, motion spikes, and scanner drift that DVARS alone may not fully characterize.

from confusius.plotting import plot_carpet

fig, ax = plot_carpet(pwd, mask=brain_mask)

Vertical streaks across voxels correspond to time points where many voxels change simultaneously. Horizontal banding can reveal spatially structured noise such as pulsatility or drift confined to specific voxel groups.

Coefficient of Variation¶

The coefficient of variation (CV) is a voxel-wise spatial metric defined as the ratio of temporal standard deviation to temporal mean:

CV quantifies how variable the signal is relative to its mean. In fUSI:

• High CV typically indicates voxels affected by motion, pulsatility artifacts, or other sources of noise.
• Low CV indicates temporally stable voxels with little variation relative to their mean signal level.

Usage¶

from confusius.qc import compute_cv

# Compute CV on the full spatial DataArray directly.
cv = compute_cv(pwd)
# cv has dims (z, y, x) — the time dimension is reduced.

Visualizing¶

Comparing CV to the mean power Doppler image helps interpret the map: motion artifacts appear as regions of elevated CV, while vascular structure appears with low CV.

Temporal SNR¶

The tSNR function is provided for completeness and for compatibility with workflows that report it:

from confusius.qc import compute_tsnr

tsnr = compute_tsnr(pwd)

Comparing tSNR to the mean power Doppler image makes the paradox concrete: low-signal regions—gel layers, shadow zones—appear bright in tSNR because their mean signal, though small in absolute terms, remains large relative to their near-zero temporal variability.

Next Steps¶

After quality control, you're ready to move on to:

1. Registration: Correct for motion and align acquisitions to an anatomical template.
2. Signal Processing: Extract regional signals and apply denoising.

API Reference¶

For full parameter documentation, see the QC API reference.