Using the multiverse in RMarkdown: Introduction to multiverse code chunks

Introduction

In this document we will describe the usage of the multiverse code block. The multiverse code block is an alternative to the R code block which will parse any code run in it directly in the multiverse, and reduces the need for auxiliary functions such as (inside). In addition, the default analysis in the multiverse will be executed in the environment in which the multiverse has been declared, which would usually be the global environment. In that case the results of the default analysis can be inspected directly in an R code block, similar to what an user would do if they were running a single universe analysis.

We demonstrate how the two methods are equivalent, and result in the same multiverse.

In this example, we will use the data which compares different modalities for physical visualizations. See (frequentist-multiverse-analysis) for more details.

data("userlogs")

As with any multiverse analysis, we first need to define the multiverse object. This step is the same for both methods. We will define two separate objects for illustrating the two different ways of adding code to the multiverse for analysis. In the multiverse analysis in this vignette, we will perform a log transformation on the duration variable of the dataset using both the inside function as well as the multiverse code block

M_inside = multiverse()
M_block = multiverse()

Inside() and Multiverse analysis in R scripts

The idea of the inside function is to allow us to write code to be executed within the multiverse and not directly in R, thus allowing us to make use of a flexible syntax for declaring the different possible analysis combinations within the multiverse. The inside function takes two arguments:

1. the name of the multiverse object
2. the expression (code) to be passed into the multiverse enclosed within a pair of curly braces, {

The expression passed into the multiverse is not executed directly, allowing us to parse and expand the expression provided by the user has declared using our branch and parameters, into their corresponding analysis combinations.

inside(M_inside, {
    data_transform <- branch(data_transform,
        "log-transformed" ~ log,
        "untransformed" ~ identity
      )
    
    duration <- do.call(data_transform, list(userlogs$duration))
})

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 default-m-1, inside = M_block}
data_transform <- branch(data_transform,
    "log-transformed" ~ log,
    "untransformed" ~ identity
  )

duration <- do.call(data_transform, list(userlogs$duration))
```

expand(M_inside)

expand(M_block)

Notes on using multiverse code blocks

Debugging Keyboard Shortcuts