Package 'diagFDR'

Description

Coerces input to a tibble, standardizes the is_decoy column to logical, validates required columns and types, attaches metadata, and returns an S3 object of class dfdr_tbl for downstream diagnostics.

Usage

as_dfdr_tbl(
  x,
  unit = NA_character_,
  scope = NA_character_,
  q_source = NA_character_,
  q_max_export = NA_real_,
  p_source = NA_character_,
  provenance = list(),
  two_pass = NA
)

Arguments

Value

An S3 object of class dfdr_tbl that inherits from tbl_df (and data.frame). The returned object:

• contains the validated input data with is_decoy coerced to logical (TRUE/FALSE);

• carries metadata in attr(x, "meta") with entries unit, scope, q_source, q_max_export, p_source, two_pass and provenance.

Examples

library(tibble)

df <- tibble(
  id = as.character(1:6),
  run = c("run1","run1","run1","run2","run2","run2"),
  is_decoy = c(FALSE, FALSE, TRUE, FALSE, TRUE, FALSE),
  score = c(10, 9, 8, 7, 6, 5),
  q = c(0.01, 0.02, 0.02, 0.05, 0.06, 0.07),
  pep = c(0.01, 0.02, NA, 0.05, NA, 0.07)
)

x <- as_dfdr_tbl(
  df,
  unit = "psm",
  scope = "global",
  q_source = "toy_q",
  provenance = list(tool = "toy")
)

x
attr(x, "meta")

Description

Search engines export several rows per reported unit (one row per run and precursor; many precursor rows per protein group). Building the list a paper reports requires collapsing rows to units, and when the rows of a unit do not all carry the same target/decoy label, a rule must decide which label the unit inherits. This function implements the four rules compared in the diagFDR paper (Supplementary Note S9):

Usage

collapse_universe(
  rep,
  key_col,
  q_col,
  rule = c("split", "winning_row", "any_decoy", "majority"),
  decoy_col = "Decoy",
  pep_col = "PEP",
  score_col = NULL,
  q_max_export = NA_real_,
  unit = "protein_group",
  scope = "global",
  q_source = q_col,
  two_pass = NA,
  tool = NA_character_,
  drop_empty_key = TRUE
)

Arguments

Details

"split"

No label is propagated: the target rows and the decoy rows of an identifier are two distinct hypotheses, each kept at its own minimum q-value. A label-mixed identifier therefore yields one target unit and one decoy unit. This reproduces DIA-NN's protein-group q-values and is the recommended rule wherever the software competes target and decoy versions of a group.

"winning_row"

The unit inherits the label of the row that supplied its minimum q-value. The defensible default when a genuine collapse to one unit per identifier is required.

"any_decoy"

The unit is a decoy if any of its rows is. What a direct any(is_decoy) aggregation produces; not recommended on label-mixed identifiers.

"majority"

The unit is a decoy if more than half of its rows are (ties resolve to target). Not recommended: its value depends on how many low-confidence rows survived the export filter.

In all rules the retained q-value (and PEP, when present) is the minimum over the rows of the unit, and the retained score the maximum.

Value

A dfdr_tbl with one row per unit (two per label-mixed identifier under "split"), whose provenance records label_rule, key, the number of label-mixed identifiers (n_mixed) and the number of rows dropped.

See Also

label_is_intrinsic, dfdr_label_rule_audit, diann_global_proteingroup, dfdr_picked_protein.

Examples

rep <- data.frame(
  Protein.Group = c("P1", "P1", "P1", "P1", "P2", "P3"),
  Decoy = c(1, 0, 0, 0, 0, 1),
  Global.PG.Q.Value = c(0.004, 0.02, 0.30, 0.60, 0.001, 0.05))
collapse_universe(rep, "Protein.Group", "Global.PG.Q.Value", rule = "split")
collapse_universe(rep, "Protein.Group", "Global.PG.Q.Value", rule = "winning_row")

Description

Accepted target identifiers of a list at a threshold

Usage

dfdr_accepted(x, alpha = 0.01, strip_run = TRUE)

Arguments

Value

Character vector of accepted target ids.

Examples

sim <- dfdr_simulate_tdc(n = 2000, seed = 2)
length(dfdr_accepted(sim, 0.01))

Description

Returns, for each flag produced by flag_headline, the diagnostic it applies to, its alert threshold and the evidential basis of that threshold, so that alerts are not read as equally calibrated:

derived check

follows from a stated result (e.g. the recomputed decoy ratio reproduces the definition of a counted q-value);

simulation-informed alert

threshold calibrated against the ground-truth simulations of the diagFDR paper;

heuristic alert

practical guideline taken from the paper's case studies, to be re-derived locally;

descriptive

reported without threshold, as a sensitivity measure.

Entrapment-based estimates, when supplied, are external evidence and carry no package alert. The decoy-ratio alert levels (1.2 and 1.5 times alpha) are review margins around a derived identity: for q-values counted on the reported list, $D_\alpha/T_\alpha \le \alpha$ by construction.

Usage

dfdr_alert_basis()

Value

A tibble with columns flag, diagnostic, threshold and basis.

Examples

dfdr_alert_basis()

Description

Computes the Benjamini–Hochberg (BH) rejection threshold $t_\alpha$, the number of discoveries $R_\alpha$, and a simple "boundary support" measure: the number of p-values just above $t_\alpha$. Boundary support is intended to indicate how sensitive the discovery set may be to small perturbations of p-values near the cutoff.

Usage

dfdr_bh_diagnostics(
  x,
  alpha = 0.01,
  boundary = c("mult", "add"),
  win = 0.2,
  delta = NULL
)

Arguments

Value

A list with two elements:

headline

A one-row tibble containing BH summary diagnostics, including t_alpha (the BH threshold), R_alpha (the number of rejected hypotheses / discoveries), and N_boundary (the number of p-values in a right-neighborhood above the cutoff as determined by boundary, win, and delta).

accepted

A character vector of id values corresponding to discoveries (rows with p <= t_alpha). If no finite BH threshold exists, this is character(0).

Examples

library(tibble)

set.seed(1)
n <- 5000
x <- tibble(
  id = as.character(seq_len(n)),
  p = c(stats::runif(4500), stats::rbeta(500, 0.3, 1))
)

out <- dfdr_bh_diagnostics(x, alpha = 0.01, boundary = "mult", win = 0.2)
out$headline
length(out$accepted)

Description

Computes the stability (elasticity) of Benjamini–Hochberg (BH) discovery sets under a multiplicative perturbation of the nominal FDR level. For each alpha in alphas, the function compares the BH discovery set at alpha to the discovery set at (1+eps)*alpha using the Jaccard index.

Usage

dfdr_bh_elasticity(
  x,
  alphas = c(1e-04, 5e-04, 0.001, 0.002, 0.005, 0.01, 0.02, 0.05),
  eps = 0.2
)

Arguments

Value

