Package 'edibble'

Description

A system to facilitate designing comparative (and non-comparative) experiments using the grammar of experimental designs https://emitanaka.org/edibble-book/. An experimental design is treated as an intermediate, mutable object that is built progressively by fundamental experimental components like units, treatments, and their relation. The system aids in experimental planning, management and workflow.

Details

(WIP)

Website

• The website for the package is at https://edibble.emitanaka.org

• Discussion is at https://github.com/emitanaka/edibble/discussions

Package options

The following options are used for changing the default view for the print out of edibble design or edibble graph.

• edibble.tree.decorate.trts

• edibble.tree.decorate.units

• edibble.tree.decorate.rcrd

• edibble.tree.decorate.levels

• edibble.tree.decorate.main

TODO

Author(s)

Maintainer: Emi Tanaka [email protected] (ORCID) [copyright holder]

See Also

Useful links:

• https://edibble.emitanaka.org/

• https://github.com/emitanaka/edibble

• Report bugs at https://github.com/emitanaka/edibble/issues

Description

This is a developer function to create a new Kitchen class with the existing design.

Usage

activate_provenance(
  .edibble,
  overwrite = c("graph", "anatomy", "recipe", "validation", "simulate",
    "simulate_result")
)

Arguments

Value

A Provenance object.

Examples

activate_provenance(takeout())

Description

This function is a short hand that combines allot_trts(), assign_trts() and serve_table().

Usage

allot_table(
  .edibble = NULL,
  ...,
  order = "random",
  seed = NULL,
  constrain = nesting_structure(.edibble),
  label_nested = NULL,
  fail = "error",
  .record = TRUE
)

Arguments

Description

This function adds the edges between factor nodes to describe the high-level relationship between factors. This function does not actually assign edges between level nodes.

Usage

allot_trts(.edibble = NULL, ..., .record = TRUE)

Arguments

Value

Return an edibble design.

See Also

assign_fcts

Other user-facing functions: allot_units(), design(), expect_rcrds(), export_design(), serve_table(), set_rcrds(), set_trts(), set_units()

Examples

design() %>%
  set_units(block = 10,
            plot = nested_in(block, 3)) %>%
  set_trts(treat = c("A", "B", "C"),
           pest = c("a", "b")) %>%
  allot_trts(treat ~ plot,
              pest ~ block)

Description

This function adds the edges between factor nodes to describe the high-level relationship between factors. This function does not actually assign edges between level nodes.

Usage

allot_units(.edibble, ..., .record = TRUE)

Arguments

Value

Return an edibble design.

See Also

assign_fcts

Other user-facing functions: allot_trts(), design(), expect_rcrds(), export_design(), serve_table(), set_rcrds(), set_trts(), set_units()

Examples

design() %>%
  set_units(block = 10,
            plot = 20) %>%
  allot_units(block ~ plot)

Description

A patch function where there is an issue with edbl factors

Usage

## S3 method for class 'edbl_table'
as_tibble(x, ...)

Arguments

Value

A data.frame.

Description

Convert edibble table to normal data frame

Usage

## S3 method for class 'edbl_table'
as.data.frame(x, ..., levels_as = "factor", ignore_numeric = TRUE)

Arguments

Description

This function assigns specific treatment or unit levels to actual units.

Usage

assign_trts(
  .edibble = NULL,
  order = "random",
  seed = NULL,
  constrain = nesting_structure(.edibble),
  ...,
  .record = TRUE
)

assign_units(
  .edibble = NULL,
  order = "random",
  seed = NULL,
  constrain = nesting_structure(.edibble),
  ...,
  .record = TRUE
)

Arguments

Value

An edibble design.

Examples

# 10 subject, 2 vaccine treatments
design() %>%
  set_units(subject = 10) %>%
  set_trts(vaccine = 2) %>%
  allot_trts(vaccine ~ subject) %>%
  assign_trts() %>%
  serve_table()

# 20 subjects, 2 blocks, assign subjects to blocks
design() %>%
  set_units(subject = 20,
            block = 2) %>%
  allot_units(block ~ subject) %>%
  assign_units() %>%
  serve_table()

Description

This function fills the values of the record factors by automatically choosing a simulation process. It tries to be smart by ensuring to use values that is within expectation.

Usage

autofill_rcrds(.data, ..., .seed = NULL, .nsim = 1L)

Arguments

Examples

spd <- design("Split-Plot Design | Split-Unit Design") %>%
  set_units(mainplot = 30,
            subplot = nested_in(mainplot, 4)) %>%
  set_trts(trt1 = LETTERS[1:3],
           trt2 = 4) %>%
  allot_trts(trt1 ~ mainplot,
             trt2 ~ subplot) %>%
  assign_trts("random", seed = 719) %>%
  serve_table() %>%
  set_rcrds(mass = mainplot,
            yield = subplot,
            type = subplot) %>%
  expect_rcrds(mass > 0,
               yield > 0,
               yield < 100,
               factor(type, levels = c("a", "b", "c")))
spd %>%
  autofill_rcrds()

Description

This is a helper function to select a column when data is supplied for lvls.

Usage

column(x)

Arguments

Description

crossed_by(A, B) is the same as ~A:B but crossed_by offers more control over the names of the new units as well as adding new attributes.

Usage

crossed_by(..., attrs = NULL)

Arguments

Value

An object of class "cross_lvls".

Examples

