# Function Options

# Function Options at a Glance

This page is a practical companion to the function reference. It lists the important arguments, their defaults, accepted choices, and what each option does.

Most user-facing arguments accept quoted names and bare names. Quoted names are recommended inside scripts, functions, and Shiny apps because they are easier to program with.

## Common Choices

Option family | Available choices | Meaning
--- | --- | ---
Table `format` | `"flextable"`, `"gt"`, `"tibble"` where supported | `flextable` is Word-friendly and the package default for publication tables; `gt` is useful for HTML/pkgdown; `tibble` is useful for inspection and downstream work.
Table `theme` | `"minimal"`, `"clinical"`, `"striped"`, `"shaded"`, `"jama"` | Preset table styling. `theme = "minimal"` is the default in most table functions.
Regression `approach` | `"logit"`, `"firth"`, `"logbinomial"`, `"poisson"`, `"robpoisson"`, `"negbin"`, `"linear"` | Chooses the model family for standard regression tables.
Survival `approach` | `"cox"`, `"survreg"` where supported | Enables Cox or parametric survival workflows in selected helper functions.
Parametric survival `distribution` | `"weibull"`, `"exponential"`, `"lognormal"`, `"loglogistic"` | Distribution used by parametric survival regression.
Reference rows | `show_ref = TRUE` or `FALSE` | `TRUE` displays reference categories as `Ref.`; `FALSE` makes compact tables and plots.
Survival sample display | `"events"`, `"n"`, `"both"`, `"none"` | Controls whether stratified Cox/survival tables show event counts, N, both, or neither.

## Describe and Inspect Data

### `descriptive_table()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`data` | required | data frame | Analysis dataset.
`exposures` | required | column names | Variables to summarise.
`by` | `NULL` | one column name or `NULL` | Creates grouped summary columns.
`percent` | `"column"` | `"column"`, `"row"` | Chooses denominator for categorical percentages.
`digits` | `1` | whole number | Number of decimal places.
`show_missing` | `"ifany"` | `"ifany"`, `"no"` | Shows missing rows only when present, or hides them.
`show_dichotomous` | `"all_levels"` | `"all_levels"`, `"single_row"` | Shows both binary levels by default; `single_row` shows one selected level.
`show_overall` | `"no"` | `"no"`, `"first"`, `"last"` | Adds an overall column before or after grouped columns.
`statistic` | `NULL` | `mean`, `median`, `mode`, `count`, `categorical`; can be named vector | Chooses numeric summary style or forces a numeric variable to display as categorical.
`value` | `NULL` | named vector of displayed levels | Selects the displayed level when `show_dichotomous = "single_row"`.
`format` | `"flextable"` | `"flextable"`, `"gt"` | Output table engine.
`theme` | `"minimal"` | table theme preset | Table styling.

    descriptive_table(
      data = birthwt_data,
      exposures = c(age, lwt, smoke, race),
      by = low,
      statistic = c(age = mean, lwt = median),
      show_overall = last
    )

### `dissect()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`data` | required | data frame | Dataset to inspect.
`verbose` | `FALSE` | `TRUE`, `FALSE` | Prints extra console guidance when `TRUE`.
`format` | `"flextable"` | `"flextable"`, `"gt"`, `"tibble"` | Publication table or inspectable tibble.

## Regression Tables

### `uni_reg()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`data` | required | data frame | Analysis dataset.
`outcome` | required | one column name | Outcome variable.
`exposures` | required | column names | Fits one univariable model per exposure.
`approach` | `"logit"` | `"logit"`, `"firth"`, `"logbinomial"`, `"poisson"`, `"robpoisson"`, `"negbin"`, `"linear"` | Model family and effect measure.
`format` | `"flextable"` | `"flextable"`, `"gt"` | Output table engine.
`theme` | `"minimal"` | table theme preset | Table styling.
`model_stats` | `FALSE` | `TRUE`, `FALSE` | Attaches AIC, BIC, log-likelihood, pseudo R2 or R2 where relevant, and N.
`show_ref` | `TRUE` | `TRUE`, `FALSE` | Displays or hides reference category rows.

