Distribution Creation
Normal
normal(mean: number, standardDeviation: number)
normal({mean: number, standardDeviation: number})
normal({p5: number, p95: number})
normal({p10: number, p90: number})
normal({p25: number, p75: number})
Creates a normal distribution (opens in a new tab) with the given mean and standard deviation.
Wikipedia (opens in a new tab)
Lognormal
lognormal(mu: number, sigma: number)
lognormal({mean: number, standardDeviation: number})
lognormal({p5: number, p95: number})
lognormal({p10: number, p90: number})
lognormal({p25: number, p75: number})
Creates a lognormal distribution (opens in a new tab) 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. However, there are several alternative ways to specify a lognormal distribution which are often easier to reason about.
Wikipedia (opens in a new tab)
❓ Understanding mu and sigma
The log of lognormal(mu, sigma)
is a normal distribution with
mean mu
and standard deviation sigma
. For example, these two distributions
are identical:
To
(5thPercentile: number) to (95thPercentile: number)
to(5thPercentile: number, 95thPercentile: number)
The to
function is an easy way to generate lognormal distributions using predicted 5th and 95th percentiles. It's the same as lognormal({p5, p95})
, but easier to write and read.
Arguments
5thPercentile
: number95thPercentile
: number, greater than5thPercentile
Tip
"
Caution
If you haven't tried calibration
training (opens in a new tab),
you're likely to be overconfident. We recommend doing calibration training
to get a feel for what a 90 percent confident interval feels like.
Uniform
uniform(low:number, high:number)
Creates a uniform distribution (opens in a new tab) with the given low and high values.
Arguments
low
: Numberhigh
: Number greater thanlow
Caution
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.
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.
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 often (but not always) 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.
Arguments
value
: Number
Beta
beta(alpha:number, beta:number)
beta({mean: number, stdev: number})
Creates a beta distribution (opens in a new tab) with the given alpha
and beta
values. For a good summary of the beta distribution, see this explanation (opens in a new tab) on Stack Overflow.
Arguments
alpha
: Number greater than zerobeta
: Number greater than zero
Caution with small numbers
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.
Examples
Mixture
mixture(...distributions: Distribution[], weights?: number[])
mixture(distributions: Distribution[], weights?: number[])
mx(...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.
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 to1.0
. If a weights array is provided, it must be the same length as the distribution paramaters.
Aliases
mx
Special Use Cases of Mixtures
🕐 Zero or Continuous
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.
In this case, I have a 20% chance of spending 0 time with it. I might estimate my hours with,
🔒 Model Uncertainty Safeguarding
One technique several Foretold.io 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.
SampleSet.fromList
SampleSet.fromList(samples:number[])
Creates a sample set distribution using an array of samples.
Samples are converted into PDFs automatically using kernel density estimation (opens in a new tab) and an approximated bandwidth. This is an approximation and can be error-prone.
Arguments
samples
: An array of at least 5 numbers.
PointSet.makeContinuous
PointSet.makeContinuous(points:{x: number, y: number})
Creates a continuous point set distribution using a list of points.
Caution!
Distributions made with makeContinuous
are not automatically normalized. We suggest normalizing them manually using the normalize
function.
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.
Arguments
points
: An array of at least 1 coordinate.