design("Strip-Plot Design | Strip-Unit Design") %>%
  set_units(block = 3,
            row = nested_in(block, 7),
            col = nested_in(block, 6),
            unit = nested_in(block, crossed_by(row, col)))

Description

This function doesn't really do much besides create a new edibble design object.

Usage

design(
  .title = NULL,
  ...,
  .name = "edibble",
  .record = TRUE,
  .seed = NULL,
  .provenance = Provenance$new()
)

redesign(
  .data,
  .title,
  ...,
  .name = NULL,
  .record = TRUE,
  .seed = NULL,
  .provenance = Provenance$new()
)

Arguments

Value

An empty edbl_design object.

See Also

Add variables to this design with set_units(), set_trts(), and set_rcrds().

Other user-facing functions: allot_trts(), allot_units(), expect_rcrds(), export_design(), serve_table(), set_rcrds(), set_trts(), set_units()

Examples

design("My design")

Description

This is a convenient wrapper for dae::designAnatomy where the formulae structure is automatically determined by the unit and treatment structure specified in edibble system. Note: the computation may be long if the design is quite complicated or there are many units.

Usage

design_anatomy(.edibble, ...)

Arguments

Value

An object of class "des_anatomy".

Examples

split <- takeout(menu_split(t1 = 3, t2 = 2, r = 2))
design_anatomy(split)

Description

Get the node or edge data from an edibble design

Usage

fct_nodes(x)

fct_edges(x)

lvl_nodes(x)

lvl_edges(x)

Arguments

Description

This

Usage

design_model(data, type = c("anova", "lmer"))

Arguments

Description

The is functions tests if an object (or an object in its attribute) inherits particular class and returns TRUE if it does, otherwise FALSE.

• is_edibble_design checks if it inherits edbl_design.

• is_edibble_graph checks if it inherits edbl_graph.

• is_edibble_table checks if it inherits edbl_table

• is_edibble checks if the object inherits edbl. The search is quite simple, it checks if the object is edbl_design, failing that it looks to see if the attribute "design" of the object is edbl_design.

• is_named_design check if it inherits NamedDesign.

The get functions extracts the requested edibble component (table, graph, or design) from the object if possible.

• edbl_design tries to get edbl_design.

• edbl_table tries to get edbl_table with no design attribute.

• edbl_graph tries to get edbl_graph.

Usage

is_edibble_design(x)

is_named_design(x)

is_edibble_table(x)

is_edibble_graph(x)

is_edibble(x)

is_edibble_levels(x)

is_nest_levels(x)

is_cross_levels(x)

edbl_design(x)

edbl_table(x)

Arguments

Value

A logical value.

Examples

is_edibble_design(takeout())

Description

Examine the simulation process

Usage

examine_process(data, process = NULL)

examine_process_values(data, process = NULL, sim = 1L)

Arguments

Description

Check the recipe code

Usage

examine_recipe(x, ...)

Arguments

Value

The recipe code.

Examples

examine_recipe(takeout())

Description

Set the expected values for recording variables

Usage

expect_rcrds(.edibble = NULL, ..., .record = TRUE)

Arguments

Value

An edibble design.

See Also

Other user-facing functions: allot_trts(), allot_units(), design(), export_design(), serve_table(), set_rcrds(), set_trts(), set_units()

Examples

takeout(menu_crd(t = 4, n = 10)) %>%
  set_rcrds(y = unit) %>%
  expect_rcrds(y > 0)

Description

These functions should be used within expect_vars where variables that are to be recorded are constraint to the expected values when exported as an xlsx file by ⁠export_design().⁠ The functions to set a particular value type (numeric, integer, date, time and character) are preceded by "to_be_" where the corresponding restriction set by with_value().

Usage

to_be_numeric(range)

to_be_integer(range)

to_be_date(range)

to_be_time(range)

to_be_character(length)

to_be_factor(levels)

Arguments

Value

A record type.

Description

This function is designed to export the design made using edibble to an external xlsx file.

Usage

export_design(
  .data,
  file,
  author = NULL,
  date = Sys.Date(),
  overwrite = FALSE,
  hide_treatments = FALSE,
  theme = NULL,
  subject = NULL,
  category = NULL,
  table_style = "TableStyleMedium9"
)

Arguments

Value

The input data object.

See Also

Other user-facing functions: allot_trts(), allot_units(), design(), expect_rcrds(), serve_table(), set_rcrds(), set_trts(), set_units()

Description

This function is used to set characteristics of the factors.

Usage

fct(.levels = character(), ...)

fct_attrs(.levels = character(), ...)

Arguments

See Also

lvls

Examples

fct(c("A", "B"))

Description

Generate a factor with custom levels and repetitions.

Usage

fct_generator(labels, nlevels)

Arguments

Details

This function creates a factor with custom labels and specified repetitions for each label.

Value

A factor with custom levels and repetitions.

Examples

# Example usage of the function
fct_generator(labels = c("A", "B", "C"), nlevels = 3)

Description

Get the factor graph.

Usage

fct_graph(x)

Arguments

Description

This function prints an edbl_graph object as a tree to terminal. The variables are color coded (or decorated) with the given options. Any ANSI coloring or styling are only visible in the console or terminal outputs that support it. The print output is best used interactively since any text styling are lost in text or R Markdown output. More details can be found in vignette("edbl-output", package = "edibble").

Usage

