Distribution

The distribution protocol defines operations on probability distributions.
Distributions may be univariate (defined over scalars) or multivariate
(defined over vectors). Distributions may be discrete or continuous.

For a list of types that implement the protocol run (extenders Distribution).
Implementations are provided for the various Clojure collection datatypes.
See the example below for using the distribution methods on these types.

See also:
  pdf, cdf, draw, support

References:
  http://en.wikipedia.org/wiki/Probability_distribution

Examples:
  (support [1 3 4 2 1 3 4 2]) ; returns the set #{1 2 3 4}
  (draw [1 3 4 2 1 3 4 2]) ; returns a value from #{1 2 3 4}
  (pdf [2 1 2] 1) ; returns the value 1/3
(cdf [2 1 2 3] 2) ; returns the value 3/4

Usage: (cdf d v)

A function of the incanter.distribution.Distribution protocol.

Returns the value of the cumulative density function for the
distribution d at support v.

See also:
  Distribution, pdf, draw, support

References:
  http://en.wikipedia.org/wiki/Cumulative_distribution_function

Examples:
  (cdf [2 1 2 3] 2) ; returns the value 3/4 

Usage: (draw d)

A function of the incanter.distribution.Distribution protocol.

Returns a randomly drawn value from the support of distribution d.

See also:
  Distribution, pdf, cdf, support

Examples:
  (draw [1 3 4 2 1 3 4 2]) ; returns a value from #{1 2 3 4}

Usage: (mean d)

mean

Usage: (pdf d v)

A function of the incanter.distribution.Distribution protocol.

Returns the value of the probability density/mass function for the
distribution d at support v.

See also:
  Distribution, cdf, draw, support

References:
  http://en.wikipedia.org/wiki/Probability_density_function

Examples:
  (pdf [2 1 2] 1) ; returns the value 1/3

Usage: (support d)

**** EXPERIMENTAL ****
A function of the incanter.distribution.Distribution protocol.

