ultrasound_metrics.metrics.snr
==============================

.. py:module:: ultrasound_metrics.metrics.snr

.. autoapi-nested-parse::

   Signal-to-Noise Ratio (SNR) metric for ultrasound, commonly used for speckle.

   This module provides functions to calculate the Signal-to-Noise Ratio (SNR)
   for ultrasound speckle patterns. The SNR is calculated as mean/standard-deviation.

   .. rubric:: References

   .. [1] C. B. Burckhardt, "Speckle in Ultrasound B-mode Scans," in IEEE Transactions
          on Sonics and Ultrasonics, vol. 25, no. 1, pp. 1-6, Jan. 1978,
          doi: 10.1109/T-SU.1978.30978.
   .. [2] D. Perdios, M. Vonlanthen, F. Martinez, M. Arditi and J. -P. Thiran,
          "CNN-Based Image Reconstruction Method for Ultrafast Ultrasound Imaging,"
          in IEEE Transactions on Ultrasonics, Ferroelectrics, and Frequency Control,
          vol. 69, no. 4, pp. 1154-1168, April 2022, doi: 10.1109/TUFFC.2021.3131383.



Functions
---------

.. autoapisummary::

   ultrasound_metrics.metrics.snr.snr


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

.. py:function:: snr(values: jaxtyping.Num[ultrasound_metrics._utils.array_api.ArrayAPIObj,  *pixels], *, db: bool = False) -> float

   Calculate Signal-to-Noise Ratio (SNR) of an image.

   This function computes the Signal-to-Noise Ratio (SNR) for ultrasound speckle
   patterns by calculating mean/standard-deviation.
   This metric provides a single value per ROI/image.

   .. math::

       \text{SNR} = \frac{\mathbb{E}[X]}{\sqrt{\text{Var}(X)}}

   where:

   - :math:`\mathbb{E}[X]` is the mean (average pixel value) across the (post-envelope) image
   - :math:`\text{Var}(X)` is the variance of pixel values across the (post-envelope) image

   In ultrasound, the statistics of fully developed speckle signals
   (post envelope detection) follow a Rayleigh distribution, and
   the SNR of a Rayleigh distribution is equal to:

   .. math::

       \text{SNR}_{\text{Rayleigh}} = \sqrt{\frac{\pi}{4 - \pi}} \approx 1.91

   :param values: Input values.
                  - spatial dimensions are flattened
                  - Can be real or complex floating-point data
   :type values: array
   :param db: If True, return the SNR in decibels (dB). Default is False.
   :type db: bool, optional

   :returns: Signal-to-Noise Ratio (SNR) of the values. If ``db=True``, the SNR is returned in decibels (dB).
   :rtype: float

   :Warns: **UserWarning** -- If variance is zero (would cause division by zero).

   .. rubric:: Notes

   - This implementation is an amplitude ratio, not a power ratio.
   - Complex data is handled by computing the magnitude (absolute value) before processing
   - For Rayleigh-distributed speckle, the theoretical SNR is approximately 1.91
   - If ROI is used, it should be applied to the input values before calling this function