From 259f71f1f7eb4b66dcf99b92f6d70dfeefb8a63a Mon Sep 17 00:00:00 2001 From: Andrew Ghazi <6763470+andrewGhazi@users.noreply.github.com> Date: Tue, 16 Jul 2024 19:20:38 -0400 Subject: [PATCH] update readme --- README.Rmd | 25 ++++++++++++++++++------- README.md | 35 +++++++++++++++++++++++++---------- 2 files changed, 43 insertions(+), 17 deletions(-) diff --git a/README.Rmd b/README.Rmd index d81b5e1..73c02b5 100644 --- a/README.Rmd +++ b/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,7 +45,11 @@ 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: @@ -47,7 +57,7 @@ Say you only had one brew parameter: the coarseness dial on the grinder. Imagine 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 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 \ No newline at end of file diff --git a/README.md b/README.md index fc87f32..4571b2f 100644 --- a/README.md +++ b/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