Launch the App

Install and load gtregression, then run:

library(gtregression)

gtregression_app()

When the app is launched from RStudio, it opens in the RStudio Viewer when available. Outside RStudio, it opens in a browser during an interactive session.

You can pass arguments to shiny::runApp() through gtregression_app():

gtregression_app(launch.browser = TRUE)

To run the app without automatically opening a browser:

gtregression_app(launch.browser = FALSE)

Close the App Safely

The app keeps the R session busy while it is running. This is normal for Shiny.

Use the Close app button in the bottom-right corner of the app to stop the session cleanly. This avoids the confusing console behaviour that can happen when users stop the app manually from RStudio.

If R ever enters a Browse[1]> prompt after an interrupted app session, type:

Q

and press Enter.

App Dependencies

The app is launched only when gtregression_app() is called. This keeps the main package lightweight for users who only want command-line functions.

The app uses standard, trusted R packages:

If a dependency is missing, the app gives a message explaining what to install.

Recommended Workflow

The app is easiest to use when users follow a deliberate order:

1. Data: load a built-in dataset or import CSV, Excel, RDS, Stata, SPSS, or SAS data.
2. Data Prep: review the data only when changes are needed. The original data are active automatically; choose Use prepared data after applying changes.
3. Descriptive: inspect variables and create a baseline table.
4. Regression: run univariable models first.
5. Regression: reselect the clinically important variables and run the multivariable model.
6. Visualise & Export: merge descriptive, crude, and adjusted outputs.
7. Visualise & Export: create plot_reg() or forest_reg() previews.
8. Advanced: check model fit, compare models, assess confounding, and assess interaction where appropriate.
9. Code panels: copy the generated code into RStudio for reproducible saving and editing.

The app intentionally encourages users to run analyses one step at a time. For example, run univariable regression first, then decide which variables to keep, then run the multivariable model.

Core and Additional Options

The app does not use a global Simple/Advanced switch. Each tab presents its core workflow first and keeps uncommon controls in a local Additional options section. This keeps the interface calm without hiding package features behind a separate experience-level choice.

For example, the Descriptive tab keeps grouping, percentage, missing-value, binary-display, and numeric-statistic choices together. The Survival tab keeps the less-common time-break interval under Additional KM options.

Quick-Start Templates

The Data tab includes quick-start templates. These load labelled teaching datasets and preselect sensible variables across the app:

Templates are meant to help users learn the flow. After selecting a template, users can still change any variable, model, or display option.

Workflow Guide

The app shows a compact workflow guide near the top of the screen. It marks which steps have already been completed and gives one suggested action.

For example:

• after loading data, it suggests reviewing the preview and choosing an analysis;
• after a descriptive table, it suggests regression or survival analysis;
• after fitted models, it suggests visualisation, model checks, merge, or export;
• after plots or merged tables, it suggests code review or download/export.

This is deliberately beginner-friendly. Users do not need to know the whole package before starting; the app nudges them through a reproducible analysis.

Live Analysis Status and Preflight Checks

A status strip remains visible near the top of the app. It identifies the loaded dataset, whether modelling uses the original or prepared data, the current sample size, and the selected regression outcome and approach. This helps prevent an analysis being run on the wrong version of the data.

The Regression and Survival tabs also show a short preflight summary immediately above their run buttons. Review it before fitting a model. It confirms the outcome or survival variables, the number of exposures and adjustment variables, the modelling mode, and any selected categorical reference levels. If a required choice is missing, the summary states what must be selected next.

Select and Clear Variable Buttons

Several tabs include Select all and Clear all buttons beside long variable lists. These are available where users commonly need to choose multiple variables, including:

• descriptive table variables;
• regression exposures and adjustment variables;
• survival exposures and adjustment variables;
• advanced model-building variables;
• mediation covariates.

The buttons are role-aware. For example, after selecting an outcome, Select all for regression exposures avoids selecting the outcome as an exposure. In the survival tab, Select all avoids the selected time, event, and stratifier variables. This reduces accidental modelling errors while keeping variable selection fast for larger uploaded datasets.

