squiggle/packages/website/docs/Features/Functions.mdx

369 lines
8.9 KiB
Plaintext
Raw Permalink Normal View History

2022-03-25 02:08:46 +00:00
---
2022-04-20 17:41:22 +00:00
title: "Functions Reference"
2022-03-25 02:08:46 +00:00
sidebar_position: 7
---
2022-04-11 00:13:11 +00:00
import { SquiggleEditor } from "../../src/components/SquiggleEditor";
2022-03-25 02:08:46 +00:00
_The source of truth for this document is [this file of code](https://github.com/quantified-uncertainty/squiggle/blob/develop/packages/squiggle-lang/src/rescript/ReducerInterface/ReducerInterface_GenericDistribution.res)_
2022-03-25 02:08:46 +00:00
2022-04-20 17:41:22 +00:00
## Inventory distributions
2022-03-25 02:08:46 +00:00
2022-04-20 16:09:57 +00:00
We provide starter distributions, computed symbolically.
2022-04-20 17:41:22 +00:00
### Normal distribution
2022-03-25 02:08:46 +00:00
The `normal(mean, sd)` function creates a normal distribution with the given mean
and standard deviation.
<SquiggleEditor initialSquiggleString="normal(5, 1)" />
2022-03-25 02:08:46 +00:00
2022-04-20 17:41:22 +00:00
#### Validity
2022-04-20 16:09:57 +00:00
- `sd > 0`
2022-04-20 17:41:22 +00:00
### Uniform distribution
2022-03-25 02:08:46 +00:00
The `uniform(low, high)` function creates a uniform distribution between the
two given numbers.
2022-03-25 02:08:46 +00:00
<SquiggleEditor initialSquiggleString="uniform(3, 7)" />
2022-03-25 02:08:46 +00:00
2022-04-20 17:41:22 +00:00
#### Validity
2022-04-20 16:09:57 +00:00
- `low < high`
2022-04-20 17:41:22 +00:00
### Lognormal distribution
2022-03-25 02:08:46 +00:00
The `lognormal(mu, sigma)` returns the log of a normal distribution with parameters
`mu` and `sigma`. The log of `lognormal(mu, sigma)` is a normal distribution with mean `mu` and standard deviation `sigma`.
2022-03-25 02:08:46 +00:00
<SquiggleEditor initialSquiggleString="lognormal(0, 0.7)" />
2022-03-25 02:08:46 +00:00
An alternative format is also available. The `to` notation creates a lognormal
2022-03-25 02:08:46 +00:00
distribution with a 90% confidence interval between the two numbers. We add
this convenience as lognormal distributions are commonly used in practice.
2022-03-25 02:08:46 +00:00
<SquiggleEditor initialSquiggleString="2 to 10" />
2022-04-20 17:41:22 +00:00
#### Future feature:
2022-04-20 16:09:57 +00:00
2022-03-25 02:08:46 +00:00
Furthermore, it's also possible to create a lognormal from it's actual mean
and standard deviation, using `lognormalFromMeanAndStdDev`.
2022-03-25 02:08:46 +00:00
TODO: interpreter/parser doesn't provide this in current `develop` branch
<SquiggleEditor initialSquiggleString="lognormalFromMeanAndStdDev(20, 10)" />
2022-03-25 02:08:46 +00:00
2022-04-20 17:41:22 +00:00
#### Validity
2022-04-20 16:09:57 +00:00
- `sigma > 0`
- In `x to y` notation, `x < y`
2022-04-20 17:41:22 +00:00
### Beta distribution
2022-03-25 02:08:46 +00:00
The `beta(a, b)` function creates a beta distribution with parameters `a` and `b`:
2022-03-25 02:08:46 +00:00
<SquiggleEditor initialSquiggleString="beta(10, 20)" />
2022-03-25 02:08:46 +00:00
2022-04-20 17:41:22 +00:00
#### Validity
2022-04-20 16:09:57 +00:00
- `a > 0`
- `b > 0`
- Empirically, we have noticed that numerical instability arises when `a < 1` or `b < 1`
2022-03-25 02:08:46 +00:00
2022-04-20 17:41:22 +00:00
### Exponential distribution
The `exponential(rate)` function creates an exponential distribution with the given
rate.
2022-03-25 02:08:46 +00:00
<SquiggleEditor initialSquiggleString="exponential(1.11)" />
2022-03-25 02:08:46 +00:00
2022-04-20 17:41:22 +00:00
#### Validity
2022-04-20 16:09:57 +00:00
- `rate > 0`
2022-04-20 17:41:22 +00:00
### Triangular distribution
2022-03-25 02:08:46 +00:00
The `triangular(a,b,c)` function creates a triangular distribution with lower
bound `a`, mode `b` and upper bound `c`.
2022-04-20 17:41:22 +00:00
#### Validity
2022-04-20 16:09:57 +00:00
- `a < b < c`
2022-03-25 02:08:46 +00:00
<SquiggleEditor initialSquiggleString="triangular(1, 2, 4)" />
2022-04-20 17:41:22 +00:00
### Scalar (constant dist)
2022-03-25 02:08:46 +00:00
2022-04-20 16:09:57 +00:00
Squiggle, when the context is right, automatically casts a float to a constant distribution.
2022-04-20 17:41:22 +00:00
## Operating on distributions
2022-04-20 16:09:57 +00:00
Here are the ways we combine distributions.
2022-04-20 17:41:22 +00:00
### Mixture of distributions
2022-04-20 17:41:22 +00:00
The `mixture` function combines 2 or more other distributions to create a weighted
2022-03-25 02:08:46 +00:00
combination of the two. The first positional arguments represent the distributions
to be combined, and the last argument is how much to weigh every distribution in the
combination.
2022-04-20 17:41:22 +00:00
<SquiggleEditor initialSquiggleString="mixture(uniform(0,1), normal(1,1), [0.5, 0.5])" />
2022-03-25 02:08:46 +00:00
It's possible to create discrete distributions using this method.
2022-03-25 02:08:46 +00:00
2022-04-20 17:41:22 +00:00
<SquiggleEditor initialSquiggleString="mixture(0, 1, [0.2,0.8])" />
2022-03-25 02:08:46 +00:00
As well as mixed distributions:
2022-04-20 17:41:22 +00:00
<SquiggleEditor initialSquiggleString="mixture(3, 8, 1 to 10, [0.2, 0.3, 0.5])" />
2022-03-25 02:08:46 +00:00
2022-04-20 17:41:22 +00:00
An alias of `mixture` is `mx`
2022-03-25 02:08:46 +00:00
2022-04-20 17:41:22 +00:00
#### Validity
2022-04-20 16:09:57 +00:00
Using javascript's variable arguments notation, consider `mx(...dists, weights)`:
- `dists.length == weights.length`
2022-04-10 23:15:46 +00:00
### Addition
A horizontal right shift
2022-03-25 02:08:46 +00:00
<SquiggleEditor
initialSquiggleString={`dist1 = 1 to 10
dist2 = triangular(1,2,3)
dist1 + dist2`}
/>
2022-03-25 02:08:46 +00:00
### Subtraction
A horizontal left shift
2022-03-25 02:08:46 +00:00
<SquiggleEditor
initialSquiggleString={`dist1 = 1 to 10
dist2 = triangular(1,2,3)
dist1 - dist2`}
/>
2022-03-25 02:08:46 +00:00
### Multiplication
TODO: provide intuition pump for the semantics
<SquiggleEditor
initialSquiggleString={`dist1 = 1 to 10
dist2 = triangular(1,2,3)
dist1 * dist2`}
/>
2022-04-20 17:41:22 +00:00
We also provide concatenation of two distributions as a syntax sugar for `*`
<SquiggleEditor initialSquiggleString="(0.1 to 1) triangular(1,2,3)" />
2022-04-20 17:41:22 +00:00
### Division
TODO: provide intuition pump for the semantics
<SquiggleEditor
initialSquiggleString={`dist1 = 1 to 10
dist2 = triangular(1,2,3)
dist1 / dist2`}
/>
### Exponentiation
TODO: provide intuition pump for the semantics
2022-04-20 17:41:22 +00:00
<SquiggleEditor initialSquiggleString={`(0.1 to 1) ^ beta(2, 3)`} />
2022-04-20 17:41:22 +00:00
### Taking the base `e` exponential
<SquiggleEditor
initialSquiggleString={`dist = triangular(1,2,3)
exp(dist)`}
/>
2022-04-20 17:41:22 +00:00
### Taking logarithms
<SquiggleEditor
initialSquiggleString={`dist = triangular(1,2,3)
log(dist)`}
/>
<SquiggleEditor
initialSquiggleString={`dist = beta(1,2)
log10(dist)`}
/>
2022-04-20 17:41:22 +00:00
Base `x`
<SquiggleEditor
initialSquiggleString={`x = 2
dist = beta(2,3)
log(dist, x)`}
/>
2022-04-20 17:41:22 +00:00
#### Validity
2022-04-20 16:09:57 +00:00
2022-04-20 17:41:22 +00:00
- `x` must be a scalar
- See [the current discourse](https://github.com/quantified-uncertainty/squiggle/issues/304)
2022-04-20 17:41:22 +00:00
### Pointwise addition
**Pointwise operations are done with `PointSetDist` internals rather than `SampleSetDist` internals**.
TODO: this isn't in the new interpreter/parser yet.
<SquiggleEditor
initialSquiggleString={`dist1 = 1 to 10
dist2 = triangular(1,2,3)
dist1 .+ dist2`}
/>
2022-04-20 17:41:22 +00:00
### Pointwise subtraction
TODO: this isn't in the new interpreter/parser yet.
<SquiggleEditor
initialSquiggleString={`dist1 = 1 to 10
dist2 = triangular(1,2,3)
dist1 .- dist2`}
/>
2022-04-20 17:41:22 +00:00
### Pointwise multiplication
<SquiggleEditor
initialSquiggleString={`dist1 = 1 to 10
dist2 = triangular(1,2,3)
dist1 .* dist2`}
/>
2022-04-20 17:41:22 +00:00
### Pointwise division
<SquiggleEditor
initialSquiggleString={`dist1 = 1 to 10
dist2 = triangular(1,2,3)
dist1 ./ dist2`}
/>
2022-04-20 17:41:22 +00:00
### Pointwise exponentiation
<SquiggleEditor
initialSquiggleString={`dist1 = 1 to 10
dist2 = triangular(1,2,3)
dist1 .^ dist2`}
/>
2022-04-20 17:41:22 +00:00
## Standard functions on distributions
2022-04-20 17:41:22 +00:00
### Probability density function
2022-03-25 02:08:46 +00:00
The `pdf(dist, x)` function returns the density of a distribution at the
given point x.
<SquiggleEditor initialSquiggleString="pdf(normal(0,1),0)" />
2022-04-20 17:41:22 +00:00
#### Validity
2022-04-20 16:09:57 +00:00
- `x` must be a scalar
- `dist` must be a distribution
2022-03-25 02:08:46 +00:00
2022-04-20 17:41:22 +00:00
### Cumulative density function
The `cdf(dist, x)` gives the cumulative probability of the distribution
or all values lower than x. It is the inverse of `inv`.
2022-03-25 02:08:46 +00:00
<SquiggleEditor initialSquiggleString="cdf(normal(0,1),0)" />
2022-04-20 17:41:22 +00:00
#### Validity
2022-04-20 16:09:57 +00:00
- `x` must be a scalar
- `dist` must be a distribution
2022-04-20 17:41:22 +00:00
### Inverse CDF
The `inv(dist, prob)` gives the value x or which the probability for all values
lower than x is equal to prob. It is the inverse of `cdf`.
<SquiggleEditor initialSquiggleString="inv(normal(0,1),0.5)" />
2022-04-20 17:41:22 +00:00
#### Validity
2022-04-20 16:09:57 +00:00
- `prob` must be a scalar (please only put it in `(0,1)`)
- `dist` must be a distribution
2022-04-20 17:41:22 +00:00
### Mean
2022-04-10 23:15:46 +00:00
The `mean(distribution)` function gives the mean (expected value) of a distribution.
2022-03-25 02:08:46 +00:00
<SquiggleEditor initialSquiggleString="mean(normal(5, 10))" />
2022-04-20 17:41:22 +00:00
### Sampling a distribution
2022-04-10 23:15:46 +00:00
The `sample(distribution)` samples a given distribution.
2022-03-25 02:08:46 +00:00
<SquiggleEditor initialSquiggleString="sample(normal(0, 10))" />
## Converting between distribution formats
Recall the [three formats of distributions](https://develop--squiggle-documentation.netlify.app/docs/Discussions/Three-Types-Of-Distributions). We can force any distribution into `SampleSet` format
<SquiggleEditor initialSquiggleString="toSampleSet(normal(5, 10))" />
Or `PointSet` format
<SquiggleEditor initialSquiggleString="toPointSet(normal(5, 10))" />
2022-04-20 17:41:22 +00:00
## Normalization
2022-04-20 16:09:57 +00:00
Some distribution operations (like horizontal shift) return an unnormalized distriibution.
We provide a `normalize` function
<SquiggleEditor initialSquiggleString="normalize((0.1 to 1) + triangular(0.1, 1, 10))" />
2022-04-20 17:41:22 +00:00
#### Validity - Input to `normalize` must be a dist
2022-04-20 16:09:57 +00:00
We provide a predicate `isNormalized`, for when we have simple control flow
<SquiggleEditor initialSquiggleString="isNormalized((0.1 to 1) * triangular(0.1, 1, 10))" />
2022-04-20 17:41:22 +00:00
#### Validity
2022-04-20 16:09:57 +00:00
- Input to `isNormalized` must be a dist
2022-04-20 17:41:22 +00:00
## Convert any distribution to a sample set distribution
`toSampleSet` has two signatures
It is unary when you use an internal hardcoded number of samples
<SquiggleEditor initialSquiggleString="toSampleSet(0.1 to 1)" />
2022-04-20 16:26:03 +00:00
And binary when you provide a number of samples (floored)
<SquiggleEditor initialSquiggleString="toSampleSet(0.1 to 1, 100)" />
2022-04-20 17:41:22 +00:00
## `inspect`
2022-04-20 16:09:57 +00:00
You may like to debug by right clicking your browser and using the _inspect_ functionality on the webpage, and viewing the _console_ tab. Then, wrap your squiggle output with `inspect` to log an internal representation.
<SquiggleEditor initialSquiggleString="inspect(toSampleSet(0.1 to 1, 100))" />
2022-04-20 16:09:57 +00:00
Save for a logging side effect, `inspect` does nothing to input and returns it.
2022-04-20 17:41:22 +00:00
## Truncate
2022-04-20 16:09:57 +00:00
You can cut off from the left
<SquiggleEditor initialSquiggleString="truncateLeft(0.1 to 1, 0.5)" />
2022-04-20 16:09:57 +00:00
You can cut off from the right
<SquiggleEditor initialSquiggleString="truncateRight(0.1 to 1, 10)" />
2022-04-20 16:09:57 +00:00
You can cut off from both sides
<SquiggleEditor initialSquiggleString="truncate(0.1 to 1, 0.5, 1.5)" />