# A Simplified Approach for Specifying Interventions in gfoRmula

Starting from version 1.1.0, the package supports a simplified approach to specify interventions. This document describes how to specify interventions using this approach. This document assumes that readers have read the long-form package documentation of McGrath et al. (2020).

Note that maintains backwards compatibility in the sense that users may continue to specify interventions using the previous approach (i.e., based on specifying the arguments , , and ).

## Specifying Interventions

To specify interventions, users can supply arguments with the following naming requirements:

- Each intervention argument begins with a prefix of
- After the prefix, the intervention number is specified and followed by a period
- After the period, the treatment variable name is specified

For example, an argument with the name specifies the first intervention, which intervenes on variable .

Each intervention argument takes as input a list with the following elements:

- The first element specifies the intervention function, such as , , or a custom intervention function.
- The subsequent elements specify any intervention “values”. For static interventions, this is a vector of length which specifies the values of the static treatment to be assigned. For threshold interventions, these are the lower and upper bounds for the threshold.
- Users can optionally supply a named element to specify the time points to apply the intervention. By default, all interventions are applied at all time points.

The example below specifies an “always treat” intervention on : The next example specifies a threshold intervention strategy on with a lower bound of 1: The next example specifies a joint intervention on and of always treat. Both and are intervened on at all time points except the last one.

The next sections illustrate complete examples.

## Example 1: Static interventions

In this example, we re-perform the analysis in Example 1 in McGrath et al. (2020) using the new intervention specification.

    id <- 'id'
    time_points <- 7
    time_name <- 't0'
    covnames <- c('L1', 'L2', 'A')
    outcome_name <- 'Y'
    outcome_type <- 'survival'
    covtypes <- c('binary', 'bounded normal', 'binary')
    histories <- c(lagged, lagavg)
    histvars <- list(c('A', 'L1', 'L2'), c('L1', 'L2'))
    covparams <- list(covmodels = c(L1 ~ lag1_A + lag_cumavg1_L1 + lag_cumavg1_L2 +
                                      L3 + t0,
                                    L2 ~ lag1_A + L1 + lag_cumavg1_L1 +
                                      lag_cumavg1_L2 + L3 + t0,
                                    A ~ lag1_A + L1 + L2 + lag_cumavg1_L1 +
                                      lag_cumavg1_L2 + L3 + t0))
    ymodel <- Y ~ A + L1 + L2 + L3 + lag1_A + lag1_L1 + lag1_L2 + t0
    nsimul <- 10000

    gform_basic <- gformula(obs_data = basicdata_nocomp, id = id,
                            time_points = time_points,
                            time_name = time_name, covnames = covnames,
                            outcome_name = outcome_name,
                            outcome_type = outcome_type, covtypes = covtypes,
                            covparams = covparams, ymodel = ymodel,
                            histories = histories, histvars = histvars,
                            basecovs = c('L3'), nsimul = nsimul,
                            seed = 1234,
                            intervention1.A = list(static, rep(0, time_points)),
                            intervention2.A = list(static, rep(1, time_points)),
                            int_descript = c('Never treat', 'Always treat'))
    gform_basic

    ## PREDICTED RISK UNDER MULTIPLE INTERVENTIONS
    ##
    ## Intervention      Description
    ## 0         Natural course
    ## 1         Never treat
    ## 2         Always treat
    ##
    ## Sample size = 2500, Monte Carlo sample size = 10000
    ## Number of bootstrap samples = 0
    ## Reference intervention = natural course (0)
    ##
    ##
    ##      k Interv. NP Risk g-form risk Risk ratio Risk difference % Intervened On
    ##  <num>   <num>   <num>       <num>      <num>           <num>           <num>
    ##      6       0  0.5056   0.5041395  1.0000000       0.0000000            0.00
    ##      6       1      NA   0.7307657  1.4495308       0.2266262          100.00
    ##      6       2      NA   0.2336471  0.4634571      -0.2704925           94.67
    ##  Aver % Intervened On
    ##                 <num>
    ##               0.00000
    ##              71.62286
    ##              34.00000

## Example 2: Custom interventions

In this example, we apply a custom intervention that assigns treatment if is below a certain threshold. We first define the custom intervention function.

    example_intervention <- function(newdf, pool, intvar, intvals, time_name, t){
      newdf[, (intvar) := 0]
      newdf[L2 < intvals[[1]], (intvar) := 1]
    }

Next, we apply the g-formula with this custom intervention where we consider different thresholds for .

    gform_basic <- gformula(obs_data = basicdata_nocomp, id = id,
                            time_points = time_points,
                            time_name = time_name, covnames = covnames,
                            outcome_name = outcome_name,
                            outcome_type = outcome_type, covtypes = covtypes,
                            covparams = covparams, ymodel = ymodel,
                            histories = histories, histvars = histvars,
                            basecovs = c('L3'), nsimul = nsimul,
                            seed = 1234,
                            intervention1.A = list(example_intervention, 0.8),
                            intervention2.A = list(example_intervention, 1),
                            int_descript = c('Treat if L2 < 0.8', 'Treat if L2 < 1'))
    gform_basic

    ## PREDICTED RISK UNDER MULTIPLE INTERVENTIONS
    ##
    ## Intervention      Description
    ## 0         Natural course
    ## 1         Treat if L2 < 0.8
    ## 2         Treat if L2 < 1
    ##
    ## Sample size = 2500, Monte Carlo sample size = 10000
    ## Number of bootstrap samples = 0
    ## Reference intervention = natural course (0)
    ##
    ##
    ##      k Interv. NP Risk g-form risk Risk ratio Risk difference % Intervened On
    ##  <num>   <num>   <num>       <num>      <num>           <num>           <num>
    ##      6       0  0.5056   0.5041395  1.0000000       0.0000000            0.00
    ##      6       1      NA   0.6958459  1.3802645       0.1917064           99.88
    ##      6       2      NA   0.3302342  0.6550453      -0.1739053           96.32
    ##  Aver % Intervened On
    ##                 <num>
    ##               0.00000
    ##              68.50143
    ##              38.47143

## References

McGrath S, Lin V, Zhang Z, Petito LC, Logan RW, Hernán MA, Young JG. gfoRmula: an R package for estimating the effects of sustained treatment strategies via the parametric g-formula. Patterns. 2020 Jun 12;1(3).