pyuncertainnumber.characterisation.stats
========================================

.. py:module:: pyuncertainnumber.characterisation.stats


Attributes
----------

.. autoapisummary::

   pyuncertainnumber.characterisation.stats.named_mom_methods
   pyuncertainnumber.characterisation.stats.named_mle_methods
   pyuncertainnumber.characterisation.stats.named_smle_methods


Functions
---------

.. autoapisummary::

   pyuncertainnumber.characterisation.stats.fit
   pyuncertainnumber.characterisation.stats.makedist
   pyuncertainnumber.characterisation.stats.MMbernoulli
   pyuncertainnumber.characterisation.stats.MMbeta
   pyuncertainnumber.characterisation.stats.mm_beta
   pyuncertainnumber.characterisation.stats.MMbetabinomial
   pyuncertainnumber.characterisation.stats.MMbinomial
   pyuncertainnumber.characterisation.stats.MMchisquared
   pyuncertainnumber.characterisation.stats.MMexponential
   pyuncertainnumber.characterisation.stats.universal_exponential
   pyuncertainnumber.characterisation.stats.mm_exponential
   pyuncertainnumber.characterisation.stats.MMF
   pyuncertainnumber.characterisation.stats.MMgamma
   pyuncertainnumber.characterisation.stats.mm_gamma
   pyuncertainnumber.characterisation.stats.MMgeometric
   pyuncertainnumber.characterisation.stats.MMgeometric
   pyuncertainnumber.characterisation.stats.MMpascal
   pyuncertainnumber.characterisation.stats.MMgumbel
   pyuncertainnumber.characterisation.stats.mm_gumbel
   pyuncertainnumber.characterisation.stats.MMextremevalue
   pyuncertainnumber.characterisation.stats.MMlognormal
   pyuncertainnumber.characterisation.stats.lognormal_mom_estimator
   pyuncertainnumber.characterisation.stats.mm_lognormal
   pyuncertainnumber.characterisation.stats.MMlaplace
   pyuncertainnumber.characterisation.stats.MMdoubleexponential
   pyuncertainnumber.characterisation.stats.MMlogistic
   pyuncertainnumber.characterisation.stats.MMloguniform
   pyuncertainnumber.characterisation.stats.MMnormal
   pyuncertainnumber.characterisation.stats.mm_normal
   pyuncertainnumber.characterisation.stats.MMgaussian
   pyuncertainnumber.characterisation.stats.MMpareto
   pyuncertainnumber.characterisation.stats.MMpoisson
   pyuncertainnumber.characterisation.stats.MMpowerfunction
   pyuncertainnumber.characterisation.stats.MMt
   pyuncertainnumber.characterisation.stats.MMstudent
   pyuncertainnumber.characterisation.stats.MMuniform
   pyuncertainnumber.characterisation.stats.MMrectangular
   pyuncertainnumber.characterisation.stats.MMtriangular
   pyuncertainnumber.characterisation.stats.MMrayleigh
   pyuncertainnumber.characterisation.stats.universal_rayleigh
   pyuncertainnumber.characterisation.stats.mm_rayleigh
   pyuncertainnumber.characterisation.stats.MLbernoulli
   pyuncertainnumber.characterisation.stats.MLbeta
   pyuncertainnumber.characterisation.stats.MLbetabinomial
   pyuncertainnumber.characterisation.stats.MLbinomial
   pyuncertainnumber.characterisation.stats.MLchisquared
   pyuncertainnumber.characterisation.stats.MLexponential
   pyuncertainnumber.characterisation.stats.MLF
   pyuncertainnumber.characterisation.stats.MLgamma
   pyuncertainnumber.characterisation.stats.MLgammaexponential
   pyuncertainnumber.characterisation.stats.MLgeometric
   pyuncertainnumber.characterisation.stats.MLgumbel
   pyuncertainnumber.characterisation.stats.MLlaplace
   pyuncertainnumber.characterisation.stats.MLlogistic
   pyuncertainnumber.characterisation.stats.MLlognormal
   pyuncertainnumber.characterisation.stats.MLloguniform
   pyuncertainnumber.characterisation.stats.MLnegativebinomial
   pyuncertainnumber.characterisation.stats.MLnormal
   pyuncertainnumber.characterisation.stats.MLpareto
   pyuncertainnumber.characterisation.stats.MLpoisson
   pyuncertainnumber.characterisation.stats.MLpowerfunction
   pyuncertainnumber.characterisation.stats.MLrayleigh
   pyuncertainnumber.characterisation.stats.MLstudent
   pyuncertainnumber.characterisation.stats.MLtriangular
   pyuncertainnumber.characterisation.stats.MLuniform
   pyuncertainnumber.characterisation.stats.sMLbernoulli
   pyuncertainnumber.characterisation.stats.sMLnormal
   pyuncertainnumber.characterisation.stats.sMLgaussian
   pyuncertainnumber.characterisation.stats.sMLexponential
   pyuncertainnumber.characterisation.stats.sMLpoisson
   pyuncertainnumber.characterisation.stats.sMLgeometric
   pyuncertainnumber.characterisation.stats.sMLgumbel
   pyuncertainnumber.characterisation.stats.sMLpascal
   pyuncertainnumber.characterisation.stats.sMLuniform
   pyuncertainnumber.characterisation.stats.sMLrectangular
   pyuncertainnumber.characterisation.stats.sMLpareto
   pyuncertainnumber.characterisation.stats.sMLlaplace
   pyuncertainnumber.characterisation.stats.sMLdoubleexponential
   pyuncertainnumber.characterisation.stats.sMLlognormal2
   pyuncertainnumber.characterisation.stats.sMLlognormal
   pyuncertainnumber.characterisation.stats.sMLloguniform
   pyuncertainnumber.characterisation.stats.sMLweibull
   pyuncertainnumber.characterisation.stats.sMLgamma
   pyuncertainnumber.characterisation.stats.MEminmax
   pyuncertainnumber.characterisation.stats.MEminmaxmean
   pyuncertainnumber.characterisation.stats.MEmeansd
   pyuncertainnumber.characterisation.stats.MEminmean
   pyuncertainnumber.characterisation.stats.MEdiscretemean
   pyuncertainnumber.characterisation.stats.MEquantiles
   pyuncertainnumber.characterisation.stats.MEdiscreteminmax
   pyuncertainnumber.characterisation.stats.MEmeanvar
   pyuncertainnumber.characterisation.stats.MEminmaxmeansd
   pyuncertainnumber.characterisation.stats.MEmmms
   pyuncertainnumber.characterisation.stats.MEminmaxmeanvar
   pyuncertainnumber.characterisation.stats.antweiler
   pyuncertainnumber.characterisation.stats.betapert
   pyuncertainnumber.characterisation.stats.mnr
   pyuncertainnumber.characterisation.stats.fermilnorm
   pyuncertainnumber.characterisation.stats.ferminorm
   pyuncertainnumber.characterisation.stats.approxksD95
   pyuncertainnumber.characterisation.stats.ks
   pyuncertainnumber.characterisation.stats.ferminormconfband
   pyuncertainnumber.characterisation.stats.fermilnormconfband
   pyuncertainnumber.characterisation.stats.parse_moments


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

