leaspy.utils.distributions
==========================

.. py:module:: leaspy.utils.distributions

.. autoapi-nested-parse::

   Module defining useful distribution for ordinal noise model.

   ..
       !! processed by numpydoc !!


Classes
-------

.. autoapisummary::

   leaspy.utils.distributions.MultinomialDistribution
   leaspy.utils.distributions.MultinomialCdfDistribution


Functions
---------

.. autoapisummary::

   leaspy.utils.distributions.discrete_sf_from_pdf
   leaspy.utils.distributions.compute_ordinal_pdf_from_ordinal_sf


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

.. py:function:: discrete_sf_from_pdf(pdf)

   
   Compute the discrete survival function values from a discrete probability density.

   For a discrete variable with levels ``l=0..L`` the survival function is
   :math:`P(X>l)=P(X\ge l+1)` for ``l=0..L-1``. This function assumes the last
   dimension of ``pdf`` indexes the discrete levels.

   :Parameters:

       **pdf** : :class:`torch.Tensor` or :class:`np.ndarray`
           The discrete probability density.



   :Returns:

       np.ndarray
           The discrete survival function values.











   ..
       !! processed by numpydoc !!

.. py:function:: compute_ordinal_pdf_from_ordinal_sf(ordinal_sf, dim_ordinal_levels = 3)

   
   Compute the probability density of an ordinal model from its survival function.

   Given the survival function probabilities :math:`P(X>l)=P(X\ge l+1)` for
   ``l=0..L-1``, compute :math:`P(X=l)` for ``l=0..L``.

   :Parameters:

       **ordinal_sf** : :class:`torch.FloatTensor`
           Survival function values : ordinal_sf[..., l] is the proba to be superior or equal to l+1
           Dimensions are:
           
           * 0=individual
           * 1=visit
           * 2=feature
           * 3=ordinal_level [l=0..L-1]
           * [4=individual_parameter_dim_when_gradient]

       **dim_ordinal_levels** : int, default = 3
           The dimension of the tensor where the ordinal levels are.



   :Returns:

       torch.FloatTensor
           Probability density where ordinal_pdf[..., l] is the proba to be equal to l (l=0..L).
           Same shape as input, except for dimension 3 which has one more element.











   ..
       !! processed by numpydoc !!

.. py:class:: MultinomialDistribution(probs, **kwargs)

   Bases: :py:obj:`torch.distributions.Multinomial`


   
   Class for a multinomial distribution with only one sample based on the Multinomial torch distrib.


   :Parameters:

       **probs** : :class:`torch.Tensor`
           The pdf of the multinomial distribution.














   ..
       !! processed by numpydoc !!

   .. py:attribute:: arg_constraints
      :type:  ClassVar

      
      Returns a dictionary from argument names to
      :class:`~torch.distributions.constraints.Constraint` objects that
      should be satisfied by each argument of this distribution. Args that
      are not tensors need not appear in this dict.
















      ..
          !! processed by numpydoc !!


   .. py:method:: from_sf(sf, **kws)
      :classmethod:


      
      Generate a new MultinomialDistribution from its survival
      function instead of its probability density function.


      :Parameters:

          **pdf** : :class:`torch.Tensor`
              The input probability density function.

          **\*\*kws**
              Additional keyword arguments to be passed for instance initialization.














      ..
          !! processed by numpydoc !!


.. py:class:: MultinomialCdfDistribution(sf, *, validate_args = True)

   Bases: :py:obj:`torch.distributions.Distribution`


   
   Class for a multinomial distribution with only sample method.


   :Parameters:

       **sf** : :class:`torch.Tensor`
           Values of the survival function [P(X > l) for l=0..L-1 where L is max_level]
           from which the distribution samples.
           Ordinal levels are assumed to be in the last dimension.
           Those values must be in [0, 1], and decreasing when ordinal level increases (not checked).

       **validate_args** : bool, optional (default True)
           Whether to validate the arguments or not (None for default behavior, which changed after torch >= 1.8 to True).

   :Attributes:

       **cdf** : :class:`torch.Tensor`
           The cumulative distribution function [P(X <= l) for l=0..L] from which the distribution samples.
           The shape of latest dimension is L+1 where L is max_level.
           We always have P(X <= L) = 1

       **arg_constraints** : :obj:`dict`
           Contains the constraints on the arguments.













   ..
       !! processed by numpydoc !!

   .. py:attribute:: arg_constraints
      :type:  ClassVar

      
      Returns a dictionary from argument names to
      :class:`~torch.distributions.constraints.Constraint` objects that
      should be satisfied by each argument of this distribution. Args that
      are not tensors need not appear in this dict.
















      ..
          !! processed by numpydoc !!


   .. py:attribute:: cdf

      
      Returns the cumulative density/mass function evaluated at
      `value`.

      Args:
          value (Tensor):















      ..
          !! processed by numpydoc !!


   .. py:method:: from_pdf(pdf, **kws)
      :classmethod:


      
      Generate a new MultinomialDistribution from its probability density
      function instead of its survival function.


      :Parameters:

          **pdf** : :class:`torch.Tensor`
              The input probability density function.

          **\*\*kws**
              Additional keyword arguments to be passed for instance initialization.














      ..
          !! processed by numpydoc !!


   .. py:method:: sample()

      
      Multinomial sampling.

      We sample uniformly on [0, 1( but for the latest dimension corresponding
      to ordinal levels this latest dimension will be broadcast when comparing
      with `cdf`.




      :Returns:

          torch.Tensor
              Vector of integer values corresponding to the multinomial sampling.
              Result is in [[0, L]].











      ..
          !! processed by numpydoc !!