% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/minmax_regret.R
\name{minmax_regret}
\alias{minmax_regret}
\title{Minimax-regret aggregator for multisite function-valued estimands}
\usage{
minmax_regret(F_hat, grid_weights = NULL, ridge = 1e-10, wrapper = NULL)
}
\arguments{
\item{F_hat}{An \code{m}-by-\code{G_grid} numeric matrix of source-site function
evaluations on a shared grid; row \code{i} is \eqn{\hat f^{(i)}}.}

\item{grid_weights}{Optional length-\code{G_grid} non-negative numeric vector
defining the target measure used to compute \eqn{\hat\Gamma} and
\eqn{\hat d}. Defaults to uniform weights \code{1 / G_grid}.}

\item{ridge}{Non-negative scalar; replaces \eqn{\hat\Gamma} with
\eqn{\hat\Gamma + \text{ridge}\cdot I} for numerical stability.
Defaults to \code{1e-10}.}

\item{wrapper}{Optional reduction function (see \code{\link[=apply_wrapper]{apply_wrapper()}}). If
\code{NULL}, \code{prediction} is the length-\code{G_grid} predicted target function;
if a function, \code{prediction} is the scalar \code{wrapper(prediction)}
(e.g. an ATE when \code{wrapper = mean} and rows of \code{F_hat} are CATE
evaluations).}
}
\value{
An object of class \code{"minmax_regret"}: a list with
\describe{
\item{\code{prediction}}{Predicted target. Length-\code{G_grid} vector when
\code{wrapper = NULL}; scalar otherwise.}
\item{\code{q}}{Length-\code{m} simplex weights from the minimax-regret QP.}
\item{\code{Gamma}}{The \code{m}-by-\code{m} Gram matrix used (post-ridge).}
\item{\code{d}}{Length-\code{m} linear coefficient vector.}
\item{\code{grid_weights}}{Grid weights used.}
\item{\code{ridge}}{Ridge value used.}
\item{\code{wrapper}}{Wrapper function or \code{NULL}.}
}
}
\description{
Implements the minimax-regret estimator of Zhang, Huang, and Imai
(\href{https://arxiv.org/abs/2412.11136}{arXiv:2412.11136}) for
aggregating site-level function estimates. Given study-level functions
\eqn{\hat f^{(i)}}, the estimator is
\deqn{\hat q = \arg\min_{q \in \Delta_{m-1}}\
  q^\top \hat\Gamma\, q - \hat d^\top q,
  \qquad
  \hat\Gamma_{ij} = \sum_g w_g\, \hat f^{(i)}(x_g)\hat f^{(j)}(x_g),\ \
  \hat d_i = \sum_g w_g\, (\hat f^{(i)}(x_g))^2,}
yielding the predicted target function
\eqn{\tilde f(x) = \sum_{i=1}^m \hat q_i\, \hat f^{(i)}(x)}.
Unlike \code{\link[=metahunt]{metahunt()}}, this method does not use study-level covariates;
the target is the worst-case-regret aggregator over the convex hull of
source functions.
}
\details{
The simplex-constrained QP is solved with \code{\link[quadprog:solve.QP]{quadprog::solve.QP()}}.
A small ridge is added to \eqn{\hat\Gamma} for numerical stability when
source functions are highly collinear. The resulting \code{q} is clipped to
be non-negative and renormalised to sum to 1 to absorb floating-point
drift.
}
\examples{
set.seed(1)
G <- 30; m <- 6
x <- seq(0, 1, length.out = G)
F_hat <- rbind(
  sin(pi * x),
  cos(pi * x),
  x,
  0.5 * sin(pi * x) + 0.5 * x,
  0.3 * cos(pi * x) + 0.7 * x,
  0.4 * sin(pi * x) + 0.4 * cos(pi * x) + 0.2 * x
)

fit <- minmax_regret(F_hat)
fit$q                                        # simplex weights over sources
length(fit$prediction)                       # G: predicted target function

# ATE-style scalar via wrapper
minmax_regret(F_hat, wrapper = mean)$prediction

}
\references{
Zhang, Y., Huang, M., and Imai, K. (2024). Minimax regret estimation
for generalizing heterogeneous treatment effects with multisite data.
\href{https://arxiv.org/abs/2412.11136}{arXiv:2412.11136}.
}
