# API for distributions - Incanter1.5.5 (stable)

by Mark M. Fredrickson and William Leung

Full namespace name: incanter.distributions

## Overview

`Probability functions (pdf, cdf, draw, etc.) for common distributions, and for collections, sets, and maps.`

## Distribution

Protocol
```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.

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
```
Known implementations: Beta-rec, Binomial-rec, ChiSquare-rec, clojure.lang.APersistentMap, clojure.lang.APersistentSet, clojure.lang.Sequential, Combination, DoubleUniform-rec, Exponential-rec, F, Gamma-rec, NegativeBinomial-rec, Normal-rec, Poisson-rec, StudentT-rec, UniformInt

### cdf

function
```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.

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 ```

### draw

function
```Usage: (draw d)
```
```A function of the incanter.distribution.Distribution protocol.

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

Distribution, pdf, cdf, support

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

### mean

function
```Usage: (mean d)
```
`mean`

### pdf

function
```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.

Distribution, cdf, draw, support

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

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

### support

function
```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?

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 ```

### variance

function
```Usage: (variance d)
```
`variance`

Source

## Beta-rec

record

Fields: [alpha beta]
Protocols: Distribution
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map

## Binomial-rec

record

Fields: [n p]
Protocols: Distribution
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map

## ChiSquare-rec

record

Fields: [df]
Protocols: Distribution
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map

## Combination

record

Fields: [n k u]
Protocols: Distribution
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map

## DoubleUniform-rec

record

Fields: [min max]
Protocols: Distribution
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map

## Exponential-rec

record

Fields: [rate]
Protocols: Distribution
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map

## F

record

Fields: [df1 df2]
Protocols: Distribution
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map

## Gamma-rec

record

Fields: [shape scale]
Protocols: Distribution
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map

## NegativeBinomial-rec

record

Fields: [size prob]
Protocols: Distribution
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map

## Normal-rec

record

Fields: [mean sd]
Protocols: Distribution
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map

## Poisson-rec

record

Fields: [lambda]
Protocols: Distribution
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map

## StudentT-rec

record

Fields: [df]
Protocols: Distribution
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map

## UniformInt

record

Fields: [start end]
Protocols: Distribution
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map

## ->Beta-rec

function
```Usage: (->Beta-rec alpha beta)
```
`Positional factory function for class incanter.distributions.Beta-rec.`

Source

## ->Binomial-rec

function
```Usage: (->Binomial-rec n p)
```
`Positional factory function for class incanter.distributions.Binomial-rec.`

Source

## ->ChiSquare-rec

function
```Usage: (->ChiSquare-rec df)
```
`Positional factory function for class incanter.distributions.ChiSquare-rec.`

Source

## ->Combination

function
```Usage: (->Combination n k u)
```
`Positional factory function for class incanter.distributions.Combination.`

Source

## ->DoubleUniform-rec

function
```Usage: (->DoubleUniform-rec min max)
```
`Positional factory function for class incanter.distributions.DoubleUniform-rec.`

Source

## ->Exponential-rec

function
```Usage: (->Exponential-rec rate)
```
`Positional factory function for class incanter.distributions.Exponential-rec.`

Source

## ->F

function
```Usage: (->F df1 df2)
```
`Positional factory function for class incanter.distributions.F.`

Source

## ->Gamma-rec

function
```Usage: (->Gamma-rec shape scale)
```
`Positional factory function for class incanter.distributions.Gamma-rec.`

Source

## ->NegativeBinomial-rec

function
```Usage: (->NegativeBinomial-rec size prob)
```
`Positional factory function for class incanter.distributions.NegativeBinomial-rec.`

Source

## ->Normal-rec

function
```Usage: (->Normal-rec mean sd)
```
`Positional factory function for class incanter.distributions.Normal-rec.`

Source

## ->Poisson-rec

function
```Usage: (->Poisson-rec lambda)
```
`Positional factory function for class incanter.distributions.Poisson-rec.`

Source

## ->StudentT-rec

function
```Usage: (->StudentT-rec df)
```
`Positional factory function for class incanter.distributions.StudentT-rec.`

Source

## ->UniformInt

function
```Usage: (->UniformInt start end)
```
`Positional factory function for class incanter.distributions.UniformInt.`