## S3 method for class 'edbl_design'
print(
  x,
  decorate_units = edibble_decorate("units"),
  decorate_trts = edibble_decorate("trts"),
  decorate_rcrds = edibble_decorate("rcrds"),
  decorate_levels = edibble_decorate("levels"),
  decorate_title = edibble_decorate("title"),
  title = NULL,
  ...
)

Arguments

Description

A function to process input as input for graph manipulation

Usage

graph_input(input, prov, ...)

Arguments

Description

This function determines whether the given object is an instance of the "Provenance" class.

Usage

is_provenance(x)

Arguments

Value

TRUE if the object is an instance of the "Provenance" class, FALSE otherwise.

Description

The function returns TRUE if the input is a takeout design.

Usage

is_takeout(x)

Arguments

Value

A logical value.

Examples

is_takeout(takeout())

Description

Label with nested or distinct labels

Usage

label_nested(x)

label_distinct(x)

index_levels(x)

Arguments

Description

These can be handy for generating pseudo labels for the levels or factor names using fct_generator

Usage

label_seq_from_to(
  from = 1L,
  to = 1L,
  by = 1L,
  prefix = "",
  suffix = "",
  sep_prefix = "",
  sep_suffix = "",
  leading_zero = edibble_labels_opt("leading_zero")
)

label_seq_from_length(
  from = 1L,
  length = 1L,
  by = 1L,
  prefix = "",
  suffix = "",
  sep_prefix = "",
  sep_suffix = "",
  leading_zero = edibble_labels_opt("leading_zero")
)

label_seq_to_length(
  to = 1L,
  length = 1L,
  by = 1L,
  prefix = "",
  suffix = "",
  sep_prefix = "",
  sep_suffix = "",
  leading_zero = edibble_labels_opt("leading_zero")
)

label_seq_length(
  length = 1L,
  prefix = "",
  suffix = "",
  sep_prefix = "",
  sep_suffix = "",
  leading_zero = edibble_labels_opt("leading_zero")
)

Arguments

Value

A character vector containing the labels generated from the sequence.

Examples

label_seq_to_length(to = 10, length = 5, by = 2)
label_seq_from_to(from = 8, to = 10, leading_zero = 3)
label_seq_length(10, leading_zero = FALSE)

Description

Lady tasting tea experiment was described in Fisher (1935) to test the ability of a lady who said she tell whether the tea or milk was added first to a cup of tea.

The experiment consisted of preparing eight cups of tea, four with milk poured first and the other four with tea poured first. The lady has been told in advance that there are four of each kind of preparation.

This data consists of the same experimental structure and result but the order presented in practice is unknown.

cup

The cup number.

first

The cup of tea prepared with milk or tea first.

guess

The guess by lady which one was poured first.

correct

Whether the lady's guess was correct.

Usage

lady_tasting_tea

Format

An object of class tbl_df (inherits from tbl, data.frame) with 8 rows and 4 columns.

Source

Fisher, Ronald (1935) The Design of Experiments.

See Also

Other experimental data: skittles

Description

Latin square designs and its generalisations as an array

Usage

latin_square(n, randomise = TRUE)

latin_rectangle(nr, nc, nt, randomise = TRUE)

latin_array(dim, nt, randomise = TRUE)

Arguments

Functions

• latin_square(): Latin square design

• latin_rectangle(): Like a Latin square design but allow different number of rows and columns

• latin_array(): Returns an array where it stitches up multiple Latin square/rectangle design

Examples

latin_square(n = 3)
latin_rectangle(3, 3, 3)
latin_array(c(3, 3, 3), 3)

Description

Setting the traits of the levels

Usage

lvls(value = NULL, n = NA_integer_, data = NULL, ...)

Arguments

Value

An edbl_lvls object.

Examples

lvls(c("A", "B"))

Description

Some combinations of parameter values cannot create a balanced incomplete block design.

Usage

menu_bibd(
  t = random_integer_small(min = 3),
  k = random_integer_small(max = t - 1),
  r = random_integer_small(),
  seed = random_seed_number()
)

Arguments

Value

A recipe for balance incomplete block design.

See Also

Other recipe-designs: menu_crd(), menu_factorial(), menu_graeco(), menu_hyper_graeco(), menu_lsd(), menu_rcbd(), menu_split(), menu_strip(), menu_youden()

Examples

menu_bibd(t = 3, k = 2, r = 4)

Description

Completely randomised design

Usage

menu_crd(
  t = random_integer_small(),
  n = random_integer_medium(min = t),
  r = NULL,
  seed = random_seed_number()
)

Arguments

Value

A recipe for completely randomised design.

See Also

Other recipe-designs: menu_bibd(), menu_factorial(), menu_graeco(), menu_hyper_graeco(), menu_lsd(), menu_rcbd(), menu_split(), menu_strip(), menu_youden()

Examples

menu_crd(t = 3, n = 10)

Description

Prepare a factorial design

Usage

menu_factorial(
  trt = c(random_integer_small(), random_integer_small()),
  r = random_integer_small(),
  design = c("crd", "rcbd"),
  seed = random_seed_number()
)

Arguments

Value

A recipe for factorial design.

See Also

Other recipe-designs: menu_bibd(), menu_crd(), menu_graeco(), menu_hyper_graeco(), menu_lsd(), menu_rcbd(), menu_split(), menu_strip(), menu_youden()

Examples

