r-tables-reporting

name	r-tables-reporting
description	Build publication-ready R tables, figures, and reporting artifacts with gtsummary, flextable, gt, officer, Quarto, and domain-specific reporting patterns. Use for polished table, figure, and report outputs.
argument-hint	["table","figure","or report task"]
paths	["**/*.Rmd","**/*.qmd","**/reports/**/*.R","**/report/**/*.R"]

R Tables Reporting

Build tables as deterministic reporting surfaces: get the variable semantics right first, make formatting explicit, and keep export wrappers thin.

Quick start

1. Read references/gtsummary-edge-cases.md for package behavior that often surprises us.
2. Read references/reporting-patterns.md for the shared formatting and export layer.
3. Read references/recurring-clinical-table-edge-cases.md when the task looks like a clinician-facing Table 1 or a heavily customized summary.
4. Read references/journal-table-figure-style-guides.md when the target journal family is known or when the user asks for journal-specific table/figure style.
5. Read references/pediatric-oncology-and-asthma-journal-guides.md when the target area is pediatric oncology or pediatric asthma and the user wants disease-aware journal doctrine for tables and figures.
6. Read references/pediatric-endpoint-family-reporting.md when the task involves Kaplan-Meier summaries, cumulative-incidence reporting, cause-specific or Fine-Gray regression tables, recurrent-event outputs, rate tables, or longitudinal trajectory reporting.
7. Read references/publication-presets-and-scope-summaries.md when the task includes named table/model presets, app previews, scope chips, or export of the exact table-input slice.
8. Read references/interactive-figure-companions.md when the work includes HTML/interactive companion figures, Shiny-linked figures, or publication figures that should share one canonical ggplot specification.
9. Read references/interactive-table-companions.md when the work includes reactable, DT, Shiny-linked tables, sortable/filterable HTML companions, or publication tables that should share one canonical reporting tibble with an interactive surface.
10. Read references/quarto-parameterized-reporting.md when the deliverable is a Quarto document, parameterized report family, dashboard-style report, or targets-managed report surface.
11. Read references/journal-facing-model-output-figure-presets.md when the task involves forest plots, adjusted-prediction figures, Kaplan-Meier or cumulative-incidence figures, journal-aware legends, ratio-scale effect plots, or model-output figure presets.
12. Read references/marginal-effects-reporting.md when the source is an adjusted-prediction, comparison, or slope table from marginaleffects.
13. Read references/survey-weighted-table-reporting.md when the source is a complex survey design, a tbl_svysummary() table, weighted proportions, or survey-aware p-values.
14. Read references/bayesian-reporting-surfaces.md when the task involves brms, posterior summaries, credible or HDI/QI intervals, posterior predictive ribbons, tidybayes, ggdist, or Bayesian figure captions.
15. Read references/causal-balance-and-effect-reporting.md when the task involves MatchIt, WeightIt, cobalt, balance tables, Love plots, weight summaries, matched-sample flow counts, or effect tables that need design metadata.
16. Read references/meta-analysis-reporting.md when the task involves metafor, forest plots, funnel plots, moderator tables, heterogeneity summaries, or sensitivity diagnostics across studies.
17. Read references/easystats-reporting-surfaces.md when the task involves diagnostics tables, parameter summaries from model_parameters(), effect-size reporting from effectsize, or prose/report surfaces from report.
18. Read references/gee-reporting-surfaces.md when the task involves geeglm(), geese(), QIC(), working-correlation comparison tables, or reporting population-averaged repeated-measure effects.
19. Read references/sem-reporting-with-lavaan.md when the task involves lavaan, cfa(), sem(), growth(), fit measures, standardized solutions, parameter estimates, modification-index appendices, latent scores, or nested-model comparison tables.
20. Read references/predictive-performance-reporting.md when the task involves ROC curves, precision-recall curves, AUC summaries, Brier score, calibration plots, threshold tables, decision curves, net benefit, pROC, probably, or rmda.
21. Read references/bootstrap-and-permutation-reporting.md when the task involves bootstrap interval tables, BCa or studentized interval labels, resampling-method footnotes, permutation p-values, null-distribution figures, boot.ci(), int_pctl(), or infer resampling outputs.
22. Read references/gam-reporting.md when the task involves nonlinear smooth terms, splines, mgcv, gam(), bam(), s(), te(), ti(), t2(), ns(), smooth-effect plots, or concurvity-aware reporting.
23. Classify every column up front: continuous, categorical, dichotomous event row, grouping variable, display-only label, post-estimation estimand column, posterior-summary column, causal-design display field, meta-analysis display field, easystats summary field, GEE display field, SEM display field, predictive-performance display field, bootstrap or permutation display field, GAM display field, or survey-weighted display field.
24. Declare type=, value=, statistic=, digits=, label=, and missingness behavior before touching modify_table_body().
25. Decide the figure or table-companion family up front too: raw-value distribution plot, point-range effect plot, Kaplan-Meier curve, cumulative-incidence curve, posterior interval plot, posterior lineribbon, Love plot, forest plot, funnel plot, diagnostic plot, parameter summary plot, GEE comparison table, SEM fit table, SEM parameter table, ROC curve, precision-recall curve, calibration plot, decision curve, bootstrap interval plot, null-distribution histogram or density, smooth-effect plot, tensor-surface plot, weight-distribution summary, frequency bar chart, interactive companion figure, interactive companion table, Quarto dashboard/report surface, or other journal-appropriate display.
26. Export through a compact as_flex_table() / gt wrapper, an interactive-table companion, a parameterized Quarto surface, or a journal-appropriate figure file and smoke-check the final object.

