% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/drf_win_ratio.R
\name{drf_win_ratio}
\alias{drf_win_ratio}
\title{Win/Loss Ratios with Distributional Random Forests}
\usage{
drf_win_ratio(
  base,
  treatment_name,
  outcome_names,
  win_function = "lexicographic",
  n_trees_drf = 1000,
  n_of_folds = 3,
  seed = 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{n_trees_drf}{Number of trees grown in the forest.
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}.}
}
\value{
A list of four 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, win_vector and lose_vector, are numeric vectors containing the nuisance function values evaluated for each individual.
}
\description{
\code{drf_win_ratio()} Computes the win/loss proportion, win ratio, and net benefit
by estimating nuisance parameters with machine learning methods.
This estimation is performed via distributional regression, implemented using distributional random forests.
}
\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 <- drf_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 <- drf_win_ratio(
  base = base,
  treatment_name = treatment_name,
  outcome_names = outcome_names
)
}
