---
title: "Defining your SEQopts()"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Defining your SEQopts()}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
data.table::setDTthreads(2)
```

# Behind SEQopts()

`SEQopts()` provides the primary API to changing internal options of `SEQuential()`. While the documentation should go over their use, we will expand on them here in greater detail:

## The options

### General Options

| Option Name | Description | Input Type | Example |
|------------|-------------------------------------|------------|------------|
| `bootstrap` | Whether bootstrapping should take place | Logical | `TRUE` |
| `bootstrap.CI` | Defines the confidence interval after bootstrapping (should be within [0, 1]) | Numeric double | `0.95` |
| `bootstrap.CI_method` | Selects which way to calculate bootstraps confidence intervals (`"se"`, `"percentile"`) | Character | `"se"` |
| `bootstrap.nboot` | Number of bootstraps to run in addition to the full model | Integer | `100L` |
| `bootstrap.sample` | Subsample of data to use when bootstrapping | Numeric double [0, 1] | `0.8` |
| `compevent` | Column name for competing event variable | Character | `"death"` |
| `covariates` | If provided, forces covariates for outcome models | Character | `"X1+X2*X3+X4"` |
| `data.return` | Whether to return expanded data as output | Logical | `TRUE` |
| `end_of_fup` | Estimate an outcome measured at a single follow-up time as a weighted per-arm average, instead of fitting a survival outcome model. Incompatible with `km.curves`, `hazard`, `compevent` and the dose-response method | Logical | `TRUE` |
| `end_of_fup.time` | The follow-up time `k` at which the end-of-follow-up outcome is evaluated (required when `end_of_fup = TRUE`) | Numeric | `12` |
| `end_of_fup.type` | Type of end-of-follow-up outcome: `"binary"` reports the weighted proportion per arm, `"continuous"` the weighted mean | Character | `"binary"` |
| `end_of_fup.window` | Half-width of the window used when a trial-period has no measurement at exactly `end_of_fup.time`; it then falls back to the measurement nearest to `k` within `[k - window, k + window]` (ties broken toward the later one, so at least `k` of follow-up has elapsed), and is censored if there is none | Numeric | `3` |
| `expand.only` | Return the expanded dataset and skip analysis | Logical | `TRUE` |
| `followup.class` | Whether to expand followup values to an indicator matrix | Logical | `FALSE` |
| `followup.include` | Whether to include `followup` and `followup_squared` in outcome models | Logical | `TRUE` |
| `followup.max` | Maximum value of followup per trial | Numeric | `60` |
| `followup.min` | Minimum value of followup per trial | Numeric | `0` |
| `followup.spline` | Whether to format followup values to a spline | Logical | `FALSE` |
| `followup.spline.df` | Degrees of freedom passed to `splines::ns()` when `followup.spline = TRUE` | Integer | `4L` |
| `hazard` | Whether to estimate the hazard ratio | Logical | `FALSE` |
| `km.curves` | Whether to estimate Kaplan-Meier survival curves and data | Logical | `TRUE` |
| `multinomial` | Whether to expect more than 2 treatment types | Logical | `FALSE` |
| `ncores` | Number of cores to use in parallel multisession | Integer | `8L` |
| `nthreads` | Number of threads to use for **data.table** manipulations | Integer | `16L` |
| `parallel` | Whether the SEQuential process should be run in parallel | Logical | `TRUE` |
| `risk.times` | Follow-up times (in follow-up units) at which to report risk difference and risk ratio when `km.curves = TRUE`; each is snapped to the latest follow-up at or before it and the final time is always included (`NA` reports only the final time) | Numeric vector | `c(36, 120)` |
| `seed` | Starting seed for random number generators | Integer | `1636` |
| `selection.first_trial` | Selects only the first eligible trial in the expanded dataset | Logical | `TRUE` |
| `selection.prob` | Subsample of total IDs to select | Numeric double [0, 1] | `0.8` |
| `selection.random` | Whether to randomly select IDs with replacement to run analysis | Logical | `FALSE` |
| `subgroup` | Column name for subgroup analysis | Character | `"sex"` |
| `survival.max` | Maximum value for Risk/Survival curves | Numeric double | `60` |
| `trial.include` | Whether to include `trial` and `trial_squared` in outcome models | Logical | `TRUE` |
| `treat.level` | Treatment levels to compare | List | `c(0, 1)` |
| `visit` | Column name for visit indicator | Character | `"visit"` |
| `visit.denominator` | Visit denominator covariates to the right hand side of a formula object | Character | `"X1+X2"` |
| `visit.numerator` | Visit numerator covariates to the right hand side of a formula object | Character | `"X1+X2"` |

### Weighting Options

In general these only affect analytic methods of 'dose-response' and 'censoring'. However, providing `cense` will allow ITT to be weighted in the case of a censoring variable like loss-to-followup.

| Option Name | Description | Input Type | Example |
|------------|-------------------------------------|------------|------------|
| `cense` | Column name for censoring variable | Character | `"LTFU"` |
| `cense.denominator` | If provided, forces denominator covariates for censoring models | Character | `"A1+A2*A3+A4"` |
| `cense.eligible` | Column name for indicator column defining which rows to use for censoring model | Character | `"eligible_cense"` |
| `cense.numerator` | If provided, forces numerator covariates for censoring models | Character | `"Z1+Z2*Z3+Z4"` |
| `denominator` | If provided, forces denominator covariates for weight models | Character | `"C1+C2*C3+B4"` |
| `numerator` | If provided, forces numerator covariates for weight models | Character | `"B1+B2*B3+B4"` |
| `weight.eligible_cols` | List of column names for indicator columns defining which weights are eligible for weight models | Character list | `list("eligible1", "eligible2")` |
| `weight.lag_condition` | Whether weights should be conditioned on treatment lag value | Logical | `TRUE` |
| `weight.lower` | Lower truncation for weight values | Numeric double | `0.0` |
| `weight.p99` | Whether to truncate weights at the 1st and 99th percentiles | Logical | `TRUE` |
| `weight.preexpansion` | Whether weighting should be done on pre-expanded data | Logical | `TRUE` |
| `weight.upper` | Upper truncation for weight values | Numeric double | `10.0` |
| `weighted` | Whether the analysis should be weighted | Logical | `TRUE` |

### Plot Options (`km.curves = TRUE`)

All of these can be changed after `SEQuential()` has finished analysis - if you forget to add them, no need to stop and restart. Additionally, `SEQuential()` will output the data used for the plot if you would like to customize it yourself through your preferred plotting software.

| Option Name | Description | Input Type | Example |
|--------------|-------------------------------|--------------|--------------|
| `plot.colors` | Figure colors for output plot | List | `list("red", "blue")` |
| `plot.labels` | Legend labels for output plot | List | `list("Tx 0", "Tx 1")` |
| `plot.subtitle` | Subtitle for plot output | Character | `"My Plot Subtitle"` |
| `plot.title` | Title for plot output | Character | `"My Plot Title"` |
| `plot.type` | Type of output plot (`"survival"`, `"risk"`, `"inc"`) | Character | `"survival"` |

### Special Cases

| Option Name | Description | Input Type | Example |
|--------------|-------------------------------|--------------|--------------|
| `excused` | When censoring, whether there is an excused condition | Logical | `TRUE` |
| `excused.cols` | List of column names for treatment switch excuses | List | `list("excuse1", "excuse2")` |

### Internal Options

These are internal options that change output name of covariates or the decomposition method when estimating coefficients.

| Option Name | Description | Input Type | Example |
|------------|-------------------------------------|------------|------------|
| `fastglm.method` | Method for decomposition by fastglm | Integer | `3L` |
| `glm.package` | Package to use for fitting GLMs | Character | either `"fastglm"` (default) or `"parglm"` |
| `indicator.baseline` | Identifier for baseline variables | Character | `"_bas"` |
| `indicator.squared` | Identifier for squared variables | Character | `"_sq"` |
| `parglm.control` | A control object from `parglm::parglm.control()` to pass to `parglm::parglm.fit()` | List | `parglm::parglm.control(method = "LINPACK")` |