### `multi_reg()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`data` | required | data frame | Analysis dataset.
`outcome` | required | one column name | Outcome variable.
`exposures` | required | column names | Variables to report.
`adjust_for` | `NULL` | column names or `NULL` | Adds adjustment covariates while reporting only `exposures`.
`interaction` | `NULL` | interaction specification or `NULL` | Fits interaction terms, for example `smoke*race`.
`approach` | `"logit"` | `"logit"`, `"firth"`, `"logbinomial"`, `"poisson"`, `"robpoisson"`, `"negbin"`, `"linear"` | Model family and effect measure.
`format` | `"flextable"` | `"flextable"`, `"gt"` | Output table engine.
`theme` | `"minimal"` | table theme preset | Table styling.
`model_stats` | `FALSE` | `TRUE`, `FALSE` | Attaches model-fit statistics.
`show_ref` | `TRUE` | `TRUE`, `FALSE` | Displays or hides reference category rows.

### `stratified_uni_reg()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`data` | required | data frame | Analysis dataset.
`outcome` | required | one column name | Outcome variable.
`exposures` | required | column names | Fits one univariable model per exposure within each stratum.
`stratifier` | required | one column name | Splits the analysis into strata.
`approach` | `"logit"` | standard regression approaches | Model family and effect measure.
`format` | `"flextable"` | `"flextable"`, `"gt"` | Output table engine.
`theme` | `"minimal"` | table theme preset | Table styling.
`show_ref` | `TRUE` | `TRUE`, `FALSE` | Displays or hides reference category rows.

### `stratified_multi_reg()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`data` | required | data frame | Analysis dataset.
`outcome` | required | one column name | Outcome variable.
`exposures` | required | column names | Variables to report within each stratum.
`stratifier` | required | one column name | Splits the analysis into strata.
`adjust_for` | `NULL` | column names or `NULL` | Adds adjustment covariates within each stratum.
`interaction` | `NULL` | interaction specification or `NULL` | Fits interaction terms within each stratum.
`approach` | `"logit"` | standard regression approaches | Model family and effect measure.
`format` | `"flextable"` | `"flextable"`, `"gt"` | Output table engine.
`theme` | `"minimal"` | table theme preset | Table styling.
`show_ref` | `TRUE` | `TRUE`, `FALSE` | Displays or hides reference category rows.

## Cox and Parametric Survival Regression

### `cox_reg()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`data` | required | data frame | Survival dataset.
`time` | required | one column name | Follow-up time. Zero follow-up is allowed; negative time is not.
`event` | required | one column name | Event indicator.
`exposures` | required | column names | Variables to report or use in a full multivariable Cox model.
`adjust_for` | `NULL` | column names or `NULL` | Adds adjustment covariates while reporting only `exposures`.
`stratifier` | `NULL` | one column name or `NULL` | Repeats Cox analyses within strata.
`interaction` | `NULL` | interaction specification or `NULL` | Fits interaction terms.
`multivariable` | `FALSE` | `TRUE`, `FALSE` | If `TRUE`, fits one Cox model using all variables in `exposures`.
`multivariate` | `NULL` | `TRUE`, `FALSE`, `NULL` | Backward-compatible alias for `multivariable`.
`format` | `"flextable"` | `"flextable"`, `"gt"` | Output table engine.
`theme` | `"minimal"` | table theme preset | Table styling.
`show_sample` | `"events"` | `"events"`, `"n"`, `"both"`, `"none"` | Controls displayed sample columns in stratified Cox tables.
`model_stats` | `FALSE` | `TRUE`, `FALSE` | Attaches AIC, BIC, log-likelihood, concordance, N, and events.
`show_ref` | `TRUE` | `TRUE`, `FALSE` | Displays or hides reference category rows.

### `surv_reg()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`data` | required | data frame | Survival dataset.
`time` | required | one column name | Follow-up time. Zero follow-up is allowed; negative time is not.
`event` | required | one column name | Event indicator.
`exposures` | required | column names | Variables to report or use in a full multivariable model.
`adjust_for` | `NULL` | column names or `NULL` | Adds adjustment covariates while reporting only `exposures`.
`stratifier` | `NULL` | one column name or `NULL` | Repeats parametric survival analyses within strata.
`interaction` | `NULL` | interaction specification or `NULL` | Fits interaction terms.
`multivariable` | `FALSE` | `TRUE`, `FALSE` | If `TRUE`, fits one model using all variables in `exposures`.
`multivariate` | `NULL` | `TRUE`, `FALSE`, `NULL` | Backward-compatible alias for `multivariable`.
`distribution` | `"weibull"` | `"weibull"`, `"exponential"`, `"lognormal"`, `"loglogistic"` | Parametric survival distribution.
`format` | `"flextable"` | `"flextable"`, `"gt"` | Output table engine.
`theme` | `"minimal"` | table theme preset | Table styling.
`show_sample` | `"events"` | `"events"`, `"n"`, `"both"`, `"none"` | Controls displayed sample columns in stratified survival tables.
`model_stats` | `FALSE` | `TRUE`, `FALSE` | Attaches model-fit statistics.
`show_ref` | `TRUE` | `TRUE`, `FALSE` | Displays or hides reference category rows.

