% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/score_to_pvalue.R
\name{score_to_pvalue}
\alias{score_to_pvalue}
\title{Convert identification scores to p-values or pseudo-p-values}
\usage{
score_to_pvalue(
  score,
  method = c("mascot", "neglog10p", "evalue", "rank", "decoy_ecdf"),
  is_decoy = NULL,
  eps = .Machine$double.xmin,
  clamp = TRUE,
  ties = c("average", "first", "random", "max", "min")
)
}
\arguments{
\item{score}{Numeric vector. Identification scores. Higher-is-better is assumed for
\code{method = "rank"} and \code{method = "decoy_ecdf"} (flip sign upstream if needed).}

\item{method}{Character. Conversion method:
\describe{
\item{\code{"mascot"}}{Treat \code{score} as Mascot score \eqn{S=-10\log_{10}(p)}; returns \eqn{p=10^{-S/10}}.}
\item{\code{"neglog10p"}}{Generic \eqn{S=-10\log_{10}(p)}; same transform as \code{"mascot"}.}
\item{\code{"evalue"}}{Treat \code{score} as an expectation/e-value-like quantity and return it as a p-like value.}
\item{\code{"rank"}}{Rank-based pseudo-p-values \eqn{p_i=\mathrm{rank}(-s_i)/(n+1)}.}
\item{\code{"decoy_ecdf"}}{Decoy-ECDF pseudo-p-values from the empirical right-tail of decoy scores;
requires \code{is_decoy}.}
}}

\item{is_decoy}{Optional logical vector (same length as \code{score}). Required for
\code{method = "decoy_ecdf"}. TRUE=decoy, FALSE=target.}

\item{eps}{Numeric scalar > 0. Lower bound to avoid exact 0 (default \code{.Machine$double.xmin}).}

\item{clamp}{Logical. If \code{TRUE} (default), clamp output to \code{[0,1]}.}

\item{ties}{Character. Tie-handling for \code{method="rank"}; passed to \code{rank()}.}
}
\value{
A numeric vector of p-values/pseudo-p-values of the same length as \code{score}.
Non-finite scores yield \code{NA_real_}. For \code{method="decoy_ecdf"}, returned
values estimate the decoy right-tail probability \eqn{P(S_{decoy}\ge s)} (with a
small +1 smoothing), which can be interpreted as a null-calibrated pseudo-p-value
when decoys provide a good null sample.
}
\description{
Converts identification scores to:
\itemize{
\item \strong{p-values} when the score has a known p-value definition (e.g. Mascot score),
\item \strong{pseudo-p-values} when no such definition exists (e.g. MaxQuant/Andromeda scores).
}
}
\details{
Pseudo-p-values are useful as inputs to plausibility checks (e.g. calibration/ECDF diagnostics),
but they are not guaranteed to be valid null p-values unless the method is explicitly null-based
(e.g. \code{method = "decoy_ecdf"} with a reliable decoy set).
}
\examples{
set.seed(1)
score <- rnorm(10)

# Mascot-like transformation: S = -10 log10(p)
S <- c(10, 20, 30)
score_to_pvalue(S, method = "mascot")

# Rank-based pseudo-p-values (higher score => smaller p)
score_to_pvalue(score, method = "rank")

# Decoy-ECDF pseudo-p-values (requires decoys)
n <- 200
score2 <- c(rnorm(n, mean = 0), rnorm(n, mean = 1))  # targets shifted higher
is_decoy <- c(rep(TRUE, n), rep(FALSE, n))
p2 <- score_to_pvalue(score2, method = "decoy_ecdf", is_decoy = is_decoy)
summary(p2)

}