Returns the support of the probability distribution d.
For discrete distributions, the support is a set (i.e. #{1 2 3}).
For continuous distributions, the support is a 2 element vector
describing the range. For example, the uniform distribution over
the unit interval would return the vector [0 1].

This function is marked as experimental to note that the output
format might need to adapt to more complex support structures.
For example, what would best describe a mixture of continuous
distributions?

See also:
  Distribution, pdf, draw, support

References:
  http://en.wikipedia.org/wiki/Cumulative_distribution_function

Examples:
  (cdf [2 1 2 3] 2) ; returns the value 3/4 

Usage: (variance d)

variance

Beta-rec

Binomial-rec

ChiSquare-rec

Combination

DoubleUniform-rec

Exponential-rec

F

Gamma-rec

NegativeBinomial-rec

Normal-rec

Poisson-rec

StudentT-rec

UniformInt

->Beta-rec

Usage: (->Beta-rec alpha beta)

Positional factory function for class incanter.distributions.Beta-rec.

->Binomial-rec

Usage: (->Binomial-rec n p)

Positional factory function for class incanter.distributions.Binomial-rec.

->ChiSquare-rec

Usage: (->ChiSquare-rec df)

Positional factory function for class incanter.distributions.ChiSquare-rec.

->Combination

Usage: (->Combination n k u)

Positional factory function for class incanter.distributions.Combination.

->DoubleUniform-rec

Usage: (->DoubleUniform-rec min max)

Positional factory function for class incanter.distributions.DoubleUniform-rec.

->Exponential-rec

Usage: (->Exponential-rec rate)

Positional factory function for class incanter.distributions.Exponential-rec.

->F

Usage: (->F df1 df2)

Positional factory function for class incanter.distributions.F.

->Gamma-rec

Usage: (->Gamma-rec shape scale)

Positional factory function for class incanter.distributions.Gamma-rec.

->NegativeBinomial-rec

Usage: (->NegativeBinomial-rec size prob)

Positional factory function for class incanter.distributions.NegativeBinomial-rec.

->Normal-rec

Usage: (->Normal-rec mean sd)

Positional factory function for class incanter.distributions.Normal-rec.

->Poisson-rec

Usage: (->Poisson-rec lambda)

Positional factory function for class incanter.distributions.Poisson-rec.

->StudentT-rec

Usage: (->StudentT-rec df)

Positional factory function for class incanter.distributions.StudentT-rec.

->UniformInt

Usage: (->UniformInt start end)

Positional factory function for class incanter.distributions.UniformInt.

beta-distribution

Usage: (beta-distribution)
       (beta-distribution alpha beta)

Returns a Beta distribution that implements the incanter.distributions.Distribution protocol.

Arguments:
  alpha      (default 1)
  beta       (default 1)

See also:
  Distribution, pdf, cdf, draw, support

References:
  http://incanter.org/docs/parallelcolt/api/cern/jet/random/tdouble/Beta.html
  http://en.wikipedia.org/wiki/Beta_distribution

Example:
  (pdf (beta-distribution 1 2) 0.5)

binomial-distribution

Usage: (binomial-distribution)
       (binomial-distribution n p)

Returns a Binomial distribution that implements the incanter.distributions.Distribution protocol.

Arguments:
  size       (default 1)
  prob       (default 1/2)

See also:
  Distribution, pdf, cdf, draw, support

References:
  http://incanter.org/docs/parallelcolt/api/cern/jet/random/tdouble/Binomial.html
  http://en.wikipedia.org/wiki/Binomial_distribution

Example:
  (pdf (binomial-distribution 20 1/4) 10)

chisq-distribution

Usage: (chisq-distribution)
       (chisq-distribution df)

Returns a Chi-square distribution that implements the incanter.distributions.Distribution protocol.

Arguments:
  df         (default 1)

See also:
  Distribution, pdf, cdf, draw, support

References:
  http://incanter.org/docs/parallelcolt/api/cern/jet/random/tdouble/ChiSquare.html
  http://en.wikipedia.org/wiki/Chi_square_distribution

Example:
  (pdf (chisq-distribution 2) 5.0)

combination-distribution

Usage: (combination-distribution n k)

Create a distribution of all the k-sized combinations of n integers.
Can be considered a multivariate distribution over k-dimensions, where
each dimension is a discrete random variable on the (0, n] range (though
these variables are decidedly non-independent).

A draw from this distribution can also be considered a sample without
replacement from any finite set, where the values in the returned
vector represent the indices of the items in the set.

Arguments:
  n	  The number of possible items from which to select.
  k	  The size of a sample (without replacement) to draw.

See also:
  test-statistic-distribution, integer-distribution, pdf, cdf, draw, support

References:
  http://en.wikipedia.org/wiki/Combination

exponential-distribution

Usage: (exponential-distribution)
       (exponential-distribution rate)

Returns a Exponential distribution that implements the incanter.distributions.Distribution protocol.

Arguments:
  rate       (default 1)

See also:
  Distribution, pdf, cdf, draw, support

References:
  http://incanter.org/docs/parallelcolt/api/cern/jet/random/tdouble/Exponential.html
  http://en.wikipedia.org/wiki/Exponential_distribution

Example:
  (pdf (exponential-distribution 1/2) 2.0)

f-distribution

Usage: (f-distribution)
       (f-distribution df1 df2)

Returns a F-distribution that implements the incanter.distributions.Distribution protocol.

Arguments:
  df1        (default 1)
  df2        (default 1)

See also:
  Distribution, pdf, cdf, draw, support

References:
  http://en.wikipedia.org/wiki/F_distribution
  http://mathworld.wolfram.com/F-Distribution.html

Example:
  (pdf (f-distribution 5 2) 1.0)

gamma-distribution

Usage: (gamma-distribution)
       (gamma-distribution shape scale)

Returns a Gamma distribution that implements the incanter.distributions.Distribution protocol.

Arguments:
  shape (k)  (default 1)
  scale (θ)  (default 1)

See also:
  Distribution, pdf, cdf, draw, support

References:
  http://incanter.org/docs/parallelcolt/api/cern/jet/random/tdouble/Gamma.html
  http://en.wikipedia.org/wiki/Gamma_distribution

Example:
  (pdf (gamma-distribution 1 2) 10)

integer-distribution

Usage: (integer-distribution)
       (integer-distribution end)
       (integer-distribution start end)

Create a uniform distribution over a set of integers over
the (start, end] interval. An alternative method of creating
a distribution would be to just use a sequence of integers
(e.g. (draw (range 100000))). For large sequences, like the one
in the example, using a sequence will be require realizing the
entire sequence before a draw can be taken. This less efficient than
computing random draws based on the end points of the distribution.

Arguments:
start	The lowest end of the interval, such that (>= (draw d) start)
      is always true. (Default 0)
  end	The value at the upper end of the interval, such that
        (> end (draw d)) is always true. Note the strict inequality.
        (Default 1)

See also:
  pdf, cdf, draw, support

References:
  http://en.wikipedia.org/wiki/Uniform_distribution_(discrete)

Examples:
  (pdf (integer-distribution 0 10) 3) ; returns 1/10 for any value
  (draw (integer-distribution -5 5))
  (draw (integer-distribution (bit-shift-left 2 1000))) ; probably a very large value

map->Beta-rec

Usage: (map->Beta-rec m#)

Factory function for class incanter.distributions.Beta-rec, taking a map of keywords to field values.

map->Binomial-rec

Usage: (map->Binomial-rec m#)

Factory function for class incanter.distributions.Binomial-rec, taking a map of keywords to field values.

map->ChiSquare-rec

Usage: (map->ChiSquare-rec m#)

Factory function for class incanter.distributions.ChiSquare-rec, taking a map of keywords to field values.

map->Combination

Usage: (map->Combination m#)

Factory function for class incanter.distributions.Combination, taking a map of keywords to field values.

map->DoubleUniform-rec

Usage: (map->DoubleUniform-rec m#)

Factory function for class incanter.distributions.DoubleUniform-rec, taking a map of keywords to field values.

map->Exponential-rec

Usage: (map->Exponential-rec m#)

Factory function for class incanter.distributions.Exponential-rec, taking a map of keywords to field values.

map->F

Usage: (map->F m#)

Factory function for class incanter.distributions.F, taking a map of keywords to field values.

map->Gamma-rec

Usage: (map->Gamma-rec m#)

Factory function for class incanter.distributions.Gamma-rec, taking a map of keywords to field values.

map->NegativeBinomial-rec

Usage: (map->NegativeBinomial-rec m#)

Factory function for class incanter.distributions.NegativeBinomial-rec, taking a map of keywords to field values.

map->Normal-rec

Usage: (map->Normal-rec m#)

Factory function for class incanter.distributions.Normal-rec, taking a map of keywords to field values.

map->Poisson-rec

Usage: (map->Poisson-rec m#)

Factory function for class incanter.distributions.Poisson-rec, taking a map of keywords to field values.

map->StudentT-rec

Usage: (map->StudentT-rec m#)

Factory function for class incanter.distributions.StudentT-rec, taking a map of keywords to field values.

map->UniformInt

Usage: (map->UniformInt m#)

Factory function for class incanter.distributions.UniformInt, taking a map of keywords to field values.

neg-binomial-distribution

Usage: (neg-binomial-distribution)
       (neg-binomial-distribution size prob)

Returns a Negative binomial distribution that implements the incanter.distributions.Distribution protocol.

Arguments:
  size       (default 10)
  prob       (default 1/2)

See also:
  Distribution, pdf, cdf, draw, support

References:
  http://incanter.org/docs/parallelcolt/api/cern/jet/random/tdouble/NegativeBinomial.html
  http://en.wikipedia.org/wiki/Negative_binomial_distribution

Example:
  (pdf (neg-binomial-distribution 20 1/2) 10)

normal-distribution

Usage: (normal-distribution)
       (normal-distribution mean sd)

Returns a Normal distribution that implements the
incanter.distributions.Distribution protocol.

Arguments:
  mean	The mean of the distribution. One of two parameters
        that summarize the Normal distribution (default 0).
  sd    The standard deviation of the distribution.
        The second parameter that describes the Normal (default 1).

See also:
    Distribution, pdf, cdf, draw, support

References:
    http://incanter.org/docs/parallelcolt/api/cern/jet/random/tdouble/Normal.html
    http://en.wikipedia.org/wiki/Normal_distribution

Example:
    (pdf (normal-distribution -2 (sqrt 0.5)) 1.96)

poisson-distribution

Usage: (poisson-distribution)
       (poisson-distribution lambda)

Returns a Poisson distribution that implements the incanter.distributions.Distribution protocol.

Arguments:
  lambda     (default 1)

See also:
  Distribution, pdf, cdf, draw, support

References:
  http://incanter.org/docs/parallelcolt/api/cern/jet/random/tdouble/Poisson.html
  http://en.wikipedia.org/wiki/Poisson_distribution

Example:
  (pdf (poisson-distribution 10) 5)

roulette-wheel

Usage: (roulette-wheel freqs)

Perform a roulette wheel selection given a list of frequencies

t-distribution

Usage: (t-distribution)
       (t-distribution df)

Returns a Student-t distribution that implements the incanter.distributions.Distribution protocol.

Arguments:
  df         (default 1)

See also:
  Distribution, pdf, cdf, draw, support

References:
  http://incanter.org/docs/parallelcolt/api/cern/jet/random/tdouble/StudentT.html
  http://en.wikipedia.org/wiki/Student-t_distribution

Example:
  (pdf (t-distribution 10) 1.2)

test-statistic-distribution

Usage: (test-statistic-distribution test-statistic n k)

Create a distribution of the test-statistic over the possible
random samples of treatment units from the possible units.

There are two methods for generating the distribution. The
first method is enumerating all possible randomizations and
performing the test statistic on each. This gives the exact
distribution, but is only feasible for small problems.

The second method uses a combination-distribution to sample
for the space of possible treatment assignments and applies
the test statistic the sampled randomizations. While the
resulting distribution is not exact, it is tractable for
larger problems.

The algorithm automatically chooses between the two methods
by computing the number of possible randomizations and
comparing it to *test-statistic-iterations*. If the exact
distribution requires fewer than *test-statistic-iterations*
the enumeration method is used. Otherwise, it draws
*test-statistic-iterations* total samples for the simulated
method.

By default, the algorithm uses parallel computation. This is
controlled by the function *test-statistic-map*, which is
bound to pmap by default. Bind it to map to use a single
thread for computation.

Arguments:
  test-statistic	A function that takes two vectors and summarizes
      the difference between them
  n	  The number of total units in the pool
  k	  The number of treatment units per sample

See also:
  combination-distribution, pdf, cdf, draw, support

References:
  http://en.wikipedia.org/wiki/Sampling_distribution
  http://en.wikipedia.org/wiki/Exact_test
  http://en.wikipedia.org/wiki/Randomization_test
  http://en.wikipedia.org/wiki/Lady_tasting_tea

uniform-distribution

Usage: (uniform-distribution)
       (uniform-distribution min max)

Returns a Uniform distribution that implements the incanter.distributions.Distribution protocol.

Arguments:
  min        (default 0)
  max        (default 1)

See also:
  Distribution, pdf, cdf, draw, support

References:
  http://incanter.org/docs/parallelcolt/api/cern/jet/random/tdouble/DoubleUniform.html
  http://en.wikipedia.org/wiki/Uniform_distribution

Example:
  (pdf (uniform-distribution 1.0 10.0) 5)