ultrasound_metrics.metrics.gcnr
===============================

.. py:module:: ultrasound_metrics.metrics.gcnr

.. autoapi-nested-parse::

   Generalized Contrast-to-Noise Ratio (gCNR) metric.

   .. rubric:: References

   .. [1] A. Rodriguez-Molares, O. M. Hoel Rindal, J. D'hooge, S. -E. Måsøy, A. Austeng
          and H. Torp, "The Generalized Contrast-to-Noise Ratio," 2018 IEEE International
          Ultrasonics Symposium (IUS), Kobe, Japan, 2018, pp. 1-4,
          doi: 10.1109/ULTSYM.2018.8580101.



Functions
---------

.. autoapisummary::

   ultrasound_metrics.metrics.gcnr.gcnr
   ultrasound_metrics.metrics.gcnr.main


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

.. py:function:: gcnr(values_inside: jaxtyping.Num[ultrasound_metrics._utils.array_api.ArrayAPIObj, *inside_dims], values_outside: jaxtyping.Num[ultrasound_metrics._utils.array_api.ArrayAPIObj, *outside_dims], bins: Union[int, jaxtyping.Num[ultrasound_metrics._utils.array_api.ArrayAPIObj,  n_bins]] = 100, ax: Optional[matplotlib.pyplot.Axes] = None) -> float

   Calculate the generalized Contrast-to-Noise Ratio (gCNR) between two regions.

   The gCNR is a robust metric for quantifying lesion detectability in medical imaging,
   particularly in ultrasound. It is defined as 1 - OVL, where OVL is the overlap area
   between the probability density functions of the pixel values inside and outside a lesion.

   Unlike traditional CNR, gCNR:

   1. Is robust against dynamic range alterations
   2. Can be applied to all kinds of images, units, or scales
   3. Has a simple statistical interpretation: the success rate expected from an ideal
      observer at the task of separating pixels

   See [1]_ for the original reference.

   :param values_inside: Pixel values from inside the lesion (I), i.e. the region of interest.
                         For hypoechoic lesions like cysts, these are typically lower intensity values.
   :param values_outside: Pixel values from outside the lesion (O), i.e. the background region.
   :param bins: Number of bins for histogram calculation, or a sequence of bin edges.
   :param ax: If set, plots the PDFs and their overlap on the given Axes object.

   :returns: Generalized contrast-to-noise ratio (1 - OVL).
   :rtype: float

   .. rubric:: Notes

   - gCNR = 0: Complete overlap of distributions (impossible to distinguish regions)
   - gCNR = 1: No overlap (perfect distinction between regions)
   - Pmax represents the theoretical maximum success rate for an ideal observer
     trying to classify individual pixels as belonging to either region


.. py:function:: main() -> None

   Example usage with synthetic data.