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

---
title: "Distribution Functions"
sidebar_position: 3
---

import { SquiggleEditor } from "../../src/components/SquiggleEditor";

## Operating on distributions

Here are the ways we combine distributions.

### Addition

A horizontal right shift. The addition operation represents the distribution of the sum of
the value of one random sample chosen from the first distribution and the value one random sample
chosen from the second distribution.

<SquiggleEditor
  initialSquiggleString={`dist1 = 1 to 10
dist2 = triangular(1,2,3)
dist1 + dist2`}
  height={60}
/>

### Subtraction

A horizontal left shift. A horizontal right shift. The substraction operation represents
the distribution of the value of one random sample chosen from the first distribution minus
the value of one random sample chosen from the second distribution.

<SquiggleEditor
  initialSquiggleString={`dist1 = 1 to 10
dist2 = triangular(1,2,3)
dist1 - dist2`}
  height={60}
/>

### Multiplication

A proportional scaling. The addition operation represents the distribution of the multiplication of
the value of one random sample chosen from the first distribution times the value one random sample
chosen from the second distribution.

<SquiggleEditor
  initialSquiggleString={`dist1 = 1 to 10
dist2 = triangular(1,2,3)
dist1 * dist2`}
  height={60}
/>

### Division

A proportional scaling (normally a shrinking if the second distribution has values higher than 1).
The addition operation represents the distribution of the division of
the value of one random sample chosen from the first distribution over the value one random sample
chosen from the second distribution. If the second distribution has some values near zero, it
tends to be particularly unstable.

<SquiggleEditor
  initialSquiggleString={`dist1 = 1 to 10
dist2 = triangular(1,2,3)
dist1 / dist2`}
  height={60}
/>

### Exponentiation

A projection over a contracted x-axis. The exponentiation operation represents the distribution of
the exponentiation of the value of one random sample chosen from the first distribution to the power of
the value one random sample chosen from the second distribution.

<SquiggleEditor initialSquiggleString={`(0.1 to 1) ^ beta(2, 3)`} height={60} />

### Taking the base `e` exponential

<SquiggleEditor
  initialSquiggleString={`dist = triangular(1,2,3)
exp(dist)`}
  height={60}
/>

### Taking logarithms

A projection over a stretched x-axis.

<SquiggleEditor
  initialSquiggleString={`dist = triangular(1,2,3)
log(dist)`}
  height={60}
/>

<SquiggleEditor
  initialSquiggleString={`dist = beta(1,2)+1
log10(dist)`}
  height={60}
/>

Base `x`

<SquiggleEditor
  initialSquiggleString={`x = 2
dist = beta(2,3)+1
log(dist, x)`}
  height={60}
/>

#### Validity

- `x` must be a scalar
- See [the current discourse](https://github.com/quantified-uncertainty/squiggle/issues/304)

### Pointwise addition

For every point on the x-axis, operate the corresponding points in the y axis of the pdf.

**Pointwise operations are done with `PointSetDist` internals rather than `SampleSetDist` internals**.

<SquiggleEditor
  initialSquiggleString={`dist1 = 1 to 10
dist2 = triangular(1,2,3)
dist1 .+ dist2`}
  height={60}
/>

### Pointwise subtraction

<SquiggleEditor
  initialSquiggleString={`dist1 = 1 to 10
dist2 = triangular(1,2,3)
dist1 .- dist2`}
  height={60}
/>

### Pointwise multiplication

<SquiggleEditor
  initialSquiggleString={`dist1 = 1 to 10
dist2 = triangular(1,2,3)
dist1 .* dist2`}
  height={60}
/>

### Pointwise division

<SquiggleEditor
  initialSquiggleString={`dist1 = uniform(0,20)
dist2 = normal(10,8)
dist1 ./ dist2`}
  height={60}
/>

### Pointwise exponentiation

<SquiggleEditor
  initialSquiggleString={`dist1 = 1 to 10
dist2 = triangular(1,2,3)
dist1 .^ dist2`}
  height={60}
/>

## 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)" height={60} />

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

<SquiggleEditor initialSquiggleString="cdf(normal(0,1),0)" height={60} />

#### Validity

- `x` must be a scalar
- `dist` must be a distribution

### Quantile

The `quantile(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`. In the literature, it
is also known as the quantiles function.

<SquiggleEditor initialSquiggleString="quantile(normal(0,1),0.5)" height={60} />

#### 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))" height={60} />

### Sampling a distribution

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

<SquiggleEditor initialSquiggleString="sample(normal(0, 10))" height={60} />

## 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))"
  height={60}
/>

Or `PointSet` format

<SquiggleEditor initialSquiggleString="toPointSet(normal(5, 10))" height={60} />

### `toSampleSet` has two signatures

Above, we saw the unary `toSampleSet`, which uses an internal hardcoded number of samples. If you'd like to provide the number of samples, it has a binary signature as well (floored)

<SquiggleEditor
  initialSquiggleString="[toSampleSet(0.1 to 1, 100.1), toSampleSet(0.1 to 1, 5000), toSampleSet(0.1 to 1, 20000)]"
  height={60}
/>

#### Validity

- Second argument to `toSampleSet` must be a number.

## Normalization

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))"
  height={60}
/>

#### Validity - Input to `normalize` must be a dist

We provide a predicate `isNormalized`, for when we have simple control flow

<SquiggleEditor
  initialSquiggleString="isNormalized((0.1 to 1) * triangular(0.1, 1, 10))"
  height={60}
/>

#### Validity

- Input to `isNormalized` must be a dist

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

<SquiggleEditor
  initialSquiggleString="inspect(toSampleSet(0.1 to 1, 100))"
  height={60}
/>

Save for a logging side effect, `inspect` does nothing to input and returns it.

## Truncate

You can truncate the left side, the right side, or both.

<SquiggleEditor
  initialSquiggleString="truncateLeft(0.1 to 1, 0.5)"
  height={40}
/>

<SquiggleEditor
  initialSquiggleString="truncateRight(0.1 to 1, 0.5)"
  height={40}
/>

<SquiggleEditor
  initialSquiggleString="truncate(0.1 to 1, 0.5, 1.5)"
  height={40}
/>