pyuncertainnumber.validation.area_metric
========================================

.. py:module:: pyuncertainnumber.validation.area_metric


Functions
---------

.. autoapisummary::

   pyuncertainnumber.validation.area_metric.am_distance_counter
   pyuncertainnumber.validation.area_metric.function_succeeds
   pyuncertainnumber.validation.area_metric.area_metric_pbox
   pyuncertainnumber.validation.area_metric.area_metric_pbox_diff
   pyuncertainnumber.validation.area_metric.area_metric_sample
   pyuncertainnumber.validation.area_metric.area_metric_np_numbers
   pyuncertainnumber.validation.area_metric.area_metric_number
   pyuncertainnumber.validation.area_metric.area_metric
   pyuncertainnumber.validation.area_metric.double_metric
   pyuncertainnumber.validation.area_metric.conformal_double_metric
   pyuncertainnumber.validation.area_metric.am_diff_register
   pyuncertainnumber.validation.area_metric.intervals_from_res
   pyuncertainnumber.validation.area_metric.plot_intervals_from_res
   pyuncertainnumber.validation.area_metric.integrate_distance


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

.. py:function:: am_distance_counter(A, B)

   Compute the distance between two sets of intervals as used in the area metric.

   .. rubric:: Notes

   It is essentially doing:

   def f(a, b, c, d):
       return np.maximum.reduce([c - b, a - d, 0])


.. py:function:: function_succeeds(f, *args, **kwargs)

.. py:function:: area_metric_pbox(a: pyuncertainnumber.Pbox, b: pyuncertainnumber.Pbox)

   when a and b are both Pboxes


.. py:function:: area_metric_pbox_diff(a: pyuncertainnumber.Pbox, b: pyuncertainnumber.Pbox)

   when a and b are both Pboxes


.. py:function:: area_metric_sample(a: numpy.typing.ArrayLike, b: numpy.typing.ArrayLike)

.. py:function:: area_metric_np_numbers(a, b)

   when a and b are both numpy arrays of scalar numbers, compute the area metric accordingly


.. py:function:: area_metric_number(a: pyuncertainnumber.Pbox | numbers.Number, b: pyuncertainnumber.Pbox | numbers.Number) -> float

   if any of a or b is a number, compute area metric accordingly


.. py:function:: area_metric(a: numbers.Number | pyuncertainnumber.Pbox | numpy.typing.ArrayLike, b: numbers.Number | pyuncertainnumber.Pbox | numpy.typing.ArrayLike) -> float

   Compute the area metric between two objects.

   .. note:: top-level function to compute area metric between any two objects


.. py:function:: double_metric(p: numbers.Number | pyuncertainnumber.Pbox | pyuncertainnumber.Interval, o: numbers.Number | pyuncertainnumber.Pbox | pyuncertainnumber.Interval)

   Double metric for two uncertain numbers.

   :param p: a prediction uncertain number (Pbox)
   :param o: an observation uncertain number (Pbox or scalar)

   .. note:: Typical case is for validation between prediction and observation where both are uncertain numbers.


.. py:function:: conformal_double_metric(p: numbers.Number | pyuncertainnumber.Pbox | pyuncertainnumber.Interval, o: numbers.Number | pyuncertainnumber.Pbox | pyuncertainnumber.Interval)

   Propsed conformal version of the double metric, which takes the maximum of the two area metrics.


.. py:function:: am_diff_register(A, B, debug=False)

   Register the distance and return a structured array with fields:

   :returns:

             - distance: float (max of c-b, a-d, 0)
             - x1: first endpoint (c or a, or 0 if 0 wins)
             - x2: second endpoint (b or d, or 0 if 0 wins)
   :rtype: In each tuple of the output array


.. py:function:: intervals_from_res(res)

   From a structured array `res` with fields: 'distance', 'x1', 'x2',
   :returns: boolean mask where distance != 0
             - intervals: (N, 2) array of sorted [lo, hi] endpoints for rows where mask is True
   :rtype: - mask


.. py:function:: plot_intervals_from_res(res, p, *, show_points=False, title=None, include_ties=False, ax=None)

   Plot horizontal intervals from `res` at heights given by `p`.

   args
       res (ArrayLike) : Structured array with fields ('distance', 'x1', 'x2').

       p (ArrayLike) : 1D array of same length as `res`, giving y-coordinate (height) of each interval.

       show_points (Boolean): If True, shows markers at interval endpoints.

       title (str): Plot title. Optional

       include_ties (bool): If True, also include intervals where distance == 0 but argmax picked c-b or a-d.

       ax (matplotlib.axes.Axes) :  Axis to plot on. If None, a new figure and axis are created. Optional

   returns
       ax (matplotlib.axes.Axes): The matplotlib axis used for plotting.


.. py:function:: integrate_distance(res, p)

   Integrate distance vs p with the trapezoidal rule,
   matching: np.trapz(y=diff, x=p)

   No masking; uses all rows. Sorts by p to avoid signed/ordering issues.