# Introduction to SEQuential

## Setting up your Analysis

There are some assumptions which must be met to avoid unintended errors when using SEQuential. These are:

1. User provided `time.col` begins at 0 per unique `id.col` entries, we also assume that the column contains only integers and continues by 1 for every time step. e.g. (0, 1, 2, 3, …) is allowed and (0, 1, 2, 2.5, …) or (0, 1, 2, 4, 5, …) are not.
2. Provided `time.col` entries may be out of order as a sort is enforced at the beginning of the function, e.g. (0, 2, 1, 4, 3, …) is valid because it begins at 0 and is continuously increasing by increments of 1, even though it is not ordered.
3. `eligible` and column names provided to `excused.cols` are binary (0/1) flag variables (with respect to `time.col`)

### Step 1 - Defining your options

In your R script, you will always start by defining your options object, through the `SEQopts()` helper. There are many defaults which allow you to target exactly how you would like to change your analysis. Through this wiki there are specific pages dedicated to each causal contrast and the parameters which affect them, but for simplicity let’s start with an intention-to-treat analysis with 20 bootstrap samples.

    library(SEQTaRget)

    options <- SEQopts(km.curves = TRUE, #asks the function to return survival and risk estimates
                       bootstrap = TRUE, #asks the model to perform bootstrapping
                       bootstrap.nboot = 20) #asks the model for 20 bootstrap samples

In general, options will be in the form `{option}.{parameter}` - here you may notice that we use `bootstrap.nboot` indicating that this parameter affects the `bootstrap`

### Step 2 - Running the Primary Function

The next step is running the primary R function, `SEQuential()`. Here you will give your options, data, and data-level information. We provide some small simulated datasets to test on.

    data <- SEQdata
    model <- SEQuential(data, id.col = "ID",
                              time.col = "time",
                              eligible.col = "eligible",
                              treatment.col = "tx_init",
                              outcome.col = "outcome",
                              time_varying.cols = c("N", "L", "P"),
                              fixed.cols = "sex",
                              method = "ITT", options = options)
    #>
    #> Full dataset: 12,180 observations, 11 variables
    #>
    #> Non-required columns provided, pruning for efficiency
    #>
    #> Pruned
    #>
    #> Original dataset (eligible subjects): 9,203 observations, 9 variables
    #>
    #> Expanding Data...
    #>
    #> Pre-filter expansion: 310,080 observations
    #>
    #> Expanded dataset: 248,485 observations, 13 variables
    #>
    #> Expansion Successful
    #>
    #> Final analysis dataset: 248,485 observations, 13 variables
    #>
    #> Moving forward with ITT analysis
    #>
    #> Bootstrapping with 80% of 300 subjects (240 subjects, ~198,788 observations per resample) 20 times
    #>
    #> ITT model created successfully
    #>
    #> Creating Survival curves
    #>
    #> Completed

We provide some print statements to help track where the `SEQuential()` function is processing at any given point in time.

### Step 3 - Recovering your results

