% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nn_win_ratio.R
\name{nn_win_ratio}
\alias{nn_win_ratio}
\title{Win/Loss Ratios with Nearest Neighbor Matching}
\usage{
nn_win_ratio(
  base,
  treatment_name,
  outcome_names,
  win_function = "lexicographic",
  distance = NULL
)
}
\arguments{
\item{base}{A data frame with n rows (individuals) and p columns.
It must include a treatment column and one or more outcome columns.
All remaining columns are considered covariates for matching.
The data frame should not contain missing values. All covariates must be either numeric or factors.}

\item{treatment_name}{A character vector of length one for the treatment column name, must be in \code{names(base)}.
The treatment column should contain only zeros and ones, with ones indicating the treatment group.}

\item{outcome_names}{A character vector specifying the names of outcome columns.
All names must exist in \code{names(base)}. Each outcome column should be numeric or binary and
binary outcomes must be encoded as 0 and 1.}

\item{win_function}{By default, this function compares outcomes lexicographically according to the column order in the data frame,
treating higher values as better. Once a distinct outcome is found, the function yields 1 (a win) if that outcome is larger
for the treated individual and 0 otherwise; in case of a tie, it yields 0.
To change the priority of outcomes, simply reorder the columns of the data frame.
Alternatively, \code{win_function} can be a custom function that takes two arguments, each corresponding to a row of the data frame:
\code{win_function(base[i, ], base[j, ])}
where the first argument represents a treated individual and the second a control individual.
The function must return a value between 0 and 1, with 1 indicating a win for the treated individual.}

\item{distance}{A function that is used to compute the nearest neighbor matching on covariates.
The distance function will be passed as an argument to \code{\link[MatchIt]{matchit}} (see  \code{\link[MatchIt]{distance}}).

\strong{Default Distance Settings}

The default value for the distance parameter is \code{NULL}. If no distance is provided, the function assigns defaults based on the type of covariates:
\itemize{
\item \strong{Numeric covariates:} Sets distance to \code{"euclidean"}.
\item \strong{Categorical covariates:} Applies Multiple Correspondence Analysis (see \code{\link[FactoMineR]{MCA}}) transformation to the covariates and sets distance to \code{"euclidean"}.
\item \strong{Mixed covariates:} Applies Factor Analysis of Mixed Data transformation (see \code{\link[FactoMineR]{FAMD}}) to the covariates and sets distance to \code{"euclidean"}.
}}
}
\value{
A list of six elements, each of which is a list structured as follows:

The first element, \code{win_proportion}, is a list with two components: \code{value} and \code{std},
where \code{std} represents the standard deviation.

The second element, \code{lose_proportion}, is a list with two components: \code{value} and \code{std},
where \code{std} represents the standard deviation.

The third element, \code{win_ratio}, is a list containing three components: \code{value}, \code{lower_CI},
and \code{upper_CI}, with \code{lower_CI} and \code{upper_CI} representing the confidence interval bounds.

The fourth element, \code{net_benefit}, is a list containing three components: \code{value}, \code{lower_CI},
and \code{upper_CI}, with \code{lower_CI} and \code{upper_CI} representing the confidence interval bounds.

The fifth and sixth elements, \code{win_vector} and \code{lose_vector}, are numeric vectors representing the number of wins and losses
for each matched element, respectively. Their entries follow the same order as the rows in \code{base}.
}
\description{
\code{nn_win_ratio()} calculates the win/loss proportion, win ratio, and net benefit
by performing nearest-neighbor matching between individuals in the treatment group
and those in the control group based on a specified ground distance. After matching,
the outcomes of paired individuals are compared to determine winners and losers.
}
\examples{
## Mixed Covariates ##

set.seed(123)
n <- 100
base <- data.frame(
  X1 = rnorm(n, mean = 5, sd = 2), # numeric covariate 1
  X2 = rnorm(n, mean = 10, sd = 3), # numeric covariate 2
  X3 = factor(sample(c("A", "B", "C"), n, replace = TRUE)), # factor covariate
  Y1 = rnorm(n, mean = 50, sd = 10), # numeric outcome 1
  Y2 = rnorm(n, mean = 100, sd = 20), # numeric outcome 2
  arm = sample(c(0, 1), n, replace = TRUE) # binary treatment arm
)
treatment_name <- "arm"
outcome_names <- c("Y1", "Y2")
res <- nn_win_ratio(
  base = base,
  treatment_name = treatment_name,
  outcome_names = outcome_names
)

## Categorical Covariates ##

set.seed(123)
n <- 100
base <- data.frame(
  X1 = factor(sample(c("A", "B", "C"), n, replace = TRUE)), # factor covariate
  X2 = factor(sample(c("A", "B", "C"), n, replace = TRUE)), # factor covariate
  X3 = factor(sample(c("A", "B", "C"), n, replace = TRUE)), # factor covariate
  Y1 = rnorm(n, mean = 50, sd = 10), # numeric outcome 1
  Y2 = rnorm(n, mean = 100, sd = 20), # numeric outcome 2
  arm = sample(c(0, 1), n, replace = TRUE) # binary treatment arm
)
treatment_name <- "arm"
outcome_names <- c("Y1", "Y2")
res <- nn_win_ratio(
  base = base,
  treatment_name = treatment_name,
  outcome_names = outcome_names
)

## Input a Distance Matrix ##

set.seed(123)
n <- 100
base <- data.frame(
  X1 = rnorm(n, mean = 5, sd = 2), # numeric covariate 1
  X2 = rnorm(n, mean = 5, sd = 2), # numeric covariate 2
  X3 = rnorm(n, mean = 5, sd = 2), # numeric covariate 3
  Y1 = rnorm(n, mean = 50, sd = 10), # numeric outcome 1
  Y2 = rnorm(n, mean = 100, sd = 20), # numeric outcome 2
  arm = sample(c(0, 1), n, replace = TRUE) # binary treatment arm
)
treatment_name <- "arm"
outcome_names <- c("Y1", "Y2")

covariate_names <- setdiff(colnames(base), c(outcome_names, treatment_name))
covariate_data <- base[, covariate_names, drop = FALSE]
distance_matrix <- as.matrix(dist(covariate_data, method = "euclidean"))

res_dist <- nn_win_ratio(
  base = base,
  treatment_name = treatment_name,
  outcome_names = outcome_names,
  distance = distance_matrix
)

res <- nn_win_ratio(
  base = base,
  treatment_name = treatment_name,
  outcome_names = outcome_names
)

res <- unlist(res)
res_dist <- unlist(res_dist)

print(all.equal(res, res_dist))

## Input a Win function ##

set.seed(123)
n <- 100
base <- data.frame(
  X1 = rnorm(n, mean = 5, sd = 2), # numeric covariate 1
  X2 = rnorm(n, mean = 5, sd = 2), # numeric covariate 2
  X3 = rnorm(n, mean = 5, sd = 2), # numeric covariate 3
  Y1 = rbinom(n, size = 1, prob = 0.5), # binary outcome 1 (0/1) with 50\% chance
  Y2 = rbinom(n, size = 10, prob = 0.7), # counts out of 10 trials with 70\% success rate
  arm = sample(c(0, 1), n, replace = TRUE) # binary treatment arm
)
treatment_name <- "arm"
outcome_names <- c("Y1", "Y2")

# Contrary to the default win function, which yields 0 for ties,
# the following win function yields 0.5.

win_function <- function(treated_row, control_row) {
  y <- as.matrix(treated_row[, outcome_names], drop = FALSE)
  z <- as.matrix(control_row[, outcome_names], drop = FALSE)
  if (all(y == z)) {
    return(0.5) # Tie, a zero in the default win function
  }
  result <- (y > z)[which.max(y != z)] * 1
  return(result)
}

res <- nn_win_ratio(
  base = base,
  treatment_name = treatment_name,
  outcome_names = outcome_names,
  win_function = win_function
)
}