Workflow

1. Choose the reporting surface deliberately

• Use gtsummary::tbl_summary() for Table 1 style summaries.
• Use gtsummary::tbl_strata() or tbl_strata2() for repeated per-stratum tables.
• Use gtsummary::tbl_regression() when the source is a model or a tidy coefficient table.
• Use gtsummary::tbl_survfit() for milestone Kaplan-Meier summaries or percentile-style survival summaries built from survfit() objects.
• Use a custom tibble plus flextable, gt, or as_gtsummary() when the table is mostly display logic rather than summary logic, especially for cumulative-incidence summaries from cuminc() / timepoints() or Fine-Gray outputs that arrive as custom tidy data.
• Use a custom tibble plus flextable/gt for most marginaleffects outputs because they are post-estimation data frames rather than raw coefficient objects.
• For Quarto, HTML, LaTeX, or Typst drafts, the package-native print(x, style = "tinytable") path can be a good first reporting surface when the default columns already match the audience need.

For figures:

• use a frequency bar chart only when the journal actually wants counts/rates shown as bars;
• use point/interval or line-based figures when the display is about estimates and uncertainty rather than filled area;
• choose a journal-facing model-output figure preset when the source is a modeled estimate, adjusted prediction, survival curve, or cumulative-incidence curve;
• and pick the figure form only after the estimand and journal target are both clear.

1b. Keep interactive companion tables tied to the same reporting tibble

• Normalize one reporting-ready tibble before adding reactable or DT wrappers so the interactive companion inherits the same labels, digits, footnotes, missingness semantics, and estimand metadata as the static table.
• Choose the interactive surface deliberately. reactable fits curated companion tables with details rows, row selection, rich theming, and Shiny-aware state helpers; DT fits dense search/filter/paging flows, editable tables, and JavaScript callback or proxy behavior.
• Declare whether search, column filters, row selection, and current page affect downloads, copied values, or manuscript-facing excerpts. That contract should be visible in the reporting helper instead of being left to the app layer to guess.
• When a figure and table are linked, keep stable keys explicit so the same row, estimate, or subgroup can be identified after sorting, filtering, or pagination.
• Keep the static table and the interactive companion aligned on column order, estimate labels, confidence-interval strings, and footnote meaning even when the companion allows re-sorting or hiding columns.
• Keep engine-specific styling at the table layer first: reactableTheme() and colDef() for reactable, or documented DT options and callbacks for DataTables. Broader CSS should refine a clear base table contract rather than carry all of the semantics.

1c. Keep survey-weighted reporting contracts explicit

