Type:	Package
Title:	Publication-Ready Summary Tables and Forest Plots
Version:	0.11.3
Description:	A comprehensive framework for descriptive statistics and regression analysis that produces publication-ready tables and forest plots. Provides a unified interface from descriptive statistics through multivariable modeling, with support for linear models, generalized linear models, Cox proportional hazards, and mixed-effects models. Also includes univariable screening, multivariate regression, model comparison, and export to multiple formats including PDF, DOCX, PPTX, 'LaTeX', HTML, and RTF. Built on 'data.table' for computational efficiency.
License:	GPL (≥ 3)
Encoding:	UTF-8
LazyData:	true
URL:	https://phmcc.github.io/summata/, https://github.com/phmcc/summata
BugReports:	https://github.com/phmcc/summata/issues
RoxygenNote:	7.3.3
Depends:	R (≥ 4.2.0)
Imports:	data.table, survival, ggplot2, stats, grDevices
Suggests:	MASS, coxme, flextable, knitr, lme4, MuMIn, officer, pROC, ragg, ResourceSelection, rmarkdown, stringr, systemfonts, tinytex, withr, xtable
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2026-03-04 01:18:49 UTC; paul
Author:	Paul Hsin-ti McClelland [aut, cre, cph]
Maintainer:	Paul Hsin-ti McClelland <PaulHMcClelland@protonmail.com>
Repository:	CRAN
Date/Publication:	2026-03-08 10:20:02 UTC

Add padding to exported table headers

Description

Adds LaTeX vertical spacing rules to column headers for proper vertical alignment in PDF/LaTeX exports.

Usage

add_header_padding(col_names)

Arguments

Value

Character vector with LaTeX padding rules added.

Add p-value column to result table

Description

Adds formatted p-value column to the survtable result.

Usage

add_pvalue_column(result, p_value, p_digits, marks = NULL)

Arguments

Value

Data.table with p-value column added.

Add raw statistics to row

Description

Appends raw numeric statistics to a data.table row for downstream processing. Used to preserve underlying values alongside formatted display strings.

Usage

add_raw_stats(row, col, stats, stat_type)

Arguments

Value

Modified row (by reference).

Add padding to exported table variables

Description

Inserts blank padding rows between variable groups in exported tables for improved visual separation.

Usage

add_variable_padding(df)

Arguments

Value

Data.table with padding rows inserted between variable groups.

Apply locale decimal mark to a sprintf-formatted string

Description

Replaces the period decimal mark in a sprintf-formatted string with the locale-appropriate decimal mark, and fixes negative-zero artefacts.

Usage

apply_decimal_mark(x, marks)

Arguments

Value

Character string with corrected decimal marks and no negative zeros.

Apply zebra stripes with proper variable group detection for indented tables

Description

Applies alternating background colors to variable groups in flextable objects. Handles both indented tables (detects groups by leading whitespace) and non-indented tables (uses pre-identified groups).

Usage

apply_zebra_stripes_ft(ft, df, var_groups)

Arguments

Value

Flextable object with zebra stripe formatting applied.

Create Forest Plot with Automatic Model Detection

Description

A convenience wrapper function that automatically detects the input type and routes to the appropriate specialized forest plot function. This eliminates the need to remember which forest function to call for different model types or analysis objects, making it ideal for exploratory analysis and rapid prototyping.

Usage

autoforest(x, data = NULL, title = NULL, ...)

Arguments

Details

This function provides a convenient wrapper around the specialized forest plot functions, automatically routing to the appropriate function based on the model class or result type. All parameters are passed through to the underlying function, so the full range of options remains available.

For model-specific advanced features, individual forest functions may be called directly.

Automatic Detection Logic:

The function uses the following priority order for detection:

1. uniscreen results: Detected by class "uniscreen_result" or presence of attributes outcome, predictors, model_type, and model_scope = "Univariable". Routes to uniforest().

2. multifit results: Detected by presence of attributes predictor, outcomes, model_type, and raw_data. Routes to multiforest().

3. Cox models: Classes coxph or clogit. Routes to coxforest().

4. GLM models: Class glm. Routes to glmforest().

5. Linear models: Class lm (but not glm). Routes to lmforest().

Value

A ggplot object containing the complete forest plot. The plot can be:

• Displayed directly: print(plot)

• Saved to file: ggsave("forest.pdf", plot, width = 12, height = 8)

• Further customized with ggplot2 functions

The returned object includes an attribute "rec_dims" accessible via attr(plot, "rec_dims"), which is a list containing:

width

Numeric. Recommended plot width in specified units

height

Numeric. Recommended plot height in specified units

These recommendations are automatically calculated based on the number of variables, text sizes, and layout parameters, and are printed to console if plot_width or plot_height are not specified.

See Also

glmforest for GLM forest plots, coxforest for Cox model forest plots, lmforest for linear model forest plots, uniforest for univariable screening forest plots, multiforest for multi-outcome forest plots, fit for single-model regression, fullfit for combined univariable/multivariable regression, uniscreen for univariable screening, multifit for multi-outcome analysis

Other visualization functions: coxforest(), glmforest(), lmforest(), multiforest(), uniforest()

Examples

data(clintrial)
data(clintrial_labels)
library(survival)

# Create example model
glm_model <- glm(surgery ~ age + sex + bmi + smoking,
                 family = binomial, data = clintrial)

# Example 1: Logistic regression model
p <- autoforest(glm_model, data = clintrial)
# Automatically detects GLM and routes to glmforest()



# Example 2: Cox proportional hazards model
cox_model <- coxph(Surv(os_months, os_status) ~ age + sex + treatment + stage,
                   data = clintrial)

plot2 <- autoforest(cox_model, data = clintrial)
# Automatically detects coxph and routes to coxforest()

# Example 3: Linear regression model
lm_model <- lm(biomarker_x ~ age + sex + bmi + treatment, data = clintrial)

plot3 <- autoforest(lm_model, data = clintrial)
# Automatically detects lm and routes to lmforest()

# Example 4: With custom labels and formatting options
plot4 <- autoforest(
    cox_model,
    data = clintrial,
    labels = clintrial_labels,
    title = "Prognostic Factors for Overall Survival",
    zebra_stripes = TRUE,
    indent_groups = TRUE
)

# Example 5: From fit() result - data and labels extracted automatically
fit_result <- fit(
    data = clintrial,
    outcome = "surgery",
    predictors = c("age", "sex", "bmi", "treatment"),
    labels = clintrial_labels
)

plot5 <- autoforest(fit_result)
# No need to pass data or labels - extracted from fit_result

# Save with recommended dimensions
dims <- attr(plot5, "rec_dims")
ggplot2::ggsave(file.path(tempdir(), "forest.pdf"),
                plot5, width = dims$width, height = dims$height)

Export Table with Automatic Format Detection

Description

Automatically detects the output format based on file extension and exports the table using the appropriate specialized function. Provides a unified interface for table export across all supported formats.

Usage

autotable(table, file, ...)

Arguments

Details

This function provides a convenient wrapper around format-specific export functions, automatically routing to the appropriate function based on the file extension. All parameters are passed through to the underlying function, so the full range of format-specific options remains available.

For format-specific advanced features, you may prefer to use the individual export functions directly:

• PDF exports support orientation, paper size, margins, and auto-sizing

• DOCX/PPTX/RTF support font customization and flextable formatting

• HTML supports CSS styling, responsive design, and custom themes

• TeX generates standalone LaTeX source with booktabs styling

Value

Invisibly returns the file path. Called primarily for its side effect of creating the output file.

See Also

table2pdf, table2docx, table2pptx, table2html, table2rtf, table2tex

Other export functions: table2docx(), table2html(), table2pdf(), table2pptx(), table2rtf(), table2tex()

Examples

# Create example data
data(clintrial)
data(clintrial_labels)
tbl <- desctable(clintrial, by = "treatment",
    variables = c("age", "sex"), labels = clintrial_labels)

# Auto-detect format from extension
if (requireNamespace("xtable", quietly = TRUE)) {
  autotable(tbl, file.path(tempdir(), "example.html"))
}


# Load example data
data(clintrial)
data(clintrial_labels)

# Create a regression table
results <- fit(
    data = clintrial,
    outcome = "os_status",
    predictors = c("age", "sex", "treatment"),
    labels = clintrial_labels
)

# Test that LaTeX can actually compile (needed for PDF export)
has_latex <- local({
  if (!nzchar(Sys.which("pdflatex"))) return(FALSE)
  test_tex <- file.path(tempdir(), "summata_latex_test.tex")
  writeLines(c("\\documentclass{article}",
               "\\usepackage{booktabs}",
               "\\begin{document}", "test",
               "\\end{document}"), test_tex)
  result <- tryCatch(
    system2("pdflatex", c("-interaction=nonstopmode",
            paste0("-output-directory=", tempdir()), test_tex),
            stdout = FALSE, stderr = FALSE),
    error = function(e) 1L)
  result == 0L
})

# Export automatically detects format from extension
autotable(results, file.path(tempdir(), "results.html"))  # Creates HTML file
autotable(results, file.path(tempdir(), "results.docx"))  # Creates Word document
autotable(results, file.path(tempdir(), "results.pptx"))  # Creates PowerPoint slide
autotable(results, file.path(tempdir(), "results.tex"))   # Creates LaTeX source
autotable(results, file.path(tempdir(), "results.rtf"))   # Creates RTF document
if (has_latex) {
  autotable(results, file.path(tempdir(), "results.pdf")) # Creates PDF
}

# Pass format-specific parameters
if (has_latex) {
  autotable(results, file.path(tempdir(), "results.pdf"), 
             orientation = "landscape",
             paper = "a4",
             font_size = 10)
}

autotable(results, file.path(tempdir(), "results.docx"),
           caption = "Table 1: Logistic Regression Results",
           font_family = "Times New Roman",
           condense_table = TRUE)

autotable(results, file.path(tempdir(), "results.html"),
           zebra_stripes = TRUE,
           dark_header = TRUE,
           bold_significant = TRUE)

# Works with any summata table output
desc <- desctable(clintrial,
                  by = "treatment",
                  variables = c("age", "sex", "bmi"))
if (has_latex) {
  autotable(desc, file.path(tempdir(), "demographics.pdf"))
}

comparison <- compfit(
    data = clintrial,
    outcome = "os_status",
    model_list = list(
        base = c("age", "sex"),
        full = c("age", "sex", "treatment", "stage")
    )
)
autotable(comparison, file.path(tempdir(), "model_comparison.docx"))

Bold significant p-values in DOCX

Description

Applies bold formatting to significant p-values in flextable objects by detecting values below threshold or "< 0.001" patterns.

Usage

bold_pvalues_ft(ft, df, p_threshold = 0.05)

Arguments

Value

Flextable object with significant p-values bolded.

Build row for failed model

Description

Creates a comparison table row with appropriate NA values for a model that failed to fit.

Usage

build_failed_model_row(model_name, n, n_predictors, model_type)

Arguments

Value

Data.table with single row of NA metrics and "Failed" convergence.

Build comparison row for successfully fitted model

Description

Creates a comparison table row with extracted metrics for a successfully fitted model.

Usage

build_model_row(
  model_name,
  n_predictors,
  converged,
  metrics,
  model_type,
  marks = NULL
)

Arguments

Value

Data.table with single row of formatted metrics.

Calculate scores for mixed-effects Cox models

Description

Computes component scores for coxme models based on concordance, pseudo-R-squared, and ICC metrics.

Usage

calculate_coxme_scores(comparison, weights, scores, n_models)

Arguments

Value

Updated scores list with calculated values and total.

Calculate table layout for forest plots

Description

Computes column widths and positions for the table portion of a forest plot. Determines spacing based on content width, font size, and desired table/forest proportion. Returns positions in log-scale units for plot coordinate system.

Usage

calculate_forest_layout(
  to_show_exp_clean,
  show_n,
  show_events,
  indent_groups,
  condense_table,
  effect_label,
  ref_label,
  font_size,
  table_width = 0.6,
  rangeb,
  center_padding
)

Arguments

Value

List with table_width, forest_width, positions, rangeplot_start, total_width, and effect_abbrev components.

Calculate scores for generalized linear mixed-effects models

Description

Computes component scores for glmer models based on concordance, marginal R-squared, and ICC metrics.

Usage

calculate_glmer_scores(comparison, weights, scores, n_models)

Arguments

Value

Updated scores list with calculated values and total.

Calculate scores for linear mixed-effects models

Description

Computes component scores for lmer models based on marginal R-squared, conditional R-squared, and ICC metrics.

Usage

calculate_lmer_scores(comparison, weights, scores, n_models)

Arguments

Value

Updated scores list with calculated values and total.

Calculate Composite Mean Scores (CMS) for model comparison

Description

Computes composite Score based on weighted combination of model quality metrics. Weights vary by model type to reflect academic consensus on important metrics for each model class.

Usage

calculate_model_scores(comparison, model_type, scoring_weights = NULL)

Arguments

Value

Data.table with CMS column added, sorted by score.

Calculate table layout for multiforest plots

Description

Computes column widths and positions for the table portion of a multiforest plot.

Usage

calculate_multiforest_layout(
  to_show_exp_clean,
  show_n,
  show_events,
  indent_predictor,
  show_predictor = TRUE,
  effect_abbrev,
  font_size,
  table_width = 0.6,
  rangeb,
  center_padding,
  ci_pct = 95
)

Calculate table width based on paper size and orientation

Description

Computes usable table width in inches based on paper dimensions and orientation, accounting for standard 1-inch margins.

Usage

calculate_table_width(paper, orientation)

Arguments

Value

Numeric usable width in inches.

Calculate table layout for uniforest plots

Description

Internal function to determine column positions and widths for forest plot table section. Positions are calculated in the same units as the data (log scale for OR/HR/RR, linear for coefficients).

Usage

calculate_uniforest_layout(
  to_show_exp_clean,
  show_n,
  show_events,
  indent_groups,
  table_width,
  center_padding,
  effect_abbrev,
  font_size,
  log_scale,
  rangeb,
  ci_pct = 95
)

Arguments

Value

List with column positions, widths, and layout parameters.

Check model convergence

Description

Checks convergence status for various model types including standard regression models and mixed-effects models.

Usage

check_convergence(model)

Arguments

Value

Character string: "Yes", "No", "Suspect", or "Failed"

Check LaTeX installation

Description

Verifies that a LaTeX distribution (pdflatex or xelatex) is available on the system for PDF compilation.

Usage

check_latex()

Value

Logical TRUE if LaTeX is available, FALSE otherwise.

Check required packages for model type

Description

Verifies that necessary packages are installed for the specified model type. Stops with informative error if required packages are missing.

Usage

check_required_packages(model_type)

Arguments

Value

NULL (invisibly). Stops execution if packages missing.

Simulated Clinical Trial Dataset

Description

A simulated dataset from a hypothetical multi-center oncology clinical trial comparing two experimental drugs against control. Designed to demonstrate the full capabilities of descriptive and regression analysis functions.

Usage

clintrial

Format

A data frame with 850 observations and 32 variables:

patient_id

Unique patient identifier (character)

age

Age at enrollment in years (numeric: 18-90)

sex

Biological sex (factor: Female, Male)

race

Self-reported race (factor: White, Black, Asian, Other)

ethnicity

Hispanic ethnicity (factor: Non-Hispanic, Hispanic)

bmi

Body mass index in kg/m^2 (numeric)

smoking