A tibble with one row per element of alphas. Columns include:

alpha

The nominal BH level.

alpha_perturbed

The perturbed level min((1+eps)*alpha, 1).

t_alpha

BH rejection threshold at alpha (NA if no rejections).

t_alpha_perturbed

BH rejection threshold at alpha_perturbed (NA if none).

R_alpha

Number of discoveries at alpha.

R_alpha_perturbed

Number of discoveries at alpha_perturbed.

jaccard

Jaccard similarity between the two discovery ID sets.

This output is intended to quantify how sensitive BH discoveries are to small changes in the chosen FDR level.

Examples

library(tibble)

set.seed(1)
n <- 5000
x <- tibble(
  id = as.character(seq_len(n)),
  # mixture: mostly null p-values + a small enriched component
  p = c(stats::runif(4500), stats::rbeta(500, 0.3, 1))
)

dfdr_bh_elasticity(x, alphas = c(1e-3, 5e-3, 1e-2, 2e-2), eps = 0.2)

Description

Repeats dfdr_simulate_tdc B times and compares the coefficient of variation of the realised FDP across replicates with the benchmark $\sqrt2\,D_\alpha^{-1/2}$ of Proposition 1 of the diagFDR paper, returning the ratio $\kappa = \mathrm{CV(FDP)} / \overline{D_\alpha^{-1/2}}$ (expected $\approx 1.41$ under independent Gaussian nulls).

Usage

dfdr_check_cv_benchmark(B = 200, alpha = 0.01, ...)

Arguments

Value

A data.frame with, per alpha: mean FDP, CV_FDP, mean D_alpha, mean support index, kappa, the share of replicates with FDP above alpha, Var_V and 2 E[D] + Var(D).

Examples

dfdr_check_cv_benchmark(B = 20, n = 20000, alpha = 0.01)

Description

Evaluates dfdr_headline over a grid of FDR thresholds (alphas) to obtain a stability curve that can be plotted or compared across workflows.

Usage

dfdr_curve_stability(x, alphas, k_fixed = 10, k_sqrt_mult = 2)

Arguments

Value

A tibble with one row per value of alphas. Columns are those returned by dfdr_headline plus the corresponding alpha. The table summarizes how headline quantities (e.g., accepted target/decoy counts and sensitivity diagnostics) vary with the chosen FDR cutoff.

Examples

library(tibble)

set.seed(1)
n <- 5000
df <- tibble(
  id = as.character(seq_len(n)),
  run = "run1",
  is_decoy = sample(c(FALSE, TRUE), n, replace = TRUE, prob = c(0.95, 0.05)),
  score = rnorm(n),
  pep = NA_real_
)

df$q <- diagFDR:::tdc_qvalues(df$score, df$is_decoy, add_decoy = 1L)
x <- as_dfdr_tbl(df, unit = "psm", scope = "global", q_source = "toy_tdc")

dfdr_curve_stability(x, alphas = c(1e-3, 5e-3, 1e-2))

Description

Computes the stability of the accepted target set under a multiplicative perturbation of the threshold:

$S_\alpha(\epsilon) = J(A(\alpha), A((1+\epsilon)\alpha)),$

where $J$ is the Jaccard index and $A(\alpha)$ is the set of accepted target IDs at threshold $\alpha$.

Usage

dfdr_elasticity(x, alphas, eps = 0.2)

Arguments

Value

A tibble with one row per alpha. Columns include:

alpha

The baseline threshold.

eps

The relative perturbation.

n1

Number of accepted targets at alpha.

n2

Number of accepted targets at (1+eps)*alpha.

jaccard

Jaccard overlap between the two accepted target sets.

Examples

library(tibble)

set.seed(1)
n <- 5000
df <- tibble(
  id = as.character(seq_len(n)),
  run = "run1",
  is_decoy = sample(c(FALSE, TRUE), n, replace = TRUE, prob = c(0.95, 0.05)),
  score = rnorm(n),
  pep = NA_real_
)

df$q <- diagFDR:::tdc_qvalues(df$score, df$is_decoy, add_decoy = 1L)
x <- as_dfdr_tbl(df, unit = "psm", scope = "global", q_source = "toy_tdc")

dfdr_elasticity(x, alphas = c(1e-3, 5e-3, 1e-2), eps = 0.2)

Description

Entrapment augments the target space with a proteome known to be absent from the sample, searched as ordinary targets. Accepted matches mapping only to it are empirical false positives independent of the decoys. With $E_\alpha$ such matches among $T_\alpha$ accepted targets, the raw estimate is $E_\alpha/T_\alpha$; the size-corrected estimate of Wen et al. (2025) is $E_\alpha(1+1/r)/(T_\alpha+E_\alpha)$, the FDP of the combined target-plus-entrapment list, where $r$ is the entrapment-to-target size ratio measured at the level where competition occurs (see dfdr_entrapment_size_ratio). The alternative $(E_\alpha/T_\alpha)/r$ estimates the FDP of the target-only list and is also returned.

Usage

dfdr_entrapment(x, entrapment, alpha = 0.01, r = NA_real_, conf = 0.95)

Arguments

Details

Wilson intervals are binomial-style descriptive intervals: they treat accepted units as independent and do not account for clustering induced by shared peptides, runs or protein groups.

Value

A data.frame with one row per alpha: T_alpha (accepted targets, entrapment matches included), E_alpha, fdp_raw, lo, hi, r, fdp_corrected (combined list), fdp_corrected_target_only, and D_alpha/decoy_ratio of the same list for comparison.

References

Wen B, Freestone J, Riffle M, MacCoss MJ, Noble WS, Keich U (2025) Assessment of false discovery rate control in tandem mass spectrometry analysis using entrapment. Nat Methods.

Examples

sim <- dfdr_simulate_tdc(n = 5000, seed = 1)
## pretend one target in ten is an entrapment sequence
ent <- !sim$is_decoy & (seq_len(nrow(sim)) %% 10 == 0) & attr(sim, "truth")$is_null
dfdr_entrapment(sim, ent, alpha = c(0.01, 0.05), r = 0.1)

Description

For two accepted target lists $A_1$ and $A_2$ on a common identifier, computes the raw entrapment FDP on the shared core $A_1 \cap A_2$, on the identifications added by $A_2$ ($A_2 \setminus A_1$), on those removed ($A_1 \setminus A_2$), and on the symmetric difference (the scope-discordant-set error rate of the diagFDR paper, Equation 5). When neither list contains the other, the added and removed sets should be read separately, since a single rate can average an error-rich addition against an error-poor removal.

Usage

dfdr_entrapment_discordant(accepted1, accepted2, entrapment_ids, conf = 0.95)

Arguments

Value

A data.frame with rows core, added, removed, discordant, list1, list2, columns n, E, fdp, lo, hi; the attribute "ratio" holds fdp[discordant] / fdp[core] and "jaccard" the overlap of the two lists.