Data Tab

Use the Data tab to start the analysis.

Users can:

• load a built-in gtregression teaching dataset;
• upload a CSV or Excel file;
• import an RDS file containing a data frame or tibble;
• import Stata (.dta), SPSS (.sav, .zsav, .por), or SAS (.sas7bdat, .xpt) data when haven is installed;
• preview the dataset;
• inspect a quick data summary;
• copy reusable data-loading code.

For uploaded CSV files, check:

• whether the file has a header;
• the separator: comma, semicolon, or tab.

For Excel files, optionally provide the sheet name or sheet number.

CSV controls are ignored for other formats, and the Excel sheet field is ignored unless an Excel file is selected. An RDS file must contain a data frame or tibble. Generated code records the appropriate readRDS(), readxl::read_excel(), or haven::read_*() call.

After loading data, check the preview before moving to the next tab. This helps catch common issues such as numeric variables imported as character, missing factor labels, or incorrect event coding.

Data Prep Tab

The Data Prep tab is an internal part of the gtregression app. It does not load or depend on the gtstats package. It provides a safe, visible sequence of common preparation steps while retaining the original imported dataset.

Users can rename and retain variables, set variable types and factor order, recode values, define or display missing values, filter rows, calculate new variables, and create grouped variables. Quick starts provide common recipes. Every applied change is added to a readable history and reusable R code.

When creating groups from a numeric variable, conditions include =, !=, >, >=, <, <=, an inclusive between range, and outside the range. Rules are checked from top to bottom and each row is assigned to the first rule it matches. The final group contains everyone not matched earlier. For example, < 35, then < 65, then everyone else produces groups for under 35, 35–64, and 65 or older. The preview shows the row count in every group before the change is applied.

The recovery controls are deliberately prominent:

• Undo reverses the latest change;
• Redo reapplies an undone change;
• Reset asks for confirmation before restoring the original data;
• Download prepared data saves the current prepared dataset;
• Download code saves the preparation recipe.

The original dataset is active immediately after loading, so users can run a table or model without visiting Data Prep. Select a different analysis dataset only when preparation is wanted:

• Use original data: subsequent analyses use the untouched imported data;
• Use prepared data: subsequent analyses use the current prepared version.

Data Prep is optional. Use Set display label when an internal variable name such as age should remain unchanged but publication output should show a clearer name such as Maternal age. Labels are reversible, are retained in prepared-data downloads, and are included in the reusable code.

For a categorical variable, the same page also shows its observed categories. Edit a category display label such as 0 to No or 1 to Yes there. This creates a labelled factor only when a category label changes, retaining a clean and reproducible analysis dataset from the outset.

If preparation is changed later, choose Use prepared data when those latest changes should be used for subsequent analyses. The generated workflow records that choice and includes the preparation operations when prepared data are selected.

Descriptive Tab

Use the Descriptive tab to create baseline tables with descriptive_table().

Choose Group by first: leave it as None for one overall table, or select the comparison variable before choosing the variables to summarise. Then choose column or row percentages, overall-column placement, missing-value display, and binary-category display to suit the reporting question.

Typical steps:

1. Select variables in Exposures.
2. Optionally select a grouping variable in By.
3. Choose the percentage denominator.
4. Decide whether to show an overall column.
5. Decide how missing values should be displayed.
6. Run the table.

Common settings:

desc_result <- descriptive_table(
  data = df,
  exposures = c("age", "lwt", "race", "smoke"),
  by = "low",
  percent = "column",
  show_overall = "last",
  show_missing = "ifany"
)

age = mean, lwt = median

descriptive_table(
  data = df,
  exposures = c("age", "lwt", "race", "smoke"),
  by = "low",
  statistic = c(age = "mean", lwt = "median")
)

Regression Tab

Use the Regression tab for standard regression tables:

• logistic regression;

