% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/build_table1.R
\name{build_table1}
\alias{build_table1}
\title{Build a Table 1 comparing baseline characteristics between groups}
\usage{
build_table1(
  in_df,
  out_xlsxpath = NULL,
  exposure_var,
  exp_value = 1,
  ref_value = 0,
  use_weights = FALSE,
  weight_var = "psweight",
  cont_vars = NULL,
  cat_vars = NULL,
  binary_vars = NULL,
  drop_vars = NULL,
  drop_varpattern = NULL,
  Var_colname = "Variable",
  Vartype_colname = "Type",
  Total_colname = "Total",
  Exp_colname = "Exp",
  Ref_colname = "Ref",
  CrudeDiff_colname = "Crude_diff",
  StdDiff_colname = "Std_diff",
  MissingTotal_colname = "Missing_Total_N_Pct",
  MissingExp_colname = "Missing_Exp_N_Pct",
  MissingRef_colname = "Missing_Ref_N_Pct",
  ExistingTotal_colname = "Existing_Total_N_denom",
  ExistingExp_colname = NULL,
  ExistingRef_colname = NULL,
  mean_decimal = 2,
  sd_decimal = 2,
  n_decimal = 0,
  pct_decimal = 1,
  use_absolute_values_for_diff = FALSE,
  add_n_of_patients_row = TRUE,
  verbose = TRUE
)
}
\arguments{
\item{in_df}{Data frame containing the analytic cohort.}

\item{out_xlsxpath}{Character string. File path for Excel output, or
\code{NULL} to skip (default \code{NULL}).}

\item{exposure_var}{Character string. Name of the binary exposure column.}

\item{exp_value}{Value in \code{exposure_var} representing the exposed group
(default 1).}

\item{ref_value}{Value in \code{exposure_var} representing the reference group
(default 0).}

\item{use_weights}{Logical. Apply weights? (default FALSE).}

\item{weight_var}{Character string. Name of the weight column (default
\code{"psweight"}).}

\item{cont_vars}{Character vector of continuous variable names.}

\item{cat_vars}{Character vector or named list of categorical variable names.
If a named list, each element should be a character vector of factor levels.}

\item{binary_vars}{Character vector of binary variable names.}

\item{drop_vars}{Character vector of variable names to exclude.}

\item{drop_varpattern}{Character vector of regex patterns; matching variables
are excluded.}

\item{Var_colname, Vartype_colname, Total_colname, Exp_colname, Ref_colname}{Column-name overrides for the output table.}

\item{CrudeDiff_colname, StdDiff_colname}{Column-name overrides for
difference columns.}

\item{MissingTotal_colname, MissingExp_colname, MissingRef_colname}{Column-name overrides for missingness columns.}

\item{ExistingTotal_colname, ExistingExp_colname, ExistingRef_colname}{Column-name overrides for non-missing-count columns. Set to \code{NULL}
to omit (default for Exp/Ref).}

\item{mean_decimal, sd_decimal}{Integer. Decimal places for mean and SD.}

\item{n_decimal}{Integer. Decimal places for counts (default 0).}

\item{pct_decimal}{Integer. Decimal places for percentages (default 1).}

\item{use_absolute_values_for_diff}{Logical. Show absolute differences?
(default FALSE).}

\item{add_n_of_patients_row}{Logical. Prepend an \code{"n_of_patients"} row?
(default TRUE).}

\item{verbose}{Logical. Print progress messages (default TRUE).}
}
\value{
Invisibly returns the Table 1 data frame.
}
\description{
Generates a descriptive Table 1 with counts, percentages, means, SDs,
crude differences, standardized mean differences (SMD), and missingness.
Supports inverse probability weighting via a user-supplied weight column
and optionally saves the output to an Excel file.
}
\section{Side Effects}{

When \code{out_xlsxpath} is not \code{NULL}, creates the output directory
(if needed) and writes an Excel workbook.
}

\examples{
csv_path <- system.file("extdata", "sample_data.csv", package = "rwetools")
df <- read.csv(csv_path)

# Unweighted Table 1
tbl <- build_table1(
  in_df        = df,
  exposure_var = "exposure",
  cont_vars    = c("cont1", "cont2", "cont3"),
  binary_vars  = c("binary1", "binary2"),
  cat_vars     = c("cat1", "cat2"),
  verbose      = FALSE
)
head(tbl)

\donttest{
# Weighted Table 1 with Excel output (requires openxlsx)
if (requireNamespace("openxlsx", quietly = TRUE)) {
  df_ps <- estimate_ps(
    in_df        = df,
    exposure_var = "exposure",
    class_vars   = c("cat1", "cat2", "cat3", "cat4"),
    cont_vars    = c("cont1", "cont2", "cont3"),
    verbose      = FALSE
  )
  df_wt <- create_ps_weights(
    in_df         = df_ps,
    exposure_var  = "exposure",
    ps_var        = "ps",
    weight_method = "mw",
    weight_var    = "mw_wt",
    verbose       = FALSE
  )
  out_xlsx <- tempfile(fileext = ".xlsx")
  tbl_wt <- build_table1(
    in_df        = df_wt,
    out_xlsxpath = out_xlsx,
    exposure_var = "exposure",
    use_weights  = TRUE,
    weight_var   = "mw_wt",
    cont_vars    = c("cont1", "cont2", "cont3"),
    binary_vars  = c("binary1", "binary2"),
    cat_vars     = c("cat1", "cat2"),
    verbose      = FALSE
  )
}
}

}