## Kaplan-Meier and Survival Summaries

### `km_plot()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`data` | required | data frame | Survival dataset.
`time` | required | one column name | Follow-up time.
`event` | required | one column name | Event indicator.
`by` | `NULL` | one column name or `NULL` | Draws grouped curves when supplied.
`conf.int` | `TRUE` | `TRUE`, `FALSE` | Shows shaded confidence intervals.
`risk_table` | `TRUE` | `TRUE`, `FALSE` | Adds a number-at-risk table.
`p_value` | `TRUE` | `TRUE`, `FALSE` | Adds log-rank p-value for grouped curves.
`p_value_position` | `NULL` | numeric `c(x, y)` or `NULL` | Manually positions the p-value label.
`censor` | `TRUE` | `TRUE`, `FALSE` | Shows censor marks.
`break_time_by` | `NULL` | number or `NULL` | Controls x-axis and risk-table time breaks.
`xlim` | `NULL` | numeric range or `NULL` | Zooms the follow-up time axis.
`ylim` | `NULL` | numeric range or `NULL` | Zooms the survival probability axis, for example `c(0.5, 1)`.
`xlab` | `"Time"` | character | X-axis label.
`ylab` | `"Survival probability"` | character | Y-axis label.
`title` | `NULL` | character or `NULL` | Main title.
`subtitle` | `NULL` | character or `NULL` | Subtitle.
`caption` | `NULL` | character or `NULL` | Figure caption.
`title_size` | `NULL` | number or `NULL` | Custom title size for publication panels.
`title_face` | `"bold"` | `"plain"`, `"bold"`, `"italic"`, `"bold.italic"` | Title font face.
`legend_title` | `NULL` | character or `NULL` | Legend heading.
`legend_position` | `NULL` | `"bottom"`, `"top"`, `"right"`, `"left"`, `"none"`, `NULL` | Legend location.
`palette` | `NULL` | colour vector or `NULL` | Curve and confidence-band colours.
`y_percent` | `TRUE` | `TRUE`, `FALSE` | Displays survival probability as percentages.
`theme` | `"classic"` | `"classic"`, `"minimal"`, `"bw"`, `"light"`, `"none"` | ggplot theme style.
`grid` | `FALSE` | `TRUE`, `FALSE` | Adds grid lines when `TRUE`.
`base_size` | `13` | number | Base font size.

### `survival_summary()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`data`, `time`, `event` | required | data frame and column names | Defines the survival object.
`by` | `NULL` | one column name or `NULL` | Produces grouped summaries.
`digits` | `1` | whole number | Number of decimal places.
`format` | `"flextable"` | `"flextable"`, `"gt"`, `"tibble"` | Output format.
`theme` | `"minimal"` | table theme preset | Table styling.

### `survival_quantiles()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`data`, `time`, `event` | required | data frame and column names | Defines the survival object.
`by` | `NULL` | one column name or `NULL` | Produces grouped quantiles.
`probs` | `c(0.25, 0.5, 0.75)` | probabilities between 0 and 1 | Survival-time quantiles to display.
`digits` | `1` | whole number | Number of decimal places.
`format` | `"flextable"` | `"flextable"`, `"gt"`, `"tibble"` | Output format.
`theme` | `"minimal"` | table theme preset | Table styling.

