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

---
title: Functions reference
sidebar_position: 7
---

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

We provide starter distributions, computed symbolically. 

## Normal distribution

The `normal(mean, sd)` function creates a normal distribution with the given mean
and standard deviation.

<SquiggleEditor initialSquiggleString="normal(5, 1)" />

### Validity
- `sd > 0`

## Uniform distribution

The `uniform(low, high)` function creates a uniform distribution between the
two given numbers.

<SquiggleEditor initialSquiggleString="uniform(3, 7)" />

### Validity
- `low < high`

## 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`.

<SquiggleEditor initialSquiggleString="lognormal(0, 0.7)" />

An alternative format is also available. The `to` notation creates a lognormal
distribution with a 90% confidence interval between the two numbers. We add
this convinience as lognormal distributions are commonly used in practice.

<SquiggleEditor initialSquiggleString="2 to 10" />

### 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
- `sigma > 0`
- In `x to y` notation, `x < y`

## Beta distribution

The `beta(a, b)` function creates a beta distribution with parameters `a` and `b`:

<SquiggleEditor initialSquiggleString="beta(20, 20)" />

### Validity
- `a > 0`
- `b > 0`
- Empirically, we have noticed that numerical instability arises when `a < 1` or `b < 1`

## Exponential distribution

The `exponential(rate)` function creates an exponential distribution with the given
rate.

<SquiggleEditor initialSquiggleString="exponential(1)" />

### Validity
- `rate > 0`

## Triangular distribution

The `triangular(a,b,c)` function creates a triangular distribution with lower
bound `a`, mode `b` and upper bound `c`.

### Validity
- `a < b < c`

<SquiggleEditor initialSquiggleString="triangular(1, 2, 4)" />

## Scalar (constant dist)

Squiggle, when the context is right, automatically casts a float to a constant distribution. 

# Operating on distributions

Here are the ways we combine distributions. 

## Mixture of distributions

The `mx` 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])" />

It's possible to create discrete distributions using this method.

<SquiggleEditor initialSquiggleString="mx(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])" />

An alias of `mx` is `mixture` 

### Validity
Using javascript's variable arguments notation, consider `mx(...dists, weights)`: 
- `dists.length == weights.length`

## Addition (horizontal right shift)

<SquiggleEditor initialSquiggleString="dist1 = 1 to 10; dist2 = triangular(1,2,3); dist1 + dist2">

## Subtraction (horizontal left shift)

<SquiggleEditor initialSquiggleString="dist1 = 1 to 10; dist2 = triangular(1,2,3); dist1 - dist2">

## Multiplication (??) 

<SquiggleEditor initialSquiggleString="dist1 = 1 to 10; dist2 = triangular(1,2,3); dist1 * dist2">

## Division (???)

<SquiggleEditor initialSquiggleString="dist1 = 1 to 10; dist2 = triangular(1,2,3); dist1 / dist2">

## Taking the base `e` exponential

<SquiggleEditor initialSquiggleString="dist = triangular(1,2,3); exp(dist)">

## Taking the base `e` and base `10` logarithm 

<SquiggleEditor initialSquiggleString="dist = triangular(1,2,3); log(dist)">

<SquiggleEditor initialSquiggleString="dist = beta(1,2); log10(dist)">

### Validity
- See [the current discourse](https://github.com/quantified-uncertainty/squiggle/issues/304)

# 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
- `x` must be a scalar
- `dist` must be a distribution

## 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
- `x` must be a scalar
- `dist` must be a distribution

## 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
- `prob` must be a scalar (please only put it in `(0,1)`)
- `dist` must be a distribution

## Mean

The `mean(distribution)` function gives the mean (expected value) of a distribution.

<SquiggleEditor initialSquiggleString="mean(normal(5, 10))" />

## Sampling a distribution

The `sample(distribution)` samples a given distribution.

<SquiggleEditor initialSquiggleString="sample(normal(0, 10))" />

# 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

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 
- Input to `isNormalized` must be a dist

# 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(1e-1 to 1e0)" />

And binary when you provide a number of samples (truncated)

<SquiggleEditor initialSquiggleString="toSampleSet(1e-1 to 1e0, 1e2)" />