From 526ee921b5d9abab381fbc687440277fe4c563da Mon Sep 17 00:00:00 2001
From: NunoSempere <nuno.sempere@protonmail.com>
Date: Tue, 3 May 2022 17:22:08 -0400
Subject: [PATCH] tweak: some tweaks to documentation, part 1/2

---
 .../Three-Formats-Of-Distributions.md         | 19 ++++++-----
 .../website/docs/Features/Distributions.mdx   |  4 ++-
 packages/website/docs/Features/Functions.mdx  | 33 ++++++++++++++-----
 packages/website/docs/Features/Language.mdx   | 16 ++++-----
 .../website/docs/Features/Node-Packages.md    |  2 +-
 5 files changed, 47 insertions(+), 27 deletions(-)

diff --git a/packages/website/docs/Discussions/Three-Formats-Of-Distributions.md b/packages/website/docs/Discussions/Three-Formats-Of-Distributions.md
index 8ec5b88d..405bc97c 100644
--- a/packages/website/docs/Discussions/Three-Formats-Of-Distributions.md
+++ b/packages/website/docs/Discussions/Three-Formats-Of-Distributions.md
@@ -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.
 
-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.
 
@@ -19,7 +19,7 @@ Note that the name "Symbolic" is fairly standard, but I haven't found common nam
 
 ## 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).
 
 **Examples**  
@@ -29,9 +29,6 @@ Mathematical representations. Require analytic solutions. These are often ideal
 **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.
 
-**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**
 
 - 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**  
 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
 
-**TLDR**  
-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.
+**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 graphically-described distribution.
 
 **Alternative Names:**  
 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**
 
-- 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.
 - 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
 
-**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.
 
 **How to Do Computation**  
diff --git a/packages/website/docs/Features/Distributions.mdx b/packages/website/docs/Features/Distributions.mdx
index 2ade1a3c..28e1db01 100644
--- a/packages/website/docs/Features/Distributions.mdx
+++ b/packages/website/docs/Features/Distributions.mdx
@@ -159,7 +159,9 @@ Creates a [normal distribution](https://en.wikipedia.org/wiki/Normal_distributio
 
 Creates a [log-normal distribution](https://en.wikipedia.org/wiki/Log-normal_distribution) with the given mu and sigma.
 
-`Mu` and `sigma` 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.
+`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)" />
 
diff --git a/packages/website/docs/Features/Functions.mdx b/packages/website/docs/Features/Functions.mdx
index 38872db3..46bc4e39 100644
--- a/packages/website/docs/Features/Functions.mdx
+++ b/packages/website/docs/Features/Functions.mdx
@@ -11,7 +11,9 @@ Here are the ways we combine distributions.
 
 ### 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
   initialSquiggleString={`dist1 = 1 to 10
@@ -21,7 +23,9 @@ dist1 + dist2`}
 
 ### 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
   initialSquiggleString={`dist1 = 1 to 10
@@ -31,7 +35,9 @@ dist1 - dist2`}
 
 ### 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
   initialSquiggleString={`dist1 = 1 to 10
@@ -45,7 +51,11 @@ We also provide concatenation of two distributions as a syntax sugar for `*`
 
 ### 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
   initialSquiggleString={`dist1 = 1 to 10
@@ -55,7 +65,9 @@ dist1 / dist2`}
 
 ### 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)`} />
 
@@ -68,6 +80,8 @@ exp(dist)`}
 
 ### Taking logarithms
 
+A projection over a stretched x-axis.
+
 <SquiggleEditor
   initialSquiggleString={`dist = triangular(1,2,3)
 log(dist)`}
@@ -93,6 +107,8 @@ log(dist, x)`}
 
 ### 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**.
 
 TODO: this isn't in the new interpreter/parser yet.
@@ -166,7 +182,8 @@ or all values lower than x. It is the inverse of `inv`.
 ### 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`.
+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)" />
 
@@ -201,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)
 
-<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
 
@@ -241,7 +258,7 @@ You can cut off from the left
 
 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
 
diff --git a/packages/website/docs/Features/Language.mdx b/packages/website/docs/Features/Language.mdx
index 5b66d2e2..74c703ae 100644
--- a/packages/website/docs/Features/Language.mdx
+++ b/packages/website/docs/Features/Language.mdx
@@ -7,21 +7,21 @@ import { SquiggleEditor } from "../../src/components/SquiggleEditor";
 
 ## Expressions
 
-A distribution
+### Distributions
 
 <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
   initialSquiggleString={`[beta(1,10), 4, isNormalized(toSampleSet(1 to 2))]`}
 />
 
-Records
+### Records
 
 <SquiggleEditor
   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
 
 <SquiggleEditor
-  initialSquiggleString={`ozzie_estimate(t) = lognormal(1, t ^ 1.01)
-nuño_estimate(t, m) = mixture(0.5 to 2, normal(m, t ^ 1.25))
-ozzie_estimate(5) * nuño_estimate(5.01, 1)`}
+  initialSquiggleString={`ozzie_estimate(t) = lognormal(t^(1.1), 0.5)
+nuno_estimate(t, m) = mixture(normal(-5, 1), lognormal(m, t / 1.25))
+ozzie_estimate(1) * nuno_estimate(1, 1)`}
 />
 
 ## See more
diff --git a/packages/website/docs/Features/Node-Packages.md b/packages/website/docs/Features/Node-Packages.md
index ab590c32..381cef1f 100644
--- a/packages/website/docs/Features/Node-Packages.md
+++ b/packages/website/docs/Features/Node-Packages.md
@@ -30,7 +30,7 @@ this library to help navigate the return type.
 
 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.
+uses `@quri/squiggle-components` frequently.
 
 We host [a storybook](https://squiggle-components.netlify.app/) with details
 and usage of each of the components made available.