Smoking history (factor: Never, Former, Current)

hypertension

Hypertension diagnosis (factor: No, Yes)

diabetes

Diabetes diagnosis (factor: No, Yes)

ecog

ECOG performance status (factor: 0, 1, 2, 3)

creatinine

Baseline creatinine in mg/dL (numeric)

hemoglobin

Baseline hemoglobin in g/dL (numeric)

biomarker_x

Serum biomarker A in ng/mL (numeric)

biomarker_y

Serum biomarker B in U/L (numeric)

site

Enrolling site (factor: Site Alpha through Site Kappa)

grade

Tumor grade (factor: Well/Moderately/Poorly differentiated)

stage

Disease stage at diagnosis (factor: I, II, III, IV)

treatment

Randomized treatment (factor: Control, Drug A, Drug B)

surgery

Surgical resection (factor: No, Yes)

any_complication

Any post-operative complication (factor: No, Yes)

wound_infection

Post-operative wound infection (factor: No, Yes)

icu_admission

ICU admission required (factor: No, Yes)

readmission_30d

Hospital readmission within 30 days (factor: No, Yes)

pain_score

Pain score at discharge (numeric: 0-10)

recovery_days

Days to functional recovery (numeric)

los_days

Hospital length of stay in days (numeric)

ae_count

Adverse event count (integer). Overdispersed count suitable for negative binomial or quasipoisson regression.

fu_count

Follow-up visit count (integer). Equidispersed count suitable for standard Poisson regression.

pfs_months

Progression-Free Survival Time (months)

pfs_status

Progression or Death Event

os_months

Overall survival time in months (numeric)

os_status

Death indicator (numeric: 0=censored, 1=death)

Details

This dataset includes realistic correlations between variables: - Survival is worse with higher stage, ECOG, age, and biomarker_x - Treatment effects show Drug B > Drug A > Control - ae_count is overdispersed (variance > mean) for negative binomial demos - fu_count is equidispersed (variance \approx mean) for Poisson demos - Approximately 2% of values are missing at random - Median follow-up is approximately 30 months

Source

Simulated data for demonstration purposes

See Also

Other sample data: clintrial_labels

Examples

data(clintrial)
data(clintrial_labels)

# Descriptive statistics by treatment arm
desctable(clintrial,
        by = "treatment", 
        variables = c("age", "sex", "stage", "ecog", 
                     "biomarker_x", "Surv(os_months, os_status)"),
        labels = clintrial_labels)


# Poisson regression for equidispersed counts
fit(clintrial,
    outcome = "fu_count",
    predictors = c("age", "stage", "treatment"),
    model_type = "glm",
    family = "poisson",
    labels = clintrial_labels)

# Negative binomial for overdispersed counts
fit(clintrial,
    outcome = "ae_count",
    predictors = c("age", "treatment", "diabetes"),
    model_type = "negbin",
    labels = clintrial_labels)

# Complete analysis pipeline
fullfit(clintrial,
        outcome = "Surv(os_months, os_status)",
        predictors = c("age", "sex", "stage", "grade", "ecog",
                      "smoking", "biomarker_x", "biomarker_y", "treatment"),
        method = "screen",
        p_threshold = 0.20,
        model_type = "coxph",
        labels = clintrial_labels)

        

Variable Labels for Clinical Trial Dataset

Description

A named character vector providing descriptive labels for all variables in the clinical_trial dataset. Use with labels parameter in functions.

Usage

clintrial_labels

Format

Named character vector with 24 elements

See Also

clintrial

Other sample data: clintrial

Combine coefficient tables from multiple models

Description

Merges coefficient tables from multiple fitted models into a single data.table with a Model identifier column.

Usage

combine_coefficient_tables(coef_list, model_names)

Arguments

Value

Combined data.table with Model column, or NULL if empty.

Combine multivariate results

Description

Internal helper to combine unadjusted and/or adjusted results from multiple outcomes into a single data.table.

Usage

combine_multifit_results(all_results, columns)

Arguments

Value

Combined data.table.

Compare Multiple Regression Models

Description

Fits multiple regression models and provides a comprehensive comparison table with model quality metrics, convergence diagnostics, and selection guidance. Computes a composite score combining multiple quality metrics to facilitate rapid model comparison and selection.

Usage

compfit(
  data,
  outcome,
  model_list,
  model_names = NULL,
  interactions_list = NULL,
  random = NULL,
  model_type = "auto",
  family = "binomial",
  conf_level = 0.95,
  p_digits = 3,
  include_coefficients = FALSE,
  scoring_weights = NULL,
  labels = NULL,
  number_format = NULL,
  verbose = NULL,
  ...
)

Arguments

    options(summata.number_format = "eu")
  

Details

This function fits all specified models and computes comprehensive quality metrics for comparison. It generates a Composite Model Score (CMS) that combines multiple metrics: lower AIC/BIC (information criteria), higher concordance (discrimination), and model convergence status.

For GLMs, McFadden's pseudo-R-squared is calculated as 1 - (logLik/logLik_null). For survival models, the global p-value comes from the log-rank test.

Models that fail to converge are flagged and penalized in the composite score.

Interaction Terms:

When interactions_list is provided, each element specifies the interaction terms for the corresponding model in model_list. This is particularly useful for testing whether adding interactions improves model fit:

• Use NULL for models without interactions

• Specify interactions using colon notation: c("age:treatment", "sex:stage")

• Main effects for all variables in interactions must be in the predictor list

• Common pattern: Compare main effects model vs model with interactions

Scoring weights can be customized based on model type:

• GLM: "convergence", "aic", "concordance", "pseudo_r2", "brier"

• Cox: "convergence", "aic", "concordance", "global_p"

• Linear: "convergence", "aic", "pseudo_r2", "rmse"

Default weights emphasize discrimination (concordance) and model fit (AIC).

The composite score is designed as a tool to quickly rank models by their quality metrics. It should be used alongside traditional model selection criteria rather than as a definitive model selection method.

Value

A data.table with class "compfit_result" containing:

Model

Model name/identifier

CMS

Composite Model Score for model selection (higher is better)

N

Sample size

Events

Number of events (for survival/logistic)

Predictors

Number of predictors

Converged

Whether model converged properly

AIC

Akaike Information Criterion

BIC

Bayesian Information Criterion

R^2 / Pseudo-R^2

McFadden pseudo-R-squared (GLM)

Concordance

C-statistic (logistic/survival)

Brier Score

Brier accuracy score (logistic)

Global p

Overall model p-value

Attributes include:

models

List of fitted model objects

coefficients

Coefficient comparison table (if requested)

best_model

Name of recommended model

See Also

fit for individual model fitting, fullfit for automated variable selection, table2pdf for exporting results

Other regression functions: fit(), fullfit(), multifit(), print.compfit_result(), print.fit_result(), print.fullfit_result(), print.multifit_result(), print.uniscreen_result(), uniscreen()

Examples

# Load example data
data(clintrial)
data(clintrial_labels)

# Example 1: Compare nested logistic regression models
models <- list(
    base = c("age", "sex"),
    clinical = c("age", "sex", "smoking", "diabetes"),
    full = c("age", "sex", "smoking", "diabetes", "stage", "ecog")
)

comparison <- compfit(
    data = clintrial,
    outcome = "os_status",
    model_list = models,
    model_names = c("Base", "Clinical", "Full")
)
comparison



# Example 2: Compare Cox survival models
library(survival)
surv_models <- list(
    simple = c("age", "sex"),
    clinical = c("age", "sex", "stage", "grade")
)

surv_comparison <- compfit(
    data = clintrial,
    outcome = "Surv(os_months, os_status)",
    model_list = surv_models,
    model_type = "coxph"
)
surv_comparison

# Example 3: Test effect of adding interaction terms
interaction_models <- list(
    main = c("age", "treatment", "sex"),
    interact = c("age", "treatment", "sex")
)

interaction_comp <- compfit(
    data = clintrial,
    outcome = "os_status",
    model_list = interaction_models,
    model_names = c("Main Effects", "With Interaction"),
    interactions_list = list(
        NULL,
        c("treatment:sex")
    )
)
interaction_comp

# Example 4: Include coefficient comparison table
detailed <- compfit(
    data = clintrial,
    outcome = "os_status",
    model_list = models,
    include_coefficients = TRUE,
    labels = clintrial_labels
)

# Access coefficient table
coef_table <- attr(detailed, "coefficients")
coef_table

# Example 5: Access fitted model objects
fitted_models <- attr(comparison, "models")
names(fitted_models)

# Example 6: Get best model recommendation
best <- attr(comparison, "best_model")
cat("Recommended model:", best, "\n")

Condense quantitative variable rows only

Description

Collapses multi-row continuous and survival variables into single rows while preserving all categorical variable rows (including binary). Only applies to descriptive tables from desctable().

Usage

condense_quantitative_rows(df, indent_groups = TRUE)

Arguments

Value

A data.table with condensed continuous/survival rows

Condense table rows for more compact display

Description

Collapses multi-row variables into single rows for compact tables. Continuous variables show only the first statistic row, binary categorical variables show only the non-reference category, and survival variables show only the median row.

Usage

condense_table_rows(df, indent_groups = TRUE)

Arguments

Value

Data.table with condensed rows.

Convert between units

Description

Converts measurements between different unit systems commonly used in graphics (inches, centimeters, millimeters, pixels, points).

Usage

convert_units(value, from = "in", to = "in", dpi = 96)

Arguments

Value

Numeric value in target units.

Create Forest Plot for Cox Proportional Hazards Models

Description

Generates a publication-ready forest plot that combines a formatted data table with a graphical representation of hazard ratios from a Cox proportional hazards survival model. The plot integrates variable names, group levels, sample sizes, event counts, hazard ratios with confidence intervals, p-values, and model diagnostics in a single comprehensive visualization designed for manuscripts and presentations.

Usage

coxforest(
  x,
  data = NULL,
  title = "Cox Proportional Hazards Model",
  effect_label = "Hazard Ratio",
  digits = 2,
  p_digits = 3,
  conf_level = 0.95,
  font_size = 1,
  annot_size = 3.88,
  header_size = 5.82,
  title_size = 23.28,
  plot_width = NULL,
  plot_height = NULL,
  table_width = 0.6,
  show_n = TRUE,
  show_events = TRUE,
  indent_groups = FALSE,
  condense_table = FALSE,
  bold_variables = FALSE,
  center_padding = 4,
  zebra_stripes = TRUE,
  ref_label = "reference",
  labels = NULL,
  color = "#8A61D8",
  qc_footer = TRUE,
  units = "in",
  number_format = NULL
)

Arguments

    options(summata.number_format = "eu")
  

Details

Survival-Specific Features:

The Cox forest plot includes several survival analysis-specific components:

• Event counts: Number of events (deaths, failures) shown for each predictor category, critical for assessing statistical power

• Hazard ratios: Always exponentiated coefficients (never raw), interpreted as the multiplicative change in hazard

• Log scale: Forest plot uses log scale for HR (reference line at 1)

• Model diagnostics: Includes concordance (C-index), global log-rank test p-value, and AIC

Plot Components:

1. Title: Centered at top

2. Data Table (left): Contains:

   • Variable and Group columns

   • n: Sample sizes by group

   • Events: Event counts by group (critical for survival)

   • aHR (95% CI); p-value: Adjusted hazard ratios with CIs and p-values

3. Forest Plot (right):

   • Point estimates (squares sized by sample size)

   • 95% confidence intervals

   • Reference line at HR = 1

   • Log scale for hazard ratios

4. Model Statistics (footer):

   • Events analyzed (with percentage of total)

   • Global log-rank test p-value

   • Concordance (C-index) with standard error

   • AIC

Interpreting Hazard Ratios:

• HR = 1: No effect on hazard (reference)

• HR > 1: Increased hazard (worse survival)

• HR < 1: Decreased hazard (better survival)

• Example: HR = 2.0 means twice the hazard of the event at any time

Event Counts:

The "Events" column is particularly important in survival analysis:

• Indicates the number of actual events (not censored observations) in each group

• Essential for assessing statistical power

• Categories with very few events may have unreliable HR estimates

• The footer shows total events analyzed and percentage of all events in the original data

Concordance (C-index):

The concordance statistic displayed in the footer indicates discrimination:

• Range: 0.5 to 1.0

• 0.5 = random prediction (coin flip)

• 0.7-0.8 = acceptable discrimination

• > 0.8 = excellent discrimination

• Standard error provided for confidence interval calculation

Global Log-Rank Test:

The global p-value tests the null hypothesis that all coefficients are zero:

• Significant p-value (< 0.05) indicates the model as a whole predicts survival

• Non-significant global test doesn't preclude significant individual predictors

• Based on the score (log-rank) test

Stratification and Clustering:

If the model includes stratification (strata()) or clustering (cluster()):

