Multiverse in RMarkdown
Although the inside function is the only way to add code to the multiverse in an RScript, RMarkdown notebooks allow us the opportunity to use different language engines (not just limited to R). This flexibility also provides an opportunity to write multiverse code directly into a code block, instead of using auxillary functions.
The language associated with a code block is provided by the first
argument: ```{r} Here the first argument is r
hence the code in the associated block will be executed in R. To convert
a code block to execute in multiverse, change the first argument to
multiverse. Thus the code block would be:
```{multiverse}
To execute a code block in multiverse, the user needs to provide two
additional arguments: label and inside.
The label is a unique identifier for the code block, and each code
block in the same document must have a different label. However, the
label argument does not need to be explicitly specified (as is the case
with an R code block). Therefore,
```{multiverse, label=default-m-1 ...},
```{multiverse, default-m-1 ...} and
```{multiverse default-m-1 ...} are all equivalent.
The inside argument takes in only multiverse objects, and is used to
indicate the multiverse object which will the code inside the code block
will be associated with. Thus declaring a multiverse code block would
be: ```{multiverse, default-m-1, inside = M}
We provide the ability to declare multiverse code block as an AddIn in RStudio. Users can click on AddIns toolbar menu in RStudio (see the image below). This would create a multiverse code block at the location of the cursor in the document.
Alternately, users can insert a multiverse We also allow users to create a keyboard shortcut to declare a multiverse code block inside a RMarkdown document. This can be done through the following steps:
- Tools > AddIns > Browse AddIns… > Keyboard Shortcuts
- Next, in the filter input field, type multiverse. You will see one result with “Insert multiverse code chunk” as the name.
- Click on the Shortcut field and press Cmd+Option+M (on Mac OS) or Ctrl+Shift+Alt+M (on Windows).
- Click “Apply” and exit the dialog box
If you are experiencing issues creating a keyboard shortcut for code
blocks, or if you are experiencing a situation where the shortcut needs
to be re-created everytime you open a new RStudio session, please refer
to the Debugging Keyboard Shortcuts section at the end of
this document.
Multiverse code block
The declaration of the chunk below is (this gets hidden when we knit
the document):
```{multiverse default-m-1, inside = M_block}
```{multiverse default-m-1, inside = M_block}
data_transform <- branch(data_transform,
"log-transformed" ~ log,
"untransformed" ~ identity
)
duration <- do.call(data_transform, list(userlogs$duration))
```The result of this code block will be identical to the result using
inside(). We first compare whether the multiverse table is
generated properly for both the multiverse objects.
expand(M_inside)## # A tibble: 2 × 6
## .universe data_transform .parameter_assignment .code .results .errors
## <int> <chr> <list> <list> <list> <list>
## 1 1 log-transformed <named list [1]> <named list> <env> <lgl>
## 2 2 untransformed <named list [1]> <named list> <env> <lgl>expand(M_block)## # A tibble: 2 × 6
## .universe data_transform .parameter_assignment .code .results .errors
## <int> <chr> <list> <list> <list> <list>
## 1 1 log-transformed <named list [1]> <named list> <env> <lgl>
## 2 2 untransformed <named list [1]> <named list> <env> <lgl>As you can see above, both the methods yield the same multiverse
table. Next, we inspect the .code column of the multiverse
object. This column contains the code used to generate each analysis
combination in the multiverse. The only differences here arise from how
the expressions are stored. The multiverse code block creates a named
list, whereas the inside function creates a unnamed list for each row of
this column.
Below is the output from the first multiverse object
(M_inside), which uses the inside function:
## [[1]]
## [[1]]$`1`
## {
## data_transform <- log
## duration <- do.call(data_transform, list(userlogs$duration))
## }
##
##
## [[2]]
## [[2]]$`1`
## {
## data_transform <- identity
## duration <- do.call(data_transform, list(userlogs$duration))
## }This is the output from the second multiverse object
(M_block), which uses the multiverse code block:
## [[1]]
## [[1]]$`default-m-1`
## {
## data_transform <- log
## duration <- do.call(data_transform, list(userlogs$duration))
## }
##
##
## [[2]]
## [[2]]$`default-m-1`
## {
## data_transform <- identity
## duration <- do.call(data_transform, list(userlogs$duration))
## }