:py:mod:`kwarray.distributions`
===============================

.. py:module:: kwarray.distributions

.. autoapi-nested-parse::

   Defines data structures for efficient repeated sampling of specific
   distributions (e.g. Normal, Uniform, Binomial) with specific parameters.

   Inspired by ~/code/imgaug/imgaug/parameters.py

   Similar Libraries:
       * https://docs.pymc.io/api/distributions.html
       * https://github.com/phobson/paramnormal

   .. todo::

      - [ ] change sample shape to just a single num.
      - [ ] Some Distributions will output vectors. Maybe we could just postpend the dimensions?
      - [ ] Expose as kwstats?



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

Classes
~~~~~~~

.. autoapisummary::

   kwarray.distributions.Uniform
   kwarray.distributions.Exponential
   kwarray.distributions.Constant
   kwarray.distributions.DiscreteUniform
   kwarray.distributions.Normal
   kwarray.distributions.Bernoulli
   kwarray.distributions.Binomial
   kwarray.distributions.Categorical
   kwarray.distributions.TruncNormal




.. py:class:: Uniform(low=0, high=1, rng=None)

   Bases: :py:obj:`Distribution`

   Defaults to a uniform distribution over floats between 0 and 1

   .. rubric:: Example

   >>> self = Uniform(rng=0)
   >>> self.sample()
   0.548813...
   >>> float(self.sample(1))
   0.7151...

   Benchmark:
       >>> import ubelt as ub
       >>> self = Uniform()
       >>> for timer in ub.Timerit(100, bestof=10):
       >>>     with timer:
       >>>         [self() for _ in range(100)]
       >>> for timer in ub.Timerit(100, bestof=10):
       >>>     with timer:
       >>>         self(100)

   .. py:method:: sample(self, *shape)


   .. py:method:: coerce(cls, arg)
      :classmethod:



.. py:class:: Exponential(scale=1, rng=None)

   Bases: :py:obj:`Distribution`

   .. rubric:: Example

   >>> self = Exponential(rng=0)
   >>> # xdoctest: +REQUIRES(--show)
   >>> import kwplot
   >>> kwplot.autompl()
   >>> kwplot.figure(fnum=1, doclf=True)
   >>> self._show(500, bins=25)

   .. py:method:: sample(self, *shape)



.. py:class:: Constant(value=0, rng=None)

   Bases: :py:obj:`Distribution`

   .. rubric:: Example

   >>> self = Constant(42, rng=0)
   >>> self.sample()
   42
   >>> self.sample(3)
   array([42, 42, 42])

   .. py:method:: sample(self, *shape)



.. py:class:: DiscreteUniform(min=0, max=1, rng=None)

   Bases: :py:obj:`Distribution`

   Uniform distribution over integers.

   :Parameters: * **min** (*int*) -- inclusive minimum
                * **max** (*int*) -- exclusive maximum

   .. rubric:: Example

   >>> self = DiscreteUniform.coerce(4)
   >>> self.sample(100)

   .. py:method:: sample(self, *shape)


   .. py:method:: coerce(cls, arg, rng=None)
      :classmethod:



.. py:class:: Normal(mean=0, std=1, rng=None)

   Bases: :py:obj:`Distribution`

   >>> self = Normal(mean=100, rng=0)
   >>> self.sample()
   >>> self.sample(100)

   .. py:method:: sample(self, *shape)



.. py:class:: Bernoulli(p=0.5, rng=None)

   Bases: :py:obj:`Distribution`

   self = Normal()
   self.sample()
   self.sample(1)

   .. py:method:: sample(self, *shape)


   .. py:method:: coerce(cls, arg)
      :classmethod:



.. py:class:: Binomial(n=1, p=0.5, rng=None)

   Bases: :py:obj:`Distribution`

   self = Normal()
   self.sample()
   self.sample(1)

   .. py:method:: sample(self, *shape)



.. py:class:: Categorical(categories, weights=None, rng=None)

   Bases: :py:obj:`Distribution`

   .. rubric:: Example

   >>> categories = [3, 5, 1]
   >>> weights = [.05, .5, .45]
   >>> self = Categorical(categories, weights, rng=0)
   >>> self.sample()
   5
   >>> list(self.sample(2))
   [1, 1]
   >>> self.sample(2, 3)
   array([[5, 5, 1],
          [5, 1, 1]])

   .. py:method:: sample(self, *shape)



.. py:class:: TruncNormal(mean=0, std=1, low=-np.inf, high=np.inf, rng=None)

   Bases: :py:obj:`Distribution`

   A truncated normal distribution.

   A normal distribution, but bounded by low and high values. Note this is
   much different from just using a clipped normal.

   :Parameters: * **mean** (*float*) -- mean of the distribution
                * **std** (*float*) -- standard deviation of the distribution
                * **low** (*float*) -- lower bound
                * **high** (*float*) -- upper bound
                * **rng** (*np.random.RandomState*)

   .. rubric:: Example

   >>> self = TruncNormal(rng=0)
   >>> self()  # output of this changes before/after scipy version 1.5
   ...0.1226...

   .. rubric:: Example

   >>> low = -np.pi / 16
   >>> high = np.pi / 16
   >>> std = np.pi / 8
   >>> self = TruncNormal(low=low, high=high, std=std, rng=0)
   >>> shape = (3, 3)
   >>> data = self(*shape)
   >>> print(ub.repr2(data, precision=5))
   np.array([[ 0.01841,  0.0817 ,  0.0388 ],
             [ 0.01692, -0.0288 ,  0.05517],
             [-0.02354,  0.15134,  0.18098]], dtype=np.float64)

   .. py:method:: _update_internals(self)


   .. py:method:: sample(self, *shape)