• Stratified variables are not shown in the forest plot (they don't have HRs)

• Clustering affects standard errors but not point estimates

• Both are handled automatically by the function

Proportional Hazards Assumption:

The forest plot assumes proportional hazards (constant HR over time). Users should verify this assumption using:

• cox.zph(model) for testing

• Stratification for variables violating the assumption

• Time-dependent coefficients if needed

Value

A ggplot object containing the complete forest plot. The plot can be:

• Displayed directly: print(plot)

• Saved to file: ggsave("forest.pdf", plot, width = 12, height = 8)

• Further customized with ggplot2 functions

The returned object includes an attribute "rec_dims" accessible via attr(plot, "rec_dims"), which is a list containing:

width

Numeric. Recommended plot width in specified units

height

Numeric. Recommended plot height in specified units

These recommendations are automatically calculated based on the number of variables, text sizes, and layout parameters, and are printed to console if plot_width or plot_height are not specified.

See Also

autoforest for automatic model detection, glmforest for logistic/GLM forest plots, lmforest for linear model forest plots, uniforest for univariable screening forest plots, multiforest for multi-outcome forest plots, coxph for fitting Cox models, fit for regression modeling

Other visualization functions: autoforest(), glmforest(), lmforest(), multiforest(), uniforest()

Examples

data(clintrial)
data(clintrial_labels)
library(survival)

# Create example model
model1 <- coxph(
    survival::Surv(os_months, os_status) ~ age + sex + treatment,
    data = clintrial)

# Example 1: Basic Cox model forest plot
p <- coxforest(model1, data = clintrial)



old_width <- options(width = 180)

# Example 2: With custom labels and title
plot2 <- coxforest(
    x = model1,
    data = clintrial,
    title = "Prognostic Factors for Overall Survival",
    labels = clintrial_labels
)

# Example 3: Comprehensive model with indented layout
model3 <- coxph(
    Surv(os_months, os_status) ~ age + sex + bmi + smoking + 
        treatment + stage + grade,
    data = clintrial
)

plot3 <- coxforest(
    x = model3,
    data = clintrial,
    labels = clintrial_labels,
    indent_groups = TRUE,
    zebra_stripes = TRUE
)

# Example 4: Condensed layout for many binary predictors
model4 <- coxph(
    Surv(os_months, os_status) ~ age + sex + smoking + 
        hypertension + diabetes + surgery,
    data = clintrial
)

plot4 <- coxforest(
    x = model4,
    data = clintrial,
    condense_table = TRUE,
    labels = clintrial_labels
)

# Example 5: Stratified Cox model
model5 <- coxph(
    Surv(os_months, os_status) ~ age + sex + treatment + strata(site),
    data = clintrial
)

plot5 <- coxforest(
    x = model5,
    data = clintrial,
    title = "Stratified by Study Site",
    labels = clintrial_labels
)

# Example 6: Save with recommended dimensions
dims <- attr(plot5, "rec_dims")
ggplot2::ggsave(file.path(tempdir(), "survival_forest.pdf"),
                plot5, width = dims$width, height = dims$height)

options(old_width)

Create Publication-Ready Descriptive Statistics Tables

Description

Generates comprehensive descriptive statistics tables with automatic variable type detection, group comparisons, and appropriate statistical testing. This function is designed to create "Table 1"-style summaries commonly used in clinical and epidemiological research, with full support for continuous, categorical, and time-to-event variables.

Usage

desctable(
  data,
  by = NULL,
  variables,
  stats_continuous = c("median_iqr"),
  stats_categorical = "n_percent",
  digits = 1,
  p_digits = 3,
  conf_level = 0.95,
  p_per_stat = FALSE,
  na_include = FALSE,
  na_label = "Unknown",
  na_percent = FALSE,
  test = TRUE,
  test_continuous = "auto",
  test_categorical = "auto",
  total = TRUE,
  total_label = "Total",
  labels = NULL,
  number_format = NULL,
  ...
)

Arguments

    options(summata.number_format = "eu")
  

Details

Variable Type Detection:

The function automatically detects variable types and applies appropriate summaries:

• Continuous: Numeric variables (integer or double) receive statistics specified in stats_continuous

• Categorical: Character, factor, or logical variables receive frequency counts and percentages

• Time-to-Event: Variables specified as Surv(time, event) display median survival with confidence intervals (level controlled by conf_level)

Statistical Testing:

When test = TRUE and by is specified:

• Continuous with "auto": Parametric tests (t-test, ANOVA) for mean-based statistics; non-parametric tests (Wilcoxon, Kruskal-Wallis) for median-based statistics

• Categorical with "auto": Fisher exact test when any expected cell frequency < 5; \chi^2 test otherwise

• Survival: Log-rank test for comparing survival curves

• Range statistics: No p-value computed (ranges are descriptive)

Missing Data Handling:

Missing values are handled differently by variable type:

• Continuous: NAs excluded from calculations; optionally shown as count when na_include = TRUE

• Categorical: NAs can be included as a category when na_include = TRUE. The na_percent parameter controls whether percentages are calculated with or without NAs in the denominator

• Survival: NAs in time or event excluded from analysis

Formatting Conventions:

All numeric output respects the number_format parameter. Separators within ranges and confidence intervals adapt automatically to avoid ambiguity:

• Mean \pm SD: "45.2 \eqn{\pm} 12.3" (US) or "45,2 \eqn{\pm} 12,3" (EU)

• Median [IQR]: "38.0 [28.0-52.0]" (US) or "38,0 [28,0-52,0]" (EU, en-dash separator)

• Range: "18.0-75.0" (positive, US), "-5.0 to 10.0" (when bounds are negative)

• Survival: "24.5 (21.2-28.9)" (US) or "24,5 (21,2-28,9)" (EU)

• Counts \ge 1000: "1,234" (US) or "1.234" (EU)

• p-values: "< 0.001" (US) or "< 0,001" (EU)

Value

A data.table with S3 class "desctable" containing formatted descriptive statistics. The table structure includes:

Variable

Variable name or label (from labels)

Group

For continuous variables: statistic type (e.g., "Mean \pm SD", "Median [IQR]"). For categorical variables: category level. Empty for variable name rows.

Total

Statistics for the total sample (if total = TRUE)

Group columns

Statistics for each group level (when by is specified). Column names match group levels.

p-value

Formatted p-values from statistical tests (when test = TRUE and by is specified)

The first row always shows sample sizes for each column. All numeric output (counts, statistics, p-values) respects the number_format setting for locale-appropriate formatting.

The returned object includes the following attributes accessible via attr():

raw_data

A data.table containing unformatted numeric values suitable for further statistical analysis or custom formatting. Includes additional columns for standard deviations, quartiles, etc.

by_variable

The grouping variable name used (value of by)

variables

The variables analyzed (value of variables)

See Also

survtable for detailed survival summary tables, fit for regression modeling, table2pdf for PDF export, table2docx for Word export, table2html for HTML export

Other descriptive functions: print.survtable(), survtable()

Examples

# Load example clinical trial data
data(clintrial)

# Example 1: Basic descriptive table without grouping
desctable(clintrial,
        variables = c("age", "sex", "bmi"))



# Example 2: Grouped comparison with default tests
desctable(clintrial,
        by = "treatment",
        variables = c("age", "sex", "race", "bmi"))

# Example 3: Customize continuous statistics
desctable(clintrial,
        by = "treatment",
        variables = c("age", "bmi", "creatinine"),
        stats_continuous = c("median_iqr", "range"))

# Example 4: Change categorical display format
desctable(clintrial,
        by = "treatment",
        variables = c("sex", "race", "smoking"),
        stats_categorical = "n")  # Show counts only

# Example 5: Include missing values
desctable(clintrial,
        by = "treatment",
        variables = c("age", "smoking", "hypertension"),
        na_include = TRUE,
        na_label = "Missing")

# Example 6: Disable statistical testing
desctable(clintrial,
        by = "treatment",
        variables = c("age", "sex", "bmi"),
        test = FALSE)

# Example 7: Force specific tests
desctable(clintrial,
        by = "surgery",
        variables = c("age", "sex"),
        test_continuous = "t",      # t-test instead of auto
        test_categorical = "fisher") # Fisher test instead of auto

# Example 8: Adjust decimal places
desctable(clintrial,
        by = "treatment",
        variables = c("age", "bmi"),
        digits = 2,    # 2 decimals for continuous
        p_digits = 4)  # 4 decimals for p-values

# Example 9: Custom variable labels
labels <- c(
    age = "Age (years)",
    sex = "Sex",
    bmi = "Body Mass Index (kg/m\u00b2)",
    treatment = "Treatment Arm"
)

desctable(clintrial,
        by = "treatment",
        variables = c("age", "sex", "bmi"),
        labels = labels)

# Example 10: Position total column last
desctable(clintrial,
        by = "treatment",
        variables = c("age", "sex"),
        total = "last")

# Example 11: Exclude total column
desctable(clintrial,
        by = "treatment",
        variables = c("age", "sex"),
        total = FALSE)

# Example 12: Survival analysis
desctable(clintrial,
        by = "treatment",
        variables = "Surv(os_months, os_status)")

# Example 13: Multiple survival endpoints
desctable(clintrial,
        by = "treatment",
        variables = c(
            "Surv(pfs_months, pfs_status)",
            "Surv(os_months, os_status)"
        ),
        labels = c(
            "Surv(pfs_months, pfs_status)" = "Progression-Free Survival",
            "Surv(os_months, os_status)" = "Overall Survival"
        ))

# Example 14: Mixed variable types
desctable(clintrial,
        by = "treatment",
        variables = c(
            "age", "sex", "race",           # Demographics
            "bmi", "creatinine",            # Labs
            "smoking", "hypertension",      # Risk factors
            "Surv(os_months, os_status)"    # Survival
        ))

# Example 15: Three or more groups
desctable(clintrial,
        by = "stage",  # Assuming stage has 3+ levels
        variables = c("age", "sex", "bmi"))
# Automatically uses ANOVA/Kruskal-Wallis and chi-squared

# Example 16: Access raw unformatted data
result <- desctable(clintrial,
                  by = "treatment",
                  variables = c("age", "bmi"))
raw_data <- attr(result, "raw_data")
print(raw_data)
# Raw data includes unformatted numbers, SDs, quartiles, etc.

# Example 17: Check which grouping variable was used
result <- desctable(clintrial,
                  by = "treatment",
                  variables = c("age", "sex"))
attr(result, "by_variable")  # "treatment"

# Example 18: NA percentage calculation options
# Include NAs in percentage denominator (all sum to 100%)
desctable(clintrial,
        by = "treatment",
        variables = "smoking",
        na_include = TRUE,
        na_percent = TRUE)

# Exclude NAs from denominator (non-missing sum to 100%)
desctable(clintrial,
        by = "treatment",
        variables = "smoking",
        na_include = TRUE,
        na_percent = FALSE)

# Example 19: Passing additional test arguments
# Equal variance t-test
desctable(clintrial,
        by = "sex",
        variables = "age",
        test_continuous = "t",
        var.equal = TRUE)

# Example 20: European number formatting
desctable(clintrial,
        by = "treatment",
        variables = c("age", "sex", "bmi"),
        number_format = "eu")

# Example 21: Complete Table 1 for publication
table1 <- desctable(
    data = clintrial,
    by = "treatment",
    variables = c(
        "age", "sex", "race", "ethnicity", "bmi",
        "smoking", "hypertension", "diabetes",
        "ecog", "creatinine", "hemoglobin",
        "site", "stage", "grade",
        "Surv(os_months, os_status)"
    ),
    labels = clintrial_labels,
    stats_continuous = c("median_iqr", "range"),
    total = TRUE,
    na_include = FALSE
)
print(table1)

Detect if model is univariable or multivariable

Description

Determines whether a model contains one predictor (univariable) or multiple predictors (multivariable) by analyzing coefficient names and factor structure. Handles interactions and random effects appropriately.

Usage

detect_model_type(model)

Arguments

Value

Character string: "Univariable" or "Multivariable".

Auto-detect model type based on outcome and random effects

Description

Determines the appropriate model type based on outcome variable characteristics and presence of random effects.

Usage

detect_model_type_auto(data, outcome, has_random_effects, family = "binomial")

Arguments

Value

Character string indicating detected model type.

Detect outcome type from data

Description

Automatically determines whether an outcome variable is binary, continuous, or count-based by examining the data values. Used for automatic model type selection and validation. Binary outcomes have 2 unique values, continuous have many values or non-integers, counts have integers >= 0.

Usage

detect_outcome_type(data, outcome)

Arguments

Value

Character string: "binary", "continuous", "count", or "unknown".

Detect available sans-serif font for plots

Description

Checks for commonly available sans-serif fonts in order of preference (Helvetica, Arial, Helvetica Neue) and returns the first available one. Falls back to "sans" if none are found or if systemfonts is unavailable.

Usage

detect_plot_font()

Details

When ragg is being used as the graphics device (detected via options or knitr settings), font detection works in non-interactive sessions since ragg handles font rendering independently of the R graphics system.

Value

Character string with the font family name to use.

Determine alignment for exported tables

Description

Creates column alignment string for LaTeX tables. Variable and Group columns are left-aligned; all others are centered.

Usage

determine_alignment(df)

Arguments

Value

Character string with alignment codes (e.g., "rlcc").

Determine Effect Type Label

Description

Identifies the appropriate effect measure label (OR, HR, RR, Coefficient, aOR, aHR, aRR, Adj. Coefficient) based on model type, exponentiation setting, and whether the estimate is adjusted (multivariable) or unadjusted (univariable).

Usage

determine_effect_type(uni_raw, multi_raw, exponentiate, adjusted = FALSE)

Arguments

Value

Character string with the effect measure label:

Extract metrics for mixed-effects Cox models (coxme)

Description

Extracts quality metrics specific to mixed-effects Cox proportional hazards models including concordance, pseudo-R-squared, and ICC.

Usage

extract_coxme_metrics(model, raw_data, metrics)

Arguments

Value

Updated metrics list with coxme-specific values.

Extract metrics for generalized linear mixed-effects models (glmer)

Description

Extracts quality metrics specific to generalized linear mixed-effects models including concordance, R-squared measures, ICC, and Brier score for binomial.

Usage

extract_glmer_metrics(model, raw_data, metrics)

Arguments

Value

Updated metrics list with glmer-specific values.

Extract metrics for linear mixed-effects models (lmer)

Description

Extracts quality metrics specific to linear mixed-effects models including R-squared measures, ICC, and global significance tests.

Usage

extract_lmer_metrics(model, raw_data, metrics)

Arguments

Value

Updated metrics list with lmer-specific values.

Extract comprehensive model metrics based on academic consensus

Description

Extracts quality control metrics from fitted models for comparison. Supports GLM, Cox, linear, and mixed-effects models.

Usage

extract_model_metrics(model, raw_data, model_type)

Arguments

Value

Named list of metrics.

Extract predictor effects from a fitted model

Description

Internal helper function that extracts only the predictor variable's coefficient(s) from a fitted model, ignoring intercept and covariates. Supports standard models (glm, lm, coxph) and mixed effects models (glmer, lmer, coxme).

Usage

extract_predictor_effects(
  model,
  predictor,
  outcome,
  conf_level = 0.95,
  adjusted = FALSE,
  terms_to_extract = NULL
)

Arguments

Value

data.table with predictor effect information.

Finalize Column Names for Display

Description

Renames internal column names (uni_effect, uni_p, multi_effect, multi_p) to publication-ready display names with appropriate effect measure labels (OR, HR, RR, aOR, aHR, aRR, Coefficient, etc.).

Usage

finalize_column_names(
  result,
  uni_raw,
  multi_raw,
  exponentiate,
  columns,
  metrics,
  conf_level = 0.95
)

Arguments

Value

The input data.table with columns renamed

Find non-reference row for binary variable condensing

Description

Identifies the non-reference row in a binary categorical variable by checking for NA estimates (reference rows have NA). This is more robust than assuming row position or matching specific strings like "Yes" or "Positive".

Usage

find_non_reference_row(var_rows, estimate_col = "estimate")

Arguments

Value

Integer index of the non-reference row within var_rows, or NULL if cannot be determined (e.g., no NA estimates found, or multiple non-NA rows).

Fit Regression Model with Publication-Ready Output

Description

Provides a unified interface for fitting various types of regression models with automatic formatting of results for publication. Supports generalized linear models, linear models, survival models, and mixed-effects models with consistent syntax and output formatting. Handles both univariable and multivariable models automatically.

Usage

fit(
  data = NULL,
  outcome = NULL,
  predictors = NULL,
  model = NULL,
  model_type = "glm",
  family = "binomial",
  random = NULL,
  interactions = NULL,
  strata = NULL,
  cluster = NULL,
  weights = NULL,
  conf_level = 0.95,
  reference_rows = TRUE,
  show_n = TRUE,
  show_events = TRUE,
  digits = 2,
  p_digits = 3,
  labels = NULL,
  keep_qc_stats = TRUE,
  exponentiate = NULL,
  number_format = NULL,
  verbose = NULL,
  ...
)

Arguments

    options(summata.number_format = "eu")
  

Details

Model Scope Detection:

The function automatically detects whether the model is:

• Univariable: Single predictor (e.g., predictors = "age"). Effect estimates are labeled as unadjusted ("OR", "HR", etc.), representing crude (unadjusted) association

• Multivariable: Multiple predictors (e.g., predictors = c("age", "sex", "treatment")) Effect estimates are labeled as adjusted ("aOR", "aHR", etc.), representing associations adjusted for confounding

Interaction Terms:

Interactions are specified using colon notation and added to the model:

• interactions = c("age:treatment") creates interaction between age and treatment

• Main effects for both variables are automatically included

• Multiple interactions can be specified: c("age:sex", "treatment:stage")

• For interactions between categorical variables, separate terms are created for each combination of levels

Stratification (Cox/Conditional Logistic):

The strata parameter creates separate baseline hazards:

• Allows baseline hazard to vary across strata without estimating stratum effects

• Useful when proportional hazards assumption violated across strata

• Example: strata = "center" for multicenter studies

• Stratification variable is not included as a predictor

Clustering (Cox Models):

The cluster parameter computes robust standard errors:

• Accounts for within-cluster correlation (e.g., multiple observations per patient)

• Uses sandwich variance estimator

• Does not change point estimates, only standard errors and p-values

Weighting:

The weights parameter enables weighted regression:

• For survey data with sampling weights

• Inverse probability weighting for causal inference

• Frequency weights for aggregated data

• Weights should be in a column of data

Mixed-Effects Models (lmer/glmer/coxme):

Mixed effects models handle hierarchical or clustered data:

• Use model_type = "lmer" for continuous/normal outcomes

• Use model_type = "glmer" with appropriate family for GLM outcomes

• Use model_type = "coxme" for survival outcomes with clustering

• Random effects are specified in predictors using lme4 syntax:

  • "(1|site)" - Random intercepts by site

  • "(treatment|site)" - Random slopes for treatment by site

  • "(1 + treatment|site)" - Both random intercepts and slopes

• Include random effects as part of the predictors vector

• Example: predictors = c("age", "treatment", "(1|site)")

Effect Measures by Model Type:

• Logistic (family = "binomial"/"quasibinomial"): Odds ratios (OR/aOR)

• Cox (model_type = "coxph"): Hazard ratios (HR/aHR)

• Poisson/Count (family = "poisson"/"quasipoisson"): Rate ratios (RR/aRR)

• Negative binomial (model_type = "negbin"): Rate ratios (RR/aRR)

• Gamma/Log-link: Ratios (multiplicative effects)

• Linear/Gaussian: Raw coefficient estimates (additive effects)

Confidence Intervals:

Confidence intervals are computed using the Wald method. This is the standard approach for GLM, Cox, and mixed-effects regression and is appropriate for standard sample sizes. The Wald interval is computed directly from the coefficient and standard error, avoiding redundant matrix operations.

For small samples, sparse data, or parameters near boundary values, profile likelihood confidence intervals may be preferred. These can be obtained from the underlying model object:

result <- fit(data, outcome, predictors)
confint(attr(result, "model"))

Value

A data.table with S3 class "fit_result" containing formatted regression results. The table structure includes:

Variable

Character. Predictor name or custom label

Group

Character. For factor variables: category level. For interactions: interaction term. For continuous: typically empty

n

Integer. Total sample size (if show_n = TRUE)

n_group

Integer. Sample size for this factor level

events

Integer. Total number of events (if show_events = TRUE)

events_group

Integer. Events for this factor level

OR/HR/RR/Coefficient or aOR/aHR/aRR/Adj. Coefficient (95% CI)

Character. Formatted effect estimate with confidence interval. Column name depends on model type and scope. Univariable models use: OR, HR, RR, Coefficient. Multivariable models use adjusted notation: aOR, aHR, aRR, Adj. Coefficient

p-value

Character. Formatted p-value from Wald test

The returned object includes the following attributes accessible via attr():

model

The fitted model object (glm, lm, coxph, etc.). Access for diagnostics, predictions, or further analysis

raw_data

data.table. Unformatted numeric results with columns for coefficients, standard errors, confidence bounds, quality statistics, etc.

outcome

Character. The outcome variable name

predictors

Character vector. The predictor variable names

formula_str

Character. The complete model formula as a string

model_scope

Character. "Univariable" (one predictor) or "Multivariable" (multiple predictors)

model_type

Character. The regression model type used

interactions

Character vector (if interactions specified). The interaction terms included

strata

Character (if stratification used). The stratification variable

cluster

Character (if clustering used). The cluster variable

weights

Character (if weighting used). The weights variable

significant

Character vector. Names of predictors with p-value below 0.05, suitable for downstream variable selection workflows

See Also

uniscreen for univariable screening of multiple predictors, fullfit for complete univariable-to-multivariable workflow, compfit for comparing multiple models, m2dt for model-to-table conversion

Other regression functions: compfit(), fullfit(), multifit(), print.compfit_result(), print.fit_result(), print.fullfit_result(), print.multifit_result(), print.uniscreen_result(), uniscreen()

Examples

# Load example data
data(clintrial)
data(clintrial_labels)
library(survival)

# Example 1: Univariable logistic regression
uni_model <- fit(
    data = clintrial,
    outcome = "os_status",
    predictors = "age"
)
print(uni_model)
# Labeled as "Univariable OR"



# Example 2: Multivariable logistic regression
multi_model <- fit(
    data = clintrial,
    outcome = "os_status",
    predictors = c("age", "sex", "bmi", "treatment"),
    labels = clintrial_labels
)
print(multi_model)

# Example 3: Cox proportional hazards model
cox_model <- fit(
    data = clintrial,
    outcome = "Surv(os_months, os_status)",
    predictors = c("age", "sex", "treatment", "stage"),
    model_type = "coxph",
    labels = clintrial_labels
)
print(cox_model)

# Example 4: Model with interaction terms
interact_model <- fit(
    data = clintrial,
    outcome = "os_status",
    predictors = c("age", "treatment", "sex"),
    interactions = c("age:treatment"),
    labels = clintrial_labels
)
print(interact_model)

# Example 5: Cox model with stratification
strat_model <- fit(
    data = clintrial,
    outcome = "Surv(os_months, os_status)",
    predictors = c("age", "sex", "treatment"),
    model_type = "coxph",
    strata = "site",  # Separate baseline hazards by site
    labels = clintrial_labels
)
print(strat_model)

# Example 6: Cox model with clustering
cluster_model <- fit(
    data = clintrial,
    outcome = "Surv(os_months, os_status)",
    predictors = c("age", "treatment"),
    model_type = "coxph",
    cluster = "site",  # Robust SEs accounting for site clustering
    labels = clintrial_labels
)
print(cluster_model)

# Example 7: Linear regression
linear_model <- fit(
    data = clintrial,
    outcome = "bmi",
    predictors = c("age", "sex", "smoking"),
    model_type = "lm",
    labels = clintrial_labels
)
print(linear_model)

# Example 8: Poisson regression for equidispersed count data
# fu_count has variance ~= mean, appropriate for standard Poisson
poisson_model <- fit(
    data = clintrial,
    outcome = "fu_count",
    predictors = c("age", "stage", "treatment", "surgery"),
    model_type = "glm",
    family = "poisson",
    labels = clintrial_labels
)
print(poisson_model)
# Returns rate ratios (RR/aRR)

# Example 9: Negative binomial regression for overdispersed counts
# ae_count has variance > mean (overdispersed), use negbin or quasipoisson
if (requireNamespace("MASS", quietly = TRUE)) {
    nb_result <- fit(
        data = clintrial,
        outcome = "ae_count",
        predictors = c("age", "treatment", "diabetes", "surgery"),
        model_type = "negbin",
        labels = clintrial_labels
    )
    print(nb_result)
}

# Example 10: Gamma regression for positive continuous outcomes
gamma_model <- fit(
    data = clintrial,
    outcome = "los_days",
    predictors = c("age", "treatment", "surgery"),
    model_type = "glm",
    family = Gamma(link = "log"),
    labels = clintrial_labels
)
print(gamma_model)

# Example 11: Access the underlying fitted model
result <- fit(
    data = clintrial,
    outcome = "os_status",
    predictors = c("age", "sex", "bmi")
)

# Get the model object
model_obj <- attr(result, "model")
summary(model_obj)

# Model diagnostics
plot(model_obj)

# Predictions
preds <- predict(model_obj, type = "response")

# Example 12: Access raw numeric data
raw_data <- attr(result, "raw_data")
print(raw_data)
# Contains unformatted coefficients, SEs, CIs, AIC, BIC, etc.

# Example 13: Multiple interactions
complex_model <- fit(
    data = clintrial,
    outcome = "os_status",
    predictors = c("age", "sex", "treatment", "bmi"),
    interactions = c("age:treatment", "sex:bmi"),
    labels = clintrial_labels
)
print(complex_model)

# Example 14: Customize output columns
minimal <- fit(
    data = clintrial,
    outcome = "os_status",
    predictors = c("age", "sex", "treatment"),
    show_n = FALSE,
    show_events = FALSE,
    reference_rows = FALSE
)
print(minimal)

# Example 15: Different confidence levels
ci90 <- fit(
    data = clintrial,
    outcome = "os_status",
    predictors = c("age", "treatment"),
    conf_level = 0.90  # 90% confidence intervals
)
print(ci90)

# Example 16: Force coefficient display instead of OR
coef_model <- fit(
    data = clintrial,
    outcome = "os_status",
    predictors = c("age", "bmi"),
    exponentiate = FALSE  # Show log odds instead of OR
)
print(coef_model)

# Example 17: Check model quality statistics
result <- fit(
    data = clintrial,
    outcome = "os_status",
    predictors = c("age", "sex", "treatment", "stage"),
    keep_qc_stats = TRUE
)

raw <- attr(result, "raw_data")
cat("AIC:", raw$AIC[1], "\n")
cat("BIC:", raw$BIC[1], "\n")
cat("C-statistic:", raw$c_statistic[1], "\n")

# Example 18: Interaction effects - treatment effect modified by stage
interaction_model <- fit(
    data = clintrial,
    outcome = "Surv(os_months, os_status)",
    predictors = c("age", "treatment", "stage"),
    interactions = c("treatment:stage"),
    model_type = "coxph",
    labels = clintrial_labels
)
print(interaction_model)
# Shows main effects plus all treatment×stage interaction terms

# Example 19: Multiple interactions in logistic regression
multi_interaction <- fit(
    data = clintrial,
    outcome = "readmission_30d",
    predictors = c("age", "sex", "surgery", "diabetes"),
    interactions = c("surgery:diabetes", "age:sex"),
    labels = clintrial_labels
)
print(multi_interaction)

# Example 20: Quasipoisson for overdispersed count data
# Alternative to negative binomial when MASS not available
quasi_model <- fit(
    data = clintrial,
    outcome = "ae_count",
    predictors = c("age", "treatment", "diabetes", "surgery"),
    model_type = "glm",
    family = "quasipoisson",
    labels = clintrial_labels
)
print(quasi_model)
# Adjusts standard errors for overdispersion

# Example 21: Quasibinomial for overdispersed binary data
quasi_logistic <- fit(
    data = clintrial,
    outcome = "any_complication",
    predictors = c("age", "bmi", "diabetes", "surgery"),
    model_type = "glm",
    family = "quasibinomial",
    labels = clintrial_labels
)
print(quasi_logistic)

# Example 22: Gamma regression with identity link for additive effects
gamma_identity <- fit(
    data = clintrial,
    outcome = "los_days",
    predictors = c("age", "treatment", "surgery", "any_complication"),
    model_type = "glm",
    family = Gamma(link = "identity"),
    labels = clintrial_labels
)
print(gamma_identity)
# Shows additive effects (coefficients) instead of multiplicative (ratios)

# Example 23: Inverse Gaussian regression for highly skewed data
inverse_gaussian <- fit(
    data = clintrial,
    outcome = "recovery_days",
    predictors = c("age", "surgery", "pain_score"),
    model_type = "glm",
    family = inverse.gaussian(link = "log"),
    labels = clintrial_labels
)
print(inverse_gaussian)

# Example 24: Linear mixed effects with random intercepts
# Accounts for clustering of patients within sites
if (requireNamespace("lme4", quietly = TRUE)) {
    lmer_model <- fit(
        data = clintrial,
        outcome = "los_days",
        predictors = c("age", "treatment", "stage", "(1|site)"),
        model_type = "lmer",
        labels = clintrial_labels
    )
    print(lmer_model)
}

# Example 25: Generalized linear mixed effects (logistic with random effects)
if (requireNamespace("lme4", quietly = TRUE)) {
    glmer_model <- fit(
        data = clintrial,
        outcome = "readmission_30d",
        predictors = c("age", "surgery", "los_days", "(1|site)"),
        model_type = "glmer",
        family = "binomial",
        labels = clintrial_labels
    )
    print(glmer_model)
}

# Example 26: Cox mixed effects for clustered survival data
if (requireNamespace("coxme", quietly = TRUE)) {
    coxme_model <- fit(
        data = clintrial,
        outcome = "Surv(os_months, os_status)",
        predictors = c("age", "treatment", "stage", "(1|site)"),
        model_type = "coxme",
        labels = clintrial_labels
    )
    print(coxme_model)
}

# Example 27: Random slopes - treatment effect varies by site
if (requireNamespace("lme4", quietly = TRUE)) {
    random_slopes <- fit(
        data = clintrial,
        outcome = "los_days",
        predictors = c("age", "treatment", "stage", "(treatment|site)"),
        model_type = "lmer",
        labels = clintrial_labels
    )
    print(random_slopes)
}

# Example 28: Format a pre-fitted model (model-based workflow)
# Useful for models fitted outside of fit()
pre_fitted <- glm(os_status ~ age + sex + treatment,
                  family = binomial, data = clintrial)
result <- fit(model = pre_fitted, 
              data = clintrial,
              labels = clintrial_labels)
print(result)

Fix negative zero in formatted strings

Description

Corrects floating-point rounding artifacts that produce "-0.00" or similar negative zero strings. Works on character vectors, replacing patterns like "-0.00", "-0.000", etc. with their positive equivalents, even when embedded within larger strings (e.g., "(-0.00, 1.23)" becomes "(0.00, 1.23)").

Usage

fix_negative_zero(x, marks = NULL)

Arguments

Details

When marks is supplied, also replaces the period decimal mark with the locale-appropriate decimal mark.

Value

Character vector with negative zeros corrected.

Determine CI separator for forest plot text annotations

Description

Returns the appropriate separator string between CI lower and upper bounds in forest plot annotations. Considers whether values may be negative and the current locale's decimal mark.

Usage

forest_ci_separator(has_negatives, marks = NULL)

Arguments

Value

Character string separator.

Format a categorical statistic for display

Description

Converts frequency counts into formatted display strings following standard conventions (n, n (%), % only) with locale-aware decimal marks.

Usage

format_categorical_stat(n, total, stat_type, marks)

Arguments

Value

Character string with the formatted statistic.

Apply formatting to column headers in exported tables (PDF/LaTeX)

Description

Formats column headers for LaTeX output by escaping special characters, italicizing 'n' and 'p', and optionally adding vertical spacing.

Usage

format_column_headers(col_names, add_header_space = TRUE)

Arguments

Value

Character vector with LaTeX-formatted column names.

Apply formatting to column headers in exported tables (HTML)

Description

Formats column headers for HTML output by italicizing 'n' and 'p' using HTML tags.

Usage

format_column_headers_html(col_names)

Arguments

Value

Character vector with HTML-formatted column names.

Format column headers with n counts (HTML)

Description

Creates HTML-formatted column headers with sample size counts displayed below the column name using line breaks.

Usage

format_column_headers_with_n_html(col_names, n_row_data)

Arguments

Value

Character vector with HTML-formatted headers including n counts.

Format column headers with n counts (TeX)

Description

Creates LaTeX-formatted column headers with sample size counts displayed below the column name in a stacked format.

Usage

format_column_headers_with_n_tex(col_names, n_row_data)

Arguments

Value

Character vector with LaTeX-formatted headers including n counts.

Format continuous statistic for display

Description

Converts numeric summary statistics into formatted display strings following standard conventions (mean \pm SD, median [IQR], range, etc.).

Usage

format_continuous_stat(stats, stat_type, fmt_str, marks)

Arguments

Value

Character string with formatted statistic.

Format an integer count with locale-aware thousands separator

Description

Formats integer values with a thousands separator for display in tables. Values below 1000 are returned as plain character strings.

Usage

format_count(n, marks)

Arguments

Value

Character string with the formatted count.

Format an integer for forest plot annotations

Description

Applies thousands separator to an integer value. Respects locale marks when provided.

Usage

format_count_forest(x, marks = NULL)

Arguments

Value

Character string.

Format combined fullfit output from formatted tables

Description

Merges univariable and multivariable results into a single publication-ready table with side-by-side display. Uses vectorized merge instead of per-variable loops.

Usage

format_fullfit_combined(
  uni_formatted,
  multi_formatted,
  uni_raw,
  multi_raw,
  predictors,
  columns,
  metrics,
  show_n,
  show_events,
  labels,
  exponentiate = NULL,
  conf_level = 0.95
)

Arguments

Value

Combined data.table with aligned univariable and multivariable results.

Format headers for flextable

Description

Applies formatting to flextable headers including italicizing 'n', adding sample size counts from N row data, and bolding all headers.

Usage

format_headers_ft(ft, has_n_row, n_row_data)

Arguments

Value

Formatted flextable object.

Apply formatting to indented groups

Description

Transforms tables with Variable/Group columns into indented format where group levels appear as indented rows under variable names. Handles both regression and descriptive tables with appropriate p-value placement.

Usage

format_indented_groups(df, indent_string = "    ")

Arguments

Value

Data.table with Group column removed and levels indented under Variables.

Format interaction term for display

Description

Converts R's internal interaction term format (e.g., "treatmentDrug A:stageII") to a more readable format (e.g., "Treatment (Drug A) × Stage (II)").

Usage

format_interaction_term(term, labels = NULL)

Arguments

Value

Formatted interaction term string.

Format model comparison table

Description

Rounds numeric columns to appropriate precision based on metric type.

Usage

format_model_comparison(comparison)

Arguments

Value

Data.table with properly rounded numeric columns.

Format model results for publication-ready display

Description

Transforms raw model coefficient data into a formatted table suitable for publication. Handles effect measure formatting (OR, HR, RR, Estimate), confidence intervals, p-values, sample sizes, and variable labels. Supports interaction terms and mixed-effects models.

Usage

format_model_table(
  data,
  effect_col = NULL,
  digits = 2,
  p_digits = 3,
  labels = NULL,
  show_n = TRUE,
  show_events = TRUE,
  reference_label = "reference",
  exponentiate = NULL,
  conf_level = 0.95,
  marks = NULL
)

Arguments

Value

Formatted data.table with publication-ready columns.

Format multifit results for publication

Description

Internal helper that formats raw multivariate results into publication-ready table format.

Usage

format_multifit_table(
  data,
  columns,
  show_n = TRUE,
  show_events = TRUE,
  digits = 2,
  p_digits = 3,
  labels = NULL,
  predictor_label = NULL,
  include_predictor = TRUE,
  exponentiate = NULL,
  conf_level = 0.95,
  marks = NULL
)

Arguments

Value

Formatted data.table.

Format a numeric value with locale-aware separators

Description

General-purpose number formatter used by all display functions. For values \ge 1000 (in absolute value), inserts the appropriate thousands separator. Fixes negative-zero display artefacts.

Usage

format_num(x, fmt_str, marks)

Arguments

Value

Character string with the formatted number.

Format numeric value with fixed decimal places

Description

Formats a numeric value to a specified number of decimal places, removing leading/trailing whitespace and fixing negative zero display (e.g., "-0.00" becomes "0.00"). When marks is supplied, applies locale-appropriate decimal mark substitution.

Usage

format_number(x, digits, marks = NULL)

Arguments

Value

Character string with formatted value.

Format a p-value for forest plot annotations

Description

Returns a formatted p-value string suitable for forest plot display, using locale-aware decimal marks when marks is provided.

Usage

format_p_forest(p, p_digits, marks = NULL)

Arguments

Value

Character string.

Format a p-value with locale-aware decimal mark

Description

Converts a numeric p-value to a display string with the correct decimal separator and threshold notation (e.g., "< 0.001" or "< 0,001").

Usage

format_pvalue(p, digits, marks)

Arguments

Value

Character string with the formatted p-value.

Format p-value for survtable

Description

Provides p-value formatting to the survtable result.

Usage

format_pvalue_survtable(p, digits, marks = NULL)

Arguments

Value

Character-formatted p-value.

Format p-values for descriptive tables

Description

Converts numeric p-values to formatted strings with appropriate precision. Handles very small p-values with threshold notation (e.g., "< 0.001").

Usage

format_pvalues_desctable(result, p_digits, marks)

Arguments

Value

Modified data.table with 'p_value' column (formatted strings).

Format p-values for exported tables (HTML)

Description

Applies bold formatting to significant p-values in HTML tables using the b tag.

Usage

format_pvalues_export_html(df, p_threshold = 0.05)

Arguments

Value

Data.table with significant p-values wrapped in HTML bold tags.

Format p-values for exported tables

Description

Applies bold formatting to significant p-values in LaTeX tables using the textbf command.

Usage

format_pvalues_export_tex(df, p_threshold = 0.05)

Arguments

Value

Data.table with significant p-values wrapped in LaTeX bold commands.

Format p-values for display

Description

Converts numeric p-values to formatted character strings using vectorized operations. Values below the threshold (determined by digits parameter) display as "< 0.001" (for digits=3), "< 0.0001" (for digits=4), etc. NA values display as "-".

Usage

format_pvalues_fit(p, digits = 3, marks = NULL)

Arguments

Value

Character vector of formatted p-values.

Format p-values for multifit display

Description

Converts numeric p-values to formatted character strings. Values below the threshold (determined by digits parameter) display as "< 0.001" (for digits=3), "< 0.0001" (for digits=4), etc. NA values display as "-".

Usage

format_pvalues_multifit(p, digits = 3, marks = NULL)

Arguments

Value

Character vector of formatted p-values.

Vectorized quantile cell formatting

Description

Formats survival quantile cells for multiple rows at once.

Usage

format_quantile_cells(est, lower, upper, fmt_str, marks = NULL)

Arguments

Value

Character vector of formatted cells.

Vectorized survival cell formatting

Description

Formats survival probability cells for multiple rows at once. Uses locale-aware decimal marks and safe CI separators that avoid ambiguity with negative values or decimal commas.

Usage

format_survival_cells(
  est,
  lower,
  upper,
  n_risk,
  n_event,
  stats,
  fmt_est,
  fmt_ci_lower,
  fmt_ci_upper,
  percent,
  marks = NULL
)

Arguments

Value

Character vector of formatted cells.

Format survival median with CI for display

Description

Formats a survival median estimate with confidence interval using locale-aware decimal marks and safe CI separators. Used by process_survival in descriptive tables.

Usage

format_survival_ci(median, lower, upper, fmt_str, marks)

Arguments

Value

Character string with formatted "median (lower-upper)".

Complete Regression Analysis Workflow

Description

Executes a comprehensive regression analysis pipeline that combines univariable screening, automatic/manual variable selection, and multivariable modeling in a single function call. This function is designed to streamline the complete analytical workflow from initial exploration to final adjusted models, with publication-ready formatted output showing both univariable and multivariable results side-by-side if desired.

Usage

fullfit(
  data,
  outcome,
  predictors,
  method = "screen",
  multi_predictors = NULL,
  p_threshold = 0.05,
  columns = "both",
  model_type = "glm",
  family = "binomial",
  random = NULL,
  conf_level = 0.95,
  reference_rows = TRUE,
  show_n = TRUE,
  show_events = TRUE,
  digits = 2,
  p_digits = 3,
  labels = NULL,
  metrics = "both",
  return_type = "table",
  keep_models = FALSE,
  exponentiate = NULL,
  parallel = TRUE,
  n_cores = NULL,
  number_format = NULL,
  verbose = NULL,
  ...
)

Arguments

    options(summata.number_format = "eu")
  

Details

Analysis Workflow:

The function implements a complete regression analysis pipeline:

1. Univariable screening: Fits separate models for each predictor (outcome ~ predictor). Each predictor is tested independently to understand crude associations.

2. Variable selection: Based on the method parameter:

   • "screen": Automatically selects predictors with univariable p \le p_threshold

   • "all": Includes all predictors (no selection)

   • "custom": Uses predictors specified in multi_predictors

3. Multivariable modeling: Fits a single model with selected predictors (outcome ~ predictor1 + predictor2 + ...). Estimates are adjusted for all other variables in the model.

4. Output formatting: Combines results into publication-ready table with appropriate effect measures and formatting.

Variable Selection Strategies:

"Screen" Method (method = "screen"):

• Uses p-value threshold for automatic selection

• Liberal thresholds (e.g., 0.20) cast a wide net to avoid missing important predictors

• Stricter thresholds (e.g., 0.05) focus on strongly associated predictors

• Helps reduce overfitting and multicollinearity

• Common in exploratory analyses and when sample size is limited

"All" Method (method = "all"):

• No variable selection - includes all predictors

• Appropriate when all variables are theoretically important

• Risk of overfitting with many predictors relative to sample size

• Useful for confirmatory analyses with pre-specified models

"Custom" Method (method = "custom"):

• Manual selection based on subject matter knowledge

• Runs univariable analysis for all predictors (for comparison)

• Includes only specified predictors in multivariable model

• Ideal for theory-driven model building

• Allows comparison of unadjusted vs adjusted effects for all variables

Interpreting Results:

When columns = "both" (default), tables show:

• Univariable columns: Crude associations, unadjusted for other variables. Labeled as "OR/HR/RR/Coefficient (95% CI)" and "Uni p"

• Multivariable columns: Adjusted associations, accounting for all other predictors in the model. Labeled as "aOR/aHR/aRR/Adj. Coefficient (95% CI)" and "Multi p" ("a" = adjusted)

• Variables not meeting selection criteria show "-" in multivariable columns

Comparing univariable and multivariable results helps identify:

• Confounding: Large changes in effect estimates

• Independent effects: Similar univariable and multivariable estimates

• Mediation: Attenuated effects in multivariable model

• Suppression: Effects that emerge only after adjustment

Sample Size Considerations:

Rule of thumb for multivariable models:

• Logistic regression: \ge 10 events per predictor variable

• Cox regression: \ge 10 events per predictor variable

• Linear regression: \ge 10-20 observations per predictor

Use screening methods to reduce predictor count when these ratios are not met.

Value

Depends on return_type parameter:

When return_type = "table" (default): A data.table with S3 class "fullfit_result" containing:

Variable

Character. Predictor name or custom label

Group

Character. Category level for factors, empty for continuous

n/n_group

Integer. Sample sizes (if show_n = TRUE)

events/events_group

Integer. Event counts (if show_events = TRUE)

OR/HR/RR/Coefficient (95% CI)

Character. Unadjusted effect (if columns includes "uni" and metrics includes "effect")

Uni p

Character. Univariable p-value (if columns includes "uni" and metrics includes "p")

aOR/aHR/aRR/Adj. Coefficient (95% CI)

Character. Adjusted effect (if columns includes "multi" and metrics includes "effect")

Multi p

Character. Multivariable p-value (if columns includes "multi" and metrics includes "p")

When return_type = "model": The fitted multivariable model object (glm, lm, coxph, etc.).

When return_type = "both": A list with two elements:

table

The formatted results data.table

model

The fitted multivariable model object

The table includes the following attributes:

outcome

Character. The outcome variable name

model_type

Character. The regression model type

method

Character. The variable selection method used

columns

Character. Which columns were displayed

model

The multivariable model object (if fitted)

uni_results

The complete univariable screening results

n_multi

Integer. Number of predictors in multivariable model

screened

Character vector. Names of predictors that passed univariable screening at the specified p-value threshold

significant

Character vector. Names of variables with p < 0.05 in the multivariable model (or univariable if multivariable was not fitted)

See Also

uniscreen for univariable screening only, fit for fitting a single multivariable model, compfit for comparing multiple models, desctable for descriptive statistics

Other regression functions: compfit(), fit(), multifit(), print.compfit_result(), print.fit_result(), print.fullfit_result(), print.multifit_result(), print.uniscreen_result(), uniscreen()

Examples

# Load example data
data(clintrial)
data(clintrial_labels)

# Example 1: Basic screening with p < 0.05 threshold
result1 <- fullfit(
    data = clintrial,
    outcome = "os_status",
    predictors = c("age", "sex", "bmi", "smoking",
                   "hypertension", "diabetes",
                   "treatment", "stage"),
    method = "screen",
    p_threshold = 0.05,
    labels = clintrial_labels
)
print(result1)
# Shows both univariable and multivariable results
# Only significant univariable predictors in multivariable model



# Example 2: Include all predictors (no selection)
result2 <- fullfit(
    data = clintrial,
    outcome = "os_status",
    predictors = c("age", "sex", "treatment", "stage"),
    method = "all",
    labels = clintrial_labels
)
print(result2)

# Example 3: Custom variable selection
result3 <- fullfit(
    data = clintrial,
    outcome = "os_status",
    predictors = c("age", "sex", "bmi", "smoking", "treatment", "stage"),
    method = "custom",
    multi_predictors = c("age", "treatment", "stage"),
    labels = clintrial_labels
)
print(result3)
# Univariable for all, multivariable for selected only

# Example 4: Cox regression with screening
library(survival)
cox_result <- fullfit(
    data = clintrial,
    outcome = "Surv(os_months, os_status)",
    predictors = c("age", "sex", "treatment", "stage"),
    model_type = "coxph",
    method = "screen",
    p_threshold = 0.10,
    labels = clintrial_labels
)
print(cox_result)

# Example 5: Linear regression without screening
linear_result <- fullfit(
    data = clintrial,
    outcome = "bmi",
    predictors = c("age", "sex", "smoking", "creatinine"),
    model_type = "lm",
    method = "all",
    labels = clintrial_labels
)
print(linear_result)

# Example 6: Poisson regression for count outcomes
poisson_result <- fullfit(
    data = clintrial,
    outcome = "fu_count",
    predictors = c("age", "stage", "treatment", "surgery"),
    model_type = "glm",
    family = "poisson",
    method = "all",
    labels = clintrial_labels
)
print(poisson_result)

# Example 7: Show only multivariable results
multi_only <- fullfit(
    data = clintrial,
    outcome = "os_status",
    predictors = c("age", "sex", "treatment", "stage"),
    method = "all",
    columns = "multi",
    labels = clintrial_labels
)
print(multi_only)

# Example 8: Return both table and model object
both <- fullfit(
    data = clintrial,
    outcome = "os_status",
    predictors = c("age", "sex", "treatment", "stage"),
    method = "all",
    return_type = "both"
)
print(both$table)
summary(both$model)

# Example 9: Keep univariable models for diagnostics
with_models <- fullfit(
    data = clintrial,
    outcome = "os_status",
    predictors = c("age", "bmi", "creatinine"),
    keep_models = TRUE
)
uni_results <- attr(with_models, "uni_results")
uni_models <- attr(uni_results, "models")
summary(uni_models[["age"]])

# Example 10: Linear mixed effects with site clustering
if (requireNamespace("lme4", quietly = TRUE)) {
    lmer_result <- fullfit(
        data = clintrial,
        outcome = "los_days",
        predictors = c("age", "treatment", "surgery", "stage"),
        random = "(1|site)",
        model_type = "lmer",
        method = "all",
        labels = clintrial_labels
    )
    print(lmer_result)
}

Extract event variable from survival model

Description

Parses the Surv() expression in survival model formulas to extract the event/status variable name. Works with coxph, clogit, and coxme models.

Usage

get_event_variable(model, model_class)

Arguments

Value

Character string naming the event variable, or NULL if not found.

Get data from model object (works with S3 and S4)

Description

Retrieves the original data used to fit a model. Checks multiple locations including model attributes, $data slot, $model slot, and @frame for S4.

Usage

get_model_data(model)

Arguments

Value

Data frame or data.table used to fit the model, or NULL if unavailable.

Get readable model type name

Description

Converts model class names to human-readable descriptions. For GLMs, uses the family to provide specific names (e.g., "Logistic", "Poisson").

Usage

get_model_type_name(model)

Arguments

Value

Character string with readable model type name.

Get factor levels from model (works with S3 and S4)

Description

Extracts factor level information from fitted model objects. Handles both S3 models (glm, lm, coxph) via xlevels slot and S4 models (lme4) via the model frame.

Usage

get_model_xlevels(model)

Arguments

Value

Named list of factor levels, or NULL if no factors present.

Get paper size for PDF/LaTeX export

Description

Returns paper dimensions and margin settings for the specified paper size.

Usage

get_paper_settings(paper, margins = NULL)

Arguments

Value

List with latex_paper, width, height, and margins components.

Get display label for statistic type

Description

Converts internal statistic type codes to formatted display labels for table column headers.

Usage

get_stat_label(stat_type)

Arguments

Value

Character string with formatted label (e.g., "Mean \pm SD").

Create Forest Plot for Generalized Linear Models

Description

Generates a publication-ready forest plot that combines a formatted data table with a graphical representation of effect estimates (odds ratios, risk ratios, or coefficients) from a generalized linear model. The plot integrates variable names, group levels, sample sizes, effect estimates with confidence intervals, p-values, and model diagnostics in a single comprehensive visualization designed for manuscripts and presentations.

Usage

glmforest(
  x,
  data = NULL,
  title = "Generalized Linear Model",
  effect_label = NULL,
  digits = 2,
  p_digits = 3,
  conf_level = 0.95,
  font_size = 1,
  annot_size = 3.88,
  header_size = 5.82,
  title_size = 23.28,
  plot_width = NULL,
  plot_height = NULL,
  table_width = 0.6,
  show_n = TRUE,
  show_events = TRUE,
  indent_groups = FALSE,
  condense_table = FALSE,
  bold_variables = FALSE,
  center_padding = 4,
  zebra_stripes = TRUE,
  ref_label = "reference",
  labels = NULL,
  color = NULL,
  exponentiate = NULL,
  qc_footer = TRUE,
  units = "in",
  number_format = NULL
)

Arguments

    options(summata.number_format = "eu")
  

Details

Plot Components:

The forest plot consists of several integrated components:

1. Title: Centered at top, describes the analysis

2. Data Table (left side): Contains columns for:

   • Variable: Predictor names (or custom labels)

   • Group: Factor levels (optional, hidden when indenting)

   • n: Sample sizes by group (optional)

   • Events: Event counts by group (optional)

   • Effect (95% CI); p-value: Formatted estimates with p-values

3. Forest Plot (right side): Graphical display with:

   • Point estimates (squares sized by sample size)

   • 95% confidence intervals (error bars)

   • Reference line (at OR/RR = 1 or coefficient = 0)

   • Log scale for odds/risk ratios

   • Labeled axis

4. Model Statistics (footer): Summary of:

   • Observations analyzed (with percentage of total data)

   • Model family (Binomial, Poisson, etc.)

   • Deviance statistics

   • Pseudo-R^2 (McFadden)

   • AIC

Automatic Effect Measure Selection:

When effect_label = NULL and exponentiate = NULL, the function intelligently selects the appropriate effect measure:

• Logistic regression (family = binomial(link = "logit")): Odds Ratios (OR)

• Log-link models (link = "log"): Risk Ratios (RR) or Rate Ratios

• Other exponential families: exp(coefficient)

• Identity link: Raw coefficients

Reference Categories:

For factor variables, the first level (determined by factor ordering or alphabetically for character variables) serves as the reference category:

• Displayed with the ref_label instead of an estimate

• No confidence interval or p-value shown

• Visually aligned with other categories

• When condense_table = TRUE, reference-only variables may be omitted entirely

Layout Optimization:

The function automatically optimizes layout based on content:

• Calculates appropriate axis ranges to accommodate all confidence intervals

• Selects meaningful tick marks on log or linear scales

• Sizes point markers proportional to sample size (larger = more data)

• Adjusts table width based on variable name lengths when table_width = NULL

• Recommends overall dimensions based on number of rows

Visual Grouping Options:

Three display modes are available:

1. Standard (indent_groups = FALSE, condense_table = FALSE): Separate "Variable" and "Group" columns, all categories shown

2. Indented (indent_groups = TRUE, condense_table = FALSE): Hierarchical display with groups indented under variables

3. Condensed (condense_table = TRUE): Binary variables shown in single rows, automatically indented

Zebra Striping:

When zebra_stripes = TRUE, alternating variables (not individual rows) receive light gray backgrounds. This helps visually group all levels of a factor variable together, making the plot easier to read especially with many multi-level factors.

Model Statistics Display:

The footer shows key diagnostic information:

• Observations analyzed: Total N and percentage of original data (accounting for missing values)

• Null/Residual Deviance: Model fit improvement

• Pseudo-R^2: McFadden R^2 = 1 - (log L_1 / log L_2)

• AIC: For model comparison (lower is better)

For logistic regression, concordance (C-statistic/AUC) may also be displayed if available.

Saving Plots:

Use ggplot2::ggsave() with recommended dimensions:

  p <- glmforest(model, data)
  dims <- attr(p, "rec_dims")
  ggplot2::ggsave("forest.pdf", p, width = dims$width, height = dims$height)

Or specify custom dimensions:

ggplot2::ggsave("forest.png", p, width = 12, height = 8, dpi = 300)

Value

A ggplot object containing the complete forest plot. The plot can be:

• Displayed directly: print(plot)

• Saved to file: ggsave("forest.pdf", plot, width = 12, height = 8)

• Further customized with ggplot2 functions

The returned object includes an attribute "rec_dims" accessible via attr(plot, "rec_dims"), which is a list containing:

width

Numeric. Recommended plot width in specified units

height

Numeric. Recommended plot height in specified units

These recommendations are automatically calculated based on the number of variables, text sizes, and layout parameters, and are printed to console if plot_width or plot_height are not specified.

See Also

autoforest for automatic model detection, coxforest for Cox proportional hazards forest plots, lmforest for linear model forest plots, uniforest for univariable screening forest plots, multiforest for multi-outcome forest plots, glm for fitting GLMs, fit for regression modeling

Other visualization functions: autoforest(), coxforest(), lmforest(), multiforest(), uniforest()

Examples

data(clintrial)
data(clintrial_labels)

# Create example model
model1 <- glm(os_status ~ age + sex + bmi + treatment,
              data = clintrial, family = binomial)

# Example 1: Basic logistic regression forest plot
p <- glmforest(model1, data = clintrial)



old_width <- options(width = 180)

# Example 2: With custom variable labels
plot2 <- glmforest(
    x = model1,
    data = clintrial,
    title = "Risk Factors for Mortality",
    labels = clintrial_labels
)

# Example 3: Indented layout with formatting options
plot3 <- glmforest(
    x = model1,
    data = clintrial,
    indent_groups = TRUE,
    zebra_stripes = TRUE,
    color = "#D62728",
    labels = clintrial_labels
)

# Example 4: Condensed layout for many binary variables
model4 <- glm(os_status ~ age + sex + smoking + hypertension + 
                  diabetes + surgery,
              data = clintrial,
              family = binomial)

plot4 <- glmforest(
    x = model4,
    data = clintrial,
    condense_table = TRUE,
    labels = clintrial_labels
)
# Binary variables shown in single rows

# Example 5: Poisson regression for count data
model5 <- glm(ae_count ~ age + treatment + diabetes + surgery,
               data = clintrial,
               family = poisson)

plot5 <- glmforest(
    x = model5,
    data = clintrial,
    title = "Rate Ratios for Adverse Events",
    labels = clintrial_labels
)

# Example 6: Save with recommended dimensions
dims <- attr(plot5, "rec_dims")
ggplot2::ggsave(file.path(tempdir(), "forest.pdf"),
                plot5, width = dims$width, height = dims$height)

options(old_width)

Identify variable groups before indentation

Description

Detects variable group boundaries by finding rows where Variable column is non-empty. Returns row indices for each group for zebra stripe application.

Usage

identify_variable_groups(df)

Arguments

Value

List of integer vectors, each containing row indices for one variable group.

Check if category name should be suppressed in condensed label

Description

Determines whether a category name should be suppressed when condensing binary variables. Returns TRUE for standard affirmative values (e.g., "Yes", "1", "Positive"), standard reference values (e.g., "No", "Absent", "None"), or when the category name essentially matches the variable label (case-insensitive comparison).

Usage

is_affirmative_category(
  category,
  label = NULL,
  norm_category = NULL,
  norm_label = NULL
)

Arguments

Value

Logical indicating whether category should be suppressed.

Check if object is a multifit result

Description

Internal helper to detect multifit output objects.

Usage

is_multifit_result(x)

Arguments

Value

Logical indicating if x is a multifit result.

Check if category name is a standard reference/negative value

Description

Determines whether a category name represents a standard reference or negative value that indicates absence. Used to suppress redundant category names when condensing binary variables.

Usage

is_reference_category(
  category,
  label = NULL,
  norm_category = NULL,
  norm_label = NULL
)

Arguments

Value

Logical indicating whether category is a reference/negative value.

Check if outcome is a Surv() expression

Description

Tests whether an outcome specification string represents a survival outcome by checking for the Surv() function pattern. Used to route model fitting to Cox proportional hazards methods.

Usage

is_surv_outcome(outcome)

Arguments

Value

Logical TRUE if outcome starts with "Surv(", FALSE otherwise.

Check if object is a uniscreen result

Description

Internal helper to detect uniscreen output objects.

Usage

is_uniscreen_result(x)

Arguments

Value

Logical indicating if x is a uniscreen result.

Create Forest Plot for Linear Models

Description

Generates a publication-ready forest plot that combines a formatted data table with a graphical representation of regression coefficients from a linear model. The plot integrates variable names, group levels, sample sizes, coefficients with confidence intervals, p-values, and model diagnostics (R^2, F-statistic, AIC) in a single comprehensive visualization designed for manuscripts and presentations.

Usage

lmforest(
  x,
  data = NULL,
  title = "Linear Model",
  effect_label = "Coefficient",
  digits = 2,
  p_digits = 3,
  conf_level = 0.95,
  font_size = 1,
  annot_size = 3.88,
  header_size = 5.82,
  title_size = 23.28,
  plot_width = NULL,
  plot_height = NULL,
  table_width = 0.6,
  show_n = TRUE,
  indent_groups = FALSE,
  condense_table = FALSE,
  bold_variables = FALSE,
  center_padding = 4,
  zebra_stripes = TRUE,
  ref_label = "reference",
  labels = NULL,
  units = "in",
  color = "#5A8F5A",
  qc_footer = TRUE,
  number_format = NULL
)

Arguments

    options(summata.number_format = "eu")
  

Details

Linear Model-Specific Features:

The linear model forest plot differs from logistic and Cox plots in several ways:

• Coefficients: Raw regression coefficients shown (not exponentiated)

• Reference line: At coefficient = 0 (not at 1)

• Linear scale: Forest plot uses linear scale (not log scale)

• No events column: Only sample sizes shown (no event counts)

• R^2 statistics: Model fit assessed by R^2 and adjusted R^2

• F-test: Overall model significance from F-statistic

Plot Components:

1. Title: Centered at top

2. Data Table (left): Contains:

   • Variable: Predictor names

   • Group: Factor levels (if applicable)

   • n: Sample sizes by group

   • Coefficient (95% CI); p-value: Raw coefficients with CIs and p-values

3. Forest Plot (right):

   • Point estimates (squares sized by sample size)

   • 95% confidence intervals (error bars)

   • Reference line at coefficient = 0

   • Linear scale

4. Model Statistics (footer):

   • Observations analyzed (with percentage of total data)

   • R^2 and adjusted R^2

   • F-statistic with degrees of freedom and p-value

   • AIC

Interpreting Coefficients:

Linear regression coefficients represent the change in the outcome variable for a one-unit change in the predictor:

• Continuous predictors: Coefficient = change in Y per unit of X

• Binary predictors: Coefficient = difference in Y between groups

• Factor predictors: Coefficients = differences from reference category

• Sign matters: Positive = increase in Y, Negative = decrease in Y

• Zero crossing: CI crossing zero suggests no significant effect

Example: If the coefficient for "age" is 0.50 when predicting BMI, BMI increases by 0.50 kg/m^2 for each additional year of age.

Model Fit Statistics:

The footer displays key diagnostics:

• R^2: Proportion of variance explained (0 to 1)

  • 0.0-0.3: Weak explanatory power

  • 0.3-0.5: Moderate

  • 0.5-0.7: Good

  • > 0.7: Strong (rare in social/biological sciences)

• Adjusted R^2: R^2 penalized for number of predictors

  • Always \le R^2

  • Preferred for model comparison

  • Accounts for model complexity

• F-statistic: Tests null hypothesis that all coefficients = 0

  • Degrees of freedom: df1 = # predictors, df2 = # observations - # predictors - 1

  • Significant p-value indicates model explains variance better than intercept-only

• AIC: For model comparison (lower is better)

Assumptions:

Linear regression assumes:

1. Linearity of relationships

2. Independence of observations

3. Homoscedasticity (constant variance)

4. Normality of residuals

5. No multicollinearity

Check assumptions using:

• plot(model) for diagnostic plots

• car::vif(model) for multicollinearity

• lmtest::bptest(model) for heteroscedasticity

• shapiro.test(residuals(model)) for normality

Reference Categories:

For factor variables:

• First level is the reference (coefficient = 0)

• Other levels show difference from reference

• Reference displayed with ref_label

• Relevel factors before modeling if needed: factor(x, levels = c("desired_ref", ...))

Sample Size Reporting:

The "n" column shows:

• For continuous variables: Total observations with non-missing data

• For factor variables: Number of observations in each category

• Footer shows total observations analyzed and percentage of original data (accounting for missing values)

Value

A ggplot object containing the complete forest plot. The plot can be:

• Displayed directly: print(plot)

• Saved to file: ggsave("forest.pdf", plot, width = 12, height = 8)

• Further customized with ggplot2 functions

The returned object includes an attribute "rec_dims" accessible via attr(plot, "rec_dims"), which is a list containing:

width

Numeric. Recommended plot width in specified units

height

Numeric. Recommended plot height in specified units

These recommendations are automatically calculated based on the number of variables, text sizes, and layout parameters, and are printed to console if plot_width or plot_height are not specified.

See Also

autoforest for automatic model detection, glmforest for logistic/GLM forest plots, coxforest for Cox model forest plots, uniforest for univariable screening forest plots, multiforest for multi-outcome forest plots, lm for fitting linear models, fit for regression modeling

Other visualization functions: autoforest(), coxforest(), glmforest(), multiforest(), uniforest()

Examples

data(clintrial)
data(clintrial_labels)

# Create example model
model1 <- lm(bmi ~ age + sex + smoking, data = clintrial)

# Example 1: Basic linear model forest plot
p <- lmforest(model1, data = clintrial)



old_width <- options(width = 180)

# Example 2: With custom labels and title
plot2 <- lmforest(
    x = model1,
    data = clintrial,
    title = "Predictors of Body Mass Index",
    effect_label = "Change in BMI (kg/m^2)",
    labels = clintrial_labels
)

# Example 3: Comprehensive model with indented layout
model3 <- lm(
    bmi ~ age + sex + smoking + hypertension + diabetes + creatinine,
    data = clintrial
)

plot3 <- lmforest(
    x = model3,
    data = clintrial,
    labels = clintrial_labels,
    indent_groups = TRUE,
    zebra_stripes = TRUE
)

# Example 4: Condensed layout
plot4 <- lmforest(
    x = model3,
    data = clintrial,
    condense_table = TRUE,
    labels = clintrial_labels
)

# Example 5: Different outcome (hemoglobin)
model5 <- lm(
    hemoglobin ~ age + sex + bmi + smoking + creatinine,
    data = clintrial
)

plot5 <- lmforest(
    x = model5,
    data = clintrial,
    title = "Predictors of Baseline Hemoglobin",
    effect_label = "Change in Hemoglobin (g/dL)",
    labels = clintrial_labels
)

# Example 6: Save with recommended dimensions
dims <- attr(plot5, "rec_dims")
ggplot2::ggsave(file.path(tempdir(), "linear_forest.pdf"),
                plot5, width = dims$width, height = dims$height)

options(old_width)

Convert Model to Data Table

Description

Extracts coefficients, confidence intervals, and comprehensive model statistics from fitted regression models and converts them to a standardized data.table format suitable for further analysis or publication. This is a core utility function frequently used internally by other summata regression functions, although it can be used as a standalone function as well.

Usage

m2dt(
  data,
  model,
  conf_level = 0.95,
  keep_qc_stats = TRUE,
  include_intercept = TRUE,
  terms_to_exclude = NULL,
  reference_rows = TRUE,
  reference_label = "reference",
  skip_counts = FALSE
)

Arguments

Details

This function is the core extraction utility used by fit() and other regression functions. It handles the complexities of different model classes and provides a consistent output format suitable for tables and forest plots.

Model Type Detection: The function automatically detects model type and applies appropriate:

• Effect measure naming (OR, HR, RR, Coefficient)

• Confidence interval calculation method

• Event counting for binary/survival outcomes

Mixed Effects Models: For lme4 models (glmer, lmer), the function extracts fixed effects only. Random effects variance components are not included in the output table, as they represent clustering structure rather than predictor effects.

Value

A data.table containing extracted model information with the following standard columns:

model_scope

Character. Either "Univariable" (unadjusted model with single predictor) or "Multivariable" (adjusted model with multiple predictors)

model_type

Character. Type of regression (e.g., "Logistic", "Linear", "Cox PH", "Poisson", etc.)

variable

Character. Variable name (for factor variables, the base variable name without the level)

group

Character. Group/level name for factor variables; empty string for continuous variables

n

Integer. Total sample size used in the model

n_group

Integer. Sample size for this specific variable level (factor variables only)

events

Integer. Total number of events in the model (for survival and logistic models)

events_group

Integer. Number of events for this specific variable level (for survival and logistic models with factor variables)

coefficient

Numeric. Raw regression coefficient (log odds, log hazard, etc.)

se

Numeric. Standard error of the coefficient

OR/HR/RR/Coefficient

Numeric. Effect estimate - column name depends on model type:

• OR for logistic regression (odds ratio)

• HR for Cox models (hazard ratio)

• RR for Poisson regression (rate/risk ratio)

• Coefficient for linear models or other GLMs

ci_lower

Numeric. Lower bound of confidence interval for effect estimate

ci_upper

Numeric. Upper bound of confidence interval for effect estimate

statistic

Numeric. Test statistic (z-value for GLM/Cox, t-value for LM)

p_value

Numeric. p-value for coefficient test

sig

Character. Significance markers: *** (p < 0.001), ** (p < 0.01), * (p < 0.05), . (p < 0.10).

sig_binary

Logical. Binary indicator: TRUE if p < 0.05, FALSE otherwise

reference

Character. Contains reference_label for reference category rows when reference_rows = TRUE, empty string otherwise

See Also

fit for the main regression interface, glmforest, coxforest, lmforest for forest plot visualization

Examples

# Load example data
data(clintrial)

# Example 1: Extract from logistic regression
glm_model <- glm(os_status ~ age + sex + treatment, 
                 data = clintrial, family = binomial)

glm_result <- m2dt(clintrial, glm_model)
glm_result



# Example 2: Extract from linear model
lm_model <- lm(los_days ~ age + sex + surgery, data = clintrial)

lm_result <- m2dt(clintrial, lm_model)
lm_result

# Example 3: Cox proportional hazards model
library(survival)
cox_model <- coxph(Surv(os_months, os_status) ~ age + sex + stage,
                   data = clintrial)

cox_result <- m2dt(clintrial, cox_model)
cox_result

# Example 4: Exclude intercept for cleaner tables
clean_result <- m2dt(clintrial, glm_model, include_intercept = FALSE)
clean_result

# Example 5: Change confidence level
result_90ci <- m2dt(clintrial, glm_model, conf_level = 0.90)
result_90ci

Multivariate Regression Analysis

Description

Performs regression analyses of a single predictor (exposure) across multiple outcomes. This function is designed for studies where a single exposure variable is tested against multiple endpoints, such as complication screening, biomarker associations, or phenome-wide association studies. Returns publication-ready formatted results with optional covariate adjustment. Supports interactions, mixed-effects models, stratification, and clustered standard errors.

Usage

multifit(
  data,
  outcomes,
  predictor,
  covariates = NULL,
  interactions = NULL,
  random = NULL,
  strata = NULL,
  cluster = NULL,
  model_type = "glm",
  family = "binomial",
  columns = "adjusted",
  p_threshold = 1,
  conf_level = 0.95,
  show_n = TRUE,
  show_events = TRUE,
  digits = 2,
  p_digits = 3,
  labels = NULL,
  predictor_label = NULL,
  include_predictor = TRUE,
  keep_models = FALSE,
  exponentiate = NULL,
  parallel = TRUE,
  n_cores = NULL,
  number_format = NULL,
  verbose = NULL,
  ...
)

Arguments

    options(summata.number_format = "eu")
  

Details

Analysis Approach:

The function implements a multivariate (multi-outcome) screening workflow that inverts the typical regression paradigm:

1. For each outcome in outcomes, fits a separate model with the predictor as the main exposure

2. If covariates specified, fits adjusted model: outcome ~ predictor + covariates + interactions

3. Extracts only the predictor effect(s) from each model, ignoring covariate coefficients

4. Combines results into a single table for comparison across outcomes

5. Optionally filters by p-value threshold

This is conceptually opposite to uniscreen(), which tests multiple predictors against a single outcome. Use multifit() when you have one exposure of interest and want to screen across multiple endpoints.

When to Use Multivariate Regression Analysis:

• Complication screening: Test one exposure (e.g., operative time, BMI, biomarker level) against multiple postoperative complications

• Treatment effects: Test one treatment against multiple efficacy and safety endpoints simultaneously

• Biomarker studies: Test one biomarker against multiple clinical outcomes to understand its prognostic value

• Phenome-wide association studies (PheWAS): Test genetic variants or exposures against many phenotypes

• Risk factor profiling: Understand how one risk factor relates to a spectrum of outcomes

Handling Categorical Predictors:

When the predictor is a factor variable with multiple levels:

• Each non-reference level gets its own row for each outcome

• Reference category is determined by factor level ordering

• The Predictor column shows "Variable (Level)" format (e.g., "Treatment (Drug A)", "Treatment (Drug B)")

• For binary variables with affirmative non-reference levels (Yes, 1, True, Present, Positive, +), shows just "Variable" (e.g., "Diabetes" instead of "Diabetes (Yes)")

• Effect estimates compare each level to the reference

Adjusted vs. Unadjusted Results:

When covariates is specified, the function fits both models but only extracts predictor effects:

• columns = "adjusted": Reports only covariate-adjusted effects. Column labeled "aOR/aHR," etc.

• columns = "unadjusted": Reports only crude effects. Column labeled "OR/HR," etc.

• columns = "both": Reports both side-by-side. Useful for identifying confounding (large change in effect) or independent effects (similar estimates)

Interaction Terms:

When interactions includes terms involving the predictor:

• Main effect of predictor is always reported

• Interaction effects are extracted and displayed with formatted names

• Format: Variable (Level) × Variable (Level) using multiplication sign notation

• Useful for testing effect modification (e.g., does treatment effect differ by sex?)

Mixed-Effects Models:

For clustered or hierarchical data (e.g., patients within hospitals):

• Use model_type = "glmer" with random = "(1|cluster)" for random intercept models

• Nested random effects: random = "(1|site/patient)"

• Crossed random effects: random = "(1|site) + (1|doctor)"

• For survival outcomes, use model_type = "coxme"

Stratification and Clustering (Cox models):

For Cox proportional hazards models:

• strata: Creates separate baseline hazards for each stratum level. Use when hazards are non-proportional across strata but stratum effects do not need to be estimated

• cluster: Computes robust (sandwich) standard errors accounting for within-cluster correlation. Alternative to mixed effects when only robust SEs are needed

Filtering based on p-value:

The p_threshold parameter filters results after fitting all models:

• Only outcomes with p less than or equal to the threshold are retained in output

• For factor predictors, outcome is kept if any level is significant

• Useful for focusing on significant associations in exploratory analyses

• Default is 1 (no filtering) - recommended for confirmatory analyses

Outcome Homogeneity:

All outcomes in a single multifit() call should be of the same type (all binary, all continuous, or all survival). Mixing outcome types produces tables with incompatible effect measures (e.g., odds ratios alongside regression coefficients), which can mislead readers. The function validates outcome compatibility and issues a warning when mixed types are detected.

For analyses involving multiple outcome types, run separate multifit() calls for each type:

# Binary outcomes
binary_results <- multifit(data, outcomes = c("death", "readmission"),
                           predictor = "treatment", model_type = "glm")

# Continuous outcomes
continuous_results <- multifit(data, outcomes = c("los_days", "cost"),
                               predictor = "treatment", model_type = "lm")

Effect Measures by Model Type:

• Logistic (model_type = "glm", family = "binomial"): Odds ratios (OR/aOR)

• Cox (model_type = "coxph"): Hazard ratios (HR/aHR)

• Poisson (model_type = "glm", family = "poisson"): Rate ratios (RR/aRR)

• Linear (model_type = "lm"): Coefficient estimates

• Mixed effects: Same as fixed-effects counterparts

Memory and Performance:

• parallel = TRUE (default) uses multiple cores for faster fitting

• keep_models = FALSE (default) discards model objects to save memory

• For many outcomes, parallel processing provides substantial speedup

• Set keep_models = TRUE only when you need model diagnostics

Value

A data.table with S3 class "multifit_result" containing formatted multivariate regression results. The table structure includes:

Outcome

Character. Outcome variable name or custom label

Predictor

Character. For factor predictors: formatted as "Variable (Level)" showing the level being compared to reference. For binary variables where the non-reference level is an affirmative value (Yes, 1, True, Present, Positive, +), shows just "Variable". For continuous predictors: the variable name. For interactions: the formatted interaction term (e.g., "Treatment (Drug A) × Sex (Male)")

n

Integer. Sample size used in the model (if show_n = TRUE)

Events

Integer. Number of events (if show_events = TRUE)

OR/HR/RR/Coefficient (95% CI)

Character. Unadjusted effect estimate with CI (if columns = "unadjusted" or "both")

aOR/aHR/aRR/Adj. Coefficient (95% CI)

Character. Adjusted effect estimate with CI (if columns = "adjusted" or "both")

Uni p / Multi p / p-value

Character. Formatted p-value(s). Column names depend on columns setting

The returned object includes the following attributes accessible via attr():

raw_data

data.table. Unformatted numeric results with separate columns for effect estimates, standard errors, confidence intervals, and p-values. Suitable for custom analysis or visualization

models

list (if keep_models = TRUE). Named list of fitted model objects, with outcome names as list names. Each element contains $unadjusted and/or $adjusted models depending on settings

predictor

Character. The predictor variable name

outcomes

Character vector. The outcome variable names

covariates

Character vector or NULL. The covariate variable names

interactions

Character vector or NULL. The interaction terms

random

Character or NULL. The random effects formula

strata

Character or NULL. The stratification variable

cluster

Character or NULL. The clustering variable

model_type

Character. The regression model type used

columns

Character. Which columns were displayed

analysis_type

Character. "multi_outcome" to identify analysis type

significant

Character vector. Names of outcomes with p < 0.05 for the predictor (uses adjusted p-values when available)

See Also

uniscreen for screening multiple predictors against one outcome, multiforest for creating forest plots from multifit results, fit for single-outcome regression with full coefficient output, fullfit for complete univariable-to-multivariable workflow

Other regression functions: compfit(), fit(), fullfit(), print.compfit_result(), print.fit_result(), print.fullfit_result(), print.multifit_result(), print.uniscreen_result(), uniscreen()

Examples

# Load example data
data(clintrial)
data(clintrial_labels)

# Example 1: Basic multivariate analysis (unadjusted)
# Test treatment effect on multiple binary outcomes
result1 <- multifit(
    data = clintrial,
    outcomes = c("surgery", "pfs_status", "os_status"),
    predictor = "treatment",
    labels = clintrial_labels,
    parallel = FALSE
)
print(result1)
# Shows odds ratios comparing Drug A and Drug B to Control



# Example 2: Adjusted analysis with covariates
# Adjust for age, sex, and disease stage
result2 <- multifit(
    data = clintrial,
    outcomes = c("surgery", "pfs_status", "os_status"),
    predictor = "treatment",
    covariates = c("age", "sex", "stage"),
    labels = clintrial_labels,
    parallel = FALSE
)
print(result2)
# Shows adjusted odds ratios (aOR)

# Example 3: Compare unadjusted and adjusted results
result3 <- multifit(
    data = clintrial,
    outcomes = c("surgery", "pfs_status", "os_status"),
    predictor = "treatment",
    covariates = c("age", "sex", "stage"),
    columns = "both",
    labels = clintrial_labels,
    parallel = FALSE
)
print(result3)
# Useful for identifying confounding effects

# Example 4: Continuous predictor across outcomes
# Test age effect on multiple outcomes
result4 <- multifit(
    data = clintrial,
    outcomes = c("surgery", "pfs_status", "os_status"),
    predictor = "age",
    covariates = c("sex", "treatment", "stage"),
    labels = clintrial_labels,
    parallel = FALSE
)
print(result4)
# One row per outcome for continuous predictor

# Example 5: Cox regression for survival outcomes
library(survival)
cox_result <- multifit(
    data = clintrial,
    outcomes = c("Surv(pfs_months, pfs_status)", 
                 "Surv(os_months, os_status)"),
    predictor = "treatment",
    covariates = c("age", "sex", "stage"),
    model_type = "coxph",
    labels = clintrial_labels,
    parallel = FALSE
)
print(cox_result)
# Returns hazard ratios (HR/aHR)

# Example 6: Cox with stratification by site
cox_strat <- multifit(
    data = clintrial,
    outcomes = c("Surv(os_months, os_status)"),
    predictor = "treatment",
    covariates = c("age", "sex"),
    strata = "site",
    model_type = "coxph",
    labels = clintrial_labels,
    parallel = FALSE
)
print(cox_strat)

# Example 7: Cox with clustered standard errors
cox_cluster <- multifit(
    data = clintrial,
    outcomes = c("Surv(os_months, os_status)"),
    predictor = "treatment",
    covariates = c("age", "sex", "stage"),
    cluster = "site",
    model_type = "coxph",
    labels = clintrial_labels,
    parallel = FALSE
)
print(cox_cluster)

# Example 8: Interaction between predictor and covariate
# Test if treatment effect differs by sex
result_int <- multifit(
    data = clintrial,
    outcomes = c("surgery", "os_status"),
    predictor = "treatment",
    covariates = c("age", "sex", "stage"),
    interactions = c("treatment:sex"),
    labels = clintrial_labels,
    parallel = FALSE
)
print(result_int)
# Shows main effects and interaction terms with × notation

# Example 9: Linear model for continuous outcomes
linear_result <- multifit(
    data = clintrial,
    outcomes = c("los_days", "biomarker_x"),
    predictor = "treatment",
    covariates = c("age", "sex"),
    model_type = "lm",
    labels = clintrial_labels,
    parallel = FALSE
)
print(linear_result)
# Returns coefficient estimates, not ratios

# Example 10: Poisson regression for equidispersed count outcomes
# fu_count has variance ~= mean, appropriate for standard Poisson
poisson_result <- multifit(
    data = clintrial,
    outcomes = c("fu_count"),
    predictor = "treatment",
    covariates = c("age", "stage"),
    model_type = "glm",
    family = "poisson",
    labels = clintrial_labels,
    parallel = FALSE
)
print(poisson_result)
# Returns rate ratios (RR)
# For overdispersed counts (ae_count), use model_type = "negbin" instead

# Example 11: Filter to significant results only
sig_results <- multifit(
    data = clintrial,
    outcomes = c("surgery", "pfs_status", "os_status"),
    predictor = "stage",
    p_threshold = 0.05,
    labels = clintrial_labels,
    parallel = FALSE
)
print(sig_results)
# Only outcomes with significant associations shown

# Example 12: Custom outcome labels
result_labeled <- multifit(
    data = clintrial,
    outcomes = c("surgery", "pfs_status", "os_status"),
    predictor = "treatment",
    labels = c(
        surgery = "Surgical Resection",
        pfs_status = "Disease Progression",
        os_status = "Death",
        treatment = "Treatment Group"
    ),
    parallel = FALSE
)
print(result_labeled)

# Example 13: Keep models for diagnostics
result_models <- multifit(
    data = clintrial,
    outcomes = c("surgery", "os_status"),
    predictor = "treatment",
    covariates = c("age", "sex"),
    keep_models = TRUE,
    parallel = FALSE
)

# Access stored models
models <- attr(result_models, "models")
names(models)

# Get adjusted model for surgery outcome
surgery_model <- models$surgery$adjusted
summary(surgery_model)

# Example 14: Access raw numeric data
result <- multifit(
    data = clintrial,
    outcomes = c("surgery", "os_status"),
    predictor = "age",
    parallel = FALSE
)

# Get unformatted results for custom analysis
raw_data <- attr(result, "raw_data")
print(raw_data)
# Contains exp_coef, ci_lower, ci_upper, p_value, \emph{etc.}

# Example 15: Hide sample size and event columns
result_minimal <- multifit(
    data = clintrial,
    outcomes = c("surgery", "os_status"),
    predictor = "treatment",
    show_n = FALSE,
    show_events = FALSE,
    parallel = FALSE
)
print(result_minimal)

# Example 16: Customize decimal places
result_digits <- multifit(
    data = clintrial,
    outcomes = c("surgery", "os_status"),
    predictor = "age",
    digits = 3,
    p_digits = 4,
    parallel = FALSE
)
print(result_digits)

# Example 17: Force coefficient display (no exponentiation)
result_coef <- multifit(
    data = clintrial,
    outcomes = c("surgery"),
    predictor = "age",
    exponentiate = FALSE,
    parallel = FALSE
)
print(result_coef)

# Example 18: Complete publication workflow
final_table <- multifit(
    data = clintrial,
    outcomes = c("surgery", "pfs_status", "os_status"),
    predictor = "treatment",
    covariates = c("age", "sex", "stage", "grade"),
    columns = "both",
    labels = clintrial_labels,
    digits = 2,
    p_digits = 3,
    parallel = FALSE
)
print(final_table)

# Example 19: Gamma regression for positive continuous outcomes
gamma_result <- multifit(
    data = clintrial,
    outcomes = c("los_days", "recovery_days"),
    predictor = "treatment",
    covariates = c("age", "surgery"),
    model_type = "glm",
    family = Gamma(link = "log"),
    labels = clintrial_labels,
    parallel = FALSE
)
print(gamma_result)
# Returns multiplicative effects on positive continuous data

# Example 20: Quasipoisson for overdispersed counts
quasi_result <- multifit(
    data = clintrial,
    outcomes = c("ae_count"),
    predictor = "treatment",
    covariates = c("age", "diabetes"),
    model_type = "glm",
    family = "quasipoisson",
    labels = clintrial_labels,
    parallel = FALSE
)
print(quasi_result)
# Adjusts standard errors for overdispersion

# Example 21: Generalized linear mixed effects (GLMER)
# Test treatment across outcomes with site clustering
if (requireNamespace("lme4", quietly = TRUE)) {
    glmer_result <- suppressWarnings(multifit(
        data = clintrial,
        outcomes = c("surgery", "pfs_status", "os_status"),
        predictor = "treatment",
        covariates = c("age", "sex"),
        random = "(1|site)",
        model_type = "glmer",
        family = "binomial",
        labels = clintrial_labels,
        parallel = FALSE
    ))
    print(glmer_result)
}

# Example 22: Cox mixed effects with random site effects
if (requireNamespace("coxme", quietly = TRUE)) {
    coxme_result <- multifit(
        data = clintrial,
        outcomes = c("Surv(pfs_months, pfs_status)", 
                     "Surv(os_months, os_status)"),
        predictor = "treatment",
        covariates = c("age", "sex", "stage"),
        random = "(1|site)",
        model_type = "coxme",
        labels = clintrial_labels,
        parallel = FALSE
    )
    print(coxme_result)
}

# Example 23: Multiple interactions across outcomes
multi_int <- multifit(
    data = clintrial,
    outcomes = c("surgery", "pfs_status", "os_status"),
    predictor = "treatment",
    covariates = c("age", "sex", "stage"),
    interactions = c("treatment:stage", "treatment:sex"),
    labels = clintrial_labels,
    parallel = FALSE
)
print(multi_int)
# Shows how treatment effects vary by stage and sex across outcomes

Create Forest Plot for Multivariate Regression

Description

Generates a publication-ready forest plot from a multifit() output object. The plot displays effect estimates (OR, HR, RR, or coefficients) with confidence intervals across multiple outcomes, organized by outcome with the predictor levels shown for each.

Usage

multiforest(
  x,
  title = "Multivariate Analysis",
  effect_label = NULL,
  column = "adjusted",
  digits = 2,
  p_digits = 3,
  conf_level = 0.95,
  font_size = 1,
  annot_size = 3.88,
  header_size = 5.82,
  title_size = 23.28,
  plot_width = NULL,
  plot_height = NULL,
  table_width = 0.6,
  show_n = TRUE,
  show_events = NULL,
  show_predictor = NULL,
  covariates_footer = TRUE,
  indent_predictor = FALSE,
  bold_variables = TRUE,
  center_padding = 4,
  zebra_stripes = TRUE,
  color = NULL,
  null_line = NULL,
  log_scale = NULL,
  labels = NULL,
  units = "in",
  number_format = NULL
)

Arguments

    options(summata.number_format = "eu")
  

Details

Plot Layout:

The forest plot is organized with outcomes as grouping headers and predictor levels (or interaction terms) as rows within each outcome. This provides a clear visual comparison of how a single predictor affects multiple outcomes.

1. Title: Centered at top

2. Data Table (left): Contains:

   • Outcome column (or grouped headers)

   • Predictor/Group column

   • n: Sample sizes (optional)

   • Events: Event counts (optional, for applicable models)

   • Effect (95% CI); p-value

3. Forest Plot (right):

   • Point estimates (squares)

   • 95% confidence intervals

   • Reference line at null value (1 or 0)

   • Log scale for ratio measures

Data Source:

The function extracts effect estimates directly from the multifit output object's raw_data attribute, which contains the numeric values needed for plotting. This approach is efficient and ensures consistency with the formatted table output.

Value

A ggplot object containing the complete forest plot. The plot can be:

• Displayed directly: print(plot)

• Saved to file: ggsave("forest.pdf", plot, width = 12, height = 8)

• Further customized with ggplot2 functions

The returned object includes an attribute "rec_dims" accessible via attr(plot, "rec_dims"), which is a list containing:

width

Numeric. Recommended plot width in specified units

height

Numeric. Recommended plot height in specified units

These recommendations are automatically calculated based on the number of variables, text sizes, and layout parameters, and are printed to console if plot_width or plot_height are not specified.

See Also

autoforest for automatic model detection, multifit for multi-outcome regression analysis, glmforest for single GLM forest plots, coxforest for single Cox model forest plots, lmforest for single linear model forest plots, uniforest for univariable screening forest plots

Other visualization functions: autoforest(), coxforest(), glmforest(), lmforest(), uniforest()

Examples

data(clintrial)
data(clintrial_labels)
library(survival)

# Create example multifit result
result <- multifit(
    data = clintrial,
    outcomes = c("surgery", "pfs_status", "os_status"),
    predictor = "treatment",
    covariates = c("age", "sex", "stage"),
    parallel = FALSE
)

# Example 1: Basic multivariate forest plot
p <- multiforest(result)



old_width <- options(width = 180)

# Example 2: With custom title and labels
plot2 <- multiforest(
    result,
    title = "Treatment Effects Across Clinical Outcomes",
    labels = clintrial_labels
)

# Example 3: Customize appearance
plot3 <- multiforest(
    result,
    color = "#E74C3C",
    zebra_stripes = TRUE,
    labels = clintrial_labels
)

# Example 4: Save with recommended dimensions
dims <- attr(plot3, "rec_dims")
ggplot2::ggsave(file.path(tempdir(), "multioutcome_forest.pdf"),
                plot3, width = dims$width, height = dims$height)

options(old_width)

Normalize model type names

Description

Converts model class names to standardized model type strings.

Usage

normalize_model_type(model_type)

Arguments

Value

Normalized character string (e.g., "lmerMod" becomes "lmer").

Number Formatting Utilities

Description

Internal utilities for locale-aware number formatting across all summata output functions. Supports preset locales (US, European, SI/ISO, plain) and fully custom separator definitions.

Global Option

The default number format can be set once per session:

  options(summata.number_format = "eu")

This avoids passing number_format to every function call.

Order comparison columns based on model type

Description

Reorders columns in the comparison table to follow a logical sequence appropriate for the model type.

Usage

order_comparison_columns(comparison, model_type)

Arguments

Value

Data.table with reordered columns.

Parse term into variable and group

Description

Splits coefficient term names into base variable names and factor levels. For example, "sexMale" becomes variable="sex" and group="Male". Handles interaction terms and continuous variables appropriately.

Usage

parse_term(terms, xlevels = NULL, model = NULL)

Arguments

Value

Data.table with 'variable' and 'group' columns.

Perform statistical tests for categorical variables

Description

Conducts chi-square or Fisher's exact tests for categorical variables across groups. Automatically selects Fisher's exact test for small expected frequencies.

Usage

perform_categorical_test(tab, test_type)

Arguments

Value

Numeric p-value from the hypothesis test.

Perform statistical tests for continuous variables

Description

Conducts hypothesis tests comparing continuous variables across groups. Supports t-tests, Wilcoxon tests, ANOVA, and Kruskal-Wallis tests with automatic selection based on number of groups.

Usage

perform_continuous_test(var_vec, grp_vec, test_type, stat_type)

Arguments

Value

Numeric p-value from the hypothesis test.

Perform survival comparison test

Description

Performs statistical test comparing survival curves across groups.

Usage

perform_survival_test(surv_obj, group_var, test_type)

Arguments

Value

List with test statistic, p-value, and test type.

Print method showing scoring methodology

Description

Print method showing scoring methodology

Usage

## S3 method for class 'compfit_result'
print(x, ...)

Arguments

Value

Invisibly returns the input object x. Called for its side effect of printing a formatted summary to the console.

See Also

Other regression functions: compfit(), fit(), fullfit(), multifit(), print.fit_result(), print.fullfit_result(), print.multifit_result(), print.uniscreen_result(), uniscreen()

Print method for fit results

Description

Displays a summary header with model scope (Univariable/Multivariable), model type, formula, sample size, and event count before printing the formatted results table.

Usage

## S3 method for class 'fit_result'
print(x, ...)

Arguments

Value

Invisibly returns the input object x. Called for its side effect of printing a formatted summary to the console.

See Also

Other regression functions: compfit(), fit(), fullfit(), multifit(), print.compfit_result(), print.fullfit_result(), print.multifit_result(), print.uniscreen_result(), uniscreen()

Print method for fullfit results

Description

Displays a summary header with outcome, model type, method, and number of multivariable predictors before printing the results table.

Usage

## S3 method for class 'fullfit_result'
print(x, ...)

Arguments

Value

Invisibly returns the input object x. Called for its side effect of printing a formatted summary to the console.

See Also

Other regression functions: compfit(), fit(), fullfit(), multifit(), print.compfit_result(), print.fit_result(), print.multifit_result(), print.uniscreen_result(), uniscreen()

Print method for multifit results

Description

Print method for multifit results

Usage

## S3 method for class 'multifit_result'
print(x, ...)

Arguments

Value

Invisibly returns the input object x. Called for its side effect of printing a formatted summary to the console.

See Also

Other regression functions: compfit(), fit(), fullfit(), multifit(), print.compfit_result(), print.fit_result(), print.fullfit_result(), print.uniscreen_result(), uniscreen()

Print method for survtable

Description

Print method for survtable

Usage

## S3 method for class 'survtable'
print(x, ...)

Arguments

Value

Invisibly returns the input object x. Called for its side effect of printing a formatted summary to the console.

See Also

Other descriptive functions: desctable(), survtable()

Print method for table2docx results

Description

Print method for table2docx results

Usage

## S3 method for class 'table2docx_result'
print(x, ...)

Arguments

Value

Invisibly returns the input object x. Called for its side effect of printing a formatted summary to the console.

Print method for table2pptx results

Description

Print method for table2pptx results

Usage

## S3 method for class 'table2pptx_result'
print(x, ...)

Arguments

Value

Invisibly returns the input object x. Called for its side effect of printing a formatted summary to the console.

Print method for table2rtf results

Description

Print method for table2rtf results

Usage

## S3 method for class 'table2rtf_result'
print(x, ...)

Arguments

Value

Invisibly returns the input object x. Called for its side effect of printing a formatted summary to the console.

Print method for uniscreen results

Description

Print method for uniscreen results

Usage

## S3 method for class 'uniscreen_result'
print(x, ...)

Arguments