% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/create_psweights.R
\name{create_ps_weights}
\alias{create_ps_weights}
\title{Calculate propensity score weights and optionally generate diagnostic reports.}
\usage{
create_ps_weights(
  in_df = NULL,
  in_csvpath = NULL,
  out_csvpath = NULL,
  out_xlsxpath_report = NULL,
  out_dir_plots = NULL,
  exposure_var = "exp",
  exp_value = 1,
  ref_value = 0,
  ps_var = "ps",
  weight_method = c("mw", "ow", "iptw", "stabiptw"),
  weight_var = "psweight",
  estimand = c("ATT", "ATE", "ATO"),
  make_unwt_wt_table1 = FALSE,
  table1_cont_vars = NULL,
  table1_binary_vars = NULL,
  table1_cat_vars = NULL,
  std_diff_threshold = 0.1,
  readme_text = NULL,
  verbose = TRUE
)
}
\arguments{
\item{in_df}{Data frame containing the input data with PS already calculated (optional if in_csvpath provided)}

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

\item{out_csvpath}{Character string. Path for output CSV file (optional)}

\item{out_xlsxpath_report}{Character string. Path for output Excel diagnostic report (optional).
If NULL, no diagnostic report is generated.}

\item{out_dir_plots}{Character string. Directory to save plot files (optional).
If NULL, no plots are saved.}

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

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

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

\item{ps_var}{Character string. Name of the PS variable column in the data (default: "ps")}

\item{weight_method}{Character string. Type of weight to calculate: "mw" (matching weights),
"ow" (overlap weights), "iptw" (inverse probability weights),
"stabiptw" (stabilized IPTW). Only ONE method can be specified.}

\item{weight_var}{Character string. Name for the weight variable column (default: "psweight")}

\item{estimand}{Character string. Target estimand: "ATT" (average treatment effect on treated),
"ATE" (average treatment effect), or "ATO" (average treatment effect in overlap population).
Only used for IPTW methods. For MW/OW, estimand is determined by the method itself.}

\item{make_unwt_wt_table1}{Logical. Whether to generate unweighted and weighted Table 1 (default: FALSE).
Only used if out_xlsxpath_report is provided.}

\item{table1_cont_vars}{Character vector. Names of continuous variables for Table 1 (optional, auto-detected if NULL)}

\item{table1_binary_vars}{Character vector. Names of binary variables for Table 1 (optional, auto-detected if NULL)}

\item{table1_cat_vars}{Character vector. Names of categorical variables for Table 1 (optional, auto-detected if NULL)}

\item{std_diff_threshold}{Numeric. Threshold for acceptable standardized difference (default: 0.1)}

\item{readme_text}{Character string. Optional message to include in README sheet of Excel report}

\item{verbose}{Logical. Print progress messages (default TRUE).}
}
\value{
A data frame with the weight column added. Also saves to CSV if path specified.
}
\description{
This function calculates various types of propensity score weights (matching weights,
overlap weights, IPTW, stabilized IPTW) and adds them to a dataset that already
contains propensity scores. Optionally generates comprehensive diagnostic reports
including assumption checks, balance tables, and plots.
}
\section{Side Effects}{

\itemize{
\item Writes a CSV file when \code{out_csvpath} is provided.
\item Creates directories, writes an Excel diagnostic report, and saves
PNG plot files when the corresponding path arguments are supplied.
}
}

\examples{
csv_path <- system.file("extdata", "sample_data.csv", package = "rwetools")
df_ps <- estimate_ps(
  in_df        = read.csv(csv_path),
  exposure_var = "exposure",
  class_vars   = c("cat1", "cat2", "cat3", "cat4"),
  cont_vars    = c("cont1", "cont2", "cont3"),
  verbose      = FALSE
)

# Add matching weights
df_mw <- create_ps_weights(
  in_df         = df_ps,
  exposure_var  = "exposure",
  ps_var        = "ps",
  weight_method = "mw",
  weight_var    = "mw_wt",
  verbose       = FALSE
)
summary(df_mw$mw_wt)

\donttest{
# Add IPTW weights with Excel diagnostic report (requires openxlsx, ggplot2)
if (requireNamespace("openxlsx", quietly = TRUE) &&
    requireNamespace("ggplot2", quietly = TRUE)) {
  out_xlsx <- tempfile(fileext = ".xlsx")
  out_dir  <- tempdir()
  df_iptw  <- create_ps_weights(
    in_df               = df_ps,
    exposure_var        = "exposure",
    ps_var              = "ps",
    weight_method       = "iptw",
    weight_var          = "iptw_wt",
    estimand            = "ATE",
    out_xlsxpath_report = out_xlsx,
    make_unwt_wt_table1 = TRUE,
    out_dir_plots       = out_dir,
    verbose             = FALSE
  )
}
}
}
