# Defining your SEQopts()

# 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")`