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

---
title: "Functions Reference"
sidebar_position: 7
---

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

## Operating on distributions

Here are the ways we combine distributions.

### Addition

A horizontal right shift

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

### Subtraction

A horizontal left shift

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

### Multiplication

TODO: provide intuition pump for the semantics

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

We also provide concatenation of two distributions as a syntax sugar for `*`

<SquiggleEditor initialSquiggleString="(0.1 to 1) triangular(1,2,3)" />

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

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

### Taking the base `e` exponential

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

### Taking logarithms

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

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

Base `x`

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

#### Validity

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

### 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`}
/>

### 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 = uniform(0,20)
dist2 = normal(10,8)
dist1 ./ dist2`}
/>

### Pointwise exponentiation

<SquiggleEditor
  initialSquiggleString={`dist1 = 1 to 10
dist2 = triangular(1,2,3)
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

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

## 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))" />

### `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)" />

#### 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))" />

#### 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))" />

#### 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))" />

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

## Truncate

You can cut off from the left

<SquiggleEditor initialSquiggleString="truncateLeft(0.1 to 1, 0.5)" />

You can cut off from the right

<SquiggleEditor initialSquiggleString="truncateRight(0.1 to 1, 10)" />

You can cut off from both sides

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