second pass; one CR comment
This commit is contained in:
Quinn Dougherty
parent
15ccf876a6
commit
9f35039b60
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: "Functions reference"
|
||||
title: "Functions Reference"
|
||||
sidebar_position: 7
|
||||
---
|
||||
|
||||
|
|
@ -7,33 +7,33 @@ import { SquiggleEditor } from "../../src/components/SquiggleEditor";
|
|||
|
||||
_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)_
|
||||
|
||||
# Inventory distributions
|
||||
## Inventory distributions
|
||||
|
||||
We provide starter distributions, computed symbolically.
|
||||
|
||||
## Normal distribution
|
||||
### Normal distribution
|
||||
|
||||
The `normal(mean, sd)` function creates a normal distribution with the given mean
|
||||
and standard deviation.
|
||||
|
||||
<SquiggleEditor initialSquiggleString="normal(5, 1)" />
|
||||
|
||||
### Validity
|
||||
#### Validity
|
||||
|
||||
- `sd > 0`
|
||||
|
||||
## Uniform distribution
|
||||
### Uniform distribution
|
||||
|
||||
The `uniform(low, high)` function creates a uniform distribution between the
|
||||
two given numbers.
|
||||
|
||||
<SquiggleEditor initialSquiggleString="uniform(3, 7)" />
|
||||
|
||||
### Validity
|
||||
#### Validity
|
||||
|
||||
- `low < high`
|
||||
|
||||
## Lognormal distribution
|
||||
### Lognormal distribution
|
||||
|
||||
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`.
|
||||
|
|
@ -46,183 +46,227 @@ this convinience as lognormal distributions are commonly used in practice.
|
|||
|
||||
<SquiggleEditor initialSquiggleString="2 to 10" />
|
||||
|
||||
### Future feature:
|
||||
#### Future feature:
|
||||
|
||||
Furthermore, it's also possible to create a lognormal from it's actual mean
|
||||
and standard deviation, using `lognormalFromMeanAndStdDev`.
|
||||
|
||||
<SquiggleEditor initialSquiggleString="lognormalFromMeanAndStdDev(20, 10)" />
|
||||
|
||||
### Validity
|
||||
#### Validity
|
||||
|
||||
- `sigma > 0`
|
||||
- In `x to y` notation, `x < y`
|
||||
|
||||
## Beta distribution
|
||||
### Beta distribution
|
||||
|
||||
The `beta(a, b)` function creates a beta distribution with parameters `a` and `b`:
|
||||
|
||||
<SquiggleEditor initialSquiggleString="beta(1e1, 2e1)" />
|
||||
|
||||
### Validity
|
||||
#### Validity
|
||||
|
||||
- `a > 0`
|
||||
- `b > 0`
|
||||
- Empirically, we have noticed that numerical instability arises when `a < 1` or `b < 1`
|
||||
|
||||
## Exponential distribution
|
||||
### Exponential distribution
|
||||
|
||||
The `exponential(rate)` function creates an exponential distribution with the given
|
||||
rate.
|
||||
|
||||
<SquiggleEditor initialSquiggleString="exponential(1.11e0)" />
|
||||
|
||||
### Validity
|
||||
#### Validity
|
||||
|
||||
- `rate > 0`
|
||||
|
||||
## Triangular distribution
|
||||
### Triangular distribution
|
||||
|
||||
The `triangular(a,b,c)` function creates a triangular distribution with lower
|
||||
bound `a`, mode `b` and upper bound `c`.
|
||||
|
||||
### Validity
|
||||
#### Validity
|
||||
|
||||
- `a < b < c`
|
||||
|
||||
<SquiggleEditor initialSquiggleString="triangular(1, 2, 4)" />
|
||||
|
||||
## Scalar (constant dist)
|
||||
### Scalar (constant dist)
|
||||
|
||||
Squiggle, when the context is right, automatically casts a float to a constant distribution.
|
||||
|
||||
# Operating on distributions
|
||||
## Operating on distributions
|
||||
|
||||
Here are the ways we combine distributions.
|
||||
|
||||
## Mixture of distributions
|
||||
### Mixture of distributions
|
||||
|
||||
The `mx` function combines 2 or more other distributions to create a weighted
|
||||
The `mixture` function combines 2 or more other distributions to create a weighted
|
||||
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.
|
||||
|
||||
<SquiggleEditor initialSquiggleString="mx(uniform(0,1), normal(1,1), [0.5, 0.5])" />
|
||||
<SquiggleEditor initialSquiggleString="mixture(uniform(0,1), normal(1,1), [0.5, 0.5])" />
|
||||
|
||||
It's possible to create discrete distributions using this method.
|
||||
|
||||
<SquiggleEditor initialSquiggleString="mx(0, 1, [0.2,0.8])" />
|
||||
<SquiggleEditor initialSquiggleString="mixture(0, 1, [0.2,0.8])" />
|
||||
|
||||
As well as mixed distributions:
|
||||
|
||||
<SquiggleEditor initialSquiggleString="mx(3, 8, 1 to 10, [0.2, 0.3, 0.5])" />
|
||||
<SquiggleEditor initialSquiggleString="mixture(3, 8, 1 to 10, [0.2, 0.3, 0.5])" />
|
||||
|
||||
An alias of `mx` is `mixture`
|
||||
An alias of `mixture` is `mx`
|
||||
|
||||
### Validity
|
||||
#### Validity
|
||||
|
||||
Using javascript's variable arguments notation, consider `mx(...dists, weights)`:
|
||||
|
||||
- `dists.length == weights.length`
|
||||
|
||||
## Addition (horizontal right shift)
|
||||
### Addition (horizontal right shift)
|
||||
|
||||
<SquiggleEditor initialSquiggleString="dist1 = 1 to 10; dist2 = triangular(1,2,3); dist1 + dist2" />
|
||||
|
||||
## Subtraction (horizontal left shift)
|
||||
### Subtraction (horizontal left shift)
|
||||
|
||||
<SquiggleEditor initialSquiggleString="dist1 = 1 to 10; dist2 = triangular(1,2,3); dist1 - dist2" />
|
||||
|
||||
## Multiplication (??)
|
||||
### Multiplication (??)
|
||||
|
||||
<SquiggleEditor initialSquiggleString="dist1 = 1 to 10; dist2 = triangular(1,2,3); dist1 * dist2" />
|
||||
|
||||
## Division (???)
|
||||
We also provide concatenation of two distributions as a syntax sugar for `*`
|
||||
|
||||
<SquiggleEditor initialSquiggleString="(1e-1 to 1e0) triangular(1,2,3)" />
|
||||
|
||||
### Division (???)
|
||||
|
||||
<SquiggleEditor initialSquiggleString="dist1 = 1 to 10; dist2 = triangular(1,2,3); dist1 / dist2" />
|
||||
|
||||
## Taking the base `e` exponential
|
||||
### Exponentiation (???)
|
||||
|
||||
<SquiggleEditor initialSquiggleString="(1e-1 to 1e0) ^ cauchy(1e0, 1e0)" />
|
||||
|
||||
### Taking the base `e` exponential
|
||||
|
||||
<SquiggleEditor initialSquiggleString="dist = triangular(1,2,3); exp(dist)" />
|
||||
|
||||
## Taking the base `e` and base `10` logarithm
|
||||
### Taking logarithms
|
||||
|
||||
<SquiggleEditor initialSquiggleString="dist = triangular(1,2,3); log(dist)" />
|
||||
|
||||
<SquiggleEditor initialSquiggleString="dist = beta(1,2); log10(dist)" />
|
||||
|
||||
### Validity
|
||||
Base `x`
|
||||
|
||||
<SquiggleEditor initialSquiggleString="x = 2; dist = cauchy(1e0,1e0); log(dist, x)" />
|
||||
#### Validity
|
||||
|
||||
- `x` must be a scalar
|
||||
- See [the current discourse](https://github.com/quantified-uncertainty/squiggle/issues/304)
|
||||
|
||||
# Standard functions on distributions
|
||||
### Pointwise addition
|
||||
|
||||
## Probability density function
|
||||
**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" />
|
||||
|
||||
### 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" />
|
||||
|
||||
### Pointwise multiplication
|
||||
|
||||
<SquiggleEditor initialSquiggleString="dist1 = 1 to 10; dist2 = triangular(1,2,3); dist1 .* dist2" />
|
||||
|
||||
### Pointwise division
|
||||
|
||||
<SquiggleEditor initialSquiggleString="dist1 = 1 to 10; dist2 = triangular(1,2,3); dist1 ./ dist2" />
|
||||
|
||||
### Pointwise exponentiation
|
||||
|
||||
<SquiggleEditor initialSquiggleString="dist1 = 1 to 10; dist2 = triangular(1,2,3); dist1 .^ dist2" />
|
||||
|
||||
### Pointwise logarithm
|
||||
|
||||
TODO: write about the semantics and the case handling re scalar vs. dist and log base.
|
||||
|
||||
<SquiggleEditor initialSquiggleString="dist1 = 1 to 10; dist2 = triangular(1,2,3); dotLog(dist1, dist2)" />
|
||||
|
||||
## Standard functions on distributions
|
||||
|
||||
### Probability density function
|
||||
|
||||
The `pdf(dist, x)` function returns the density of a distribution at the
|
||||
given point x.
|
||||
|
||||
<SquiggleEditor initialSquiggleString="pdf(normal(0,1),0)" />
|
||||
|
||||
### Validity
|
||||
#### Validity
|
||||
|
||||
- `x` must be a scalar
|
||||
- `dist` must be a distribution
|
||||
|
||||
## Cumulative density function
|
||||
### 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`.
|
||||
|
||||
<SquiggleEditor initialSquiggleString="cdf(normal(0,1),0)" />
|
||||
|
||||
### Validity
|
||||
#### Validity
|
||||
|
||||
- `x` must be a scalar
|
||||
- `dist` must be a distribution
|
||||
|
||||
## Inverse CDF
|
||||
### 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)" />
|
||||
|
||||
### Validity
|
||||
#### Validity
|
||||
|
||||
- `prob` must be a scalar (please only put it in `(0,1)`)
|
||||
- `dist` must be a distribution
|
||||
|
||||
## Mean
|
||||
### Mean
|
||||
|
||||
The `mean(distribution)` function gives the mean (expected value) of a distribution.
|
||||
|
||||
<SquiggleEditor initialSquiggleString="mean(normal(5, 10))" />
|
||||
|
||||
## Sampling a distribution
|
||||
### Sampling a distribution
|
||||
|
||||
The `sample(distribution)` samples a given distribution.
|
||||
|
||||
<SquiggleEditor initialSquiggleString="sample(normal(0, 10))" />
|
||||
|
||||
# Normalization
|
||||
## Normalization
|
||||
|
||||
Some distribution operations (like horizontal shift) return an unnormalized distriibution.
|
||||
|
||||
We provide a `normalize` function
|
||||
|
||||
<SquiggleEditor initialSquiggleString="normalize((1e-1 to 1e0) + triangular(1e-1, 1e0, 1e1))" />
|
||||
### Valdity - Input to `normalize` must be a dist
|
||||
#### Validity - Input to `normalize` must be a dist
|
||||
|
||||
We provide a predicate `isNormalized`, for when we have simple control flow
|
||||
|
||||
<SquiggleEditor initialSquiggleString="isNormalized((1e-1 to 1e0) * triangular(1e-1, 1e0, 1e1))" />
|
||||
|
||||
### Validity
|
||||
#### Validity
|
||||
|
||||
- Input to `isNormalized` must be a dist
|
||||
|
||||
# Convert any distribution to a sample set distribution
|
||||
## Convert any distribution to a sample set distribution
|
||||
|
||||
`toSampleSet` has two signatures
|
||||
|
||||
|
|
@ -234,7 +278,7 @@ And binary when you provide a number of samples (floored)
|
|||
|
||||
<SquiggleEditor initialSquiggleString="toSampleSet(1e-1 to 1e0, 1e2)" />
|
||||
|
||||
# `inspect`
|
||||
## `inspect`
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -242,7 +286,7 @@ You may like to debug by right clicking your browser and using the _inspect_ fun
|
|||
|
||||
Save for a logging side effect, `inspect` does nothing to input and returns it.
|
||||
|
||||
# Truncate
|
||||
## Truncate
|
||||
|
||||
You can cut off from the left
|
||||
|
||||
|
|
|
|||
|
|
@ -11,13 +11,13 @@ Invariants to check with property tests.
|
|||
|
||||
_This document right now is normative and aspirational, not a description of the testing that's currently done_.
|
||||
|
||||
# Algebraic combinations
|
||||
## Algebraic combinations
|
||||
|
||||
The academic keyword to search for in relation to this document is "[algebra of random variables](https://wikiless.org/wiki/Algebra_of_random_variables?lang=en)". Squiggle doesn't yet support getting the standard deviation, denoted by $\sigma$, but such support could yet be added.
|
||||
|
||||
## Means and standard deviations
|
||||
### Means and standard deviations
|
||||
|
||||
### Sums
|
||||
#### Sums
|
||||
|
||||
$$
|
||||
mean(f+g) = mean(f) + mean(g)
|
||||
|
|
@ -33,7 +33,7 @@ $$
|
|||
mean(normal(a,b) + normal(c,d)) = mean(normal(a+c, \sqrt{b^2 + d^2}))
|
||||
$$
|
||||
|
||||
### Subtractions
|
||||
#### Subtractions
|
||||
|
||||
$$
|
||||
mean(f-g) = mean(f) - mean(g)
|
||||
|
|
@ -43,7 +43,7 @@ $$
|
|||
\sigma(f-g) = \sqrt{\sigma(f)^2 + \sigma(g)^2}
|
||||
$$
|
||||
|
||||
### Multiplications
|
||||
#### Multiplications
|
||||
|
||||
$$
|
||||
mean(f \cdot g) = mean(f) \cdot mean(g)
|
||||
|
|
@ -53,15 +53,15 @@ $$
|
|||
\sigma(f \cdot g) = \sqrt{ (\sigma(f)^2 + mean(f)) \cdot (\sigma(g)^2 + mean(g)) - (mean(f) \cdot mean(g))^2}
|
||||
$$
|
||||
|
||||
### Divisions
|
||||
#### Divisions
|
||||
|
||||
Divisions are tricky, and in general we don't have good expressions to characterize properties of ratios. In particular, the ratio of two normals is a Cauchy distribution, which doesn't have to have a mean.
|
||||
|
||||
## Probability density functions (pdfs)
|
||||
### Probability density functions (pdfs)
|
||||
|
||||
Specifying the pdf of the sum/multiplication/... of distributions as a function of the pdfs of the individual arguments can still be done. But it requires integration. My sense is that this is still doable, and I (Nuño) provide some _pseudocode_ to do this.
|
||||
|
||||
### Sums
|
||||
#### Sums
|
||||
|
||||
Let $f, g$ be two independently distributed functions. Then, the pdf of their sum, evaluated at a point $z$, expressed as $(f + g)(z)$, is given by:
|
||||
|
||||
|
|
@ -114,31 +114,31 @@ let pdfOfSum = (pdf1, pdf2, cdf1, cdf2, z) => {
|
|||
};
|
||||
```
|
||||
|
||||
## Cumulative density functions
|
||||
### Cumulative density functions
|
||||
|
||||
TODO
|
||||
|
||||
## Inverse cumulative density functions
|
||||
### Inverse cumulative density functions
|
||||
|
||||
TODO
|
||||
|
||||
# `pdf`, `cdf`, and `inv`
|
||||
## `pdf`, `cdf`, and `inv`
|
||||
|
||||
With $\forall dist, pdf := x \mapsto \texttt{pdf}(dist, x) \land cdf := x \mapsto \texttt{cdf}(dist, x) \land inv := p \mapsto \texttt{inv}(dist, p)$,
|
||||
|
||||
## `cdf` and `inv` are inverses
|
||||
### `cdf` and `inv` are inverses
|
||||
|
||||
$$
|
||||
\forall x \in (0,1), cdf(inv(x)) = x \land \forall x \in \texttt{dom}(cdf), x = inv(cdf(x))
|
||||
$$
|
||||
|
||||
## The codomain of `cdf` equals the open interval `(0,1)` equals the codomain of `pdf`
|
||||
### The codomain of `cdf` equals the open interval `(0,1)` equals the codomain of `pdf`
|
||||
|
||||
$$
|
||||
\texttt{cod}(cdf) = (0,1) = \texttt{cod}(pdf)
|
||||
$$
|
||||
|
||||
# To do:
|
||||
## To do:
|
||||
|
||||
- Provide sources or derivations, useful as this document becomes more complicated
|
||||
- Provide definitions for the probability density function, exponential, inverse, log, etc.
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user