.. py:function:: fit(method: str, family: str, data: numpy.ndarray) -> pyuncertainnumber.UncertainNumber

   parametric estimator to fit a distribution from data

   :param method: method of fitting, e.g., {'mle' or 'mom'} 'entropy', 'pert', 'fermi', 'bayesian'
   :type method: str
   :param family: distribution family to be fitted
   :type family: str
   :param data: data to be fitted
   :type data: np.ndarray

   :returns:

             - UncertainNumber object

   .. rubric:: Example

   >>> # precise data
   >>> pun.fit('mle', 'norm', np.random.normal(0, 1, 100))
   >>>  # imprecise data
   >>> precise_sample = sps.expon(scale=1/0.4).rvs(15)
   >>> imprecise_data = pba.I(lo = precise_sample - 1.4, hi=precise_sample + 1.4)
   >>> pun.fit('mom', family='exponential', data=imprecise_data)

   .. seealso::
       :func:`pyuncertainnumber.pba.KS_bounds` : a non-parametric charactearisation method using Kolmogorov-Smirnov bounds


.. py:function:: makedist(shape: str)

   a decorator to transform a `sps.dist` into `Distribution` objects


.. py:function:: MMbernoulli(x)

   a first attempt to Maximum likelihood estimation for Bernoulli distribution which accepts both precise and imprecise data;

   #! the example of `singleparam` pattern
   #! to change, add the 'interval_measurement' decorator
   .. note::

      the attempt is successful per se, but not accommodating to the top-level calling signature yet.
      
      - precise data returns precise distrubution
      - imprecise data need to be in Interval type to return a pbox
      - interval data can return either a precise distribution or a pbox