menu_factorial(trt = c(3, 2), r = 2, design = "crd")

Description

Graeco-Latin Square Design

Usage

menu_graeco(t = random_integer_small(), seed = random_seed_number())

Arguments

Value

A recipe for Graeco-Latin square design.

See Also

Other recipe-designs: menu_bibd(), menu_crd(), menu_factorial(), menu_hyper_graeco(), menu_lsd(), menu_rcbd(), menu_split(), menu_strip(), menu_youden()

Examples

menu_graeco(t = 3)

Description

Hyper-Graeco-Latin Square Design

Usage

menu_hyper_graeco(t = random_integer_small(), seed = random_seed_number())

Arguments

Value

A recipe Hyper-Graeco-Latin square design.

See Also

Other recipe-designs: menu_bibd(), menu_crd(), menu_factorial(), menu_graeco(), menu_lsd(), menu_rcbd(), menu_split(), menu_strip(), menu_youden()

Examples

menu_hyper_graeco(t = 3)

Description

Prepare classical Latin square design

Usage

menu_lsd(t = random_integer_small(), seed = random_seed_number())

Arguments

Value

A recipe Latin square design.

See Also

Other recipe-designs: menu_bibd(), menu_crd(), menu_factorial(), menu_graeco(), menu_hyper_graeco(), menu_rcbd(), menu_split(), menu_strip(), menu_youden()

Examples

menu_lsd(t = 3)

Description

Prepare a randomised complete block design

Usage

menu_rcbd(
  t = random_integer_small(),
  r = random_integer_small(),
  seed = random_seed_number()
)

Arguments

Value

A recipe for randomised complete block design.

See Also

Other recipe-designs: menu_bibd(), menu_crd(), menu_factorial(), menu_graeco(), menu_hyper_graeco(), menu_lsd(), menu_split(), menu_strip(), menu_youden()

Examples

menu_rcbd(t = 3, r = 2)

Description

Originally referred to as split-plot design when it was first used.

Usage

menu_split(
  t1 = random_integer_small(),
  t2 = random_integer_small(),
  r = random_integer_small(),
  seed = random_seed_number()
)

Arguments

Value

A recipe split-plot design.

See Also

Other recipe-designs: menu_bibd(), menu_crd(), menu_factorial(), menu_graeco(), menu_hyper_graeco(), menu_lsd(), menu_rcbd(), menu_strip(), menu_youden()

Examples

menu_split(t1 = 3, t2 = 2, r = 4)

Description

Strip-unit design

Usage

menu_strip(
  t1 = random_integer_small(),
  t2 = random_integer_small(),
  r = random_integer_small(),
  seed = random_seed_number()
)

Arguments

Value

A recipe strip-unit design.

See Also

Other recipe-designs: menu_bibd(), menu_crd(), menu_factorial(), menu_graeco(), menu_hyper_graeco(), menu_lsd(), menu_rcbd(), menu_split(), menu_youden()

Examples

menu_strip(t1 = 3, t2 = 3, r = 2)

Description

Youden square design

Usage

menu_youden(
  nc = random_integer_small(),
  t = random_integer_small(min = nc + 1),
  seed = random_seed_number()
)

Arguments

Value

A recipe Youden square design.

See Also

Other recipe-designs: menu_bibd(), menu_crd(), menu_factorial(), menu_graeco(), menu_hyper_graeco(), menu_lsd(), menu_rcbd(), menu_split(), menu_strip()

Examples

menu_youden(nc = 4, t = 5)

Description

Conditional treatment is different to nested units as the levels are assumed to be distinct for the latter but not for the former.

Usage

nested_in(x, ...)

conditioned_on(x, ...)

Arguments

Details

Currently when specifying conditional treatment, only character vectors are accepted on the RHS.

Value

A nested level.

See Also

See set_units() for examples of how to use this.

Examples

design("Split-Plot Design | Split-Unit Design") %>%
  set_units(mainplot = 60,
            subplot = nested_in(mainplot, 10))

Description

Get the nesting structure for the units

Usage

nesting_structure(design)

Arguments

Value

Return a named list. Only shows the direct parent.

Examples

nesting_structure(takeout(menu_split()))

Description

This helps to construct a new edibble table which is a special type of tibble.

Usage

new_edibble(.data, ..., .design = NULL, .class = NULL)

as_edibble(.data, ...)

Arguments

Value

An edibble table.

Description

A custom ordering algorithm

Usage

order_trts(x, ...)

Arguments

Description

Interactive plot of the edibble design

Usage

## S3 method for class 'edbl_design'
plot(
  x,
  which = c("factors", "levels"),
  width = "100%",
  height = NULL,
  seed = 1,
  title = NULL,
  subtitle = NULL,
  footer = NULL,
  background = "transparent",
  view = c("show-buttons", "hide-buttons", "static"),
  ...
)

## S3 method for class 'edbl_table'
plot(x, ...)

plot_fct_graph(
  x,
  width = "100%",
  height = NULL,
  seed = 1,
  title = NULL,
  subtitle = NULL,
  footer = NULL,
  background = "transparent",
  view = c("show-buttons", "hide-buttons", "static"),
  ...
)

plot_lvl_graph(
  x,
  width = "100%",
  height = NULL,
  seed = 1,
  title = NULL,
  subtitle = NULL,
  footer = NULL,
  background = "transparent",
  view = c("show-buttons", "hide-buttons", "static"),
  ...
)

