649 lines
11 KiB
Plaintext
649 lines
11 KiB
Plaintext
---
|
||
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"
|
||
|
||
<TOCInline toc={toc} />
|
||
|
||
## 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)
|
||
```
|
||
|
||
### exponential
|
||
|
||
**Definitions**
|
||
|
||
```javascript
|
||
exponential: (distribution|number) => distribution
|
||
```
|
||
|
||
**Examples**
|
||
|
||
```javascript
|
||
exponential(2)
|
||
```
|
||
|
||
### bernoulli
|
||
|
||
**Definitions**
|
||
|
||
```javascript
|
||
bernoulli: (distribution|number) => distribution
|
||
```
|
||
|
||
**Examples**
|
||
|
||
```javascript
|
||
bernoulli(0.5)
|
||
```
|
||
|
||
### triangular
|
||
|
||
**Definitions**
|
||
|
||
```javascript
|
||
triangular: (number, number, number) => distribution
|
||
```
|
||
|
||
**Examples**
|
||
|
||
```javascript
|
||
triangular(5, 10, 20)
|
||
```
|
||
|
||
### To / credibleIntervalToDistribution
|
||
|
||
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.
|
||
|
||
``To`` is an alias for ``credibleIntervalToDistribution``. However, because of its frequent use, it is recommended to use the shorter name.
|
||
|
||
```javascript
|
||
to: (distribution|number, distribution|number) => distribution
|
||
credibleIntervalToDistribution(distribution|number, distribution|number) => distribution
|
||
```
|
||
|
||
**Examples**
|
||
|
||
```javascript
|
||
5 to 10
|
||
to(5,10)
|
||
-5 to 5
|
||
```
|
||
|
||
|
||
### mixture
|
||
|
||
```javascript
|
||
mixture: (...distributionLike, weights?:list<float>) => distribution
|
||
mixture: (list<distributionLike>, weights?:list<float>) => 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])
|
||
```
|
||
|
||
## Functions
|
||
|
||
### 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<number>
|
||
```
|
||
|
||
**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<distributionLike>) => distribution
|
||
```
|
||
|
||
```javascript
|
||
sum([normal(0,1), normal(1,3), uniform(10,1)])
|
||
```
|
||
|
||
### multiply
|
||
|
||
```javascript
|
||
multiply: (distributionLike, distributionLike) => distribution
|
||
```
|
||
|
||
### product
|
||
|
||
```javascript
|
||
product: (list<distributionLike>) => 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<dict<{min: number, max: number}>>}>) => declaration
|
||
```
|
||
|
||
**Examples**
|
||
|
||
```javascript
|
||
declareFn({
|
||
fn: {|a,b| a },
|
||
inputs: [
|
||
{min: 0, max: 100},
|
||
{min: 30, max: 50}
|
||
]
|
||
})
|
||
```
|