From 06b0b3cfbaf87addb44c7b0c02b328723a85f84a Mon Sep 17 00:00:00 2001 From: Douglas Ezra Morrison Date: Mon, 7 Sep 2026 10:30:06 -0700 Subject: [PATCH 1/5] start: blurb memoise (closes #353) From 8e47c47830861da8769c856386751515031a3567 Mon Sep 17 00:00:00 2001 From: Douglas Ezra Morrison Date: Mon, 7 Sep 2026 10:45:47 -0700 Subject: [PATCH 2/5] docs: expand memoise caching blurb and cross-reference in benchmarking (closes #353) --- coding-practices/benchmarking.qmd | 1 + coding-practices/r-lib-packages.qmd | 12 ++++++++++-- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/coding-practices/benchmarking.qmd b/coding-practices/benchmarking.qmd index b995ec7c..26cb8f94 100644 --- a/coding-practices/benchmarking.qmd +++ b/coding-practices/benchmarking.qmd @@ -542,6 +542,7 @@ n_iterations <- 1000 - [`{bench}`](https://bench.r-lib.org/) - Accurate benchmarking - [`{profvis}`](https://profvis.r-lib.org/) - Interactive profiling +- [`{memoise}`](https://memoise.r-lib.org/) - Function-call caching to eliminate repeated bottlenecks (@sec-memoise) - [Measuring Performance](https://adv-r.hadley.nz/perf-measure.html) chapter in Advanced R - [Improving Performance](https://adv-r.hadley.nz/perf-improve.html) chapter in Advanced R - [`{touchstone}`](https://github.com/lorenzwalthert/touchstone) - CI benchmarking with PR comments diff --git a/coding-practices/r-lib-packages.qmd b/coding-practices/r-lib-packages.qmd index e7915095..15885a81 100644 --- a/coding-practices/r-lib-packages.qmd +++ b/coding-practices/r-lib-packages.qmd @@ -209,8 +209,16 @@ This manual requires `{here}` for file paths (see @sec-here-package-practices). ### [`{memoise}`](https://memoise.r-lib.org/) {#sec-memoise} [`{memoise}`](https://memoise.r-lib.org/) adds memoisation (function-call caching) to R functions. -Wrapping a function with `memoise()` causes it to cache results so repeated calls -with the same arguments return the cached value instead of recomputing. +Wrapping an expensive or pure function with `memoise()` causes it to cache computed return values +in memory or on disk, +so repeated calls with identical arguments return instantly from cache instead of recomputing. +It supports multiple storage backends via the `cache` argument +(including `cachem::cache_mem()` for in-memory caching and `cachem::cache_disk()` for persistent disk caching across sessions), +and provides `forget()` and `is.memoised()` to manage and inspect cache state. +Use `{memoise}` to avoid redundant computation in iterative simulations, +API queries, +or repeated data extraction steps +where underlying inputs remain unchanged. ### [`{scales}`](https://scales.r-lib.org/) {#sec-scales} From 05b5d7f1148a9c7cf2d853264d9e908fac8c09a0 Mon Sep 17 00:00:00 2001 From: Douglas Ezra Morrison Date: Tue, 8 Sep 2026 09:16:53 -0700 Subject: [PATCH 3/5] docs: clarify memoise pure/expensive requirements and stochastic simulation caveats (closes #353) --- coding-practices/r-lib-packages.qmd | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/coding-practices/r-lib-packages.qmd b/coding-practices/r-lib-packages.qmd index 15885a81..b06bb7ce 100644 --- a/coding-practices/r-lib-packages.qmd +++ b/coding-practices/r-lib-packages.qmd @@ -209,16 +209,20 @@ This manual requires `{here}` for file paths (see @sec-here-package-practices). ### [`{memoise}`](https://memoise.r-lib.org/) {#sec-memoise} [`{memoise}`](https://memoise.r-lib.org/) adds memoisation (function-call caching) to R functions. -Wrapping an expensive or pure function with `memoise()` causes it to cache computed return values +Wrapping an expensive, pure function with `memoise::memoise()` causes it to cache computed return values in memory or on disk, so repeated calls with identical arguments return instantly from cache instead of recomputing. It supports multiple storage backends via the `cache` argument -(including `cachem::cache_mem()` for in-memory caching and `cachem::cache_disk()` for persistent disk caching across sessions), -and provides `forget()` and `is.memoised()` to manage and inspect cache state. -Use `{memoise}` to avoid redundant computation in iterative simulations, -API queries, -or repeated data extraction steps -where underlying inputs remain unchanged. +(such as `cachem::cache_mem()` for in-memory caching +and `cachem::cache_disk()` for persistent disk caching across sessions), +and provides `memoise::forget()` and `memoise::is.memoised()` to manage and inspect cache state. +Use `{memoise}` only for deterministic functions without side effects +(such as pure mathematical evaluations, +stable API queries, +or idempotent data processing pipelines). +Do not memoise stochastic simulation routines or pseudorandom number generators +unless the random seed or iteration index is explicitly included in the formal arguments, +as memoisation will otherwise suppress stochastic variability and return identical draws. ### [`{scales}`](https://scales.r-lib.org/) {#sec-scales} From 094a0c19a81a5cb5c962bc932fd088af4f787091 Mon Sep 17 00:00:00 2001 From: Douglas Ezra Morrison Date: Tue, 8 Sep 2026 09:22:12 -0700 Subject: [PATCH 4/5] docs: specify is.memoised/has_cache precision and explicit RNG seeding requirement (closes #353) --- coding-practices/r-lib-packages.qmd | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/coding-practices/r-lib-packages.qmd b/coding-practices/r-lib-packages.qmd index b06bb7ce..f17ef950 100644 --- a/coding-practices/r-lib-packages.qmd +++ b/coding-practices/r-lib-packages.qmd @@ -215,14 +215,16 @@ so repeated calls with identical arguments return instantly from cache instead o It supports multiple storage backends via the `cache` argument (such as `cachem::cache_mem()` for in-memory caching and `cachem::cache_disk()` for persistent disk caching across sessions), -and provides `memoise::forget()` and `memoise::is.memoised()` to manage and inspect cache state. +and provides `memoise::forget()` to clear caches, +`memoise::is.memoised()` to test whether a function is memoised, +and `memoise::has_cache()` to check whether specific arguments have cached results. Use `{memoise}` only for deterministic functions without side effects (such as pure mathematical evaluations, stable API queries, or idempotent data processing pipelines). -Do not memoise stochastic simulation routines or pseudorandom number generators -unless the random seed or iteration index is explicitly included in the formal arguments, -as memoisation will otherwise suppress stochastic variability and return identical draws. +Do not memoise stochastic simulation routines or functions that draw pseudorandom numbers; +memoisation suppresses stochastic variation across calls with identical arguments, +returning identical pseudorandom draws unless an explicit RNG seed argument is passed and sets the generator state deterministically. ### [`{scales}`](https://scales.r-lib.org/) {#sec-scales} From 78aec6163773d330bb47132e53bc97a7c7558238 Mon Sep 17 00:00:00 2001 From: Douglas Ezra Morrison Date: Tue, 8 Sep 2026 09:27:56 -0700 Subject: [PATCH 5/5] docs: prohibit memoising stochastic/RNG functions and format semantic line breaks (closes #353) --- coding-practices/r-lib-packages.qmd | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/coding-practices/r-lib-packages.qmd b/coding-practices/r-lib-packages.qmd index f17ef950..8e06e1f4 100644 --- a/coding-practices/r-lib-packages.qmd +++ b/coding-practices/r-lib-packages.qmd @@ -208,23 +208,27 @@ This manual requires `{here}` for file paths (see @sec-here-package-practices). ### [`{memoise}`](https://memoise.r-lib.org/) {#sec-memoise} -[`{memoise}`](https://memoise.r-lib.org/) adds memoisation (function-call caching) to R functions. -Wrapping an expensive, pure function with `memoise::memoise()` causes it to cache computed return values -in memory or on disk, -so repeated calls with identical arguments return instantly from cache instead of recomputing. +[`{memoise}`](https://memoise.r-lib.org/) adds memoisation +(function-call caching) to R functions. +Wrapping an expensive, pure function with `memoise::memoise()` +causes it to cache computed return values in memory or on disk, +so repeated calls with identical arguments return instantly from cache +instead of recomputing. It supports multiple storage backends via the `cache` argument (such as `cachem::cache_mem()` for in-memory caching and `cachem::cache_disk()` for persistent disk caching across sessions), and provides `memoise::forget()` to clear caches, `memoise::is.memoised()` to test whether a function is memoised, -and `memoise::has_cache()` to check whether specific arguments have cached results. +and `memoise::has_cache()` to check whether specific arguments +have cached results. Use `{memoise}` only for deterministic functions without side effects (such as pure mathematical evaluations, stable API queries, or idempotent data processing pipelines). -Do not memoise stochastic simulation routines or functions that draw pseudorandom numbers; -memoisation suppresses stochastic variation across calls with identical arguments, -returning identical pseudorandom draws unless an explicit RNG seed argument is passed and sets the generator state deterministically. +Never memoise stochastic simulation routines +or functions that generate pseudorandom numbers; +memoisation suppresses stochastic variation across repeated calls, +silently collapsing random variability by returning stale cached draws. ### [`{scales}`](https://scales.r-lib.org/) {#sec-scales}