Choose the outcome before the exposures. Run univariable models first, then move clinically justified variables into the multivariable model. The app does not select adjustment variables automatically: use the study question, a DAG, and clinical knowledge. - Firth logistic regression; - log-binomial regression; - Poisson regression; - robust Poisson regression; - negative binomial regression; - linear regression.

The recommended order is:

1. Choose the outcome.
2. Choose all candidate exposures.
3. Run Univariate analysis.
4. Review the crude results.
5. Reselect variables for the adjusted analysis.
6. Add adjustment variables where needed.
7. Run Multivariable analysis.
8. Copy the generated code into an R script.

Example:

uni_result <- uni_reg(
  data = df,
  outcome = "low",
  exposures = c("age", "lwt", "race", "smoke"),
  approach = "logit",
  show_ref = TRUE,
  format = "flextable"
)

multi_result <- multi_reg(
  data = df,
  outcome = "low",
  exposures = c("smoke", "ht", "ui"),
  adjust_for = c("age", "lwt", "race"),
  approach = "logit",
  show_ref = TRUE,
  format = "flextable"
)

analysis_data[["smoke"]] <- stats::relevel(
  factor(
    as.character(analysis_data[["smoke"]]),
    levels = c("No", "Yes")
  ),
  ref = "No"
)

Stratified Regression

The Stratified output repeats regression analyses within levels of a stratifier.

Use it when the clinical or epidemiological question is naturally stratified, for example:

• sex-specific associations;
• treatment subgroup analyses;
• hospital or site-level exploratory analyses;
• diabetes status subgroups.

Example:

stratified_result <- stratified_multi_reg(
  data = df,
  outcome = "low",
  exposures = c("smoke", "ht"),
  adjust_for = c("age", "lwt"),
  stratifier = "race",
  approach = "logit",
  show_ref = TRUE,
  format = "flextable"
)

Stratified outputs are useful for tables. For plots, plot_reg() can create quick presentation-style views. For publication forest outputs, use forest_df() and forest_reg() after checking that the display remains readable.

Survival Tab

Use the Survival tab for:

• Cox regression with cox_reg();

Choose Cox regression for hazard ratios when no baseline-hazard distribution is specified. Choose parametric survival regression when a distributional model and time-ratio interpretation are appropriate. Kaplan-Meier plots describe the observed curves and should not be used as a substitute for either fitted model. - parametric survival regression with surv_reg(); - Kaplan-Meier curves with km_plot(); - log-rank tests and survival summaries.

At the top of the workspace, choose Cox regression or Parametric survival. The app shows one model workflow at a time: Cox mode hides the distribution control, while Parametric survival mode asks for the Weibull, exponential, log-normal, or log-logistic distribution. The active mode also controls the run button, model result, and reusable code. Each method retains two independent result slots: Exposure models and Multivariable model. Running one does not replace the other. Both completed tables remain available as separate choices in Visualise & Export, including the merge-table menu, and in compatible Advanced tools.

For a complete GUI workflow, first leave Single multivariable model clear and run the exposure models. Then select the predictors for the joint model, check Single multivariable model, and run again. Review or download either result from its named subtab. This mirrors the two API calls below and makes it possible to merge the resulting crude/exposure and multivariable tables.

Typical Cox regression workflow:

cox_result <- cox_reg(
  data = df,
  time = "time",
  event = "status",
  exposures = c("trt", "celltype", "prior"),
  adjust_for = c("age", "karno"),
  show_ref = TRUE,
  format = "flextable"
)

For one full multivariable Cox model using all selected exposures:

cox_result <- cox_reg(
  data = df,
  time = "time",
  event = "status",
  exposures = c("trt", "celltype", "prior", "age", "karno"),
  multivariable = TRUE,
  show_ref = TRUE,
  format = "flextable"
)

Parametric survival regression follows the same app flow, with an additional distribution option:

survreg_result <- surv_reg(
  data = df,
  time = "time",
  event = "status",
  exposures = c("trt", "celltype", "prior"),
  adjust_for = c("age", "karno"),
  distribution = "weibull",
  show_ref = TRUE,
  format = "flextable"
)