### `survival_prob()` and `km_risk_table()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`data`, `time`, `event` | required | data frame and column names | Defines the survival object.
`by` | `NULL` | one column name or `NULL` | Produces grouped outputs.
`times` | required | numeric vector | Time points for survival probability or number at risk.
`digits` | `1` | whole number | Number of decimal places.
`extend` | `TRUE` | `TRUE`, `FALSE` | Allows reporting beyond the last event time where appropriate.
`format` | `"flextable"` | `"flextable"`, `"gt"`, `"tibble"` | Output format.
`theme` | `"minimal"` | table theme preset | Table styling.

### `logrank_test()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`data`, `time`, `event`, `by` | required | data frame and column names | Defines grouped survival comparison.
`digits` | `2` | whole number | Number of decimal places.
`format` | `"flextable"` | `"flextable"`, `"gt"`, `"tibble"` | Output format.
`theme` | `"minimal"` | table theme preset | Table styling.

### `rmst_table()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`data`, `time`, `event` | required | data frame and column names | Defines the survival object.
`by` | `NULL` | one column name or `NULL` | Produces grouped RMST estimates.
`tau` | required | number | Restriction time for RMST.
`digits` | `1` | whole number | Number of decimal places.
`conf.level` | `0.95` | number between 0 and 1 | Confidence level.
`format` | `"flextable"` | `"flextable"`, `"gt"`, `"tibble"` | Output format.
`theme` | `"minimal"` | table theme preset | Table styling.

### Parametric survival helpers

Function | Argument | Default | Available options or input | What it does
--- | --- | --- | --- | ---
`surv_model_compare()` | `distributions` | four common distributions | `"weibull"`, `"exponential"`, `"lognormal"`, `"loglogistic"` | Compares candidate parametric survival distributions.
`surv_model_compare()` | `exposures`, `adjust_for` | required, `NULL` | column names | Defines predictors and adjustment covariates.
`surv_predict()` | `model`, `newdata`, `times` | required, `NULL`, required | fitted model, data frame, numeric times | Predicts survival probabilities.
`plot_surv_fit()` | `distributions` | four common distributions | distribution names | Draws fitted parametric survival curves.
`plot_surv_fit()` | `by`, `adjust_for` | `NULL`, `NULL` | column names or `NULL` | Groups curves or adjusts predicted curves.
`plot_surv_fit()` | `break_time_by`, `xlim`, `n_points` | `NULL`, `NULL`, `200` | number, range, number | Controls curve resolution and x-axis.
`check_ph()` | `transform` | `"km"` | `"km"`, `"rank"`, `"identity"` | Chooses time transform for proportional hazards test.
`check_ph()` | `alpha` | `0.05` | number | Threshold used to flag possible PH violation.
`check_ph()` | `format` | `"flextable"` | `"flextable"`, `"gt"`, `"tibble"` | Output format.

## Regression Plots and Model Fit

### `plot_reg()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`tbl` | required | gtregression regression object | Plots regression estimates.
`title`, `caption` | `NULL` | character or `NULL` | Plot title and caption.
`ref_line` | automatic | number or `NULL` | Null reference line; usually 1 for ratios and 0 for linear estimates.
`order_y` | `NULL` | character vector or `NULL` | Manually controls vertical order.
`log_x` | `FALSE` | `TRUE`, `FALSE` | Uses a linear x-axis by default. Set `TRUE` for the conventional log-scale display of odds, risk, hazard, or time ratios.
`xlim`, `breaks` | `NULL` | numeric vectors or `NULL` | Controls axis range and tick marks.
`point_color`, `errorbar_color` | `"#6B7280"` | colour values | Styles non-significant estimates and confidence intervals with neutral grey.
`sig_color`, `sig_errorbar_color` | `"#0072B2"` | colour values or `NULL` | Highlights estimates whose confidence interval excludes the null with accessible blue; use `NULL` to reuse the base colours.
`point_size`, `point_stroke`, `ci_linewidth` | `2.8`, `0.55`, `0.55` | positive numbers | Controls estimate marker size, marker outline, and confidence-interval thickness.
`base_size` | `12` | number | Base font size. Increase for a single large figure.
`show_ref` | `TRUE` | `TRUE`, `FALSE` | Displays or hides reference rows.
`alpha` | `0.05` | number | Significance threshold.
`show_adjustment_note` | `TRUE` | `TRUE`, `FALSE` | Adds adjustment note when available.

