diff --git a/doc/source/univariate.rst b/doc/source/univariate.rst index 5468fc55c..47b269d40 100644 --- a/doc/source/univariate.rst +++ b/doc/source/univariate.rst @@ -23,7 +23,7 @@ Parameter Retrieval .. function:: params(d) - Return a tuple of parameters. + Return a tuple of parameters. **Note:** Let ``d`` be a distribution of type ``D``, then ``D(params(d)...)`` will construct exactly the same distribution as ``d``. @@ -33,7 +33,7 @@ Parameter Retrieval .. function:: failprob(d) - Get the probability of failure. + Get the probability of failure. .. function:: scale(d) @@ -41,30 +41,30 @@ Parameter Retrieval .. function:: location(d) - Get the location parameter. + Get the location parameter. .. function:: shape(d) - Get the shape parameter. + Get the shape parameter. .. function:: rate(d) - Get the rate parameter. + Get the rate parameter. .. function:: ncategories(d) - Get the number of categories. + Get the number of categories. .. function:: ntrials(d) - Get the number of trials. + Get the number of trials. .. function:: dof(d) Get the degrees of freedom. -**Note:** ``params`` are defined for all univariate distributions, while other parameter retrieval methods are only defined for those distributions for which these parameters make sense. See below for details. +**Note:** ``params`` are defined for all univariate distributions, while other parameter retrieval methods are only defined for those distributions for which these parameters make sense. See below for details. Computation of statistics @@ -88,9 +88,9 @@ Let ``d`` be a distribution: Return the median value of distribution ``d``. -.. function:: modes(d) +.. function:: modes(d) - Return an array of all modes of ``d``. + Return an array of all modes of ``d``. .. function:: mode(d) @@ -122,7 +122,7 @@ Let ``d`` be a distribution: .. function:: entropy(d, base) - Return the entropy value of distribution ``d``, w.r.t. a given base. + Return the entropy value of distribution ``d``, w.r.t. a given base. .. function:: mgf(d, t) @@ -130,15 +130,15 @@ Let ``d`` be a distribution: .. function:: cf(d, t) - Evaluate the characteristic function of distribution ``d``. + Evaluate the characteristic function of distribution ``d``. Probability Evaluation ~~~~~~~~~~~~~~~~~~~~~~~ .. function:: insupport(d, x) - When ``x`` is a scalar, it returns whether x is within the support of ``d``. - When ``x`` is an array, it returns whether every element in x is within the support of ``d``. + When ``x`` is a scalar, it returns whether x is within the support of ``d``. + When ``x`` is an array, it returns whether every element in x is within the support of ``d``. .. function:: pdf(d, x) @@ -159,7 +159,7 @@ Probability Evaluation .. function:: logpdf(d, x) - The logarithm of the pdf value(s) evaluated at x, i.e. ``log(pdf(x))``. + The logarithm of the pdf value(s) evaluated at x, i.e. ``log(pdf(x))``. **Note:** The internal implementation may directly evaluate logpdf instead of first computing pdf and then taking the logarithm, for better numerical stability or efficiency. @@ -171,7 +171,7 @@ Probability Evaluation The cumulative distribution function evaluated at ``x``. -.. function:: logcdf(d, x) +.. function:: logcdf(d, x) The logarithm of the cumulative function value(s) evaluated at ``x``, i.e. ``log(cdf(x))``. @@ -193,11 +193,11 @@ Probability Evaluation .. function:: invlogcdf(d, lp) - The inverse function of logcdf. + The inverse function of logcdf. .. function:: invlogccdf(d, lp) - The inverse function of logccdf. + The inverse function of logccdf. Vectorized evaluation @@ -216,7 +216,7 @@ Vectorized computation and inplace vectorized computation are supported for the * ``invlogcdf`` * ``invlogccdf`` -For example, when ``x`` is an array, then ``r = pdf(d, x)`` returns an array ``r`` of the same size, such that ``r[i] = pdf(d, x[i])``. One can also use ``pdf!`` to write results to pre-allocated storage, as ``pdf!(r, d, x)``. +For example, when ``x`` is an array, then ``r = pdf(d, x)`` returns an array ``r`` of the same size, such that ``r[i] = pdf(d, x[i])``. One can also use ``pdf!`` to write results to pre-allocated storage, as ``pdf!(r, d, x)``. Sampling (Random number generation) @@ -232,7 +232,13 @@ Sampling (Random number generation) .. function:: rand(d, dims) - Return an array of size dims that is filled with independent samples from the distribution ``d``. + Return an array of size ``dims`` that is filled with independent samples from the distribution ``d``. + +.. function:: rand(d, dim0, dim1, ...) + + Similar to ``rand(d, dims)`` above, except that the dimensions can be input as individual integers. + + For example, one can write ``rand(d, 2, 3)`` or ``rand(d, (2, 3))``, which are equivalent. .. function:: rand!(d, arr) @@ -295,17 +301,17 @@ All discrete univariate distribution types are subtypes of *DiscreteUnivariateDi .. _bernoulli: -Bernoulli Distribution +Bernoulli Distribution ~~~~~~~~~~~~~~~~~~~~~~~ -A `Bernoulli distribution `_ is parameterized by a success rate :math:`p`, which takes value 1 with probability :math:`p` and 0 with probability :math:`1-p`. +A `Bernoulli distribution `_ is parameterized by a success rate :math:`p`, which takes value 1 with probability :math:`p` and 0 with probability :math:`1-p`. -.. math:: +.. math:: P(X = k) = \begin{cases} p & \quad \text{for } k = 0, \\ 1 - p & \quad \text{for } k = 1. - \end{cases} + \end{cases} .. code-block:: julia @@ -322,7 +328,7 @@ A `Bernoulli distribution ` Binomial Distribution ~~~~~~~~~~~~~~~~~~~~~~ -A `Binomial distribution `_ characterizes the number of successes in a sequence of independent trials. It has two parameters: :math:`n`, the number of trials, and :math:`p`, the success rate. +A `Binomial distribution `_ characterizes the number of successes in a sequence of independent trials. It has two parameters: :math:`n`, the number of trials, and :math:`p`, the success rate. .. math:: @@ -345,7 +351,7 @@ A `Binomial distribution `_ Categorical Distribution ~~~~~~~~~~~~~~~~~~~~~~~~~ -A `Categorical distribution `_ is parameterized by a probability vector :math:`p` (of length ``K``). +A `Categorical distribution `_ is parameterized by a probability vector :math:`p` (of length ``K``). .. math:: @@ -359,9 +365,9 @@ A `Categorical distribution `_ is a uniform distribution over a consecutive sequence of integers between :math:`a` and :math:`b`. +A `Discrete uniform distribution `_ is a uniform distribution over a consecutive sequence of integers between :math:`a` and :math:`b`. .. math:: @@ -391,7 +397,7 @@ A `Discrete uniform distribution `_ characterizes the number of failures before the first success in a sequence of independent Bernoulli trials with success rate :math:`p`. +A `Geometric distribution `_ characterizes the number of failures before the first success in a sequence of independent Bernoulli trials with success rate :math:`p`. .. math:: @@ -412,7 +418,7 @@ A `Geometric distribution ` Hypergeometric Distribution ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A `Hypergeometric distribution `_ describes the number of successes in :math:`n` draws without replacement from a finite population containing :math:`s` successes and :math:`f` failures. +A `Hypergeometric distribution `_ describes the number of successes in :math:`n` draws without replacement from a finite population containing :math:`s` successes and :math:`f` failures. .. math:: @@ -420,7 +426,7 @@ A `Hypergeometric distribution `_ de P(X = k) = e^{-(\mu_1 + \mu_2)} \left( \frac{\mu_1}{\mu_2} \right)^{k/2} I_k(2 \sqrt{\mu_1 \mu_2}) \quad \text{for integer $k$.} -Here, :math:`I_k` is the modified Bessel function of the first kind. +Here, :math:`I_k` is the modified Bessel function of the first kind. .. code-block:: julia @@ -530,7 +536,7 @@ The probability density function of an `Arcsine distribution 0 .. code-block:: julia - + BetaPrime() # equivalent to BetaPrime(0.0, 1.0) BetaPrime(a) # equivalent to BetaPrime(a, a) BetaPrime(a, b) # Beta prime distribution with shape parameters a and b params(d) # Get the parameters, i.e. (a, b) -**Note:** If :math:`X \sim Beta(\alpha, \beta)`, then :math:`\frac{X}{1 - X} \sim BetaPrime(\alpha, \beta)`. +**Note:** If :math:`X \sim Beta(\alpha, \beta)`, then :math:`\frac{X}{1 - X} \sim BetaPrime(\alpha, \beta)`. .. _cauchy: @@ -664,7 +670,7 @@ The probability density function of an `Erlang distribution `_ with shape :math:`\alpha` and scale :math:`\beta` is +The probability density function of a `Fréchet distribution `_ with shape :math:`\alpha` and scale :math:`\beta` is .. math:: @@ -729,7 +735,7 @@ The probability density function of a `Fréchet distribution 0 .. code-block:: julia @@ -752,7 +758,7 @@ The probability density function of a `Gamma distribution 0 .. code-block:: julia - + InverseGaussian() # Inverse Gaussian distribution with unit mean and unit shape, i.e. InverseGaussian(1.0, 1.0) InverseGaussian(mu), # Inverse Gaussian distribution with mean mu and unit shape, i.e. InverseGaussian(u, 1.0) InverseGaussian(mu, lambda) # Inverse Gaussian distribution with mean mu and shape lambda @@ -830,7 +836,7 @@ The probability density function of an `inverse Gaussian distribution `_ with location :math:`\mu` and scale :math:`\beta` is +The probability density function of a `Laplace distribution `_ with location :math:`\mu` and scale :math:`\beta` is .. math:: @@ -852,7 +858,7 @@ The probability density function of a `Laplace distribution `_ with location :math:`\mu` and scale :math:`c` is +The probability density function os a `Lévy distribution `_ with location :math:`\mu` and scale :math:`c` is .. math:: @@ -866,7 +872,7 @@ The probability density function os a `Lévy distribution `_ with location :math:`\mu` and scale :math:`\beta` is -.. math:: +.. math:: - f(x; \mu, \beta) = \frac{1}{4 \beta} \mathrm{sech}^2 + f(x; \mu, \beta) = \frac{1}{4 \beta} \mathrm{sech}^2 \left( \frac{x - \mu}{\beta} \right) .. code-block:: julia @@ -897,18 +903,18 @@ The probability density function of a `Logistic distribution `_. The probability density function is +Let :math:`Z` be a random variable of standard normal distribution, then the distribution of :math:`\exp(\mu + \sigma Z)` is a `Lognormal distribution `_. The probability density function is .. math:: - f(x; \mu, \sigma) = \frac{1}{x \sqrt{2 \pi \sigma^2}} + f(x; \mu, \sigma) = \frac{1}{x \sqrt{2 \pi \sigma^2}} \exp \left( - \frac{(\log(x) - \mu)^2}{2 \sigma^2} \right) .. code-block:: julia LogNormal() # Log-normal distribution with zero log-mean and unit scale LogNormal(mu) # Log-normal distribution with log-mean mu and unit scale - LogNormal(mu, sig) # Log-normal distribution with log-mean mu and scale sig + LogNormal(mu, sig) # Log-normal distribution with log-mean mu and scale sig params(d) # Get the parameters, i.e. (mu, sig) meanlogx(d) # Get the mean of log(X), i.e. mu @@ -958,7 +964,7 @@ The probability density function of a `Pareto distribution `_ with scale :math:`\sigma` is +The probability density function of a `Rayleigh distribution `_ with scale :math:`\sigma` is .. math:: @@ -989,7 +995,7 @@ The probability density function of a `Rayleigh distribution `_ with lower limit a, upper limit b and mode c is .. math:: - + f(x; a, b, c)= \begin{cases} 0 & \mathrm{for\ } x < a, \\ \frac{2(x-a)}{(b-a)(c-a)} & \mathrm{for\ } a \le x \leq c, \\[4pt] @@ -1099,7 +1105,7 @@ The probability density function of a `von Mises distribution `_ with shape :math:`\alpha` and scale :math:`\beta` is +The probability density function of a `Weibull distribution `_ with shape :math:`\alpha` and scale :math:`\beta` is .. math:: @@ -1115,6 +1121,3 @@ The probability density function of a `Weibull distribution