.. py:function:: MMbeta(x: numpy.ndarray)

.. py:function:: mm_beta(mean, std)

   from given moments, return a beta distribution


.. py:function:: MMbetabinomial(n: int, x)

.. py:function:: MMbinomial(x, n: int)

   :param - n: number of trials
   :type - n: int


.. py:function:: MMchisquared(x)

.. py:function:: MMexponential(x)

.. py:function:: universal_exponential(mean)

   single parameter pattern exponential distribution constructor

   .. note:: mean can be a precise number or an interval; Exponential is parameterised by scale, which is the inverse of the rate parameter (lambda).


.. py:function:: mm_exponential(mean)

   from given moments, return an exponential distribution

   .. note:: This constructor is parameterised by scale, which is the inverse of the rate parameter (lambda).


.. py:function:: MMF(x)

.. py:function:: MMgamma(x)

.. py:function:: mm_gamma(mean, std=None)

   from given moments, return a gamma distribution


.. py:function:: MMgeometric(x)

.. py:function:: MMgeometric(x)

.. py:function:: MMpascal(x)

.. py:function:: MMgumbel(x)

.. py:function:: mm_gumbel(mean, std)

   from given moments, return a gumbel distribution


.. py:function:: MMextremevalue(x)

.. py:function:: MMlognormal(x)

.. py:function:: lognormal_mom_estimator(data=None, sample_mean=None, sample_variance=None)

   Method of Moments estimator for Lognormal(μ, σ^2).

   :param data: Raw data sample. If provided, mean and variance are computed from it.
   :type data: array-like, optional
   :param sample_mean: Precomputed sample mean (ignored if data is provided).
   :type sample_mean: float, optional
   :param sample_variance: Precomputed sample variance (ignored if data is provided).
   :type sample_variance: float, optional

   :returns: * **mu_hat** (*float*) -- Estimated mean of the underlying normal distribution.
             * **sigma2_hat** (*float*) -- Estimated variance of the underlying normal distribution.


.. py:function:: mm_lognormal(mean: float, std: float)

   Method of Moments estimator for Lognormal(μ, σ^2).

   args
       mean (float):
           Sample mean of the data (m1).
       std (float):
           Sample standard deviation of the data (s).

   returns
       mu_hat (float):
           Estimated mean of the underlying normal distribution.
       sigma2_hat (float):
           Estimated variance of the underlying normal distribution.


.. py:function:: MMlaplace(x)

.. py:function:: MMdoubleexponential(x)

.. py:function:: MMlogistic(x)

.. py:function:: MMloguniform(x)

.. py:function:: MMnormal(x)

.. py:function:: mm_normal(mean, std)

   from given moments, return a normal distribution


.. py:function:: MMgaussian(x)

.. py:function:: MMpareto(x)

.. py:function:: MMpoisson(x)

.. py:function:: MMpowerfunction(x)

.. py:function:: MMt(x)

.. py:function:: MMstudent(x)

.. py:function:: MMuniform(x)

.. py:function:: MMrectangular(x)

.. py:function:: MMtriangular(x, iters=100, dives=10)

.. py:function:: MMrayleigh(x)

.. py:function:: universal_rayleigh(mean)

   single parameter pattern rayleigh distribution constructor

   .. note:: mean can be a precise number or an interval;


.. py:function:: mm_rayleigh(mean)

   from given moments, return a rayleigh distribution


.. py:data:: named_mom_methods

.. py:function:: MLbernoulli(x)