Source

## beta-distribution

function
```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)

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)
```

Source

## binomial-distribution

function
```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)

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)
```

Source

## chisq-distribution

function
```Usage: (chisq-distribution)
(chisq-distribution df)
```
```Returns a Chi-square distribution that implements the incanter.distributions.Distribution protocol.

Arguments:
df         (default 1)

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)
```

Source

## combination-distribution

function
```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.

test-statistic-distribution, integer-distribution, pdf, cdf, draw, support

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

```

Source

## exponential-distribution

function
```Usage: (exponential-distribution)
(exponential-distribution rate)
```
```Returns a Exponential distribution that implements the incanter.distributions.Distribution protocol.

Arguments:
rate       (default 1)

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)
```

Source

## f-distribution

function
```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)

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)
```

Source

## gamma-distribution

function
```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)

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)
```

Source

## integer-distribution

function
```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)

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
```

Source

## map->Beta-rec

function
```Usage: (map->Beta-rec m#)
```
`Factory function for class incanter.distributions.Beta-rec, taking a map of keywords to field values.`

Source

## map->Binomial-rec

function
```Usage: (map->Binomial-rec m#)
```
`Factory function for class incanter.distributions.Binomial-rec, taking a map of keywords to field values.`

Source

## map->ChiSquare-rec

function
```Usage: (map->ChiSquare-rec m#)
```
`Factory function for class incanter.distributions.ChiSquare-rec, taking a map of keywords to field values.`

Source

## map->Combination

function
```Usage: (map->Combination m#)
```
`Factory function for class incanter.distributions.Combination, taking a map of keywords to field values.`

Source

## map->DoubleUniform-rec

function
```Usage: (map->DoubleUniform-rec m#)
```
`Factory function for class incanter.distributions.DoubleUniform-rec, taking a map of keywords to field values.`

Source

## map->Exponential-rec

function
```Usage: (map->Exponential-rec m#)
```
`Factory function for class incanter.distributions.Exponential-rec, taking a map of keywords to field values.`

Source

## map->F

function
```Usage: (map->F m#)
```
`Factory function for class incanter.distributions.F, taking a map of keywords to field values.`

Source

## map->Gamma-rec

function
```Usage: (map->Gamma-rec m#)
```
`Factory function for class incanter.distributions.Gamma-rec, taking a map of keywords to field values.`

Source

## map->NegativeBinomial-rec

function
```Usage: (map->NegativeBinomial-rec m#)
```
`Factory function for class incanter.distributions.NegativeBinomial-rec, taking a map of keywords to field values.`

Source

## map->Normal-rec

function
```Usage: (map->Normal-rec m#)
```
`Factory function for class incanter.distributions.Normal-rec, taking a map of keywords to field values.`

Source

## map->Poisson-rec

function
```Usage: (map->Poisson-rec m#)
```
`Factory function for class incanter.distributions.Poisson-rec, taking a map of keywords to field values.`

Source

## map->StudentT-rec

function
```Usage: (map->StudentT-rec m#)
```
`Factory function for class incanter.distributions.StudentT-rec, taking a map of keywords to field values.`

Source

## map->UniformInt

function
```Usage: (map->UniformInt m#)
```
`Factory function for class incanter.distributions.UniformInt, taking a map of keywords to field values.`

Source

## neg-binomial-distribution

function
```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)

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)
```

Source

## normal-distribution

function
```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).

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)
```

Source

## poisson-distribution

function
```Usage: (poisson-distribution)
(poisson-distribution lambda)
```
```Returns a Poisson distribution that implements the incanter.distributions.Distribution protocol.

Arguments:
lambda     (default 1)

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)
```

Source

## roulette-wheel

function
```Usage: (roulette-wheel freqs)
```
`Perform a roulette wheel selection given a list of frequencies`

Source

## t-distribution

function
```Usage: (t-distribution)
(t-distribution df)
```
```Returns a Student-t distribution that implements the incanter.distributions.Distribution protocol.

Arguments:
df         (default 1)

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)
```

Source

## test-statistic-distribution

function
```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

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

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

```

Source

## uniform-distribution

function
```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)

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)
```

Source

Logo & site design by Tom Hickey.
Clojure auto-documentation system by Tom Faulhaber.