Add interactive documentation
This commit is contained in:
Sam Nolan
parent
cfa2379a16
commit
142d846223
136
packages/website/docs/Functions.mdx
Normal file
136
packages/website/docs/Functions.mdx
Normal file
|
|
@ -0,0 +1,136 @@
|
|||
---
|
||||
sidebar_position: 7
|
||||
---
|
||||
|
||||
import { SquiggleEditor } from '@quri/squiggle-components'
|
||||
|
||||
# Squiggle Functions Reference
|
||||
|
||||
## Distributions
|
||||
|
||||
### Normal distribution
|
||||
|
||||
The `normal(mean, sd)` function creates a normal distribution with the given mean
|
||||
and standard deviation.
|
||||
|
||||
<SquiggleEditor initialSquiggleString="normal(0, 1)" />
|
||||
|
||||
### Uniform distribution
|
||||
|
||||
The `uniform(low, high)` function creates a uniform distribution between the
|
||||
two given numbers:
|
||||
|
||||
<SquiggleEditor initialSquiggleString="uniform(0, 10)" />
|
||||
|
||||
|
||||
### 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 parameters
|
||||
mean mu and standard deviation sigma.
|
||||
|
||||
<SquiggleEditor initialSquiggleString="lognormal(0, 1)" />
|
||||
|
||||
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 convinience as lognormal distributions are commonly used in practice
|
||||
|
||||
<SquiggleEditor initialSquiggleString="2 to 10" />
|
||||
|
||||
Furthermore, it's also possible to create a lognormal from it's actual mean
|
||||
and standard deviation, using `lognormalFromMeanAndStdDev`:
|
||||
|
||||
<SquiggleEditor initialSquiggleString="lognormalFromMeanAndStdDev(20, 20)" />
|
||||
|
||||
|
||||
### Beta distribution
|
||||
|
||||
The `beta(a, b)` function creates a beta distribution with parameters a and b:
|
||||
|
||||
<SquiggleEditor initialSquiggleString="beta(20, 20)" />
|
||||
|
||||
### Exponential distribution
|
||||
|
||||
The `exponential(mean)` function creates an exponential distribution with the given
|
||||
mean.
|
||||
|
||||
<SquiggleEditor initialSquiggleString="exponential(1)" />
|
||||
|
||||
|
||||
### The Triangular distribution
|
||||
|
||||
The `triangular(a,b,c)` function creates a triangular distribution with lower
|
||||
bound a, mode b and upper bound c:
|
||||
|
||||
<SquiggleEditor initialSquiggleString="triangular(1, 2, 4)" />
|
||||
|
||||
### Multimodal distriutions
|
||||
|
||||
The multimodal 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="mm(uniform(0,1), normal(1,1), [0.5, 0.5])" />
|
||||
|
||||
It's possible to create discrete distributions using this method:
|
||||
|
||||
<SquiggleEditor initialSquiggleString="mm(0, 1, [0.2,0.8])" />
|
||||
|
||||
As well as mixed distributions:
|
||||
|
||||
<SquiggleEditor initialSquiggleString="mm(0, 1 to 10, [0.2,0.8])" />
|
||||
|
||||
## Other Functions
|
||||
|
||||
### PDF of a distribution
|
||||
The `pdf(distribution, x)` function returns the density of a distribution at the
|
||||
given point x:
|
||||
|
||||
|
||||
<SquiggleEditor initialSquiggleString="pdf(normal(0,1),0)" />
|
||||
|
||||
### Inverse of a distribution
|
||||
|
||||
The `inv(distribution, 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)" />
|
||||
|
||||
### CDF of a distribution
|
||||
|
||||
The `cdf(distribution,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)" />
|
||||
|
||||
### Mean of a distribution
|
||||
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))" />
|
||||
|
||||
### Exponential Scaling
|
||||
|
||||
The `scaleExp(distribution, factor)` function scales a distribution's PDF exponentially
|
||||
in the y axis.
|
||||
|
||||
<SquiggleEditor initialSquiggleString="scaleExp(normal(10, 10), 10)" />
|
||||
|
||||
### Multiply Scaling
|
||||
|
||||
The `scaleMultiply(distribution, factor)` function scales a distribution's PDF by multiplication
|
||||
in the y axis.
|
||||
|
||||
<SquiggleEditor initialSquiggleString="scaleMultiply(normal(10, 10), 2)" />
|
||||
|
||||
### Log scaling
|
||||
|
||||
The `scaleLog(distribution, factor)` function scales a distribution's PDF by the log
|
||||
function in the y axis
|
||||
|
||||
<SquiggleEditor initialSquiggleString="scaleLog(normal(10, 10), 2)" />
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
sidebar_position: 3
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# Future Features
|
||||
|
|
@ -79,3 +79,32 @@ Right now, Monte Carlo simulations are totally random. It would be nicer to be a
|
|||
|
||||
## Fixes
|
||||
- Discrete distributions are particularly buggy. Try ``mm(1,2,3,4,5,6,7,8,9,10) .* (5 to 8)``
|
||||
|
||||
## New Functions
|
||||
|
||||
### Distributions
|
||||
```
|
||||
cauchy() //todo
|
||||
pareto() //todo
|
||||
metalog() //todo
|
||||
```
|
||||
|
||||
Possibly change mm to mix, or mx(). Also, change input format, maybe to mx([a,b,c], [a,b,c]).
|
||||
|
||||
|
||||
### Functions
|
||||
```
|
||||
samples(distribution, n) //todo
|
||||
toPdf(distribution) //todo
|
||||
toCdf(distribution) //todo
|
||||
toHash(distribution) //todo. Make hash of content, like, {xs:[], ys:[]}
|
||||
trunctate(distribution, leftValue, rightValue) //todo
|
||||
leftTrunctate(distribution, leftValue) //todo
|
||||
rightTrunctate(distribution, rightValue) //todo
|
||||
distributionFromSamples(array, params) //todo
|
||||
distributionFromPoints() //todo
|
||||
distributionFromHash() //todo
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
10
packages/website/docs/Introduction.md
Normal file
10
packages/website/docs/Introduction.md
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Squiggle
|
||||
|
||||
Squiggle is a language for writing calculations under uncertainty. It has use
|
||||
cases in forecasting and writing better evaluations.
|
||||
|
||||
The best way to get started with Squiggle is to [try it out yourself](https://playground.squiggle-language.com/).
|
||||
|
|
@ -1,16 +1,36 @@
|
|||
---
|
||||
sidebar_position: 2
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
# Javascript Library
|
||||
# Javascript Libraries
|
||||
|
||||
There's a very simple javscript library for Squiggle here: https://www.npmjs.com/package/squiggle-experimental.
|
||||
There are two JavaScript packages currently available for Squiggle:
|
||||
- [`@quri/squiggle-lang`](https://www.npmjs.com/package/@quri/squiggle-lang)
|
||||
- [`@quri/squiggle-components`](https://www.npmjs.com/package/@quri/squiggle-components)
|
||||
|
||||
You can see it live on this Observable page: [https://observablehq.com/d/a99e822870c4ca5f](https://observablehq.com/d/a99e822870c4ca5f).
|
||||
Types are available for both packages.
|
||||
|
||||
## Squiggle Language
|
||||
|
||||
## Simple Example
|
||||
```
|
||||
let squiggle = require("squiggle-experimental@0.1.9/dist/index.js")
|
||||
squiggle.runMePlease("3 + normal(50,1))
|
||||
```
|
||||
The `@quri/squiggle-lang` package exports a single function, `run`, which given
|
||||
a string of Squiggle code, will execute the code and return any exports and the
|
||||
environment created from the squiggle code.
|
||||
|
||||
`run` has two optional arguments. The first optional argument allows you to set
|
||||
sampling settings for Squiggle when representing distributions. The second optional
|
||||
argument allows you to pass an environment previously created by another `run`
|
||||
call. Passing this environment will mean that all previously declared variables
|
||||
in the previous environment will be made available.
|
||||
|
||||
The return type of `run` is a bit complicated, and comes from auto generated js
|
||||
code that comes from rescript. I highly recommend using typescript when using
|
||||
this library to help navigate the return type.
|
||||
|
||||
## Squiggle Components
|
||||
|
||||
The `@quri/squiggle-components` package offers several components and utilities
|
||||
for people who want to embed Squiggle components into websites. This documentation
|
||||
relies on `@quri/squiggle-components` frequently.
|
||||
|
||||
We host [a storybook](https://components.squiggle-language.com/) with details
|
||||
and usage of each of the components made available.
|
||||
|
|
|
|||
|
|
@ -1,67 +0,0 @@
|
|||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Squiggle Language
|
||||
|
||||
## Distributions
|
||||
```js
|
||||
normal(a,b)
|
||||
uniform(a,b)
|
||||
lognormal(a,b)
|
||||
lognormalFromMeanAndStdDev(mean, stdev)
|
||||
beta(a,b)
|
||||
exponential(a)
|
||||
triangular(a,b,c)
|
||||
mm(a,b,c, [1,2,3]) //todo: change to mix, or mx(). Also, change input format, maybe to mx([a,b,c], [a,b,c]).
|
||||
cauchy() //todo
|
||||
pareto() //todo
|
||||
metalog() //todo
|
||||
```
|
||||
|
||||
## Functions
|
||||
```js
|
||||
pdf(distribution, float)
|
||||
inv(distribution, float)
|
||||
cdf(distribution, float)
|
||||
mean(distribution)
|
||||
sample(distribution)
|
||||
scaleExp(distribution, float)
|
||||
scaleMultiply(distribution, float)
|
||||
scaleLog(distribution, float)
|
||||
samples(distribution, n) //todo
|
||||
toPdf(distribution) //todo
|
||||
toCdf(distribution) //todo
|
||||
toHash(distribution) //todo. Make hash of content, like, {xs:[], ys:[]}
|
||||
trunctate(distribution, leftValue, rightValue) //todo
|
||||
leftTrunctate(distribution, leftValue) //todo
|
||||
rightTrunctate(distribution, rightValue) //todo
|
||||
distributionFromSamples(array, params) //todo
|
||||
distributionFromPoints() //todo
|
||||
distributionFromHash() //todo
|
||||
log() //todo
|
||||
|
||||
```
|
||||
|
||||
## Example Functions
|
||||
|
||||
```js
|
||||
ozzie_estimate(t) = lognormal({mean: 3 + (t+.1)^2.5, stdev: 8})
|
||||
nuño_estimate(t) = lognormal({mean: 3 + (t+.1)^2, stdev: 10})
|
||||
combined(t) = mm(ozzie_estimate(t) .+ nuño_estimate(t))
|
||||
combined
|
||||
```
|
||||
|
||||
```js
|
||||
us_economy_2018 = (10.5 to 10.9)T
|
||||
growth_rate = 1.08 to 1.2
|
||||
us_economy(t) = us_economy_2018 * (growth_rate^t)
|
||||
|
||||
us_population_2019 = 320M to 330M
|
||||
us_population_growth_rate = 1.01 to 1.1
|
||||
us_population(t) = us_population_2019 * (us_population_growth_rate^t)
|
||||
gdp_per_person(t) = us_economy(t)/us_population(t)
|
||||
gdp_per_person
|
||||
|
||||
gdp_per_person
|
||||
```
|
||||
51
packages/website/docs/Language.mdx
Normal file
51
packages/website/docs/Language.mdx
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
---
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
import { SquiggleEditor } from '@quri/squiggle-components'
|
||||
|
||||
# Squiggle Language
|
||||
|
||||
The squiggle language has a very simply syntax. The best way to get to understand
|
||||
it is by simply looking at examples.
|
||||
|
||||
|
||||
## Basic Language
|
||||
|
||||
As an example:
|
||||
|
||||
<SquiggleEditor initialSquiggleString={`value_of_work = 10 to 70
|
||||
value_of_work`} />
|
||||
|
||||
Squiggle can declare variables (`value_of_work = 10 to 70`) and declare exports
|
||||
(the lone `value_of_work` line). Variables can be used later in a squiggle program
|
||||
and even in other notebooks!
|
||||
|
||||
An export is rendered to the output view so you can see your result.
|
||||
|
||||
the exports can be expressions, such as:
|
||||
|
||||
<SquiggleEditor initialSquiggleString="normal(0,1)" />
|
||||
|
||||
## Functions
|
||||
|
||||
Squiggle supports functions, including the rendering of functions:
|
||||
|
||||
<SquiggleEditor initialSquiggleString={`ozzie_estimate(t) = lognormal({mean: 3 + (t+.1)^2.5, stdev: 8})
|
||||
ozzie_estimate
|
||||
`} />
|
||||
|
||||
## Squiggle units
|
||||
|
||||
Squiggle supports using suffixes at the end of numbers to refer to units:
|
||||
|
||||
<SquiggleEditor initialSquiggleString={`
|
||||
us_economy_2018 = (10.5 to 10.9)T
|
||||
growth_rate = 1.08 to 1.2
|
||||
us_economy(t) = us_economy_2018 * (growth_rate^t)
|
||||
us_population_2019 = 320M to 330M
|
||||
us_population_growth_rate = 1.01 to 1.1
|
||||
us_population(t) = us_population_2019 * (us_population_growth_rate^t)
|
||||
gdp_per_person(t) = us_economy(t)/us_population(t)
|
||||
gdp_per_person`} />
|
||||
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
sidebar_position: 4
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# Three Formats of Distributions
|
||||
|
|
|
|||
|
|
@ -3,18 +3,35 @@
|
|||
|
||||
const lightCodeTheme = require('prism-react-renderer/themes/github');
|
||||
const darkCodeTheme = require('prism-react-renderer/themes/dracula');
|
||||
const path = require('path');
|
||||
|
||||
/** @type {import('@docusaurus/types').Config} */
|
||||
const config = {
|
||||
title: 'Squiggle (alpha)',
|
||||
tagline: "Scorable programming, for use by forecasters",
|
||||
url: 'https://squiggle-documentation.netlify.app',
|
||||
tagline: "Estimation language for forecasters",
|
||||
url: 'https://squiggle-language.com',
|
||||
baseUrl: '/',
|
||||
onBrokenLinks: 'throw',
|
||||
onBrokenMarkdownLinks: 'warn',
|
||||
favicon: 'img/favicon.ico',
|
||||
organizationName: 'QURI', // Usually your GitHub org/user name.
|
||||
projectName: 'Squiggle', // Usually your repo name.
|
||||
organizationName: 'QURIResearch', // Usually your GitHub org/user name.
|
||||
projectName: 'squiggle', // Usually your repo name.
|
||||
|
||||
plugins: [
|
||||
() => ({
|
||||
configureWebpack(config, isServer, utils, content) {
|
||||
return {
|
||||
resolve: {
|
||||
alias : {
|
||||
"@quri/squiggle-components": path.resolve(__dirname, "../components/src"),
|
||||
"@quri/squiggle-lang": path.resolve(__dirname, "../squiggle-lang/src/js")
|
||||
}
|
||||
}
|
||||
|
||||
};
|
||||
}
|
||||
})
|
||||
],
|
||||
|
||||
presets: [
|
||||
[
|
||||
|
|
@ -51,7 +68,7 @@ const config = {
|
|||
items: [
|
||||
{
|
||||
type: 'doc',
|
||||
docId: 'Language',
|
||||
docId: 'Introduction',
|
||||
position: 'left',
|
||||
label: 'Documentation',
|
||||
},
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user