GPTomics/bio-reporting-publication-tables

Version Compatibility

Reference examples tested with: gtsummary 2.0+, gt 0.10+, flextable 0.9+, kableExtra 1.4+, great_tables 0.13+, pandas 2.2+, tableone 0.9+, openpyxl 3.1+

Before using code patterns, verify installed versions match. If versions differ:

• R: packageVersion('gtsummary') then ?tbl_summary (gtsummary had a major API refresh at v2.0)
• Python: pip show great_tables then help(great_tables.GT.save)

If code throws an error, introspect the installed package and adapt the example to the actual API rather than retrying.

Publication-Ready Tables

"Make my Table 1" / "export this results table for the paper" -> Generate the table programmatically with the right statistics and export it to the journal's target format.

• R: gtsummary::tbl_summary(data, by=arm) then as_flex_table() -> Word
• Python: great_tables.GT(df) -> HTML/PNG; tableone.TableOne(...) for a descriptive table

The Load-Bearing Idea: A Table Is Structure + Precision + the Right Statistics

Three orthogonal concerns, and conflating them is where tables go wrong:

• Structure - rows are units (subjects, genes, models), columns are variables/groups, spanners group columns, footnotes/source-notes carry the apparatus. This is the grammar of tables that gt, great_tables, and flextable all encode.
• Precision - report to MEANINGFUL precision, not the float default. P-values to 2-3 significant figures or "<0.001"; estimates to the precision the CI supports; percentages to 0-1 decimal. A 3.14159265 mean is noise.
• The right statistics - a table is DESCRIPTIVE (summarize the sample: n(%), mean(SD) or median(IQR)) or INFERENTIAL (estimate + CI + test statistic, with the effect size primary and the p-value never alone). Declare which.

The deepest framing, shared with figures: a table is a deterministic function of data + code. Same input + same code -> the same table, byte for byte. Manual edits in Word break this; every number must trace to a line of code. That principle dictates the tooling - generate programmatically and never hand-edit the output.

Tool Decision (by language and target format)

Target format dominates: Word for most biomedical journals, LaTeX for some genomics/physics venues, HTML for web/preprints/Quarto, CSV/Excel for machine-readable supplements.

| Need | Tool | Path | |------|------|------| | R, descriptive Table 1 or regression results | gtsummary | tbl_summary / tbl_regression -> as_flex_table() / as_gt() | | R, going to Word/PowerPoint | flextable | save_as_docx() (most reliable Word fidelity; pairs with officer) | | R, going to LaTeX/PDF | gt or kableExtra | gtsave('x.tex') / kbl(format='latex') | | R, going to HTML/Quarto | gt or kableExtra | as_raw_html() / save_kable() | | Python, display HTML/image | great_tables | GT(df) -> save('x.png') / as_raw_html() | | Python, going to LaTeX | pandas Styler | df.style.format(...).to_latex() (pandas 1.3+) | | Either, classic Table 1 with SMD | tableone | CreateTableOne (R) / TableOne (Python) | | Machine-readable supplement | CSV (preferred) or Excel | gene-symbol-safe export (below) |

gt has the broadest R export (HTML/PNG/PDF/RTF/LaTeX/Word). great_tables.save() is image+PDF only (HTML via as_raw_html()/write_raw_html()) - NO native Word or LaTeX, a real limitation vs the R stack. DT is for interactive exploration and online-only/interactive HTML supplements - never for a static print/PDF table.

Table 1 Is Descriptive, Not Inferential

Table 1 reports baseline characteristics so the reader can judge who was studied and how comparable the groups are. It describes the sample; it is not a place to test hypotheses.

The p-value fallacy (randomized trials): adding a p-value column comparing arms in a randomized trial is discouraged by CONSORT and statisticians. In a properly randomized trial any baseline imbalance is by definition due to chance, so the test asks whether a difference could have arisen by chance when the assignment WAS by chance - it tests a null already known true. A "significant" baseline p-value is a Type I error by construction; a non-significant one tells nothing new. The right response to a worrying imbalance on a prognostic covariate is to adjust for it (pre-specified ANCOVA covariate), not test it (Senn 1994; CONSORT 2010 item 15). gtsummary's documentation cautions against add_p() on a randomized Table 1 for this reason.

• Randomized Table 1: no p-value column. To convey balance, use standardized mean differences (SMD) - they describe the magnitude of imbalance (|SMD| > 0.1 is a common "notable" rule of thumb) without the inferential fallacy. If a journal or regulator nonetheless requires a baseline comparison column, report it but interpret per Senn: a "significant" baseline difference in a properly randomized trial is a Type I error, not evidence of confounding. Note add_difference() compares exactly two groups; for >2 arms, SMD is defined pairwise, so report reference-group or all-pairs SMDs rather than one omnibus value.
• Observational studies: a comparison column can be defensible (the groups genuinely may differ), but multiplicity (many rows -> many tests) and "significant does not mean important" still bite, and SMD is the standard balance diagnostic in propensity-score/causal contexts. SMD is preferred over p-values for balance in essentially all cases.

Continuous Summaries and Missingness

