The branch() function allows the user to define multiple analysis options for a particular step in the analysis.

## Arguments

parameter A string to identify the branch. Each branch is characterised using a parameter which takes different options. Different options for completing a particular step in the analysis. Each option is declared as ~ . See examples for more details. Declare a continuous value as the option of a parameter using a sequence (see examples for details), and the expanded sequence will be included as options for that parameter in the multiverse.

## Details

For every step in the analysis, there may be more than one analysis option. We use branch() to declare these different analysis options. Each branch is characterised by a parameter. The first argument passed into the branch is the parameter.

All the other arguments passed into branch are the different analysis options corresponding to that parameter (that particular step in the analysis process). Naturally, at least two or more options should be declared. Thus, the branch function will provide a warning if the total number arguments passed is less than three.

The branch() function does not support nested branches. Thus, we cannot declare a branch within a branch.

## Examples

# \donttest{
library(dplyr)
#>
#> Attaching package: ‘dplyr’#> The following objects are masked from ‘package:stats’:
#>
#>     filter, lag#> The following objects are masked from ‘package:base’:
#>
#>     intersect, setdiff, setequal, union
# declaring multiple options for a data processing step (calculating a new variable)
data(durante)
data.durante <- durante

data.durante  %>%
mutate( ComputedCycleLength = StartDateofLastPeriod - StartDateofPeriodBeforeLast ) %>%
mutate( NextMenstrualOnset = StartDateNext)
#> # A tibble: 502 x 26
#>    WorkerID  Rel1  Rel2  Rel3 Abortion Marriage StemCell RestrictAbortion
#>       <dbl> <dbl> <dbl> <dbl>    <dbl>    <dbl>    <dbl>            <dbl>
#>  1        1     8     8     7        2        7        7                7
#>  2        2     8     7     7        7        2        5                1
#>  3        3     6     6     2        3        1        6                4
#>  4        4     7     8     6        7        5        6                2
#>  5        5     7     7     9        7        1        4                1
#>  6        6     9     9     9        1        7        6                7
#>  7        7     5     8     5        5        4        5                5
#>  8        8     1     1     1        7        1        6                1
#>  9        9     7     7     7        3        1        6                1
#> 10       10     6     6     6        5        5        5                1
#> # … with 492 more rows, and 18 more variables: Marijuana <dbl>,
#> #   FreeMarket <dbl>, RichTax <dbl>, StLiving <dbl>, Profit <dbl>,
#> #   PrivSocialSec <dbl>, Sure1 <dbl>, Sure2 <dbl>, Relationship <dbl>,
#> #   ReportedCycleLength <dbl>, Vote <dbl>, Donate <dbl>, DateTesting <date>,
#> #   StartDateofLastPeriod <date>, StartDateofPeriodBeforeLast <date>,
#> #   StartDateNext <date>, ComputedCycleLength <drtn>, NextMenstrualOnset <date>

# create a multiverse object
M <- multiverse()

# if the variable NextMenstrualOnset can be calculated in more than one way
# we can use branch to declare all the different analysis options. This will
# replace the current analysis within the current syntax.
# Since this is a multiverse analysis, this is only supported within a multiverse object. Hence:
inside(M, {
df <- data.durante  %>%
mutate( ComputedCycleLength = StartDateofLastPeriod - StartDateofPeriodBeforeLast ) %>%
mutate( NextMenstrualOnset = branch(menstrual_calculation,
"mc_option1" ~ StartDateofLastPeriod + ComputedCycleLength,
"mc_option2" ~ StartDateofLastPeriod + ReportedCycleLength,
"mc_option3" ~ StartDateNext)
)
})

# continuous option values for a parameter
inside(M, {
branch(foo, "option1" ~ 1, .options = 1:10)
})

M2 = multiverse()
# alternatively, we could specify how we want the vector to be expanded
# for continuous parameters
inside(M2, {
branch(foo, "option1" ~ 1, .options = seq(0, 1, by = 0.1))
})
# }