Kaplan-Meier Plots

The app supports publication-friendly Kaplan-Meier plots:

• grouped or overall curves;
• shaded confidence intervals;
• risk tables;
• log-rank p-values;
• percent or probability y-axis;
• x-axis limits;
• y-axis limits;
• classic, minimal, black-and-white, light, or no theme;
• optional grid lines.

Example:

km_result <- km_plot(
  data = df,
  time = "time",
  event = "status",
  by = "trt",
  conf.int = TRUE,
  risk_table = TRUE,
  p_value = TRUE,
  y_percent = TRUE,
  ylim = c(50, 100),
  xlim = c(0, 800),
  break_time_by = 200,
  theme = "classic",
  grid = FALSE
)

Use y-axis limits when curves sit between high survival probabilities. For example, if survival stays between 80% and 100%, setting ylim = c(50, 100) can make group differences easier to see.

For multi-panel figures created with patchwork, use smaller titles or remove titles in the app-generated code and add labels later:

p1 <- km_plot(df, time = "time", event = "status", by = "trt",
              title = NULL, base_size = 10)
p2 <- km_plot(df, time = "time", event = "status", by = "celltype",
              title = NULL, base_size = 10)

p1 + p2

Visualise & Export Tab

The Visualise & Export tab turns fitted results into tables and figures. The top-level Session Code tab provides Download complete R script, which saves a single gtregression-session.R file for the current session. The script records the selected data source, any Data Prep changes, categorical reference levels, completed descriptive and modelling steps, visualisations, and export calls. Only analyses that have actually been run are included.

Open Session Code to review the same script before downloading it. The downloaded script begins with library(gtregression) and can be edited or rerun in RStudio as the reproducible record of the app workflow.

Choose the task from the menu across the top. The left panel then displays only the controls needed for that task, while the corresponding preview opens on the right. This keeps table merging, regression plots, forest plots, and model-fit diagnostics separate.

It can preview:

• merged tables;
• single-result plot_reg() outputs;
• combined crude and adjusted plot_reg_combine() outputs;
• single-result or combined crude and adjusted forest_reg() outputs;
• model fit plots.

It can also generate code for:

• plot_reg();
• plot_reg_combine();
• merge_tables();
• forest_df();
• forest_reg();
• save_table();
• save_plot();
• save_forest().

merged_table <- merge_tables(
  desc_result,
  uni_result,
  multi_result,
  spanners = c("Descriptive", "Crude", "Adjusted")
)

save_table(merged_table, filename = "merged_table.docx")

reg_plot <- plot_reg(
  multi_result,
  log_x = TRUE
)

save_plot(reg_plot, filename = "plot_reg.png", width = 9, height = 6)

combined_plot <- plot_reg_combine(
  uni_result,
  multi_result,
  log_x = TRUE
)

save_plot(
  combined_plot,
  filename = "plot_reg_combined.png",
  width = 10,
  height = 7
)

age = Maternal age
smoke: Yes = Smoker
estimate = Adjusted OR

forest_data <- forest_df(multi_result)

forest_plot <- forest_reg(
  forest_data,
  ci_col_width = 20
)

forest_both <- forest_df(
  uni_result,
  multi_result,
  desc = desc_result
)

forest_both_plot <- forest_reg(
  forest_both,
  ci_col_width = 24,
  xlim = c(0.25, 12),
  ticks_at = c(0.5, 1, 2, 4, 8)
)

save_forest(
  forest_both_plot,
  filename = "forest_reg_combined.pdf",
  width = 13,
  height = 9
)

forest_reg(
  forest_both,
  ci_col_width = 28,
  xlim = c(0.25, 20),
  ticks_at = c(0.5, 1, 2, 5, 10, 20)
)

save_forest(
  forest_both_plot,
  filename = "large_forest_plot.pdf",
  width = 16,
  height = 12
)

Advanced Tab

The Advanced tab supports model building, diagnostics, confounding, and interaction assessment without presenting every setting at once.

