sim_bound {bandsfdp}  R Documentation 
Simultaneous Band
Description
This function computes upper prediction bounds on the target wins among the
top k
hypotheses of TDC, for each k = 1,\ldots,n
where n
is the total number of hypotheses.
Usage
sim_bound(
labels,
gamma,
type,
d_max = NULL,
max_fdp = 0.5,
c = 0.5,
lambda = 0.5
)
simband(
labels,
gamma,
type,
d_max = NULL,
max_fdp = 0.5,
c = 0.5,
lambda = 0.5
)
Arguments
labels 
A vector of (ordered) labels. See details below. 
gamma 
The confidence parameter of the band. Typical values include

type 
A character string specifying which band to use. Must be one of

d_max 
An optional positive integer specifying the maximum number of decoy wins considered in calculating the bands. 
max_fdp 
A number specifying the maximum FDP considered by the user in
calculating the bands. Used to compute 
c 
Determines the ranks of the target score that are considered
winning. Defaults to 
lambda 
Determines the ranks of the target score that are
considered losing. Defaults to 
Details
In (singledecoy) TDC, each hypothesis is associated to a
winning score and a label (1 for a target win, 1 for a decoy win). This
function assumes that the hypotheses are ordered in decreasing order of
winning scores (with ties broken at random). The argument labels
,
therefore, must be ordered according to this rule.
This function also supports the extension of TDC that uses multiple
decoys. In that setup, the target score is competed with multiple decoy
scores and the rank of the target score after competition is used to determine whether the
hypothesis is a target win (label = 1), decoy win (1) or uncounted (0).
The top c
proportion of ranks are considered winning, the bottom
1lambda
losing, and all the rest uncounted.
The threshold of TDC is given by the formula (assuming hypotheses are ordered):
\max\{k : \frac{D_k + 1}{T_k \vee 1} \cdot \frac{c}{1\lambda} \leq \alpha\}
where T_k
is the number of target wins among the top
k
hypotheses, and D_k
is the number of decoy wins similarly.
The argument gamma
sets a confidence level of 1gamma
. Both
the uniform and standardized bands require precomputed Monte Carlo
statistics, so only certain values of gamma
are available to use.
Commonly used confidence levels, like 0.95 and 0.99, are available.
We refer the reader to the README of this package for more details.
The argument d_max
controls the rate at which the returned bounds
increase: a larger d_max
results in a more conservative bound.
If, however, D_k + 1
exceeds d_max
for some index k
, each target
win thereafter is considered a false discovery when computing the bound.
Thus it is important that d_max
, chosen a priori, is large enough. Given
it is sufficiently large, the precise value of d_max
does not have a
significant effect on the resulting bounds (see https://arxiv.org/abs/2302.11837 for more details).
We recommend setting d_max = NULL
so that it is computed automatically
using max_fdp
. This argument ensures that D_k + 1
never
exceeds d_max
when the (noninterpolated) FDP bound on the top
k
hypotheses is less than max_fdp
.
Value
A vector of upper prediction bounds on the FDP of target wins among
the top k
hypotheses for each k = 1,\ldots,n
where n
is the total number of hypotheses.
References
Ebadi et al. (2022), Bounding the FDP in competitionbased control of the FDR https://arxiv.org/abs/2302.11837.
Examples
if (requireNamespace("fdpbandsdata", quietly = TRUE)) {
set.seed(123)
labels < c(
rep(1, 250),
sample(c(1, 1), size = 250, replace = TRUE, prob = c(0.9, 0.1)),
sample(c(1, 1), size = 250, replace = TRUE, prob = c(0.5, 0.5)),
sample(c(1, 1), size = 250, replace = TRUE, prob = c(0.1, 0.9))
)
gamma < 0.05
head(sim_bound(labels, gamma, "stband"))
}