update readme

README.Rmd

@@ -31,6 +31,12 @@ You need to install [`cmdstanr`](https://mc-stan.org/cmdstanr/index.html) to use
 install.packages("cmdstanr", repos = c("https://stan-dev.r-universe.dev", getOption("repos")))
 ```
 
+then use that to install CmdStan:
+
+```{r eval=FALSE}
+install_cmdstan(cores = 2)
+```
+
 After that, you can install the development version of `dyingforacup` like so:
 
 ```{r eval=FALSE}
@@ -39,15 +45,19 @@ remotes::install_github('andrewGhazi/dyingforacup', type = "source")
 
 ## 1D Example animation
 
-The point of this package is to suggest coffee brewing configurations in brew parameter space that balance A) improving the expected rating and B) exploring the space. There are a **lot** of dials to turn when brewing coffee, and it's practically impossible to try every combination of grind size, temperature, bloom time, filter thickness, etc.
+This will give you the gist of it:
+
+![](man/figures/out2.gif)
+
+The point of this package is to suggest coffee brewing configurations in brew parameter space that balance A) improving the expected rating and B) exploring the space. There are *many* dials to turn when brewing coffee, and it's practically impossible to try every combination of grind size, temperature, bloom time, etc.
 
 Say you only had one brew parameter: the coarseness dial on the grinder. Imagine the true, unknown relationship between grinder setting and coffee quality looks like this:
 
 ![](man/figures/bo_anim0-fs8.png)
 
 You have one starting observation at 4.5 (too fine, so the observed rating is low). There's a bit of noise about the true function. What setting should you try next?
 
-If you use Gaussian processes and [Bayesian Optimization](https://www.youtube.com/watch?v=wZODGJzKmD0), you can get suggestions that are, in a sense, optimal. Let's see how automated suggestions work out:
+If you use Gaussian processes and [Bayesian Optimization](https://www.youtube.com/watch?v=wZODGJzKmD0), you can get suggestions that are, in a sense, optimal. The suggestions balance identifying/refining promising regions and collapsing uncertainty in unexplored regions. Let's look again at the gif demonstrating automated suggestions along a one-dimensional brew parameter space for grinder setting. At each iteration, you fit a GP to the data, then use that fit to determine where the next data point should be collected:
 
 ![](man/figures/out2.gif)
 
@@ -64,11 +74,11 @@ There's a lot going on in that animation. This explains each panel:
 * bottom pane, green function: the acquisition function, a weighted mixture of the two curves above. `lambda * blue + (1-lambda) * red = green`
   * orange diamond: maximum point on the acquisition function = next suggested point
 
-You can see that first it suggests a very high setting because that's where there's the most uncertainty given the first point. After that turns out badly as well, it tries in the middle. That does much better, after which it hones in on the global maximum (it gets somewhat lucky and finds a near optimal point at only the fourth suggestion). After that it tries elsewhere in the space, collapsing uncertainty wherever it's high to see if there's some other hidden peak. 
+You can see that first it suggests a very high setting because that's where there's the most uncertainty given the first point. After that turns out badly as well, it tries in the middle. That does much better, after which it hones in on the global maximum (it gets somewhat lucky and finds a near-optimal point at only the fourth suggestion). After that it tries elsewhere in the space, collapsing uncertainty wherever it's high to see if there's some other hidden peak. 
 
 ## Usage
 
-As the last frame of the video suggests, this process can be extended to an arbitrary number of brew parameters. Bear in mind that this isn't magic, and finding optima in higher dimensional spaces will require many more observations. This is especially true if the ratings are noisy, so try hard to give each cup a fair, normally-distributed rating. Speaking of, integer ratings of 0-10 aren't allowed, the ratings have to be normally distributed. That might change if I feel like implementing it.
+As the last frame of the gif suggests, this process can be extended to an arbitrary number of brew parameters. Bear in mind that this isn't magic, and finding optima in higher dimensional spaces will require many more observations. This is especially true if the ratings are noisy, so try hard to give each cup a fair, normally-distributed rating. Speaking of, integer ratings of 0-10 aren't allowed, the ratings have to be normally distributed. That might change if I feel like implementing it.
 
 Give the `suggest_next()` function a data frame of brew parameters with ratings and it will suggest a point to try next that has high predicted probability of improving the rating.
 
@@ -103,13 +113,14 @@ $suggested
      <num>   <num> <num>           <num> <num>      <num>
 1:    1.19   0.464 0.536               9   195         30
 ```
-This returns a list of MCMC draws, the acquisition function values over a grid of brew parameters, and a suggestion on where to go next. `offset` and `lambda` can be tweaked to control exploration vs exploitation, but expect to be suggested some combinations that result in really bad coffee sometimes.  See `?suggest_next` for more detail on these and more function arguments.
+This returns a list of MCMC draws, the acquisition function values over a grid of brew parameters, and a suggestion on where to go next. `offset` and `lambda` can be tweaked to control exploration vs exploitation, but expect to be suggested some combinations that result in really bad coffee sometimes.  See `?suggest_next` for more detail on these function arguments and more.
 
 ## TODO list
 
 Easy:
 
 * User prior input
+* Other acquisition functions
 * Viz functions
 
 Medium:
@@ -125,5 +136,5 @@ Hard:
 Nightmare:
 
 * Fast GP approximations for 3D+ 
-  * I think this would require writing my own ND FFT function?
-* Refactor to use INLA (preferably from scratch over `R-INLA`)
+  * This would probably require some custom ND FFT functions
+* Refactor to use INLA 

README.md

@@ -23,6 +23,12 @@ package:
 install.packages("cmdstanr", repos = c("https://stan-dev.r-universe.dev", getOption("repos")))
 ```
 
+then use that to install CmdStan:
+
+``` r
+install_cmdstan(cores = 2)
+```
+
 After that, you can install the development version of `dyingforacup`
 like so:
 
@@ -32,11 +38,15 @@ remotes::install_github('andrewGhazi/dyingforacup', type = "source")
 
 ## 1D Example animation
 
+This will give you the gist of it:
+
+![](man/figures/out2.gif)
+
 The point of this package is to suggest coffee brewing configurations in
 brew parameter space that balance A) improving the expected rating and
-B) exploring the space. There are a **lot** of dials to turn when
-brewing coffee, and it’s practically impossible to try every combination
-of grind size, temperature, bloom time, filter thickness, etc.
+B) exploring the space. There are *many* dials to turn when brewing
+coffee, and it’s practically impossible to try every combination of
+grind size, temperature, bloom time, etc.
 
 Say you only had one brew parameter: the coarseness dial on the grinder.
 Imagine the true, unknown relationship between grinder setting and
