% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hnp_package.r
\name{hnp_umbrella}
\alias{hnp_umbrella}
\title{HNP Umbrella Algorithm}
\usage{
hnp_umbrella(
  X,
  Y,
  levels,
  tolerances,
  importance_order,
  method = "logistic",
  pretrained_model = NULL,
  input_is_score = FALSE,
  grid_search = TRUE,
  grid_set = NULL,
  max_grid = 15,
  max_combinations = 2000,
  hnp_split = NULL,
  verbose = FALSE
)
}
\arguments{
\item{X}{A data.frame of features, or an \verb{n x T} score matrix when
\code{input_is_score = TRUE}.}

\item{Y}{A vector of class labels of length \code{nrow(X)}. All labels must be
covered by \code{importance_order}.}

\item{levels}{Numeric vector of length \code{T - 1}. Control levels (alpha) for
the under-classification error of classes 1, ..., T-1. Each must lie in (0, 1).}

\item{tolerances}{Numeric vector of length \code{T - 1}. Tolerance (delta) values
for the confidence bounds. Each must lie in (0, 1).}

\item{importance_order}{Character vector giving the class priority order,
most severe first. Defines the mapping to internal levels "1", ..., "T".}

\item{method}{Character string: one of 'randomforest', 'svm', or 'logistic'.
The base method used when training a scoring-type classifier internally.}

\item{pretrained_model}{Optional. A user-supplied scoring model: a fitted
model object, a function returning an \verb{n x T} score/probability matrix, or
a list containing \code{score_functions}. When provided, no internal model is
trained.}

\item{input_is_score}{Logical. If \code{TRUE}, \code{X} is treated as a precomputed
\verb{n x T} score matrix and \code{pretrained_model} is ignored.}

\item{grid_search}{Logical. If \code{TRUE}, search candidate thresholds to
minimize the weighted remaining error; if \code{FALSE}, use the upper-bound as
thresholds directly.}

\item{grid_set}{Optional list of length \code{T - 1} of candidate threshold
vectors per class. If \code{NULL}, candidates are derived from the threshold set.}

\item{max_grid}{Integer. Maximum number of candidate thresholds considered
per class in the grid search.}

\item{max_combinations}{Integer. Maximum number of threshold combinations
explored in the grid search.}

\item{hnp_split}{Optional list of length \code{T} specifying the class-wise data
split ratios (train / threshold / error). If \code{NULL}, sensible defaults are
used based on \code{grid_search} and whether scores are already available.}

\item{verbose}{Logical. If \code{TRUE}, print progress information.}
}
\value{
A HNP Umbrella classifier function \verb{function(new_data, output_internal = FALSE)}
that returns predicted class labels (original labels by default, internal
labels if \code{output_internal = TRUE}), with attributes recording the selected
thresholds, objective value, \code{importance_order}, label mapping, and other
metadata. Returns \code{NULL} if no feasible classifier is found.
}
\description{
Implementation of the Hierarchical Neyman-Pearson (HNP) Umbrella
algorithm for general \code{T}-class classification (\code{T >= 2}). Classes are
ordered by \code{importance_order} and re-labelled internally to the classes "1", ..., "T".
The algorithm trains (or reuses) a scoring-type classifier (e.g. random forest, support
vector machine, or logistic regression) and selects thresholds that control the
under-classification error of the more severe classes at the requested
levels with the given tolerances, either by treating upper bounds as thresholds or by
a grid search that minimizes the weighted remaining error.
}
\examples{
set.seed(123)
n <- 500
X <- data.frame(x1 = rnorm(n), x2 = rnorm(n))
Y <- sample(c("A", "B", "C"), n, replace = TRUE, prob = c(0.2, 0.3, 0.5))
clf <- hnp_umbrella(
  X = X, Y = Y,
  levels = c(0.1, 0.1),
  tolerances = c(0.1, 0.1),
  importance_order = c("A", "B", "C"),
  method = "logistic"
)
preds <- clf(X)
}
\references{
Lijia Wang, Y. X. Rachel Wang, Jingyi Jessica Li, and Xin Tong (2024).
"Hierarchical Neyman-Pearson Classification for Prioritizing Severe Disease
Categories in COVID-19 Patient Data."
\emph{Journal of the American Statistical Association}, 119(545), 39-51.
\doi{10.1080/01621459.2023.2270657}
}