Arguments

Value

A plot.

Examples

plot(takeout(menu_crd(t = 4, n = 20)))

Description

An object to query, record and modify an edibble graph

An object to query, record and modify an edibble graph

Details

The Provenance contains a set of operations to manipulate the nodes and edges of the edibble graph object.

Active bindings

Methods

Public methods

• Provenance$new()

• Provenance$set_title()

• Provenance$set_name()

• Provenance$set_validation()

• Provenance$set_simulate()

• Provenance$reactivate()

• Provenance$deactivate()

• Provenance$fct_id()

• Provenance$fct_id_parent()

• Provenance$fct_id_child()

• Provenance$fct_id_ancestor()

• Provenance$fct_id_descendant()

• Provenance$fct_id_leaves()

• Provenance$lvl_id()

• Provenance$lvl_id_parent()

• Provenance$lvl_id_child()

• Provenance$lvl_id_ancestor()

• Provenance$fct_id_from_lvl_id()

• Provenance$fct_id_from_lvl_values()

• Provenance$lvl_id_from_fct_id()

• Provenance$fct_names()

• Provenance$unit_names()

• Provenance$trt_names()

• Provenance$rcrd_names()

• Provenance$rcrd_class()

• Provenance$lvl_values()

• Provenance$unit_values()

• Provenance$trt_values()

• Provenance$rcrd_values()

• Provenance$fct_role()

• Provenance$fct_levels()

• Provenance$fct_levels_id_to_edbl_fct()

• Provenance$fct_levels_id_to_value()

• Provenance$fct_levels_value_to_id()

• Provenance$fct_exists()

• Provenance$trt_exists()

• Provenance$unit_exists()

• Provenance$rcrd_exists()

• Provenance$append_fct_nodes()

• Provenance$append_lvl_nodes()

• Provenance$append_fct_edges()

• Provenance$append_lvl_edges()

• Provenance$serve_units()

• Provenance$serve_trts()

• Provenance$serve_rcrds()

• Provenance$make_trts_table()

• Provenance$graph_subset()

• Provenance$save_seed()

• Provenance$get_title()

• Provenance$get_validation()

• Provenance$get_trail()

• Provenance$get_graph()

• Provenance$get_seed()

• Provenance$get_session_info()

• Provenance$get_edibble_version()

• Provenance$get_simulate()

• Provenance$get_simulate_result_env()

• Provenance$mapping()

• Provenance$mapping_to_unit()

• Provenance$record_step()

• Provenance$lvl_mapping()

• Provenance$record_track_external()

• Provenance$fct_id_links()

• Provenance$fct_graph_components()

• Provenance$lvl_graph_components()

• Provenance$clone()

Method new()

Initialise function

Usage

Provenance$new(graph = NULL)

Arguments

Method set_title()

Set the title.

Usage

Provenance$set_title(title)

Arguments

Method set_name()

Set the name.

Usage

Provenance$set_name(name)

Arguments

Method set_validation()

Set the validation.

Usage

Provenance$set_validation(validation, type = "rcrds")

Arguments

Method set_simulate()

Set the simulation process

Usage

Provenance$set_simulate(name, process, rcrds)

Arguments

Method reactivate()

Reactivate the graph in the provenance object.

Usage

Provenance$reactivate(
  design,
  overwrite = c("graph", "anatomy", "recipe", "validation", "simulate",
    "simualte_result")
)

Arguments

Method deactivate()

Deactivate the provenance object.

Usage

Provenance$deactivate(delete = c("graph", "anatomy", "recipe", "validation"))

Arguments

Method fct_id()

Get the id based on either the name of the factor node. If none supplied then it will give all.

Usage

Provenance$fct_id(name = NULL, role = NULL)

Arguments

Method fct_id_parent()

Get the factor parent ids

Usage

Provenance$fct_id_parent(id = NULL, role = NULL, type = NULL)

Arguments

Method fct_id_child()

Get the factor child ids. If role is supplied then the child has to fit role

Usage

Provenance$fct_id_child(id = NULL, role = NULL)

Arguments

Method fct_id_ancestor()

Get the factor ancestor ids

Usage

Provenance$fct_id_ancestor(id = NULL, role = NULL)

Arguments

Method fct_id_descendant()

Get the factor descendant ids

Usage

Provenance$fct_id_descendant(id = NULL, role = NULL)

Arguments

Method fct_id_leaves()

Get the leave factor ids.

Usage

Provenance$fct_id_leaves(role = NULL)

Arguments

Method lvl_id()

Get the id based on name of level node. Assumes that level ids obtained are all from the same fid

Usage

Provenance$lvl_id(value = NULL, role = NULL, fid = NULL)

Arguments

Method lvl_id_parent()

Get the level parent ids

Usage

Provenance$lvl_id_parent(id = NULL, role = NULL)

Arguments

Method lvl_id_child()

Get the level child ids

Usage

Provenance$lvl_id_child(id = NULL, role = NULL)

Arguments

Method lvl_id_ancestor()

Get the level ancestor ids

Usage

Provenance$lvl_id_ancestor(id = NULL, role = NULL)

Arguments

Method fct_id_from_lvl_id()

Find the factor id from level ids.

Usage

Provenance$fct_id_from_lvl_id(id = NULL, fid_search = NULL)

Arguments

Method fct_id_from_lvl_values()

