singlesample_matched_null_benchmark.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/singlesample-matched-null.R
\name{singlesample_matched_null_benchmark}
\alias{singlesample_matched_null_benchmark}
\title{Single-sample matched-null benchmark for within-sample miRNA panel scoring}
\usage{
singlesample_matched_null_benchmark(
  X,
  y,
  panel,
  scoring_fn,
  K = 10000L,
  feature_pool = NULL,
  exclude_features = character(0),
  post_hemolysis_corrected = FALSE,
  seed = 42L,
  auc_ci_method = c("hanley_mcneil", "delong", "none")
)
}
\arguments{
\item{X}{Matrix (samples \eqn{\times} features). Must have column names.
Should be the full feature pool, not just the observed panel.}

\item{y}{Binary outcome (0/1 or factor with 2 levels).}

\item{panel}{Character vector of feature names in the observed panel.}

\item{scoring_fn}{Function \code{function(X_subset)} returning a per-sample
numeric score.}

\item{K}{Integer — number of null panels. Default 10,000 (per plan v0.3.3).}

\item{feature_pool}{Character vector — full feature pool. Defaults to
\code{colnames(X)}.}

\item{exclude_features}{Character — feature names to exclude from the
candidate pool (e.g., hemolysis markers). Default \code{character(0)}.}

\item{post_hemolysis_corrected}{Logical. If \code{TRUE}, prepends the
canonical hemolysis-marker list to \code{exclude_features}. Default
\code{FALSE}.}

\item{seed}{Integer — RNG seed. Default 42.}

\item{auc_ci_method}{Character; one of \code{"hanley_mcneil"} (default;
closed-form Hanley-McNeil 1982 standard error), \code{"delong"}
(\code{pROC::ci.auc(method="delong")}; requires \code{pROC} >= 1.16),
or \code{"none"} (skip CI). The 95\% CI is reported alongside the
observed AUC as \code{auc_obs_ci_lo} / \code{auc_obs_ci_hi}.}
}
\value{
A list with components:
  \describe{
    \item{\code{auc_obs}}{Observed panel AUC.}
    \item{\code{auc_obs_ci_lo}, \code{auc_obs_ci_hi}}{95\% confidence
      interval for the observed AUC; NA when
      \code{auc_ci_method = "none"} or computation fails.}
    \item{\code{auc_null}}{Length-\code{K} numeric vector of null AUCs
      (NA for degenerate draws).}
    \item{\code{p_emp}}{Empirical p-value, or \code{NA_real_} if not
      eligible.}
    \item{\code{panel_size}}{Number of features in the observed panel.}
    \item{\code{K}, \code{seed}}{Parameters as supplied.}
    \item{\code{null_panels}}{List of length \code{K} of random feature
      name sets.}
    \item{\code{excluded_features}}{Final exclusion list applied.}
    \item{\code{eligible}}{Logical: whether matched-null p-value is valid.}
    \item{\code{fallback_tier}}{1, 2, or 3 (3 = not eligible).}
    \item{\code{fallback_count}}{Number of draws that fell back to tier 3.}
  }
}
\description{
For an observed scoring method \code{scoring_fn} applied to a panel of
size \code{k}, generates \code{K} random panels of the same size drawn from
the cohort feature pool, jointly stratified on per-feature detection-rate and
log-mean-abundance quartile bins (16 strata total). The empirical p-value
measures whether the observed panel AUC exceeds the matched-null distribution.

Name note: the simpler (non-stratified) package predecessor is
\code{\link{os_panel_null_benchmark}} (\code{panel-gates.R}). This function
uses the name \code{singlesample_matched_null_benchmark} to avoid collision.
}
\examples{
\dontrun{
set.seed(42)
X <- matrix(rlnorm(100 * 50, meanlog = 5, sdlog = 1), nrow = 100,
            dimnames = list(NULL, paste0("mir-", seq_len(50))))
y <- rbinom(100, 1, 0.5)
panel <- paste0("mir-", 1:10)
res <- singlesample_matched_null_benchmark(X, y, panel,
         scoring_fn = function(M) rowSums(log(M + 1)),
         K = 200L)
res$p_emp
}

}