.. py:function:: MLbeta(x)

.. py:function:: MLbetabinomial(x)

.. py:function:: MLbinomial(x)

   # TODO to check
   #! no fitting func for scipy discrete distributions


.. py:function:: MLchisquared(x)

.. py:function:: MLexponential(x)

   a standalone caller for exponential distribution with interval data (not in use yet)


.. py:function:: MLF(x)

.. py:function:: MLgamma(x)

.. py:function:: MLgammaexponential(x)

.. py:function:: MLgeometric(x)

.. py:function:: MLgumbel(x)

.. py:function:: MLlaplace(x)

.. py:function:: MLlogistic(x)

.. py:function:: MLlognormal(x)

.. py:function:: MLloguniform(x)

.. py:function:: MLnegativebinomial(x)

.. py:function:: MLnormal(x)

.. py:function:: MLpareto(x)

.. py:function:: MLpoisson(x)

.. py:function:: MLpowerfunction(x)

.. py:function:: MLrayleigh(x)

.. py:function:: MLstudent(x)

.. py:function:: MLtriangular(x)

.. py:function:: MLuniform(x)

.. py:data:: named_mle_methods

.. py:function:: sMLbernoulli(x)

.. py:function:: sMLnormal(x)

.. py:function:: sMLgaussian(x)

.. py:function:: sMLexponential(x)

.. py:function:: sMLpoisson(x)

.. py:function:: sMLgeometric(x)

.. py:function:: sMLgumbel(x)

.. py:function:: sMLpascal(x)

.. py:function:: sMLuniform(x)

.. py:function:: sMLrectangular(x)

.. py:function:: sMLpareto(x)

.. py:function:: sMLlaplace(x)

.. py:function:: sMLdoubleexponential(x)

.. py:function:: sMLlognormal2(x)

.. py:function:: sMLlognormal(x)

.. py:function:: sMLloguniform(x)

.. py:function:: sMLweibull(x, shapeinterval=None)

.. py:function:: sMLgamma(data)

.. py:data:: named_smle_methods

.. py:function:: MEminmax(min, max)

.. py:function:: MEminmaxmean(min, max, mean)

.. py:function:: MEmeansd(mean, sd)

.. py:function:: MEminmean(min, mean)

.. py:function:: MEdiscretemean(x, mu, steps=10, iterations=50)

.. py:function:: MEquantiles(v, p)

.. py:function:: MEdiscreteminmax(min, max)

.. py:function:: MEmeanvar(mean, var)

.. py:function:: MEminmaxmeansd(min, max, mean, sd)

.. py:function:: MEmmms(min, max, mean, sd)

.. py:function:: MEminmaxmeanvar(min, max, mean, var)

.. py:function:: antweiler(x)

.. py:function:: betapert(min, max, mode)

.. py:function:: mnr(n, many=10000)

.. py:function:: fermilnorm(x1, x2, n=None, pr=0.9)

.. py:function:: ferminorm(x1, x2, n=None, pr=0.9)

.. py:function:: approxksD95(n)

.. py:function:: ks(x, conf=0.95, min=None, max=None)

.. py:function:: ferminormconfband(x1, x2, n, pr=0.9, conf=0.95, bOt=0.001, tOp=0.999)

.. py:function:: fermilnormconfband(x1, x2, n, pr=0.9, conf=0.95, bOt=0.001, tOp=0.999)

.. py:function:: parse_moments(family: str, mean: numbers.Number | pyuncertainnumber.pba.intervals.Interval, std: numbers.Number = None, var: numbers.Number = None, **kwargs)

   parse the moments input to a standard form for dist construction

   :param family: distribution family
   :type family: str
   :param mean: mean value, which could be either precise value or an Interval object. Python list is not supported.
   :type mean: Number | Interval
   :param std: standard deviation
   :type std: Number
   :param var: variance
   :type var: Number

   .. rubric:: Example

   >>> parse_moments(family='normal', mean=3., std=1.)

   .. note::

      Only accept up to 2nd moment for now. Interval mean is supported due to single parameter construction.
      Combined mean and std intervals are not supported as they are deemed NP hard question.