% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Balance.R
\name{computeCovariateBalance}
\alias{computeCovariateBalance}
\title{Compute covariate balance before and after PS adjustment}
\usage{
computeCovariateBalance(
  population,
  cohortMethodData,
  computeCovariateBalanceArgs = createComputeCovariateBalanceArgs()
)
}
\arguments{
\item{population}{A data frame containing the people that are remaining after PS adjustment.}

\item{cohortMethodData}{An object of type \link{CohortMethodData} as generated using
\code{\link[=getDbCohortMethodData]{getDbCohortMethodData()}}.}

\item{computeCovariateBalanceArgs}{Settings object as created by \code{createComputeCovariateBalanceArgs()}.}
}
\value{
Returns a tibble describing the covariate balance before and after PS adjustment,
with one row per covariate, with the same data as the \code{covariateRef} table in the \code{CohortMethodData} object,
and the following additional columns:
\itemize{
\item beforeMatchingMeanTarget: The (weighted) mean value in the target before PS adjustment.
\item beforeMatchingMeanComparator: The (weighted) mean value in the comparator before PS adjustment.
\item beforeMatchingSumTarget: The (weighted) sum value in the target before PS adjustment.
\item beforeMatchingSumComparator: The (weighted) sum value in the comparator before PS adjustment.
\item beforeMatchingSdTarget: The standard deviation of the value in the target before PS adjustment.
\item beforeMatchingSdComparator: The standard deviation of the value in the comparator before PS adjustment.
\item beforeMatchingMean: The mean of the value across target and comparator before PS adjustment.
\item beforeMatchingSd: The standard deviation of the value across target and comparator before PS adjustment.
\item beforeMatchingStdDiff: The standardized difference of means when comparing the target to
the comparator before PS adjustment.
\item beforeMatchingSdmVariance: The variance of the standardized difference of the means when comparing the target to
the comparator before PS adjustment.
\item beforeMatchingSdmP : The P-value for whether abs(beforeMatchingStdDiff) exceeds the threshold.
\item beforeMatchingBalanced : TRUE if the covariate is considered balanced between the target and comparator before PS
adjustment (depending on the threshold and alpha settings).
\item afterMatchingMeanTarget: The (weighted) mean value in the target after PS adjustment.
\item afterMatchingMeanComparator: The (weighted) mean value in the comparator after PS adjustment.
\item afterMatchingSumTarget: The (weighted) sum value in the target after PS adjustment.
\item afterMatchingSumComparator: The (weighted) sum value in the comparator after PS adjustment.
\item afterMatchingSdTarget: The standard deviation of the value in the target after PS adjustment.
\item afterMatchingSdComparator: The standard deviation of the value in the comparator after PS adjustment.
\item afterMatchingMean: The mean of the value across target and comparator after PS adjustment.
\item afterMatchingSd: The standard deviation of the value across target and comparator after PS adjustment.
\item afterMatchingStdDiff: The standardized difference of means when comparing the target to
the comparator after PS adjustment.
\item afterMatchingSdmVariance: The variance of the standardized difference of the means when comparing the target to
the comparator after PS adjustment.
\item afteMatchingSdmP : The P-value for whether abs(beforeMatchingStdDiff) exceeds the threshold.
\item afteMatchingBalanced : TRUE if the covariate is considered balanced between the target and comparator before PS
adjustment (depending on the threshold and alpha settings).
\item targetStdDiff: The standardized difference of means when comparing the target
before PS adjustment to the target after PS adjustment.
\item comparatorStdDiff: The standardized difference of means when comparing the comparator
before PS adjustment to the comparator after PS adjustment.
-targetComparatorStdDiff:  The standardized difference of means when comparing the entire
population before PS adjustment to the entire population after
PS adjustment.
}

The 'beforeMatchingStdDiff' and 'afterMatchingStdDiff' columns inform on the balance:
are the target and comparator sufficiently similar in terms of baseline covariates to
allow for valid causal estimation?

The 'targetStdDiff', 'comparatorStdDiff', and 'targetComparatorStdDiff' columns inform on
the generalizability: are the cohorts after PS adjustment sufficiently similar to the cohorts
before adjustment to allow generalizing the findings to the original cohorts?
}
\description{
For every covariate, prevalence in treatment and comparator groups before and after
matching/trimming/weighting are computed. When variable ratio matching was used
the balance score will be corrected according the method described in Austin et
al (2008).
}
\details{
The population data frame should have the following three columns:
\itemize{
\item rowId (numeric): A unique identifier for each row (e.g. the person ID).
\item treatment (integer): Column indicating whether the person is in the target (1) or comparator (0) group.
\item propensityScore (numeric): Propensity score.
}
}
\references{
Austin, PC (2008) Assessing balance in measured baseline covariates when using many-to-one
matching on the propensity-score. Pharmacoepidemiology and Drug Safety, 17: 1218-1225.

Hripcsak G, Zhang L, Chen Y, Li K, Suchard MA, Ryan PB, Schuemie MJ (2025)
Assessing Covariate Balance with Small Sample Sizes. Stat Med. 2025 Aug;44(18-19):e70212.
}
