ultrasound_metrics.metrics.tsnr

ultrasound_metrics.metrics.tsnr#

Temporal Signal-to-Noise Ratio (tSNR) for ultrasound speckle.

This module provides functions for computing the temporal SNR of ultrasound speckle over multiple acquisitions, which is useful for quantifying decorrelation, evaluating probe motion, and checking image stability in repeated scans.

This method is closely related to the repeated-measurements and adjacent-frame SNR estimates used in noise.py, but retains per-pixel granularity rather than aggregating into a single value.

Functions#

tsnr(→ ultrasound_metrics._utils.array_api.ArrayAPIObj)

Compute the temporal Signal-to-Noise Ratio (tSNR) of ultrasound speckle.

Module Contents#

ultrasound_metrics.metrics.tsnr.tsnr(
data: ultrasound_metrics._utils.array_api.ArrayAPIObj,
*,
output_db: bool = False,
) → ultrasound_metrics._utils.array_api.ArrayAPIObj[source]#

Compute the temporal Signal-to-Noise Ratio (tSNR) of ultrasound speckle.

This function evaluates the stability of signal over time at each spatial location (pixel or voxel) using signal decomposition.

tSNR(x, y, z) = signal_power(x, y, z) / noise_power(x, y, z) where: - signal_power is the power of the temporal mean (stable component) - noise_power is the power of temporal variations (unstable component)

Parameters:

  • data – Input data with shape (x, [y,], z, t) or (x, t) where: - x, y, z are spatial dimensions (y is optional for 2D data) - t is the time dimension (repeated acquisitions/frames) - For ROI analysis, spatial dimensions can be flattened to (x, t) - Can be real or complex floating-point data

  • output_db – If True, return tSNR in decibels: 10 * log10(signal_power / noise_power) If False, return tSNR in linear scale: signal_power / noise_power Default is False.

Returns:

Temporal SNR values with shape (x, [y,], z). Each pixel/voxel contains the tSNR value for that spatial location.

Return type:

ndarray

Raises:

ValueError – If data has fewer than 2 dimensions or if time dimension has fewer than 2 points.

Warns:

UserWarning – If noise power is zero for some pixels (would cause division by zero).

Notes

  • For 2D data, input shape should be (x, z, t)

  • For 3D data, input shape should be (x, y, z, t)

  • For ROI analysis, flattened spatial data can use shape (x, t)

  • The time dimension (t) must have at least 2 points to compute temporal mean

  • Zero noise power will cause a warning and return +inf for those pixels

  • Complex data is handled by computing the magnitude (absolute value) before processing

  • Uses signal decomposition: signal = temporal_mean, noise = data - signal