• Current tbl_svysummary() documentation says the input is a survey.design object and keeps percent = c("column", "row", "cell") explicit. Keep weighted percentage semantics visible in the reporting helper.
• The same documentation exposes weighted and unweighted fields such as {n}, {N}, {p}, {n_unweighted}, {N_unweighted}, and {p_unweighted}, plus {deff}. Keep weighted and unweighted counts or design effects distinct when the table contract includes them.
• Current add_p.tbl_svysummary() documentation says the default tests are svy.wilcox.test for continuous variables and svy.chisq.test for categorical variables. Keep those defaults visible when the table is survey-aware.
• Team doctrine: survey tables should make it easy for the reader to tell that design-based weighting and design-based p-values are in play.

2. Make variable semantics explicit

• Declare dichotomous variables explicitly when a single event row is required.
• Keep parent availability indicators and child yes/no rows conceptually separate.
• Convert missing by= values into an explicit level whenever they must appear in output.
• Preserve human-facing labels on the columns before building the table.
• Preserve estimand labels too: adjusted prediction, risk difference, risk ratio, average marginal effect, elasticity, and response/link scale should remain visible.

3. Centralize formatting

• Keep raw numerics available until the last display step.
• Format p-values, estimate/CI strings, and display labels through a shared wrapper layer.
• Keep the same rounding and threshold rules across tables, Shiny previews, and report exports.
• Keep confidence interval presentation and scale labels aligned with the underlying estimand.
• Keep figure legends, axis labels, uncertainty definitions, and any ratio-scale posture aligned with the same estimand metadata rather than hand-tuned after export.

4. Treat row surgery as a final pass

• Get the base table structure correct first.
• Use modify_table_body() only for true structural or presentational cleanup.
• Keep each row-surgery step narrow so it stays testable and easy to reverse.

5. Pick inferential defaults intentionally

• Confirm whether the dataset is sparse enough that Fisher’s exact test should be declared explicitly.
• Keep dichotomous event values and displayed estimands aligned with the study question.
• When regression tables come from custom estimands, feed a tidy table through tidy_fun= instead of forcing a class mismatch.
• When the result comes from marginaleffects, keep the contrast or slope definition visible rather than flattening it into a generic coefficient label.
• When the result comes from survival, competing-risk, recurrent-event, or rate models, keep the endpoint family, time origin, event definition, and any offset unit visible in the table or its footnotes.

5b. Keep posterior quantities and interval semantics explicit

• Current tidybayes documentation supports interval summaries such as median_qi() and related tidy posterior summaries. Keep the chosen point summary and interval type visible in the table header, footnote, or figure caption.
• Current ggdist documentation supports point-interval, half-eye, and lineribbon displays for uncertainty. Match the reporting surface to the posterior quantity: point-interval displays for discrete coefficients or scenario contrasts, lineribbons for ordered x-axis functions, and predictive intervals only when future-observation uncertainty is the actual reporting target.
• Current brms documentation distinguishes expected-response draws from posterior predictive draws. Keep that quantity choice visible in captions and footnotes so readers can tell whether a ribbon or interval summarizes the modeled mean response or future observations.
• Current posterior documentation keeps draw summaries and diagnostics explicit. When a posterior table is central to the report, consider whether convergence or effective-sample-size diagnostics belong in a supplement, appendix, or analyst-facing QC table.
• Team doctrine: every Bayesian reporting surface should name the posterior quantity, interval type, interval width, and scale.

5c. Keep causal-design metadata visible in balance and effect reporting

• Current summary.matchit() documentation reports balance before and after matching. Keep both surfaces available when reporting the quality of a matched design.
• Current cobalt documentation positions bal.tab() and love.plot() as primary balance-reporting surfaces across matching, weighting, and subclassification workflows. Treat balance tables and Love plots as part of the main design narrative rather than as undocumented analyst side work.
• Current weightit() and trim() documentation expose estimand, focal group, weight ranges, extreme weights, and effective sample sizes. Carry that design metadata into the balance table, figure caption, or effect-table footnote when weighting is the design stage.
• Current MatchIt effect-estimation guidance shows matched analysis frames carrying distance, weights, and subclass. When matched-sample effect tables are produced, keep the design method and resulting target population visible in the title, subtitle, footnote, or companion text.
• Current glm_weightit() documentation says weighted effect models can account for the estimation of weights in the covariance matrix when supported. When that uncertainty posture is used, state it in the reporting surface or nearby methods note.
• Team doctrine: pair the causal effect estimate with a compact account of the design that produced it.