### `plot_reg_combine()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`tbl_uni`, `tbl_multi` | required | two compatible regression objects | Plots crude and adjusted estimates side by side.
`title_uni`, `title_multi`, `caption` | `NULL` | character or `NULL` | Plot labels.
`ref_line`, `order_y`, `log_x` | automatic/`NULL`/`FALSE` | number, order vector, logical | Controls the null line, order, and scale; set `log_x = TRUE` for a ratio-scale log axis.
`xlim_uni`, `breaks_uni` | `NULL` | numeric vectors or `NULL` | Axis control for the crude plot.
`xlim_multi`, `breaks_multi` | `NULL` | numeric vectors or `NULL` | Axis control for the adjusted plot.
`point_color`, `errorbar_color` | `"#6B7280"` | colour values | Styles non-significant estimates and confidence intervals with neutral grey.
`sig_color`, `sig_errorbar_color` | `"#0072B2"` | colour values or `NULL` | Highlights estimates whose confidence interval excludes the null with accessible blue.
`point_size`, `point_stroke`, `ci_linewidth` | `2.8`, `0.55`, `0.55` | positive numbers | Controls estimate marker size, marker outline, and confidence-interval thickness.
`base_size`, `show_ref`, `alpha` | `12`, `TRUE`, `0.05` | number, logical, number | Controls readability, reference rows, and highlighting.
`show_adjustment_note` | `TRUE` | `TRUE`, `FALSE` | Adds adjustment note when available.

### `plot_model_fit()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`model` | required | `uni_reg()`, `multi_reg()`, `cox_reg()`, `surv_reg()`, or fitted model | Object to diagnose.
`model_name` | `NULL` | model name or `NULL` | Selects one named model when the object stores several models.
`type` | `"auto"` | `"auto"`, `"all"`, `"residual"`, `"qq"`, `"scale_location"`, `"cooks"`, `"observed_predicted"`, `"calibration"` | Chooses diagnostic plot type.
`bins` | `10` | whole number | Number of bins for calibration plots.
`base_size` | `13` | number | Base font size.

## Forest Tables and Forest Plots

### `forest_df()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`uni` | required | regression object, descriptive table, or stratified regression object | Main object used to create the forest-ready data.
`multi` | `NULL` | adjusted regression object or `NULL` | Adds adjusted estimates.
`desc` | `NULL` | descriptive table or `NULL` | Adds descriptive columns.
`digits` | `2` | whole number | Number of decimals for forest table estimates.

### `forest_reg()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`df` | `NULL` | `forest_df()` output or `NULL` | Plots prepared forest data.
`uni`, `multi`, `desc` | `NULL` | gtregression objects | Builds and plots in one call.
`theme` | `NULL` | forestploter theme or `NULL` | Plot theme passed to forestploter.
`ci_col_width` | `20` | number | Width of CI drawing columns; increase when forest columns feel cramped.
`side` | `"right"` | `"right"`, `"left"` | Places forest columns to the right or left of text columns.
`quiet` | `TRUE` | `TRUE`, `FALSE` | Suppresses helpful messages.
`effects` | `NULL` | effect column names or `NULL` | Selects which estimate columns to draw.
`ticks_at` | `NULL` | numeric vector or list | Manually sets axis tick marks; useful when x-axis labels overlap.
`ticks_digits` | `NULL` | whole number or `NULL` | Controls tick-label precision.
`xlim` | `NULL` | numeric range or list | Manually sets forest x-axis limits.
`style_strata` | `TRUE` | `TRUE`, `FALSE` | Highlights stratum header rows.
`strata_fill` | `"#EAF2F1"` | colour value | Background colour for stratum rows.
`...` | passed on | forestploter options | Extra arguments forwarded to `forestploter::forest()`.

### `save_forest()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`forest` | required | forest plot object | Object returned by `forest_reg()`.
`filename` | `"forest"` | file path or file stem | Output file. Uses a temporary location when no path is supplied.
`format` | `"pdf"` | `"pdf"`, `"png"`, `"tiff"`, `"jpg"` | Export file type.
`width`, `height` | `NULL` | inches or `NULL` | Manual canvas size.
`scale` | `1` | positive number | Scales automatic width and height.
`auto_size` | `TRUE` | `TRUE`, `FALSE` | Estimates a sensible canvas size from table dimensions.
`padding` | `0.25` | number | Extra white space around the saved forest plot.
`dpi` | `300` | number | Image resolution for raster formats.

