% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/create_psweights.R
\name{create_ps_matched_cohort}
\alias{create_ps_matched_cohort}
\title{Perform propensity score matching and optionally generate diagnostic reports.}
\usage{
create_ps_matched_cohort(
  in_df = NULL,
  in_csvpath = NULL,
  out_csvpath_matcheddata = NULL,
  out_csvpath_crudedata_w_matchindicator = NULL,
  out_xlsxpath_report = NULL,
  out_dir_plots = NULL,
  exposure_var = "exp",
  exp_value = 1,
  ref_value = 0,
  ps_var = "ps",
  ratio = 1,
  caliper = 0.2,
  replace = FALSE,
  make_crude_matched_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_matcheddata}{Character string. Path for matched cohort CSV file (optional)}

\item{out_csvpath_crudedata_w_matchindicator}{Character string. Path for crude data with match indicator CSV file (optional)}

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

\item{out_dir_plots}{Character string. Directory to save plot files (optional).}

\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{ratio}{Integer. Matching ratio (1:k). Default is 1 for 1:1 matching.}

\item{caliper}{Numeric. Caliper width in standard deviations of logit(PS). Default is 0.2.}

\item{replace}{Logical. Whether to match with replacement. Default is FALSE.}

\item{make_crude_matched_table1}{Logical. Whether to generate crude and matched Table 1 (default: FALSE).}

\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 containing the matched cohort only (crude data with match indicator
can be saved to CSV via out_csvpath_crudedata_w_matchindicator).
}
\description{
This function performs 1:k nearest neighbor PS matching using MatchIt and
generates comprehensive diagnostic reports including assumption checks,
balance tables, and plots.
}
\section{Side Effects}{

\itemize{
\item Writes matched-cohort and/or crude-data CSV files when the
corresponding path arguments are provided.
\item Creates directories, writes an Excel diagnostic report, and saves
PNG plot files when the corresponding path arguments are supplied.
}
}

\examples{
\donttest{
# Requires MatchIt
if (requireNamespace("MatchIt", quietly = TRUE)) {
  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
  )

  matched <- create_ps_matched_cohort(
    in_df        = df_ps,
    exposure_var = "exposure",
    ps_var       = "ps",
    ratio        = 1,
    caliper      = 0.2,
    verbose      = FALSE
  )
  nrow(matched)
}
}
}