5d. Keep meta-analysis model structure visible in synthesis reporting

• Current forest.rma() documentation supports model-aware additions such as pooled estimates and prediction intervals. Keep the forest plot aligned with the fitted synthesis model and any prediction-interval choice.
• Current rma.uni() and rma.mv() documentation keep the model family and dependency structure explicit. Carry that synthesis posture into the table title, caption, footnote, or methods note when presenting pooled results.
• Current funnel() and regtest() documentation provide asymmetry and small-study-effect diagnostics. Treat funnel plots and asymmetry tests as diagnostic companions to the synthesis rather than isolated headline results.
• Current leave1out() and influence() documentation support sensitivity summaries across studies. When one or a few studies materially affect the pooled result, keep that information visible in an appendix or companion table.
• Team doctrine: meta-analysis reports should carry the effect measure, heterogeneity posture, dependency structure, moderator status, and key sensitivity diagnostics alongside the pooled estimate.

5e. Keep easystats summaries tied to the underlying statistical object

• Current parameters::model_parameters() documentation supports a broad, tidy parameter surface with explicit standardization and exponentiation options. Keep those choices visible in the table subtitle, column labels, or footnotes when they change interpretation.
• Current performance documentation exposes diagnostic summaries and comparison surfaces such as model_performance() and compare_performance(). Treat diagnostics tables as distinct reporting objects from coefficient tables so fit metrics and inferential estimates do not blur together.
• Current effectsize documentation supports both general and dedicated effect-size functions. When an effect-size column or table is reported, keep the metric family explicit instead of flattening all standardized quantities into one generic label.
• Current report documentation produces narrative communication layers built from checked and summarized statistical objects. Keep report-style prose or markdown surfaces aligned with the same parameter, effect-size, and diagnostic objects that feed the tables.
• Current see documentation provides plot methods for easystats outputs. When figures are generated from easystats objects, keep the plotted summary tied to the same object used in the corresponding table or prose section.
• Team doctrine: diagnostics tables, parameter tables, effect-size tables, and narrative report text should all point back to the same checked model object and the same explicit summary options.

5f. Keep GEE working-correlation and cluster metadata visible in reporting

• Current geeglm() documentation says the fit depends on an explicit cluster id, contiguous cluster rows, and optional waves ordering. Keep the cluster unit and repeated-measure ordering visible in the methods note, footnote, or table subtitle when they matter to interpretation.
• The same documentation keeps corstr, std.err, scale.fix, and scale.value explicit. Report the working-correlation structure and standard-error method alongside the coefficient table instead of leaving them implicit.
• Current QIC() documentation distinguishes QIC, QICu, and CIC for different comparison tasks. When alternative mean models or working-correlation structures were compared, keep the comparison rule visible in the reporting table or appendix.
• Current geese() documentation supports more advanced mean, scale, and correlation structures. If that path was used, keep the modeling posture visible in the reporting surface instead of presenting the results as if they came from a simple repeated-measures regression.
• Team inference: coefficient tables from GEE are easiest to interpret when they are labeled as population-averaged or marginal repeated-measure effects so readers do not confuse them with subject-specific mixed-model estimates.

5g. Keep SEM fit, parameter, and modification reporting on distinct surfaces

• Current fitMeasures() documentation exposes global fit summaries as their own extraction surface. Keep fit-index tables separate from parameter tables so global model fit and parameter interpretation do not blur together.
• Current parameterEstimates() documentation can include standardized columns while keeping tests and standard errors tied to the unstandardized estimates. When that route is used, label the table clearly so readers know which quantities are standardized and which inferential columns come from the raw parameterization.
• Current standardizedSolution() documentation provides a dedicated standardized-parameter surface with its own inferential quantities. Keep that reporting surface distinct when the standardized solution itself is the main table.
• Current modificationIndices() documentation provides local score-test diagnostics. Treat modification indices as diagnostic or appendix material unless the reporting goal is explicitly model-development review.
• Current lavPredict() documentation produces model-based latent scores. If those values appear in tables, figure companions, or exports, label them as latent-score outputs derived from the fitted SEM.
• Current lavTestLRT() documentation keeps nested-model comparison explicit and may require scaled difference tests under robust estimation. Keep the comparison method visible in model-comparison tables or captions.
• Team doctrine: separate SEM fit tables, parameter tables, standardized-solution tables, latent-score outputs, and modification-diagnostic appendices so each surface answers one clear question.

