Plan {plnr}R Documentation

R6 Class representing a Plan

Description

We work within the mental model where we have one (or more) datasets and we want to run multiple analyses on these datasets.

By demanding that all analyses use the same data sources we can:

By demanding that all analysis functions only use two arguments (data and argset) we can:

By including all of this in one Plan class, we can easily maintain a good overview of all the analyses (i.e. outputs) that need to be run.

Details

An argset is:

An analysis is:

A plan is:

Public fields

analyses

List of analyses.

Methods

Public methods


Method new()

Create a new Plan instance.

Usage
Plan$new(verbose = interactive() | config$force_verbose, use_foreach = FALSE)
Arguments
verbose

Should this plan be verbose?

use_foreach

???


Method add_data()

Add a new data set.

Usage
Plan$add_data(name, fn = NULL, fn_name = NULL, direct = NULL)
Arguments
name

Name of the data set.

fn

A function that returns the data set.

fn_name

A character string containing the name of a function that returns the data set.

direct

A direct data set.

Examples
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)
p$get_data()

Method add_argset()

Add a new argset.

Usage
Plan$add_argset(name = uuid::UUIDgenerate(), ...)
Arguments
name

Name of the (eventual) analysis that this argset will be connected to.

...

Named arguments that will comprise the argset.

Examples
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 add_argset_from_df()

Add a batch of argsets from a data.frame.

Usage
Plan$add_argset_from_df(df)
Arguments
df

A data.frame where each row is a new argset, and each column will be a named element in the argset.

Examples
p <- plnr::Plan$new()
batch_argset_df <- data.frame(name = c("a", "b", "c"), var_1 = c(1, 2, 3), var_2 = c("i", "j", "k"))
p$add_argset_from_df(batch_argset_df)
p$get_argsets_as_dt()

Method add_argset_from_list()

Add a batch of argsets from a list.

Usage
Plan$add_argset_from_list(l)
Arguments
l

A list of lists with named elements where each outermost element is a new argset, and each internal named element named element in the argset.

Examples
p <- plnr::Plan$new()
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")
)
p$add_argset_from_list(batch_argset_list)
p$get_argsets_as_dt()

Method add_analysis()

Add a new analysis.

Usage
Plan$add_analysis(name = uuid::UUIDgenerate(), fn = NULL, fn_name = NULL, ...)
Arguments
name

Name of the analysis.

fn

Action function.

fn_name

Action function name.

...

Named arguments to be added to the argset.

Examples
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$get_argsets_as_dt()
p$run_one("analysis_1")

Method add_analysis_from_df()

Add a batch of analyses from a data.frame.

Usage
Plan$add_analysis_from_df(fn = NULL, fn_name = NULL, df)
Arguments
fn

Action function.

fn_name

Action function name.

df

A data.frame where each row is a new argset, and each column will be a named element in the 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_df <- data.frame(name = c("a", "b", "c"), var_1 = c(1, 2, 3), var_2 = c("i", "j", "k"))
p$add_analysis_from_df(
  fn_name = "plnr::example_action_fn",
  df = batch_argset_df
 )
p$get_argsets_as_dt()
p$run_one(1)

Method add_analysis_from_list()

Add a batch of argsets from a list.

Usage
Plan$add_analysis_from_list(fn = NULL, fn_name = NULL, l)
Arguments
fn

Action function.

fn_name

Action function name.

l

A list of lists with named elements where each outermost element is a new argset, and each internal named element named element in the 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_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
fn

Action function.

fn_name

Action 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
fn

Action function.

fn_name

Action 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
pb

Progress bar.


Method set_progressor()

Set an internal progressor progress bar

Usage
Plan$set_progressor(pb)
Arguments
pb

progressor progress bar.


Method set_verbose()

Set verbose flag

Usage
Plan$set_verbose(x)
Arguments
x

Boolean.


Method set_use_foreach()

Set use_foreach flag

Usage
Plan$set_use_foreach(x)
Arguments
x

Boolean.


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:

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_analysis

Either 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_analysis

Either 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_analysis

Either an integer (1:length(analyses)) or a character string representing the name of the analysis.

data

Named 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_analysis

Either 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
data

Named 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 clone()

The objects of this class are cloneable with this method.

Usage
Plan$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

Examples


## ------------------------------------------------
## 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)
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()
batch_argset_df <- data.frame(name = c("a", "b", "c"), var_1 = c(1, 2, 3), var_2 = c("i", "j", "k"))
p$add_argset_from_df(batch_argset_df)
p$get_argsets_as_dt()

## ------------------------------------------------
## Method `Plan$add_argset_from_list`
## ------------------------------------------------

p <- plnr::Plan$new()
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")
)
p$add_argset_from_list(batch_argset_list)
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$get_argsets_as_dt()
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")
batch_argset_df <- data.frame(name = c("a", "b", "c"), var_1 = c(1, 2, 3), var_2 = c("i", "j", "k"))
p$add_analysis_from_df(
  fn_name = "plnr::example_action_fn",
  df = batch_argset_df
 )
p$get_argsets_as_dt()
p$run_one(1)

## ------------------------------------------------
## 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")
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()
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()

[Package plnr version 2022.11.23 Index]