## Diagnostics, Selection, and Model Comparison

`select_models()` and `compare_models()` answer different questions. `select_models()` generates and ranks models as part of a selection workflow. `compare_models()` compares specific fitted models that you have named and chosen, checks whether their analysis samples are comparable, and preserves all fit statistics for transparent reporting. Use `interaction_models()` for one planned interaction comparison and `identify_confounder()` for candidate-level confounding/effect-modification screening rather than final causal decisions.

For linear models, typing `result$reg_check` displays a publication-ready diagnostic table. The underlying rows remain available for scripts, for example `result$reg_check$multivariable_model`. These checks complement, rather than replace, residual and influence plots.

### `check_convergence()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`data`, `exposures`, `outcome` | required | data frame and column names | Defines candidate models.
`approach` | `"logit"` | `"logit"`, `"logbinomial"`, `"poisson"`, `"robpoisson"`, `"negbin"` | Model family to test.
`multivariate` | `FALSE` | `TRUE`, `FALSE` | Checks one multivariable model instead of separate univariable models.
`format` | `"flextable"` | `"flextable"`, `"gt"`, `"tibble"` | Output format.

### `check_collinearity()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`model` | required | fitted model | Model to assess for collinearity.
`format` | `"flextable"` | `"flextable"`, `"gt"`, `"tibble"` | Output format.

### `select_models()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`data`, `outcome`, `exposures` | required | data frame and column names | Defines candidate predictors.
`approach` | `"logit"` | standard regression approaches plus `"cox"` and `"survreg"` | Model family used for selection.
`time`, `event` | `NULL` | column names or `NULL` | Required for Cox and parametric survival selection.
`distribution` | `"weibull"` | survival distributions | Parametric survival distribution when `approach = "survreg"`.
`direction` | `"forward"` | `"forward"`, `"backward"`, `"both"` when supported | Stepwise selection direction.
`format` | `"flextable"` | `"flextable"`, `"gt"`, `"tibble"` | Output format.

### `compare_models()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`...` | required | gtregression model objects or fitted models | Candidate models to compare.
`model_names` | `NULL` | character vector or `NULL` | Overrides default model labels; otherwise object names are used when available.
`nested` | `TRUE` | `TRUE`, `FALSE` | Requests sequential likelihood-ratio comparison where appropriate.
`primary_exposure` | `NULL` | one term name or `NULL` | Displays primary estimate and percentage change.
`exponentiate` | `NULL` | `TRUE`, `FALSE`, `NULL` | Controls whether primary estimate is exponentiated.
`digits` | `2` | whole number | Number of decimals for estimates and fit statistics.
`p_digits` | `3` | whole number | Number of decimals for p-values.
`format` | `"flextable"` | `"flextable"`, `"gt"`, `"tibble"` | Output format.
`theme` | `"minimal"` | table theme preset | Table styling.

#### Compare Models in the gtregression App

The R function above compares already fitted gtregression objects. The app adds a candidate-model builder in Advanced > Compare models, fits the requested models, and then calls the same function.

App control | Default | Available options or input | What it does
--- | --- | --- | ---
Regression approach | `logit` | logistic, linear, Firth, log-binomial, Poisson, robust Poisson, negative binomial, Cox, parametric survival | Selects the gtregression fitting function used for every candidate.
Outcome | first eligible variable | one column | Common outcome for ordinary regression candidates.
Follow-up time, event | first eligible variables | numeric time and event columns | Replace outcome for Cox and parametric survival candidates.
Distribution | `weibull` | distributions supported by `surv_reg()` | Appears only for parametric survival regression.
Primary exposure to track | none | one predictor or none | Adds the estimate and percentage change from the first candidate.
Candidate name | generated model name | unique text | Becomes the visible model label in the comparison table and generated code.
Reported exposures | none | one or more predictors | Defines the candidate’s focal predictors. These are included in the fitted model.
Adjustment variables | none | zero or more predictors | Adds planned covariates to that candidate.
Interaction | none | two predictors already in the candidate | Adds one interaction while retaining its main effects.
Add candidate | two initially | two to six candidates | Adds another independently specified model.
Remove candidate | not applicable | candidates above the minimum | Removes the last candidate while retaining at least two.

