Merge pull request #5 from forestgeo/memoise

Memoise allo_evaluate()

DESCRIPTION

@@ -48,7 +48,8 @@ Imports:
     rlang (>= 0.3.1),
     stats,
     tibble (>= 2.0.1),
-    tidyr (>= 0.8.2)
+    tidyr (>= 0.8.2),
+    memoise
 Suggests: 
     covr (>= 3.2.1),
     testthat (>= 2.0.1)

NEWS.md

@@ -1,6 +1,11 @@
-# fgeo.x (development version)
+# fgeo.biomass (development version)
+
+* `allo_evaluate()` is now memoised.
 
 * Request R >= 3.1
-* Require recent release of fgeo.tool
-* Require recent dev version of allodb
-* Build and deploy website site on Travis CI
+
+* Require recent release of fgeo.tool.
+
+* Require recent dev version of allodb.
+
+* Build and deploy website site on Travis CI.

R/allo_evaluate.R

@@ -1,3 +1,10 @@
+allo_evaluate_impl <- function(.data) {
+  .biomass <- purrr::map2_dbl(
+    .data$eqn, .data$dbh,
+    ~eval(parse(text = .x), envir = list(dbh = .y))
+  )
+  dplyr::mutate(.data, biomass = .biomass)
+}
 #' Evaluate equations, giving a biomass result per row.
 #'
 #' @param .data A dataframe as those created with [allo_order()].
@@ -16,10 +23,4 @@
 #'   allo_order()
 #'
 #' allo_evaluate(best)
-allo_evaluate <- function(.data) {
-  .biomass <- purrr::map2_dbl(
-    .data$eqn, .data$dbh,
-    ~eval(parse(text = .x), envir = list(dbh = .y))
-  )
-  dplyr::mutate(.data, biomass = .biomass)
-}
+allo_evaluate <- memoise::memoise(allo_evaluate_impl)

README.Rmd

@@ -157,6 +157,26 @@ with_biomass %>%
   arrange(desc(total_biomass))
 ```
 
+### Memoization
+
+> If a function is called multiple times with the same input, you can often speed things up by keeping a cache of known answers that it can retrieve. This is called memoisation http://en.wikipedia.org/wiki/Memoization.
+
+-- https://github.com/r-lib/memoise
+
+Because `allo_evaluate()` can be slow, its result is stored and reused after the first time you run it.
+
+```{r, cache=FALSE}
+# Clear cache to show how it works
+memoise::forget(allo_evaluate)
+
+# `allo_evaluate()` may be slow the first time you run it
+system.time(allo_evaluate(best))
+memoise::is.memoised(allo_evaluate)
+
+# Calls after the first one take almost no time
+system.time(allo_evaluate(best))
+```
+
 ### Known issues
 
 Right now there may be multiple rows per `rowid`. This is because, for a single stem, there may be multiple equations to reflect the allometries of different parts of the stem. __fgeo.biomass__ doesn't deal with this issue yet but helps you find them.
@@ -219,6 +239,7 @@ census_species %>%
 ```
 
 * New `allo_customize()` to insert custom equations.
+
 Some other possible improvements:
 
 * Allow using ViewFullTable and ViewTaxonomy.

README.md

@@ -301,6 +301,36 @@ with_biomass %>%
 #> # ... with 42 more rows
 ```
 
+### Memoization
+
+> If a function is called multiple times with the same input, you can
+> often speed things up by keeping a cache of known answers that it can
+> retrieve. This is called memoisation
+> <http://en.wikipedia.org/wiki/Memoization>.
+
+– <https://github.com/r-lib/memoise>
+
+Because `allo_evaluate()` can be slow, its result is stored and reused
+after the first time you run it.
+
+``` r
+# Clear cache to show how it works
+memoise::forget(allo_evaluate)
+#> [1] TRUE
+
+# `allo_evaluate()` may be slow the first time you run it
+system.time(allo_evaluate(best))
+#>    user  system elapsed 
+#>    0.84    0.02    0.90
+memoise::is.memoised(allo_evaluate)
+#> [1] TRUE
+
+# Calls after the first one take almost no time
+system.time(allo_evaluate(best))
+#>    user  system elapsed 
+#>    0.00    0.01    0.02
+```
+
 ### Known issues
 
 Right now there may be multiple rows per `rowid`. This is because, for a
@@ -455,13 +485,12 @@ census_species %>%
   auto_equations()
 ```
 
-  - New `allo_customize()` to insert custom equations. Some other
-    possible improvements:
+  - New `allo_customize()` to insert custom equations.
 
-  - Allow using ViewFullTable and ViewTaxonomy.
+Some other possible improvements:
 
+  - Allow using ViewFullTable and ViewTaxonomy.
   - Allow using any table with the required columns.
-
   - Simplify interfaces via generic functions that *know* what to do
     with different (S3) classes of ForestGEO data – i.e. census and
     species tables; ViewFullTable and ViewTaxonomy tables; or any two