Declaring conditions in the multiverse

The %when% operator

There are two ways in which you can specify the %when% operator. The first is to specify it at the end of the branch. This will work even if you omit the branch option name.

df <- df |>
    mutate(NextMenstrualOnset = branch(menstrual_calculation,
        "mc_option1" ~ (StartDateofLastPeriod + ComputedCycleLength) %when% (cycle_length != "cl_option3"),
        "mc_option2" ~ (StartDateofLastPeriod + ReportedCycleLength) %when% (cycle_length != "cl_option2"),
        "mc_option3" ~ StartDateNext)
    )

The other is to specify it at the head of the branch, right after the option name:

df |>
    mutate(NextMenstrualOnset = branch(menstrual_calculation,
        "mc_option1" %when% (cycle_length != "cl_option3") ~ StartDateofLastPeriod + ComputedCycleLength,
        "mc_option2" %when% (cycle_length != "cl_option2") ~ (StartDateofLastPeriod + ReportedCycleLength),
        "mc_option3" ~ StartDateNext)
    )

Note: In this example we will be using the inside syntax to enter code into the multiverse, instead of multiverse code blocks to highlight the syntax of the conditional declaration as multiverse code blocks shows the code for a universe, and hides the actual code declared by the user.

We can write the complete analysis by specifying the condition with the %when% operator as:

M = multiverse()

inside(M, {
  df.1 <- df_durante  |>
      mutate( ComputedCycleLength = StartDateofLastPeriod - StartDateofPeriodBeforeLast )  |>
      dplyr::filter( branch(cycle_length,
          "cl_option1" ~ TRUE,
          "cl_option2" ~ ComputedCycleLength > 25 & ComputedCycleLength < 35,
          "cl_option3" ~ ReportedCycleLength > 25 & ReportedCycleLength < 35
      )) |>
      mutate(NextMenstrualOnset = branch(menstrual_calculation,
          "mc_option1" %when% (cycle_length != "cl_option3") ~ StartDateofLastPeriod + ComputedCycleLength,
          "mc_option2" %when% (cycle_length != "cl_option2") ~ StartDateofLastPeriod + ReportedCycleLength,
          "mc_option3" ~ StartDateNext)
      )
})

In multiverse code chunks conditionals can be declared in pretty much the same way:

```{multiverse default-m-1, inside = M}
df <- df_durante  |>
      mutate( ComputedCycleLength = StartDateofLastPeriod - StartDateofPeriodBeforeLast )  |>
      dplyr::filter( branch(cycle_length,
          "cl_option1" ~ TRUE,
          "cl_option2" ~ ComputedCycleLength > 25 & ComputedCycleLength < 35,
          "cl_option3" ~ ReportedCycleLength > 25 & ReportedCycleLength < 35
      )) |>
      mutate(NextMenstrualOnset = branch(menstrual_calculation,
          "mc_option1" %when% (cycle_length != "cl_option3") ~ StartDateofLastPeriod + ComputedCycleLength,
          "mc_option2" %when% (cycle_length != "cl_option2") ~ StartDateofLastPeriod + ReportedCycleLength,
          "mc_option3" ~ StartDateNext)
      )
```

Note: in this vignette we used the script-oriented inside() function for implementing the multiverse. However, we can implement the exact same multiverse in RMarkdown using the multiverse-code-block for more interactive programming. To implement this using a multiverse-code-block, we can simply place the code passed into the inside function (the second argument) inside a code block of type multiverse, provide it with the appropriate labels and multiverse object, and execute it. See (multiverse-in-rmd) and (branch) for more details and examples.