Candidates are compared in their displayed order. Use meaningful unique names, place the baseline model first, and include the tracked primary exposure in every candidate. The app’s Code panel contains the complete `multi_reg()`, `cox_reg()`, or `surv_reg()` calls followed by `compare_models()`.

## Confounding, Interaction, and Mediation

### `identify_confounder()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`data` | required | data frame | Analysis dataset.
`outcome` | `NULL` | column name or `NULL` | Outcome for non-survival models.
`exposure` | required | one column name | Main exposure.
`potential_confounder` | required | one column name | Candidate screened as a potential confounder and effect modifier.
`approach` | `"logit"` | standard approaches plus `"cox"` and `"survreg"` | Model family.
`time`, `event` | `NULL` | column names or `NULL` | Required for survival approaches.
`distribution` | `"weibull"` | survival distributions | Parametric distribution for `approach = "survreg"`.
`method` | `"change"` | `"change"`, `"mh"`, `"both"` | Confounder assessment method.
`threshold` | `10` | number | Percent-change threshold for confounding.
`emm_threshold` | `10` | number | Percent-change threshold for effect-measure modification.
`emm_test` | `"interaction"` | `"interaction"`, `"both"`, `"estimate"` | How to assess effect modification.
`interaction_alpha` | `0.05` | number | P-value threshold for the candidate-only interaction screen; no other covariates are adjusted for.
`format` | `"flextable"` | `"flextable"`, `"gt"` | Output format.
`theme` | `"minimal"` | table theme preset | Table styling.

### `interaction_models()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`data` | required | data frame | Analysis dataset.
`outcome` | `NULL` | column name or `NULL` | Outcome for non-survival models.
`exposure` | required | one column name | Main exposure.
`covariates` | `NULL` | column names or `NULL` | Adjustment variables included in both models being compared.
`effect_modifier` | required | one column name | Candidate effect modifier.
`approach` | `"logit"` | standard approaches plus `"cox"` and `"survreg"` | Model family.
`time`, `event` | `NULL` | column names or `NULL` | Required for survival approaches.
`distribution` | `"weibull"` | survival distributions | Parametric distribution for `approach = "survreg"`.
`test` | `"LRT"` | `"LRT"`, `"Wald"` | Interaction test type.
`alpha` | `0.05` | number | Threshold used to flag evidence of interaction.
`verbose` | `FALSE` | `TRUE`, `FALSE` | Prints extra details when `TRUE`.
`format` | `"flextable"` | `"flextable"`, `"gt"`, `"tibble"` | Output format.

### `mediation_analysis()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`data` | required | data frame | Analysis dataset.
`exposure`, `mediator`, `outcome` | required | column names | Defines mediation pathway.
`covariates` | `NULL` | column names or `NULL` | Adjustment variables.
`mediator_approach` | `"linear"` | currently linear mediator model | Fits mediator model.
`outcome_approach` | `"linear"` | `"linear"`, `"logit"` | Fits continuous or binary outcome model.
`exposure_value`, `reference_value` | `NULL` | values or `NULL` | Defines exposure contrast.
`sims` | `1000` | whole number | Bootstrap replicates.
`conf_level` | `0.95` | number between 0 and 1 | Confidence level.
`seed` | `NULL` | number or `NULL` | Reproducibility seed.
`format` | `"flextable"` | `"flextable"`, `"gt"` | Output table engine.
`theme` | `"minimal"` | table theme preset | Table styling.

### `plot_mediation()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`mediation_object` | required | output from `mediation_analysis()` | Draws mediation path diagram.
`show_estimates` | `TRUE` | `TRUE`, `FALSE` | Displays effect estimates on the diagram.
`base_size` | `13` | number | Base font size.

## Merge, Modify, and Export

### `merge_tables()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`...` | required | gtregression table objects | Merges descriptive, crude, adjusted, Cox, survival, or other compatible tables.
`spanners` | `NULL` | character vector or `NULL` | Adds group headers above merged table blocks.
`theme` | `"minimal"` | table theme preset | Table styling.
`format` | `"flextable"` | `"flextable"`, `"gt"` | Output engine for the merged table, independent of the input-table formats.

For descriptive + crude + adjusted tables, keep binary-variable rows consistent. The recommended publication layout is `show_dichotomous = "all_levels"` in `descriptive_table()` and `show_ref = TRUE` in every regression table. Mixing these settings can add unexpected rows, and `merge_tables()` issues a warning that explains how to correct it.

