Distribution Module

Probability distributions with sampling, PDF/CDF, and statistical moments.

The Distribution module provides 12 probability distributions with comprehensive statistical functions including sampling (reproducible and non-reproducible), probability density/mass functions, cumulative distribution functions, quantiles, and moments (mean, variance, skewness).

Distributions

Continuous: Normal, Uniform, Exponential, Gamma, Beta, ChiSquared, StudentT, Weibull, LogNormal
Discrete: Poisson, Bernoulli, Binomial

Common patterns

import Distribution
import Result

-- Create and sample from a normal distribution
let normal = Distribution.normal 0.0 1.0
    |> Result.withDefault (panic "invalid")

let samples = Distribution.sampleN 100 normal
let reproducible = Distribution.sampleSeeded 42 normal

-- Probability calculations
Distribution.pdf 0.0 normal     -- ~0.3989
Distribution.cdf 1.96 normal    -- ~0.975

-- Statistical moments
Distribution.mean normal        -- 0.0
Distribution.variance normal    -- 1.0

Return types

Constructor functions return Result Distribution String to validate parameters:

normal 0.0 (-1.0) returns Err "Standard deviation must be positive"

Sampling returns Int for discrete distributions, Float for continuous.

Functions

Constructors

`Distribution.normal`

Float -> Float -> Result Distribution String

Create a normal (Gaussian) distribution with given mean and standard deviation.

Example:

import Distribution

Distribution.normal 0.0 1.0

Notes: Standard deviation must be positive.

See also: Distribution.sample, Distribution.pdf

`Distribution.uniform`

Float -> Float -> Result Distribution String

Create a uniform distribution over the interval [min, max).

Example:

import Distribution

Distribution.uniform 0.0 10.0

Notes: Minimum must be less than maximum.

See also: Distribution.normal

`Distribution.exponential`

Float -> Result Distribution String

Create an exponential distribution with given rate parameter.

Example:

import Distribution

Distribution.exponential 0.5

Notes: Rate must be positive.

See also: Distribution.gamma

`Distribution.poisson`

Float -> Result Distribution String

Create a Poisson distribution with given lambda (rate) parameter.

Example:

import Distribution

Distribution.poisson 5.0

Notes: Lambda must be positive. This is a discrete distribution.

See also: Distribution.binomial

`Distribution.bernoulli`

Float -> Result Distribution String

Create a Bernoulli distribution with given probability of success.

Example:

import Distribution

Distribution.bernoulli 0.5

Notes: Probability must be between 0 and 1. Samples return 0 or 1.

See also: Distribution.binomial

`Distribution.binomial`

Int -> Float -> Result Distribution String

Create a binomial distribution with n trials and probability p of success.

Example:

import Distribution

Distribution.binomial 10 0.5

Notes: n must be non-negative, p must be between 0 and 1.

See also: Distribution.bernoulli

`Distribution.gamma`

Float -> Float -> Result Distribution String

Create a gamma distribution with given shape and rate parameters.

Example:

import Distribution

Distribution.gamma 2.0 1.0

Notes: Shape and rate must be positive.

See also: Distribution.exponential, Distribution.chiSquared

`Distribution.beta`

Float -> Float -> Result Distribution String

Create a beta distribution with given alpha and beta shape parameters.

Example:

import Distribution

Distribution.beta 2.0 5.0

Notes: Alpha and beta must be positive.

See also: Distribution.uniform

`Distribution.chiSquared`

Float -> Result Distribution String

Create a chi-squared distribution with k degrees of freedom.

Example:

import Distribution

Distribution.chiSquared 3.0

Notes: Degrees of freedom must be positive.

See also: Distribution.gamma

`Distribution.studentT`

Float -> Result Distribution String

Create a Student's t-distribution with given degrees of freedom (standard form: mean=0, scale=1).

Example:

import Distribution

Distribution.studentT 10.0

Notes: Degrees of freedom must be positive.

See also: Distribution.normal

`Distribution.weibull`

Float -> Float -> Result Distribution String

Create a Weibull distribution with given shape and scale parameters.

Example:

import Distribution

Distribution.weibull 1.5 2.0

Notes: Shape and scale must be positive.

See also: Distribution.exponential

`Distribution.logNormal`

Float -> Float -> Result Distribution String

Create a log-normal distribution with given mu and sigma (parameters of the underlying normal).

Example:

import Distribution

Distribution.logNormal 0.0 1.0

Notes: Sigma must be positive.

See also: Distribution.normal

Sampling

`Distribution.sample`

Distribution -> number

Draw one random sample from the distribution. Returns Int for discrete distributions, Float for continuous.

Example:

import Distribution

Distribution.normal 0.0 1.0
    |> Result.withDefault (panic "invalid")
    |> Distribution.sample

Notes: Uses thread-local RNG. For reproducible results, use sampleSeeded.

See also: Distribution.sampleSeeded, Distribution.sampleN

`Distribution.sampleSeeded`

Int -> Distribution -> number

Draw one sample using a specific seed for reproducibility.

Example:

import Distribution

Distribution.normal 0.0 1.0
    |> Result.withDefault (panic "invalid")
    |> Distribution.sampleSeeded 42

Notes: Same seed always produces same result.

See also: Distribution.sample, Distribution.sampleNSeeded

`Distribution.sampleN`

Int -> Distribution -> [number]

Draw n random samples from the distribution.

Example:

import Distribution

Distribution.normal 0.0 1.0
    |> Result.withDefault (panic "invalid")
    |> Distribution.sampleN 100

Notes: Uses thread-local RNG.

See also: Distribution.sample, Distribution.sampleNSeeded

`Distribution.sampleNSeeded`

