ultrasound_metrics.metrics.clip
===============================

.. py:module:: ultrasound_metrics.metrics.clip

.. autoapi-nested-parse::

   Measure signal-clipping in ultrasound pulse-echo data (RF or I/Q).

   Uses time-domain amplitude thresholding.



Attributes
----------

.. autoapisummary::

   ultrasound_metrics.metrics.clip.Scalar


Classes
-------

.. autoapisummary::

   ultrasound_metrics.metrics.clip.ClipDetectMethod


Functions
---------

.. autoapisummary::

   ultrasound_metrics.metrics.clip.clip_ratio
   ultrasound_metrics.metrics.clip.is_clipped_max_amplitude
   ultrasound_metrics.metrics.clip.is_clipped_threshold


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

.. py:class:: ClipDetectMethod

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Enum for different clipping metrics.

   Initialize self.  See help(type(self)) for accurate signature.


   .. py:attribute:: MAX_AMPLITUDE
      :value: 'max_amplitude'



   .. py:attribute:: THRESHOLD
      :value: 'threshold'



.. py:function:: clip_ratio(data: jaxtyping.Num[jaxtyping.Array,  *batch sample], method: Union[ClipDetectMethod, str] = ClipDetectMethod.THRESHOLD, **kwargs: Any) -> float

   Measure the ratio of clipped samples in the data.

   Supports multiple methods for clipping detection.

   :param data: Data array of shape (..., n_samples).
   :param method: Method to use for clipping detection.
   :param \*\*kwargs: Additional keyword arguments for the clipping detection method.

   :returns: Ratio of clipped samples in the data.
   :rtype: float


.. py:function:: is_clipped_max_amplitude(data: jaxtyping.Num[jaxtyping.Array,  *batch sample], *, range_factor: Union[Scalar, tuple[Optional[Scalar], Optional[Scalar]]] = 0.01, min_contiguous: int = 1) -> jaxtyping.Bool[jaxtyping.Array,  *batch sample]

   Detect clipped samples in the data by checking for contiguous segments outside the normal range.

   Implementation note: allows for a different threshold for each time-series in the batch.

   :param data: Data array of shape (..., n_samples).
   :param range_factor: How far inside the data's min/max range to consider as clipping.
                        Can be either:

                        - float: symmetric factor for real data (e.g., 0.01 means within ±1% of the data range).
                          For complex data, this is the factor for the magnitude range.
                        - tuple: (lower, upper) factors for asymmetric thresholds
                        - None for either value in the tuple to disable clipping detection on that side

                        Use range_factor when clipping is soft, or when there is some preprocessing
                        (such as filtering or lossy compression) that softens hard-clipping.
   :param min_contiguous: Minimum number of contiguous samples outside the range to consider
                          that the signal was clipped.
                          This is for guessing whether the signal was clipped, rather than just
                          that the actual signal amplitude has some range.

   :returns: Boolean mask with shape=data.shape indicating which samples were clipped.
   :rtype: ndarray


.. py:function:: is_clipped_threshold(data: jaxtyping.Num[jaxtyping.Array,  *batch sample], *, max_threshold: float, min_threshold: Optional[float] = None) -> jaxtyping.Bool[jaxtyping.Array,  *batch sample]

   Detect clipped samples in the data by comparing to a threshold.

   :param data: Data array of shape (..., n_samples).
   :param max_threshold: Maximum allowed amplitude.
   :param min_threshold: Minimum allowed amplitude. If None, symmetric threshold is assumed.

   :returns: Boolean mask with shape=data.shape indicating which samples were clipped.
   :rtype: ndarray


.. py:data:: Scalar