The merged result carries the footnotes already present in each input table. Exact duplicate notes are shown once; table-specific notes, including an adjustment note from `multi_reg()`, are retained unchanged. Multivariable adjustment notes use the same display labels as the table body.

### `modify_table()`

Argument | Default | Available options or input | What it does
--- | --- | --- | ---
`gt_table` | required | gtregression table object | Table to modify.
`variable_labels` | `NULL` | named character vector or `NULL` | Relabels variables.
`level_labels` | `NULL` | named list of named character vectors or `NULL` | Relabels factor levels within each variable.
`header_labels` | `NULL` | named character vector or `NULL` | Relabels column headers.
`caption` | `NULL` | character or `NULL` | Adds table caption.
`bold_labels` | `TRUE` | `TRUE`, `FALSE` | Displays variable label rows in bold. This preserves the default gtregression hierarchy.
`bold_levels` | `FALSE` | `TRUE`, `FALSE` | Displays level rows in bold.
`italic_labels` | `FALSE` | `TRUE`, `FALSE` | Italicizes variable label rows.
`italic_levels` | `FALSE` | `TRUE`, `FALSE` | Italicizes factor level rows.
`remove_N` | `FALSE` | `TRUE`, `FALSE` | Removes displayed sample-size columns when present.
`remove_N_obs` | `FALSE` | `TRUE`, `FALSE` | Removes the complete-case `N = ... observations` footnote.
`remove_abbreviations` | `FALSE` | `TRUE`, `FALSE` | Removes abbreviation footnotes.
`remove_adjustment_note` | `FALSE` | `TRUE`, `FALSE` | Removes the automatic adjustment note; use `caveat` for customised wording.
`caveat` | `NULL` | character or `NULL` | Adds custom caveat or interpretation note.

### Save helpers

Function | Argument | Default | Available options or input | What it does
--- | --- | --- | --- | ---
`save_table()` | `filename` | `"table"` | path or file stem | Saves to a temporary location when no path is supplied.
`save_table()` | `format` | `"docx"` | `"docx"`, `"pdf"`, `"html"` | Table export type.
`save_table()` | `orientation` | `"auto"` | `"auto"`, `"portrait"`, `"landscape"` | Chooses page orientation; auto prefers landscape for wide tables.
`save_table()` | `fit_width` | `TRUE` | `TRUE`, `FALSE` | Attempts to fit table to page width.
`save_table()` | `font_size`, `min_font_size` | `9`, `8` | numbers | Font-size control with lower bound.
`save_docx()` | `tables`, `plots` | `NULL`, `NULL` | lists or objects | Builds a Word report from tables and plots.
`save_docx()` | `filename` | `"report.docx"` | path or file stem | Word output file.
`save_docx()` | `titles` | `NULL` | character vector or `NULL` | Section titles in the Word report.
`save_docx()` | `table_width`, `plot_width`, `plot_height` | `6.5`, `6`, `5` | numbers | Output sizing in inches.
`save_plot()` | `filename` | `"plot"` | path or file stem | Saves to a temporary location when no path is supplied.
`save_plot()` | `format` | `"png"` | `"png"`, `"pdf"`, `"jpg"` | Plot export type.
`save_plot()` | `width`, `height`, `dpi` | `8`, `6`, `300` | numbers | Plot canvas and resolution.

## Practical Defaults

Goal | Recommended option
--- | ---
Word manuscript table | Use the default `format = "flextable"`.
HTML/pkgdown output | Use `format = "gt"`.
Data checking or pipes | Use `format = "tibble"` when supported.
Compact binary regression tables | Use `show_ref = FALSE`; use `show_ref = TRUE` when reference rows are needed.
Compact binary descriptive tables | Use `show_dichotomous = "single_row"`; use `"all_levels"` for full level display.
KM plot with publication panels | Use `title_face = "plain"`, smaller `title_size`, `risk_table = FALSE`, and patchwork.
KM plot when survival remains high | Use `ylim = c(0.5, 1)` or another clinically meaningful range.
Forest plot x-axis overlap | Set `xlim` and `ticks_at` manually; increase `ci_col_width` if the CI drawing column is cramped.
Wide forest plot export | Use `save_forest()` with `auto_size = TRUE`, or manually increase `width`.