---
title: "Function Options"
description: "A quick reference for gtregression arguments, defaults, available choices, and what each option does."
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Function Options}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", eval = FALSE)
```

# 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

### `import_data()`

| Argument | Default | Available options or input | What it does |
|---|---:|---|---|
| `file` | required | existing file path | Dataset to import. |
| `format` | `NULL` | supported extension such as `"csv"`, `"xlsx"`, or `"dta"` | Overrides extension detection, including for extensionless Shiny upload paths. |
| `sheet` | `NULL` | Excel sheet name or number | Selects an Excel worksheet; the first sheet is used by default. |
| `header` | `TRUE` | `TRUE`, `FALSE` | Indicates whether a delimited file contains column names. |
| `sep` | `NULL` | delimiter such as `","`, `";"`, or `"\t"` | Overrides the format-aware delimiter for CSV, TSV, or TXT. |
| `na` | `c("", "NA")` | character vector | Values interpreted as missing. |
| `encoding` | `"UTF-8"` | valid text encoding | Encoding for delimited text files. |
| `name_repair` | `"check_unique"` | `"check_unique"`, `"unique"`, `"minimal"` | Preserves and checks names, repairs them reproducibly, or preserves them without validation. |
| `...` | none | reader-specific arguments | Passes additional options to the selected reader. |

```r
analysis_data <- import_data("data/analysis.csv")

stata_data <- import_data("data/analysis.dta")
```

### `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. |