`SEQuential()` produces a lot of internal diagnostics, models, and dataframes out of its main function in an S4 class. We provide a few different methods to handle obtaining your results.

    outcome(model)     # Returns a list of only the outcome models
    #> $`1`
    #> $`1`[[1]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -6.8593155              0.2253094              0.0353817
    #>           followup_sq                  trial               trial_sq
    #>            -0.0001599              0.0447179              0.0005762
    #>                  sex1                  N_bas                  L_bas
    #>             0.1270458              0.0032867             -0.0138509
    #>                 P_bas  tx_init_bas1:followup
    #>             0.2009289             -0.0017040
    #>
    #> $`1`[[2]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -1.142e+01              5.460e-02              3.791e-02
    #>           followup_sq                  trial               trial_sq
    #>            -4.194e-05              1.368e-01             -7.522e-05
    #>                  sex1                  N_bas                  L_bas
    #>             2.543e-01             -7.727e-04              4.306e-02
    #>                 P_bas  tx_init_bas1:followup
    #>             6.704e-01              5.939e-03
    #>
    #> $`1`[[3]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -3.3498939             -0.1304562              0.0225204
    #>           followup_sq                  trial               trial_sq
    #>             0.0001097             -0.0136204              0.0008879
    #>                  sex1                  N_bas                  L_bas
    #>            -0.0112329              0.0028767              0.1422793
    #>                 P_bas  tx_init_bas1:followup
    #>            -0.1612921              0.0097465
    #>
    #> $`1`[[4]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -9.654e+00              2.340e-01              5.385e-02
    #>           followup_sq                  trial               trial_sq
    #>            -2.283e-04              1.099e-01              6.676e-05
    #>                  sex1                  N_bas                  L_bas
    #>             1.060e-02              2.478e-03              1.596e-04
    #>                 P_bas  tx_init_bas1:followup
    #>             4.625e-01             -5.474e-03
    #>
    #> $`1`[[5]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -3.8762731              0.2839141              0.0446831
    #>           followup_sq                  trial               trial_sq
    #>            -0.0002418             -0.0171521              0.0008746
    #>                  sex1                  N_bas                  L_bas
    #>             0.3577205              0.0023892              0.1213233
    #>                 P_bas  tx_init_bas1:followup
    #>            -0.1543408             -0.0061850
    #>
    #> $`1`[[6]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -7.872e+00              2.857e-01              4.979e-02
    #>           followup_sq                  trial               trial_sq
    #>            -2.134e-04              7.171e-02              9.684e-05
    #>                  sex1                  N_bas                  L_bas
    #>             5.725e-03              1.697e-03              1.643e-01
    #>                 P_bas  tx_init_bas1:followup
    #>             2.710e-01             -5.677e-03
    #>
    #> $`1`[[7]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -3.2199088              0.2787730              0.0544891
    #>           followup_sq                  trial               trial_sq
    #>            -0.0005079             -0.0111051              0.0005926
    #>                  sex1                  N_bas                  L_bas
    #>             0.0884466              0.0073813              0.0798378
    #>                 P_bas  tx_init_bas1:followup
    #>            -0.2158476             -0.0111902
    #>
    #> $`1`[[8]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -1.354e+01              4.235e-01              2.875e-02
    #>           followup_sq                  trial               trial_sq
    #>            -2.554e-04              1.733e-01             -3.871e-04
    #>                  sex1                  N_bas                  L_bas
    #>            -8.301e-02              5.562e-03             -2.383e-01
    #>                 P_bas  tx_init_bas1:followup
    #>             9.544e-01             -1.051e-02
    #>
    #> $`1`[[9]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -1.416e+01              2.321e-01              3.835e-02
    #>           followup_sq                  trial               trial_sq
    #>            -2.675e-04              1.756e-01             -1.391e-04
    #>                  sex1                  N_bas                  L_bas
    #>            -7.554e-02              3.196e-03              7.352e-02
    #>                 P_bas  tx_init_bas1:followup
    #>             9.779e-01              6.029e-03
    #>
    #> $`1`[[10]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -6.655e+00              3.970e-01              2.521e-02
    #>           followup_sq                  trial               trial_sq
    #>             8.869e-06              3.420e-02              5.946e-04
    #>                  sex1                  N_bas                  L_bas
    #>             2.502e-01              3.615e-03             -3.848e-02
    #>                 P_bas  tx_init_bas1:followup
    #>             1.883e-01             -4.851e-03
    #>
    #> $`1`[[11]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -5.8598484              0.3091680              0.0455605
    #>           followup_sq                  trial               trial_sq
    #>            -0.0002919              0.0329778              0.0006202
    #>                  sex1                  N_bas                  L_bas
    #>             0.2823440             -0.0001494             -0.0778672
    #>                 P_bas  tx_init_bas1:followup
    #>             0.0964464             -0.0103717
    #>
    #> $`1`[[12]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -6.5048190              0.3084113              0.0302161
    #>           followup_sq                  trial               trial_sq
    #>            -0.0001221              0.0289356              0.0008674
    #>                  sex1                  N_bas                  L_bas
    #>             0.2407384              0.0010997             -0.1096261
    #>                 P_bas  tx_init_bas1:followup
    #>             0.1741302             -0.0048712
    #>
    #> $`1`[[13]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -8.7146457              0.1887386              0.0354209
    #>           followup_sq                  trial               trial_sq
    #>            -0.0001994              0.0826768              0.0001829
    #>                  sex1                  N_bas                  L_bas
    #>             0.3489603              0.0010110             -0.0016571
    #>                 P_bas  tx_init_bas1:followup
    #>             0.3850167             -0.0008589
    #>
    #> $`1`[[14]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -7.2989331              0.2469415              0.0428921
    #>           followup_sq                  trial               trial_sq
    #>            -0.0002066              0.0588531              0.0004014
    #>                  sex1                  N_bas                  L_bas
    #>            -0.0417420             -0.0016170              0.0409524
    #>                 P_bas  tx_init_bas1:followup
    #>             0.2477187             -0.0026039
    #>
    #> $`1`[[15]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -7.0345524              0.2102826              0.0423960
    #>           followup_sq                  trial               trial_sq
    #>            -0.0002520              0.0555857              0.0003593
    #>                  sex1                  N_bas                  L_bas
    #>             0.2185446              0.0027708              0.0017738
    #>                 P_bas  tx_init_bas1:followup
    #>             0.2021000             -0.0045819
    #>
    #> $`1`[[16]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -7.305e+00              4.630e-02              2.220e-02
    #>           followup_sq                  trial               trial_sq
    #>             1.896e-05              4.636e-02              7.206e-04
    #>                  sex1                  N_bas                  L_bas
    #>             3.077e-01              6.235e-03             -7.164e-02
    #>                 P_bas  tx_init_bas1:followup
    #>             2.389e-01              8.571e-03
    #>
    #> $`1`[[17]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -2.212e+00              2.205e-01              4.276e-02
    #>           followup_sq                  trial               trial_sq
    #>            -2.377e-04             -4.227e-02              1.375e-03
    #>                  sex1                  N_bas                  L_bas
    #>             3.693e-01              1.906e-03             -2.166e-01
    #>                 P_bas  tx_init_bas1:followup
    #>            -3.123e-01              8.017e-06
    #>
    #> $`1`[[18]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -1.013e+01              3.768e-01              4.717e-02
    #>           followup_sq                  trial               trial_sq
    #>            -3.080e-04              1.008e-01              2.401e-05
    #>                  sex1                  N_bas                  L_bas
    #>             3.800e-01              3.652e-03              1.027e-01
    #>                 P_bas  tx_init_bas1:followup
    #>             5.084e-01             -1.162e-02
    #>
    #> $`1`[[19]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -3.1209072              0.1868126              0.0404734
    #>           followup_sq                  trial               trial_sq
    #>            -0.0002459             -0.0232774              0.0010339
    #>                  sex1                  N_bas                  L_bas
    #>             0.1942638              0.0022952             -0.0182316
    #>                 P_bas  tx_init_bas1:followup
    #>            -0.2126433             -0.0019657
    #>
    #> $`1`[[20]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -2.9744004              0.1211038              0.0343352
    #>           followup_sq                  trial               trial_sq
    #>            -0.0001729             -0.0231250              0.0012913
    #>                  sex1                  N_bas                  L_bas
    #>             0.2703645             -0.0057852             -0.3095214
    #>                 P_bas  tx_init_bas1:followup
    #>            -0.1923032             -0.0023748
    #>
    #> $`1`[[21]]
    #>
    #> Call:  fastglm.default(x = X, y = y, family = family, start = start,
    #>     method = params@fastglm.method)
    #>
    #> Coefficients:
    #>           (Intercept)           tx_init_bas1               followup
    #>            -9.2861343              0.4711949              0.0419221
    #>           followup_sq                  trial               trial_sq
    #>            -0.0002020              0.0882078              0.0003023
    #>                  sex1                  N_bas                  L_bas
    #>             0.1783233              0.0039188             -0.1056911
    #>                 P_bas  tx_init_bas1:followup
    #>             0.4515229             -0.0065481
    km_curve(model)    # Prints the survival curve

    risk_data(model)
    #> Index: <Followup>
    #>    Method Followup      A      Risk   95% LCI   95% UCI         SE
    #>    <char>    <num> <char>     <num>     <num>     <num>      <num>
    #> 1:    ITT       60      0 0.8372582 0.7488409 0.9256755 0.04511170
    #> 2:    ITT       60      1 0.8744359 0.7888421 0.9600297 0.04367109
    risk_comparison(model)
    #>    Followup    A_x    A_y Risk Ratio RR 95% LCI RR 95% UCI log(RR) SE
    #>       <num> <fctr> <fctr>      <num>      <num>      <num>      <num>
    #> 1:       60 risk_0 risk_1  1.0444041  0.9719203   1.122294 0.03669861
    #> 2:       60 risk_1 risk_0  0.9574838  0.8910325   1.028891 0.03669861
    #>    Risk Difference  RD 95% LCI RD 95% UCI      RD SE
    #>              <num>       <num>      <num>      <num>
    #> 1:      0.03717768 -0.02368060 0.09803596 0.03105071
    #> 2:     -0.03717768 -0.09803596 0.02368060 0.03105071