@@ -50,8 +60,12 @@ setting should you try next?
 
 If you use Gaussian processes and [Bayesian
 Optimization](https://www.youtube.com/watch?v=wZODGJzKmD0), you can get
-suggestions that are, in a sense, optimal. Let’s see how automated
-suggestions work out:
+suggestions that are, in a sense, optimal. The suggestions balance
+identifying/refining promising regions and collapsing uncertainty in
+unexplored regions. Let’s look again at the gif demonstrating automated
+suggestions along a one-dimensional brew parameter space for grinder
+setting. At each iteration, you fit a GP to the data, then use that fit
+to determine where the next data point should be collected:
 
 ![](man/figures/out2.gif)
 
@@ -80,13 +94,13 @@ You can see that first it suggests a very high setting because that’s
 where there’s the most uncertainty given the first point. After that
 turns out badly as well, it tries in the middle. That does much better,
 after which it hones in on the global maximum (it gets somewhat lucky
-and finds a near optimal point at only the fourth suggestion). After
+and finds a near-optimal point at only the fourth suggestion). After
 that it tries elsewhere in the space, collapsing uncertainty wherever
 it’s high to see if there’s some other hidden peak.
 
 ## Usage
 
-As the last frame of the video suggests, this process can be extended to
+As the last frame of the gif suggests, this process can be extended to
 an arbitrary number of brew parameters. Bear in mind that this isn’t
 magic, and finding optima in higher dimensional spaces will require many
 more observations. This is especially true if the ratings are noisy, so
@@ -133,13 +147,14 @@ a grid of brew parameters, and a suggestion on where to go next.
 `offset` and `lambda` can be tweaked to control exploration vs
 exploitation, but expect to be suggested some combinations that result
 in really bad coffee sometimes. See `?suggest_next` for more detail on
-these and more function arguments.
+these function arguments and more.
 
 ## TODO list
 
 Easy:
 
 - User prior input
+- Other acquisition functions
 - Viz functions
 
 Medium:
@@ -157,5 +172,5 @@ Hard:
 Nightmare:
 
 - Fast GP approximations for 3D+
-  - I think this would require writing my own ND FFT function?
-- Refactor to use INLA (preferably from scratch over `R-INLA`)
+  - This would probably require some custom ND FFT functions
+- Refactor to use INLA