Find the factor id from level values.

Usage

Provenance$fct_id_from_lvl_values(value = NULL, fid_search = NULL)

Arguments

Method lvl_id_from_fct_id()

Find the level id from the given fid

Usage

Provenance$lvl_id_from_fct_id(fid = NULL)

Arguments

Method fct_names()

Get the factor names based on id or role

Usage

Provenance$fct_names(id = NULL, role = NULL)

Arguments

Method unit_names()

Get the unit names

Usage

Provenance$unit_names(id = NULL)

Arguments

Method trt_names()

Get the treatment names

Usage

Provenance$trt_names(id = NULL)

Arguments

Method rcrd_names()

Get the record names.

Usage

Provenance$rcrd_names(id = NULL)

Arguments

Method rcrd_class()

Get the class for record with validation.

Usage

Provenance$rcrd_class(name = NULL)

Arguments

Method lvl_values()

Get the level values based on id or role cannot have just role only defined. id must be from the same fid

Usage

Provenance$lvl_values(id = NULL, role = NULL, fid = NULL)

Arguments

Method unit_values()

Get the unit values.

Usage

Provenance$unit_values(id = NULL, fid = NULL)

Arguments

Method trt_values()

Get the treatment values.

Usage

Provenance$trt_values(id = NULL, fid = NULL)

Arguments

Method rcrd_values()

Get the record values.

Usage

Provenance$rcrd_values(uid = NULL, fid = NULL)

Arguments

Method fct_role()

Get the role of the vertex given the factor id

Usage

Provenance$fct_role(id = NULL)

Arguments

Method fct_levels()

Get the levels for each factor

Usage

Provenance$fct_levels(id = NULL, name = NULL, return = c("id", "value"))

Arguments

Method fct_levels_id_to_edbl_fct()

Factor levels to edble factor

Usage

Provenance$fct_levels_id_to_edbl_fct(fct_levels, role)

Arguments

Method fct_levels_id_to_value()

Get the factor levels in value given id format

Usage

Provenance$fct_levels_id_to_value(fct_levels)

Arguments

Method fct_levels_value_to_id()

Get the factor levels in id given value format.

Usage

Provenance$fct_levels_value_to_id(fct_levels)

Arguments

Method fct_exists()

One of name, id or role is defined to check if it exists. If more than one of the arguments name, id and role are supplied, then the intersection of it will be checked.

Usage

Provenance$fct_exists(id = NULL, name = NULL, role = NULL, abort = TRUE)

Arguments

Method trt_exists()

Check if treatment exists.

Usage

Provenance$trt_exists(id = NULL, name = NULL, abort = TRUE)

Arguments

Method unit_exists()

Check if unit exists.

Usage

Provenance$unit_exists(id = NULL, name = NULL, abort = TRUE)

Arguments

Method rcrd_exists()

Check if record exists.

Usage

Provenance$rcrd_exists(id = NULL, name = NULL, abort = TRUE)

Arguments

Method append_fct_nodes()

Given node data, append the factor nodes

Usage

Provenance$append_fct_nodes(name, role, attrs = NULL)

Arguments

Method append_lvl_nodes()

Given node data, append the level nodes

Usage

Provenance$append_lvl_nodes(
  value,
  n = NULL,
  label = NULL,
  attrs = NULL,
  fid = NULL
)

Arguments

Method append_fct_edges()

Given edge data, append the factor edges

Usage

Provenance$append_fct_edges(from, to, type = NULL, group = FALSE, attrs = NULL)

Arguments

Method append_lvl_edges()

Given edge data, append the level edges

Usage

Provenance$append_lvl_edges(from, to, attrs = NULL)

Arguments

Method serve_units()

Serve the units.

Usage

Provenance$serve_units(id = NULL, return = c("id", "value"))

Arguments

Method serve_trts()

Serve treatments

Usage

Provenance$serve_trts(id = NULL, return = c("id", "value"))

Arguments

Method serve_rcrds()

Serve records

Usage

Provenance$serve_rcrds(id = NULL, return = c("id", "value"))

Arguments

Method make_trts_table()

Make the treatments table

Usage

Provenance$make_trts_table(id = NULL, return = c("id", "value"))

Arguments

Returns

A treatment table

Method graph_subset()

Subset graph

Usage

Provenance$graph_subset(
  id = NULL,
  include = c("self", "child", "parent", "ancestors")
)

Arguments

Returns

subsetted graph

Method save_seed()

Save the seed

Usage

Provenance$save_seed(seed, type)

Arguments

Method get_title()

Get the title

Usage

Provenance$get_title()

Method get_validation()

Get the validation

Usage

Provenance$get_validation(type = NULL)

Arguments

Method get_trail()

Get the trail.

Usage

Provenance$get_trail()

Method get_graph()

Get the graph

Usage

Provenance$get_graph()

Method get_seed()

Get the seed

Usage

Provenance$get_seed()

Method get_session_info()

Get the session information

Usage

Provenance$get_session_info()

Method get_edibble_version()

Get the edibble version.

Usage

Provenance$get_edibble_version()

Method get_simulate()

Get the simulation information

Usage

Provenance$get_simulate(name = NULL)

Arguments

Method get_simulate_result_env()

Get the simulation results

Usage

Provenance$get_simulate_result_env(name = NULL)

Arguments

Method mapping()

Mapping of a role to role

Usage