Examples

a1 <- paste0("p", 1:100); a2 <- paste0("p", 1:120)
dfdr_entrapment_discordant(a1, a2, entrapment_ids = c("p3", "p101", "p115"))

Description

Computes $r = N_{ET}/N_T$ at protein level (number of entries) and at peptide level (number of distinct in-silico tryptic peptides), with and without the peptides shared between the two databases. The corrected entrapment estimate of dfdr_entrapment depends on which $r$ is used, which is why both must be reported. Peptide-level digestion of full proteomes takes a few minutes.

Usage

dfdr_entrapment_size_ratio(
  target_fasta,
  entrapment_fasta,
  sites = c("K", "R"),
  no_cut_before = character(0),
  missed = 1L,
  min_len = 7L,
  max_len = 30L,
  peptide_level = TRUE
)

Arguments

Value

A data.frame with quantity and value: numbers of proteins and peptides, shared peptides, r_protein, r_peptide, r_peptide_unique.

Examples

t <- tempfile(); e <- tempfile()
writeLines(c(">sp|P1|A", "MKAAAAAAAKRPEPTIDEKLLLLLLLR", ">sp|P2|B", "GGGGGGGGKRRRR"), t)
writeLines(c(">sp|A1|C", "MKAAAAAAAKRQQQQQQQQK"), e)
dfdr_entrapment_size_ratio(t, e)

Description

Computes decoy fractions in q-value bands and performs a pooled binomial test of whether the decoy fraction is near 0.5 in a mismatch-dominated region (specified by low_conf). The check assumes paired 1:1 target-decoy competition, a single-pass export and an unconditioned low-confidence band: targets and decoys listed separately, or a second pass on a library reduced by a first pass, move the fraction away from 0.5 even with valid decoys.

Usage

dfdr_equal_chance_qbands(
  x,
  breaks = c(0, 0.01, 0.02, 0.05, 0.1, 0.2, 0.5),
  low_conf = c(0.2, 0.5),
  min_N = 2000
)

Arguments

Value

A list with components:

bands

A tibble with one row per q-band, including n (band size), n_decoy, decoy_frac, and q_mean.

pooled

A one-row tibble with pooled quantities over bands whose q_mean lies within low_conf, including pi_D_hat (pooled decoy fraction), a Wilson confidence interval, and a binomial test p-value. pass_minN indicates whether min_N is met. In cases where the requested banding is not applicable (e.g. qmax below the smallest nonzero break), fields are returned as NA and a note may be provided.

params

A list of parameters used (breaks, low_conf, min_N).

Examples

library(tibble)

set.seed(1)
n <- 8000
df <- tibble(
  id = as.character(seq_len(n)),
  run = "run1",
  is_decoy = sample(c(FALSE, TRUE), n, replace = TRUE, prob = c(0.9, 0.1)),
  score = rnorm(n),
  pep = NA_real_
)
# Toy q-values in [0, 1]
df$q <- stats::runif(n)
x <- as_dfdr_tbl(df, unit = "psm", scope = "global", q_source = "toy")

ec <- dfdr_equal_chance_qbands(x, breaks = c(0, 0.2, 0.5, 1), low_conf = c(0.2, 0.5), min_N = 200)
ec$pooled

Description

Computes headline counts at the acceptance threshold corresponding to alpha (e.g., numbers of accepted targets/decoys) and simple stability diagnostics that quantify how sensitive the result is to small changes in the decoy boundary support.

Usage

dfdr_headline(x, alpha = 0.01, k_fixed = 10, k_sqrt_mult = 2)

Arguments

Details

The function assumes that x contains target/decoy labels in is_decoy and q-values in column q. If your input uses another name (e.g., q_value), rename it to q before calling this function.

Value

A one-row tibble with headline diagnostics evaluated at the specified alpha. The table includes the number of accepted targets and decoys at the threshold and additional sensitivity/stability summaries derived from perturbing the boundary decoy support (using k_fixed and k_sqrt_mult). The returned tibble is intended for reporting and for comparison across workflows.

Column FDR_hat is the recomputed decoy ratio $D_\alpha/T_\alpha$, an internal consistency check of the exported q-values, not an estimate of the realised error. Column support_index is the decoy-support index $D_\alpha^{-1/2}$; CV_benchmark is the FDP-CV benchmark $\sqrt{2}D_\alpha^{-1/2}$, an approximation to the coefficient of variation of the realised false discovery proportion under equal chance, independence, and accepted decoys standing for incorrect matches only, with $D_\alpha$ and $T_\alpha$ varying little across experiments (dependence between units and heavy-tailed null scores increase it).

Examples

library(tibble)

set.seed(1)
n <- 5000
x <- tibble(
  id = as.character(seq_len(n)),
  run = "run1",
  is_decoy = sample(c(FALSE, TRUE), n, replace = TRUE, prob = c(0.95, 0.05)),
  score = rnorm(n),
  pep = NA_real_
)

# Construct simple TDC q-values from the score (higher is better)
x$q <- diagFDR:::tdc_qvalues(score = x$score, is_decoy = x$is_decoy, add_decoy = 1L)
x <- as_dfdr_tbl(x, unit = "psm", scope = "global", q_source = "toy_tdc")

dfdr_headline(x, alpha = 0.01)

Description

Computes the IPE used in the headline table and in the diagFDR paper. Targets and decoys are binned by PEP; in each bin $b$ the mean PEP of the targets, $\overline{PEP}_{b,T}$, is compared with the decoy-derived reference $\hat e_b = \min\{1, (D_b + a)/T_b\}$, which under equal chance and 1:1 competition estimates the fraction of incorrect targets in the bin. The IPE is the size-weighted mean absolute difference

$IPE = \sum_b w_b |\overline{PEP}_{b,T} - \hat e_b|,\quad w_b = n_b / \sum_{b'} n_{b'},\quad n_b = T_b + D_b,$

over bins with $\overline{PEP}_{b,T} \le$ pep_max and $n_b \ge$ n_min.

Usage

dfdr_ipe(x, binwidth = 0.05, pep_max = 0.5, n_min = 200, add_decoy = 0L)

Arguments

Details

The IPE measures concordance between reported PEPs and the decoys of the same export (an internal, T2, check). It cannot tell whether the PEPs are correct probabilities of incorrect identification, which requires external validation (e.g. entrapment).

Value

A list with bins (one row per bin: bin, n_target, n_decoy, n, pep_mean_targets, e_b, used), IPE (numeric scalar, NA if no bin is eligible), bins_used and params.

Examples

library(tibble)
set.seed(1)
n <- 20000
null <- runif(n) < 0.3
lab_decoy <- null & runif(n) < 0.5
df <- tibble(
  id = as.character(seq_len(n)), run = "run1",
  is_decoy = lab_decoy,
  score = ifelse(null, rnorm(n), rnorm(n, 3)),
  q = 0, pep = pmin(1, pmax(0, plogis(-2 * score + 1)))
)
x <- as_dfdr_tbl(df, unit = "psm", scope = "global", q_source = "toy")
dfdr_ipe(x)$IPE

