quantified.uncertainty/squiggle
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #449 from quantified-uncertainty/documentation-refactors-april

Browse Source 
Documentation refactors april
This commit is contained in:
Ozzie Gooen 2022-05-03 19:30:14 -04:00 committed by GitHub
commit 4e49c5d81a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 418 additions and 162 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
packages/squiggle-lang/src/rescript/Distributions/SymbolicDist/SymbolicDist.res
View File

@ -219,12 +219,18 @@ module Uniform = {
module Float = { module Float = {
type t = float type t = float
let make = t => #Float(t) let make = t => #Float(t)
let makeSafe = t =>
if E.Float.isFinite(t) {
Ok(#Float(t))
} else {
Error("Float must be finite")
}
let pdf = (x, t: t) => x == t ? 1.0 : 0.0 let pdf = (x, t: t) => x == t ? 1.0 : 0.0
let cdf = (x, t: t) => x >= t ? 1.0 : 0.0 let cdf = (x, t: t) => x >= t ? 1.0 : 0.0
let inv = (p, t: t) => p < t ? 0.0 : 1.0 let inv = (p, t: t) => p < t ? 0.0 : 1.0
let mean = (t: t) => Ok(t) let mean = (t: t) => Ok(t)
let sample = (t: t) => t let sample = (t: t) => t
let toString = Js.Float.toString let toString = (t: t) => j`Delta($t)`
} }
module From90thPercentile = { module From90thPercentile = {

6
packages/squiggle-lang/src/rescript/ReducerInterface/ReducerInterface_GenericDistribution.res
View File

@ -178,10 +178,12 @@ let dispatchToGenericOutput = (call: ExpressionValue.functionCall, _environment)
> => { > => {
let (fnName, args) = call let (fnName, args) = call
switch (fnName, args) { switch (fnName, args) {
| ("exponential" as fnName, [EvNumber(f1)]) => | ("exponential" as fnName, [EvNumber(f)]) =>
SymbolicConstructors.oneFloat(fnName) SymbolicConstructors.oneFloat(fnName)
->E.R.bind(r => r(f1)) ->E.R.bind(r => r(f))
->SymbolicConstructors.symbolicResultToOutput ->SymbolicConstructors.symbolicResultToOutput
| ("delta", [EvNumber(f)]) =>
SymbolicDist.Float.makeSafe(f)->SymbolicConstructors.symbolicResultToOutput
| ( | (
("normal" | "uniform" | "beta" | "lognormal" | "cauchy" | "to") as fnName, ("normal" | "uniform" | "beta" | "lognormal" | "cauchy" | "to") as fnName,
[EvNumber(f1), EvNumber(f2)], [EvNumber(f1), EvNumber(f2)],

1
packages/squiggle-lang/src/rescript/Utility/E.res
View File

@ -198,6 +198,7 @@ module Float = {
let with3DigitsPrecision = Js.Float.toPrecisionWithPrecision(_, ~digits=3) let with3DigitsPrecision = Js.Float.toPrecisionWithPrecision(_, ~digits=3)
let toFixed = Js.Float.toFixed let toFixed = Js.Float.toFixed
let toString = Js.Float.toString let toString = Js.Float.toString
let isFinite = Js.Float.isFinite
} }
module I = { module I = {

19
packages/website/docs/Discussions/Three-Formats-Of-Distributions.md
View File

@ -11,7 +11,7 @@ _Symbolic_ formats are just the math equations. `normal(5,3)` is the symbolic re
When you sample distributions (usually starting with symbolic formats), you get lists of samples. Monte Carlo techniques return lists of samples. Let’s call this the “_Sample Set_” format. When you sample distributions (usually starting with symbolic formats), you get lists of samples. Monte Carlo techniques return lists of samples. Let’s call this the “_Sample Set_” format.
Lastly is what I’ll refer to as the _Graph_ format. It describes the coordinates, or the shape, of the distribution. You can save these formats in JSON, for instance, like, `{xs: [1, 2, 3, 4…], ys: [.0001, .0003, .002, …]}`. Lastly is what I’ll refer to as the _Graph_ format. It describes the coordinates, or the shape, of the distribution. You can save these formats in JSON, for instance, like, `{xs: [1, 2, 3, 4, …], ys: [.0001, .0003, .002, …]}`.
Symbolic, Sample Set, and Graph formats all have very different advantages and disadvantages. Symbolic, Sample Set, and Graph formats all have very different advantages and disadvantages.
@ -19,7 +19,7 @@ Note that the name "Symbolic" is fairly standard, but I haven't found common nam
## Symbolic Formats ## Symbolic Formats
**TLDR** **TL;DR**
Mathematical representations. Require analytic solutions. These are often ideal where they can be applied, but apply to very few actual functions. Typically used sparsely, except for the starting distributions (before any computation is performed). Mathematical representations. Require analytic solutions. These are often ideal where they can be applied, but apply to very few actual functions. Typically used sparsely, except for the starting distributions (before any computation is performed).
**Examples** **Examples**
@ -29,9 +29,6 @@ Mathematical representations. Require analytic solutions. These are often ideal
**How to Do Computation** **How to Do Computation**
To perform calculations of symbolic systems, you need to find analytical solutions. For example, there are equations to find the pdf or cdf of most distribution shapes at any point. There are also lots of simplifications that could be done in particular situations. For example, there’s an analytical solution for combining normal distributions. To perform calculations of symbolic systems, you need to find analytical solutions. For example, there are equations to find the pdf or cdf of most distribution shapes at any point. There are also lots of simplifications that could be done in particular situations. For example, there’s an analytical solution for combining normal distributions.
**Special: The Metalog Distribution**
The Metalog distribution seems like it can represent almost any reasonable distribution. It’s symbolic. This is great for storage, but it’s not clear if it helps with calculation. My impression is that we don’t have symbolic ways of doing most functions (addition, multiplication, etc) on metalog distributions. Also, note that it can take a fair bit of computation to fit a shape to the Metalog distribution.
**Advantages** **Advantages**
- Maximally compressed; i.e. very easy to store. - Maximally compressed; i.e. very easy to store.
@ -54,10 +51,14 @@ The Metalog distribution seems like it can represent almost any reasonable distr
**How to Visualize** **How to Visualize**
Convert to graph, then display that. (Optionally, you can also convert to samples, then display those using a histogram, but this is often worse you have both options.) Convert to graph, then display that. (Optionally, you can also convert to samples, then display those using a histogram, but this is often worse you have both options.)
**Bonus: The Metalog Distribution**
The Metalog distribution seems like it can represent almost any reasonable distribution. It’s symbolic. This is great for storage, but it’s not clear if it helps with calculation. My impression is that we don’t have symbolic ways of doing most functions (addition, multiplication, etc) on metalog distributions. Also, note that it can take a fair bit of computation to fit a shape to the Metalog distribution.
## Graph Formats ## Graph Formats
**TLDR** **TL;DR**
Lists of the x-y coordinates of the shape of a distribution. (Usually the pdf, which is more compressed than the cdf). Some key functions (like pdf, cdf) and manipulations can work on almost any graphally-described distribution. Lists of the x-y coordinates of the shape of a distribution. (Usually the pdf, which is more compressed than the cdf). Some key functions (like pdf, cdf) and manipulations can work on almost any graphically-described distribution.
**Alternative Names:** **Alternative Names:**
Grid, Mesh, Graph, Vector, Pdf, PdfCoords/PdfPoints, Discretised, Bezier, Curve Grid, Mesh, Graph, Vector, Pdf, PdfCoords/PdfPoints, Discretised, Bezier, Curve
@ -77,7 +78,7 @@ Use graph techniques. These can be fairly computationally-intensive (particularl
**Disadvantages** **Disadvantages**
- Most calculations are infeasible/impossible to perform graphally. In these cases, you need to use sampling. - Most calculations are infeasible/impossible to perform graphically. In these cases, you need to use sampling.
- Not as accurate or fast as symbolic methods, where the symbolic methods are applicable. - Not as accurate or fast as symbolic methods, where the symbolic methods are applicable.
- The tails get cut off, which is subideal. It’s assumed that the value of the pdf outside of the bounded range is exactly 0, which is not correct. (Note: If you have ideas on how to store graph formats that don’t cut off tails, let me know) - The tails get cut off, which is subideal. It’s assumed that the value of the pdf outside of the bounded range is exactly 0, which is not correct. (Note: If you have ideas on how to store graph formats that don’t cut off tails, let me know)
@ -108,7 +109,7 @@ Use graph techniques. These can be fairly computationally-intensive (particularl
## Sample Set Formats ## Sample Set Formats
**TLDR** **TL;DR**
Random samples. Use Monte Carlo simulation to perform calculations. This is the predominant technique using Monte Carlo methods; in these cases, most nodes are essentially represented as sample sets. [Guesstimate](https://www.getguesstimate.com/) works this way. Random samples. Use Monte Carlo simulation to perform calculations. This is the predominant technique using Monte Carlo methods; in these cases, most nodes are essentially represented as sample sets. [Guesstimate](https://www.getguesstimate.com/) works this way.
**How to Do Computation** **How to Do Computation**

360
packages/website/docs/Features/Distributions.mdx Normal file
View File

@ -0,0 +1,360 @@
---
title: "Distribution Creation"
sidebar_position: 8
---
import TOCInline from "@theme/TOCInline";
import { SquiggleEditor } from "../../src/components/SquiggleEditor";
import Admonition from "@theme/Admonition";
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
<TOCInline toc={toc} maxHeadingLevel={2} />
## 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>
<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 initialSquiggleString="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 initialSquiggleString="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 initialSquiggleString="-5 to -3" />
</TabItem>
<TabItem value="ex4" label="1 to 10000">
It's very easy to generate distributions with very long tails. If this
happens, you can click the "log x scale" box to view this using a log scale.
<SquiggleEditor initialSquiggleString="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[])`
The `mixture` mixes combines multiple distributions to create a mixture. You can optionally pass in a list of proportional weights.
<Tabs>
<TabItem value="ex1" label="Simple" default>
<SquiggleEditor initialSquiggleString="mixture(1 to 2, 5 to 8, 9 to 10)" />
</TabItem>
<TabItem value="ex2" label="With Weights">
<SquiggleEditor initialSquiggleString="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 initialSquiggleString="mixture(1 to 5, 8 to 10, 1, 3, 20)" />
</TabItem>
</Tabs>
### Arguments
- `distributions`: A set of distributions or numbers, each passed as a paramater. Numbers will be converted into Delta 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>
<SquiggleEditor
initialSquiggleString={`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
initialSquiggleString={`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>
<TabItem value="ex1" label="normal(5,1)" default>
<SquiggleEditor initialSquiggleString="normal(5, 1)" />
</TabItem>
<TabItem value="ex2" label="normal(100000000000, 100000000000)">
<SquiggleEditor initialSquiggleString="normal(100000000000, 100000000000)" />
</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 initialSquiggleString="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
initialSquiggleString={`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 initialSquiggleString="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>
## Delta
`delta(value:number)`
Creates a discrete distribution with all of its probability mass at point `value`.
Few Squiggle users call the function `delta()` directly. Numbers are converted into delta 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 delta distributions
with values at 1 and 2. Therefore, this is the same as `mixture(delta(1),delta(2),normal(5,2))`.
`Delta()` distributions are currently the only discrete distributions accessible in Squiggle.
<Tabs>
<TabItem value="ex1" label="delta(3)" default>
<SquiggleEditor initialSquiggleString="delta(3)" />
</TabItem>
<TabItem value="ex3" label="mixture(1,3,5)">
<SquiggleEditor initialSquiggleString="mixture(1,3,5)" />
</TabItem>
<TabItem value="ex2" label="normal(5,2) * 6">
<SquiggleEditor initialSquiggleString="normal(5,2) * 6" />
</TabItem>
<TabItem value="ex4" label="dotAdd(normal(5,2), 6)">
<SquiggleEditor initialSquiggleString="dotAdd(normal(5,2), 6)" />
</TabItem>
<TabItem value="ex5" label="dotMultiply(normal(5,2), 6)">
<SquiggleEditor initialSquiggleString="dotMultiply(normal(5,2), 6)" />
</TabItem>
</Tabs>
### Arguments
- `value`: Number
## Beta
`beta(alpha:number, beta: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>
<TabItem value="ex1" label="beta(10, 20)" default>
<SquiggleEditor initialSquiggleString="beta(10,20)" />
</TabItem>
<TabItem value="ex2" label="beta(1000, 1000)">
<SquiggleEditor initialSquiggleString="beta(1000, 2000)" />
</TabItem>
<TabItem value="ex3" label="beta(1, 10)">
<SquiggleEditor initialSquiggleString="beta(1, 10)" />
</TabItem>
<TabItem value="ex4" label="beta(10, 1)">
<SquiggleEditor initialSquiggleString="beta(10, 1)" />
</TabItem>
<TabItem value="ex5" label="beta(0.8, 0.8)">
<SquiggleEditor initialSquiggleString="beta(0.8, 0.8)" />
</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>
<TabItem value="ex1" label="beta(0.3, 0.3)" default>
<SquiggleEditor initialSquiggleString="beta(0.3, 0.3)" />
</TabItem>
<TabItem value="ex2" label="beta(0.5, 0.5)">
<SquiggleEditor initialSquiggleString="beta(0.5, 0.5)" />
</TabItem>
<TabItem value="ex3" label="beta(0.8, 0.8)">
<SquiggleEditor initialSquiggleString="beta(.8,.8)" />
</TabItem>
<TabItem value="ex4" label="beta(0.9, 0.9)">
<SquiggleEditor initialSquiggleString="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 initialSquiggleString="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 initialSquiggleString="triangular(1, 2, 4)" />
## FromSamples
`fromSamples(samples:number[])`
Creates a sample set distribution using an array of samples.
<SquiggleEditor initialSquiggleString="fromSamples([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>

168
packages/website/docs/Features/Functions.mdx
View File

@ -5,144 +5,15 @@ sidebar_position: 7
import { SquiggleEditor } from "../../src/components/SquiggleEditor"; 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 convenience 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`.
TODO: interpreter/parser doesn't provide this in current `develop` branch
<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(10, 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.11)" />
#### 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.
## `fromSamples`
The last distribution constructor takes an array of samples and constructs a sample set distribution.
<SquiggleEditor initialSquiggleString="fromSamples([1,2,3,4,6,5,5,5])" />
#### Validity
For `fromSamples(xs)`,
- `xs.length > 5`
- Strictly every element of `xs` must be a number.
## Operating on distributions ## Operating on distributions
Here are the ways we combine distributions. Here are the ways we combine distributions.
### Mixture of distributions
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="mixture(uniform(0,1), normal(1,1), [0.5, 0.5])" />
It's possible to create discrete distributions using this method.
<SquiggleEditor initialSquiggleString="mixture(0, 1, [0.2,0.8])" />
As well as mixed distributions:
<SquiggleEditor initialSquiggleString="mixture(3, 8, 1 to 10, [0.2, 0.3, 0.5])" />
An alias of `mixture` is `mx`
#### Validity
Using javascript's variable arguments notation, consider `mx(...dists, weights)`:
- `dists.length == weights.length`
### Addition ### Addition
A horizontal right shift 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 <SquiggleEditor
initialSquiggleString={`dist1 = 1 to 10 initialSquiggleString={`dist1 = 1 to 10
@ -152,7 +23,9 @@ dist1 + dist2`}
### Subtraction ### Subtraction
A horizontal left shift 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 <SquiggleEditor
initialSquiggleString={`dist1 = 1 to 10 initialSquiggleString={`dist1 = 1 to 10
@ -162,7 +35,9 @@ dist1 - dist2`}
### Multiplication ### Multiplication
TODO: provide intuition pump for the semantics 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 <SquiggleEditor
initialSquiggleString={`dist1 = 1 to 10 initialSquiggleString={`dist1 = 1 to 10
@ -176,7 +51,11 @@ We also provide concatenation of two distributions as a syntax sugar for `*`
### Division ### Division
TODO: provide intuition pump for the semantics 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 <SquiggleEditor
initialSquiggleString={`dist1 = 1 to 10 initialSquiggleString={`dist1 = 1 to 10
@ -186,7 +65,9 @@ dist1 / dist2`}
### Exponentiation ### Exponentiation
TODO: provide intuition pump for the semantics 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)`} /> <SquiggleEditor initialSquiggleString={`(0.1 to 1) ^ beta(2, 3)`} />
@ -199,6 +80,8 @@ exp(dist)`}
### Taking logarithms ### Taking logarithms
A projection over a stretched x-axis.
<SquiggleEditor <SquiggleEditor
initialSquiggleString={`dist = triangular(1,2,3) initialSquiggleString={`dist = triangular(1,2,3)
log(dist)`} log(dist)`}
@ -224,6 +107,8 @@ log(dist, x)`}
### Pointwise addition ### 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**. **Pointwise operations are done with `PointSetDist` internals rather than `SampleSetDist` internals**.
TODO: this isn't in the new interpreter/parser yet. TODO: this isn't in the new interpreter/parser yet.
@ -255,8 +140,8 @@ dist1 .* dist2`}
### Pointwise division ### Pointwise division
<SquiggleEditor <SquiggleEditor
initialSquiggleString={`dist1 = 1 to 10 initialSquiggleString={`dist1 = uniform(0,20)
dist2 = triangular(1,2,3) dist2 = normal(10,8)
dist1 ./ dist2`} dist1 ./ dist2`}
/> />
@ -297,7 +182,8 @@ or all values lower than x. It is the inverse of `inv`.
### Inverse CDF ### Inverse CDF
The `inv(dist, prob)` gives the value x or which the probability for all values 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`. 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="inv(normal(0,1),0.5)" /> <SquiggleEditor initialSquiggleString="inv(normal(0,1),0.5)" />
@ -332,7 +218,7 @@ Or `PointSet` format
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) 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)" /> <SquiggleEditor initialSquiggleString="[toSampleSet(0.1 to 1, 100.1), toSampleSet(0.1 to 1, 5000), toSampleSet(0.1 to 1, 20000)]" />
#### Validity #### Validity
@ -372,7 +258,7 @@ You can cut off from the left
You can cut off from the right You can cut off from the right
<SquiggleEditor initialSquiggleString="truncateRight(0.1 to 1, 10)" /> <SquiggleEditor initialSquiggleString="truncateRight(0.1 to 1, 0.5)" />
You can cut off from both sides You can cut off from both sides

16
packages/website/docs/Features/Language.mdx
View File

@ -7,21 +7,21 @@ import { SquiggleEditor } from "../../src/components/SquiggleEditor";
## Expressions ## Expressions
A distribution ### Distributions
<SquiggleEditor initialSquiggleString={`mixture(1 to 2, 3, [0.3, 0.7])`} /> <SquiggleEditor initialSquiggleString={`mixture(1 to 2, 3, [0.3, 0.7])`} />
A number ### Numbers
<SquiggleEditor initialSquiggleString="4.321e-3" /> <SquiggleEditor initialSquiggleString="4.32" />
Arrays ### Arrays
<SquiggleEditor <SquiggleEditor
initialSquiggleString={`[beta(1,10), 4, isNormalized(toSampleSet(1 to 2))]`} initialSquiggleString={`[beta(1,10), 4, isNormalized(toSampleSet(1 to 2))]`}
/> />
Records ### Records
<SquiggleEditor <SquiggleEditor
initialSquiggleString={`d = {dist: triangular(0, 1, 2), weight: 0.25} initialSquiggleString={`d = {dist: triangular(0, 1, 2), weight: 0.25}
@ -42,9 +42,9 @@ A statement assigns expressions to names. It looks like `<symbol> = <expression>
We can define functions We can define functions
<SquiggleEditor <SquiggleEditor
initialSquiggleString={`ozzie_estimate(t) = lognormal(1, t ^ 1.01) initialSquiggleString={`ozzie_estimate(t) = lognormal(t^(1.1), 0.5)
nuño_estimate(t, m) = mixture(0.5 to 2, normal(m, t ^ 1.25)) nuno_estimate(t, m) = mixture(normal(-5, 1), lognormal(m, t / 1.25))
ozzie_estimate(5) * nuño_estimate(5.01, 1)`} ozzie_estimate(1) * nuno_estimate(1, 1)`}
/> />
## See more ## See more

2
packages/website/docs/Features/Node-Packages.md
View File

@ -30,7 +30,7 @@ this library to help navigate the return type.
The `@quri/squiggle-components` package offers several components and utilities The `@quri/squiggle-components` package offers several components and utilities
for people who want to embed Squiggle components into websites. This documentation for people who want to embed Squiggle components into websites. This documentation
relies on `@quri/squiggle-components` frequently. uses `@quri/squiggle-components` frequently.
We host [a storybook](https://squiggle-components.netlify.app/) with details We host [a storybook](https://squiggle-components.netlify.app/) with details
and usage of each of the components made available. and usage of each of the components made available.