Provenance$mapping(role_from, role_to)

Arguments

Method mapping_to_unit()

Mapping of an id to a unit

Usage

Provenance$mapping_to_unit(id = NULL)

Arguments

Method record_step()

Record step.

Usage

Provenance$record_step()

Method lvl_mapping()

Get the level edges by factor

Usage

Provenance$lvl_mapping(from, to, return = c("vector", "table"))

Arguments

Method record_track_external()

Record track external.

Usage

Provenance$record_track_external(code)

Arguments

Method fct_id_links()

Find all id that is linked.

Usage

Provenance$fct_id_links(id = NULL, role = NULL, link = c("direct", "indirect"))

Arguments

Returns

id of linked factors, excluding itself.

Method fct_graph_components()

Get the nodes with components (subgraph number)

Usage

Provenance$fct_graph_components(id = NULL)

Arguments

Method lvl_graph_components()

Get the nodes with components (subgraph number)

Usage

Provenance$lvl_graph_components()

Method clone()

The objects of this class are cloneable with this method.

Usage

Provenance$clone(deep = FALSE)

Arguments

Description

Similar to scales::rescale() but it has a different behaviour when only upper or lower bound is given.

Usage

rescale_values(x, lower = NA, upper = NA)

Arguments

Description

Find the short names of the named designs

Usage

scan_menu(packages = NULL, exclude = NULL)

Arguments

Value

A data.frame with package, name, arguments, and full name.

Examples

scan_menu()

Description

This converts an edibble graph object to a data frame called edibble. This function should be used when the design is in the final form (or close to the final form). The table can only be formed when the variables can be reconciled, otherwise it will be a data frame with zero rows.

Usage

serve_table(
  .edibble = NULL,
  label_nested = NULL,
  fail = c("error", "warn", "ignore"),
  .record = TRUE
)

Arguments

Value

An edbl data frame with columns defined by vertices and rows displayed only if the vertices are connected and reconcile for output.

See Also

Other user-facing functions: allot_trts(), allot_units(), design(), expect_rcrds(), export_design(), set_rcrds(), set_trts(), set_units()

Examples

design("Completely Randomised Design") %>%
  set_units(unit = 28) %>%
  set_trts(trt = 6) %>%
  allot_trts(trt ~ unit) %>%
  assign_trts("random", seed = 521) %>%
  serve_table()

Description

These are structured information that can be encoded in into the design object. By encoding this information, you can make it interoperable. If you use export_design(), the information is exported to the title sheet of the excel output.

Usage

set_attrs(.edibble = design(), ...)

Arguments

Examples

des <- set_attrs(design(aim = "Testing for new flu vaccine.",
                        contact = "emi.tanaka (at) anu.edu",
                       "Funded by Better Experiments Institute.") )

des$context

Description

This function creates new nodes to edibble graph with the name corresponding to either the intended response that will be measured or a variable to be recorded. Avoid record names staring with a "." as these are reserved for other purposes downstream.

Usage

set_rcrds(
  .edibble = NULL,
  ...,
  .name_repair = c("check_unique", "unique", "universal", "minimal"),
  .record = TRUE
)

set_rcrds_of(.edibble = NULL, ...)

Arguments

Value

An edibble design.

See Also

Other user-facing functions: allot_trts(), allot_units(), design(), expect_rcrds(), export_design(), serve_table(), set_trts(), set_units()

Examples

takeout(menu_crd(t = 4, n = 10)) %>%
  set_rcrds(y = unit)

takeout(menu_crd(t = 4, n = 10)) %>%
  set_rcrds_of(unit = "y")

Description

This function add a special class, called edbl_trt, of edibble variables.

Usage

set_trts(
  .edibble = design(),
  ...,
  .name_repair = c("check_unique", "unique", "universal", "minimal"),
  .record = TRUE
)

Arguments

Value

An edibble design.

Definition of treatment

The word treatment is sometimes used to refer to one of these variables. When there are more than one treatment variables then this unfortunately confuses whether treatment refers to the variable or the combination of all treatment variables.

Treatment is the whole description of what is applied in an experiment.

See Also

Other user-facing functions: allot_trts(), allot_units(), design(), expect_rcrds(), export_design(), serve_table(), set_rcrds(), set_units()

Examples

design() %>%
  set_trts(pesticide = c("A", "B", "C"),
           dosage = c(0, 10, 20, 30, 40))

Description

This function sets new edibble variables of class edbl_unit. More specifically, this means that new nodes are added to the edbl_graph.

Usage

set_units(
  .edibble = design(),
  ...,
  .name_repair = c("check_unique", "unique", "universal", "minimal"),
  .record = TRUE
)

Arguments

Value

An edibble design.

Definition of unit

A unit, much like factor, is an over-used word but due to lack of a better word, edibble uses the word "unit" to refer to any entity, physical or otherwise, that pertain to the experiment. This function doen't explicitly distinguish between experimental or observational units, nor is a unit limited to these type of units. A unit in edibble can be a blocking factor or even a discrete time unit.

Limitations

Currently a unit should only have a discrete set of levels and you need to know the number of levels prior to setting the units.

See Also

Other user-facing functions: allot_trts(), allot_units(), design(), expect_rcrds(), export_design(), serve_table(), set_rcrds(), set_trts()

Examples

# 30 rats
design() %>%
  set_units(rat = 30) %>%
  serve_table()

