ultrasound_metrics.metrics.tsnr
===============================

.. py:module:: ultrasound_metrics.metrics.tsnr

.. autoapi-nested-parse::

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

.. autoapisummary::

   ultrasound_metrics.metrics.tsnr.tsnr


Module Contents
---------------

.. py:function:: tsnr(data: ultrasound_metrics._utils.array_api.ArrayAPIObj, *, output_db: bool = False) -> ultrasound_metrics._utils.array_api.ArrayAPIObj

   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)

   :param 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
   :param 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.
   :rtype: 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).

   .. rubric:: 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