pyuncertainnumber.pba.aggregation
=================================

.. py:module:: pyuncertainnumber.pba.aggregation


Functions
---------

.. autoapisummary::

   pyuncertainnumber.pba.aggregation.envelope
   pyuncertainnumber.pba.aggregation.imposition
   pyuncertainnumber.pba.aggregation.stochastic_mixture
   pyuncertainnumber.pba.aggregation.stacking
   pyuncertainnumber.pba.aggregation.mixture_pbox
   pyuncertainnumber.pba.aggregation.mixture_ds
   pyuncertainnumber.pba.aggregation.env_samples
   pyuncertainnumber.pba.aggregation.env_ecdf_sep
   pyuncertainnumber.pba.aggregation.env_am
   pyuncertainnumber.pba.aggregation.env_pbox_am


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

.. py:function:: envelope(*l_uns: pyuncertainnumber.pba.pbox_abc.Pbox | pyuncertainnumber.pba.dss.DempsterShafer | numbers.Number | pyuncertainnumber.pba.intervals.Interval | pyuncertainnumber.pba.distributions.Distribution | pyuncertainnumber.characterisation.uncertainNumber.UncertainNumber, output_type='pbox') -> pyuncertainnumber.pba.pbox_abc.Staircase | pyuncertainnumber.characterisation.uncertainNumber.UncertainNumber

   calculates the envelope of constructs only

   :param l_uns: the components, constructs and uncertain numbers, on which the envelope operation applied on.
   :type l_uns: list
   :param output_type: {'pbox' or 'uncertain_number' or 'un'}
                       - default is pbox
   :type output_type: str

   :returns: the envelope of the given arguments,  either a p-box or an interval.

   .. rubric:: Example

   >>> from pyuncertainnumber import envelope
   >>> a = pba.normal(3, 1)
   >>> b = pba.uniform(5, 8)
   >>> c = pba.normal(13, 2)
   >>> t = envelope(a, b, c, output_type='pbox') # or output_type='uncertain_number'


.. py:function:: imposition(*l_uns: pyuncertainnumber.pba.pbox_abc.Pbox | pyuncertainnumber.pba.dss.DempsterShafer | numbers.Number | pyuncertainnumber.pba.intervals.Interval | pyuncertainnumber.pba.distributions.Distribution | pyuncertainnumber.characterisation.uncertainNumber.UncertainNumber, output_type='pbox') -> pyuncertainnumber.pba.pbox_abc.Staircase | pyuncertainnumber.characterisation.uncertainNumber.UncertainNumber

   Returns the imposition/intersection of the list of p-boxes

   :param l_uns: a list of constructs or UN objects to be mixed
   :type l_uns: list
   :param output_type: {'pbox' or 'uncertain_number' or 'un'}
                       - default is pbox
   :type output_type: str

   :returns:

             - Pbox or UncertainNumber

   .. rubric:: Example

   >>> import pyuncertainnumber as pun
   >>> from pyuncertainnumber import pba
   >>> a = pba.normal([3, 7], 1)
   >>> b = pba.uniform([3,5], [6,9])
   >>> i = pun.imposition(a, b)


.. py:function:: stochastic_mixture(*l_uns: pyuncertainnumber.pba.pbox_abc.Pbox | pyuncertainnumber.pba.dss.DempsterShafer | numbers.Number | pyuncertainnumber.pba.intervals.Interval | pyuncertainnumber.pba.distributions.Distribution | pyuncertainnumber.characterisation.uncertainNumber.UncertainNumber, weights=None)

   it could work for either Pbox, distribution, DS structure or Intervals

   :param - l_uns: list of constructs or uncertain numbers
   :type - l_uns: list
   :param - weights: list of weights
   :type - weights: list

   .. rubric:: Example

   >>> import pyuncertainnumber as pun
   >>> p = pun.stochastic_mixture([[1,3], [2,4]])


.. py:function:: stacking(vec_interval: pyuncertainnumber.pba.intervals.Interval | list[pyuncertainnumber.pba.intervals.Interval], *, weights=None, display=False, ax=None, return_type='pbox', **kwargs) -> pyuncertainnumber.pba.pbox_abc.Pbox

   stochastic mixture operation of Intervals with probability masses

   :param - vec_interval: list of Intervals or a vectorised Interval
   :type - vec_interval: list
   :param - weights: list of weights
   :type - weights: list
   :param - display: boolean for plotting
   :type - display: Boolean
   :param - return_type: {'pbox' or 'ds' or 'bounds'}
   :type - return_type: str

   :returns: by default a p-box but can return the left and right bound F in `eCDF_bundlebounds`.

   .. note::

      - For intervals specifically.
      - it takes a list of intervals or a single vectorised interval, which is
      a different signature compared to the other aggregation functions.
      - together the interval and masses, it can be deemed that all the inputs
      required is jointly a DS structure

   .. rubric:: Example

   >>> stacking([[1,3], [2,4]], weights=[0.5, 0.5], display=True)


.. py:function:: mixture_pbox(*l_pboxes, weights=None, display=False) -> pyuncertainnumber.pba.pbox_abc.Pbox

.. py:function:: mixture_ds(*l_ds, display=False) -> pyuncertainnumber.pba.dss.DempsterShafer

   mixture operation for DS structure


.. py:function:: env_samples(data: numpy.typing.ArrayLike, output_type='pbox', ecdf_choice='canonical')

   nonparametric envelope function directly from data samples

   :param data: Each row represents a distribution, on which the envelope operation applied.
   :type data: ArrayLike
   :param output_type: {'pbox' or 'cdf'}
                       default is pbox
                       cdf is the CDF bundle
   :type output_type: str
   :param ecdf_choice: {'canonical' or 'staircase'}
   :type ecdf_choice: str

   .. note:: envelope on a set of empirical CDFs


.. py:function:: env_ecdf_sep(*ecdfs, output_type='pbox', ecdf_choice='canonical')

   nonparametric envelope function for separate empirical CDFs


.. py:function:: env_am(n_pars: numpy.typing.ArrayLike) -> numpy.ndarray

   bespoke function used for am metric case

   :param n_pars: (n_sam, 2) of tuple (mu, sigma) which may be a tensor
   :type n_pars: ArrayLike


.. py:function:: env_pbox_am(n_mean: numpy.typing.ArrayLike, n_std: numpy.typing.ArrayLike) -> numpy.ndarray

   bespoke function used for am metric case

   :param n_mean: (n_sam,) of mean values which may be a tensor
   :type n_mean: ArrayLike
   :param n_std: (n_sam,) of standard deviation values which may be a tensor
   :type n_std: ArrayLike