---
sidebar_position: 3
title: Distribution
---
Distributions are the flagship data type in Squiggle. The distribution type is a generic data type that contains one of three different formats of distributions.
These subtypes are [point set](/docs/Api/DistPointSet), [sample set](/docs/Api/DistSampleSet), and symbolic. The first two of these have a few custom functions that only work on them. You can read more about the differences between these formats [here](/docs/Discussions/Three-Formats-Of-Distributions).
Several functions below only can work on particular distribution formats.
For example, scoring and pointwise math requires the point set format. When this happens, the types are automatically converted to the correct format. These conversions are lossy.
import TOCInline from "@theme/TOCInline"
## Distribution Creation
These are functions for creating primative distributions. Many of these could optionally take in distributions as inputs; in these cases, Monte Carlo Sampling will be used to generate the greater distribution. This can be used for simple hierarchical models.
See a longer tutorial on creating distributions [here](/docs/Guides/DistributionCreation).
### Normal
**Definitions**
```javascript
normal: (distribution|number, distribution|number) => distribution
normal: (dict<{p5: distribution|number, p95: distribution|number}>) => distribution
normal: (dict<{mean: distribution|number, stdev: distribution|number}>) => distribution
```
**Examples**
```js
normal(5, 1)
normal({ p5: 4, p95: 10 })
normal({ mean: 5, stdev: 2 })
normal(5 to 10, normal(3, 2))
normal({ mean: uniform(5, 9), stdev: 3 })
```
### Lognormal
**Definitions**
```javascript
lognormal: (distribution|number, distribution|number) => distribution
lognormal: (dict<{p5: distribution|number, p95: distribution|number}>) => distribution
lognormal: (dict<{mean: distribution|number, stdev: distribution|number}>) => distribution
```
**Examples**
```javascript
lognormal(0.5, 0.8)
lognormal({ p5: 4, p95: 10 })
lognormal({ mean: 5, stdev: 2 })
```
### Uniform
**Definitions**
```javascript
uniform: (distribution|number, distribution|number) => distribution
```
**Examples**
```javascript
uniform(10, 12)
```
### Beta
**Definitions**
```javascript
beta: (distribution|number, distribution|number) => distribution
```
**Examples**
```javascript
beta(20, 25)
```
### Cauchy
**Definitions**
```javascript
cauchy: (distribution|number, distribution|number) => distribution
```
**Examples**
```javascript
cauchy(5, 1)
```
### Gamma
**Definitions**
```javascript
gamma: (distribution|number, distribution|number) => distribution
```
**Examples**
```javascript
gamma(5, 1)
```
### Logistic
**Definitions**
```javascript
logistic: (distribution|number, distribution|number) => distribution
```
**Examples**
```javascript
gamma(5, 1)
```
### To (Distribution)
The `to` function is an easy way to generate simple distributions using predicted _5th_ and _95th_ percentiles.
If both values are above zero, a `lognormal` distribution is used. If not, a `normal` distribution is used.
**Definitions**
```javascript
to: (distribution|number, distribution|number) => distribution
credibleIntervalToDistribution(distribution|number, distribution|number) => distribution
```
**Examples**
```javascript
5 to 10
to(5,10)
-5 to 5
```
### Exponential
**Definitions**
```javascript
exponential: (distribution|number) => distribution
```
**Examples**
```javascript
exponential(2)
```
### Bernoulli
**Definitions**
```javascript
bernoulli: (distribution|number) => distribution
```
**Examples**
```javascript
bernoulli(0.5)
```
## Functions
### mixture
```javascript
mixture: (...distributionLike, weights?:list) => distribution
mixture: (list, weights?:list) => distribution
```
**Examples**
```javascript
mixture(normal(5, 1), normal(10, 1), 8)
mx(normal(5, 1), normal(10, 1), [0.3, 0.7])
mx([normal(5, 1), normal(10, 1)], [0.3, 0.7])
```
### sample
One random sample from the distribution
```javascript
sample(distribution) => number
```
**Examples**
```javascript
sample(normal(5, 2))
```
### sampleN
N random samples from the distribution
```javascript
sampleN: (distribution, number) => list
```
**Examples**
```javascript
sampleN(normal(5, 2), 100)
```
### mean
The distribution mean
```javascript
mean: (distribution) => number
```
**Examples**
```javascript
mean(normal(5, 2))
```
### stdev
Standard deviation. Only works now on sample set distributions (so converts other distributions into sample set in order to calculate.)
```javascript
stdev: (distribution) => number
```
### variance
Variance. Similar to stdev, only works now on sample set distributions.
```javascript
variance: (distribution) => number
```
### mode
```javascript
mode: (distribution) => number
```
### cdf
```javascript
cdf: (distribution, number) => number
```
**Examples**
```javascript
cdf(normal(5, 2), 3)
```
### pdf
```javascript
pdf: (distribution, number) => number
```
**Examples**
```javascript
pdf(normal(5, 2), 3)
```
### quantile
```javascript
quantile: (distribution, number) => number
```
**Examples**
```javascript
quantile(normal(5, 2), 0.5)
```
### toPointSet
Converts a distribution to the pointSet format
```javascript
toPointSet: (distribution) => pointSetDistribution
```
**Examples**
```javascript
toPointSet(normal(5, 2))
```
### toSampleSet
Converts a distribution to the sampleSet format, with n samples
```javascript
toSampleSet: (distribution, number) => sampleSetDistribution
```
**Examples**
```javascript
toSampleSet(normal(5, 2), 1000)
```
### truncateLeft
Truncates the left side of a distribution. Returns either a pointSet distribution or a symbolic distribution.
```javascript
truncateLeft: (distribution, l => number) => distribution
```
**Examples**
```javascript
truncateLeft(normal(5, 2), 3)
```
### truncateRight
Truncates the right side of a distribution. Returns either a pointSet distribution or a symbolic distribution.
```javascript
truncateRight: (distribution, r => number) => distribution
```
**Examples**
```javascript
truncateLeft(normal(5, 2), 6)
```
### klDivergence
[Kullback–Leibler divergence](https://en.wikipedia.org/wiki/Kullback%E2%80%93Leibler_divergence) between two distributions.
```javascript
klDivergence: (distribution, distribution) => number
```
**Examples**
```javascript
klDivergence(normal(5, 2), normal(5, 4)) // returns 0.57
```
## Display
### toString
```javascript
toString: (distribution) => string
```
**Examples**
```javascript
toString(normal(5, 2))
```
### toSparkline
Produce a sparkline of length n
```javascript
toSparkline: (distribution, n = 20) => string
```
**Examples**
```javascript
toSparkline(normal(5, 2), 10)
```
### inspect
Prints the value of the distribution to the Javascript console, then returns the distribution.
```javascript
inspect: (distribution) => distribution
```
**Examples**
```javascript
inspect(normal(5, 2))
```
## Normalization
### normalize
Normalize a distribution. This means scaling it appropriately so that it's cumulative sum is equal to 1.
```javascript
normalize: (distribution) => distribution
```
**Examples**
```javascript
normalize(normal(5, 2))
```
### isNormalized
Check of a distribution is normalized. Most distributions are typically normalized, but there are some commands that could produce non-normalized distributions.
```javascript
isNormalized: (distribution) => bool
```
**Examples**
```javascript
isNormalized(normal(5, 2)) // returns true
```
### integralSum
Get the sum of the integral of a distribution. If the distribution is normalized, this will be 1.
```javascript
integralSum: (distribution) => number
```
**Examples**
```javascript
integralSum(normal(5, 2))
```
## Regular Arithmetic Operations
Regular arithmetic operations cover the basic mathematical operations on distributions. They work much like their equivalent operations on numbers.
The infixes ``+``,``-``, ``*``, ``/``, ``^``, ``-`` are supported for addition, subtraction, multiplication, division, power, and unaryMinus.
```javascript
pointMass(5 + 10) == pointMass(5) + pointMass(10)
```
### add
```javascript
add: (distributionLike, distributionLike) => distribution
```
```javascript
normal(0,1) + normal(1,3) // returns normal(1, 3.16...)
add(normal(0,1), normal(1,3)) // returns normal(1, 3.16...)
```
### sum
**Todo: Not yet implemented for distributions**
```javascript
sum: (list) => distribution
```
```javascript
sum([normal(0,1), normal(1,3), uniform(10,1)])
```
### multiply
```javascript
multiply: (distributionLike, distributionLike) => distribution
```
### product
```javascript
product: (list) => distribution
```
### subtract
```javascript
subtract: (distributionLike, distributionLike) => distribution
```
### divide
```javascript
divide: (distributionLike, distributionLike) => distribution
```
### pow
```javascript
pow: (distributionLike, distributionLike) => distribution
```
### exp
```javascript
exp: (distributionLike, distributionLike) => distribution
```
### log
```javascript
log: (distributionLike, distributionLike) => distribution
```
### log10
```javascript
log10: (distributionLike, distributionLike) => distribution
```
### unaryMinus
```javascript
unaryMinus: (distribution) => distribution
```
```javascript
-(normal(5,2)) // same as normal(-5, 2)
unaryMinus(normal(5,2)) // same as normal(-5, 2)
```
## Pointwise Arithmetic Operations
### dotAdd
```javascript
dotAdd: (distributionLike, distributionLike) => distribution
```
### dotMultiply
```javascript
dotMultiply: (distributionLike, distributionLike) => distribution
```
### dotSubtract
```javascript
dotSubtract: (distributionLike, distributionLike) => distribution
```
### dotDivide
```javascript
dotDivide: (distributionLike, distributionLike) => distribution
```
### dotPow
```javascript
dotPow: (distributionLike, distributionLike) => distribution
```
### dotExp
```javascript
dotExp: (distributionLike, distributionLike) => distribution
```
## Scale Arithmetic Operations
### scaleMultiply
```javascript
scaleMultiply: (distributionLike, number) => distribution
```
### scalePow
```javascript
scalePow: (distributionLike, number) => distribution
```
### scaleExp
```javascript
scaleExp: (distributionLike, number) => distribution
```
### scaleLog
```javascript
scaleLog: (distributionLike, number) => distribution
```
### scaleLog10
```javascript
scaleLog10: (distributionLike, number) => distribution
```
## Special
### Declaration (Continuous Functions)
Adds metadata to a function of the input ranges. Works now for numeric and date inputs. This is useful when making predictions. It allows you to limit the domain that your prediction will be used and scored within.
```javascript
declareFn: (dict<{fn: lambda, inputs: array>}>) => declaration
```
**Examples**
```javascript
declareFn({
fn: {|a,b| a },
inputs: [
{min: 0, max: 100},
{min: 30, max: 50}
]
})
```