% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/create_psweights.R
\name{create_ps_fs_weights}
\alias{create_ps_fs_weights}
\title{Calculate PS Fine Stratification Weights, Trim Non-overlapping Regions,
and Generate Diagnostics}
\usage{
create_ps_fs_weights(
  in_df,
  out_csvpath = NULL,
  out_xlsxpath_report = NULL,
  out_dir_plots = NULL,
  trim_nonoverlap_region = TRUE,
  exposure_var = "exp",
  exp_value = 1,
  ref_value = 0,
  ps_var = NULL,
  weight_var = "ps_fs_wt",
  number_of_strata = 50,
  stratification_method = c("exposure", "cohort"),
  estimand = c("ATT", "ATE"),
  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 with PS already calculated (the "crude" / untrimmed data)}

\item{out_csvpath}{Character. Path for output CSV of trimmed+weighted data (optional)}

\item{out_xlsxpath_report}{Character. Path for Excel diagnostic report (optional)}

\item{out_dir_plots}{Character. Directory to save diagnostic plots (NULL = skip plots)}

\item{trim_nonoverlap_region}{Logical. Trim non-overlapping PS regions (default TRUE)}

\item{exposure_var}{Character. Name of binary exposure variable (default "exp")}

\item{exp_value}{Value representing exposed group (default 1)}

\item{ref_value}{Value representing reference group (default 0)}

\item{ps_var}{Character. Name of PS variable in the data (required)}

\item{weight_var}{Character. Name for the stratification weight variable (default "ps_fs_wt")}

\item{number_of_strata}{Integer. Number of strata to create (default 50)}

\item{stratification_method}{Character. "exposure" or "cohort" (default "exposure")}

\item{estimand}{Character. "ATT" or "ATE" (default "ATT")}

\item{make_unwt_wt_table1}{Logical. Build crude vs weighted balance table (default FALSE)}

\item{table1_cont_vars}{Character vector. Continuous vars for Table 1 (auto-detected if NULL)}

\item{table1_binary_vars}{Character vector. Binary vars for Table 1 (auto-detected if NULL)}

\item{table1_cat_vars}{Character vector. Categorical vars for Table 1 (auto-detected if NULL)}

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

\item{readme_text}{Character. Optional message for README sheet in Excel report}

\item{verbose}{Logical. Print progress messages (default TRUE).}
}
\value{
Invisibly returns the trimmed+weighted data frame.
}
\description{
Combined function that (1) creates PS fine strata, (2) calculates stratification
weights, (3) trims non-overlapping PS regions, and optionally (4) builds a
crude vs weighted balance table (Table 1) and (5) generates diagnostic 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
)

result <- create_ps_fs_weights(
  in_df                 = df_ps,
  exposure_var          = "exposure",
  ps_var                = "ps",
  weight_var            = "fs_wt",
  number_of_strata      = 10,
  stratification_method = "exposure",
  estimand              = "ATT",
  verbose               = FALSE
)
summary(result$fs_wt)
}