Description

Given accession strings such as DIA-NN's Protein.Group ("P12345;Q67890") and the set of entrapment accessions, flags each string as an entrapment identification under the "pure" rule (every accession belongs to the entrapment proteome; the conservative rule used in the diagFDR paper) or the "any" rule (at least one does).

Usage

dfdr_is_entrapment_group(
  groups,
  accessions,
  rule = c("pure", "any"),
  sep = ";"
)

Arguments

Details

DIA-NN writes bare UniProt accessions with no species tag, so matching must be done against the accession set and not a string prefix such as "ARATH"; see read_fasta_accessions.

Value

Logical vector.

Examples

dfdr_is_entrapment_group(c("A1;A2", "A1;P1", "P1"), accessions = c("A1", "A2"))

Description

Collapses the same export under each of the four rules of collapse_universe and reports, at the threshold alpha, the accepted target and decoy counts, the recomputed decoy ratio, the decoy-support index and the FDP-CV benchmark. The spread across rules is the unstated degree of freedom the diagFDR paper asks authors to report (main-text Table 3, Panel B).

Usage

dfdr_label_rule_audit(
  rep,
  key_col,
  q_col,
  alpha = 0.01,
  rules = c("split", "winning_row", "any_decoy", "majority"),
  decoy_col = "Decoy",
  pep_col = "PEP",
  q_max_export = NA_real_,
  two_pass = NA
)

Arguments

Value

A data.frame with one row per rule and columns rule, n_units, T_alpha, D_alpha, decoy_ratio, support_index, CV_benchmark, n_mixed.

Examples

rep <- data.frame(
  Protein.Group = rep(paste0("P", 1:200), each = 3),
  Decoy = rbinom(600, 1, 0.1),
  Global.PG.Q.Value = runif(600, 0, 0.05))
dfdr_label_rule_audit(rep, "Protein.Group", "Global.PG.Q.Value", alpha = 0.01)

Description

Counts the number of observations (and decoys) in a right-neighborhood of each threshold $\alpha$, defined as $(\alpha,\, \alpha + \rho\alpha]$ where $\rho$ is win_rel. This approximates how well supported the decision boundary is by decoys in the immediate tail.

Usage

dfdr_local_tail(
  x,
  alphas,
  win_rel = 0.2,
  truncation = c("warn_drop", "drop", "cap")
)

Arguments

Value

A tibble with one row per alpha. Columns include:

alpha

The threshold.

delta

The effective window width used ($w\alpha$, with $w$ = win_rel, or capped).

n_win

Number of entries with q in the window.

D_alpha_win

Number of decoys in the window.

decoy_frac_win

Decoy fraction in the window (D_alpha_win/n_win).

upper_used

Upper endpoint actually used for the window.

truncated

Logical indicating whether the requested window was truncated (or dropped) due to export limits.

This table is used to assess boundary support: very small n_win or D_alpha_win indicates an unstable/poorly-supported cutoff.

Examples

library(tibble)

set.seed(1)
n <- 5000
df <- tibble(
  id = as.character(seq_len(n)),
  run = "run1",
  is_decoy = sample(c(FALSE, TRUE), n, replace = TRUE, prob = c(0.95, 0.05)),
  score = rnorm(n),
  pep = NA_real_
)
df$q <- diagFDR:::tdc_qvalues(df$score, df$is_decoy, add_decoy = 1L)
x <- as_dfdr_tbl(df, unit = "psm", scope = "global", q_source = "toy_tdc")

dfdr_local_tail(x, alphas = c(1e-3, 5e-3, 1e-2), win_rel = 0.2, truncation = "cap")

Description

Computes the empirical CDF $\hat F(u) = P(p \le u)$ on a grid of u values and summarises departures from uniformity in a decision-relevant region $u \le u_{\max}$. Intended as a plausibility diagnostic for (pseudo-)p-values (e.g. under the null, $\hat F(u) \approx u$).

Usage

dfdr_p_calibration(
  x,
  u_grid = c(seq(0.001, 0.1, by = 0.001), seq(0.11, 1, by = 0.01)),
  u_max = 0.1,
  stratify = NULL,
  min_n = 200
)

Arguments

Value

A list with components:

ecdf

A tibble with columns stratum, u, Fhat, and n. There is one row per u value per stratum.

summary

A tibble with one row per stratum, including n (number of finite p-values), max_inflation (maximum of Fhat(u)-u for u <= u_max), and auc_inflation (area under the positive part of Fhat(u)-u on $[0,u_{\max}]$, normalised by u_max). Strata with n < min_n are reported with NA metrics and a note.

Examples

library(tibble)

set.seed(1)
n <- 5000
df <- tibble(
  id = as.character(seq_len(n)),
  run = sample(c("run1", "run2"), n, replace = TRUE),
  # mostly uniform p-values + a small enriched component
  p = c(stats::runif(4500), stats::rbeta(500, 0.3, 1))
)

out <- dfdr_p_calibration(df, stratify = "run", u_max = 0.1, min_n = 200)
head(out$ecdf)
out$summary

Description

Turns dfdr_p_summary into a few short statements for the report: the $\pi_0$ estimates (where the estimators converge, and which differ), the p-value (and score or PEP) threshold giving an estimated FDR of alpha on targets, compared with target–decoy counting, the pooled targets + decoys check, and the caveats that apply. Cases handled: too few p-values; decoy-calibrated pseudo-p-values (decoy $\pi_0 \approx 1$ by construction, so not a check) versus supplied p-values (decoy $\pi_0$ is then a real check); estimators that do not converge; no entry reaching the FDR level; a threshold at the resolution limit of the pseudo-p-values; two-pass exports.

Usage

dfdr_p_interpretation(ps, T_alpha = NULL)

Arguments

Value

A character vector of statements (plain ASCII; the report renders pi0, alpha, <= and >= as symbols).

Description

Summarises what the p-value diagnostics of dfdr_run_all say about a list: the proportion of true nulls $\pi_0$ (incorrect identifications) estimated on targets and decoys together, on targets and on decoys, and the p-value threshold that gives an estimated FDR of alpha, with the corresponding score (or PEP) threshold when the p-values were derived from a score (or from $-$PEP).

Usage

dfdr_p_summary(
  x,
  alpha = 0.01,
  nbins = 20,
  pz = 0.05,
  pi0_method_fdr = "consensus",
  min_n = 2000,
  tol = 0.05
)

Arguments

Details

$\pi_0$ is estimated with the eight estimators of cp4p::estim.pi0() (Storey with spline or bootstrap, Jiang, histogram, Langaas, Pounds, ABH, SLIM); if cp4p fails, Storey's estimator at $\lambda = 0.5$ is used. The estimates are then grouped: the estimators within tol of the median of all estimates converge, and their median is the consensus value; the others are listed separately. With fewer than three converging estimators there is no consensus.

