summata

summata | /suːˈmɑːtə/ | Latin, n. pl. of summātum, gerundive of summāre: those that have been summarized

Concise, publication-ready statistical summaries.

Overview

The summata package provides a comprehensive framework for generating summary tables and visualizations from statistical analyses. Built on data.table for computational efficiency, it streamlines the workflow from descriptive statistics, through regression modeling, to final output—all using a unified interface with standardized, presentation-ready results.

For a more comprehensive description of this package and its features, see the full documentation and vignettes.

Installation

This package is not yet on CRAN. Install it from GitHub (stable) or Codeberg (development):

# Stable release
devtools::install_github("phmcc/summata")

# Development version
devtools::install_git("https://codeberg.org/phmcc/summata.git")

Package Composition

Design Principles

The architecture of summata reflects three guiding principles:

1. Consistent syntax. All modeling functions share a common signature: data first, followed by the outcome or variable of interest, then constituent/modifying variables. This convention facilitates both pipe-based workflows and pedagogical clarity.

2. Transparent computation. Functions attach their underlying model objects and raw numerical results as attributes, permitting verification of computations or extension of analyses beyond the formatted output.

3. Separation of concerns. Analysis, formatting, and export constitute distinct operations, allowing each stage to be modified independently.

These principles manifest in the standard calling convention:

result <- fit(data, variable, c("var1", "var2", ..., "varN"), ...)

where data is the dataset, variable is the variable of interest (dependent variable, endpoint/outcome, stratification/grouping variable, etc.), and c("var1", "var2", ..., "varN")is a vector of constituent/modifying variables (independent variables, model covariates, compared/explanatory factors, etc.). The result is a formatted table for export, with readily accessible attributes for further analysis.

# The formatted table
print(result)

# The underlying model object
model <- attr(result, "model")

# Raw numerical results
raw <- attr(result, "raw_data")

Functional Reference

This package provides a variety of functions for different stages of statistical analysis:

Descriptive analysis

Tables to provide quick summary data and comparison tests between different groups.

Predictive analysis

Fitted univariable and multivariable regression results for predictive modeling.

Table export

Export of finalized tables to various commonly used formats.

Data visualization

Generation of publication-ready forest plot graphics to summarize regression models.

Supported Model Classes

The following regression models are currently supported by summata. Specify the model using the model_type parameter in the appropriate regression function (uniscreen(), fit(), fullfit(), compfit(), or multifit()):

*with log link; coefficient with identity link

Comparison with Related Packages

The R ecosystem includes several established packages for regression table generation. The following comparison identifies areas of overlap and distinction:

_{✓ Full support | ◐ Partial support | — Not available}

A detailed feature comparison is available in the package documentation.

Illustrative Example

The clintrial dataset included with this package provides simulated clinical trial data comprising patient identifiers, baseline characteristics, therapeutic interventions, short-term outcomes, and long-term survival statistics. The following example demonstrates how summata functions can be used to analyze perioperative factors affecting 30-day hospital readmission.

Step 0: Data Preparation

Prior to analysis, load the dataset, apply labels, and define predictors:

library(summata)

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

# Define candidate predictors
predictors <- c("age", "sex", "race", "ethnicity", "bmi", "smoking",
                "hypertension", "diabetes", "ecog", "creatinine",
                "hemoglobin", "biomarker_x", "biomarker_y", "grade",
                "treatment", "surgery", "los_days", "stage")

Step 1: Descriptive Statistics

Use the desctable() function to generate summary statistics with stratification by a grouping variable (in this case, 30-day readmission):

table1 <- desctable(
    data = clintrial,
    by = "readmission_30d",
    variables = predictors,
    labels = clintrial_labels
)

table2pdf(table1, "table1.pdf",
          caption = "\\textbf{Table 1} - Baseline characteristics by 30-day readmission status",
          paper = "auto",
          condense_table = TRUE,
          dark_header = TRUE,
          zebra_stripes = TRUE
)

Step 2: Regression Analysis

Perform an integrated univariable-to-multivariable regression workflow using the fullfit() function:

table2 <- fullfit(
    data = clintrial,
    outcome = "readmission_30d",
    predictors = predictors,
    method = "screen",
    p_threshold = 0.05,
    model_type = "glm",
    labels = clintrial_labels
)

table2pdf(table2, "table2.pdf",
          caption = "\\textbf{Table 2} - Predictors of 30-day readmission, multivariable Cox regression with univariable screen",
          paper = "auto",
          condense_table = TRUE,
          dark_header = TRUE,
          zebra_stripes = TRUE
)

Step 3: Forest Plot

Finally, generate a forest plot to provide a graphical representation of effect estimates using the glmforest() function:

forest_30d <- glmforest(table2,
                        title = "Factors Affecting 30-Day Readmission",
                        labels = clintrial_labels,
                        indent_groups = TRUE
                        )

ggsave("forest_30d.pdf", forest_30d,
       width = attr(forest_30d, "rec_dims")$width,
       height = attr(forest_30d, "rec_dims")$height, 
       units = "in")

Development

Repository

• Primary development: codeberg.org/phmcc/summata
• GitHub releases: github.com/phmcc/summata

Contributing

Bug reports and feature requests may be submitted via the issue tracker. Contributions are welcome; please consult the contributing guidelines prior to submitting pull requests.

Acknowledgments

The design of summata draws inspiration from several existing packages:

• finalfit (Harrison) — Regression workflow concepts
  
• gtsummary (Sjoberg et al.) — Table generation architecture
  
• arsenal (Heinzen et al.) — Descriptive statistics methodology
  
• data.table (Dowle & Srinivasan) — High-performance data operations

License

GPL (>= 3.0)

Citation

citation("summata")

To cite summata in publications, use:

  McClelland PH (2026). _summata: Publication-Ready Summary Tables and Forest Plots_. R package version 0.11.0, <https://phmcc.github.io/summata/>.

A BibTeX entry for LaTeX users is

  @Manual{,
    title = {summata: Publication-Ready Summary Tables and Forest Plots},
    author = {Paul Hsin-ti McClelland},
    year = {2026},
    note = {R package version 0.11.0},
    url = {https://phmcc.github.io/summata/},
  }

Further Resources

• Function documentation: ?function_name or the reference index
• Vignettes: vignette("summata") or online articles
• Issue tracker: Codeberg Issues, GitHub Issues

_{The summata package is under active development. The API may change prior to CRAN submission.}