5h. Keep discrimination, calibration, thresholds, and net-benefit reporting on distinct surfaces

• Current yardstick documentation keeps roc_auc(), pr_auc(), and brier_class() on distinct metric surfaces. Keep discrimination summaries, precision-recall summaries, and probability-error summaries in separate tables or figure captions so readers can tell which evaluation question is being answered.
• Current pROC::roc() documentation builds a reusable ROC object, and current ci.auc() documentation keeps AUC uncertainty explicit. When ROC/AUC appears in a report, keep curve figures and AUC interval summaries aligned but conceptually distinct.
• Current probably::cal_plot_breaks() documentation provides a dedicated calibration-plot surface. Keep calibration plots or calibration tables separate from ROC/PR displays so probability alignment is visible on its own terms.
• Current pROC::coords() and probably::threshold_perf() documentation expose threshold-specific operating characteristics. Treat threshold tables as policy-facing reporting surfaces rather than as universally optimal cutpoint declarations.
• Current rmda::decision_curve() and plot_decision_curve() documentation define and plot net benefit over thresholds while keeping policy and threshold range explicit. Keep decision curves labeled with the policy and threshold range they represent.
• Team doctrine: report discrimination, calibration, threshold performance, and decision utility on separate surfaces so prediction-model evaluation stays interpretable.

5i. Keep bootstrap intervals and permutation tests labeled as separate reporting surfaces

• Current boot.ci() documentation says interval families are explicit through type = c("norm", "basic", "stud", "perc", "bca"). Keep the interval label visible in the table column header, figure caption, footnote, or methods note whenever bootstrap confidence intervals are reported.
• Current rsample::int_pctl() documentation returns .lower, .estimate, .upper, .alpha, .method, and term, and notes that percentile, student-t, and BCa intervals have different computational requirements. Keep .method or an equivalent display field visible instead of flattening all bootstrap intervals into one generic “95% CI” label.
• Current infer::get_confidence_interval() documentation keeps type explicit through percentile, standard-error, or bias-corrected intervals and requires a point estimate for some methods. Keep the interval construction rule visible whenever infer-based intervals feed a table or figure.
• Current infer::get_p_value() documentation says a reported p-value of 0 is an approximation caused by finite reps and that the true p-value is likely smaller than 3/reps. Reflect that finite-resample approximation in reporting rather than presenting a simulation-based p-value as an exact zero.
• Current rsample::bootstraps() documentation keeps out-of-bag and apparent-sample posture explicit. When that posture matters to how an interval or validation summary was computed, carry it into the report note or appendix.
• Team doctrine: bootstrap reports should state the statistic, resampling engine, interval family, and replicate count. Permutation reports should state the null hypothesis, permutation rule, replicate count, and that the p-value comes from a simulated null distribution.
• Team inference: bootstrap estimates are often clearest as point-interval tables or point-interval figures, while permutation tests are often clearest as null-distribution figures paired with the observed statistic and a companion p-value table.

5j. Keep smooth-term reporting separate from parametric-term reporting

• Current summary.gam() documentation provides parametric-term and smooth-term summaries on separate surfaces, with estimated degrees of freedom and approximate significance summaries for smooths. Keep smooth effects conceptually separate from ordinary coefficient tables.
• Current plot.gam() documentation says the default smooth-effect plots are on the linear predictor scale. When the reporting surface is meant for domain readers, make the scale explicit and use response-scale prediction surfaces when that is the real interpretive target.
• Current predict.gam() documentation supports response-scale, link-scale, and term-level prediction surfaces. Keep prediction tables or plotted curves aligned with the same scale choice.
• Current gam.check() and concurvity() documentation expose important diagnostics for basis adequacy and nonlinear collinearity. When smooths drive the main result, keep diagnostic context close enough that readers can tell the nonlinear surface was checked rather than only drawn.
• For spline bases such as ns() inside ordinary regression models, the raw basis coefficients are rarely the publication-facing result. Prefer joint tests or model-based effect plots when the scientific question is about nonlinear shape.
• Team doctrine: report nonlinear effects with curves, uncertainty, and clear scale labels, while reserving coefficient tables mainly for the parametric part of the model.

