% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot.R
\name{plot_tableone}
\alias{plot_tableone}
\title{Publication-ready Table 1 (Baseline Characteristics)}
\usage{
plot_tableone(
  data,
  vars,
  strata = NULL,
  type = NULL,
  label = NULL,
  statistic = NULL,
  digits = NULL,
  percent = "column",
  missing = "no",
  add_p = TRUE,
  add_smd = FALSE,
  overall = FALSE,
  exclude_labels = NULL,
  theme = "lancet",
  label_width = 200,
  stat_width = 140,
  pvalue_width = 100,
  row_height = 8,
  save = FALSE,
  dest = NULL,
  png_scale = 2,
  pdf_width = NULL,
  pdf_height = NULL
)
}
\arguments{
\item{data}{data.frame. Input data containing all variables.}

\item{vars}{Character vector. Variable names to display in the table.}

\item{strata}{Character scalar. Column name for the grouping/stratification
variable. \code{NULL} produces an unstratified overall summary.}

\item{type}{Named list or \code{NULL}. Variable type overrides passed
directly to \code{\link[gtsummary]{tbl_summary}}.
E.g. \code{list(age = "continuous2")}.}

\item{label}{Named list / formula list or \code{NULL}. Label overrides.
E.g. \code{list(age ~ "Age (years)", sex ~ "Sex")}.}

\item{statistic}{Named list or \code{NULL}. Statistic format strings.
E.g. \code{list(all_continuous() ~ "{mean} ({sd})")}.}

\item{digits}{Named list or \code{NULL}. Decimal place overrides.
E.g. \code{list(age ~ 1)}.}

\item{percent}{Character. Percentage base for categorical variables:
\code{"column"} (default), \code{"row"}, or \code{"cell"}.}

\item{missing}{Character. Display of missing counts:
\code{"no"} (default), \code{"ifany"}, or \code{"always"}.}

\item{add_p}{Logical. Add a p-value column. Default \code{TRUE};
disabled with a warning if \code{strata} is \code{NULL}.}

\item{add_smd}{Logical. Add a standardised mean difference (SMD) column.
Continuous variables use Cohen's \emph{d}; categorical variables use
root-mean-square deviation (RMSD) of group proportions. SMD is shown
only on label rows. Default \code{FALSE}; disabled with a warning if
\code{strata} is \code{NULL}.}

\item{overall}{Logical. Add an Overall column when \code{strata} is set.
Default \code{FALSE}.}

\item{exclude_labels}{Character vector or \code{NULL}. Row labels to
remove from the rendered table, matched exactly against the
\code{label} column in the gtsummary table body.
E.g. \code{c("Unknown", "Missing")}.}

\item{theme}{Character. Visual theme preset. Only \code{"lancet"}
(default) is currently supported. Controls alternating row shading
(\code{#f8e8e7} / white), three-line borders, and 15 px font size.}

\item{label_width}{Integer. Label column width in pixels. Default \code{200}.}

\item{stat_width}{Integer. Statistics column(s) width in pixels.
Default \code{140}.}

\item{pvalue_width}{Integer. P-value and SMD column width in pixels.
Default \code{100}.}

\item{row_height}{Integer. Data row padding (top + bottom) in pixels.
Default \code{8}.}

\item{save}{Logical. Export the table to files. Default \code{FALSE}.}

\item{dest}{Character or \code{NULL}. File path without extension.
When \code{save = TRUE}, four files are written:
\code{<dest>.docx}, \code{<dest>.html}, \code{<dest>.pdf},
\code{<dest>.png}. Required when \code{save = TRUE}.}

\item{png_scale}{Numeric. Zoom factor for PNG export via \pkg{webshot2}.
Higher values produce larger, higher-resolution images. Default: \code{2}.}

\item{pdf_width}{Numeric or \code{NULL}. PDF paper width in inches passed to
\code{pagedown::chrome_print}. A larger value increases the page size so
more content fits on a single page. Default: \code{NULL} (Chrome default).}

\item{pdf_height}{Numeric or \code{NULL}. PDF paper height in inches.
Increase if the table is cut off across pages. Default: \code{NULL}.}
}
\value{
A \pkg{gt} table object, returned invisibly.
}
\description{
Generates a publication-quality baseline-characteristics table (Table 1)
using \pkg{gtsummary}, with optional SMD column, \emph{Lancet}-style
theming, and automatic export to four formats.
}
\details{
The following behaviours are fixed (not exposed as parameters):
\itemize{
\item Variable labels are \strong{bold} (\code{bold_labels()}).
\item P-values are formatted as \code{<0.001} or to 3 decimal places.
\item Significant p-values (\eqn{p < 0.05}) are \strong{bold}.
\item The p-value column header is rendered as \emph{P}-value.
\item The table uses a three-line (booktabs) border.
\item Saving always exports \strong{word}, \strong{html}, \strong{pdf},
and \strong{png}.
}
}
\examples{
library(gtsummary)
data(trial)

# Basic stratified table
plot_tableone(
  data   = trial,
  vars   = c("age", "marker", "grade"),
  strata = "trt",
  save   = FALSE
)

# With SMD, custom labels, exclude Unknown level
plot_tableone(
  data           = trial,
  vars           = c("age", "marker", "grade", "stage"),
  strata         = "trt",
  label          = list(age ~ "Age (years)", marker ~ "Marker level"),
  add_smd        = TRUE,
  exclude_labels = "Unknown",
  save           = FALSE
)
}