The FDR threshold is the largest $t$ such that $\hat\pi_0 m t / \#\{p \le t\} \le \alpha$ (the estimator of the "Estimated FDR" plots), computed with the consensus $\hat\pi_0$ (or the estimator named in pi0_method_fdr) and with $\pi_0 = 1$ (Benjamini–Hochberg, the conservative choice).

Value

A list with pi0 (one row per subset and estimator), summary (one row per subset: count, the eight estimates, the consensus value, how many estimators converge and which, the others, and the $\pi_0$ used for the threshold), thresholds (one row per subset and $\pi_0$ choice: p-value threshold, number of accepted entries, targets and decoys, score or PEP threshold) and info (kind of p-values and their resolution).

See Also

dfdr_p_interpretation

Examples

set.seed(1)
n <- 1500
dec <- rep(c(TRUE, FALSE), c(500, 1000))
sc <- c(rnorm(500), rnorm(500), rnorm(500, 4))
df <- data.frame(id = paste0("u", seq_len(n)), is_decoy = dec, q = 1,
                 pep = NA_real_, run = "r", score = sc)
df$p <- score_to_pvalue(sc, method = "decoy_ecdf", is_decoy = dec)
x <- as_dfdr_tbl(df, unit = "psm", scope = "global", q_source = "toy")
attr(x, "meta")$p_source <- "score_to_pvalue(score, method='decoy_ecdf')"
if (requireNamespace("cp4p", quietly = TRUE)) {
  s <- dfdr_p_summary(x, alpha = 0.01, min_n = 400)
  s$summary
  s$thresholds
}

Description

Summarises how many decoys receive surprisingly small PEP values. Under a well-calibrated PEP, decoys should typically have high error probabilities; large fractions of decoys below small PEP thresholds can indicate issues with PEP calibration or labeling.

Usage

dfdr_pep_decoy_sanity(x, thresholds = c(0.01, 0.05, 0.1, 0.2))

Arguments

Value

A tibble with one row per threshold. Columns include:

threshold

The PEP cutoff used for counting.

n_decoy

Number of decoys with finite PEP in $(0,1]$.

n_target

Number of targets with finite PEP in $(0,1]$.

decoy_le

Count of decoys with pep <= threshold.

target_le

Count of targets with pep <= threshold.

frac_decoy_le

decoy_le / n_decoy.

frac_target_le

target_le / n_target.

Examples

library(tibble)

set.seed(1)
n <- 5000
df <- tibble(
  id = as.character(seq_len(n)),
  run = "run1",
  is_decoy = sample(c(FALSE, TRUE), n, replace = TRUE, prob = c(0.95, 0.05)),
  score = rnorm(n),
  q = pmin(1, rank(-score) / n),
  pep = stats::runif(n)
)
x <- as_dfdr_tbl(df, unit = "psm", scope = "global", q_source = "toy")

dfdr_pep_decoy_sanity(x, thresholds = c(0.01, 0.05, 0.1))

Description

Plain-language interpretation of PEP concordance

Usage

dfdr_pep_interpretation(ps)

Arguments

Value

A character vector of sentences.

Description

Bins identifications (targets and decoys together) by predicted PEP and compares the mean predicted PEP with the observed decoy fraction $D_b/(T_b+D_b)$ within each bin. This pooled comparator is kept as a secondary summary; the internal PEP calibration error (IPE) reported in the headline table is computed by dfdr_ipe with the target-decoy comparator $D_b/T_b$.

Usage

dfdr_pep_reliability(x, binwidth = 0.05, n_min = 200, pep_max = 0.5)

Arguments

Value

A list with components:

bins

A tibble with one row per PEP bin and columns pep_mean (mean predicted PEP), decoy_rate (observed decoy fraction), and n (bin size).

IPE

Numeric scalar. Pooled-comparator calibration error: weighted mean absolute deviation between pep_mean and decoy_rate across eligible bins (n >= n_min and pep_mean <= pep_max). NA if no eligible bins exist. See dfdr_ipe for the IPE used in the headline table.

params

A list of parameters used (binwidth, n_min, pep_max).

Examples

library(tibble)

set.seed(1)
n <- 5000
df <- tibble(
  id = as.character(seq_len(n)),
  run = "run1",
  is_decoy = sample(c(FALSE, TRUE), n, replace = TRUE, prob = c(0.95, 0.05)),
  score = rnorm(n),
  q = pmin(1, rank(-score) / n),         # simple monotone q-like values
  pep = pmin(1, pmax(0, stats::runif(n))) # toy PEP in [0,1]
)
x <- as_dfdr_tbl(df, unit = "psm", scope = "global", q_source = "toy")

out <- dfdr_pep_reliability(x, binwidth = 0.1, n_min = 50, pep_max = 0.5)
out$IPE
head(out$bins)

Description

Bins identifications by predicted PEP and estimates an error proxy for targets within each bin using decoys as a proxy via a target-decoy-competition (TDC) style ratio $(D + add\_decoy) / T$.

Usage

dfdr_pep_reliability_tdc(x, breaks = seq(0, 0.5, by = 0.05), add_decoy = 0L)

Arguments

Value

A tibble with one row per PEP bin, including:

bin

Formatted bin label.

n_target

Number of targets in the bin.

n_decoy

Number of decoys in the bin.

pep_mean_targets

Mean PEP among targets in the bin.

pep_mean_all

Mean PEP among all entries in the bin.

err_hat_target

Estimated target error proxy $(D + add\_decoy)/T$, capped at 1.

pep_bin_mid

Midpoint of the PEP bin (useful for plotting).

Examples

library(tibble)

set.seed(1)
n <- 8000
df <- tibble(
  id = as.character(seq_len(n)),
  run = "run1",
  is_decoy = sample(c(FALSE, TRUE), n, replace = TRUE, prob = c(0.9, 0.1)),
  score = rnorm(n),
  q = stats::runif(n),
  pep = stats::runif(n)
)
x <- as_dfdr_tbl(df, unit = "psm", scope = "global", q_source = "toy")

dfdr_pep_reliability_tdc(x, breaks = seq(0, 0.5, by = 0.1), add_decoy = 1L)

Description

Compares, in PEP bins with mean target PEP $\le$ pep_max and at least n_min entries, the mean PEP of targets with the decoy-derived reference $\hat e_b = D_b/T_b$ (paper Eq. 1), and the sum of PEPs of the targets accepted at alpha with the number of accepted decoys $D_\alpha$, the target–decoy estimate of the number of false targets.

Usage

dfdr_pep_summary(
  x,
  alpha = 0.01,
  binwidth = 0.05,
  pep_max = 0.5,
  n_min = 200,
  tol = 0.01
)

Arguments

Value

