Plan: R6 Class for Planning and Executing Analyses
In plnr: A Framework for Planning and Executing Analyses
Plan R Documentation
R6 Class for Planning and Executing Analyses
Description
The Plan class provides a framework for organizing and executing multiple analyses
on one or more datasets. It enforces a structured approach to analysis by:
-
Data Management:
Loading data once and reusing across analyses
Separating data cleaning from analysis
Providing hash-based tracking of data changes
-
Analysis Structure:
Requiring all analyses to use the same data sources
Standardizing analysis functions to accept only data and argset parameters
Organizing analyses into clear, maintainable plans
-
Execution Control:
Supporting both single-function and multi-function analysis plans
Providing flexible execution options (sequential or parallel)
Including built-in debugging tools
Details
The framework uses three main concepts:
-
Argset: A named list containing a set of arguments for an analysis
-
Analysis: A combination of one argset and one action function
-
Plan: A container that holds one data pull and a list of analyses
Public fields
analysesList of analyses, each containing an argset and action function
Methods
Public methods
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Method new()
Create a new Plan instance
Usage
Plan$new(verbose = interactive() | config$force_verbose, use_foreach = FALSE)
Arguments
verboseLogical, whether to show verbose output. Defaults to TRUE in interactive mode
or when config$force_verbose is TRUE
use_foreachLogical, whether to use foreach for parallel processing.
NULL = program decides, FALSE = use loop, TRUE = use foreach
Returns
A new Plan instance
Method add_data()
Add a new dataset to the plan
Usage
Plan$add_data(name, fn = NULL, fn_name = NULL, direct = NULL)
Arguments
nameCharacter string, name of the dataset
fnFunction that returns the dataset (optional)
fn_nameCharacter string, name of a function that returns the dataset (optional)
directDirect dataset object (optional)
Returns
NULL, modifies the plan in place
Examples
p <- plnr::Plan$new()
# Add data using a function
data_fn <- function() { return(plnr::nor_covid19_cases_by_time_location) }
p$add_data("data_1", fn = data_fn)
# Add data using a function name
p$add_data("data_2", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
# Add data directly
p$add_data("data_3", direct = plnr::nor_covid19_cases_by_time_location)
# View added data
p$get_data()
Method add_argset()
Add a new argset to the plan
Usage
Plan$add_argset(name = uuid::UUIDgenerate(), ...)
Arguments
nameCharacter string, name of the argset (defaults to a UUID)
...Named arguments that will comprise the argset
Returns
NULL, modifies the plan in place
Examples
p <- plnr::Plan$new()
# Add argsets with different arguments
p$add_argset("argset_1", var_1 = 3, var_b = "hello")
p$add_argset("argset_2", var_1 = 8, var_c = "hello2")
# View added argsets
p$get_argsets_as_dt()
Method add_argset_from_df()
Add multiple argsets from a data frame
Usage
Plan$add_argset_from_df(df)
Arguments
dfData frame where each row represents a new argset
Returns
NULL, modifies the plan in place
Examples
p <- plnr::Plan$new()
# Create data frame of argsets
batch_argset_df <- data.frame(
name = c("a", "b", "c"),
var_1 = c(1, 2, 3),
var_2 = c("i", "j", "k")
)
# Add argsets from data frame
p$add_argset_from_df(batch_argset_df)
# View added argsets
p$get_argsets_as_dt()
Method add_argset_from_list()
Add multiple argsets from a list
Usage
Plan$add_argset_from_list(l)
Arguments
lList of lists, where each inner list represents a new argset
Returns
NULL, modifies the plan in place
Examples
p <- plnr::Plan$new()
# Create list of argsets
batch_argset_list <- list(
list(name = "a", var_1 = 1, var_2 = "i"),
list(name = "b", var_1 = 2, var_2 = "j"),
list(name = "c", var_1 = 3, var_2 = "k")
)
# Add argsets from list
p$add_argset_from_list(batch_argset_list)
# View added argsets
p$get_argsets_as_dt()
Method add_analysis()
Add a new analysis to the plan
Usage
Plan$add_analysis(name = uuid::UUIDgenerate(), fn = NULL, fn_name = NULL, ...)
Arguments
nameCharacter string, name of the analysis (defaults to a UUID)
fnFunction to use for the analysis (optional)
fn_nameCharacter string, name of the function to use (optional)
...Additional arguments to be added to the argset
Returns
NULL, modifies the plan in place
Examples
p <- plnr::Plan$new()
# Add example data
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
# Add analysis
p$add_analysis(
name = "analysis_1",
fn_name = "plnr::example_action_fn"
)
# View argsets and run analysis
p$get_argsets_as_dt()
p$run_one("analysis_1")
Method add_analysis_from_df()
Add multiple analyses from a data frame
Usage
Plan$add_analysis_from_df(fn = NULL, fn_name = NULL, df)
Arguments
fnFunction to use for all analyses (optional)
fn_nameCharacter string, name of the function to use (optional)
dfData frame where each row represents a new analysis
Returns
NULL, modifies the plan in place
Examples
p <- plnr::Plan$new()
# Add example data
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
# Create data frame of analyses
batch_argset_df <- data.frame(
name = c("a", "b", "c"),
var_1 = c(1, 2, 3),
var_2 = c("i", "j", "k")
)
# Add analyses from data frame
p$add_analysis_from_df(
fn_name = "plnr::example_action_fn",
df = batch_argset_df
)
# View argsets and run example
p$get_argsets_as_dt()
p$run_one(1)
Method add_analysis_from_list()
Add multiple analyses from a list
Usage
Plan$add_analysis_from_list(fn = NULL, fn_name = NULL, l)
Arguments
fnFunction to use for all analyses (optional)
fn_nameCharacter string, name of the function to use (optional)
lList of lists, where each inner list represents a new analysis
Returns
NULL, modifies the plan in place
Examples
p <- plnr::Plan$new()
# Add example data
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
# Create list of analyses
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
# Add analyses from list
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
# View argsets and run example
p$get_argsets_as_dt()
p$run_one("analysis_1")
Method apply_action_fn_to_all_argsets()
Applies an action function to all the argsets
Usage
Plan$apply_action_fn_to_all_argsets(fn = NULL, fn_name = NULL)
Arguments
fnAction function.
fn_nameAction function name.
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_argset_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
p$get_argsets_as_dt()
p$apply_action_fn_to_all_argsets(fn_name = "plnr::example_action_fn")
p$run_one("analysis_1")
Method apply_analysis_fn_to_all()
Deprecated. Use apply_action_fn_to_all_argsets.
Usage
Plan$apply_analysis_fn_to_all(fn = NULL, fn_name = NULL)
Arguments
fnAction function.
fn_nameAction function name.
Method x_length()
Number of analyses in the plan.
Usage
Plan$x_length()
Method x_seq_along()
Generate a regular sequence from 1 to the length of the analyses in the plan.
Usage
Plan$x_seq_along()
Method set_progress()
Set an internal progress bar
Usage
Plan$set_progress(pb)
Arguments
pbProgress bar.
Method set_progressor()
Set an internal progressor progress bar
Usage
Plan$set_progressor(pb)
Arguments
pbprogressor progress bar.
Method set_verbose()
Set verbose flag
Usage
Plan$set_verbose(x)
Arguments
xBoolean.
Method set_use_foreach()
Set use_foreach flag
Usage
Plan$set_use_foreach(x)
Arguments
xBoolean.
Method get_data()
Extracts the data provided via 'add_data' and returns it as a named list.
Usage
Plan$get_data()
Returns
Named list, where most elements have been added via add_data.
One extra named element is called 'hash'. 'hash' contains the data hashes of particular datasets/variables, as calculated using the 'spookyhash' algorithm via digest::digest.
'hash' contains two named elements:
current (the hash of the entire named list)
current_elements (the hash of the named elements within the named list)
Examples
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
p$get_data()
Method get_analysis()
Extracts an analysis from the plan.
Usage
Plan$get_analysis(index_analysis)
Arguments
index_analysisEither an integer (1:length(analyses)) or a character string representing the name of the analysis.
Returns
An analysis.
Examples
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
p$get_analysis("analysis_1")
Method get_argset()
Extracts an argset from the plan.
Usage
Plan$get_argset(index_analysis)
Arguments
index_analysisEither an integer (1:length(analyses)) or a character string representing the name of the analysis.
Returns
An argset
Examples
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
p$get_argset("analysis_1")
Method get_argsets_as_dt()
Gets all argsets and presents them as a data.table.
Usage
Plan$get_argsets_as_dt()
Returns
Data.table that contains all the argsets within a plan.
Examples
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
p$get_argsets_as_dt()
Method run_one_with_data()
Run one analysis (data is provided by user).
Usage
Plan$run_one_with_data(index_analysis, data, ...)
Arguments
index_analysisEither an integer (1:length(analyses)) or a character string representing the name of the analysis.
dataNamed list (generally obtained from p$get_data()).
...Not used.
Returns
Returned value from the action function.
Examples
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
data <- p$get_data()
p$run_one_with_data("analysis_1", data)
Method run_one()
Run one analysis (data is obtained automatically from self$get_data()).
Usage
Plan$run_one(index_analysis, ...)
Arguments
index_analysisEither an integer (1:length(analyses)) or a character string representing the name of the analysis.
...Not used.
Returns
Returned value from the action function.
Examples
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
p$run_one("analysis_1")
Method run_all_with_data()
Run all analyses (data is provided by user).
Usage
Plan$run_all_with_data(data, ...)
Arguments
dataNamed list (generally obtained from p$get_data()).
...Not used.
Returns
List where each element contains the returned value from the action function.
Examples
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
data <- p$get_data()
p$run_all_with_data(data)
Method run_all()
Run all analyses (data is obtained automatically from self$get_data()).
Usage
Plan$run_all(...)
Arguments
...Not used.
Returns
List where each element contains the returned value from the action function.
Examples
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
p$run_all()
Method run_all_progress()
Run all analyses with a progress bar (data is obtained automatically from self$get_data()).
Usage
Plan$run_all_progress(...)
Arguments
...Not used.
Returns
List where each element contains the returned value from the action function.
Examples
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
p$run_all_progress()
Method run_all_parallel()
Run all analyses in parallel (data is obtained automatically from self$get_data()).
This function only works on linux computers and uses pbmcapply as the parallel backend.
Usage
Plan$run_all_parallel(mc.cores = getOption("mc.cores", 2L), ...)
Arguments
mc.coresNumber of cores to be used.
...Not used.
Returns
List where each element contains the returned value from the action function.
Method clone()
The objects of this class are cloneable with this method.
Usage
Plan$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Examples
## ------------------------------------------------
## Method `Plan$add_data`
## ------------------------------------------------
p <- plnr::Plan$new()
# Add data using a function
data_fn <- function() { return(plnr::nor_covid19_cases_by_time_location) }
p$add_data("data_1", fn = data_fn)
# Add data using a function name
p$add_data("data_2", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
# Add data directly
p$add_data("data_3", direct = plnr::nor_covid19_cases_by_time_location)
# View added data
p$get_data()
## ------------------------------------------------
## Method `Plan$add_argset`
## ------------------------------------------------
p <- plnr::Plan$new()
# Add argsets with different arguments
p$add_argset("argset_1", var_1 = 3, var_b = "hello")
p$add_argset("argset_2", var_1 = 8, var_c = "hello2")
# View added argsets
p$get_argsets_as_dt()
## ------------------------------------------------
## Method `Plan$add_argset_from_df`
## ------------------------------------------------
p <- plnr::Plan$new()
# Create data frame of argsets
batch_argset_df <- data.frame(
name = c("a", "b", "c"),
var_1 = c(1, 2, 3),
var_2 = c("i", "j", "k")
)
# Add argsets from data frame
p$add_argset_from_df(batch_argset_df)
# View added argsets
p$get_argsets_as_dt()
## ------------------------------------------------
## Method `Plan$add_argset_from_list`
## ------------------------------------------------
p <- plnr::Plan$new()
# Create list of argsets
batch_argset_list <- list(
list(name = "a", var_1 = 1, var_2 = "i"),
list(name = "b", var_1 = 2, var_2 = "j"),
list(name = "c", var_1 = 3, var_2 = "k")
)
# Add argsets from list
p$add_argset_from_list(batch_argset_list)
# View added argsets
p$get_argsets_as_dt()
## ------------------------------------------------
## Method `Plan$add_analysis`
## ------------------------------------------------
p <- plnr::Plan$new()
# Add example data
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
# Add analysis
p$add_analysis(
name = "analysis_1",
fn_name = "plnr::example_action_fn"
)
# View argsets and run analysis
p$get_argsets_as_dt()
p$run_one("analysis_1")
## ------------------------------------------------
## Method `Plan$add_analysis_from_df`
## ------------------------------------------------
p <- plnr::Plan$new()
# Add example data
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
# Create data frame of analyses
batch_argset_df <- data.frame(
name = c("a", "b", "c"),
var_1 = c(1, 2, 3),
var_2 = c("i", "j", "k")
)
# Add analyses from data frame
p$add_analysis_from_df(
fn_name = "plnr::example_action_fn",
df = batch_argset_df
)
# View argsets and run example
p$get_argsets_as_dt()
p$run_one(1)
## ------------------------------------------------
## Method `Plan$add_analysis_from_list`
## ------------------------------------------------
p <- plnr::Plan$new()
# Add example data
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
# Create list of analyses
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
# Add analyses from list
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
# View argsets and run example
p$get_argsets_as_dt()
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")
p$get_data()
## ------------------------------------------------
## 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")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
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")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
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")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
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")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
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")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
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")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
data <- p$get_data()
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")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
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")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
p$run_all_progress()
plnr documentation built on Nov. 23, 2025, 1:06 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| Plan | R Documentation |
R6 Class for Planning and Executing Analyses
Description
The Plan class provides a framework for organizing and executing multiple analyses
on one or more datasets. It enforces a structured approach to analysis by:
-
Data Management:
Loading data once and reusing across analyses
Separating data cleaning from analysis
Providing hash-based tracking of data changes
-
Analysis Structure:
Requiring all analyses to use the same data sources
Standardizing analysis functions to accept only
dataandargsetparametersOrganizing analyses into clear, maintainable plans
-
Execution Control:
Supporting both single-function and multi-function analysis plans
Providing flexible execution options (sequential or parallel)
Including built-in debugging tools
Details
The framework uses three main concepts:
-
Argset: A named list containing a set of arguments for an analysis
-
Analysis: A combination of one argset and one action function
-
Plan: A container that holds one data pull and a list of analyses
Public fields
analysesList of analyses, each containing an argset and action function
Methods
Public methods
Method new()
Create a new Plan instance
Usage
Plan$new(verbose = interactive() | config$force_verbose, use_foreach = FALSE)
Arguments
verboseLogical, whether to show verbose output. Defaults to TRUE in interactive mode or when config$force_verbose is TRUE
use_foreachLogical, whether to use foreach for parallel processing. NULL = program decides, FALSE = use loop, TRUE = use foreach
Returns
A new Plan instance
Method add_data()
Add a new dataset to the plan
Usage
Plan$add_data(name, fn = NULL, fn_name = NULL, direct = NULL)
Arguments
nameCharacter string, name of the dataset
fnFunction that returns the dataset (optional)
fn_nameCharacter string, name of a function that returns the dataset (optional)
directDirect dataset object (optional)
Returns
NULL, modifies the plan in place
Examples
p <- plnr::Plan$new()
# Add data using a function
data_fn <- function() { return(plnr::nor_covid19_cases_by_time_location) }
p$add_data("data_1", fn = data_fn)
# Add data using a function name
p$add_data("data_2", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
# Add data directly
p$add_data("data_3", direct = plnr::nor_covid19_cases_by_time_location)
# View added data
p$get_data()
Method add_argset()
Add a new argset to the plan
Usage
Plan$add_argset(name = uuid::UUIDgenerate(), ...)
Arguments
nameCharacter string, name of the argset (defaults to a UUID)
...Named arguments that will comprise the argset
Returns
NULL, modifies the plan in place
Examples
p <- plnr::Plan$new()
# Add argsets with different arguments
p$add_argset("argset_1", var_1 = 3, var_b = "hello")
p$add_argset("argset_2", var_1 = 8, var_c = "hello2")
# View added argsets
p$get_argsets_as_dt()
Method add_argset_from_df()
Add multiple argsets from a data frame
Usage
Plan$add_argset_from_df(df)
Arguments
dfData frame where each row represents a new argset
Returns
NULL, modifies the plan in place
Examples
p <- plnr::Plan$new()
# Create data frame of argsets
batch_argset_df <- data.frame(
name = c("a", "b", "c"),
var_1 = c(1, 2, 3),
var_2 = c("i", "j", "k")
)
# Add argsets from data frame
p$add_argset_from_df(batch_argset_df)
# View added argsets
p$get_argsets_as_dt()
Method add_argset_from_list()
Add multiple argsets from a list
Usage
Plan$add_argset_from_list(l)
Arguments
lList of lists, where each inner list represents a new argset
Returns
NULL, modifies the plan in place
Examples
p <- plnr::Plan$new() # Create list of argsets batch_argset_list <- list( list(name = "a", var_1 = 1, var_2 = "i"), list(name = "b", var_1 = 2, var_2 = "j"), list(name = "c", var_1 = 3, var_2 = "k") ) # Add argsets from list p$add_argset_from_list(batch_argset_list) # View added argsets p$get_argsets_as_dt()
Method add_analysis()
Add a new analysis to the plan
Usage
Plan$add_analysis(name = uuid::UUIDgenerate(), fn = NULL, fn_name = NULL, ...)
Arguments
nameCharacter string, name of the analysis (defaults to a UUID)
fnFunction to use for the analysis (optional)
fn_nameCharacter string, name of the function to use (optional)
...Additional arguments to be added to the argset
Returns
NULL, modifies the plan in place
Examples
p <- plnr::Plan$new()
# Add example data
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
# Add analysis
p$add_analysis(
name = "analysis_1",
fn_name = "plnr::example_action_fn"
)
# View argsets and run analysis
p$get_argsets_as_dt()
p$run_one("analysis_1")
Method add_analysis_from_df()
Add multiple analyses from a data frame
Usage
Plan$add_analysis_from_df(fn = NULL, fn_name = NULL, df)
Arguments
fnFunction to use for all analyses (optional)
fn_nameCharacter string, name of the function to use (optional)
dfData frame where each row represents a new analysis
Returns
NULL, modifies the plan in place
Examples
p <- plnr::Plan$new()
# Add example data
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
# Create data frame of analyses
batch_argset_df <- data.frame(
name = c("a", "b", "c"),
var_1 = c(1, 2, 3),
var_2 = c("i", "j", "k")
)
# Add analyses from data frame
p$add_analysis_from_df(
fn_name = "plnr::example_action_fn",
df = batch_argset_df
)
# View argsets and run example
p$get_argsets_as_dt()
p$run_one(1)
Method add_analysis_from_list()
Add multiple analyses from a list
Usage
Plan$add_analysis_from_list(fn = NULL, fn_name = NULL, l)
Arguments
fnFunction to use for all analyses (optional)
fn_nameCharacter string, name of the function to use (optional)
lList of lists, where each inner list represents a new analysis
Returns
NULL, modifies the plan in place
Examples
p <- plnr::Plan$new()
# Add example data
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
# Create list of analyses
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
# Add analyses from list
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
# View argsets and run example
p$get_argsets_as_dt()
p$run_one("analysis_1")
Method apply_action_fn_to_all_argsets()
Applies an action function to all the argsets
Usage
Plan$apply_action_fn_to_all_argsets(fn = NULL, fn_name = NULL)
Arguments
fnAction function.
fn_nameAction function name. p <- plnr::Plan$new() p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location") batch_argset_list <- list( list(name = "analysis_1", var_1 = 1, var_2 = "i"), list(name = "analysis_2", var_1 = 2, var_2 = "j"), list(name = "analysis_3", var_1 = 3, var_2 = "k") ) p$add_argset_from_list( fn_name = "plnr::example_action_fn", l = batch_argset_list ) p$get_argsets_as_dt() p$apply_action_fn_to_all_argsets(fn_name = "plnr::example_action_fn") p$run_one("analysis_1")
Method apply_analysis_fn_to_all()
Deprecated. Use apply_action_fn_to_all_argsets.
Usage
Plan$apply_analysis_fn_to_all(fn = NULL, fn_name = NULL)
Arguments
fnAction function.
fn_nameAction function name.
Method x_length()
Number of analyses in the plan.
Usage
Plan$x_length()
Method x_seq_along()
Generate a regular sequence from 1 to the length of the analyses in the plan.
Usage
Plan$x_seq_along()
Method set_progress()
Set an internal progress bar
Usage
Plan$set_progress(pb)
Arguments
pbProgress bar.
Method set_progressor()
Set an internal progressor progress bar
Usage
Plan$set_progressor(pb)
Arguments
pbprogressor progress bar.
Method set_verbose()
Set verbose flag
Usage
Plan$set_verbose(x)
Arguments
xBoolean.
Method set_use_foreach()
Set use_foreach flag
Usage
Plan$set_use_foreach(x)
Arguments
xBoolean.
Method get_data()
Extracts the data provided via 'add_data' and returns it as a named list.
Usage
Plan$get_data()
Returns
Named list, where most elements have been added via add_data.
One extra named element is called 'hash'. 'hash' contains the data hashes of particular datasets/variables, as calculated using the 'spookyhash' algorithm via digest::digest. 'hash' contains two named elements:
current (the hash of the entire named list)
current_elements (the hash of the named elements within the named list)
Examples
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
p$get_data()
Method get_analysis()
Extracts an analysis from the plan.
Usage
Plan$get_analysis(index_analysis)
Arguments
index_analysisEither an integer (1:length(analyses)) or a character string representing the name of the analysis.
Returns
An analysis.
Examples
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
p$get_analysis("analysis_1")
Method get_argset()
Extracts an argset from the plan.
Usage
Plan$get_argset(index_analysis)
Arguments
index_analysisEither an integer (1:length(analyses)) or a character string representing the name of the analysis.
Returns
An argset
Examples
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
p$get_argset("analysis_1")
Method get_argsets_as_dt()
Gets all argsets and presents them as a data.table.
Usage
Plan$get_argsets_as_dt()
Returns
Data.table that contains all the argsets within a plan.
Examples
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
p$get_argsets_as_dt()
Method run_one_with_data()
Run one analysis (data is provided by user).
Usage
Plan$run_one_with_data(index_analysis, data, ...)
Arguments
index_analysisEither an integer (1:length(analyses)) or a character string representing the name of the analysis.
dataNamed list (generally obtained from p$get_data()).
...Not used.
Returns
Returned value from the action function.
Examples
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
data <- p$get_data()
p$run_one_with_data("analysis_1", data)
Method run_one()
Run one analysis (data is obtained automatically from self$get_data()).
Usage
Plan$run_one(index_analysis, ...)
Arguments
index_analysisEither an integer (1:length(analyses)) or a character string representing the name of the analysis.
...Not used.
Returns
Returned value from the action function.
Examples
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
p$run_one("analysis_1")
Method run_all_with_data()
Run all analyses (data is provided by user).
Usage
Plan$run_all_with_data(data, ...)
Arguments
dataNamed list (generally obtained from p$get_data()).
...Not used.
Returns
List where each element contains the returned value from the action function.
Examples
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
data <- p$get_data()
p$run_all_with_data(data)
Method run_all()
Run all analyses (data is obtained automatically from self$get_data()).
Usage
Plan$run_all(...)
Arguments
...Not used.
Returns
List where each element contains the returned value from the action function.
Examples
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
p$run_all()
Method run_all_progress()
Run all analyses with a progress bar (data is obtained automatically from self$get_data()).
Usage
Plan$run_all_progress(...)
Arguments
...Not used.
Returns
List where each element contains the returned value from the action function.
Examples
p <- plnr::Plan$new()
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
p$run_all_progress()
Method run_all_parallel()
Run all analyses in parallel (data is obtained automatically from self$get_data()).
This function only works on linux computers and uses pbmcapply as the parallel backend.
Usage
Plan$run_all_parallel(mc.cores = getOption("mc.cores", 2L), ...)Arguments
mc.coresNumber of cores to be used.
...Not used.
Returns
List where each element contains the returned value from the action function.
Method clone()
The objects of this class are cloneable with this method.
Usage
Plan$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Examples
## ------------------------------------------------
## Method `Plan$add_data`
## ------------------------------------------------
p <- plnr::Plan$new()
# Add data using a function
data_fn <- function() { return(plnr::nor_covid19_cases_by_time_location) }
p$add_data("data_1", fn = data_fn)
# Add data using a function name
p$add_data("data_2", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
# Add data directly
p$add_data("data_3", direct = plnr::nor_covid19_cases_by_time_location)
# View added data
p$get_data()
## ------------------------------------------------
## Method `Plan$add_argset`
## ------------------------------------------------
p <- plnr::Plan$new()
# Add argsets with different arguments
p$add_argset("argset_1", var_1 = 3, var_b = "hello")
p$add_argset("argset_2", var_1 = 8, var_c = "hello2")
# View added argsets
p$get_argsets_as_dt()
## ------------------------------------------------
## Method `Plan$add_argset_from_df`
## ------------------------------------------------
p <- plnr::Plan$new()
# Create data frame of argsets
batch_argset_df <- data.frame(
name = c("a", "b", "c"),
var_1 = c(1, 2, 3),
var_2 = c("i", "j", "k")
)
# Add argsets from data frame
p$add_argset_from_df(batch_argset_df)
# View added argsets
p$get_argsets_as_dt()
## ------------------------------------------------
## Method `Plan$add_argset_from_list`
## ------------------------------------------------
p <- plnr::Plan$new()
# Create list of argsets
batch_argset_list <- list(
list(name = "a", var_1 = 1, var_2 = "i"),
list(name = "b", var_1 = 2, var_2 = "j"),
list(name = "c", var_1 = 3, var_2 = "k")
)
# Add argsets from list
p$add_argset_from_list(batch_argset_list)
# View added argsets
p$get_argsets_as_dt()
## ------------------------------------------------
## Method `Plan$add_analysis`
## ------------------------------------------------
p <- plnr::Plan$new()
# Add example data
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
# Add analysis
p$add_analysis(
name = "analysis_1",
fn_name = "plnr::example_action_fn"
)
# View argsets and run analysis
p$get_argsets_as_dt()
p$run_one("analysis_1")
## ------------------------------------------------
## Method `Plan$add_analysis_from_df`
## ------------------------------------------------
p <- plnr::Plan$new()
# Add example data
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
# Create data frame of analyses
batch_argset_df <- data.frame(
name = c("a", "b", "c"),
var_1 = c(1, 2, 3),
var_2 = c("i", "j", "k")
)
# Add analyses from data frame
p$add_analysis_from_df(
fn_name = "plnr::example_action_fn",
df = batch_argset_df
)
# View argsets and run example
p$get_argsets_as_dt()
p$run_one(1)
## ------------------------------------------------
## Method `Plan$add_analysis_from_list`
## ------------------------------------------------
p <- plnr::Plan$new()
# Add example data
p$add_data("covid_data", fn_name = "plnr::example_data_fn_nor_covid19_cases_by_time_location")
# Create list of analyses
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
# Add analyses from list
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
# View argsets and run example
p$get_argsets_as_dt()
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")
p$get_data()
## ------------------------------------------------
## 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")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
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")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
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")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
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")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
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")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
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")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
data <- p$get_data()
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")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
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")
batch_argset_list <- list(
list(name = "analysis_1", var_1 = 1, var_2 = "i"),
list(name = "analysis_2", var_1 = 2, var_2 = "j"),
list(name = "analysis_3", var_1 = 3, var_2 = "k")
)
p$add_analysis_from_list(
fn_name = "plnr::example_action_fn",
l = batch_argset_list
)
p$run_all_progress()
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.