You can install the package from CRAN:
install.packages("edibble")
You can install the development version with:
# install.packages("remotes")
::install_github("emitanaka/edibble") remotes
The goal of edibble
R-package is to aid in the plan,
design and simulation of experiments by mapping fundamental components
of experiments to an object oriented system. The edibble
system is built on the principle that the system must make it easy to
recover experimental context by encouraging the user to be explicit
about experimental details in fundamental terms.
Consider an experiment where you want to know what is an effective way of teaching (flipped or traditional style) for teaching a particular subject and how different forms of exams (take-home, open-book or closed-book) affect student’s marks.
There are four classes for this subject with each class holding 30 students. The teaching style can only be applied to the whole class but exam can be different for individual students.
library(edibble)
set.seed(2020)
<- design(name = "Effective teaching") %>%
des set_units(class = 4,
student = nested_in(class, 30)) %>%
set_trts(style = c("flipped", "traditional"),
exam = c("take-home", "open-book", "closed-book")) %>%
allot_trts(style ~ class,
~ student) %>%
exam assign_trts("random")
serve_table(des)
#> # Effective teaching
#> # An edibble: 120 x 4
#> class student style exam
#> <unit(4)> <unit(120)> <trt(2)> <trt(3)>
#> 1 class1 student1 traditional closed-book
#> 2 class1 student2 traditional open-book
#> 3 class1 student3 traditional take-home
#> 4 class1 student4 traditional closed-book
#> 5 class1 student5 traditional take-home
#> 6 class1 student6 traditional take-home
#> 7 class1 student7 traditional open-book
#> 8 class1 student8 traditional open-book
#> 9 class1 student9 traditional closed-book
#> 10 class1 student10 traditional closed-book
#> # … with 110 more rows
Before constructing the experiment, you might want to think about what you are recording for which level of unit and what values these variables can be recorded as.
<- des %>%
out set_rcrds_of(student = c("exam_mark",
"quiz1_mark",
"quiz2_mark",
"gender"),
class = c("room",
"teacher")) %>%
expect_rcrds(exam_mark <= 100,
>= 0,
exam_mark <= 15L,
quiz1_mark >= 0L,
quiz1_mark <= 30L,
quiz2_mark >= 0L,
quiz2_mark factor(gender, levels = c("female", "male", "non-binary", "unknown"))) %>%
serve_table()
out#> # Effective teaching
#> # An edibble: 120 x 10
#> class student style exam exam_mark quiz1_mark quiz2_mark
#> <unit(4)> <unit(120)> <trt(2)> <trt(3)> <rcrd> <rcrd> <rcrd>
#> 1 class1 student1 traditional closed-book o o o
#> 2 class1 student2 traditional open-book o o o
#> 3 class1 student3 traditional take-home o o o
#> 4 class1 student4 traditional closed-book o o o
#> 5 class1 student5 traditional take-home o o o
#> 6 class1 student6 traditional take-home o o o
#> 7 class1 student7 traditional open-book o o o
#> 8 class1 student8 traditional open-book o o o
#> 9 class1 student9 traditional closed-book o o o
#> 10 class1 student10 traditional closed-book o o o
#> # … with 110 more rows, and 3 more variables: gender <rcrd>, room <rcrd>,
#> # teacher <rcrd>
When you export the above edibble design using the
export_design
function, the variables you are recording are
constraint to the values you expect, e.g. for factors, the cells have a
drop-down menu to select from possible values.
export_design(out, file = "/PATH/TO/FILE.xlsx")
In addition, there is a spreadsheet for every observational level.
E.g. here room
and teacher
is the same for all
students in one class so rather than entering duplicate information,
these are exported to another sheet for data entry.
There is also support for more complex nesting structures. You can always make the structure using edibble and take the resulting data frame to use in other experimental design software. It’s also possible to bring existing data frame into edibble if you want to take advantage of the exporting feature in edibble.
design("nesting structure") %>%
# there are 3 sites labelled A, B, C
set_units(site = c("A", "B", "C"),
# each site has 2 blocks except B with 3 sites
block = nested_in(site,
"B" ~ 3,
~ 2),
. # levels can be specified by their number instead
# so for below "block1" has 30 plots,
# "block2" and "block3" has 40 plots,
# the rest of blocks have 20 plots.
plot = nested_in(block,
1 ~ 30,
c(2, 3) ~ 40,
~ 20)) %>%
. serve_table()
#> # nesting structure
#> # An edibble: 190 x 3
#> site block plot
#> <unit(3)> <unit(7)> <unit(190)>
#> 1 A block1 plot1
#> 2 A block1 plot2
#> 3 A block1 plot3
#> 4 A block1 plot4
#> 5 A block1 plot5
#> 6 A block1 plot6
#> 7 A block1 plot7
#> 8 A block1 plot8
#> 9 A block1 plot9
#> 10 A block1 plot10
#> # … with 180 more rows
tidyverse is well suited for the data science project workflow as
illustrated below in (B) (from Grolemund and Wickham
2017). For experimental data, the statistical aspect begins before
obtaining data as depicted below in (A). The focus of
edibble
is to facilitate work in (A).
The edibble R-package differ considerably to other packages for constructing experimental design with a focus on the whole process and less on the randomisation process (which the other software generally focus and do well on). Some features include:
Work-in-progress book on this package can be found here.
Currently, edibble:
The way that edibble specifies experimental design is largely novel (if I say so myself) and there are no work that resembles it. I’m concurrently working on two extension packages:
deggust
- to visualise the designs constructed from
edibble as ggplot2 objects (WIP).sizzled
- for experiments that require sample size
calculation (WIP).Below are some other related work. You can also have a look at the CRAN Task View for Design of Experiment and Analysis of Experimental Data for a whole collection.
DeclareDesign
for survey or sampling designsdesignr
for balanced factorial designs with crossed and
nested random and fixed effect to data framedae
for functions useful in the design and ANOVA of
experiments (this is in fact powering the randomisation in edibble)plotdesignr
for designing agronomic field
experimentsedibble is hugely inspired by the work of Tidyverse Team. I’m grateful for the dedication and work by the Tidyverse Team, as well as R Development Core Team that supports the core R ecosystem, that made developing this package possible.
The implementation in edibble adopt a similar nomenclature and design philosophy as tidyverse (and where it does not, it’s likely my shortcoming) so that tidyverse users can leverage their familiarity of the tidyverse language when using edibble. Specifically, edibble follows the philosophy:
<verb>_<noun>
(e.g. set_units
and
set_rcrds
) where the nouns are generally plural. Exceptions
are when the subject matter is clearly singular
(e.g. design
and set_context
);tibble
for
additions to edibble graph;prep_classical_
;dplyr::case_when
(LHS is character or integer for edibble
however).Please note that the edibble project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.