A list with IPE, bins_used, ratio (mean target PEP over mean reference), signed (weighted mean of mean target PEP minus reference), share_under (weight of bins where PEP is below the reference), mean_pep, mean_ref, sum_pep, D_alpha, T_alpha and verdict ("agree", "under", "over", "mixed", "no_bins").

See Also

dfdr_pep_interpretation

Description

Estimates $\pi_0(\lambda) = \#\{p>\lambda\} / ((1-\lambda)m)$ over a grid of lambdas. This is a plausibility diagnostic for (pseudo-)p-values: under a well-calibrated null, the upper tail should be approximately uniform, leading to stable $\pi_0(\lambda)$ curves.

Usage

dfdr_pi0_storey(
  x,
  lambdas = seq(0.5, 0.95, by = 0.05),
  stratify = NULL,
  min_n = 2000,
  clamp = TRUE
)

Arguments

Value

A list with components:

pi0

A tibble with one row per lambda per stratum and columns stratum, lambda, pi0_hat, and n (the number of finite p-values in the stratum).

summary

A tibble with one row per stratum, including n and summary statistics of pi0_hat across lambdas (median_pi0, sd_pi0, iqr_pi0). Strata with n < min_n are reported with NA metrics and a note.

Examples

library(tibble)

set.seed(1)
n <- 6000
df <- tibble(
  run = sample(c("run1", "run2"), n, replace = TRUE),
  # mostly uniform p-values + a small enriched component
  p = c(stats::runif(5400), stats::rbeta(600, 0.3, 1))
)

out <- dfdr_pi0_storey(df, stratify = "run", lambdas = seq(0.5, 0.9, by = 0.1), min_n = 500)
head(out$pi0)
out$summary

Description

A procedural comparator for the label-propagation rules of collapse_universe. Instead of inheriting a label, the target and decoy versions of the same identifier compete directly: the better of the pair (smaller q-value, or larger score) is kept and the other discarded, and q-values are recomputed by target–decoy counting over the retained entries. Because every retained entry comes from a matched pair, the null is explicit and no label has to be propagated.

Usage

dfdr_picked_protein(x, alpha = 0.01, by = c("q", "score"), add_decoy = 0L)

Arguments

Details

The competition should be run on the full (unfiltered) universe: the decoy tail needed to recompute q-values is absent from an export filtered at 1%.

Value

A list with tbl (a dfdr_tbl of the picked entries with the recomputed q-value in q, the input evidence in q_in), T_alpha, D_alpha, decoy_ratio, support_index, CV_benchmark, n_pairs (identifiers carrying both labels), n_ids, and accepted_targets.

References

Savitski MM et al. (2015) A scalable approach for protein false discovery rate estimation in large proteomic data sets. Mol Cell Proteomics 14:2394–2404.

Examples

df <- data.frame(id = c("P1", "P1", "P2", "P3", "P3"),
                 is_decoy = c(FALSE, TRUE, FALSE, TRUE, FALSE),
                 q = c(0.001, 0.2, 0.002, 0.004, 0.05))
dfdr_picked_protein(df, alpha = 0.01)

Description

Convenience plotting function for the output of dfdr_bh_elasticity. The x-axis is log10(alpha) and the y-axis is the Jaccard overlap between BH discovery sets at alpha and (1+eps)*alpha.

Usage

dfdr_plot_bh_elasticity(
  el_tbl,
  xlab = "alpha (log10)",
  title = "BH elasticity: Jaccard(alpha, (1+eps)alpha)"
)

Arguments

Value

A ggplot object.

Examples

library(tibble)

set.seed(1)
n <- 2000
x <- tibble(
  id = as.character(seq_len(n)),
  p = c(stats::runif(1800), stats::rbeta(200, 0.3, 1))
)

el <- dfdr_bh_elasticity(x, alphas = c(1e-3, 5e-3, 1e-2, 2e-2), eps = 0.2)
p <- dfdr_plot_bh_elasticity(el)
p

Description

Plots the decoy-support index $D_\alpha^{-1/2}$ (column support_index) against the threshold alpha for one or more lists.

Usage

dfdr_plot_cv(
  stab_tbl,
  xlab = "alpha (log10)",
  title = "Decoy-support index D_alpha^(-1/2) vs alpha"
)

Arguments

Value

A ggplot object.

Examples

library(tibble)

stab_tbl <- tibble(
  list = rep(c("A", "B"), each = 4),
  alpha = rep(c(1e-3, 2e-3, 5e-3, 1e-2), times = 2),
  support_index = c(0.30, 0.22, 0.15, 0.12, 0.40, 0.28, 0.20, 0.18)
)
dfdr_plot_cv(stab_tbl)

Description

Plots the number of accepted decoys at each threshold alpha. This is a key stability indicator: very small $D_\alpha$ implies granular/unstable behaviour of target-decoy based estimates.

Usage

dfdr_plot_dalpha(
  stab_tbl,
  xlab = "alpha (log10)",
  title = "Decoy support D_alpha vs alpha"
)

Arguments

Value

A ggplot object.

Examples

library(tibble)

stab_tbl <- tibble(
  list = rep(c("A", "B"), each = 4),
  alpha = rep(c(1e-3, 2e-3, 5e-3, 1e-2), times = 2),
  D_alpha = c(5, 8, 20, 40, 2, 3, 6, 10)
)
dfdr_plot_dalpha(stab_tbl)

Description

Plots the number of decoys in a right-neighborhood above each threshold (as computed by dfdr_local_tail). This approximates how well supported the boundary is by nearby decoys.

Usage

dfdr_plot_dwin(
  dwin_tbl,
  xlab = "alpha (log10)",
  title = "Local decoy support D_alpha_win vs alpha"
)

Arguments

Value

A ggplot object.

Examples

library(tibble)

dwin_tbl <- tibble(
  list = rep(c("A", "B"), each = 4),
  alpha = rep(c(1e-3, 2e-3, 5e-3, 1e-2), times = 2),
  D_alpha_win = c(1, 2, 6, 15, 0, 1, 2, 4)
)
dfdr_plot_dwin(dwin_tbl)

Description

Plots Jaccard overlap values (as returned by dfdr_elasticity) against alpha. Lower overlap indicates greater sensitivity of the accepted set to small changes of the threshold.

Usage

dfdr_plot_elasticity(
  el_tbl,
  xlab = "alpha (log10)",
  title = "Threshold elasticity (Jaccard) vs alpha"
)

Arguments

Value

A ggplot object.

Examples

library(tibble)

el_tbl <- tibble(
  list = rep(c("A", "B"), each = 4),
  alpha = rep(c(1e-3, 2e-3, 5e-3, 1e-2), times = 2),
  jaccard = c(0.95, 0.93, 0.90, 0.88, 0.92, 0.90, 0.86, 0.82)
)
dfdr_plot_elasticity(el_tbl)

Description

