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

---
title: "Distributions: Creation"
sidebar_position: 2
---

import { SquiggleEditor } from "../../src/components/SquiggleEditor";
import Admonition from "@theme/Admonition";
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

## To

`(5thPercentile: number) to (95thPercentile: number)`  
`to(5thPercentile: number, 95thPercentile: number)`

The `to` function is an easy way to generate simple distributions using predicted _5th_ and _95th_ percentiles.

If both values are above zero, a `lognormal` distribution is used. If not, a `normal` distribution is used.

<Tabs lazy>
  <TabItem value="ex1" label="5 to 10" default>
    When <code>5 to 10</code> is entered, both numbers are positive, so it
    generates a lognormal distribution with 5th and 95th percentiles at 5 and
    10.
    <SquiggleEditor defaultCode="5 to 10" />
  </TabItem>
  <TabItem value="ex3" label="to(5,10)">
    <code>5 to 10</code> does the same thing as <code>to(5,10)</code>.
    <SquiggleEditor defaultCode="to(5,10)" />
  </TabItem>
  <TabItem value="ex2" label="-5 to 5">
    When <code>-5 to 5</code> is entered, there's negative values, so it
    generates a normal distribution. This has 5th and 95th percentiles at 5 and
    10.
    <SquiggleEditor defaultCode="-5 to -3" />
  </TabItem>
  <TabItem value="ex4" label="1 to 10000">
    It's very easy to generate distributions with very long tails. These can be
    impossible to see without changing view settings. (These settings are
    available in the Playground, but not this smaller editor component)
    <SquiggleEditor defaultCode="1 to 10000" />
  </TabItem>
</Tabs>

### Arguments

- `5thPercentile`: number
- `95thPercentile`: number, greater than `5thPercentile`

<Admonition type="tip" title="Tip">
  <p>
    "<bold>To</bold>" is a great way to generate probability distributions very
    quickly from your intuitions. It's easy to write and easy to read. It's
    often a good place to begin an estimate.
  </p>
</Admonition>

<Admonition type="caution" title="Caution">
  <p>
    If you haven't tried{" "}
    <a href="https://www.lesswrong.com/posts/LdFbx9oqtKAAwtKF3/list-of-probability-calibration-exercises">
      calibration training
    </a>
    , you're likely to be overconfident. We recommend doing calibration training
    to get a feel for what a 90 percent confident interval feels like.
  </p>
</Admonition>

## Mixture

`mixture(...distributions: Distribution[], weights?: number[])`  
`mx(...distributions: Distribution[], weights?: number[])`  
`mixture(distributions: Distributions[], weights?: number[])`  
`mx(distributions: Distributions[], weights?: number[])`

The `mixture` mixes combines multiple distributions to create a mixture. You can optionally pass in a list of proportional weights.

<Tabs lazy>
  <TabItem value="ex1" label="Simple" default>
    <SquiggleEditor defaultCode="mixture(1 to 2, 5 to 8, 9 to 10)" />
  </TabItem>
  <TabItem value="ex2" label="With Weights">
    <SquiggleEditor defaultCode="mixture(1 to 2, 5 to 8, 9 to 10, [0.1, 0.1, 0.8])" />
  </TabItem>
  <TabItem value="ex3" label="With Continuous and Discrete Inputs">
    <SquiggleEditor defaultCode="mixture(1 to 5, 8 to 10, 1, 3, 20)" />
  </TabItem>
  <TabItem value="ex4" label="Array of Distributions Input">
    <SquiggleEditor defaultCode="mx([1 to 2, exponential(1)], [1,1])" />
  </TabItem>
</Tabs>

### Arguments

- `distributions`: A set of distributions or numbers, each passed as a paramater. Numbers will be converted into point mass distributions.
- `weights`: An optional array of numbers, each representing the weight of its corresponding distribution. The weights will be re-scaled to add to `1.0`. If a weights array is provided, it must be the same length as the distribution paramaters.

### Aliases

- `mx`

### Special Use Cases of Mixtures

<details>
  <summary>🕐 Zero or Continuous</summary>
  <p>
    One common reason to have mixtures of continous and discrete distributions is to handle the special case of 0.
    Say I want to model the time I will spend on some upcoming project. I think I have an 80% chance of doing it.
  </p>

  <p>
    In this case, I have a 20% chance of spending 0 time with it. I might estimate my hours with,
  </p>
  <Admonition type="caution" title="Caution">
    <p>
      There's a temporary bug where the below render is compressed. If you toggle the code it will fix render correctly.
    </p>
  </Admonition>
  <SquiggleEditor
    defaultCode={`hours_the_project_will_take = 5 to 20
chance_of_doing_anything = 0.8
mx(hours_the_project_will_take, 0, [chance_of_doing_anything, 1 - chance_of_doing_anything])`}
  />
</details>