As the condition implies, the parameter menstrual_calcaultion (which is for calculating the variable NextMenstrualCalculation) cannot take the value of “mc_option1” when we filter cycle_length using “cl_option3”. Similarly, menstrual_calcaultion cannot take the value of “mc_option2” when we filter cycle_length using “cl_option2”. In the multiverse table below, you can see that those two parameter combinations are absent (universes indexed 3 and 5.

expand(M)

## # A tibble: 7 × 7
##   .universe cycle_length menstrual_calculation .parameter_assignment
##       <int> <chr>        <chr>                 <list>               
## 1         1 cl_option1   mc_option1            <named list [2]>     
## 2         2 cl_option1   mc_option2            <named list [2]>     
## 3         3 cl_option1   mc_option3            <named list [2]>     
## 4         4 cl_option2   mc_option1            <named list [2]>     
## 5         5 cl_option2   mc_option3            <named list [2]>     
## 6         6 cl_option3   mc_option2            <named list [2]>     
## 7         7 cl_option3   mc_option3            <named list [2]>     
## # ℹ 3 more variables: .code <list>, .results <list>, .errors <list>

The branch_assert() function

The same can be performed with the branch_assert() function. The benefit of using this is that within the branch assert function, the user can specify any logical operation.

For eg: the above logical operations can be specified as: branch_assert((menstrual_calculation != "mc_option1" | cycle_length != "cl_option3"))

Both these operations have the same result, but the first may not be as easily interpretable. We specify the conditionals using the branch_assert() function in our example as:

df |>
    branch_assert( (menstrual_calculation != "mc_option1" | (cycle_length != "cl_option3")) ) |>
    branch_assert( (menstrual_calculation != "mc_option2" | (cycle_length != "cl_option2")) )

Using the branch_assert(), we can perform the exact same analysis:

M = multiverse()

inside(M, {
    df.2 <- df_durante  |>
        mutate( ComputedCycleLength = StartDateofLastPeriod - StartDateofPeriodBeforeLast )  |>
        filter( branch(cycle_length,
            "cl_option1" ~ TRUE,
            "cl_option2" ~ ComputedCycleLength > 25 & ComputedCycleLength < 35,
            "cl_option3" ~ ReportedCycleLength > 25 & ReportedCycleLength < 35
        )) |>
        mutate(NextMenstrualOnset = branch(menstrual_calculation,
            "mc_option1" ~ StartDateofLastPeriod + ComputedCycleLength,
            "mc_option2" ~ StartDateofLastPeriod + ReportedCycleLength,
            "mc_option3" ~ StartDateNext)
        ) |>
        branch_assert( (menstrual_calculation != "mc_option1" | (cycle_length != "cl_option3")) ) |>
        branch_assert( (menstrual_calculation != "mc_option2" | (cycle_length != "cl_option2")) )
})

## Warning in FUN(X[[i]], ...): error in universe 1

## 
##  Error in FUN(X[[i]], ...) : object 'df.2' not found
##  tools::buildVignettes -> engine$weave -> vweave_rmarkdown -> rmarkdown::render -> knitr::knit -> process_file -> xfun:::handle_error -> withCallingHandlers -> process_group -> call_block -> block_exec -> eng_r -> in_input_dir -> in_dir -> evaluate -> evaluate::evaluate -> withRestarts -> withRestartList -> withOneRestart -> withRestartList -> withOneRestart -> withRestartList -> withOneRestart -> with_handlers -> eval -> eval -> withCallingHandlers -> withVisible -> eval -> eval -> inside -> execute_universe -> lapply -> FUN -> tryStack -> lapply -> FUN -> FUN -> FUN(X[[i]], ...)

As we can see, this results in the same multiverse, where universes indexed 3 and 5 are not compatible.

expand(M)

## # A tibble: 7 × 7
##   .universe cycle_length menstrual_calculation .parameter_assignment
##       <int> <chr>        <chr>                 <list>               
## 1         1 cl_option1   mc_option1            <named list [2]>     
## 2         2 cl_option1   mc_option2            <named list [2]>     
## 3         3 cl_option1   mc_option3            <named list [2]>     
## 4         4 cl_option2   mc_option1            <named list [2]>     
## 5         5 cl_option2   mc_option3            <named list [2]>     
## 6         6 cl_option3   mc_option2            <named list [2]>     
## 7         7 cl_option3   mc_option3            <named list [2]>     
## # ℹ 3 more variables: .code <list>, .results <list>, .errors <list>