ultrasound_metrics.metrics.rf_snr
=================================

.. py:module:: ultrasound_metrics.metrics.rf_snr

.. autoapi-nested-parse::

   Radiofrequency Signal-to-Noise Ratio (RF SNR) metric.

   This module provides functions to calculate the Signal-to-Noise Ratio (SNR)
   for radiofrequency ultrasound data. SNR quantifies how much stronger the
   signal (pulse echo) is compared to background noise.

   .. rubric:: References

   .. [1] H. Liebgott, A. Rodriguez-Molares, F. Cervenansky, J. A. Jensen and O. Bernard,
          "Plane-Wave Imaging Challenge in Medical Ultrasound," 2016 IEEE International
          Ultrasonics Symposium (IUS), Tours, France, 2016, pp. 1-4,
          doi: 10.1109/ULTSYM.2016.7728908.

   .. [2] P. Ecarlat, E. Carcreff, F. Varray, H. Liebgott and B. Nicolas, "Get Ready to Spy on Ultrasound: Meet ultraspy,"
          2023 IEEE International Ultrasonics Symposium (IUS), Montreal, QC, Canada, 2023, pp. 1-4,
          doi: 10.1109/IUS51837.2023.10307778.



Functions
---------

.. autoapisummary::

   ultrasound_metrics.metrics.rf_snr.compute_rf_snr
   ultrasound_metrics.metrics.rf_snr.find_signal_and_noise


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

.. py:function:: compute_rf_snr(signal_data: jaxtyping.Num[ultrasound_metrics._utils.array_api.ArrayAPIObj, *signal_dims], noise_data: jaxtyping.Num[ultrasound_metrics._utils.array_api.ArrayAPIObj, *noise_dims], *, center: bool = True, max_power: bool = False, show: bool = False, ax: Optional[matplotlib.pyplot.Axes] = None) -> float

   Calculate the Signal-to-Noise Ratio (SNR) for radiofrequency data.

   SNR quantifies how much stronger the signal (pulse echo) is compared to
   background noise. This metric is commonly used in ultrasound imaging quality
   assessment [1]_ and has been implemented in analysis tools [2]_.

   The calculation uses the formula:

   SNR (dB) = 10 * log10(signal_power / noise_power)

   where power is calculated as the Root Mean Square (RMS) squared.

   :param signal_data: The signal region data to evaluate. Should be a 1D array of RF values.
   :type signal_data: ArrayAPIObj
   :param noise_data: The noise region data to evaluate. Should be a 1D array of RF values.
   :type noise_data: ArrayAPIObj
   :param center: If True, center the signal and noise regions to zero mean before
                  calculating power. This removes DC offset effects.
   :type center: bool, optional
   :param max_power: If True, use the maximum squared value in the signal region instead
                     of the average power. Default is False (use average power).
   :type max_power: bool, optional
   :param show: If True, display a plot showing the signal and noise data.
   :type show: bool, optional
   :param ax: If set, plots the signal and noise data on the given Axes object.
   :type ax: plt.Axes, optional

   :returns: The Signal-to-Noise Ratio in decibels (dB).
   :rtype: float

   .. rubric:: Notes

   - Higher SNR values indicate better signal quality
   - Typical SNR values range from 30-100 dB for good quality RF data
   - Centering the data (center=True) is recommended to remove DC offset


.. py:function:: find_signal_and_noise(data: jaxtyping.Num[ultrasound_metrics._utils.array_api.ArrayAPIObj, *dims], signal_width: Union[int, list[int]] = 20, noise_offset: int = 50, ignore_until: int = 0, noise_size: Optional[int] = None, show: bool = False, ax: Optional[matplotlib.pyplot.Axes] = None) -> tuple[jaxtyping.Num[ultrasound_metrics._utils.array_api.ArrayAPIObj, *signal_dims], jaxtyping.Num[ultrasound_metrics._utils.array_api.ArrayAPIObj, *noise_dims]]

   Automatically estimate signal and noise regions in RF data.

   This function finds the maximum value in the data (after ignoring initial samples)
   and defines signal and noise regions around it based on the provided parameters.

   :param data: The RF data to analyze. Should be a 1D array.
   :type data: ArrayAPIObj
   :param signal_width: Width of the signal region. If int, defines total width centered on max.
                        If list[int], defines [samples_before_max, samples_after_max].
   :type signal_width: int or list[int], optional
   :param noise_offset: Number of samples to skip between signal and noise regions.
   :type noise_offset: int, optional
   :param ignore_until: Number of initial samples to ignore (e.g., to avoid startup artifacts).
   :type ignore_until: int, optional
   :param noise_size: Maximum number of samples for noise region. If None, uses all available.
   :type noise_size: int, optional
   :param show: If True, display a plot showing the estimated regions.
   :type show: bool, optional
   :param ax: If set, plots the signal and noise data on the given Axes object.
   :type ax: plt.Axes, optional

   :returns: (signal_data, noise_data) where each is the extracted data array.
   :rtype: tuple[ArrayAPIObj, ArrayAPIObj]

   .. rubric:: Notes

   - The signal region is centered on the maximum value in the data
   - The noise region is placed after the signal region with the specified offset
   - This is a heuristic approach and may need manual adjustment for best results