Visualises decoy fractions by q-value band (as produced by dfdr_equal_chance_qbands). A horizontal reference at 0.5 indicates the expected decoy fraction under an "equal-chance" region assumption.

Usage

dfdr_plot_equal_chance(
  bands_tbl,
  title = "Equal chance under paired competition: decoy fraction by q-band"
)

Arguments

Value

A ggplot object.

Examples

library(tibble)

bands_tbl <- tibble(
  q_mean = c(0.05, 0.15, 0.30, 0.45),
  decoy_frac = c(0.10, 0.20, 0.45, 0.52),
  n = c(2000, 1500, 800, 400)
)
dfdr_plot_equal_chance(bands_tbl)

Description

Given p-values (or pseudo-p-values), estimates $\pi_0$ using cp4p::estim.pi0() and plots

$\widehat{\mathrm{FDR}}(t) = \hat\pi_0 \, m \, t / R(t),$

where $R(t) = \#\{p \le t\}$ and $m$ is the number of finite p-values.

Usage

dfdr_plot_fdrhat_pi0(
  x,
  sel = c("all", "target", "decoy"),
  pi0.method = "pounds",
  nbins = 20,
  pz = 0.05,
  t_grid = 10^seq(-6, 0, length.out = 400),
  r_min = 1,
  cap_one = TRUE
)

Arguments

Value

A list with components:

plot

A ggplot object.

data

A tibble with columns t, R, and fdr_hat.

pi0_hat

Numeric scalar $\hat\pi_0$.

m

Integer. Number of finite p-values used.

Examples

library(tibble)

if (requireNamespace("cp4p", quietly = TRUE)) {
  set.seed(1)
  n <- 4000
  df <- tibble(
    id = as.character(seq_len(n)),
    is_decoy = sample(c(FALSE, TRUE), n, replace = TRUE, prob = c(0.95, 0.05)),
    p = c(stats::runif(3600), stats::rbeta(400, 0.3, 1))
  )
  out <- dfdr_plot_fdrhat_pi0(df, sel = "all", pi0.method = "pounds", nbins = 10)
  out$pi0_hat
  out$plot
}

Description

Plots $\hat F(u) - u$ against $u$ using the ecdf component returned by dfdr_p_calibration. Values above zero indicate potential inflation (excess of small p-values) relative to uniform.

Usage

dfdr_plot_p_calibration(ecdf_tbl, title = "P-value calibration: ECDF(p) - u")

Arguments

Value

A ggplot object.

Examples

library(tibble)

set.seed(1)
n <- 2000
df <- tibble(
  id = as.character(seq_len(n)),
  run = sample(c("run1", "run2"), n, replace = TRUE),
  p = c(stats::runif(1800), stats::rbeta(200, 0.3, 1))
)
cal <- dfdr_p_calibration(df, stratify = "run", min_n = 100)
p <- dfdr_plot_p_calibration(cal$ecdf)
p

Description

Plots the ECDF of $1-p$ and overlays reference curves derived from cp4p::estim.pi0() using multiple $\pi_0$ estimation methods. This provides a visual plausibility check for p-value calibration.

Usage

dfdr_plot_p_calibration2(
  x,
  sel = c("all", "decoy", "target"),
  nbins = 20,
  pz = 0.05,
  step = 0.001,
  return_data = FALSE
)

Arguments

Value

If return_data = FALSE (default), returns a ggplot object.

If return_data = TRUE, returns a list with components:

plot

A ggplot object.

pi0

Named numeric vector of $\pi_0$ estimates (one per method).

data

A list with main (ECDF data) and ref (reference curve data).

Examples

library(tibble)

set.seed(1)
n <- 2000
df <- tibble(
  id = as.character(seq_len(n)),
  is_decoy = sample(c(FALSE, TRUE), n, replace = TRUE, prob = c(0.9, 0.1)),
  p = c(stats::runif(1800), stats::rbeta(200, 0.3, 1))
)

if (requireNamespace("cp4p", quietly = TRUE)) {
  g <- dfdr_plot_p_calibration2(df, sel = "all", return_data = FALSE)
  g
}

Description

Plots density curves of (pseudo-)p-values for targets vs decoys. Optionally plots $-\log_{10}(p)$ to emphasise small p-values.

Usage

dfdr_plot_p_density_by_decoy(
  x,
  p_max = 1,
  bw = "nrd0",
  adjust = 1,
  title = "(Pseudo-)p-value distribution (density): targets vs decoys",
  log10_x = FALSE,
  eps = 1e-300
)

Arguments

Value

A ggplot object.

Examples

library(tibble)

set.seed(1)
n <- 4000
df <- tibble(
  id = as.character(seq_len(n)),
  run = "run1",
  is_decoy = sample(c(FALSE, TRUE), n, replace = TRUE, prob = c(0.95, 0.05)),
  score = rnorm(n),
  q = stats::runif(n, 0, 0.05),
  pep = NA_real_,
  p = stats::runif(n)
)
x <- as_dfdr_tbl(df, unit = "psm", scope = "global", q_source = "toy", p_source = "toy")
dfdr_plot_p_density_by_decoy(x, log10_x = TRUE)

Description

Plots density curves of PEP values for targets vs decoys, truncated to pep <= pep_max.

Usage

dfdr_plot_pep_density_by_decoy(
  x,
  pep_max = 0.5,
  bw = "nrd0",
  adjust = 1,
  title = "PEP distribution (density): targets vs decoys"
)

Arguments

Value

A ggplot object.

Examples

library(tibble)

set.seed(1)
n <- 4000
df <- tibble(
  id = as.character(seq_len(n)),
  run = "run1",
  is_decoy = sample(c(FALSE, TRUE), n, replace = TRUE, prob = c(0.95, 0.05)),
  score = rnorm(n),
  q = stats::runif(n, 0, 0.05),
  pep = stats::runif(n)
)
x <- as_dfdr_tbl(df, unit = "psm", scope = "global", q_source = "toy")
dfdr_plot_pep_density_by_decoy(x, pep_max = 0.5)

Description

Visualises PEP reliability by plotting the observed decoy fraction against the mean predicted PEP in each bin (from dfdr_pep_reliability). Point size reflects bin counts.

Usage

dfdr_plot_pep_reliability(bins_tbl, title = "PEP reliability")

Arguments

Value

A ggplot object.

Examples

library(tibble)

bins_tbl <- tibble(
  pep_mean = c(0.05, 0.15, 0.25, 0.35),
  decoy_rate = c(0.06, 0.14, 0.30, 0.40),
  n = c(500, 400, 250, 120)
)
dfdr_plot_pep_reliability(bins_tbl)

Description

Visualises the output of dfdr_pep_reliability_tdc by plotting the estimated target error proxy err_hat_target against the mean predicted target PEP per bin. Point size reflects the number of targets per bin.

Usage

dfdr_plot_pep_reliability_tdc(
  rel_tbl,
  title = "PEP reliability (targets; TDC-style D/T error proxy)"
)