6. Export with a thin wrapper

• Convert once with gtsummary::as_flex_table() when Word output is the target.
• For custom post-estimation tables, convert the normalized data frame directly to flextable or gt.
• For package-native marginaleffects drafts in Quarto, HTML, LaTeX, or Typst, consider print(x, style = "tinytable") before building a heavier custom table.
• Apply only the small set of styling calls the report truly needs.
• Keep template/style selection explicit so reruns remain reproducible.
• For journal-facing figures, keep one export helper per figure family so width, dpi, font sizing, and file type stay explicit and reproducible.
• When the figure is model-output driven, keep the preset fields explicit too: estimand label, scale label, interval type, ratio/log posture, legend note, and whether a risk table or event-definition note belongs with the figure.

6b. Keep Quarto report surfaces parameter-aware and reproducible

• Build tables and figures upstream, then let Quarto consume normalized reporting objects. Keep Quarto as the presentation layer, not the only place where heavy data wrangling happens.
• Current Quarto parameter docs for the knitr engine define parameters in YAML params: and expose them through params$.... Keep those parameters narrow and readable: cohort, subgroup, reporting window, journal/profile variant, or similarly explicit report choices.
• Current Quarto docs support command-line overrides with -P key:value and parameter files with --execute-params params.yml. Keep these entry points aligned with the same documented parameter schema.
• When one report must render across a grid of parameter sets, let targets own the orchestration with tar_quarto() or tar_quarto_rep() instead of hiding repeated renders inside ad hoc loops.
• Keep output-file naming explicit across parameter sets so report artifacts are deterministic and easy to diff, archive, and hand off.
• Quarto dashboards are a useful report surface when the deliverable needs value boxes, tables, figures, htmlwidgets, and dashboard layout without becoming a full application. Current dashboard docs also expose sidebars, toolbars, and card-level inputs for report-style interactivity.
• Keep the same reporting tibble and estimand metadata across static exports, Quarto reports, and dashboard-style outputs so the narrative layer does not redefine the analytical result.

Coordination notes

• Reach for /r-model-builder when the hard part is the modeling helper, pooled-fit helper, or post-estimation adapter.
• Reach for /r-stats when the hard part is method choice, statistical interpretation, or choosing the right estimand scale.
• Reach for /r-shiny when the reporting surface lives inside an app or must participate in linked table/plot interactions.
• Reach for /r-eda when the hard part is the reproducible targets pipeline or parameterized report orchestration rather than the table/figure formatting itself.
• Reach for /r-advanced when repo history or repeated commits need to be turned into reusable R guidance.

Resources

• references/gtsummary-edge-cases.md
• references/reporting-patterns.md
• references/recurring-clinical-table-edge-cases.md
• references/journal-table-figure-style-guides.md
• references/publication-presets-and-scope-summaries.md
• references/pediatric-oncology-and-asthma-journal-guides.md
• references/pediatric-endpoint-family-reporting.md
• references/interactive-figure-companions.md
• references/interactive-table-companions.md
• references/quarto-parameterized-reporting.md
• references/journal-facing-model-output-figure-presets.md
• references/marginal-effects-reporting.md
• references/survey-weighted-table-reporting.md
• references/bayesian-reporting-surfaces.md
• references/causal-balance-and-effect-reporting.md
• references/meta-analysis-reporting.md
• references/easystats-reporting-surfaces.md
• references/gee-reporting-surfaces.md
• references/sem-reporting-with-lavaan.md
• references/predictive-performance-reporting.md
• references/bootstrap-and-permutation-reporting.md
• references/gam-reporting.md