Choose one tool across the top of the page:

The left panel then shows only the controls needed by that tool. For Cox and parametric survival tools, Follow-up time and Event status replace the ordinary outcome selector. Survival distribution appears only for parametric survival regression.

After running a tool, the app opens the Output panel and provides:

• a publication-style table when the function returns one;
• concise guidance specific to that result;
• console messages and warnings;
• DOCX, RTF, and HTML downloads;
• a complete copyable command under Code.

In Compare models, the app fits each candidate model for you. Choose the outcome and regression approach once, then define two to six candidates. Each candidate has a meaningful name, reported exposures, adjustment variables, and an optional interaction. The app creates compatible multi_reg(), cox_reg(), or surv_reg() objects and passes them to compare_models(). The generated code shows every fitted model, so the comparison is fully reproducible in RStudio.

Use Primary exposure to track when the same exposure appears in every candidate. The comparison then shows how its estimate changes as variables are added. Variables selected as adjustment variables are included in the fitted model even though the app distinguishes them from the exposures being reported.

Collinearity requires an explicitly selected fitted multivariable model, because it is a property of predictors fitted together.

selected_models <- select_models(
  data = df,
  outcome = "low",
  exposures = c("age", "lwt", "smoke", "race"),
  approach = "logit",
  direction = "both",
  format = "flextable"
)

clinical <- multi_reg(
  data = df,
  outcome = "low",
  exposures = c("smoke", "age", "lwt"),
  approach = "logit"
)

expanded <- multi_reg(
  data = df,
  outcome = "low",
  exposures = c("smoke", "age", "lwt", "race", "ht"),
  approach = "logit"
)

comparison_table <- compare_models(
  clinical = clinical,
  expanded = expanded,
  primary_exposure = "smoke",
  format = "flextable"
)

treatment_only <- cox_reg(
  data = lung_data,
  time = time,
  event = status,
  exposures = trt
)

clinical_adjustment <- cox_reg(
  data = lung_data,
  time = time,
  event = status,
  exposures = trt,
  adjust_for = c(age, karno)
)

compare_models(
  `Treatment only` = treatment_only,
  `Clinical adjustment` = clinical_adjustment,
  primary_exposure = trt
)

confounder_check <- identify_confounder(
  data = df,
  outcome = "low",
  exposure = "smoke",
  potential_confounder = "race",
  approach = "logit",
  format = "flextable"
)

interaction_check <- interaction_models(
  data = df,
  outcome = "low",
  exposure = "smoke",
  effect_modifier = "race",
  covariates = c("age", "lwt"),
  approach = "logit",
  format = "flextable"
)

Mediation Tab

The Mediation tab runs mediation_analysis() and draws a mediation path diagram.

Typical workflow:

1. Choose exposure.
2. Choose mediator.
3. Choose outcome.
4. Add covariates.
5. Choose logit or linear outcome model.
6. Choose bootstrap replicates.
7. Run mediation analysis.
8. Review the table and diagram.
9. Copy the code.

Example:

mediation_result <- mediation_analysis(
  data = df,
  exposure = "obesity",
  mediator = "glucose",
  outcome = "diabetes",
  covariates = c("age", "blood_pressure", "pregnancies", "diabetes_pedigree"),
  outcome_approach = "logit",
  sims = 300,
  seed = 123,
  format = "flextable"
)

plot_mediation(mediation_result)

Mediation results require strong assumptions. Interpret them causally only when the design, DAG, temporal order, and no-unmeasured-confounding assumptions are defensible.

Saving Outputs

The app provides download buttons for tables and plots. For final publication work, copied code gives more control.

Tables:

save_table(merged_table, filename = "table_1.docx")
save_table(merged_table, filename = "table_1.rtf")
save_table(merged_table, filename = "table_1.html")

The app displays publication-ready tables with the same flextable engine used for DOCX and RTF export. Use HTML when you want a browser-friendly copy of the same table. Direct table PDF export is intentionally not shown in the app because flextable output is more reliable through DOCX, RTF, or HTML.