• mean(SD) vs median(IQR) is distribution-driven. Symmetric -> mean(SD); skewed/heavy-tailed (most biomarkers, counts, lab values, length-of-stay) -> median(IQR), because the mean is pulled by the tail. gtsummary defaults continuous variables to median (p25, p75) - defensible because biomedical variables are usually skewed and normality cannot be assumed column by column. Override per-variable (statistic = list(age ~ "{mean} ({sd})")) only after checking normality. Categorical: n(%), and state row% vs column% (baseline tables want column%).
• Missingness must be SHOWN, not silently dropped. The cardinal sin is computing percentages on complete cases with no indication rows were dropped - a reader cannot tell 90% from 90%-of-the-60%-with-data. gtsummary's missing = "ifany" (default) shows a missing row when any value is absent; missing_text = "Unknown" labels it. Never compute denominators that hide missingness; if rows are dropped, report the analyzed N in the table or a footnote.

Getting Formatting Into the Target Format

• Word (the chronic pain point): flextable save_as_docx() is the most reliable path; gtsummary as_flex_table() then save_as_docx() gives the best Word fidelity; gt gtsave('x.docx') works but routes through rmarkdown and supports fewer Word styles. great_tables has NO native Word export.
• LaTeX: gtsave('x.tex'), kableExtra::kbl(format='latex', booktabs=TRUE), or pandas Styler.to_latex().
• HTML: gt as_raw_html(), great_tables as_raw_html()/write_raw_html(), kableExtra save_kable().

The Excel Gene-Symbol Hazard

Excel, with default settings, auto-converts gene symbols and IDs when it PARSES them - opening a CSV, double-clicking, or typing: SEPT2 -> 2-Sep, MARCH1 -> 1-Mar; RIKEN IDs like 2310009E13 -> 2.31E+13 (precision lost irreversibly); long numeric accessions lose trailing digits to float rounding. (The corruption is a parse behavior, not a write behavior - a string written by openpyxl stays intact until Excel re-interprets it, which is why forcing text format matters.) Ziemann et al. 2016 found ~19.6% of papers with supplementary Excel gene lists affected; Abeysooriya et al. 2021 showed it persisted at 30.9% and drove HGNC to rename the families (SEPT->SEPTIN, MARCH->MARCHF) in 2020 - biology changed its nomenclature to defend against a spreadsheet bug.

When a gene table must reach Excel:

• Prefer CSV and tell the consumer to import the gene column as Text (not double-click).
• If writing .xlsx, set the gene column to Excel text format '@' (openpyxl cell.number_format = '@'; XlsxWriter add_format({'num_format': '@'}) or write_string()). Note pandas Styler.format is IGNORED by to_excel - set the number format via the writer, not the styler.
• Verify by reopening - the only sure check.

Precision and Locale

Report to significant figures, not the float default (fmt_number(decimals=), pvalue_fun, Styler .format('{:.2f}')). Watch the decimal-comma locale trap: a CSV written in a ,-decimal locale becomes unparseable elsewhere and Excel may re-misinterpret columns. Write numeric supplements with .-decimal and document the locale rather than relying on the system default.

Common Errors

| Symptom | Cause | Fix | |---------|-------|-----| | p-value column on a randomized Table 1 | testing a null known to be true | drop it; use SMD for balance | | Percentages do not add up / hide dropped rows | missingness silently excluded | missing="ifany"; report analyzed N | | SEPT2 became a date in the supplement | Excel auto-conversion | CSV + import-as-text, or '@' text format in .xlsx | | mean(SD) misleads on a skewed variable | wrong summary statistic | median(IQR) for skewed data | | Word table lost its formatting | exported HTML/LaTeX into Word | flextable save_as_docx() | | great_tables won't save to Word/LaTeX | not supported (image/HTML/PDF only) | use the R stack, or export PNG/HTML | | Excel export ignored my number format | Styler.format is dropped by to_excel | set number_format via the ExcelWriter |

Related Skills

• reporting/figure-export - The figure counterpart to table export
• reporting/rmarkdown-reports - Embedding kable/gt tables in R reports
• reporting/quarto-reports - Embedding tables in Quarto reports
• clinical-biostatistics/trial-reporting - CONSORT trial reporting context for Table 1
• differential-expression/de-results - Result tables these formatters present

References

• Senn S. Testing for baseline balance in clinical trials. Stat Med. 1994;13(17):1715-1726. doi:10.1002/sim.4780131703
• Schulz KF, Altman DG, Moher D; CONSORT Group. CONSORT 2010 Statement: updated guidelines for reporting parallel group randomised trials. BMC Med. 2010;8:18 (item 15, baseline table). doi:10.1186/1741-7015-8-18
• Ziemann M, Eren Y, El-Osta A. Gene name errors are widespread in the scientific literature. Genome Biol. 2016;17:177. doi:10.1186/s13059-016-1044-7
• Abeysooriya M, Soria M, Kasu MS, Ziemann M. Gene name errors: Lessons not learned. PLoS Comput Biol. 2021;17(7):e1008984. doi:10.1371/journal.pcbi.1008984