```r
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. |

### `conditional_logit_reg()`

Use conditional logistic regression when cases and controls are linked through
matched sets. This is different from adding the matching variables to an
ordinary logistic regression model.

| Argument | Default | Available options or input | What it does |
|---|---:|---|---|
| `data` | required | data frame | Matched case-control dataset. |
| `outcome` | required | binary column | Identifies cases and controls. |
| `exposures` | required | column names | Variables for which matched odds ratios are reported. |
| `matched_set` | required | one column name | Links every case to its matched control or controls. |
| `adjust_for` | `NULL` | column names or `NULL` | Adds covariates to each exposure model. |
| `multivariable` | `FALSE` | `TRUE`, `FALSE` | Fits all exposures in one conditional logistic model. |
| `multivariate` | `NULL` | `TRUE`, `FALSE`, `NULL` | Convenience alias for `multivariable`. |
| `model_stats` | `FALSE` | `TRUE`, `FALSE` | Returns matched-set, case, control, N, AIC, and log-likelihood summaries. |
| `format` | `"flextable"` | `"flextable"`, `"gt"` | Output table engine. |
| `theme` | `"minimal"` | table theme preset | Table styling. |
| `show_ref` | `TRUE` | `TRUE`, `FALSE` | Controls categorical reference rows. Multilevel references remain visible. |

The matched-set identifier is used to condition the model and therefore does
not receive an odds ratio. Sets without both a case and a control are reported
and excluded because they provide no information to the conditional analysis.

### `multilevel_reg()`

Use this focused workflow when observations are clustered, such as patients
within clinics or pupils within schools, and a random-intercept model is
appropriate.

| Argument | Default | Available options or input | What it does |
|---|---:|---|---|
| `data` | required | data frame | Clustered analysis dataset. |
| `outcome` | required | one column name | Continuous outcome for `linear` or binary outcome for `logit`. |
| `exposures` | required | column names | Fixed-effect predictors reported in the table. |
| `group` | required | one grouping column | Defines clusters and receives a random intercept; it is not reported as a coefficient. |
| `adjust_for` | `NULL` | column names or `NULL` | Adds fixed-effect covariates without displaying them as table rows. |
| `approach` | `"linear"` | `"linear"`, `"logit"` | Fits a linear or binary logistic mixed-effects model. |
| `format` | `"flextable"` | `"flextable"`, `"gt"` | Selects the publication-table engine. |
| `theme` | `"minimal"` | table theme preset | Styles the output table. |
| `model_stats` | `FALSE` | `TRUE`, `FALSE` | Returns model fit, N, clusters, variance components, ICC, and singular-fit status. |
| `show_ref` | `TRUE` | `TRUE`, `FALSE` | Controls categorical reference rows. Multilevel references remain visible. |

Linear models report beta coefficients and an observed-scale ICC. Logistic
models report odds ratios and a latent-scale ICC calculated with residual
variance pi-squared over three. Fixed-effect p-values use a Wald normal
approximation. A singular-fit warning means the estimated random-intercept
variance is close to zero and the need for a multilevel model should be
reconsidered. This function intentionally supports one random intercept;
random slopes, crossed effects, and nested random-effects formulas should be
fitted using specialist workflows.

### `ordinal_reg()`

Use ordinal logistic regression when an outcome has three or more naturally
ordered categories, such as poor, fair, good, and excellent. The outcome must
be an ordered factor so the direction of the common odds ratio is explicit.

| Argument | Default | Available options or input | What it does |
|---|---:|---|---|
| `data` | required | data frame | Ordinal-outcome analysis dataset. |
| `outcome` | required | one ordered-factor column | Defines categories from lower to higher through its factor-level order. |
| `exposures` | required | column names | Predictors reported as common odds ratios. |
| `adjust_for` | `NULL` | column names or `NULL` | Adds covariates to each exposure model without reporting them. |
| `multivariable` | `FALSE` | `TRUE`, `FALSE` | Fits and reports all exposures in one joint model. |
| `multivariate` | `NULL` | `TRUE`, `FALSE`, `NULL` | Convenience alias for `multivariable`. |
| `assumption_test` | `TRUE` | `TRUE`, `FALSE` | Returns term-level likelihood-ratio checks of proportional odds. |
| `model_stats` | `FALSE` | `TRUE`, `FALSE` | Returns AIC, BIC, log-likelihood, N, outcome-level count, and convergence. |
| `format` | `"flextable"` | `"flextable"`, `"gt"` | Selects the publication-table engine. |
| `theme` | `"minimal"` | table theme preset | Styles the output table. |
| `show_ref` | `TRUE` | `TRUE`, `FALSE` | Controls categorical reference rows. Multilevel references remain visible. |

An odds ratio above one means greater odds of being in a higher outcome
category, assuming proportional odds. Inspect `$assumption_tests` before
interpreting the common odds ratio. A small p-value indicates that the effect
may differ across outcome thresholds; it does not mean that the predictor has
no association with the outcome.

### `multinomial_reg()`

Use multinomial logistic regression when an outcome has three or more
categories without a natural order, such as discharge destination. The first
factor level is the reference outcome category.

| Argument | Default | Available options or input | What it does |
|---|---:|---|---|
| `data` | required | data frame | Nominal-outcome analysis dataset. |
| `outcome` | required | one unordered-factor column | Defines the outcome; its first level is the reference category. |
| `exposures` | required | column names | Predictors reported in every outcome comparison. |
| `adjust_for` | `NULL` | column names or `NULL` | Adds covariates to each exposure model without reporting them. |
| `multivariable` | `FALSE` | `TRUE`, `FALSE` | Fits and reports all exposures in one joint model. |
| `multivariate` | `NULL` | `TRUE`, `FALSE`, `NULL` | Convenience alias for `multivariable`. |
| `model_stats` | `FALSE` | `TRUE`, `FALSE` | Returns AIC, BIC, log-likelihood, N, outcome-level count, and convergence. |
| `format` | `"flextable"` | `"flextable"`, `"gt"` | Selects the publication-table engine. |
| `theme` | `"minimal"` | table theme preset | Styles the output table. |
| `show_ref` | `TRUE` | `TRUE`, `FALSE` | Controls predictor reference rows. Multilevel references remain visible. |

The main table displays one column for each non-reference outcome compared with
the reference outcome. Use `relevel()` before fitting to change that reference.
For a focused graph, select a comparison from `$per_outcome`, for example
`plot_reg(result$per_outcome[["Rehabilitation"]])`. The same component can be
passed to `forest_df()` and `forest_reg()`.

### `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. |
| `baseline_strata` | `NULL` | categorical column names or `NULL` | Fits one Cox model with separate baseline hazards across strata and common HRs for the reported predictors. No HR is estimated for the strata variables. |
| `time_start` | `NULL` | numeric column name or `NULL` | Uses `Surv(time_start, time, event)` for delayed entry or start-stop observations. |
| `cluster` | `NULL` | column name or `NULL` | Calculates cluster-robust sandwich standard errors for correlated observations. |
| `weights` | `NULL` | non-negative numeric column name or `NULL` | Applies case weights. |
| `robust` | `NULL` | `TRUE`, `FALSE`, `NULL` | Controls robust sandwich variance; clustering implies robust variance. |
| `ties` | `"efron"` | `"efron"`, `"breslow"`, `"exact"` | Selects the tied-event method. |
| `control` | `NULL` | named list or `NULL` | Supplies selected `coxph.control()` settings. |
| `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` | `"both"` | `"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` | `"both"` | `"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. |

### `cuminc_plot()`

| Argument | Default | Available options or input | What it does |
|---|---:|---|---|
| `data` | required | data frame | Competing-risk dataset. |
| `time` | required | one numeric column | Follow-up time. |
| `event` | required | one column with distinct event codes | Identifies censoring, the event of interest, and competing events. |
| `event_of_interest` | required | one observed event code or label | Selects the cumulative-incidence function to plot. |
| `censor_code` | `0` | one observed code or label | Explicitly identifies censored observations. |
| `by` | `NULL` | one grouping column or `NULL` | Draws grouped curves and enables Gray's test. |
| `conf.int` | `TRUE` | `TRUE`, `FALSE` | Shows pointwise 95% confidence intervals. |
| `p_value` | `TRUE` | `TRUE`, `FALSE` | Displays Gray's test p-value for grouped curves. |
| `p_value_position` | `NULL` | numeric `c(x, y)` or `NULL` | Positions the Gray's test annotation. |
| `break_time_by` | `NULL` | positive number or `NULL` | Controls x-axis intervals. |
| `xlim`, `ylim` | `NULL` | numeric ranges or `NULL` | Controls visible plot limits. |
| `xlab`, `ylab` | `"Time"`, `"Cumulative incidence"` | character | Changes axis labels. |
| `title`, `subtitle`, `caption` | `NULL` | character or `NULL` | Adds publication figure text. |
| `legend_title` | `NULL` | character or `NULL` | Changes the group legend heading. |
| `legend_position` | `NULL` | `"bottom"`, `"top"`, `"right"`, `"left"`, `"none"` | Controls the legend location. |
| `palette` | `NULL` | colour vector or `NULL` | Changes curve and confidence-band colours. |
| `y_percent` | `TRUE` | `TRUE`, `FALSE` | Displays cumulative incidence as percentages or proportions. |
| `theme` | `"classic"` | `"classic"`, `"minimal"`, `"bw"`, `"light"` | Selects the plot theme. |
| `grid` | `FALSE` | `TRUE`, `FALSE` | Shows or hides major grid lines. |
| `base_size` | `13` | positive number | Controls the base font size. |

`cuminc_plot()` requires at least one competing event in addition to the event
of interest. A Kaplan-Meier failure curve is not a substitute because treating
competing events as ordinary censoring generally overestimates event risk.

```r
cuminc_plot(
  data_competing_risk,
  time = follow_up_months,
  event = outcome,
  event_of_interest = Relapse,
  censor_code = Censored,
  by = treatment
)
```

### `competing_risk_reg()`

| Argument | Default | Available options or input | What it does |
|---|---:|---|---|
| `data` | required | data frame | Competing-risk dataset. |
| `time` | required | one numeric column | Follow-up time. |
| `event` | required | one column with distinct event codes | Identifies censoring and every event type. |
| `event_of_interest` | required | one observed code or label | Selects the event modelled by Fine-Gray regression. |
| `exposures` | required | column names | Variables reported in the table. |
| `censor_code` | `0` | one observed code or label | Explicitly identifies censoring. |
| `adjust_for` | `NULL` | column names or `NULL` | Fits one adjusted model per exposure and reports the exposure SHR. |
| `multivariable` | `FALSE` | `TRUE`, `FALSE` | Fits one model containing and reporting all exposures. |
| `multivariate` | `NULL` | `TRUE`, `FALSE`, `NULL` | Alias for `multivariable`. |
| `format` | `"flextable"` | `"flextable"`, `"gt"` | Selects the publication-table engine. |
| `theme` | `"minimal"` | table theme preset | Styles the output table. |
| `model_stats` | `FALSE` | `TRUE`, `FALSE` | Returns N, event counts, pseudo-log-likelihood, and convergence. |
| `show_ref` | `TRUE` | `TRUE`, `FALSE` | Controls categorical reference rows. |

The reported SHR is a subdistribution hazard ratio for cumulative incidence.
It is not a cause-specific Cox hazard ratio. The output footnote names the event
of interest and confirms that competing events were retained.

```r
relapse_model <- competing_risk_reg(
  data_competing_risk,
  time = follow_up_months,
  event = outcome,
  event_of_interest = Relapse,
  censor_code = Censored,
  exposures = treatment,
  adjust_for = c(age, stage)
)
```

### `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. |
| `plot(check_ph(...))` | `model`, `term` | `NULL` | model/term name or position | Draws scaled Schoenfeld residual diagnostics. Select `model` when several Cox models were checked. |
| `plot_cox_survival()` | `model`, `newdata`, `by` | required, `NULL`, `NULL` | Cox model/result, profile data, categorical model variable | Draws adjusted Cox survival curves at supplied or representative covariate profiles. |

## 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 from the same model family | Plots crude and adjusted estimates side by side. Supports standard, Cox, parametric survival, Fine-Gray, conditional logistic, ordinal, and individual multinomial outcome objects. |
| `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`, `NULL`, `0.05` | number, `TRUE`, `FALSE`, `NULL`, number | Controls readability, reference rows, and highlighting. `NULL` inherits the source-table reference setting. |
| `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. |

The inputs do not need to be different table types. Two or more univariable or
multivariable tables can be combined for complete-case, best-case, worst-case,
or other sensitivity analyses. Use a clear `spanners` label for every model:

```r
merge_tables(
  primary_model,
  best_case_model,
  worst_case_model,
  spanners = c("Primary", "Best case", "Worst case")
)
```

Rows are matched using the underlying variable and category rather than their
position. A predictor absent from one scenario remains in the merged table with
blank cells for that scenario.

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`. |