% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/estimate_ps.R
\name{estimate_ps}
\alias{estimate_ps}
\title{Calculate propensity scores and add them to the dataset}
\usage{
estimate_ps(
  in_df = NULL,
  in_csvpath = NULL,
  out_csvpath = NULL,
  out_xlsxpath_odds_ratio = NULL,
  exposure_var = "exposure",
  exp_value = 1,
  ref_value = 0,
  class_vars = NULL,
  cont_vars = NULL,
  ps_var = "ps",
  interactions = NULL,
  exclude_vars_w_extreme_distribution = FALSE,
  verbose = TRUE
)
}
\arguments{
\item{in_df}{Data frame containing the input data (optional if in_csvpath provided)}

\item{in_csvpath}{Character string. Path to input CSV file (optional if in_df provided)}

\item{out_csvpath}{Character string. Path for output CSV file (optional, if NULL no CSV is saved)}

\item{out_xlsxpath_odds_ratio}{Character string. Path for output Excel file with OR table (optional)}

\item{exposure_var}{Character string. Name of the binary exposure/treatment variable column (default: "exposure")}

\item{exp_value}{Value representing the exposed/treated group (default: 1)}

\item{ref_value}{Value representing the reference/control group (default: 0)}

\item{class_vars}{Character vector. Names of categorical/factor variables to include in PS model}

\item{cont_vars}{Character vector. Names of continuous variables to include in PS model}

\item{ps_var}{Character string. Name for the calculated PS variable column (default: "ps")}

\item{interactions}{Character string. Interaction terms to include (e.g., "var1:var2 + var1:var3")}

\item{exclude_vars_w_extreme_distribution}{Logical. If TRUE, automatically excludes variables
with extreme distribution (categorical: only 1 unique level in either group, or any
level with count < 5 in either group; continuous: constant/single unique value
(SD < 1e-6) in either group, or SMD > 1.5 between groups)
instead of throwing error (default: FALSE). The categorical screen unions levels
across the two exposure groups, so a level present in one group but absent in the
other is counted as n = 0 and flagged by the cnt < 5 rule.}

\item{verbose}{Logical. Print progress messages (default TRUE).}
}
\value{
A data frame with the PS column added. Also saves to CSV if path specified.
}
\description{
This function calculates propensity scores using logistic regression and adds them
as a new column to the dataset. It can output both an R data frame and/or CSV file.
Additionally, it can save odds ratio table from the PS model to Excel or data frame.
}
\section{Side Effects}{

\itemize{
\item Writes a CSV file when \code{out_csvpath} is provided.
\item Writes an Excel file with odds-ratio table when
\code{out_xlsxpath_odds_ratio} is provided.
}
}

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

# Basic usage: estimate PS and add it as a new column
result <- estimate_ps(
  in_df        = df,
  exposure_var = "exposure",
  class_vars   = c("cat1", "cat2", "cat3", "cat4"),
  cont_vars    = c("cont1", "cont2", "cont3"),
  verbose      = FALSE
)
head(result$ps)

\donttest{
# With CSV output and Excel OR table (requires openxlsx)
if (requireNamespace("openxlsx", quietly = TRUE)) {
  out_csv  <- tempfile(fileext = ".csv")
  out_xlsx <- tempfile(fileext = ".xlsx")
  result2 <- estimate_ps(
    in_df                               = df,
    out_csvpath                         = out_csv,
    out_xlsxpath_odds_ratio             = out_xlsx,
    exposure_var                        = "exposure",
    class_vars                          = c("cat1", "cat2"),
    cont_vars                           = c("cont1", "cont2"),
    exclude_vars_w_extreme_distribution = TRUE,
    verbose                             = FALSE
  )
}
}
}
