| Title: | A Framework for Planning and Executing Analyses |
|---|---|
| Description: | Use a plan to run the same analysis function over many sets of arguments, or to run different functions on the same data. A plan holds the data sources, the argument sets and the functions. Running the plan loads the data once and passes it to every analysis, in sequence or in parallel. Typical uses are one method applied across strata such as locations or age groups, or across exposures and outcomes, and the tables and figures of a report. |
| Authors: | Richard Aubrey White [aut, cre, cph] (ORCID: <https://orcid.org/0000-0002-6747-1726>) |
| Maintainer: | Richard Aubrey White <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 2026.9.24 |
| Built: | 2026-09-24 15:26:02 UTC |
| Source: | https://github.com/raubreywhite/plnr |
create_rmarkdown() writes a small project to home. Its run.R builds a
Plan with one dataset and two analyses, then renders a report that runs
them.
create_rmarkdown(home)create_rmarkdown(home)
home |
Character string. The directory for the project. |
The project holds:
run.R, which calls org::initialize_project(), builds the plan and
renders the report.
R/table_death.R and R/figure_death.R, the two action functions.
paper/paper.Rmd, the report.
The empty directories results and raw.
run.R needs the org, ggplot2, huxtable, lubridate and rmarkdown packages.
plnr does not install them.
The project path, invisibly, as usethis::create_project() returns
it.
vignette("plnr") for the concepts that run.R uses.
Other utilities:
try_again()
home <- tempfile("plnr_example_") create_rmarkdown(home) list.files(home, recursive = TRUE) unlink(home, recursive = TRUE)home <- tempfile("plnr_example_") create_rmarkdown(home) list.files(home, recursive = TRUE) unlink(home, recursive = TRUE)
example_action_fn() is an example action function. It prints the names of
the datasets in data and the names of the elements in argset.
example_action_fn(data, argset)example_action_fn(data, argset)
data |
A named list of datasets, as a Plan passes it. |
argset |
A named list of arguments for one analysis. |
names(argset), invisibly.
vignette("plnr") for what an action function is.
Other example and test functions:
example_data_fn_nor_covid19_cases_by_time_location(),
test_action_fn()
p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_list( fn_name = "plnr::example_action_fn", l = list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) ) ) p$run_one("analysis_1")p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_list( fn_name = "plnr::example_action_fn", l = list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) ) ) p$run_one("analysis_1")
example_data_fn_nor_covid19_cases_by_time_location() is an example data
function: it takes no arguments and returns one dataset. Give its name to
Plan$add_data() as fn_name.
example_data_fn_nor_covid19_cases_by_time_location()example_data_fn_nor_covid19_cases_by_time_location()
nor_covid19_cases_by_time_location, a data.table.
vignette("adding_analyses"), which writes its own data functions.
Other example and test functions:
example_action_fn(),
test_action_fn()
dim(example_data_fn_nor_covid19_cases_by_time_location()) p <- plnr::Plan$new() p$add_data( name = "covid19_cases", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location" ) names(p$get_data())dim(example_data_fn_nor_covid19_cases_by_time_location()) p <- plnr::Plan$new() p$add_data( name = "covid19_cases", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location" ) names(p$get_data())
expand_list() returns one named list for each combination of the values
of its arguments. It works like tidyr::expand_grid(), but it returns a list
of lists, which Plan$add_argset_from_list() and
Plan$add_analysis_from_list() take.
expand_list(...)expand_list(...)
... |
Named vectors or lists. Each holds the values of one argument. |
A list of named lists, one for each combination. The first argument varies slowest.
vignette("adding_analyses"), which builds argsets with
expand_list().
Other plan helpers:
Plan,
get_anything(),
is_run_directly(),
set_opts()
argsets <- plnr::expand_list(location = c("oslo", "bergen"), age = c("0-14", "15+")) str(argsets)argsets <- plnr::expand_list(location = c("oslo", "bergen"), age = c("0-14", "15+")) str(argsets)
get_anything() returns the object that a name refers to. Plan uses it to
find the function that fn_name names.
get_anything(x, envir = parent.frame(), mode = "any")get_anything(x, envir = parent.frame(), mode = "any")
x |
Character string. The name of the object. |
envir |
The environment where step 2 starts. The default is the
environment that calls |
mode |
The type of object to find, as in |
get_anything() looks in this order and returns the first match:
For "pkg::name", the object that package pkg exports. It looks
nowhere else.
The environments from envir up to, but not including, the first global
environment or package namespace above it.
The global environment, then the search path.
The plnr namespace, then the packages that plnr imports.
The object that x names. get_anything() stops with an error when
no object matches.
vignette("plnr"), whose "Function names" section shows how a
Plan uses fn_name.
Other plan helpers:
Plan,
expand_list(),
is_run_directly(),
set_opts()
# Get a namespace-qualified object head(plnr::get_anything("plnr::nor_covid19_cases_by_time_location")) # Get an object from the calling environment f <- function() { x <- 1 get_anything("x") } f()# Get a namespace-qualified object head(plnr::get_anything("plnr::nor_covid19_cases_by_time_location")) # Get an object from the calling environment f <- function() { x <- 1 get_anything("x") } f()
is_run_directly() returns TRUE when you call it at the top level of the R
console or of an Rscript file. It returns FALSE inside a function, and
inside source(), eval() and a knitr chunk.
is_run_directly()is_run_directly()
Put it at the start of an action function to load data and argset while
you develop the function line by line. When the plan runs the function, it
returns FALSE, so the lines do nothing.
TRUE or FALSE.
vignette("plnr"), whose "Debugging" section shows the pattern.
Other plan helpers:
Plan,
expand_list(),
get_anything(),
set_opts()
f <- function() { is_run_directly() } f()f <- function() { is_run_directly() } f()
The data come from the Norwegian Surveillance System for Communicable
Diseases (MSIS). date is the date of the PCR test. The data were extracted
on 2022-05-04.
nor_covid19_cases_by_time_locationnor_covid19_cases_by_time_location
A data.table with 11028 rows and 18 variables:
"day" or "isoweek".
"nation" or "county".
"nor".
"nation_nor", or one of 11 county codes such as "county_nor03".
The year of the county borders, 2020.
"total".
"total".
ISO year.
ISO week.
ISO year and week, such as "2020-08".
Season, such as "2020/2021".
Week within the season.
Calendar year. NA in weekly rows.
Calendar month. NA in weekly rows.
Calendar year and month, such as "2020-M02". NA in weekly rows.
The date. In weekly rows, the Sunday that ends the ISO week.
Number of confirmed cases.
Number of confirmed cases per 100 000 population.
A Plan holds data sources and analyses, and runs the analyses on the data.
An analysis is one argset plus one action function.
An argset is a named list of arguments for one analysis. When an analysis
runs, its argset also holds index_analysis: the position or name that ran
it.
An action function MUST take the data as its first argument and the argset as
its second. It MAY take further arguments. The run methods pass their ...
to it in one of two ways:
A function given as fn gets the argset by position, and every argument in
....
A function given as fn_name gets data and argset by name. It gets
... only when it has more than two formal arguments.
get_anything() finds the function that fn_name names when the analysis
runs. If the name resolved in a local environment when you set fn_name,
the plan stores that environment and looks there first.
Plan$new() returns a new Plan object.
analysesA named list with one element for each analysis. Each
element holds argset and, once set, fn, fn_name and fn_env.
Plan$new()Create a new plan.
Plan$new(verbose = interactive() | config$force_verbose, use_foreach = FALSE)
verboseLogical. TRUE makes run_all() show progress. The default
is TRUE in an interactive session, or after
set_opts(force_verbose = TRUE).
use_foreachLogical or NULL. TRUE makes run_all() use foreach,
and FALSE a loop. NULL uses foreach when a backend with more than one
worker is registered and progressr is installed. The default is FALSE.
A new Plan object.
Plan$add_data()Add a data source. get_data() loads every data source.
Give one of fn, fn_name and direct. If you give more, direct
wins over fn_name, and fn_name wins over fn.
Plan$add_data(name, fn = NULL, fn_name = NULL, direct = NULL)
nameCharacter string. The name of the dataset in the list that
get_data() returns.
fnOptional. A function with no arguments that returns the dataset.
fn_nameOptional. The name of such a function, as a character string.
"pkg::fn" also works.
directOptional. The dataset itself.
The stored data source, invisibly: a list that holds fn,
fn_name, direct, name and fn_env.
p <- plnr::Plan$new()
data_fn <- function() {
return(plnr::nor_covid19_cases_by_time_location)
}
p$add_data("data_1", fn = data_fn)
p$add_data("data_2", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
p$add_data("data_3", direct = plnr::nor_covid19_cases_by_time_location)
names(p$get_data())
Plan$add_argset()Add an argset: an analysis that has no action function yet.
If an analysis with this name exists, add_argset() replaces its argset and
keeps its action function.
Plan$add_argset(name = uuid::UUIDgenerate(), ...)
nameCharacter string. The name of the analysis. The default is a UUID.
...Named arguments. They make up the argset.
The argset, invisibly.
p <- plnr::Plan$new()
p$add_argset("argset_1", var_1 = 3, var_b = "hello")
p$add_argset("argset_2", var_1 = 8, var_c = "hello2")
p$get_argsets_as_dt()
Plan$add_argset_from_df()Add one argset for each row of a data frame.
Plan$add_argset_from_df(df)
dfA data frame. Each row is one argset. A column name names the
analyses.
NULL, invisibly.
p <- plnr::Plan$new()
p$add_argset_from_df(data.frame(name = c("a", "b"), var_1 = c(1, 2)))
p$get_argsets_as_dt()
Plan$add_argset_from_list()Add one argset for each element of a list.
Plan$add_argset_from_list(l)
lA list of named lists. Each inner list is one argset. An element
name names the analysis.
NULL, invisibly.
p <- plnr::Plan$new()
p$add_argset_from_list(plnr::expand_list(var_1 = 1:2, var_2 = c("i", "j")))
p$get_argsets_as_dt()
Plan$add_analysis()Add an analysis: one argset and one action function. If an
analysis with this name exists, add_analysis() replaces it.
Plan$add_analysis(name = uuid::UUIDgenerate(), fn = NULL, fn_name = NULL, ...)
nameCharacter string. The name of the analysis. The default is a UUID.
fnOptional. The action function.
fn_nameOptional. The name of the action function, as a character
string. "pkg::fn" also works. Give fn or fn_name, not both.
...Named arguments. They make up the argset.
The argset, invisibly.
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
p$add_analysis(name = "analysis_1", fn_name = "plnr::example_action_fn")
p$run_one("analysis_1")
Plan$add_analysis_from_df()Add one analysis for each row of a data frame.
Plan$add_analysis_from_df(fn = NULL, fn_name = NULL, df)
fnOptional. The action function of every analysis.
fn_nameOptional. The name of the action function of every analysis.
A column fn_name in df overrides it.
dfA data frame. Each row is one argset. A column name names the
analyses.
NULL, invisibly.
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
p$add_analysis_from_df(
fn_name = "plnr::example_action_fn",
df = data.frame(name = c("a", "b"), var_1 = c(1, 2))
)
p$run_one("a")
Plan$add_analysis_from_list()Add one analysis for each element of a list.
Plan$add_analysis_from_list(fn = NULL, fn_name = NULL, l)
fnOptional. The action function of every analysis.
fn_nameOptional. The name of the action function of every analysis.
An element fn_name in an inner list overrides it.
lA list of named lists. Each inner list is one argset. An element
name names the analysis.
NULL, invisibly.
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = list(
list(name = "analysis_1", var_1 = 1),
list(name = "analysis_2", var_1 = 2)
)
)
p$run_one("analysis_1")
Plan$apply_action_fn_to_all_argsets()Give every analysis in the plan the same action function. It replaces any action function that an analysis already has.
Plan$apply_action_fn_to_all_argsets(fn = NULL, fn_name = NULL)
fnOptional. The action function.
fn_nameOptional. The name of the action function, as a character string.
NULL, invisibly.
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
p$add_argset_from_list(list(
list(name = "analysis_1", var_1 = 1),
list(name = "analysis_2", var_1 = 2)
))
p$apply_action_fn_to_all_argsets(fn_name = "plnr::example_action_fn")
p$run_one("analysis_1")
Plan$apply_analysis_fn_to_all()Deprecated. Use apply_action_fn_to_all_argsets().
Plan$apply_analysis_fn_to_all(fn = NULL, fn_name = NULL)
fnOptional. The action function.
fn_nameOptional. The name of the action function.
NULL, invisibly.
Plan$x_length()Count the analyses in the plan.
Plan$x_length()
An integer.
Plan$x_seq_along()Get the positions of the analyses, seq_along(analyses).
Plan$x_seq_along()
An integer vector.
Plan$set_progress()Set a progress bar that run_all() ticks once for each
analysis.
Plan$set_progress(pb)
pbAn object with a tick() method, such as one from
progress::progress_bar$new().
pb, invisibly.
Plan$set_progressor()Set a progressr progressor that run_all() calls once for each
analysis.
Plan$set_progressor(pb)
pbA function from progressr::progressor().
pb, invisibly.
Plan$set_verbose()Set verbose, which new() describes.
Plan$set_verbose(x)
xLogical.
x, invisibly.
Plan$set_use_foreach()Set use_foreach, which new() describes.
Plan$set_use_foreach(x)
xLogical or NULL.
x, invisibly.
Plan$get_data()Load every data source, and return the datasets as a named list.
Plan$get_data()
A named list with one element for each dataset, and an element
hash. hash$current is the spookyhash digest of the datasets.
hash$current_elements holds one digest for each dataset. plnr does not
read these digests.
If the only data source is data__________go_up_one_level and it returns
a named list, that list holds the datasets.
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
str(p$get_data(), max.level = 1)
Plan$get_analysis()Get one analysis.
Plan$get_analysis(index_analysis)
index_analysisThe position of the analysis, or its name.
The analysis, as analyses holds it. Its argset also holds
index_analysis.
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = list(
list(name = "analysis_1", var_1 = 1),
list(name = "analysis_2", var_1 = 2)
)
)
p$get_analysis("analysis_1")
Plan$get_argset()Get the argset of one analysis.
Plan$get_argset(index_analysis)
index_analysisThe position of the analysis, or its name.
The argset, a named list.
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = list(
list(name = "analysis_1", var_1 = 1),
list(name = "analysis_2", var_1 = 2)
)
)
p$get_argset("analysis_1")
Plan$get_argsets_as_dt()Get every argset as one row of a data.table.
Plan$get_argsets_as_dt()
A data.table. Its first columns are name_analysis and
index_analysis, and it has one more column for each argset element.
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = list(
list(name = "analysis_1", var_1 = 1),
list(name = "analysis_2", var_1 = 2)
)
)
p$get_argsets_as_dt()
Plan$run_one_with_data()Run one analysis on data that you give it.
Plan$run_one_with_data(index_analysis, data, ...)
index_analysisThe position of the analysis, or its name.
dataA named list of datasets, normally from get_data().
...Further arguments for the action function. See 'Details'.
The value that the action function returns.
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = list(
list(name = "analysis_1", var_1 = 1),
list(name = "analysis_2", var_1 = 2)
)
)
data <- p$get_data()
p$run_one_with_data("analysis_1", data)
Plan$run_one()Run one analysis. run_one() loads the data with get_data()
each time you call it.
Plan$run_one(index_analysis, ...)
index_analysisThe position of the analysis, or its name.
...Further arguments for the action function. See 'Details'.
The value that the action function returns.
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = list(
list(name = "analysis_1", var_1 = 1),
list(name = "analysis_2", var_1 = 2)
)
)
p$run_one("analysis_1")
Plan$run_all_with_data()Run every analysis on data that you give it.
Plan$run_all_with_data(data, ..., .plnr.options = NULL)
dataA named list of datasets, normally from get_data().
...Further arguments for the action function. See 'Details'.
.plnr.optionsA list of options for plnr. The action function
does not get it. chunk_size goes to foreach as
.options.future = list(chunk.size = chunk_size). Only a future-based
backend, such as doFuture, reads it. The default is 1.
A list, invisibly. Element i is the value that the action function
of analysis i returns. Without foreach, a NULL value at the end of the
plan adds no element, so the list can be shorter than the plan.
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = list(
list(name = "analysis_1", var_1 = 1),
list(name = "analysis_2", var_1 = 2)
)
)
data <- p$get_data()
results <- p$run_all_with_data(data)
Plan$run_all()Run every analysis. run_all() loads the data once with
get_data(), and passes it to every analysis.
Plan$run_all(...)
...Further arguments for the action function, and .plnr.options.
run_all_with_data() describes both.
A list, invisibly, as run_all_with_data() returns it.
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = list(
list(name = "analysis_1", var_1 = 1),
list(name = "analysis_2", var_1 = 2)
)
)
results <- p$run_all()
Plan$run_all_progress()Run every analysis, as run_all() does, inside
progressr::with_progress(). A progressr progressor then shows progress.
It stops with an error when the progressr package is not installed.
Plan$run_all_progress(...)
...Passed to run_all().
A list, invisibly, as run_all() returns it.
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = list(
list(name = "analysis_1", var_1 = 1),
list(name = "analysis_2", var_1 = 2)
)
)
if (requireNamespace("progressr", quietly = TRUE)) {
results <- p$run_all_progress()
}
Plan$run_all_parallel()Run every analysis in forked processes with
pbmcapply::pbmclapply(), which shows a progress bar. It loads the data once
with get_data(). Windows cannot fork. There, pbmcapply sets mc.cores to
1, warns, and runs the analyses in sequence.
Plan$run_all_parallel(mc.cores = getOption("mc.cores", 2L), ...)
mc.coresThe number of processes.
...Further arguments for the action function. See 'Details'.
A list, invisibly. Element i is the value that the action function
of analysis i returns.
Plan$clone()The objects of this class are cloneable with this method.
Plan$clone(deep = FALSE)
deepWhether to make a deep clone.
vignette("plnr") for the concepts. vignette("adding_analyses")
for worked single-function and multi-function plans.
Other plan helpers:
expand_list(),
get_anything(),
is_run_directly(),
set_opts()
## ------------------------------------------------ ## Method `Plan$add_data()` ## ------------------------------------------------ p <- plnr::Plan$new() data_fn <- function() { return(plnr::nor_covid19_cases_by_time_location) } p$add_data("data_1", fn = data_fn) p$add_data("data_2", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_data("data_3", direct = plnr::nor_covid19_cases_by_time_location) names(p$get_data()) ## ------------------------------------------------ ## Method `Plan$add_argset()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_argset("argset_1", var_1 = 3, var_b = "hello") p$add_argset("argset_2", var_1 = 8, var_c = "hello2") p$get_argsets_as_dt() ## ------------------------------------------------ ## Method `Plan$add_argset_from_df()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_argset_from_df(data.frame(name = c("a", "b"), var_1 = c(1, 2))) p$get_argsets_as_dt() ## ------------------------------------------------ ## Method `Plan$add_argset_from_list()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_argset_from_list(plnr::expand_list(var_1 = 1:2, var_2 = c("i", "j"))) p$get_argsets_as_dt() ## ------------------------------------------------ ## Method `Plan$add_analysis()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis(name = "analysis_1", fn_name = "plnr::example_action_fn") p$run_one("analysis_1") ## ------------------------------------------------ ## Method `Plan$add_analysis_from_df()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_df( fn_name = "plnr::example_action_fn", df = data.frame(name = c("a", "b"), var_1 = c(1, 2)) ) p$run_one("a") ## ------------------------------------------------ ## Method `Plan$add_analysis_from_list()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_list( fn_name = "plnr::example_action_fn", l = list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) ) ) p$run_one("analysis_1") ## ------------------------------------------------ ## Method `Plan$apply_action_fn_to_all_argsets()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_argset_from_list(list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) )) p$apply_action_fn_to_all_argsets(fn_name = "plnr::example_action_fn") p$run_one("analysis_1") ## ------------------------------------------------ ## Method `Plan$get_data()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") str(p$get_data(), max.level = 1) ## ------------------------------------------------ ## Method `Plan$get_analysis()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_list( fn_name = "plnr::example_action_fn", l = list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) ) ) p$get_analysis("analysis_1") ## ------------------------------------------------ ## Method `Plan$get_argset()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_list( fn_name = "plnr::example_action_fn", l = list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) ) ) p$get_argset("analysis_1") ## ------------------------------------------------ ## Method `Plan$get_argsets_as_dt()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_list( fn_name = "plnr::example_action_fn", l = list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) ) ) p$get_argsets_as_dt() ## ------------------------------------------------ ## Method `Plan$run_one_with_data()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_list( fn_name = "plnr::example_action_fn", l = list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) ) ) data <- p$get_data() p$run_one_with_data("analysis_1", data) ## ------------------------------------------------ ## Method `Plan$run_one()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_list( fn_name = "plnr::example_action_fn", l = list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) ) ) p$run_one("analysis_1") ## ------------------------------------------------ ## Method `Plan$run_all_with_data()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_list( fn_name = "plnr::example_action_fn", l = list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) ) ) data <- p$get_data() results <- p$run_all_with_data(data) ## ------------------------------------------------ ## Method `Plan$run_all()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_list( fn_name = "plnr::example_action_fn", l = list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) ) ) results <- p$run_all() ## ------------------------------------------------ ## Method `Plan$run_all_progress()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_list( fn_name = "plnr::example_action_fn", l = list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) ) ) if (requireNamespace("progressr", quietly = TRUE)) { results <- p$run_all_progress() }## ------------------------------------------------ ## Method `Plan$add_data()` ## ------------------------------------------------ p <- plnr::Plan$new() data_fn <- function() { return(plnr::nor_covid19_cases_by_time_location) } p$add_data("data_1", fn = data_fn) p$add_data("data_2", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_data("data_3", direct = plnr::nor_covid19_cases_by_time_location) names(p$get_data()) ## ------------------------------------------------ ## Method `Plan$add_argset()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_argset("argset_1", var_1 = 3, var_b = "hello") p$add_argset("argset_2", var_1 = 8, var_c = "hello2") p$get_argsets_as_dt() ## ------------------------------------------------ ## Method `Plan$add_argset_from_df()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_argset_from_df(data.frame(name = c("a", "b"), var_1 = c(1, 2))) p$get_argsets_as_dt() ## ------------------------------------------------ ## Method `Plan$add_argset_from_list()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_argset_from_list(plnr::expand_list(var_1 = 1:2, var_2 = c("i", "j"))) p$get_argsets_as_dt() ## ------------------------------------------------ ## Method `Plan$add_analysis()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis(name = "analysis_1", fn_name = "plnr::example_action_fn") p$run_one("analysis_1") ## ------------------------------------------------ ## Method `Plan$add_analysis_from_df()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_df( fn_name = "plnr::example_action_fn", df = data.frame(name = c("a", "b"), var_1 = c(1, 2)) ) p$run_one("a") ## ------------------------------------------------ ## Method `Plan$add_analysis_from_list()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_list( fn_name = "plnr::example_action_fn", l = list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) ) ) p$run_one("analysis_1") ## ------------------------------------------------ ## Method `Plan$apply_action_fn_to_all_argsets()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_argset_from_list(list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) )) p$apply_action_fn_to_all_argsets(fn_name = "plnr::example_action_fn") p$run_one("analysis_1") ## ------------------------------------------------ ## Method `Plan$get_data()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") str(p$get_data(), max.level = 1) ## ------------------------------------------------ ## Method `Plan$get_analysis()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_list( fn_name = "plnr::example_action_fn", l = list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) ) ) p$get_analysis("analysis_1") ## ------------------------------------------------ ## Method `Plan$get_argset()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_list( fn_name = "plnr::example_action_fn", l = list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) ) ) p$get_argset("analysis_1") ## ------------------------------------------------ ## Method `Plan$get_argsets_as_dt()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_list( fn_name = "plnr::example_action_fn", l = list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) ) ) p$get_argsets_as_dt() ## ------------------------------------------------ ## Method `Plan$run_one_with_data()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_list( fn_name = "plnr::example_action_fn", l = list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) ) ) data <- p$get_data() p$run_one_with_data("analysis_1", data) ## ------------------------------------------------ ## Method `Plan$run_one()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_list( fn_name = "plnr::example_action_fn", l = list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) ) ) p$run_one("analysis_1") ## ------------------------------------------------ ## Method `Plan$run_all_with_data()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_list( fn_name = "plnr::example_action_fn", l = list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) ) ) data <- p$get_data() results <- p$run_all_with_data(data) ## ------------------------------------------------ ## Method `Plan$run_all()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_list( fn_name = "plnr::example_action_fn", l = list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) ) ) results <- p$run_all() ## ------------------------------------------------ ## Method `Plan$run_all_progress()` ## ------------------------------------------------ p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") p$add_analysis_from_list( fn_name = "plnr::example_action_fn", l = list( list(name = "analysis_1", var_1 = 1), list(name = "analysis_2", var_1 = 2) ) ) if (requireNamespace("progressr", quietly = TRUE)) { results <- p$run_all_progress() }
set_opts() sets options for the whole package.
set_opts(force_verbose = FALSE)set_opts(force_verbose = FALSE)
force_verbose |
Logical. |
force_verbose, invisibly.
vignette("plnr") for the concepts.
Other plan helpers:
Plan,
expand_list(),
get_anything(),
is_run_directly()
set_opts(force_verbose = TRUE) set_opts(force_verbose = FALSE)set_opts(force_verbose = TRUE) set_opts(force_verbose = FALSE)
test_action_fn() is a placeholder action function. It ignores its arguments.
test_action_fn(data, argset)test_action_fn(data, argset)
data |
Not used. |
argset |
Not used. |
The number 1, a double.
vignette("plnr") for what an action function is.
Other example and test functions:
example_action_fn(),
example_data_fn_nor_covid19_cases_by_time_location()
test_action_fn(data = list(), argset = list()) p <- plnr::Plan$new() p$add_data(name = "deaths", direct = data.frame(deaths = 1:4, year = 2001:2004)) p$add_analysis(name = "analysis_1", fn_name = "plnr::test_action_fn") p$run_one("analysis_1")test_action_fn(data = list(), argset = list()) p <- plnr::Plan$new() p$add_data(name = "deaths", direct = data.frame(deaths = 1:4, year = 2001:2004)) p$add_analysis(name = "analysis_1", fn_name = "plnr::test_action_fn") p$run_one("analysis_1")
try_again() evaluates x up to times times, and stops at the first
attempt that raises no error. After each failed attempt it waits a number of
seconds drawn from a uniform distribution on
[delay_seconds_min, delay_seconds_max]. The delay does not grow with the
attempt number, so this is not exponential backoff.
try_again( x, times = 2, delay_seconds_min = 5, delay_seconds_max = 10, verbose = FALSE )try_again( x, times = 2, delay_seconds_min = 5, delay_seconds_max = 10, verbose = FALSE )
x |
The code to run. |
times |
The maximum number of attempts. The default is 2. |
delay_seconds_min |
The shortest delay in seconds. The default is 5. |
delay_seconds_max |
The longest delay in seconds. The default is 10. |
verbose |
Logical. |
try_again() is adapted from try_again() in testthat. It adds the delay
and the verbose argument.
TRUE, invisibly, after the first attempt that succeeds. When every
attempt fails, try_again() signals the error of the last attempt.
vignette("plnr") for the concepts. try_again() itself is not
part of the Plan workflow.
Other utilities:
create_rmarkdown()
try_again(1 + 1) # Fail once, then succeed. The delays are 0 so that the example runs fast. attempt_n <- 0 try_again( { attempt_n <- attempt_n + 1 if (attempt_n < 2) stop("not ready yet") }, times = 3, delay_seconds_min = 0, delay_seconds_max = 0 ) attempt_ntry_again(1 + 1) # Fail once, then succeed. The delays are 0 so that the example runs fast. attempt_n <- 0 try_again( { attempt_n <- attempt_n + 1 if (attempt_n < 2) stop("not ready yet") }, times = 3, delay_seconds_min = 0, delay_seconds_max = 0 ) attempt_n