Arguments

Value

A ggplot object.

Examples

library(tibble)

rel_tbl <- tibble(
  bin = c("(0,0.1]", "(0.1,0.2]", "(0.2,0.3]"),
  n_target = c(800, 500, 200),
  n_decoy = c(20, 30, 40),
  pep_mean_targets = c(0.05, 0.15, 0.25),
  pep_mean_all = c(0.06, 0.17, 0.28),
  err_hat_target = c(0.03, 0.06, 0.20),
  pep_bin_mid = c(0.05, 0.15, 0.25)
)
dfdr_plot_pep_reliability_tdc(rel_tbl)

Description

Plots $\pi_0(\lambda)$ estimates returned by dfdr_pi0_storey. Values closer to 1 suggest many nulls (few true effects), while values far below 1 (especially if unstable across lambda) may indicate deviations from tail-uniformity.

Usage

dfdr_plot_pi0(pi0_tbl, title = "Storey pi0(lambda) diagnostic")

Arguments

Value

A ggplot object.

Examples

library(tibble)

set.seed(1)
df <- tibble(
  stratum = rep("all", 5),
  lambda = seq(0.5, 0.9, by = 0.1),
  pi0_hat = c(0.95, 0.96, 0.97, 0.98, 0.99),
  n = 1000
)
p <- dfdr_plot_pi0(df)
p

Description

Computes accepted target ID sets for each list at a fixed alpha and visualises pairwise Jaccard overlaps as a heatmap. IDs are compared at the "base" level by stripping any "run||" prefix.

Usage

dfdr_plot_scope_disagreement_matrix(xs, alpha = 0.01)

Arguments

Value

A ggplot object (heatmap).

Examples

library(tibble)

set.seed(1)
n <- 2000

make_x <- function(label) {
  df <- tibble(
    id = paste0("run1||", as.character(seq_len(n))),
    run = "run1",
    is_decoy = sample(c(FALSE, TRUE), n, replace = TRUE, prob = c(0.95, 0.05)),
    score = rnorm(n),
    q = stats::runif(n, 0, 0.05),
    pep = NA_real_
  )
  as_dfdr_tbl(df, unit = "psm", scope = label, q_source = "toy")
}

xs <- list(A = make_x("A"), B = make_x("B"), C = make_x("C"))
dfdr_plot_scope_disagreement_matrix(xs, alpha = 0.01)

Description

Plots density distributions of scores (if available) or q-values (fallback) for targets vs decoys. This provides a quick sanity check that decoys are shifted toward lower scores (or higher q-values).

Usage

dfdr_plot_score_distributions(x, title = "Target vs Decoy Score Distributions")

Arguments

Value

A ggplot object.

Examples

library(tibble)

set.seed(1)
n <- 4000
df <- tibble(
  id = as.character(seq_len(n)),
  run = "run1",
  is_decoy = sample(c(FALSE, TRUE), n, replace = TRUE, prob = c(0.95, 0.05)),
  score = rnorm(n),
  q = pmin(1, rank(-score) / n),
  pep = NA_real_
)
x <- as_dfdr_tbl(df, unit = "psm", scope = "global", q_source = "toy")
dfdr_plot_score_distributions(x)

Description

Realised FDP of a simulated list

Usage

dfdr_realised_fdp(sim, alpha = 0.01)

Arguments

Value

A data.frame with alpha, T_alpha, D_alpha, V_alpha (accepted incorrect targets), decoy_ratio and the realised FDP.

Examples

sim <- dfdr_simulate_tdc(n = 20000, seed = 3)
dfdr_realised_fdp(sim, alpha = 0.01)

Description

Renders an HTML report that summarises key diagnostics and embeds plots contained in diag$plots. The report is intended for interactive review and auditable reporting.

Usage

dfdr_render_report(
  diag,
  out_dir,
  filename = "diagFDR_report.html",
  self_contained = FALSE,
  open = FALSE
)

Arguments

Details

This function requires the rmarkdown package (suggested dependency) and uses the built-in R Markdown template shipped with the package (inst/templates/dfdr_report.Rmd).

Value

The path to the rendered HTML file, returned invisibly. The function is called for its side effect of creating an HTML report on disk.

Examples

# A minimal example that renders a report from a toy dataset.
# This example is conditional because rmarkdown is in Suggests.
if (requireNamespace("rmarkdown", quietly = TRUE)) {
  library(tibble)
  tmpdir <- tempdir()

  set.seed(1)
  n <- 3000
  df <- tibble(
    id = as.character(seq_len(n)),
    run = "run1",
    is_decoy = sample(c(FALSE, TRUE), n, replace = TRUE, prob = c(0.95, 0.05)),
    score = rnorm(n),
    q = pmin(1, rank(-score) / n),
    pep = NA_real_
  )
  x <- as_dfdr_tbl(df, unit = "psm", scope = "global", q_source = "toy")

  diag <- dfdr_run_all(
    xs = list(toy = x),
    alpha_main = 0.01,
    compute_pseudo_pvalues = FALSE
  )

  # Render to a temporary directory (does not open a browser during checks)
  dfdr_render_report(diag, out_dir = tmpdir, open = FALSE)
}

Description

Runs stability, boundary-support, and plausibility diagnostics on a named list of dfdr_tbl objects and returns both summary tables and plots.

Usage

dfdr_run_all(
  xs,
  alpha_main = 0.01,
  alphas = c(1e-04, 5e-04, 0.001, 0.002, 0.005, 0.01, 0.02, 0.05, 0.1, 0.2),
  eps = 0.2,
  win_rel = 0.2,
  truncation = "warn_drop",
  k_fixed = 10,
  k_sqrt_mult = 2,
  qband_breaks = c(0, 0.01, 0.02, 0.05, 0.1, 0.2, 0.5),
  low_conf = c(0.2, 0.5),
  min_N_equalchance = 2000,
  pep_binwidth = 0.05,
  pep_n_min = 200,
  pep_max = 0.5,
  pep_sanity_thresholds = c(0.01, 0.05, 0.1, 0.2),
  pep_density_max = 0.5,
  pep_rel_tdc_breaks = seq(0, 0.5, by = 0.05),
  pep_rel_tdc_add_decoy = 0L,
  compute_pseudo_pvalues = TRUE,
  pseudo_pvalue_method = "decoy_ecdf",
  pseudo_pvalue_score = c("score", "pep"),
  p_u_grid = c(seq(0.001, 0.1, by = 0.001), seq(0.11, 1, by = 0.01)),
  p_u_max = 0.1,
  p_stratify = NULL,
  p_min_n_calib = 200,
  p_lambdas = seq(0.5, 0.95, by = 0.05),
  p_min_n_pi0 = 2000,
  bh_boundary = c("mult", "add"),
  bh_win = 0.2,
  bh_delta = NULL
)

Arguments