Plots:

save_plot(reg_plot, filename = "regression_plot.png", width = 9, height = 6)
save_plot(km_result, filename = "km_plot.png", width = 8, height = 6)

Forest plots:

save_forest(
  forest_both_plot,
  filename = "forest_plot.pdf",
  width = 13,
  height = 9
)

When a save function is called without a user-supplied destination, the package uses a temporary location. This is helpful for examples, testing, and CRAN-safe documentation.

Troubleshooting

install.packages("shiny")

gtregression_app()

save_forest(forest_plot, "forest_plot.pdf", width = 16, height = 10)

forest_reg(
  forest_data,
  xlim = c(0.25, 20),
  ticks_at = c(0.5, 1, 2, 5, 10, 20)
)

forest_reg(
  forest_data,
  ci_col_width = 28
)

save_forest(forest_plot, "forest_plot.pdf", width = 16, height = 10)

km_plot(
  data = df,
  time = "time",
  event = "status",
  by = "trt",
  y_percent = TRUE,
  ylim = c(50, 100)
)

km_plot(
  data = df,
  time = "time",
  event = "status",
  by = "trt",
  y_percent = FALSE,
  ylim = c(0.5, 1)
)

uni_result <- uni_reg(
  data = df,
  outcome = "low",
  exposures = exposures,
  approach = "logit",
  show_ref = TRUE
)

merge_tables(desc_result, uni_result, multi_result)

gtregression_app()

gtregression_app(launch.browser = FALSE)

Beginner Case Study: Birth Weight

This example mirrors a common app workflow.

library(gtregression)
library(dplyr)

data("data_birthwt", package = "gtregression")

birthwt_data <- data_birthwt |>
  mutate(
    race = factor(race, levels = c(1, 2, 3),
                  labels = c("White", "Black", "Other")),
    smoke = factor(smoke, levels = c(0, 1), labels = c("No", "Yes")),
    ht = factor(ht, levels = c(0, 1), labels = c("No", "Yes")),
    ui = factor(ui, levels = c(0, 1), labels = c("No", "Yes")),
    low = factor(low, levels = c(0, 1), labels = c("Normal BW", "Low BW")),
    ptl_cat = ifelse(ptl > 0, "Yes", "No"),
    ftv_cat = case_when(
      ftv == 0 ~ "None",
      ftv == 1 ~ "One",
      ftv >= 2 ~ "Two or more"
    ),
    ptl_cat = factor(ptl_cat, levels = c("No", "Yes")),
    ftv_cat = factor(ftv_cat, levels = c("None", "One", "Two or more"))
  )

exposures <- c("age", "lwt", "race", "smoke", "ht", "ui", "ptl_cat", "ftv_cat")

desc_result <- descriptive_table(
  data = birthwt_data,
  exposures = exposures,
  by = "low",
  percent = "column",
  show_overall = "last"
)

uni_result <- uni_reg(
  data = birthwt_data,
  outcome = "low",
  exposures = exposures,
  approach = "logit",
  show_ref = TRUE
)

multi_result <- multi_reg(
  data = birthwt_data,
  outcome = "low",
  exposures = c("smoke", "ht", "ui"),
  adjust_for = c("age", "lwt", "race", "ptl_cat", "ftv_cat"),
  approach = "logit",
  show_ref = TRUE
)

merged_table <- merge_tables(
  desc_result,
  uni_result,
  multi_result,
  spanners = c("Descriptive", "Crude", "Adjusted")
)

forest_data <- forest_df(uni_result, multi_result, desc = desc_result)

forest_plot <- forest_reg(
  forest_data,
  ci_col_width = 24,
  xlim = c(0.25, 12),
  ticks_at = c(0.5, 1, 2, 4, 8)
)

The app helps users build this workflow by clicking through tabs. The copied code gives them the same analysis in script form.

Best Practice

Use the app to learn, explore, and generate reproducible code. Use the copied code in RStudio for final analyses, manuscript tables, and final figure exports.