API for distributions - Incanter 2.0 (in development)

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.

Protocols



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.

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

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 

      
      
      
    

draw

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

      
      
      
    

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.

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

      
      
      
    

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?

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 

      
      
      
    

variance

function
Usage: (variance d)
variance

      
      
      
    
Source

Types



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

Public Variables and Functions



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

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)

    
    
    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)

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)

    
    
    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)

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)

    
    
    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.

See also:
  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)

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)

    
    
    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)

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)

    
    
    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)

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)

    
    
    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)

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

    
    
    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)

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)

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

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)

    
    
    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)

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)

    
    
    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)

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)

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


    
    
    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)

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)

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