% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/matching_cem.R
\name{cem_match}
\alias{cem_match}
\title{Coarsened Exact Matching}
\usage{
cem_match(
  left,
  right,
  vars,
  cutpoints = NULL,
  n_bins = "sturges",
  grouping = NULL,
  keep = "all",
  left_id = "id",
  right_id = "id"
)
}
\arguments{
\item{left}{Data frame of left (treated) units}

\item{right}{Data frame of right (control) units}

\item{vars}{Character vector of variable names to coarsen and match on}

\item{cutpoints}{Named list of break vectors per variable. If NULL,
automatic binning is used.}

\item{n_bins}{Binning method when \code{cutpoints} is NULL: \code{"sturges"}
(default), \code{"fd"} (Freedman-Diaconis), \code{"scott"}, or an integer
specifying the number of bins for all variables.}

\item{grouping}{Character vector of variable names to match exactly
(without coarsening). These are typically categorical variables.}

\item{keep}{Which units to return: \code{"all"} (default) returns all units
with weight 0 for unmatched, \code{"matched"} drops unmatched units.}

\item{left_id}{Name of ID column in left (default: \code{"id"})}

\item{right_id}{Name of ID column in right (default: \code{"id"})}
}
\value{
An S3 object of class \code{c("cem_result", "couplr_result")}
containing:
\describe{
\item{matched}{Tibble with columns \code{id}, \code{side}, \code{stratum},
\code{weight}}
\item{strata_summary}{Tibble with per-stratum counts}
\item{info}{List with \code{n_strata}, \code{n_matched_left},
\code{n_matched_right}, \code{n_pruned_left}, \code{n_pruned_right},
\code{method}, \code{vars}}
}
}
\description{
Coarsens continuous variables into bins, then performs exact matching on
the coarsened values. Units in strata containing both left and right units
are kept; others are pruned. Matched units receive weights inversely
proportional to stratum sizes to maintain balance.
}
\details{
CEM algorithm:
\enumerate{
\item Coarsen each numeric variable using \code{\link[base]{cut}} with
either user-specified breakpoints or automatic binning (Sturges, FD, or
Scott rule)
\item Categorical variables in \code{grouping} are kept as-is
\item Create strata by concatenating all coarsened values
\item Drop strata with 0 left or 0 right units
\item Compute CEM weights: left units get weight 1, right units get
weight \code{n_left_in_stratum / n_right_in_stratum} so that the total
weight of right units in each stratum equals the number of left units
}
}
\examples{
set.seed(42)
left <- data.frame(
  id = 1:20, age = rnorm(20, 40, 10),
  income = rnorm(20, 50000, 10000)
)
right <- data.frame(
  id = 21:60, age = rnorm(40, 42, 10),
  income = rnorm(40, 52000, 10000)
)
result <- cem_match(left, right, vars = c("age", "income"))
print(result)

}