<details>
  <summary>🔒 Model Uncertainty Safeguarding</summary>
  <p>
  One technique several <a href="https://www.foretold.io/">Foretold.io</a> users used is to combine their main guess, with a
  "just-in-case distribution". This latter distribution would have very low weight, but would be
  very wide, just in case they were dramatically off for some weird reason.
  </p>
<SquiggleEditor
  defaultCode={`forecast = 3 to 30
chance_completely_wrong = 0.05
forecast_if_completely_wrong = -100 to 200
mx(forecast, forecast_if_completely_wrong, [1-chance_completely_wrong, chance_completely_wrong])`}
/>

</details>

## Normal

`normal(mean:number, standardDeviation:number)`

Creates a [normal distribution](https://en.wikipedia.org/wiki/Normal_distribution) with the given mean and standard deviation.

<Tabs lazy>
  <TabItem value="ex1" label="normal(5,1)" default>
    <SquiggleEditor defaultCode="normal(5, 1)" />
  </TabItem>
  <TabItem value="ex2" label="normal(1G, 1G)">
    <SquiggleEditor defaultCode="normal(1G, 1G)" />
  </TabItem>
</Tabs>

### Arguments

- `mean`: Number
- `standard deviation`: Number greater than zero

[Wikipedia](https://en.wikipedia.org/wiki/Normal_distribution)

## Log-normal

`lognormal(mu: number, sigma: number)`

Creates a [log-normal distribution](https://en.wikipedia.org/wiki/Log-normal_distribution) with the given mu and sigma.

`Mu` and `sigma` represent the mean and standard deviation of the normal which results when
you take the log of our lognormal distribution. They can be difficult to directly reason about.
Because of this complexity, we recommend typically using the <a href="#to">to</a> syntax instead of estimating `mu` and `sigma` directly.

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

### Arguments

- `mu`: Number
- `sigma`: Number greater than zero

[Wikipedia](https://en.wikipedia.org/wiki/Log-normal_distribution)

<details>
  <summary>
    ❓ Understanding <bold>mu</bold> and <bold>sigma</bold>
  </summary>
  <p>
    The log of <code>lognormal(mu, sigma)</code> is a normal distribution with
    mean <code>mu</code>
    and standard deviation <code>sigma</code>. For example, these two distributions
    are identical:
  </p>
  <SquiggleEditor
    defaultCode={`normalMean = 10
normalStdDev = 2
logOfLognormal = log(lognormal(normalMean, normalStdDev))
[logOfLognormal, normal(normalMean, normalStdDev)]`}
  />
</details>

## Uniform

`uniform(low:number, high:number)`

Creates a [uniform distribution](<https://en.wikipedia.org/wiki/Uniform_distribution_(continuous)>) with the given low and high values.

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

### Arguments

- `low`: Number
- `high`: Number greater than `low`

<Admonition type="caution" title="Caution">
  <p>
    While uniform distributions are very simple to understand, we find it rare
    to find uncertainties that actually look like this. Before using a uniform
    distribution, think hard about if you are really 100% confident that the
    paramater will not wind up being just outside the stated boundaries.
  </p>

  <p>
    One good example of a uniform distribution uncertainty would be clear
    physical limitations. You might have complete complete uncertainty on what
    time of day an event will occur, but can say with 100% confidence it will
    happen between the hours of 0:00 and 24:00.
  </p>
</Admonition>

## Point Mass

`pointMass(value:number)`

Creates a discrete distribution with all of its probability mass at point `value`.

Few Squiggle users call the function `pointMass()` directly. Numbers are converted into point mass distributions automatically, when it is appropriate.

For example, in the function `mixture(1,2,normal(5,2))`, the first two arguments will get converted into point mass distributions
with values at 1 and 2. Therefore, this is the same as `mixture(pointMass(1),pointMass(2),pointMass(5,2))`.

`pointMass()` distributions are currently the only discrete distributions accessible in Squiggle.

<Tabs lazy>
  <TabItem value="ex1" label="pointMass(3)" default>
    <SquiggleEditor defaultCode="pointMass(3)" />
  </TabItem>
  <TabItem value="ex3" label="mixture(1,3,5)">
    <SquiggleEditor defaultCode="mixture(1,3,5)" />
  </TabItem>
  <TabItem value="ex2" label="normal(5,2) * 6">
    <SquiggleEditor defaultCode="normal(5,2) * 6" />
  </TabItem>
  <TabItem value="ex4" label="dotAdd(normal(5,2), 6)">
    <SquiggleEditor defaultCode="dotAdd(normal(5,2), 6)" />
  </TabItem>
  <TabItem value="ex5" label="dotMultiply(normal(5,2), 6)">
    <SquiggleEditor defaultCode="dotMultiply(normal(5,2), 6)" />
  </TabItem>
</Tabs>

### Arguments

- `value`: Number

## Beta

`beta(alpha:number, beta:number)`
`beta({mean: number, stdev: number})`

Creates a [beta distribution](https://en.wikipedia.org/wiki/Beta_distribution) with the given `alpha` and `beta` values. For a good summary of the beta distribution, see [this explanation](https://stats.stackexchange.com/a/47782) on Stack Overflow.

<Tabs lazy>
  <TabItem value="ex1" label="beta(10, 20)" default>
    <SquiggleEditor defaultCode="beta(10,20)" />
  </TabItem>
  <TabItem value="ex2" label="beta(1000, 1000)">
    <SquiggleEditor defaultCode="beta(1000, 2000)" />
  </TabItem>
  <TabItem value="ex3" label="beta(1, 10)">
    <SquiggleEditor defaultCode="beta(1, 10)" />
  </TabItem>
  <TabItem value="ex4" label="beta(10, 1)">
    <SquiggleEditor defaultCode="beta(10, 1)" />
  </TabItem>
  <TabItem value="ex5" label="beta(0.8, 0.8)">
    <SquiggleEditor defaultCode="beta(0.8, 0.8)" />
  </TabItem>
  <TabItem value="ex6" label="beta({mean: 0.39, stdev: 0.1})">
    <SquiggleEditor defaultCode="beta({mean: 0.39, stdev: 0.1})" />
  </TabItem>
</Tabs>

### Arguments

- `alpha`: Number greater than zero
- `beta`: Number greater than zero

<Admonition type="caution" title="Caution with small numbers">
  <p>
    Squiggle struggles to show beta distributions when either alpha or beta are
    below 1.0. This is because the tails at ~0.0 and ~1.0 are very high. Using a
    log scale for the y-axis helps here.
  </p>
  <details>
    <summary>Examples</summary>
    <Tabs lazy>
      <TabItem value="ex1" label="beta(0.3, 0.3)" default>
        <SquiggleEditor defaultCode="beta(0.3, 0.3)" />
      </TabItem>
      <TabItem value="ex2" label="beta(0.5, 0.5)">
        <SquiggleEditor defaultCode="beta(0.5, 0.5)" />
      </TabItem>
      <TabItem value="ex3" label="beta(0.8, 0.8)">
        <SquiggleEditor defaultCode="beta(.8,.8)" />
      </TabItem>
      <TabItem value="ex4" label="beta(0.9, 0.9)">
        <SquiggleEditor defaultCode="beta(.9,.9)" />
      </TabItem>
    </Tabs>
  </details>
</Admonition>

## Exponential

`exponential(rate:number)`

Creates an [exponential distribution](https://en.wikipedia.org/wiki/Exponential_distribution) with the given rate.

<SquiggleEditor defaultCode="exponential(4)" />

### Arguments

- `rate`: Number greater than zero

## Triangular distribution

`triangular(low:number, mode:number, high:number)`

Creates a [triangular distribution](https://en.wikipedia.org/wiki/Triangular_distribution) with the given low, mode, and high values.

### Arguments

- `low`: Number
- `mode`: Number greater than `low`
- `high`: Number greater than `mode`

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

## SampleSet.fromList

`SampleSet.fromList(samples:number[])`

Creates a sample set distribution using an array of samples.

<SquiggleEditor defaultCode="SampleSet.fromList([1,2,3,4,6,5,5,5])" />

### Arguments

- `samples`: An array of at least 5 numbers.

<Admonition type="caution" title="Caution!">
  <p>
    Samples are converted into{" "}
    <a href="https://en.wikipedia.org/wiki/Probability_density_function">PDF</a>{" "}
    shapes automatically using{" "}
    <a href="https://en.wikipedia.org/wiki/Kernel_density_estimation">
      kernel density estimation
    </a>{" "}
    and an approximated bandwidth. Eventually Squiggle will allow for more
    specificity.
  </p>
</Admonition>

## PointSet.makeContinuous

`PointSet.makeContinuous(points:{x: number, y: number})`

Creates a continuous point set distribution using a list of points.

<SquiggleEditor
  defaultCode={`PointSet.makeContinuous([
  { x: 0, y: 0.1 },
  { x: 1, y: 0.2 },
  { x: 2, y: 0.15 },
  { x: 3, y: 0.1 }
])`}
/>

### Arguments

- `points`: An array of at least 3 coordinates.

## PointSet.makeDiscrete

`PointSet.makeDiscrete(points:{x: number, y: number})`

Creates a discrete point set distribution using a list of points.

<SquiggleEditor
  defaultCode={`PointSet.makeDiscrete([
  { x: 0, y: 0.1 },
  { x: 1, y: 0.2 },
  { x: 2, y: 0.15 },
  { x: 3, y: 0.1 }
])`}
/>

### Arguments

- `points`: An array of at least 1 coordinate.