# 4 girls named "Anna", "Betty", "Carol", "Diana"
design() %>%
  set_units(girl = c("Anna", "Betty", "Carol", "Diana")) %>%
  serve_table()

# 3 companies, with 10 boxes each
design() %>%
  set_units(company = c("A", "B", "C"),
                box = nested_in(company, 10))

# 2 classes, one with 10 students, the other with 20 students
design() %>%
  set_units(class = 2,
            student = nested_in(class,
                                1 ~ 10,
                                2 ~ 20))

# 4 countries with 10 people from Australia & New Zealand and 20 from the rest
design() %>%
  set_units(country = c("AU", "NZ", "USA", "JPN"),
            person = nested_in(country,
                               c("AU", "NZ") ~ 10,
                                           . ~ 20)) %>%
  serve_table()

Description

This function to create and store functions to simulate the records.

Usage

simulate_process(.data, ...)

Arguments

Details

When creating a function, internally you can refer to any of the factors without referring to the actual data. The data referred to is expected to be from the full data. Like in tidyverse, syntax .data is reserved for the full data and .env can be used to refer to environment variables.

You can use the syntax n() to refer to nrow(.data) or n(fct) where fct corresponds to unquoted factor name. The return value will be the number of the observed number of levels of factor fct in the data. For n(fct1, fct2) it will return the observed number of distinct interaction levels for fct1 and fct2.

Note that you can actually put as many process as you like if you use a process name (starting with a dot), even if this is for the same record factor.

Description

Simulate records

Usage

simulate_rcrds(.data, ..., .seed = NULL, .nsim = 1L)

Arguments

Examples

design() %>%
 set_units(unit = 4) %>%
 set_trts(trt = 2) %>%
 allot_table(trt ~ unit) %>%
 set_rcrds(y = unit) %>%
 simulate_process(y = function() {
            res <- rnorm(n())
            res
 }) %>%
 simulate_rcrds(y = with_params(), .nsim = 3)

Description

This contains the data from the skittle experiment conducted by Nick Tierney. The goal of the experiment was to assess if people can discern the flavour of the skittle (indicated by color of the skittle) based on taste alone. The participants are blindfolded.

The experiment had 3 participants with each participant tasting 10 skittles, 2 of each 5 color, in a random order.

skittle_type

The type of skittle. Coincides with real_skittle.

person

The participant.

order

The order the skittle was tasted.

choice

The participant's choice.

real_skittle

The actual skittle color.

Usage

skittles

Format

An object of class spec_tbl_df (inherits from tbl_df, tbl, data.frame) with 30 rows and 6 columns.

Source

https://github.com/njtierney/skittles

See Also

Other experimental data: lady_tasting_tea

Description

This function has a similar result with split() where it returns a named list with names corresponding to the levels of the separating factor (or concatenated strings if multiple separating factors). The key differences to split(), are that the splitting factor does not appear in the elements of the list and only linked factors and their ancestors appear in the output, e.g. if treatment is applied to wholeplot and subplots are nested within subplots, then the subplot will not be shown in the output if split by treatment.

Usage

split_by(.data, ..., .sep = ":", .remove_empty = TRUE)

count_by(.data, ..., .remove_empty = TRUE)

Arguments

Value

A named list.

See Also

pivot_wider_by()

Examples

spd <- takeout(menu_split())
split(spd, spd$trt1)
spd %>% split_by(trt1)
spd %>% split_by(trt2)
spd %>% split_by(mainplot)
spd %>% count_by(trt1)

fac <- takeout(menu_factorial(trt = c(2, 2, 2)))
fac %>% count_by(where(~is_trt(.x)))

Description

This function generates a named experimental design by supplying the selected menu named design and prints out by default

You can find the available recipes with scan_menu().

Usage

takeout(recipe = NULL, show = TRUE)

Arguments

Value

A recipe design.

See Also

See scan_menu() for finding the short names of the named experimental designs.

Examples

takeout(menu_crd(n = 50, t = 5))
# if you omit the design parameters then it will use the default
# (which may be random)
takeout(menu_crd())
# if you don't give any short names then it will generate a random one
takeout()

Description

Treatments table

Usage

trts_table(.edibble)

Arguments

Description

The S3 methods for edbl_fct objects have the same expected output that of a factor.

Other functions are utility functions related to edbl_fct object.

Usage

## S3 method for class 'edbl_fct'
as.character(x, ...)

## S3 method for class 'edbl_fct'
as.integer(x, ...)

is_fct(x)

is_unit(x)

is_trt(x)

is_rcrd(x)

Arguments

Value

A character vector.

Description

This is a helper function to set the parameter values

Usage

with_params(..., .censor = NA, .aggregate = NULL)

Arguments

See Also

simulate_rcrds()

Description

This creates a list that is used later for creating data validation rules when the data is exported.

Usage

with_value(
  operator = c("=", "==", ">=", "<=", "<", ">", "!="),
  value = NULL,
  between = NULL,
  not_between = NULL
)

Arguments

Value

A list with two elements operator and value.

Description

The other options give are characteristics of the record (not the independent variables). Warning: none of the other options work at the moment!

Usage

with_variables(
  ...,
  .missing = FALSE,
  .interaction = random_true_false(),
  .discrete = FALSE,
  .linear = random_true_false(),
  .error_dist = NULL
)

Arguments

See Also

autofill_rcrds()