% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/eif_win_ratio.R
\name{eif_win_ratio}
\alias{eif_win_ratio}
\title{Win/Loss Ratios with Efficient Influence Functions}
\usage{
eif_win_ratio(
  base,
  treatment_name,
  outcome_names,
  win_function = "lexicographic",
  distance = NULL,
  n_trees_drf = 1000,
  n_of_folds = 3,
  seed = NULL,
  propensity_model = "probability_forest",
  n_trees_propensity = 1000,
  propensity_scores = NULL,
  clip_propensity = 0
)
}
\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{Mixed covariates:} Applies Factor Analysis of Mixed Data transformation (see \code{\link[FactoMineR]{FAMD}}) to the covariates and sets distance to \code{"euclidean"}.
\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{n_trees_drf}{Number of trees grown in the distributional random forests.
It passed as the argument \code{num.trees} to \code{\link[drf]{drf}}. The default value is 1000.}

\item{n_of_folds}{Number of folds used in cross-fitting. The default value is 3.}

\item{seed}{Numeric value used in \code{set.seed()} to guarantee reproducible results when sampling the folds. The default value is \code{NULL}.}

\item{propensity_model}{Character string specifying the type of model to use.
Must be either "glm" or "probability_forest".
Defaults to "probability_forest". The model is only used if no vector
of propensity scores (\code{propensity_scores}) is provided.}

\item{n_trees_propensity}{Number of trees grown when computing the propensity scores using \code{propensity_model}.}

\item{propensity_scores}{Numeric vector of propensity score probabilities}

\item{clip_propensity}{Numeric value used to clip propensity scores,
ensuring they lie within the interval \verb{[clip_propensity, 1 - clip_propensity]}. The default value is zero.}
}
\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 containing the plug-in estimator
evaluated for each individual, along with the corresponding EIF correction term.
}
\description{
\code{eif_win_ratio()} calculates the win/loss proportion, win ratio, and net benefit
by adding a correction term to \code{drf_win_ratio()} using Efficient Influence Functions.
}
\examples{
## Input Propensity Scores ##

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")

ps_model <- stats::glm(arm ~ X1 + X3, # only consider X1 and X3 and no cross-fitting
  family = binomial(),
  data = base
)

propensity_scores <- stats::predict(ps_model, type = "response")
res <- eif_win_ratio(
  base = base,
  treatment_name = treatment_name,
  outcome_names = outcome_names,
  propensity_scores = propensity_scores
)
}
