diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 000000000..8f5a6463c --- /dev/null +++ b/doc/README.md @@ -0,0 +1 @@ +`genrst.jl` generates the rst files from Julia docstrings. This should be run *before* committing the changes to the repository. \ No newline at end of file diff --git a/doc/genrst.jl b/doc/genrst.jl new file mode 100644 index 000000000..806369a33 --- /dev/null +++ b/doc/genrst.jl @@ -0,0 +1,55 @@ +using Distributions + +if VERSION < v"0.5.0-" + function Markdown.rstinline(io::IO, md::Markdown.Link) + if ismatch(r":(func|obj|ref|exc|class|const|data):`\.*", md.url) + Markdown.rstinline(io, md.url) + else + Markdown.rstinline(io, "`", md.text, " <", md.url, ">`_") + end + end +end + +function printrst(io,md) + mdd = md.content[1] + sigs = shift!(mdd.content) + + decl = ".. function:: "*replace(sigs.code, "\n","\n ") + body = Markdown.rst(mdd) + println(io, decl) + println(io) + for l in split(body, "\n") + ismatch(r"^\s*$", l) ? println(io) : println(io, " ", l) + end +end + +cd(joinpath(dirname(@__FILE__),"source")) do + for (name,T) in [("Univariate Discrete",DiscreteUnivariateDistribution), + ("Univariate Continuous",ContinuousUnivariateDistribution), + ] + + fname = replace(lowercase(name),' ','-') + open("$fname.rst","w") do f + println(f,".. _$fname:") + println(f) + println(f,"$name Distributions") + println(f,"----------------------------------------------------") + println(f) + println(f, ".. DO NOT EDIT: this file is generated from Julia source.") + println(f) + + for D in subtypes(T) + if isleaftype(D) + md = Base.doc(D) + if isa(md,Markdown.MD) + isa(md.content[1].content[1],Markdown.Code) || error("Incorrect docstring format: $D") + + printrst(f,md) + else + warn("$D is not documented.") + end + end + end + end + end +end diff --git a/doc/source/conf.py b/doc/source/conf.py index 102933897..32f7c8a1b 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -25,7 +25,9 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath'] +extensions = ['sphinx.ext.mathjax', + 'sphinx.ext.todo', + 'sphinx.ext.coverage'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -34,7 +36,7 @@ source_suffix = '.rst' # The encoding of source files. -#source_encoding = 'utf-8-sig' +source_encoding = 'utf-8-sig' # The master toctree document. master_doc = 'index' diff --git a/doc/source/univariate-continuous.rst b/doc/source/univariate-continuous.rst new file mode 100644 index 000000000..80bb85245 --- /dev/null +++ b/doc/source/univariate-continuous.rst @@ -0,0 +1,683 @@ +.. _univariate-continuous: + +Univariate Continuous Distributions +---------------------------------------------------- + +.. DO NOT EDIT: this file is generated from Julia source. + +.. function:: Arcsine(a,b) + + The *Arcsine distribution* has probability density function + + .. math:: + + f(x) = \frac{1}{\pi \sqrt{(x - a) (b - x)}}, \quad x \in [a, b] + + .. code-block:: julia + + Arcsine() # Arcsine distribution with support [0, 1] + Arcsine(b) # Arcsine distribution with support [0, b] + Arcsine(a, b) # Arcsine distribution with support [a, b] + + params(d) # Get the parameters, i.e. (a, b) + minimum(d) # Get the lower bound, i.e. a + maximum(d) # Get the upper bound, i.e. b + location(d) # Get the left bound, i.e. a + scale(d) # Get the span of the support, i.e. b - a + + External links + + * `Arcsine distribution on Wikipedia `_ + +.. function:: Beta(α,β) + + The *Beta distribution* has probability density function + + .. math:: + + f(x; \alpha, \beta) = \frac{1}{B(\alpha, \beta)} + x^{\alpha - 1} (1 - x)^{\beta - 1}, \quad x \in [0, 1] + + The Beta distribution is related to the :func:`Gamma` distribution via the property that if :math:`X \sim \operatorname{Gamma}(\alpha)` and :math:`Y \sim \operatorname{Gamma} (\beta)` independently, then :math:`X / (X + Y) \sim \operatorname{Beta}(\alpha, \beta)`\ . + + .. code-block:: julia + + Beta() # equivalent to Beta(1.0, 1.0) + Beta(a) # equivalent to Beta(a, a) + Beta(a, b) # Beta distribution with shape parameters a and b + + params(d) # Get the parameters, i.e. (a, b) + + External links + + * `Beta distribution on Wikipedia `_ + +.. function:: BetaPrime(α,β) + + The *Beta prime distribution* has probability density function + + .. math:: + + f(x; \alpha, \beta) = \frac{1}{B(\alpha, \beta)} + x^{\alpha - 1} (1 + x)^{- (\alpha + \beta)}, \quad x > 0 + + The Beta prime distribution is related to the :func:`Beta` distribution via the relation ship that if :math:`X \sim \operatorname{Beta}(\alpha, \beta)` then :math:`\frac{X}{1 - X} \sim \operatorname{BetaPrime}(\alpha, \beta)` + + .. 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) + + External links + + * `Beta prime distribution on Wikipedia `_ + + + +.. function:: Cauchy(μ, σ) + + The *Cauchy distribution* with location ``μ`` and scale ``σ`` has probability density function + + .. math:: + + f(x; \mu, \sigma) = \frac{1}{\pi \sigma \left(1 + \left(\frac{x - \mu}{\sigma} \right)^2 \right)} + + .. code-block:: julia + + Cauchy() # Standard Cauchy distribution, i.e. Cauchy(0.0, 1.0) + Cauchy(u) # Cauchy distribution with location u and unit scale, i.e. Cauchy(u, 1.0) + Cauchy(u, b) # Cauchy distribution with location u and scale b + + params(d) # Get the parameters, i.e. (u, b) + location(d) # Get the location parameter, i.e. u + scale(d) # Get the scale parameter, i.e. b + + External links + + * `Cauchy distribution on Wikipedia `_ + +.. function:: Chi(ν) + + The *Chi distribution* ``ν`` degrees of freedom has probability density function + + .. math:: + + f(x; k) = \frac{1}{\Gamma(k/2)} 2^{1 - k/2} x^{k-1} e^{-x^2/2}, \quad x > 0 + + It is the distribution of the square-root of a :func:`Chisq` variate. + + .. code-block:: julia + + Chi(k) # Chi distribution with k degrees of freedom + + params(d) # Get the parameters, i.e. (k,) + dof(d) # Get the degrees of freedom, i.e. k + + External links + + * `Chi distribution on Wikipedia `_ + +.. function:: Chisq(ν) + + The *Chi squared distribution* (typically written χ²) with ``ν`` degrees of freedom has the probability density function + + .. math:: + + f(x; k) = \frac{x^{k/2 - 1} e^{-x/2}}{2^{k/2} \Gamma(k/2)}, \quad x > 0. + + If ``ν`` is an integer, then it is the distribution of the sum of squares of ``ν`` independent standard :func:`Normal` variates. + + .. code-block:: julia + + Chisq(k) # Chi-squared distribution with k degrees of freedom + + params(d) # Get the parameters, i.e. (k,) + dof(d) # Get the degrees of freedom, i.e. k + + External links + + * `Chi-squared distribution on Wikipedia `_ + +.. function:: Erlang(α,θ) + + The *Erlang distribution* is a special case of a :func:`Gamma` distribution with integer shape parameter. + + .. code-block:: julia + + Erlang() # Erlang distribution with unit shape and unit scale, i.e. Erlang(1.0, 1.0) + Erlang(a) # Erlang distribution with shape parameter a and unit scale, i.e. Erlang(a, 1.0) + Erlang(a, s) # Erlang distribution with shape parameter a and scale b + + External links + + * `Erlang distribution on Wikipedia `_ + +.. function:: Exponential(θ) + + The *Exponential distribution* with scale parameter ``θ`` has probability density function + + .. math:: + + f(x; \theta) = \frac{1}{\theta} e^{-\frac{x}{\theta}}, \quad x > 0 + + .. code-block:: julia + + Exponential() # Exponential distribution with unit scale, i.e. Exponential(1.0) + Exponential(b) # Exponential distribution with scale b + + params(d) # Get the parameters, i.e. (b,) + scale(d) # Get the scale parameter, i.e. b + rate(d) # Get the rate parameter, i.e. 1 / b + + External links + + * `Exponential distribution on Wikipedia `_ + +.. function:: FDist(ν1,ν2) + + The *F distribution* has probability density function + + .. math:: + + f(x; \nu_1, \nu_2) = \frac{1}{x B(\nu_1/2, \nu_2/2)} + \sqrt{\frac{(\nu_1 x)^{\nu_1} \cdot \nu_2^{\nu_2}}{(\nu_1 x + \nu_2)^{\nu_1 + \nu_2}}}, + \quad x>0 + + It is related to the :func:`Chisq` distribution via the property that if :math:`X_1 \sim \operatorname{Chisq}(\nu_1)` and :math:`X_2 \sim \operatorname{Chisq}(\nu_2)`\ , then $(X_1/\\nu_1) / (X_2 / \\nu_2) \\sim FDist(\\nu_1, \\nu_2)`. + + .. code-block:: julia + + FDist(d1, d2) # F-Distribution with parameters d1 and d2 + + params(d) # Get the parameters, i.e. (d1, d2) + + External links + + * `F distribution on Wikipedia `_ + +.. function:: Frechet(α,θ) + + The *Fréchet distribution* with shape ``α`` and scale ``θ`` has probability density function + + .. math:: + + f(x; \alpha, \theta) = \frac{\alpha}{\theta} \left( \frac{x}{\theta} \right)^{-\alpha-1} + e^{-(x/\theta)^{-\alpha}}, \quad x > 0 + + .. code-block:: julia + + Frechet() # Fréchet distribution with unit shape and unit scale, i.e. Frechet(1.0, 1.0) + Frechet(a) # Fréchet distribution with shape a and unit scale, i.e. Frechet(a, 1.0) + Frechet(a, b) # Fréchet distribution with shape a and scale b + + params(d) # Get the parameters, i.e. (a, b) + shape(d) # Get the shape parameter, i.e. a + scale(d) # Get the scale parameter, i.e. b + + External links + + * `Fréchet_distribution on Wikipedia `_ + +.. function:: Gamma(α,θ) + + The *Gamma distribution* with shape parameter ``α`` and scale ``θ`` has probability density function + + .. math:: + + f(x; \alpha, \beta) = \frac{x^{\alpha-1} e^{-x/\beta}}{\Gamma(\alpha) \beta^\alpha}, + \quad x > 0 + + .. code-block:: julia + + Gamma() # Gamma distribution with unit shape and unit scale, i.e. Gamma(1.0, 1.0) + Gamma(a) # Gamma distribution with shape a and unit scale, i.e. Gamma(a, 1.0) + Gamma(a, b) # Gamma distribution with shape a and scale b + + params(d) # Get the parameters, i.e. (a, b) + shape(d) # Get the shape parameter, i.e. a + scale(d) # Get the scale parameter, i.e. b + + External links + + * `Gamma distribution on Wikipedia `_ + +.. function:: GeneralizedExtremeValue(μ, σ, ξ) + + The *Generalized extreme value distribution* with shape parameter ``ξ``\ , scale ``σ`` and location ``μ`` has probability density function + + .. math:: + + f(x; \xi, \sigma, \mu) = \begin{cases} + \frac{1}{\sigma} \left[ 1+\left(\frac{x-\mu}{\sigma}\right)\xi\right]^{-1/\xi-1} \exp\left\{-\left[ 1+ \left(\frac{x-\mu}{\sigma}\right)\xi\right]^{-1/\xi} \right\} & \text{for } \xi \neq 0 \\ + \frac{1}{\sigma} \exp\left\{-\frac{x-\mu}{\sigma}\right\} \exp\left\{-\exp\left[-\frac{x-\mu}{\sigma}\right]\right\} & \text{for } \xi = 0 + \end{cases} + + for + + .. math:: + + x \in \begin{cases} + \left[ \mu - \frac{\sigma}{\xi}, + \infty \right) & \text{for } \xi > 0 \\ + \left( - \infty, + \infty \right) & \text{for } \xi = 0 \\ + \left( - \infty, \mu - \frac{\sigma}{\xi} \right] & \text{for } \xi < 0 + \end{cases} + + .. code-block:: julia + + GeneralizedExtremeValue(k, s, m) # Generalized Pareto distribution with shape k, scale s and location m. + + params(d) # Get the parameters, i.e. (k, s, m) + shape(d) # Get the shape parameter, i.e. k (sometimes called c) + scale(d) # Get the scale parameter, i.e. s + location(d) # Get the location parameter, i.e. m + + External links + + * `Generalized extreme value distribution on Wikipedia `_ + +.. function:: GeneralizedPareto(ξ, σ, μ) + + The *Generalized Pareto distribution* with shape parameter ``ξ``\ , scale ``σ`` and location ``μ`` has probability density function + + .. math:: + + f(x; \xi, \sigma, \mu) = \begin{cases} + \frac{1}{\sigma}(1 + \xi \frac{x - \mu}{\sigma} )^{-\frac{1}{\xi} - 1} & \text{for } \xi \neq 0 \\ + \frac{1}{\sigma} e^{-\frac{\left( x - \mu \right) }{\sigma}} & \text{for } \xi = 0 + \end{cases}~, + \quad x \in \begin{cases} + \left[ \mu, \infty \right] & \text{for } \xi \geq 0 \\ + \left[ \mu, \mu - \sigma / \xi \right] & \text{for } \xi < 0 + \end{cases} + + .. code-block:: julia + + GeneralizedPareto() # Generalized Pareto distribution with unit shape and unit scale, i.e. GeneralizedPareto(1.0, 1.0, 0.0) + GeneralizedPareto(k, s) # Generalized Pareto distribution with shape k and scale s, i.e. GeneralizedPareto(k, s, 0.0) + GeneralizedPareto(k, s, m) # Generalized Pareto distribution with shape k, scale s and location m. + + params(d) # Get the parameters, i.e. (k, s, m) + shape(d) # Get the shape parameter, i.e. k + scale(d) # Get the scale parameter, i.e. s + location(d) # Get the location parameter, i.e. m + + External links + + * `Generalized Pareto distribution on Wikipedia `_ + +.. function:: Gumbel(μ, θ) + + The *Gumbel distribution* with location ``μ`` and scale ``θ`` has probability density function + + .. math:: + + f(x; \mu, \theta) = \frac{1}{\theta} e^{-(z + e^z)}, + \quad \text{ with } z = \frac{x - \mu}{\theta} + + .. code-block:: julia + + Gumbel() # Gumbel distribution with zero location and unit scale, i.e. Gumbel(0.0, 1.0) + Gumbel(u) # Gumbel distribution with location u and unit scale, i.e. Gumbel(u, 1.0) + Gumbel(u, b) # Gumbel distribution with location u and scale b + + params(d) # Get the parameters, i.e. (u, b) + location(d) # Get the location parameter, i.e. u + scale(d) # Get the scale parameter, i.e. b + + External links + + * `Gumbel distribution on Wikipedia `_ + +.. function:: InverseGamma(α, θ) + + The *inverse gamma distribution* with shape parameter ``α`` and scale ``θ`` has probability density function + + .. math:: + + f(x; \alpha, \theta) = \frac{\theta^\alpha x^{-(\alpha + 1)}}{\Gamma(\alpha)} + e^{-\frac{\theta}{x}}, \quad x > 0 + + It is related to the :func:`Gamma` distribution: if :math:`X \sim \operatorname{Gamma}(\alpha, \beta)`\ , then :math:`1 / X \sim \operatorname{InverseGamma}(\alpha, \beta^{-1})`\ . + + .. code-block:: julia + + .. code-block:: julia + + InverseGamma() # Inverse Gamma distribution with unit shape and unit scale, i.e. InverseGamma(1.0, 1.0) + InverseGamma(a) # Inverse Gamma distribution with shape a and unit scale, i.e. InverseGamma(a, 1.0) + InverseGamma(a, b) # Inverse Gamma distribution with shape a and scale b + + params(d) # Get the parameters, i.e. (a, b) + shape(d) # Get the shape parameter, i.e. a + scale(d) # Get the scale parameter, i.e. b + + External links + + * `Inverse gamma distribution on Wikipedia `_ + +.. function:: InverseGaussian(μ,λ) + + The *inverse Gaussian distribution* with mean ``μ`` and shape ``λ`` has probability density function + + .. math:: + + f(x; \mu, \lambda) = \sqrt{\frac{\lambda}{2\pi x^3}} + \exp\!\left(\frac{-\lambda(x-\mu)^2}{2\mu^2x}\right), \quad x > 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 + + params(d) # Get the parameters, i.e. (mu, lambda) + mean(d) # Get the mean parameter, i.e. mu + shape(d) # Get the shape parameter, i.e. lambda + + External links + + * `Inverse Gaussian distribution on Wikipedia `_ + +.. function:: Laplace(μ,θ) + + The *Laplace distribution* with location ``μ`` and scale ``θ`` has probability density function + + .. math:: + + f(x; \mu, \beta) = \frac{1}{2 \beta} \exp \left(- \frac{|x - \mu|}{\beta} \right) + + .. code-block:: julia + + Laplace() # Laplace distribution with zero location and unit scale, i.e. Laplace(0.0, 1.0) + Laplace(u) # Laplace distribution with location u and unit scale, i.e. Laplace(u, 1.0) + Laplace(u, b) # Laplace distribution with location u ans scale b + + params(d) # Get the parameters, i.e. (u, b) + location(d) # Get the location parameter, i.e. u + scale(d) # Get the scale parameter, i.e. b + + External links + + * `Laplace distribution on Wikipedia `_ + +.. function:: Levy(μ, σ) + + The *Lévy distribution* with location ``μ`` and scale ``σ`` has probability density function + + .. math:: + + f(x; \mu, \sigma) = \sqrt{\frac{\sigma}{2 \pi (x - \mu)^3}} + \exp \left( - \frac{\sigma}{2 (x - \mu)} \right), \quad x > \mu + + .. code-block:: julia + + Levy() # Levy distribution with zero location and unit scale, i.e. Levy(0.0, 1.0) + Levy(u) # Levy distribution with location u and unit scale, i.e. Levy(u, 1.0) + Levy(u, c) # Levy distribution with location u ans scale c + + params(d) # Get the parameters, i.e. (u, c) + location(d) # Get the location parameter, i.e. u + + External links + + * `Lévy distribution on Wikipedia `_ + +.. function:: LogNormal(μ,σ) + + The *log normal distribution* is the distribution of the exponential of a :func:`Normal` variate: if :math:`X \sim \operatorname{Normal}(\mu, \sigma)` then :math:`\exp(X) \sim \operatorname{LogNormal}(\mu,\sigma)`\ . The probability density function is + + .. math:: + + f(x; \mu, \sigma) = \frac{1}{x \sqrt{2 \pi \sigma^2}} + \exp \left( - \frac{(\log(x) - \mu)^2}{2 \sigma^2} \right), + \quad x > 0 + + .. 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 + + params(d) # Get the parameters, i.e. (mu, sig) + meanlogx(d) # Get the mean of log(X), i.e. mu + varlogx(d) # Get the variance of log(X), i.e. sig^2 + stdlogx(d) # Get the standard deviation of log(X), i.e. sig + + External links + + * `Log normal distribution on Wikipedia `_ + +.. function:: Logistic(μ,θ) + + The *Logistic distribution* with location ``μ`` and scale ``θ`` has probability density function + + .. math:: + + f(x; \mu, \theta) = \frac{1}{4 \theta} \mathrm{sech}^2 + \left( \frac{x - \mu}{\theta} \right) + + .. code-block:: julia + + Logistic() # Logistic distribution with zero location and unit scale, i.e. Logistic(0.0, 1.0) + Logistic(u) # Logistic distribution with location u and unit scale, i.e. Logistic(u, 1.0) + Logistic(u, b) # Logistic distribution with location u ans scale b + + params(d) # Get the parameters, i.e. (u, b) + location(d) # Get the location parameter, i.e. u + scale(d) # Get the scale parameter, i.e. b + + External links + + * `Logistic distribution on Wikipedia `_ + +.. function:: Normal(μ,σ) + + The *Normal distribution* with mean ``μ`` and standard deviation ``σ`` has probability density function + + .. math:: + + f(x; \mu, \sigma) = \frac{1}{\sqrt{2 \pi \sigma^2}} + \exp \left( - \frac{(x - \mu)^2}{2 \sigma^2} \right) + + .. code-block:: julia + + Normal() # standard Normal distribution with zero mean and unit variance + Normal(mu) # Normal distribution with mean mu and unit variance + Normal(mu, sig) # Normal distribution with mean mu and variance sig^2 + + params(d) # Get the parameters, i.e. (mu, sig) + mean(d) # Get the mean, i.e. mu + std(d) # Get the standard deviation, i.e. sig + + External links + + * `Normal distribution on Wikipedia `_ + +.. function:: NormalInverseGaussian(μ,α,β,δ) + + The *Normal-inverse Gaussian distribution* with location ``μ``\ , tail heaviness ``α``\ , asymmetry parameter ``β`` and scale ``δ`` has probability density function + + .. math:: + + f(x; \mu, \alpha, \beta, \delta) = \frac{\alpha\delta K_1 \left(\alpha\sqrt{\delta^2 + (x - \mu)^2}\right)}{\pi \sqrt{\delta^2 + (x - \mu)^2}} \; e^{\delta \gamma + \beta (x - \mu)} + + where :math:`K_j` denotes a modified Bessel function of the third kind. + + External links + + * `Normal-inverse Gaussian distribution on Wikipedia `_ + +.. function:: Pareto(α,θ) + + The *Pareto distribution* with shape ``α`` and scale ``θ`` has probability density function + + .. math:: + + f(x; \alpha, \theta) = \frac{\alpha \theta^\alpha}{x^{\alpha + 1}}, \quad x \ge \theta + + .. code-block:: julia + + Pareto() # Pareto distribution with unit shape and unit scale, i.e. Pareto(1.0, 1.0) + Pareto(a) # Pareto distribution with shape a and unit scale, i.e. Pareto(a, 1.0) + Pareto(a, b) # Pareto distribution with shape a and scale b + + params(d) # Get the parameters, i.e. (a, b) + shape(d) # Get the shape parameter, i.e. a + scale(d) # Get the scale parameter, i.e. b + + External links * `Pareto distribution on Wikipedia `_ + +.. function:: Rayleigh(σ) + + The *Rayleigh distribution* with scale ``σ`` has probability density function + + .. math:: + + f(x; \sigma) = \frac{x}{\sigma^2} e^{-\frac{x^2}{2 \sigma^2}}, \quad x > 0 + + It is related to the :func:`Normal` distribution via the property that if :math:`X, Y \sim \operatorname{Normal}(0,\sigma)`\ , independently, then :math:`\sqrt{X^2 + Y^2} \sim \operatorname{Rayleigh}(\sigma)`\ . + + .. code-block:: julia + + Rayleigh() # Rayleigh distribution with unit scale, i.e. Rayleigh(1.0) + Rayleigh(s) # Rayleigh distribution with scale s + + params(d) # Get the parameters, i.e. (s,) + scale(d) # Get the scale parameter, i.e. s + + External links + + * `Rayleigh distribution on Wikipedia `_ + +.. function:: SymTriangularDist(μ,σ) + + The *Symmetric triangular distribution* with location ``μ`` and scale ``σ`` has probability density function + + .. math:: + + f(x; \mu, \sigma) = \frac{1}{\sigma} \left( 1 - \left| \frac{x - \mu}{\sigma} \right| \right), \quad \mu - \sigma \le x \le \mu + \sigma + + .. code-block:: julia + + SymTriangularDist() # Symmetric triangular distribution with zero location and unit scale + SymTriangularDist(u) # Symmetric triangular distribution with location u and unit scale + SymTriangularDist(u, s) # Symmetric triangular distribution with location u and scale s + + params(d) # Get the parameters, i.e. (u, s) + location(d) # Get the location parameter, i.e. u + scale(d) # Get the scale parameter, i.e. s + +.. function:: TDist(ν) + + The *Students T distribution* with ``ν`` degrees of freedom has probability density function + + .. math:: + + f(x; d) = \frac{1}{\sqrt{d} B(1/2, d/2)} + \left( 1 + \frac{x^2}{d} \right)^{-\frac{d + 1}{2}} + + .. code-block:: julia + + TDist(d) # t-distribution with d degrees of freedom + + params(d) # Get the parameters, i.e. (d,) + dof(d) # Get the degrees of freedom, i.e. d + + External links + + `Student's T distribution on Wikipedia `_ + +.. function:: TriangularDist(a,b,c) + + The *triangular distribution* with lower limit ``a``\ , upper limit ``b`` and mode ``c`` has probability density function + + .. 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] + \frac{2(b-x)}{(b-a)(b-c)} & \mathrm{for\ } c < x \le b, \\[4pt] + 0 & \mathrm{for\ } b < x, + \end{cases} + + .. code-block:: julia + + TriangularDist(a, b) # Triangular distribution with lower limit a, upper limit b, and mode (a+b)/2 + TriangularDist(a, b, c) # Triangular distribution with lower limit a, upper limit b, and mode c + + params(d) # Get the parameters, i.e. (a, b, c) + minimum(d) # Get the lower bound, i.e. a + maximum(d) # Get the upper bound, i.e. b + mode(d) # Get the mode, i.e. c + + External links + + * `Triangular distribution on Wikipedia `_ + +.. function:: Uniform(a,b) + + The *continuous uniform distribution* over an interval :math:`[a, b]` has probability density function + + .. math:: + + f(x; a, b) = \frac{1}{b - a}, \quad a \le x \le b + + .. code-block:: julia + + Uniform() # Uniform distribution over [0, 1] + Uniform(a, b) # Uniform distribution over [a, b] + + params(d) # Get the parameters, i.e. (a, b) + minimum(d) # Get the lower bound, i.e. a + maximum(d) # Get the upper bound, i.e. b + location(d) # Get the location parameter, i.e. a + scale(d) # Get the scale parameter, i.e. b - a + + External links + + * `Uniform distribution (continuous) on Wikipedia `_ + +.. function:: VonMises(μ, κ) + + The *von Mises distribution* with mean ``μ`` and concentration ``κ`` has probability density function + + .. math:: + + f(x; \mu, \kappa) = \frac{1}{2 \pi I_0(\kappa)} \exp \left( \kappa \cos (x - \mu) \right) + + .. code-block:: julia + + VonMises() # von Mises distribution with zero mean and unit concentration + VonMises(κ) # von Mises distribution with zero mean and concentration κ + VonMises(μ, κ) # von Mises distribution with mean μ and concentration κ + + External links + + * `von Mises distribution on Wikipedia `_ + +.. function:: Weibull(α,θ) + + The *Weibull distribution* with shape ``α`` and scale ``θ`` has probability density function + + .. math:: + + f(x; \alpha, \theta) = \frac{\alpha}{\theta} \left( \frac{x}{\theta} \right)^{\alpha-1} e^{-(x/\theta)^\alpha}, + \quad x \ge 0 + + .. code-block:: julia + + Weibull() # Weibull distribution with unit shape and unit scale, i.e. Weibull(1.0, 1.0) + Weibull(a) # Weibull distribution with shape a and unit scale, i.e. Weibull(a, 1.0) + Weibull(a, b) # Weibull distribution with shape a and scale b + + params(d) # Get the parameters, i.e. (a, b) + shape(d) # Get the shape parameter, i.e. a + scale(d) # Get the scale parameter, i.e. b + + External links + + * `Weibull distribution on Wikipedia `_ + diff --git a/doc/source/univariate-discrete.rst b/doc/source/univariate-discrete.rst new file mode 100644 index 000000000..c25daf4da --- /dev/null +++ b/doc/source/univariate-discrete.rst @@ -0,0 +1,249 @@ +.. _univariate-discrete: + +Univariate Discrete Distributions +---------------------------------------------------- + +.. DO NOT EDIT: this file is generated from Julia source. + +.. function:: Bernoulli(p) + + A *Bernoulli distribution* is parameterized by a success rate ``p``\ , which takes value 1 with probability ``p`` and 0 with probability ``1-p``\ . + + .. math:: + + P(X = k) = \begin{cases} + 1 - p & \quad \text{for } k = 0, \\ + p & \quad \text{for } k = 1. + \end{cases} + + .. code-block:: julia + + Bernoulli() # Bernoulli distribution with p = 0.5 + Bernoulli(p) # Bernoulli distribution with success rate p + + params(d) # Get the parameters, i.e. (p,) + succprob(d) # Get the success rate, i.e. p + failprob(d) # Get the failure rate, i.e. 1 - p + + External links: + + * `Bernoulli distribution on Wikipedia `_ + +.. function:: BetaBinomial(n,α,β) + + A *Beta-binomial distribution* is the compound distribution of the :func:`Binomial` distribution where the probability of success ``p`` is distributed according to the :func:`Beta`. It has three parameters: ``n``\ , the number of trials and two shape parameters ``α``\ , ``β`` + + .. math:: + + P(X = k) = {n \choose k} B(k + \alpha, n - k + \beta) / B(\alpha, \beta), \quad \text{ for } k = 0,1,2, \ldots, n. + + .. code-block:: julia + + BetaBinomial(n, a, b) # BetaBinomial distribution with n trials and shape parameters a, b + + params(d) # Get the parameters, i.e. (n, a, b) + ntrials(d) # Get the number of trials, i.e. n + + External links: + + * `Beta-binomial distribution on Wikipedia `_ + +.. function:: Binomial(n,p) + + A *Binomial distribution* characterizes the number of successes in a sequence of independent trials. It has two parameters: ``n``\ , the number of trials, and ``p``\ , the probability of success in an individual trial, with the distribution: + + .. math:: + + P(X = k) = {n \choose k}p^k(1-p)^{n-k}, \quad \text{ for } k = 0,1,2, \ldots, n. + + .. code-block:: julia + + Binomial() # Binomial distribution with n = 1 and p = 0.5 + Binomial(n) # Binomial distribution for n trials with success rate p = 0.5 + Binomial(n, p) # Binomial distribution for n trials with success rate p + + params(d) # Get the parameters, i.e. (n, p) + ntrials(d) # Get the number of trials, i.e. n + succprob(d) # Get the success rate, i.e. p + failprob(d) # Get the failure rate, i.e. 1 - p + + External links: + + * `Binomial distribution on Wikipedia `_ + +.. function:: Categorical(p) + + A *Categorical distribution* is parameterized by a probability vector ``p`` (of length ``K``\ ). + + .. math:: + + P(X = k) = p[k] \quad \text{for } k = 1, 2, \ldots, K. + + .. code-block:: julia + + Categorical(p) # Categorical distribution with probability vector p + + params(d) # Get the parameters, i.e. (p,) + probs(d) # Get the probability vector, i.e. p + ncategories(d) # Get the number of categories, i.e. K + + Here, ``p`` must be a real vector, of which all components are nonnegative and sum to one. + + **Note:** The input vector ``p`` is directly used as a field of the constructed distribution, without being copied. + + External links: + + * `Categorical distribution on Wikipedia `_ + +.. function:: DiscreteUniform(a,b) + + A *Discrete uniform distribution* is a uniform distribution over a consecutive sequence of integers between ``a`` and ``b``\ , inclusive. + + .. math:: + + P(X = k) = 1 / (b - a + 1) \quad \text{for } k = a, a+1, \ldots, b. + + .. code-block:: julia + + DiscreteUniform(a, b) # a uniform distribution over {a, a+1, ..., b} + + params(d) # Get the parameters, i.e. (a, b) + span(d) # Get the span of the support, i.e. (b - a + 1) + probval(d) # Get the probability value, i.e. 1 / (b - a + 1) + minimum(d) # Return a + maximum(d) # Return b + + External links + + * `Discrete uniform distribution on Wikipedia `_ + +.. function:: Geometric(p) + + A *Geometric distribution* characterizes the number of failures before the first success in a sequence of independent Bernoulli trials with success rate ``p``\ . + + .. math:: + + P(X = k) = p (1 - p)^k, \quad \text{for } k = 0, 1, 2, \ldots. + + .. code-block:: julia + + Geometric() # Geometric distribution with success rate 0.5 + Geometric(p) # Geometric distribution with success rate p + + params(d) # Get the parameters, i.e. (p,) + succprob(d) # Get the success rate, i.e. p + failprob(d) # Get the failure rate, i.e. 1 - p + + External links + + * `Geometric distribution on Wikipedia `_ + +.. function:: Hypergeometric(s, f, n) + + A *Hypergeometric distribution* describes the number of successes in ``n`` draws without replacement from a finite population containing ``s`` successes and ``f`` failures. + + .. math:: + + P(X = k) = {{{s \choose k} {f \choose {n-k}}}\over {s+f \choose n}}, \quad \text{for } k = \max(0, n - f), \ldots, \min(n, s). + + .. code-block:: julia + + Hypergeometric(s, f, n) # Hypergeometric distribution for a population with + # s successes and f failures, and a sequence of n trials. + + params(d) # Get the parameters, i.e. (s, f, n) + + External links + + * `Hypergeometric distribution on Wikipedia `_ + +.. function:: NegativeBinomial(r,p) + + A *Negative binomial distribution* describes the number of failures before the ``r``\ th success in a sequence of independent Bernoulli trials. It is parameterized by ``r``\ , the number of successes, and ``p``\ , the probability of success in an individual trial. + + .. math:: + + P(X = k) = {k + r - 1 \choose k} p^r (1 - p)^k, \quad \text{for } k = 0,1,2,\ldots. + + The distribution remains well-defined for any positive ``r``\ , in which case + + .. math:: + + P(X = k) = \frac{\Gamma(k+r)}{k! \Gamma(r)} p^r (1 - p)^k, \quad \text{for } k = 0,1,2,\ldots. + + .. code-block:: julia + + NegativeBinomial() # Negative binomial distribution with r = 1 and p = 0.5 + NegativeBinomial(r, p) # Negative binomial distribution with r successes and success rate p + + params(d) # Get the parameters, i.e. (r, p) + succprob(d) # Get the success rate, i.e. p + failprob(d) # Get the failure rate, i.e. 1 - p + + External links: + + * `Negative binomial distribution on Wikipedia `_ + +.. function:: Poisson(λ) + + A *Poisson distribution* descibes the number of independent events occurring within a unit time interval, given the average rate of occurrence ``λ``\ . + + .. math:: + + P(X = k) = \frac{\lambda^k}{k!} e^{-\lambda}, \quad \text{ for } k = 0,1,2,\ldots. + + .. code-block:: julia + + Poisson() # Poisson distribution with rate parameter 1 + Poisson(lambda) # Poisson distribution with rate parameter lambda + + params(d) # Get the parameters, i.e. (λ,) + mean(d) # Get the mean arrival rate, i.e. λ + + External links: + + * `Poisson distribution on Wikipedia `_ + +.. function:: PoissonBinomial(p) + + A *Poisson-binomial distribution* describes the number of successes in a sequence of independent trials, wherein each trial has a different success rate. It is parameterized by a vector ``p`` (of length ``K``\ ), where ``K`` is the total number of trials and ``p[i]`` corresponds to the probability of success of the ``i``\ th trial. + + .. math:: + + P(X = k) = \sum\limits_{A\in F_k} \prod\limits_{i\in A} p[i] \prod\limits_{j\in A^c} (1-p[j]), \quad \text{ for } k = 0,1,2,\ldots,K, + + where :math:`F_k` is the set of all subsets of :math:`k` integers that can be selected from :math:`\{1,2,3,...,K\}`\ . + + .. code-block:: julia + + PoissonBinomial(p) # Poisson Binomial distribution with success rate vector p + + params(d) # Get the parameters, i.e. (p,) + succprob(d) # Get the vector of success rates, i.e. p + failprob(d) # Get the vector of failure rates, i.e. 1-p + + External links: + + * `Poisson-binomial distribution on Wikipedia `_ + +.. function:: Skellam(μ1, μ2) + + A *Skellam distribution* describes the difference between two independent :func:`Poisson` variables, respectively with rate ``μ1`` and ``μ2``\ . + + .. math:: + + 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 + + where :math:`I_k` is the modified Bessel function of the first kind. + + .. code-block:: julia + + Skellam(mu1, mu2) # Skellam distribution for the difference between two Poisson variables, + # respectively with expected values mu1 and mu2. + + params(d) # Get the parameters, i.e. (mu1, mu2) + + External links: + + * `Skellam distribution on Wikipedia `_ + diff --git a/doc/source/univariate.rst b/doc/source/univariate.rst index cb5d32327..3830f5ae0 100644 --- a/doc/source/univariate.rst +++ b/doc/source/univariate.rst @@ -3,6 +3,13 @@ Univariate Distributions ========================== + +.. toctree:: + :maxdepth: 1 + + univariate-continuous.rst + univariate-discrete.rst + *Univariate distributions* are the distributions whose variate forms are ``Univariate`` (*i.e* each sample is a scalar). Abstract types for univariate distributions: .. code-block:: julia @@ -245,977 +252,3 @@ Sampling (Random number generation) Fills a pre-allocated array ``arr`` with independent samples from the distribution ``d``. -List of Distributions ----------------------- - -*Distributions* provides a large collection of univariate distributions. Here is a brief list: - -* Discrete univariate distributions: - - - :ref:`bernoulli` - - :ref:`betabinomial` - - :ref:`binomial` - - :ref:`categorical` - - :ref:`discreteuniform` - - :ref:`geometric` - - :ref:`hypergeometric` - - :ref:`negativebinomial` - - :ref:`poissonbinomial` - - :ref:`poisson` - - :ref:`skellam` - -* Continuous univariate distributions: - - - :ref:`arcsine` - - :ref:`beta` - - :ref:`betaprime` - - :ref:`cauchy` - - :ref:`chi` - - :ref:`chisquare` - - :ref:`erlang` - - :ref:`exponential` - - :ref:`fdist` - - :ref:`frechet` - - :ref:`gamma` - - :ref:`generalizedpareto` - - :ref:`generalizedextremevalue` - - :ref:`gumbel` - - :ref:`inversegamma` - - :ref:`inversegaussian` - - :ref:`laplace` - - :ref:`levy` - - :ref:`logistic` - - :ref:`lognormal` - - :ref:`normal` - - :ref:`normalinversegaussian` - - :ref:`pareto` - - :ref:`rayleigh` - - :ref:`symtriangular` - - :ref:`tdist` - - :ref:`triangular` - - :ref:`uniform` - - :ref:`vonmises` - - :ref:`weibull` - - -Discrete Distributions ------------------------- - -All discrete univariate distribution types are subtypes of *DiscreteUnivariateDistribution*. Each sample from a discrete univariate distribution is an integer (of type ``Int``). - -.. _bernoulli: - -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`. - -.. math:: - - P(X = k) = \begin{cases} - 1 - p & \quad \text{for } k = 0, \\ - p & \quad \text{for } k = 1. - \end{cases} - -.. code-block:: julia - - Bernoulli() # Bernoulli distribution with p = 0.5 - Bernoulli(p) # Bernoulli distribution with success rate p - - params(d) # Get the parameters, i.e. (p,) - succprob(d) # Get the success rate, i.e. p - failprob(d) # Get the failure rate, i.e. 1 - p - -.. _betabinomial: - -Beta-binomial Distribution -~~~~~~~~~~~~~~~~~~~~~~ - -A `Beta-binomial distribution `_ characterizes the number of successes in a sequence of independent trials where the probability of success is determined by the beta distribution. It has three parameters: :math:`n`, the number of trials and two shape parameters :math:`\alpha`, :math:`\beta` - -.. math:: - - P(X = k) = {n \choose k} B(k + \alpha, n - k + \beta) / B(\alpha, \beta), \quad \text{ for } k = 0,1,2, \ldots, n. - -.. code-block:: julia - - BetaBinomial(n, a, b) # BetaBinomial distribution with n trials and shape parameters a, b - - params(d) # Get the parameters, i.e. (n, a, b) - ntrials(d) # Get the number of trials, i.e. n - -.. _binomial: - -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. - -.. math:: - - P(X = k) = {n \choose k}p^k(1-p)^{n-k}, \quad \text{ for } k = 0,1,2, \ldots, n. - -.. code-block:: julia - - Binomial() # Binomial distribution with n = 1 and p = 0.5 - Binomial(n) # Binomial distribution for n trials with success rate p = 0.5 - Binomial(n, p) # Binomial distribution for n trials with success rate p - - params(d) # Get the parameters, i.e. (n, p) - ntrials(d) # Get the number of trials, i.e. n - succprob(d) # Get the success rate, i.e. p - failprob(d) # Get the failure rate, i.e. 1 - p - -.. _categorical: - -Categorical Distribution -~~~~~~~~~~~~~~~~~~~~~~~~~ - -A `Categorical distribution `_ is parameterized by a probability vector :math:`p` (of length ``K``). - -.. math:: - - P(X = k) = p[k] \quad \text{for } k = 1, 2, \ldots, K. - -.. code-block:: julia - - Categorical(p) # Categorical distribution with probability vector p - - params(d) # Get the parameters, i.e. (p,) - probs(d) # Get the probability vector, i.e. p - ncategories(d) # Get the number of categories, i.e. K - -Here, ``p`` must be a real vector, of which all components are nonnegative and sum to one. - -**Note:** The input vector ``p`` is directly used as a field of the constructed distribution, without being copied. - - -.. _discreteuniform: - -Discrete Uniform Distribution -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A `Discrete uniform distribution `_ is a uniform distribution over a consecutive sequence of integers between :math:`a` and :math:`b`. - -.. math:: - - P(X = k) = 1 / (b - a + 1) \quad \text{for } k = a, a+1, \ldots, b. - -.. code-block:: julia - - DiscreteUniform(a, b) # a uniform distribution over {a, a+1, ..., b} - - params(d) # Get the parameters, i.e. (a, b) - span(d) # Get the span of the support, i.e. (b - a + 1) - probval(d) # Get the probability value, i.e. 1 / (b - a + 1) - minimum(d) # Return a - maximum(d) # Return b - - -.. _geometric: - -Geometric Distribution -~~~~~~~~~~~~~~~~~~~~~~~ - -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:: - - P(X = k) = p (1 - p)^k, \quad \text{for } k = 0, 1, 2, \ldots. - -.. code-block:: julia - - Geometric() # Geometric distribution with success rate 0.5 - Geometric(p) # Geometric distribution with success rate p - - params(d) # Get the parameters, i.e. (p,) - succprob(d) # Get the success rate, i.e. p - failprob(d) # Get the failure rate, i.e. 1 - p - - -.. _hypergeometric: - -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. - -.. math:: - - P(X = k) = {{{s \choose k} {f \choose {n-k}}}\over {s+f \choose n}}, \quad \text{for } k = \max(0, n - f), \ldots, \min(n, s). - -.. code-block:: julia - - Hypergeometric(s, f, n) # Hypergeometric distribution for a population with - # s successes and f failures, and a sequence of n trials. - - params(d) # Get the parameters, i.e. (s, f, n) - - -.. _negativebinomial: - -Negative Binomial Distribution -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A `Negative binomial distribution `_ describes the number of failures before the :math:`r`-th success in a sequence of independent Bernoulli trials. It is parameterized by :math:`r`, the number of successes, and :math:`p`, the success rate. - -.. math:: - - P(X = k) = {k + r - 1 \choose k} p^r (1 - p)^k, \quad \text{for } k = 0,1,2,\ldots. - -.. code-block:: julia - - NegativeBinomial() # Negative binomial distribution with r = 1 and p = 0.5 - NegativeBinomial(r, p) # Negative binomial distribution with r successes and success rate p - - params(d) # Get the parameters, i.e. (r, p) - succprob(d) # Get the success rate, i.e. p - failprob(d) # Get the failure rate, i.e. 1 - p - - - -.. _poissonbinomial: - -Poisson Binomial Distribution -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A `Poisson Binomial distribution `_ describes the number of successes in a sequence of independent trials, wherein each trial has a different success rate. It is parameterized by a vector :math:`p` (of length ``K``), where ``K`` is the total number of trials and each entry of :math:`p` corresponds to the success rate of one trial. - -.. math:: - - P(X = k) = \sum\limits_{A\in F_k} \prod\limits_{i\in A} p[i] \prod\limits_{j\in A^c} (1-p[j]), \quad \text{ for } k = 0,1,2,\ldots,K. - -Here, :math:`F_k` is the set of all subsets of ``k`` integers that can be selected from :math:`\{1,2,3,...,K\}`. - -.. code-block:: julia - - PoissonBinomial(p) # Poisson Binomial distribution with success rate vector p - - params(d) # Get the parameters, i.e. (p,) - succprob(d) # Get the vector of success rates, i.e. p - failprob(d) # Get the vector of failure rates, i.e. 1-p - - - -.. _poisson: - -Poisson Distribution -~~~~~~~~~~~~~~~~~~~~~ - -A `Poisson distribution `_ descibes the number of independent events occurring within a unit time interval, given the average rate of occurrence :math:`\lambda`. - -.. math:: - - P(X = k) = \frac{\lambda^k}{k!} e^{-\lambda}, \quad \text{ for } k = 0,1,2,\ldots. - -.. code-block:: julia - - Poisson() # Poisson distribution with rate parameter 1 - Poisson(lambda) # Poisson distribution with rate parameter lambda - - params(d) # Get the parameters, i.e. (lambda,) - mean(d) # Get the mean arrival rate, i.e. lambda - - -.. _skellam: - -Skellam Distribution -~~~~~~~~~~~~~~~~~~~~~ - -A `Skellam distribution `_ describes the difference between two independent Poisson variables, respectively with rate :math:`\mu_1` and :math:`\mu_2`. - -.. math:: - - 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. - -.. code-block:: julia - - Skellam(mu1, mu2) # Skellam distribution for the difference between two Poisson variables, - # respectively with expected values mu1 and mu2. - - params(d) # Get the parameters, i.e. (mu1, mu2) - - - -Continuous Distributions -------------------------- - -All discrete univariate distribution types are subtypes of *ContinuousUnivariateDistribution*. Each sample from a discrete univariate distribution is a real-valued scalar (of type ``Float64``). - -.. _arcsine: - -Arcsine Distribution -~~~~~~~~~~~~~~~~~~~~~~ - -The probability density function of an `Arcsine distribution `_ with bounded support :math:`[a, b]` is: - -.. math:: - - f(x) = \frac{1}{\pi \sqrt{(x - a) (b - x)}}, \quad x \in [a, b] - -.. code-block:: julia - - Arcsine() # Arcsine distribution with support [0, 1] - Arcsine(b) # Arcsine distribution with support [0, b] - Arcsine(a, b) # Arcsine distribution with support [a, b] - - params(d) # Get the parameters, i.e. (a, b) - minimum(d) # Get the lower bound, i.e. a - maximum(d) # Get the upper bound, i.e. b - location(d) # Get the left bound, i.e. a - scale(d) # Get the span of the support, i.e. b - a - -.. _beta: - -Beta Distribution -~~~~~~~~~~~~~~~~~~~~~~ - -The probability density function of a `Beta distribution `_ with shape parameters :math:`\alpha` and :math:`\beta` is: - -.. math:: - - f(x; \alpha, \beta) = \frac{1}{B(\alpha, \beta)} - x^{\alpha - 1} (1 - x)^{\beta - 1}, \quad x \in [0, 1] - -.. code-block:: julia - - Beta() # equivalent to Beta(1.0, 1.0) - Beta(a) # equivalent to Beta(a, a) - Beta(a, b) # Beta distribution with shape parameters a and b - - params(d) # Get the parameters, i.e. (a, b) - -**Note:** If :math:`X \sim Gamma(\alpha)` and :math:`Y \sim Gamma(\beta)`, then :math:`X / (X + Y) \sim Beta(\alpha, \beta)`. - - -.. _betaprime: - -Beta Prime Distribution -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The probability density function of a `Beta prime distribution `_ with shape parameters :math:`\alpha` and :math:`\beta` is: - -.. math:: - - f(x; \alpha, \beta) = \frac{1}{B(\alpha, \beta)} - x^{\alpha - 1} (1 + x)^{- (\alpha + \beta)}, \quad x > 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)`. - - -.. _cauchy: - -Cauchy Distribution -~~~~~~~~~~~~~~~~~~~~~ - -The probability density function of a `Cauchy distribution `_ with location :math:`\mu` and scale :math:`\beta` is: - -.. math:: - - f(x; \mu, \beta) = \frac{1}{\pi \beta \left(1 + \left(\frac{x - \mu}{\beta} \right)^2 \right)} - -.. code-block:: julia - - Cauchy() # Standard Cauchy distribution, i.e. Cauchy(0.0, 1.0) - Cauchy(u) # Cauchy distribution with location u and unit scale, i.e. Cauchy(u, 1.0) - Cauchy(u, b) # Cauchy distribution with location u and scale b - - params(d) # Get the parameters, i.e. (u, b) - location(d) # Get the location parameter, i.e. u - scale(d) # Get the scale parameter, i.e. b - - -.. _chi: - -Chi Distribution -~~~~~~~~~~~~~~~~~ - -The `Chi distribution `_ with :math:`k` degrees of freedom is the distribution of the square root of the sum of squares of :math:`k` independent variables that are normally distributed. The probability density function is: - -.. math:: - - f(x; k) = \frac{1}{\Gamma(k/2)} 2^{1 - k/2} x^{k-1} e^{-x^2/2}, \quad x > 0 - -.. code-block:: julia - - Chi(k) # Chi distribution with k degrees of freedom - - params(d) # Get the parameters, i.e. (k,) - dof(d) # Get the degrees of freedom, i.e. k - - -.. _chisquare: - -Chi-square Distribution -~~~~~~~~~~~~~~~~~~~~~~~~ - -The `Chi square distribution `_ with :math:`k` degrees of freedom is the distribution of the sum of squares of :math:`k` independent variables that are normally distributed. The probability density function is: - -.. math:: - - f(x; k) = \frac{x^{k/2 - 1} e^{-x/2}}{2^{k/2} \Gamma(k/2)}, \quad x > 0 - -.. code-block:: julia - - Chisq(k) # Chi-squared distribution with k degrees of freedom - - params(d) # Get the parameters, i.e. (k,) - dof(d) # Get the degrees of freedom, i.e. k - - -.. _erlang: - -Erlang Distribution -~~~~~~~~~~~~~~~~~~~~ - -The probability density function of an `Erlang distribution `_ with shape parameter :math:`\alpha` and scale :math:`\beta` is - -.. math:: - - f(x; \alpha, \beta) = \frac{x^{\alpha-1} e^{-x/\beta}}{\Gamma(\alpha) \beta^\alpha}, \quad x > 0 - -.. code-block:: julia - - Erlang() # Erlang distribution with unit shape and unit scale, i.e. Erlang(1.0, 1.0) - Erlang(a) # Erlang distribution with shape parameter a and unit scale, i.e. Erlang(a, 1.0) - Erlang(a, s) # Erlang distribution with shape parameter a and scale b - -**Note:** The Erlang distribution is a special case of the Gamma distribution with integer shape parameter. - - -.. _exponential: - -Exponential Distribution -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The probability density function of an `Exponential distribution `_ with scale :math:`\beta` is - -.. math:: - - f(x; \beta) = \frac{1}{\beta} e^{-\frac{x}{\beta}}, \quad x > 0 - -.. code-block:: julia - - Exponential() # Exponential distribution with unit scale, i.e. Exponential(1.0) - Exponential(b) # Exponential distribution with scale b - - params(d) # Get the parameters, i.e. (b,) - scale(d) # Get the scale parameter, i.e. b - rate(d) # Get the rate parameter, i.e. 1 / b - - -.. _fdist: - -F Distribution -~~~~~~~~~~~~~~~ - -The probability density function of an `F distribution `_ with parameters :math:`d_1` and :math:`d_2` is - -.. math:: - - f(x; d_1, d_2) = \frac{1}{x B(d_1/2, d_2/2)} - \sqrt{\frac{(d_1 x)^{d_1} \cdot d_2^{d_2}}{(d_1 x + d_2)^{d_1 + d_2}}} - -.. code-block:: julia - - FDist(d1, d2) # F-Distribution with parameters d1 and d2 - - params(d) # Get the parameters, i.e. (d1, d2) - -**Note:** If :math:`X \sim Chisq(d1)` and :math:`Y \sim Chisq(d2)`, then :math:`(X / d1) / (Y / d2) \sim FDist(d1, d2)`. - - -.. _frechet: - -Fréchet Distribution -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The probability density function of a `Fréchet distribution `_ with shape :math:`\alpha` and scale :math:`\beta` is - -.. math:: - - f(x; \alpha, \beta) = \frac{\alpha}{\beta} \left( \frac{x}{\beta} \right)^{-\alpha-1} e^{-(x/\beta)^{-\alpha}}, - \quad x > 0 - -.. code-block:: julia - - Frechet() # Fréchet distribution with unit shape and unit scale, i.e. Frechet(1.0, 1.0) - Frechet(a) # Fréchet distribution with shape a and unit scale, i.e. Frechet(a, 1.0) - Frechet(a, b) # Fréchet distribution with shape a and scale b - - params(d) # Get the parameters, i.e. (a, b) - shape(d) # Get the shape parameter, i.e. a - scale(d) # Get the scale parameter, i.e. b - - -.. _gamma: - -Gamma Distribution -~~~~~~~~~~~~~~~~~~~ - -The probability density function of a `Gamma distribution `_ with shape parameter :math:`\alpha` and scale :math:`\beta` is - -.. math:: - - f(x; \alpha, \beta) = \frac{x^{\alpha-1} e^{-x/\beta}}{\Gamma(\alpha) \beta^\alpha}, - \quad x > 0 - -.. code-block:: julia - - Gamma() # Gamma distribution with unit shape and unit scale, i.e. Gamma(1.0, 1.0) - Gamma(a) # Gamma distribution with shape a and unit scale, i.e. Gamma(a, 1.0) - Gamma(a, b) # Gamma distribution with shape a and scale b - - params(d) # Get the parameters, i.e. (a, b) - shape(d) # Get the shape parameter, i.e. a - scale(d) # Get the scale parameter, i.e. b - - -.. _generalizedpareto: - -Generalized Pareto Distribution -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The probability density function of a `Generalized Pareto distribution `_ with shape parameter :math:`\xi`, scale :math:`\sigma` and location :math:`\mu` is - -.. math:: - - f(x; \xi, \sigma, \mu) = \begin{cases} - \frac{1}{\sigma}(1 + \xi \frac{x - \mu}{\sigma} )^{-\frac{1}{\xi} - 1} & \text{for } \xi \neq 0 \\ - \frac{1}{\sigma} e^{-\frac{\left( x - \mu \right) }{\sigma}} & \text{for } \xi = 0 - \end{cases}~, - \quad x \in \begin{cases} - \left[ \mu, \infty \right] & \text{for } \xi \geq 0 \\ - \left[ \mu, \mu - \sigma / \xi \right] & \text{for } \xi < 0 - \end{cases} - -.. code-block:: julia - - GeneralizedPareto() # Generalized Pareto distribution with unit shape and unit scale, i.e. GeneralizedPareto(1.0, 1.0, 0.0) - GeneralizedPareto(k, s) # Generalized Pareto distribution with shape k and scale s, i.e. GeneralizedPareto(k, s, 0.0) - GeneralizedPareto(k, s, m) # Generalized Pareto distribution with shape k, scale s and location m. - - params(d) # Get the parameters, i.e. (k, s, m) - shape(d) # Get the shape parameter, i.e. k - scale(d) # Get the scale parameter, i.e. s - location(d) # Get the location parameter, i.e. m - - -.. _generalizedextremevalue: - -Generalized Extreme Value Distribution -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The probability density function of a `Generalized extreme value distribution `_ with shape parameter :math:`\xi`, scale :math:`\sigma` and location :math:`\mu` is - -.. math:: - - f(x; \xi, \sigma, \mu) = \begin{cases} - \frac{1}{\sigma} (1+(\tfrac{x-\mu}{\sigma})\xi\right)^{-1/\xi}^{\xi+1}e^{-(1+(\tfrac{x-\mu}{\sigma})\xi\right)^{-1/\xi}} & \text{for } \xi \neq 0 \\ - \frac{1}{\sigma} e^{-(x-\mu)/\sigma}^{\xi+1}e^{-e^{-(x-\mu)/\sigma}} & \text{for } \xi = 0 - \end{cases}~, - \quad x \in \begin{cases} - \left[ \mu - \frac{\sigma}{\xi}, + \infty \right) & \text{for } \xi > 0 \\ - \left( - \infty, + \infty \right) & \text{for } \xi = 0 \\ - \left( - \infty, \mu - \frac{\sigma}{\xi} \right] & \text{for } \xi < 0 - \end{cases} - -.. code-block:: julia - - GeneralizedExtremeValue(k, s, m) # Generalized Pareto distribution with shape k, scale s and location m. - - params(d) # Get the parameters, i.e. (k, s, m) - shape(d) # Get the shape parameter, i.e. k (sometimes called c) - scale(d) # Get the scale parameter, i.e. s - location(d) # Get the location parameter, i.e. m - - -.. _gumbel: - -Gumbel Distribution -~~~~~~~~~~~~~~~~~~~~~ - -The probability density function of a `Gumbel distribution `_ with location :math:`\mu` and scale :math:`\beta` is - -.. math:: - - f(x; \mu, \beta) = \frac{1}{\beta} e^{-(z + e^z)}, - \quad \text{ with } z = \frac{x - \mu}{\beta} - -.. code-block:: julia - - Gumbel() # Gumbel distribution with zero location and unit scale, i.e. Gumbel(0.0, 1.0) - Gumbel(u) # Gumbel distribution with location u and unit scale, i.e. Gumbel(u, 1.0) - Gumbel(u, b) # Gumbel distribution with location u and scale b - - params(d) # Get the parameters, i.e. (u, b) - location(d) # Get the location parameter, i.e. u - scale(d) # Get the scale parameter, i.e. b - - -.. _inversegamma: - -Inverse Gamma Distribution -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The probability density function of an `inverse Gamma distribution `_ with shape parameter :math:`\alpha` and scale :math:`\beta` is - -.. math:: - - f(x; \alpha, \beta) = \frac{\beta^\alpha x^{-(\alpha + 1)}}{\Gamma(\alpha)} - e^{-\frac{\beta}{x}}, \quad x > 0 - -.. code-block:: julia - - InverseGamma() # Inverse Gamma distribution with unit shape and unit scale, i.e. InverseGamma(1.0, 1.0) - InverseGamma(a) # Inverse Gamma distribution with shape a and unit scale, i.e. InverseGamma(a, 1.0) - InverseGamma(a, b) # Inverse Gamma distribution with shape a and scale b - - params(d) # Get the parameters, i.e. (a, b) - shape(d) # Get the shape parameter, i.e. a - scale(d) # Get the scale parameter, i.e. b - -**Note:** If :math:`X \sim Gamma(\alpha, \beta)`, then :math:`1 / X \sim InverseGamma(\alpha, \beta^{-1})`. - - -.. _inversegaussian: - -Inverse Gaussian Distribution -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The probability density function of an `inverse Gaussian distribution `_ with mean :math:`\mu` and shape :math:`\lambda` is - -.. math:: - - f(x; \mu, \lambda) = \sqrt{\frac{\lambda}{2\pi x^3}} - \exp\!\left(\frac{-\lambda(x-\mu)^2}{2\mu^2x}\right), \quad x > 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 - - params(d) # Get the parameters, i.e. (mu, lambda) - mean(d) # Get the mean parameter, i.e. mu - shape(d) # Get the shape parameter, i.e. lambda - - -.. _laplace: - -Laplace Distribution -~~~~~~~~~~~~~~~~~~~~~ - -The probability density function of a `Laplace distribution `_ with location :math:`\mu` and scale :math:`\beta` is - -.. math:: - - f(x; \mu, \beta) = \frac{1}{2 \beta} \exp \left(- \frac{|x - \mu|}{\beta} \right) - -.. code-block:: julia - - Laplace() # Laplace distribution with zero location and unit scale, i.e. Laplace(0.0, 1.0) - Laplace(u) # Laplace distribution with location u and unit scale, i.e. Laplace(u, 1.0) - Laplace(u, b) # Laplace distribution with location u ans scale b - - params(d) # Get the parameters, i.e. (u, b) - location(d) # Get the location parameter, i.e. u - scale(d) # Get the scale parameter, i.e. b - - -.. _levy: - -Lévy Distribution -~~~~~~~~~~~~~~~~~~ - -The probability density function os a `Lévy distribution `_ with location :math:`\mu` and scale :math:`c` is - -.. math:: - - f(x; \mu, c) = \sqrt{\frac{c}{2 \pi (x - \mu)^3}} - \exp \left( - \frac{c}{2 (x - \mu)} \right), \quad x > \mu - -.. code-block:: julia - - Levy() # Levy distribution with zero location and unit scale, i.e. Levy(0.0, 1.0) - Levy(u) # Levy distribution with location u and unit scale, i.e. Levy(u, 1.0) - Levy(u, c) # Levy distribution with location u ans scale c - - params(d) # Get the parameters, i.e. (u, c) - location(d) # Get the location parameter, i.e. u - - -.. _logistic: - -Logistic Distribution -~~~~~~~~~~~~~~~~~~~~~~ - -The probability density function of a `Logistic distribution `_ with location :math:`\mu` and scale :math:`\beta` is - -.. math:: - - f(x; \mu, \beta) = \frac{1}{4 \beta} \mathrm{sech}^2 - \left( \frac{x - \mu}{\beta} \right) - -.. code-block:: julia - - Logistic() # Logistic distribution with zero location and unit scale, i.e. Logistic(0.0, 1.0) - Logistic(u) # Logistic distribution with location u and unit scale, i.e. Logistic(u, 1.0) - Logistic(u, b) # Logistic distribution with location u ans scale b - - params(d) # Get the parameters, i.e. (u, b) - location(d) # Get the location parameter, i.e. u - scale(d) # Get the scale parameter, i.e. b - - -.. _lognormal: - -Log-normal Distribution -~~~~~~~~~~~~~~~~~~~~~~~~ - -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}} - \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 - - params(d) # Get the parameters, i.e. (mu, sig) - meanlogx(d) # Get the mean of log(X), i.e. mu - varlogx(d) # Get the variance of log(X), i.e. sig^2 - stdlogx(d) # Get the standard deviation of log(X), i.e. sig - - -.. _normal: - -Normal Distribution -~~~~~~~~~~~~~~~~~~~~~~ - -The probability density distribution of a `Normal distribution `_ with mean :math:`\mu` and standard deviation :math:`\sigma` is - -.. math:: - - f(x; \mu, \sigma) = \frac{1}{\sqrt{2 \pi \sigma^2}} - \exp \left( - \frac{(x - \mu)^2}{2 \sigma^2} \right) - -.. code-block:: julia - - Normal() # standard Normal distribution with zero mean and unit variance - Normal(mu) # Normal distribution with mean mu and unit variance - Normal(mu, sig) # Normal distribution with mean mu and variance sig^2 - - params(d) # Get the parameters, i.e. (mu, sig) - mean(d) # Get the mean, i.e. mu - std(d) # Get the standard deviation, i.e. sig - - -.. _normalinversegaussian: - -Normal-inverse Gaussian distribution -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The probability density distribution of a `Normal-inverse Gaussian distribution `_ with location :math:`\mu`, tail heaviness :math:`\alpha`, asymmetry parameter :math:`\beta` and scale :math:`\delta` is - -.. math:: - - f(x; \mu, \alpha, \beta, \delta) = \frac{\alpha\delta K_1 \left(\alpha\sqrt{\delta^2 + (x - \mu)^2}\right)}{\pi \sqrt{\delta^2 + (x - \mu)^2}} \; e^{\delta \gamma + \beta (x - \mu)} - -:math:`K_j` denotes a modified Bessel function of the third kind. - -.. code-block:: julia - - NormalInverseGaussian(mu, alpha, beta, delta) # Normal-inverse Gaussian distribution with - # location mu, tail heaviness alpha, asymmetry - # parameter beta and scale delta - -.. _pareto: - -Pareto Distribution -~~~~~~~~~~~~~~~~~~~~~ - -The probability density function of a `Pareto distribution `_ with shape :math:`\alpha` and scale :math:`\beta` is - -.. math:: - - f(x; \alpha, \beta) = \frac{\alpha \beta^\alpha}{x^{\alpha + 1}}, \quad x \ge \beta - -.. code-block:: julia - - Pareto() # Pareto distribution with unit shape and unit scale, i.e. Pareto(1.0, 1.0) - Pareto(a) # Pareto distribution with shape a and unit scale, i.e. Pareto(a, 1.0) - Pareto(a, b) # Pareto distribution with shape a and scale b - - params(d) # Get the parameters, i.e. (a, b) - shape(d) # Get the shape parameter, i.e. a - scale(d) # Get the scale parameter, i.e. b - - -.. _rayleigh: - -Rayleigh Distribution -~~~~~~~~~~~~~~~~~~~~~~ - -The probability density function of a `Rayleigh distribution `_ with scale :math:`\sigma` is - -.. math:: - - f(x; \sigma) = \frac{x}{\sigma^2} e^{-\frac{x^2}{2 \sigma^2}} - -.. code-block:: julia - - Rayleigh() # Rayleigh distribution with unit scale, i.e. Rayleigh(1.0) - Rayleigh(s) # Rayleigh distribution with scale s - - params(d) # Get the parameters, i.e. (s,) - scale(d) # Get the scale parameter, i.e. s - - -**Note:** If :math:`X, Y \sim \mathcal{N}(\sigma^2)`, then :math:`\sqrt{X^2 + Y^2} \sim Rayleigh(\sigma)`. - - -.. _symtriangular: - -Symmetric Triangular Distribution -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The probability density function of a *Symmetric triangular distribution* with location :math:`\mu` and scale :math:`s` is - -.. math:: - - f(x; \mu, s) = \frac{1}{s} \left( 1 - \left| \frac{x - \mu}{s} \right| \right), \quad \mu - s \le x \le \mu + s - -.. code-block:: julia - - SymTriangularDist() # Symmetric triangular distribution with zero location and unit scale - SymTriangularDist(u) # Symmetric triangular distribution with location u and unit scale - SymTriangularDist(u, s) # Symmetric triangular distribution with location u and scale s - - params(d) # Get the parameters, i.e. (u, s) - location(d) # Get the location parameter, i.e. u - scale(d) # Get the scale parameter, i.e. s - - -.. _tdist: - -(Student's) T-Distribution -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The probability density function of a `Students T distribution `_ with :math:`d` degrees of freedom is - -.. math:: - - f(x; d) = \frac{1}{\sqrt{d} B(1/2, d/2)} - \left( 1 + \frac{x^2}{d} \right)^{-\frac{d + 1}{2}} - -.. code-block:: julia - - TDist(d) # t-distribution with d degrees of freedom - - params(d) # Get the parameters, i.e. (d,) - dof(d) # Get the degrees of freedom, i.e. d - - -.. _triangular: - -Triangular Distribution -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The probability density function of a `Triangular 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] - \frac{2(b-x)}{(b-a)(b-c)} & \mathrm{for\ } c < x \le b, \\[4pt] - 0 & \mathrm{for\ } b < x, - \end{cases} - -.. code-block:: julia - - TriangularDist(a, b) # Triangular distribution with lower limit a, upper limit b, and mode (a+b)/2 - TriangularDist(a, b, c) # Triangular distribution with lower limit a, upper limit b, and mode c - - params(d) # Get the parameters, i.e. (a, b, c) - minimum(d) # Get the lower bound, i.e. a - maximum(d) # Get the upper bound, i.e. b - mode(d) # Get the mode, i.e. c - - -.. _uniform: - -Uniform Distribution -~~~~~~~~~~~~~~~~~~~~~~~ - -The probability density function of a `Continuous Uniform distribution `_ over an interval :math:`[a, b]` is - -.. math:: - - f(x; a, b) = \frac{1}{b - a}, \quad a \le x \le b - -.. code-block:: julia - - Uniform() # Uniform distribution over [0, 1] - Uniform(a, b) # Uniform distribution over [a, b] - - params(d) # Get the parameters, i.e. (a, b) - minimum(d) # Get the lower bound, i.e. a - maximum(d) # Get the upper bound, i.e. b - location(d) # Get the location parameter, i.e. a - scale(d) # Get the scale parameter, i.e. b - a - - -.. _vonmises: - -Von Mises Distribution -~~~~~~~~~~~~~~~~~~~~~~~ - -The probability density function of a `von Mises distribution `_ with mean μ and concentration κ is - -.. math:: - - f(x; \mu, \kappa) = \frac{1}{2 \pi I_0(\kappa)} \exp \left( \kappa \cos (x - \mu) \right) - -.. code-block:: julia - - VonMises() # von Mises distribution with zero mean and unit concentration - VonMises(κ) # von Mises distribution with zero mean and concentration κ - VonMises(μ, κ) # von Mises distribution with mean μ and concentration κ - - -.. _weibull: - -Weibull Distribution -~~~~~~~~~~~~~~~~~~~~~ - -The probability density function of a `Weibull distribution `_ with shape :math:`\alpha` and scale :math:`\beta` is - -.. math:: - - f(x; \alpha, \beta) = \frac{\alpha}{\beta} \left( \frac{x}{\beta} \right)^{\alpha-1} e^{-(x/\beta)^\alpha}, - \quad x \ge 0 - -.. code-block:: julia - - Weibull() # Weibull distribution with unit shape and unit scale, i.e. Weibull(1.0, 1.0) - Weibull(a) # Weibull distribution with shape a and unit scale, i.e. Weibull(a, 1.0) - Weibull(a, b) # Weibull distribution with shape a and scale b - - params(d) # Get the parameters, i.e. (a, b) - shape(d) # Get the shape parameter, i.e. a - scale(d) # Get the scale parameter, i.e. b diff --git a/src/univariate/continuous/arcsine.jl b/src/univariate/continuous/arcsine.jl index 212a67f87..49d10640e 100644 --- a/src/univariate/continuous/arcsine.jl +++ b/src/univariate/continuous/arcsine.jl @@ -1,3 +1,27 @@ +doc""" + Arcsine(a,b) + +The *Arcsine distribution* has probability density function + +$f(x) = \frac{1}{\pi \sqrt{(x - a) (b - x)}}, \quad x \in [a, b]$ + +```julia +Arcsine() # Arcsine distribution with support [0, 1] +Arcsine(b) # Arcsine distribution with support [0, b] +Arcsine(a, b) # Arcsine distribution with support [a, b] + +params(d) # Get the parameters, i.e. (a, b) +minimum(d) # Get the lower bound, i.e. a +maximum(d) # Get the upper bound, i.e. b +location(d) # Get the left bound, i.e. a +scale(d) # Get the span of the support, i.e. b - a +``` + +External links + +* [Arcsine distribution on Wikipedia](http://en.wikipedia.org/wiki/Arcsine_distribution) + +""" immutable Arcsine <: ContinuousUnivariateDistribution a::Float64 b::Float64 diff --git a/src/univariate/continuous/beta.jl b/src/univariate/continuous/beta.jl index dfce68a81..93261bf7f 100644 --- a/src/univariate/continuous/beta.jl +++ b/src/univariate/continuous/beta.jl @@ -1,3 +1,29 @@ +doc""" + Beta(α,β) + +The *Beta distribution* has probability density function + +$f(x; \alpha, \beta) = \frac{1}{B(\alpha, \beta)} + x^{\alpha - 1} (1 - x)^{\beta - 1}, \quad x \in [0, 1]$ + +The Beta distribution is related to the [`Gamma`](:func:`Gamma`) distribution via the +property that if $X \sim \operatorname{Gamma}(\alpha)$ and $Y \sim \operatorname{Gamma} +(\beta)$ independently, then $X / (X + Y) \sim \operatorname{Beta}(\alpha, \beta)$. + + +```julia +Beta() # equivalent to Beta(1.0, 1.0) +Beta(a) # equivalent to Beta(a, a) +Beta(a, b) # Beta distribution with shape parameters a and b + +params(d) # Get the parameters, i.e. (a, b) +``` + +External links + +* [Beta distribution on Wikipedia](http://en.wikipedia.org/wiki/Beta_distribution) + +""" immutable Beta <: ContinuousUnivariateDistribution α::Float64 β::Float64 diff --git a/src/univariate/continuous/betaprime.jl b/src/univariate/continuous/betaprime.jl index 47e0f19ae..c45bdf964 100644 --- a/src/univariate/continuous/betaprime.jl +++ b/src/univariate/continuous/betaprime.jl @@ -1,3 +1,29 @@ +doc""" + BetaPrime(α,β) + +The *Beta prime distribution* has probability density function + +$f(x; \alpha, \beta) = \frac{1}{B(\alpha, \beta)} +x^{\alpha - 1} (1 + x)^{- (\alpha + \beta)}, \quad x > 0$ + + +The Beta prime distribution is related to the [`Beta`](:func:`Beta`) distribution via the +relation ship that if $X \sim \operatorname{Beta}(\alpha, \beta)$ then $\frac{X}{1 - X} +\sim \operatorname{BetaPrime}(\alpha, \beta)$ + +```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) +``` + +External links + +* [Beta prime distribution on Wikipedia](http://en.wikipedia.org/wiki/Beta_prime_distribution) + + """ immutable BetaPrime <: ContinuousUnivariateDistribution α::Float64 β::Float64 diff --git a/src/univariate/continuous/cauchy.jl b/src/univariate/continuous/cauchy.jl index 129244476..155845380 100644 --- a/src/univariate/continuous/cauchy.jl +++ b/src/univariate/continuous/cauchy.jl @@ -1,3 +1,25 @@ +doc""" + Cauchy(μ, σ) + +The *Cauchy distribution* with location `μ` and scale `σ` has probability density function + +$f(x; \mu, \sigma) = \frac{1}{\pi \sigma \left(1 + \left(\frac{x - \mu}{\sigma} \right)^2 \right)}$ + +```julia +Cauchy() # Standard Cauchy distribution, i.e. Cauchy(0.0, 1.0) +Cauchy(u) # Cauchy distribution with location u and unit scale, i.e. Cauchy(u, 1.0) +Cauchy(u, b) # Cauchy distribution with location u and scale b + +params(d) # Get the parameters, i.e. (u, b) +location(d) # Get the location parameter, i.e. u +scale(d) # Get the scale parameter, i.e. b +``` + +External links + +* [Cauchy distribution on Wikipedia](http://en.wikipedia.org/wiki/Cauchy_distribution) + +""" immutable Cauchy <: ContinuousUnivariateDistribution μ::Float64 σ::Float64 diff --git a/src/univariate/continuous/chi.jl b/src/univariate/continuous/chi.jl index cdd3bd4bd..7419048bd 100644 --- a/src/univariate/continuous/chi.jl +++ b/src/univariate/continuous/chi.jl @@ -1,3 +1,24 @@ +doc""" + Chi(ν) + +The *Chi distribution* `ν` degrees of freedom has probability density function + +$f(x; k) = \frac{1}{\Gamma(k/2)} 2^{1 - k/2} x^{k-1} e^{-x^2/2}, \quad x > 0$ + +It is the distribution of the square-root of a [`Chisq`](:func:`Chisq`) variate. + +```julia +Chi(k) # Chi distribution with k degrees of freedom + +params(d) # Get the parameters, i.e. (k,) +dof(d) # Get the degrees of freedom, i.e. k +``` + +External links + +* [Chi distribution on Wikipedia](http://en.wikipedia.org/wiki/Chi_distribution) + +""" immutable Chi <: ContinuousUnivariateDistribution ν::Float64 diff --git a/src/univariate/continuous/chisq.jl b/src/univariate/continuous/chisq.jl index d56eff73b..a9af7ec27 100644 --- a/src/univariate/continuous/chisq.jl +++ b/src/univariate/continuous/chisq.jl @@ -1,3 +1,25 @@ +doc""" + Chisq(ν) + +The *Chi squared distribution* (typically written χ²) with `ν` degrees of freedom has the +probability density function + +$f(x; k) = \frac{x^{k/2 - 1} e^{-x/2}}{2^{k/2} \Gamma(k/2)}, \quad x > 0.$ + +If `ν` is an integer, then it is the distribution of the sum of squares of `ν` independent standard [`Normal`](:func:`Normal`) variates. + +```julia +Chisq(k) # Chi-squared distribution with k degrees of freedom + +params(d) # Get the parameters, i.e. (k,) +dof(d) # Get the degrees of freedom, i.e. k +``` + +External links + +* [Chi-squared distribution on Wikipedia](http://en.wikipedia.org/wiki/Chi-squared_distribution) + +""" immutable Chisq <: ContinuousUnivariateDistribution ν::Float64 diff --git a/src/univariate/continuous/erlang.jl b/src/univariate/continuous/erlang.jl index 07937088f..ca00f950f 100644 --- a/src/univariate/continuous/erlang.jl +++ b/src/univariate/continuous/erlang.jl @@ -1,3 +1,19 @@ +doc""" + Erlang(α,θ) + +The *Erlang distribution* is a special case of a [`Gamma`](:func:`Gamma`) distribution with integer shape parameter. + +```julia +Erlang() # Erlang distribution with unit shape and unit scale, i.e. Erlang(1.0, 1.0) +Erlang(a) # Erlang distribution with shape parameter a and unit scale, i.e. Erlang(a, 1.0) +Erlang(a, s) # Erlang distribution with shape parameter a and scale b +``` + +External links + +* [Erlang distribution on Wikipedia](http://en.wikipedia.org/wiki/Erlang_distribution) + +""" immutable Erlang <: ContinuousUnivariateDistribution α::Int θ::Float64 diff --git a/src/univariate/continuous/exponential.jl b/src/univariate/continuous/exponential.jl index 76d1ce788..e2ffdf613 100644 --- a/src/univariate/continuous/exponential.jl +++ b/src/univariate/continuous/exponential.jl @@ -1,3 +1,24 @@ +doc""" + Exponential(θ) + +The *Exponential distribution* with scale parameter `θ` has probability density function + +$f(x; \theta) = \frac{1}{\theta} e^{-\frac{x}{\theta}}, \quad x > 0$ + +```julia +Exponential() # Exponential distribution with unit scale, i.e. Exponential(1.0) +Exponential(b) # Exponential distribution with scale b + +params(d) # Get the parameters, i.e. (b,) +scale(d) # Get the scale parameter, i.e. b +rate(d) # Get the rate parameter, i.e. 1 / b +``` + +External links + +* [Exponential distribution on Wikipedia](http://en.wikipedia.org/wiki/Exponential_distribution) + +""" immutable Exponential <: ContinuousUnivariateDistribution θ::Float64 # note: scale not rate diff --git a/src/univariate/continuous/fdist.jl b/src/univariate/continuous/fdist.jl index 79630108e..a128f8140 100644 --- a/src/univariate/continuous/fdist.jl +++ b/src/univariate/continuous/fdist.jl @@ -1,3 +1,27 @@ +doc""" + FDist(ν1,ν2) + +The *F distribution* has probability density function + +$f(x; \nu_1, \nu_2) = \frac{1}{x B(\nu_1/2, \nu_2/2)} +\sqrt{\frac{(\nu_1 x)^{\nu_1} \cdot \nu_2^{\nu_2}}{(\nu_1 x + \nu_2)^{\nu_1 + \nu_2}}}, +\quad x>0$ + +It is related to the [`Chisq`](:func:`Chisq`) distribution via the property that if $X_1 +\sim \operatorname{Chisq}(\nu_1)$ and $X_2 \sim \operatorname{Chisq}(\nu_2)$, then +$(X_1/\nu_1) / (X_2 / \nu_2) \sim FDist(\nu_1, \nu_2)`. + + +```julia +FDist(d1, d2) # F-Distribution with parameters d1 and d2 + +params(d) # Get the parameters, i.e. (d1, d2) +``` + +External links + +* [F distribution on Wikipedia](http://en.wikipedia.org/wiki/F-distribution) + """ immutable FDist <: ContinuousUnivariateDistribution ν1::Float64 ν2::Float64 diff --git a/src/univariate/continuous/frechet.jl b/src/univariate/continuous/frechet.jl index 4336c0da5..571cfa248 100644 --- a/src/univariate/continuous/frechet.jl +++ b/src/univariate/continuous/frechet.jl @@ -1,3 +1,26 @@ +doc""" + Frechet(α,θ) + +The *Fréchet distribution* with shape `α` and scale `θ` has probability density function + +$f(x; \alpha, \theta) = \frac{\alpha}{\theta} \left( \frac{x}{\theta} \right)^{-\alpha-1} +e^{-(x/\theta)^{-\alpha}}, \quad x > 0$ + +```julia +Frechet() # Fréchet distribution with unit shape and unit scale, i.e. Frechet(1.0, 1.0) +Frechet(a) # Fréchet distribution with shape a and unit scale, i.e. Frechet(a, 1.0) +Frechet(a, b) # Fréchet distribution with shape a and scale b + +params(d) # Get the parameters, i.e. (a, b) +shape(d) # Get the shape parameter, i.e. a +scale(d) # Get the scale parameter, i.e. b +``` + +External links + +* [Fréchet_distribution on Wikipedia](http://en.wikipedia.org/wiki/Fréchet_distribution) + +""" immutable Frechet <: ContinuousUnivariateDistribution α::Float64 θ::Float64 diff --git a/src/univariate/continuous/gamma.jl b/src/univariate/continuous/gamma.jl index 13cd0dda3..f1d32718e 100644 --- a/src/univariate/continuous/gamma.jl +++ b/src/univariate/continuous/gamma.jl @@ -1,3 +1,27 @@ +doc""" + Gamma(α,θ) + +The *Gamma distribution* with shape parameter `α` and scale `θ` has probability density +function + +$f(x; \alpha, \beta) = \frac{x^{\alpha-1} e^{-x/\beta}}{\Gamma(\alpha) \beta^\alpha}, +\quad x > 0$ + +```julia +Gamma() # Gamma distribution with unit shape and unit scale, i.e. Gamma(1.0, 1.0) +Gamma(a) # Gamma distribution with shape a and unit scale, i.e. Gamma(a, 1.0) +Gamma(a, b) # Gamma distribution with shape a and scale b + +params(d) # Get the parameters, i.e. (a, b) +shape(d) # Get the shape parameter, i.e. a +scale(d) # Get the scale parameter, i.e. b +``` + +External links + +* [Gamma distribution on Wikipedia](http://en.wikipedia.org/wiki/Gamma_distribution) + +""" immutable Gamma <: ContinuousUnivariateDistribution α::Float64 θ::Float64 diff --git a/src/univariate/continuous/generalizedextremevalue.jl b/src/univariate/continuous/generalizedextremevalue.jl index 12bf0bd70..422940a9a 100644 --- a/src/univariate/continuous/generalizedextremevalue.jl +++ b/src/univariate/continuous/generalizedextremevalue.jl @@ -1,3 +1,35 @@ +doc""" + GeneralizedExtremeValue(μ, σ, ξ) + +The *Generalized extreme value distribution* with shape parameter `ξ`, scale `σ` and location `μ` has probability density function + +$f(x; \xi, \sigma, \mu) = \begin{cases} + \frac{1}{\sigma} \left[ 1+\left(\frac{x-\mu}{\sigma}\right)\xi\right]^{-1/\xi-1} \exp\left\{-\left[ 1+ \left(\frac{x-\mu}{\sigma}\right)\xi\right]^{-1/\xi} \right\} & \text{for } \xi \neq 0 \\ + \frac{1}{\sigma} \exp\left\{-\frac{x-\mu}{\sigma}\right\} \exp\left\{-\exp\left[-\frac{x-\mu}{\sigma}\right]\right\} & \text{for } \xi = 0 + \end{cases}$ + +for + +$x \in \begin{cases} + \left[ \mu - \frac{\sigma}{\xi}, + \infty \right) & \text{for } \xi > 0 \\ + \left( - \infty, + \infty \right) & \text{for } \xi = 0 \\ + \left( - \infty, \mu - \frac{\sigma}{\xi} \right] & \text{for } \xi < 0 + \end{cases}$ + +```julia +GeneralizedExtremeValue(k, s, m) # Generalized Pareto distribution with shape k, scale s and location m. + +params(d) # Get the parameters, i.e. (k, s, m) +shape(d) # Get the shape parameter, i.e. k (sometimes called c) +scale(d) # Get the scale parameter, i.e. s +location(d) # Get the location parameter, i.e. m +``` + +External links + +* [Generalized extreme value distribution on Wikipedia](https://en.wikipedia.org/wiki/Generalized_extreme_value_distribution) + +""" immutable GeneralizedExtremeValue <: ContinuousUnivariateDistribution μ::Float64 σ::Float64 diff --git a/src/univariate/continuous/generalizedpareto.jl b/src/univariate/continuous/generalizedpareto.jl index a1c861201..d81a7c363 100644 --- a/src/univariate/continuous/generalizedpareto.jl +++ b/src/univariate/continuous/generalizedpareto.jl @@ -1,3 +1,35 @@ +doc""" + GeneralizedPareto(ξ, σ, μ) + +The *Generalized Pareto distribution* with shape parameter `ξ`, scale `σ` and location `μ` has probability density function + +$f(x; \xi, \sigma, \mu) = \begin{cases} + \frac{1}{\sigma}(1 + \xi \frac{x - \mu}{\sigma} )^{-\frac{1}{\xi} - 1} & \text{for } \xi \neq 0 \\ + \frac{1}{\sigma} e^{-\frac{\left( x - \mu \right) }{\sigma}} & \text{for } \xi = 0 + \end{cases}~, + \quad x \in \begin{cases} + \left[ \mu, \infty \right] & \text{for } \xi \geq 0 \\ + \left[ \mu, \mu - \sigma / \xi \right] & \text{for } \xi < 0 + \end{cases}$ + + +```julia +GeneralizedPareto() # Generalized Pareto distribution with unit shape and unit scale, i.e. GeneralizedPareto(1.0, 1.0, 0.0) +GeneralizedPareto(k, s) # Generalized Pareto distribution with shape k and scale s, i.e. GeneralizedPareto(k, s, 0.0) +GeneralizedPareto(k, s, m) # Generalized Pareto distribution with shape k, scale s and location m. + +params(d) # Get the parameters, i.e. (k, s, m) +shape(d) # Get the shape parameter, i.e. k +scale(d) # Get the scale parameter, i.e. s +location(d) # Get the location parameter, i.e. m +``` + +External links + +* [Generalized Pareto distribution on Wikipedia](https://en.wikipedia.org/wiki/Generalized_Pareto_distribution) + +""" + immutable GeneralizedPareto <: ContinuousUnivariateDistribution ξ::Float64 σ::Float64 diff --git a/src/univariate/continuous/gumbel.jl b/src/univariate/continuous/gumbel.jl index cc8ad5105..630845a84 100644 --- a/src/univariate/continuous/gumbel.jl +++ b/src/univariate/continuous/gumbel.jl @@ -1,3 +1,25 @@ +doc""" + Gumbel(μ, θ) + +The *Gumbel distribution* with location `μ` and scale `θ` has probability density function + +$f(x; \mu, \theta) = \frac{1}{\theta} e^{-(z + e^z)}, +\quad \text{ with } z = \frac{x - \mu}{\theta}$ + +```julia +Gumbel() # Gumbel distribution with zero location and unit scale, i.e. Gumbel(0.0, 1.0) +Gumbel(u) # Gumbel distribution with location u and unit scale, i.e. Gumbel(u, 1.0) +Gumbel(u, b) # Gumbel distribution with location u and scale b + +params(d) # Get the parameters, i.e. (u, b) +location(d) # Get the location parameter, i.e. u +scale(d) # Get the scale parameter, i.e. b +``` + +External links + +* [Gumbel distribution on Wikipedia](http://en.wikipedia.org/wiki/Gumbel_distribution) +""" immutable Gumbel <: ContinuousUnivariateDistribution μ::Float64 # location θ::Float64 # scale diff --git a/src/univariate/continuous/inversegamma.jl b/src/univariate/continuous/inversegamma.jl index 2d752876f..b55a0a51e 100644 --- a/src/univariate/continuous/inversegamma.jl +++ b/src/univariate/continuous/inversegamma.jl @@ -1,3 +1,29 @@ +doc""" + InverseGamma(α, θ) + +The *inverse gamma distribution* with shape parameter `α` and scale `θ` has probability +density function + +$f(x; \alpha, \theta) = \frac{\theta^\alpha x^{-(\alpha + 1)}}{\Gamma(\alpha)} +e^{-\frac{\theta}{x}}, \quad x > 0$ + +It is related to the [`Gamma`](:func:`Gamma`) distribution: if $X \sim \operatorname{Gamma}(\alpha, \beta)$, then $1 / X \sim \operatorname{InverseGamma}(\alpha, \beta^{-1})$. + +.. code-block:: julia + + InverseGamma() # Inverse Gamma distribution with unit shape and unit scale, i.e. InverseGamma(1.0, 1.0) + InverseGamma(a) # Inverse Gamma distribution with shape a and unit scale, i.e. InverseGamma(a, 1.0) + InverseGamma(a, b) # Inverse Gamma distribution with shape a and scale b + + params(d) # Get the parameters, i.e. (a, b) + shape(d) # Get the shape parameter, i.e. a + scale(d) # Get the scale parameter, i.e. b + +External links + +* [Inverse gamma distribution on Wikipedia](http://en.wikipedia.org/wiki/Inverse-gamma_distribution) + +""" immutable InverseGamma <: ContinuousUnivariateDistribution invd::Gamma θ::Float64 diff --git a/src/univariate/continuous/inversegaussian.jl b/src/univariate/continuous/inversegaussian.jl index 0eed7918b..cc9c29e37 100644 --- a/src/univariate/continuous/inversegaussian.jl +++ b/src/univariate/continuous/inversegaussian.jl @@ -1,3 +1,26 @@ +doc""" + InverseGaussian(μ,λ) + +The *inverse Gaussian distribution* with mean `μ` and shape `λ` has probability density function + +$f(x; \mu, \lambda) = \sqrt{\frac{\lambda}{2\pi x^3}} +\exp\!\left(\frac{-\lambda(x-\mu)^2}{2\mu^2x}\right), \quad x > 0$ + +```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 + +params(d) # Get the parameters, i.e. (mu, lambda) +mean(d) # Get the mean parameter, i.e. mu +shape(d) # Get the shape parameter, i.e. lambda +``` + +External links + +* [Inverse Gaussian distribution on Wikipedia](http://en.wikipedia.org/wiki/Inverse_Gaussian_distribution) + +""" immutable InverseGaussian <: ContinuousUnivariateDistribution μ::Float64 λ::Float64 diff --git a/src/univariate/continuous/laplace.jl b/src/univariate/continuous/laplace.jl index 1e0fbbcf4..ed29a1b50 100644 --- a/src/univariate/continuous/laplace.jl +++ b/src/univariate/continuous/laplace.jl @@ -1,3 +1,25 @@ +doc""" + Laplace(μ,θ) + +The *Laplace distribution* with location `μ` and scale `θ` has probability density function + +$f(x; \mu, \beta) = \frac{1}{2 \beta} \exp \left(- \frac{|x - \mu|}{\beta} \right)$ + +```julia +Laplace() # Laplace distribution with zero location and unit scale, i.e. Laplace(0.0, 1.0) +Laplace(u) # Laplace distribution with location u and unit scale, i.e. Laplace(u, 1.0) +Laplace(u, b) # Laplace distribution with location u ans scale b + +params(d) # Get the parameters, i.e. (u, b) +location(d) # Get the location parameter, i.e. u +scale(d) # Get the scale parameter, i.e. b +``` + +External links + +* [Laplace distribution on Wikipedia](http://en.wikipedia.org/wiki/Laplace_distribution) + +""" immutable Laplace <: ContinuousUnivariateDistribution μ::Float64 θ::Float64 diff --git a/src/univariate/continuous/levy.jl b/src/univariate/continuous/levy.jl index dab2519ac..e2264837f 100644 --- a/src/univariate/continuous/levy.jl +++ b/src/univariate/continuous/levy.jl @@ -1,3 +1,24 @@ +doc""" + Levy(μ, σ) + +The *Lévy distribution* with location `μ` and scale `σ` has probability density function + +$f(x; \mu, \sigma) = \sqrt{\frac{\sigma}{2 \pi (x - \mu)^3}} +\exp \left( - \frac{\sigma}{2 (x - \mu)} \right), \quad x > \mu$ + +```julia +Levy() # Levy distribution with zero location and unit scale, i.e. Levy(0.0, 1.0) +Levy(u) # Levy distribution with location u and unit scale, i.e. Levy(u, 1.0) +Levy(u, c) # Levy distribution with location u ans scale c + +params(d) # Get the parameters, i.e. (u, c) +location(d) # Get the location parameter, i.e. u +``` + +External links + +* [Lévy distribution on Wikipedia](http://en.wikipedia.org/wiki/Lévy_distribution) +""" immutable Levy <: ContinuousUnivariateDistribution μ::Float64 σ::Float64 diff --git a/src/univariate/continuous/logistic.jl b/src/univariate/continuous/logistic.jl index 6b784b0f1..ddc2d6d19 100644 --- a/src/univariate/continuous/logistic.jl +++ b/src/univariate/continuous/logistic.jl @@ -1,3 +1,26 @@ +doc""" + Logistic(μ,θ) + +The *Logistic distribution* with location `μ` and scale `θ` has probability density function + +$f(x; \mu, \theta) = \frac{1}{4 \theta} \mathrm{sech}^2 +\left( \frac{x - \mu}{\theta} \right)$ + +```julia +Logistic() # Logistic distribution with zero location and unit scale, i.e. Logistic(0.0, 1.0) +Logistic(u) # Logistic distribution with location u and unit scale, i.e. Logistic(u, 1.0) +Logistic(u, b) # Logistic distribution with location u ans scale b + +params(d) # Get the parameters, i.e. (u, b) +location(d) # Get the location parameter, i.e. u +scale(d) # Get the scale parameter, i.e. b +``` + +External links + +* [Logistic distribution on Wikipedia](http://en.wikipedia.org/wiki/Logistic_distribution) + +""" immutable Logistic <: ContinuousUnivariateDistribution μ::Float64 θ::Float64 diff --git a/src/univariate/continuous/lognormal.jl b/src/univariate/continuous/lognormal.jl index a5f210380..1e4acb0ea 100644 --- a/src/univariate/continuous/lognormal.jl +++ b/src/univariate/continuous/lognormal.jl @@ -1,3 +1,28 @@ +doc""" + LogNormal(μ,σ) + +The *log normal distribution* is the distribution of the exponential of a [`Normal`](:func:`Normal`) variate: if $X \sim \operatorname{Normal}(\mu, \sigma)$ then $\exp(X) \sim \operatorname{LogNormal}(\mu,\sigma)$. The probability density function is + +$f(x; \mu, \sigma) = \frac{1}{x \sqrt{2 \pi \sigma^2}} +\exp \left( - \frac{(\log(x) - \mu)^2}{2 \sigma^2} \right), +\quad x > 0$ + +```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 + +params(d) # Get the parameters, i.e. (mu, sig) +meanlogx(d) # Get the mean of log(X), i.e. mu +varlogx(d) # Get the variance of log(X), i.e. sig^2 +stdlogx(d) # Get the standard deviation of log(X), i.e. sig +``` + +External links + +* [Log normal distribution on Wikipedia](http://en.wikipedia.org/wiki/Log-normal_distribution) + +""" immutable LogNormal <: ContinuousUnivariateDistribution μ::Float64 σ::Float64 diff --git a/src/univariate/continuous/normal.jl b/src/univariate/continuous/normal.jl index 901728be4..003e32f37 100644 --- a/src/univariate/continuous/normal.jl +++ b/src/univariate/continuous/normal.jl @@ -1,3 +1,26 @@ +doc""" + Normal(μ,σ) + +The *Normal distribution* with mean `μ` and standard deviation `σ` has probability density function + +$f(x; \mu, \sigma) = \frac{1}{\sqrt{2 \pi \sigma^2}} +\exp \left( - \frac{(x - \mu)^2}{2 \sigma^2} \right)$ + +```julia +Normal() # standard Normal distribution with zero mean and unit variance +Normal(mu) # Normal distribution with mean mu and unit variance +Normal(mu, sig) # Normal distribution with mean mu and variance sig^2 + +params(d) # Get the parameters, i.e. (mu, sig) +mean(d) # Get the mean, i.e. mu +std(d) # Get the standard deviation, i.e. sig +``` + +External links + +* [Normal distribution on Wikipedia](http://en.wikipedia.org/wiki/Normal_distribution) + +""" immutable Normal <: ContinuousUnivariateDistribution μ::Float64 σ::Float64 diff --git a/src/univariate/continuous/normalinversegaussian.jl b/src/univariate/continuous/normalinversegaussian.jl index cd3f88be7..de47e4b73 100644 --- a/src/univariate/continuous/normalinversegaussian.jl +++ b/src/univariate/continuous/normalinversegaussian.jl @@ -1,3 +1,18 @@ +doc""" + NormalInverseGaussian(μ,α,β,δ) + +The *Normal-inverse Gaussian distribution* with location `μ`, tail heaviness `α`, asymmetry parameter `β` and scale `δ` has probability density function + +$f(x; \mu, \alpha, \beta, \delta) = \frac{\alpha\delta K_1 \left(\alpha\sqrt{\delta^2 + (x - \mu)^2}\right)}{\pi \sqrt{\delta^2 + (x - \mu)^2}} \; e^{\delta \gamma + \beta (x - \mu)}$ + +where $K_j$ denotes a modified Bessel function of the third kind. + + +External links + +* [Normal-inverse Gaussian distribution on Wikipedia](http://en.wikipedia.org/wiki/Normal-inverse_Gaussian_distribution) + +""" immutable NormalInverseGaussian <: ContinuousUnivariateDistribution μ::Float64 α::Float64 diff --git a/src/univariate/continuous/pareto.jl b/src/univariate/continuous/pareto.jl index d67b3015f..eb0822b72 100644 --- a/src/univariate/continuous/pareto.jl +++ b/src/univariate/continuous/pareto.jl @@ -1,3 +1,24 @@ +doc""" + Pareto(α,θ) + +The *Pareto distribution* with shape `α` and scale `θ` has probability density function + +$f(x; \alpha, \theta) = \frac{\alpha \theta^\alpha}{x^{\alpha + 1}}, \quad x \ge \theta$ + +```julia +Pareto() # Pareto distribution with unit shape and unit scale, i.e. Pareto(1.0, 1.0) +Pareto(a) # Pareto distribution with shape a and unit scale, i.e. Pareto(a, 1.0) +Pareto(a, b) # Pareto distribution with shape a and scale b + +params(d) # Get the parameters, i.e. (a, b) +shape(d) # Get the shape parameter, i.e. a +scale(d) # Get the scale parameter, i.e. b +``` + +External links + * [Pareto distribution on Wikipedia](http://en.wikipedia.org/wiki/Pareto_distribution) + +""" immutable Pareto <: ContinuousUnivariateDistribution α::Float64 θ::Float64 diff --git a/src/univariate/continuous/rayleigh.jl b/src/univariate/continuous/rayleigh.jl index 9f7481e43..d2d595496 100644 --- a/src/univariate/continuous/rayleigh.jl +++ b/src/univariate/continuous/rayleigh.jl @@ -1,3 +1,25 @@ +doc""" + Rayleigh(σ) + +The *Rayleigh distribution* with scale `σ` has probability density function + +$f(x; \sigma) = \frac{x}{\sigma^2} e^{-\frac{x^2}{2 \sigma^2}}, \quad x > 0$ + +It is related to the [`Normal`](:func:`Normal`) distribution via the property that if $X, Y \sim \operatorname{Normal}(0,\sigma)$, independently, then $\sqrt{X^2 + Y^2} \sim \operatorname{Rayleigh}(\sigma)$. + +```julia +Rayleigh() # Rayleigh distribution with unit scale, i.e. Rayleigh(1.0) +Rayleigh(s) # Rayleigh distribution with scale s + +params(d) # Get the parameters, i.e. (s,) +scale(d) # Get the scale parameter, i.e. s +``` + +External links + +* [Rayleigh distribution on Wikipedia](http://en.wikipedia.org/wiki/Rayleigh_distribution) + +""" immutable Rayleigh <: ContinuousUnivariateDistribution σ::Float64 diff --git a/src/univariate/continuous/symtriangular.jl b/src/univariate/continuous/symtriangular.jl index e58b6e770..26c9f9e78 100644 --- a/src/univariate/continuous/symtriangular.jl +++ b/src/univariate/continuous/symtriangular.jl @@ -1,3 +1,20 @@ +doc""" + SymTriangularDist(μ,σ) + +The *Symmetric triangular distribution* with location `μ` and scale `σ` has probability density function + +$f(x; \mu, \sigma) = \frac{1}{\sigma} \left( 1 - \left| \frac{x - \mu}{\sigma} \right| \right), \quad \mu - \sigma \le x \le \mu + \sigma$ + +```julia +SymTriangularDist() # Symmetric triangular distribution with zero location and unit scale +SymTriangularDist(u) # Symmetric triangular distribution with location u and unit scale +SymTriangularDist(u, s) # Symmetric triangular distribution with location u and scale s + +params(d) # Get the parameters, i.e. (u, s) +location(d) # Get the location parameter, i.e. u +scale(d) # Get the scale parameter, i.e. s +``` +""" immutable SymTriangularDist <: ContinuousUnivariateDistribution μ::Float64 σ::Float64 diff --git a/src/univariate/continuous/tdist.jl b/src/univariate/continuous/tdist.jl index e3b29efac..664d1a928 100644 --- a/src/univariate/continuous/tdist.jl +++ b/src/univariate/continuous/tdist.jl @@ -1,3 +1,23 @@ +doc""" + TDist(ν) + +The *Students T distribution* with `ν` degrees of freedom has probability density function + +$f(x; d) = \frac{1}{\sqrt{d} B(1/2, d/2)} +\left( 1 + \frac{x^2}{d} \right)^{-\frac{d + 1}{2}}$ + +```julia +TDist(d) # t-distribution with d degrees of freedom + +params(d) # Get the parameters, i.e. (d,) +dof(d) # Get the degrees of freedom, i.e. d +``` + +External links + +[Student's T distribution on Wikipedia](https://en.wikipedia.org/wiki/Student%27s_t-distribution) + +""" immutable TDist <: ContinuousUnivariateDistribution ν::Float64 diff --git a/src/univariate/continuous/triangular.jl b/src/univariate/continuous/triangular.jl index f0c3e081d..cb7a497f6 100644 --- a/src/univariate/continuous/triangular.jl +++ b/src/univariate/continuous/triangular.jl @@ -1,3 +1,30 @@ +doc""" + TriangularDist(a,b,c) + +The *triangular distribution* with lower limit `a`, upper limit `b` and mode `c` has probability density function + +$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] + \frac{2(b-x)}{(b-a)(b-c)} & \mathrm{for\ } c < x \le b, \\[4pt] + 0 & \mathrm{for\ } b < x, + \end{cases}$ + +```julia +TriangularDist(a, b) # Triangular distribution with lower limit a, upper limit b, and mode (a+b)/2 +TriangularDist(a, b, c) # Triangular distribution with lower limit a, upper limit b, and mode c + +params(d) # Get the parameters, i.e. (a, b, c) +minimum(d) # Get the lower bound, i.e. a +maximum(d) # Get the upper bound, i.e. b +mode(d) # Get the mode, i.e. c +``` + +External links + +* [Triangular distribution on Wikipedia](http://en.wikipedia.org/wiki/Triangular_distribution) + +""" immutable TriangularDist <: ContinuousUnivariateDistribution a::Float64 b::Float64 diff --git a/src/univariate/continuous/uniform.jl b/src/univariate/continuous/uniform.jl index d31a1f6d1..d90455590 100644 --- a/src/univariate/continuous/uniform.jl +++ b/src/univariate/continuous/uniform.jl @@ -1,3 +1,26 @@ +doc""" + Uniform(a,b) + +The *continuous uniform distribution* over an interval $[a, b]$ has probability density function + +$f(x; a, b) = \frac{1}{b - a}, \quad a \le x \le b$ + +```julia +Uniform() # Uniform distribution over [0, 1] +Uniform(a, b) # Uniform distribution over [a, b] + +params(d) # Get the parameters, i.e. (a, b) +minimum(d) # Get the lower bound, i.e. a +maximum(d) # Get the upper bound, i.e. b +location(d) # Get the location parameter, i.e. a +scale(d) # Get the scale parameter, i.e. b - a +``` + +External links + +* [Uniform distribution (continuous) on Wikipedia](http://en.wikipedia.org/wiki/Uniform_distribution_(continuous)) + +""" immutable Uniform <: ContinuousUnivariateDistribution a::Float64 b::Float64 diff --git a/src/univariate/continuous/vonmises.jl b/src/univariate/continuous/vonmises.jl index 30f5ef23b..3514884b6 100644 --- a/src/univariate/continuous/vonmises.jl +++ b/src/univariate/continuous/vonmises.jl @@ -1,8 +1,21 @@ -# von Mises distribution -# -# Implemented based on Wikipedia -# +doc""" + VonMises(μ, κ) +The *von Mises distribution* with mean `μ` and concentration `κ` has probability density function + +$f(x; \mu, \kappa) = \frac{1}{2 \pi I_0(\kappa)} \exp \left( \kappa \cos (x - \mu) \right)$ + +```julia +VonMises() # von Mises distribution with zero mean and unit concentration +VonMises(κ) # von Mises distribution with zero mean and concentration κ +VonMises(μ, κ) # von Mises distribution with mean μ and concentration κ +``` + +External links + +* [von Mises distribution on Wikipedia](http://en.wikipedia.org/wiki/Von_Mises_distribution) + +""" immutable VonMises <: ContinuousUnivariateDistribution μ::Float64 # mean κ::Float64 # concentration diff --git a/src/univariate/continuous/weibull.jl b/src/univariate/continuous/weibull.jl index 739525602..d963c8311 100644 --- a/src/univariate/continuous/weibull.jl +++ b/src/univariate/continuous/weibull.jl @@ -1,3 +1,26 @@ +doc""" + Weibull(α,θ) + +The *Weibull distribution* with shape `α` and scale `θ` has probability density function + +$f(x; \alpha, \theta) = \frac{\alpha}{\theta} \left( \frac{x}{\theta} \right)^{\alpha-1} e^{-(x/\theta)^\alpha}, + \quad x \ge 0$ + +```julia +Weibull() # Weibull distribution with unit shape and unit scale, i.e. Weibull(1.0, 1.0) +Weibull(a) # Weibull distribution with shape a and unit scale, i.e. Weibull(a, 1.0) +Weibull(a, b) # Weibull distribution with shape a and scale b + +params(d) # Get the parameters, i.e. (a, b) +shape(d) # Get the shape parameter, i.e. a +scale(d) # Get the scale parameter, i.e. b +``` + +External links + +* [Weibull distribution on Wikipedia](http://en.wikipedia.org/wiki/Weibull_distribution) + +""" immutable Weibull <: ContinuousUnivariateDistribution α::Float64 # shape θ::Float64 # scale diff --git a/src/univariate/discrete/bernoulli.jl b/src/univariate/discrete/bernoulli.jl index 28e959066..e67b147c9 100644 --- a/src/univariate/discrete/bernoulli.jl +++ b/src/univariate/discrete/bernoulli.jl @@ -1,3 +1,27 @@ +doc""" + Bernoulli(p) + +A *Bernoulli distribution* is parameterized by a success rate `p`, which takes value 1 +with probability `p` and 0 with probability `1-p`. + +$P(X = k) = \begin{cases} +1 - p & \quad \text{for } k = 0, \\ +p & \quad \text{for } k = 1. +\end{cases}$ + +```julia +Bernoulli() # Bernoulli distribution with p = 0.5 +Bernoulli(p) # Bernoulli distribution with success rate p + +params(d) # Get the parameters, i.e. (p,) +succprob(d) # Get the success rate, i.e. p +failprob(d) # Get the failure rate, i.e. 1 - p +``` + +External links: + +* [Bernoulli distribution on Wikipedia](http://en.wikipedia.org/wiki/Bernoulli_distribution) +""" immutable Bernoulli <: DiscreteUnivariateDistribution p::Float64 diff --git a/src/univariate/discrete/betabinomial.jl b/src/univariate/discrete/betabinomial.jl index a4c037561..f1daad8ad 100644 --- a/src/univariate/discrete/betabinomial.jl +++ b/src/univariate/discrete/betabinomial.jl @@ -1,3 +1,21 @@ +doc""" + BetaBinomial(n,α,β) + +A *Beta-binomial distribution* is the compound distribution of the [`Binomial`](:func:`Binomial`) distribution where the probability of success `p` is distributed according to the [`Beta`](:func:`Beta`). It has three parameters: `n`, the number of trials and two shape parameters `α`, `β` + +$P(X = k) = {n \choose k} B(k + \alpha, n - k + \beta) / B(\alpha, \beta), \quad \text{ for } k = 0,1,2, \ldots, n.$ + +```julia +BetaBinomial(n, a, b) # BetaBinomial distribution with n trials and shape parameters a, b + +params(d) # Get the parameters, i.e. (n, a, b) +ntrials(d) # Get the number of trials, i.e. n +``` + +External links: + +* [Beta-binomial distribution on Wikipedia](https://en.wikipedia.org/wiki/Beta-binomial_distribution) +""" immutable BetaBinomial <: DiscreteUnivariateDistribution n::Int α::Float64 diff --git a/src/univariate/discrete/binomial.jl b/src/univariate/discrete/binomial.jl index 5a504d5ad..c041378cb 100644 --- a/src/univariate/discrete/binomial.jl +++ b/src/univariate/discrete/binomial.jl @@ -1,3 +1,25 @@ +doc""" + Binomial(n,p) + +A *Binomial distribution* characterizes the number of successes in a sequence of independent trials. It has two parameters: `n`, the number of trials, and `p`, the probability of success in an individual trial, with the distribution: + +$P(X = k) = {n \choose k}p^k(1-p)^{n-k}, \quad \text{ for } k = 0,1,2, \ldots, n.$ + +```julia +Binomial() # Binomial distribution with n = 1 and p = 0.5 +Binomial(n) # Binomial distribution for n trials with success rate p = 0.5 +Binomial(n, p) # Binomial distribution for n trials with success rate p + +params(d) # Get the parameters, i.e. (n, p) +ntrials(d) # Get the number of trials, i.e. n +succprob(d) # Get the success rate, i.e. p +failprob(d) # Get the failure rate, i.e. 1 - p +``` + +External links: + +* [Binomial distribution on Wikipedia](http://en.wikipedia.org/wiki/Binomial_distribution) +""" immutable Binomial <: DiscreteUnivariateDistribution n::Int p::Float64 diff --git a/src/univariate/discrete/categorical.jl b/src/univariate/discrete/categorical.jl index 5c3376ece..103ad409f 100644 --- a/src/univariate/discrete/categorical.jl +++ b/src/univariate/discrete/categorical.jl @@ -1,3 +1,27 @@ +doc""" + Categorical(p) + +A *Categorical distribution* is parameterized by a probability vector `p` (of length `K`). + +$P(X = k) = p[k] \quad \text{for } k = 1, 2, \ldots, K.$ + +```julia +Categorical(p) # Categorical distribution with probability vector p + +params(d) # Get the parameters, i.e. (p,) +probs(d) # Get the probability vector, i.e. p +ncategories(d) # Get the number of categories, i.e. K +``` + +Here, `p` must be a real vector, of which all components are nonnegative and sum to one. + +**Note:** The input vector `p` is directly used as a field of the constructed distribution, without being copied. + +External links: + +* [Categorical distribution on Wikipedia](http://en.wikipedia.org/wiki/Categorical_distribution) + +""" immutable Categorical <: DiscreteUnivariateDistribution K::Int p::Vector{Float64} diff --git a/src/univariate/discrete/discreteuniform.jl b/src/univariate/discrete/discreteuniform.jl index 45aabd3fb..7fd6fbdb7 100644 --- a/src/univariate/discrete/discreteuniform.jl +++ b/src/univariate/discrete/discreteuniform.jl @@ -1,3 +1,24 @@ +doc""" + DiscreteUniform(a,b) + +A *Discrete uniform distribution* is a uniform distribution over a consecutive sequence of integers between `a` and `b`, inclusive. + +$P(X = k) = 1 / (b - a + 1) \quad \text{for } k = a, a+1, \ldots, b.$ + +```julia +DiscreteUniform(a, b) # a uniform distribution over {a, a+1, ..., b} + +params(d) # Get the parameters, i.e. (a, b) +span(d) # Get the span of the support, i.e. (b - a + 1) +probval(d) # Get the probability value, i.e. 1 / (b - a + 1) +minimum(d) # Return a +maximum(d) # Return b +``` + +External links + +* [Discrete uniform distribution on Wikipedia](http://en.wikipedia.org/wiki/Uniform_distribution_(discrete)) +""" immutable DiscreteUniform <: DiscreteUnivariateDistribution a::Int b::Int diff --git a/src/univariate/discrete/geometric.jl b/src/univariate/discrete/geometric.jl index 6b4fa6b22..33fd5ffea 100644 --- a/src/univariate/discrete/geometric.jl +++ b/src/univariate/discrete/geometric.jl @@ -1,3 +1,24 @@ +doc""" + Geometric(p) + +A *Geometric distribution* characterizes the number of failures before the first success in a sequence of independent Bernoulli trials with success rate `p`. + +$P(X = k) = p (1 - p)^k, \quad \text{for } k = 0, 1, 2, \ldots.$ + +```julia +Geometric() # Geometric distribution with success rate 0.5 +Geometric(p) # Geometric distribution with success rate p + +params(d) # Get the parameters, i.e. (p,) +succprob(d) # Get the success rate, i.e. p +failprob(d) # Get the failure rate, i.e. 1 - p +``` + +External links + +* [Geometric distribution on Wikipedia](http://en.wikipedia.org/wiki/Geometric_distribution) + +""" immutable Geometric <: DiscreteUnivariateDistribution p::Float64 diff --git a/src/univariate/discrete/hypergeometric.jl b/src/univariate/discrete/hypergeometric.jl index ed9814327..e34dab245 100644 --- a/src/univariate/discrete/hypergeometric.jl +++ b/src/univariate/discrete/hypergeometric.jl @@ -1,11 +1,22 @@ -# Hypergeometric(ns, nf, n): -# -# Consider a population with ns successes and nf failures, and -# we draw n samples from this population without replacement, -# the number of successes within these samples follow -# a hyper-geometric distribution -# +doc""" + Hypergeometric(s, f, n) +A *Hypergeometric distribution* describes the number of successes in `n` draws without replacement from a finite population containing `s` successes and `f` failures. + +$P(X = k) = {{{s \choose k} {f \choose {n-k}}}\over {s+f \choose n}}, \quad \text{for } k = \max(0, n - f), \ldots, \min(n, s).$ + +```julia +Hypergeometric(s, f, n) # Hypergeometric distribution for a population with + # s successes and f failures, and a sequence of n trials. + +params(d) # Get the parameters, i.e. (s, f, n) +``` + +External links + +* [Hypergeometric distribution on Wikipedia](http://en.wikipedia.org/wiki/Hypergeometric_distribution) + +""" immutable Hypergeometric <: DiscreteUnivariateDistribution ns::Int # number of successes in population nf::Int # number of failures in population diff --git a/src/univariate/discrete/negativebinomial.jl b/src/univariate/discrete/negativebinomial.jl index 554bfd6c6..39b93dfc6 100644 --- a/src/univariate/discrete/negativebinomial.jl +++ b/src/univariate/discrete/negativebinomial.jl @@ -1,9 +1,29 @@ -# NegativeBinomial is the distribution of the number of failures -# before the r-th success in a sequence of Bernoulli trials. -# We do not enforce integer size, as the distribution is well defined -# for non-integers, and this can be useful for e.g. overdispersed -# discrete survival times. +doc""" + NegativeBinomial(r,p) +A *Negative binomial distribution* describes the number of failures before the `r`th success in a sequence of independent Bernoulli trials. It is parameterized by `r`, the number of successes, and `p`, the probability of success in an individual trial. + +$P(X = k) = {k + r - 1 \choose k} p^r (1 - p)^k, \quad \text{for } k = 0,1,2,\ldots.$ + +The distribution remains well-defined for any positive `r`, in which case + +$P(X = k) = \frac{\Gamma(k+r)}{k! \Gamma(r)} p^r (1 - p)^k, \quad \text{for } k = 0,1,2,\ldots.$ + + +```julia +NegativeBinomial() # Negative binomial distribution with r = 1 and p = 0.5 +NegativeBinomial(r, p) # Negative binomial distribution with r successes and success rate p + +params(d) # Get the parameters, i.e. (r, p) +succprob(d) # Get the success rate, i.e. p +failprob(d) # Get the failure rate, i.e. 1 - p +``` + +External links: + +* [Negative binomial distribution on Wikipedia](http://en.wikipedia.org/wiki/Negative_binomial_distribution) + +""" immutable NegativeBinomial <: DiscreteUnivariateDistribution r::Float64 p::Float64 diff --git a/src/univariate/discrete/poisson.jl b/src/univariate/discrete/poisson.jl index 3686b1a48..0bbbf0ba5 100644 --- a/src/univariate/discrete/poisson.jl +++ b/src/univariate/discrete/poisson.jl @@ -1,3 +1,23 @@ +doc""" + Poisson(λ) + +A *Poisson distribution* descibes the number of independent events occurring within a unit time interval, given the average rate of occurrence `λ`. + +$P(X = k) = \frac{\lambda^k}{k!} e^{-\lambda}, \quad \text{ for } k = 0,1,2,\ldots.$ + +```julia +Poisson() # Poisson distribution with rate parameter 1 +Poisson(lambda) # Poisson distribution with rate parameter lambda + +params(d) # Get the parameters, i.e. (λ,) +mean(d) # Get the mean arrival rate, i.e. λ +``` + +External links: + +* [Poisson distribution on Wikipedia](http://en.wikipedia.org/wiki/Poisson_distribution) + +""" immutable Poisson <: DiscreteUnivariateDistribution λ::Float64 diff --git a/src/univariate/discrete/poissonbinomial.jl b/src/univariate/discrete/poissonbinomial.jl index b19cf639a..63b7281dd 100644 --- a/src/univariate/discrete/poissonbinomial.jl +++ b/src/univariate/discrete/poissonbinomial.jl @@ -1,37 +1,26 @@ # TODO: this distribution may need clean-up +doc""" + PoissonBinomial(p) -# Computes the pdf of a poisson-binomial random variable using -# fast fourier transform -# -# Hong, Y. (2013). -# On computing the distribution function for the Poisson binomial -# distribution. Computational Statistics and Data Analysis, 59, 41–51. -# -function poissonbinomial_pdf_fft(p::AbstractArray) - n = length(p) - ω = 2. / (n + 1) +A *Poisson-binomial distribution* describes the number of successes in a sequence of independent trials, wherein each trial has a different success rate. It is parameterized by a vector `p` (of length ``K``), where ``K`` is the total number of trials and `p[i]` corresponds to the probability of success of the `i`th trial. - x = Array(Complex{Float64}, n+1) - lmax = ceil(Int, n/2) - x[1] = 1./(n+1) - for l=1:lmax - logz = 0. - argz = 0. - for j=1:n - zjl = 1 - p[j] + p[j] * cospi(ω*l) + im * p[j] * sinpi(ω * l) - logz += log(abs(zjl)) - argz += atan2(imag(zjl), real(zjl)) - end - dl = exp(logz) - x[l+1] = dl * cos(argz) / (n+1) + dl * sin(argz) * im / (n+1) - if n + 1 - l > l - x[n+1-l+1] = conj(x[l+1]) - end - end - fft!(x) - [max(0., real(xi)) for xi in x] -end +$P(X = k) = \sum\limits_{A\in F_k} \prod\limits_{i\in A} p[i] \prod\limits_{j\in A^c} (1-p[j]), \quad \text{ for } k = 0,1,2,\ldots,K,$ + +where $F_k$ is the set of all subsets of $k$ integers that can be selected from $\{1,2,3,...,K\}$. + +```julia +PoissonBinomial(p) # Poisson Binomial distribution with success rate vector p + +params(d) # Get the parameters, i.e. (p,) +succprob(d) # Get the vector of success rates, i.e. p +failprob(d) # Get the vector of failure rates, i.e. 1-p +``` + +External links: +* [Poisson-binomial distribution on Wikipedia](http://en.wikipedia.org/wiki/Poisson_binomial_distribution) + +""" immutable PoissonBinomial <: DiscreteUnivariateDistribution p::Vector{Float64} @@ -109,6 +98,39 @@ pdf(d::PoissonBinomial, k::Int) = insupport(d, k) ? d.pmf[k+1] : 0. logpdf(d::PoissonBinomial, k::Int) = insupport(d, k) ? log(d.pmf[k+1]) : -Inf pdf(d::PoissonBinomial) = copy(d.pmf) + +# Computes the pdf of a poisson-binomial random variable using +# fast fourier transform +# +# Hong, Y. (2013). +# On computing the distribution function for the Poisson binomial +# distribution. Computational Statistics and Data Analysis, 59, 41–51. +# +function poissonbinomial_pdf_fft(p::AbstractArray) + n = length(p) + ω = 2. / (n + 1) + + x = Array(Complex{Float64}, n+1) + lmax = ceil(Int, n/2) + x[1] = 1./(n+1) + for l=1:lmax + logz = 0. + argz = 0. + for j=1:n + zjl = 1 - p[j] + p[j] * cospi(ω*l) + im * p[j] * sinpi(ω * l) + logz += log(abs(zjl)) + argz += atan2(imag(zjl), real(zjl)) + end + dl = exp(logz) + x[l+1] = dl * cos(argz) / (n+1) + dl * sin(argz) * im / (n+1) + if n + 1 - l > l + x[n+1-l+1] = conj(x[l+1]) + end + end + fft!(x) + [max(0., real(xi)) for xi in x] +end + #### Sampling sampler(d::PoissonBinomial) = PoissBinAliasSampler(d) diff --git a/src/univariate/discrete/skellam.jl b/src/univariate/discrete/skellam.jl index afb744721..7fa85fe64 100644 --- a/src/univariate/discrete/skellam.jl +++ b/src/univariate/discrete/skellam.jl @@ -1,3 +1,23 @@ +doc""" + Skellam(μ1, μ2) + +A *Skellam distribution* describes the difference between two independent [`Poisson`](:func:`Poisson`) variables, respectively with rate `μ1` and `μ2`. + +$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$ + +where $I_k$ is the modified Bessel function of the first kind. + +```julia +Skellam(mu1, mu2) # Skellam distribution for the difference between two Poisson variables, + # respectively with expected values mu1 and mu2. + +params(d) # Get the parameters, i.e. (mu1, mu2) +``` + +External links: + +* [Skellam distribution on Wikipedia](http://en.wikipedia.org/wiki/Skellam_distribution) +""" immutable Skellam <: DiscreteUnivariateDistribution μ1::Float64 μ2::Float64