Int -> Int -> Distribution -> [number]

Draw n samples using a specific seed for reproducibility.

Example:

import Distribution

Distribution.normal 0.0 1.0
    |> Result.withDefault (panic "invalid")
    |> Distribution.sampleNSeeded 42 100

Notes: Arguments are: seed, count, distribution.

See also: Distribution.sampleN, Distribution.sampleSeeded

Probability

`Distribution.pdf`

Float -> Distribution -> Float

Probability density function. For discrete distributions, returns PMF at integer points, 0 otherwise.

Example:

import Distribution

Distribution.normal 0.0 1.0
    |> Result.withDefault (panic "invalid")
    |> Distribution.pdf 0.0

-- ~0.3989

See also: Distribution.cdf, Distribution.pmf

`Distribution.pmf`

Int -> Distribution -> Float

Probability mass function for discrete distributions (Poisson, Bernoulli, Binomial).

Example:

import Distribution

Distribution.poisson 5.0
    |> Result.withDefault (panic "invalid")
    |> Distribution.pmf 5

Notes: Only works for discrete distributions.

See also: Distribution.pdf

`Distribution.cdf`

Float -> Distribution -> Float

Cumulative distribution function: P(X <= x).

Example:

import Distribution

Distribution.normal 0.0 1.0
    |> Result.withDefault (panic "invalid")
    |> Distribution.cdf 1.96

-- ~0.975

See also: Distribution.quantile, Distribution.pdf

`Distribution.quantile`

Float -> Distribution -> Result Float String

Inverse CDF: returns x such that P(X <= x) = p. Only for continuous distributions.

Example:

import Distribution

Distribution.normal 0.0 1.0
    |> Result.withDefault (panic "invalid")
    |> Distribution.quantile 0.975

-- Ok ~1.96

Notes: Probability must be strictly between 0 and 1.

See also: Distribution.cdf

`Distribution.logPdf`

Float -> Distribution -> Float

Log of the probability density function. More numerically stable for extreme values.

Example:

import Distribution

Distribution.normal 0.0 1.0
    |> Result.withDefault (panic "invalid")
    |> Distribution.logPdf 0.0

See also: Distribution.pdf

Moments

`Distribution.mean`

Distribution -> Float

Expected value (first moment) of the distribution.

Example:

import Distribution

Distribution.normal 5.0 2.0
    |> Result.withDefault (panic "invalid")
    |> Distribution.mean

-- 5.0

See also: Distribution.variance, Distribution.stdDev

`Distribution.variance`

Distribution -> Float

Variance (second central moment) of the distribution.

Example:

import Distribution

Distribution.normal 0.0 2.0
    |> Result.withDefault (panic "invalid")
    |> Distribution.variance

-- 4.0

See also: Distribution.mean, Distribution.stdDev

`Distribution.stdDev`

Distribution -> Float

Standard deviation (square root of variance).

Example:

import Distribution

Distribution.normal 0.0 2.0
    |> Result.withDefault (panic "invalid")
    |> Distribution.stdDev

-- 2.0

See also: Distribution.variance

`Distribution.skewness`

Distribution -> Maybe Float

Skewness (third standardized moment). Returns Nothing if undefined.

Example:

import Distribution

Distribution.normal 0.0 1.0
    |> Result.withDefault (panic "invalid")
    |> Distribution.skewness

-- Just 0.0

See also: Distribution.kurtosis

`Distribution.kurtosis`

Distribution -> Maybe Float

Excess kurtosis (fourth standardized moment - 3). Returns Nothing if undefined.

Example:

import Distribution

Distribution.normal 0.0 1.0
    |> Result.withDefault (panic "invalid")
    |> Distribution.kurtosis

Notes: Currently returns Nothing for all distributions.

See also: Distribution.skewness

Inspection

`Distribution.min`

Distribution -> Float

Lower bound of the distribution's support.

Example:

import Distribution

Distribution.uniform 5.0 10.0
    |> Result.withDefault (panic "invalid")
    |> Distribution.min

-- 5.0

Notes: Returns negative infinity for unbounded distributions.

See also: Distribution.max

`Distribution.max`

Distribution -> Float

Upper bound of the distribution's support.

Example:

import Distribution

Distribution.uniform 5.0 10.0
    |> Result.withDefault (panic "invalid")
    |> Distribution.max

-- 10.0

Notes: Returns positive infinity for unbounded distributions.

See also: Distribution.min

`Distribution.isDiscrete`

Distribution -> Bool

Returns True if the distribution is discrete (Poisson, Bernoulli, Binomial).

Example:

import Distribution

Distribution.poisson 5.0
    |> Result.withDefault (panic "invalid")
    |> Distribution.isDiscrete

-- True

See also: Distribution.isContinuous

`Distribution.isContinuous`

Distribution -> Bool

Returns True if the distribution is continuous.

Example:

import Distribution

Distribution.normal 0.0 1.0
    |> Result.withDefault (panic "invalid")
    |> Distribution.isContinuous

-- True

See also: Distribution.isDiscrete

`Distribution.name`

Distribution -> String

Returns the name of the distribution type.

Example:

import Distribution

Distribution.normal 0.0 1.0
    |> Result.withDefault (panic "invalid")
    |> Distribution.name

-- "Normal"

See also: Distribution.parameters

`Distribution.parameters`

Distribution -> [(String, Float)]

Returns the parameters of the distribution as a list of (name, value) tuples.

Example:

import Distribution

Distribution.normal 0.0 1.0
    |> Result.withDefault (panic "invalid")
    |> Distribution.parameters

-- [("mean", 0.0), ("stdDev", 1.0)]

See also: Distribution.name