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()
)

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, 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

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

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

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).

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.

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

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 ($\rho\alpha$ 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

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

Bins identifications by predicted PEP and compares mean predicted PEP to the observed decoy fraction within each bin (internal target-decoy consistency check).

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. The internal PEP calibration error (IPE), computed as a 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.

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

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

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 a stability proxy (CV_hat) against the threshold alpha for one or more lists.

Usage

dfdr_plot_cv(
  stab_tbl,
  xlab = "alpha (log10)",
  title = "Stability proxy CV_hat 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),
  CV_hat = 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 plausibility: 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

Renders an HTML report that summarises key diagnostics and embeds plots contained in diag$plots. The report is intended for interactive review and verifiable 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",
  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

Details

Diagnostics include (depending on available columns):

• Target/decoy headline diagnostics at alpha_main (counts, FDR estimate, stability proxies)

• Stability curves across alphas

• Local tail decoy support near each alpha

• Elasticity (Jaccard overlap under threshold perturbation)

• PEP reliability / IPE and PEP sanity summaries (if pep is present)

• Equal-chance by q-bands (always attempted; may be not applicable if q-range is truncated)

• (Pseudo-)p-value calibration and Storey $\pi_0(\lambda)$ (if p is present or computed)

• BH diagnostics (if p is present)

Value

A list with components:

tables

A named list of result tables (tibbles) for the computed diagnostics (e.g. headline, stability, local_tail, elasticity, and optional PEP/p-value/BH-related tables).

plots

A named list of ggplot objects produced from the diagnostics.

objects

The input xs, possibly augmented with computed pseudo-p-values if compute_pseudo_pvalues=TRUE.

params

A list of parameter values used to compute the diagnostics.

Examples

library(tibble)

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

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

names(diag$tables)
names(diag$plots)
diag$tables$headline

Description

Computes pairwise Jaccard similarity between runs based on accepted target IDs at a fixed threshold alpha. This can reveal run-to-run disagreement or heterogeneity in identifications.

Usage

dfdr_run_jaccard(x, alpha = 0.01)

Arguments

Value

A tibble with one row per run pair and columns:

run1

Name/identifier of the first run.

run2

Name/identifier of the second run.

jaccard

Jaccard similarity between accepted target ID sets.

Examples

library(tibble)

set.seed(1)
n <- 8000
df <- tibble(
  id = as.character(seq_len(n)),
  run = sample(c("runA", "runB", "runC"), n, replace = TRUE),
  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_run_jaccard(x, alpha = 0.01)

Description

Computes the Jaccard overlap of accepted target IDs between two dfdr_tbl objects across a set of thresholds. This is useful for comparing results obtained under different FDR scopes (e.g. run-wise vs global) or from different pipelines, provided that both inputs use compatible id semantics.

Usage

dfdr_scope_disagreement(
  x1,
  x2,
  alphas,
  label1 = "A",
  label2 = "B",
  normalize_ids = TRUE
)

Arguments

Value

A tibble with one row per alpha and columns:

alpha

The threshold.

label1,label2

The labels identifying the two inputs.

n1,n2

Numbers of accepted target IDs in x1 and x2 at alpha.

jaccard

Jaccard similarity between the two accepted target ID sets.

Examples

library(tibble)

set.seed(1)
n <- 4000

# Two "lists" with slightly different q-values for the same base IDs
base_ids <- as.character(seq_len(n))

df1 <- tibble(
  id = paste0("run1||", base_ids),
  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_
)

df2 <- tibble(
  id = base_ids,              # no run prefix here
  run = "all",
  is_decoy = df1$is_decoy,    # same decoy labels for simplicity
  score = df1$score + rnorm(n, sd = 0.2),
  q = pmin(1, df1$q * 1.2),   # slightly perturbed q-values
  pep = NA_real_
)

x1 <- as_dfdr_tbl(df1, unit = "psm", scope = "runwise", q_source = "toy")
x2 <- as_dfdr_tbl(df2, unit = "psm", scope = "global",  q_source = "toy")

dfdr_scope_disagreement(x1, x2, alphas = c(0.005, 0.01, 0.02), normalize_ids = TRUE)

Description

Convenience helper to assemble a compact, export-ready summary table from the output of dfdr_run_all. The function merges headline metrics with selected columns from other diagnostics (e.g. local tail support, equal-chance pooled estimate, and PEP reliability headline if available).

Usage

dfdr_summary_headline(diag)

Arguments

Value

A tibble with one row per element of the input list used in dfdr_run_all (i.e. one row per list label). The table is suitable for exporting to a CSV (e.g. summary_headline.csv).

The output typically contains (when available) headline target/decoy counts at alpha_main, local boundary-support columns (e.g. D_alpha_win, n_win), equal-chance pooled columns (e.g. pi_D_hat, effect_abs), and PEP reliability headline quantities (e.g. IPE). If diag$tables$headline is missing or empty, an empty tibble is returned.

Examples

library(tibble)

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

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

dfdr_summary_headline(diag)

Description

Computes $\sum_{i \in A(\alpha)} \mathrm{PEP}_i$ among accepted targets for each threshold $\alpha$, where acceptance is defined by q <= alpha.

Usage

dfdr_sumpep(x, alphas)

Arguments

Value

A tibble with one row per alpha. Columns include:

alpha

The threshold.

n_targets

Number of accepted targets (!is_decoy and q <= alpha).

sum_PEP

Sum of PEP values among accepted targets (expected false targets).

mean_PEP

Mean PEP among accepted targets.

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_sumpep(x, alphas = c(0.001, 0.01, 0.05))

Description

Writes a manifest alongside exported outputs to record key run parameters and per-list metadata (unit, scope, q-source, export ceiling, etc.). This helps tie diagnostic outputs to the exact inputs and settings used.

Usage

dfdr_write_manifest(diag, out_dir, filename = "manifest")

Arguments

Details

If jsonlite is available (suggested dependency), the manifest is written as JSON (*.json); otherwise a human-readable plain text file (*.txt) is written.

Value

The path to the manifest file, returned invisibly. The function is called for its side effect of writing a file to disk.

Examples

library(tibble)

# Create a minimal dfdr_run_all-like object to demonstrate manifest writing
df <- tibble(
  id = c("1","2","3"),
  run = "run1",
  is_decoy = c(FALSE, TRUE, FALSE),
  score = c(10, 9, 8),
  q = c(0.01, 0.02, 0.03),
  pep = NA_real_
)
x <- as_dfdr_tbl(df, unit = "psm", scope = "global", q_source = "toy")

diag <- list(
  objects = list(toy = x),
  params = list(alpha_main = 0.01),
  warnings = character()
)

out_dir <- tempdir()
dfdr_write_manifest(diag, out_dir = out_dir, filename = "manifest_example")

Description

Produces a lightweight narrative report in Markdown that summarises the most important diagnostics (headline summary, key plots, exported tables) and records per-list metadata (unit, scope, q-source, etc.) from a dfdr_run_all result. This is intended to accompany an export folder for auditing and sharing.

Usage

dfdr_write_readme(diag, out_dir, filename = "README.md")

Arguments

Value

The path to the written README file, returned invisibly. The function is called for its side effect of writing a file to disk.

Examples

library(tibble)

# Minimal dfdr_run_all-like object for demonstrating README writing
df <- tibble(
  id = c("1","2","3"),
  run = "run1",
  is_decoy = c(FALSE, TRUE, FALSE),
  score = c(10, 9, 8),
  q = c(0.01, 0.02, 0.03),
  pep = NA_real_
)
x <- as_dfdr_tbl(df, unit = "psm", scope = "global", q_source = "toy")

diag <- list(
  objects = list(toy = x),
  params = list(alpha_main = 0.01),
  tables = list(headline = tibble(list = "toy", alpha = 0.01)),
  warnings = character()
)

out_dir <- tempdir()
dfdr_write_readme(diag, out_dir = out_dir, filename = "README_example.md")

Description

Writes tables as CSV and plots as PNG, optionally creates a PPTX (requires officer+rvg).

Exports the output of dfdr_run_all to disk. Depending on selected formats, this function can:

• write diagnostic tables as CSV;

• write plots as PNG;

• create a PowerPoint (.pptx) containing the plots (requires officer and rvg in Suggests);

• write a lightweight manifest (dfdr_write_manifest);

• write a human-readable README.md (dfdr_write_readme);

• write a compact headline summary table (summary_headline.csv).

Usage

dfdr_write_report(
  diag,
  out_dir,
  formats = c("csv", "png", "manifest", "readme", "summary"),
  pptx_path = file.path(out_dir, "diagFDR_report.pptx"),
  width = 7.2,
  height = 4.4,
  dpi = 180
)

dfdr_write_report(
  diag,
  out_dir,
  formats = c("csv", "png", "manifest", "readme", "summary"),
  pptx_path = file.path(out_dir, "diagFDR_report.pptx"),
  width = 7.2,
  height = 4.4,
  dpi = 180
)

Arguments

Value

Invisibly returns TRUE.

Returns TRUE invisibly. The function is called for its side effects of writing files to out_dir.

Examples

library(tibble)

# Create a minimal diag object with one table and one plot
diag <- list(
  tables = list(headline = tibble(list = "toy", alpha = 0.01, D_alpha = 10)),
  plots = list(example_plot = ggplot2::ggplot(tibble(x = 1:3, y = 1:3),
                                             ggplot2::aes(x, y)) +
                ggplot2::geom_point()),
  objects = list(),
  params = list(alpha_main = 0.01),
  warnings = character()
)

out_dir <- tempdir()
dfdr_write_report(
diag, out_dir = out_dir,
formats = c("csv", "png", "summary", "manifest", "readme"))

Description

Constructs a precursor-level table by taking the minimum run-wise q-value across runs for each Precursor.Id. This mirrors a common scope misuse (aggregating run-wise q-values into a single global list) and is useful for scope-disagreement diagnostics.

Usage

diann_global_minrunq(
  rep,
  run_col = NULL,
  q_col = "Q.Value",
  pep_col = NULL,
  score_col = NULL,
  q_max_export = NA_real_,
  unit = "precursor",
  scope = "aggregated",
  q_source = paste0("min_run(", q_col, ")")
)

Arguments

Value

A dfdr_tbl with one row per precursor, where q equals the minimum of the run-wise q-values across runs for that precursor. The returned object is intended for diagnostics (e.g. scope disagreement), not as a recommended FDR procedure.

Examples

library(tibble)

rep <- tibble(
  Run = c("r1", "r2", "r1", "r2"),
  Precursor.Id = c("P1", "P1", "P2", "P2"),
  Decoy = c(0L, 0L, 0L, 1L),
  Q.Value = c(0.02, 0.01, 0.05, 0.04),
  PEP = c(0.03, 0.02, 0.1, 0.9)
)

x <- diann_global_minrunq(rep, run_col = "Run", q_col = "Q.Value", q_max_export = 0.5)
x

Description

Constructs a precursor-level universe by aggregating a DIA-NN report table to one row per Precursor.Id. For each precursor, the minimum q-value is used (via safe_min) and is_decoy is set to TRUE if any row in the group is a decoy.

Usage

diann_global_precursor(
  rep,
  q_col = "Q.Value",
  pep_col = NULL,
  score_col = NULL,
  q_max_export = NA_real_,
  unit = "precursor",
  scope = "global",
  q_source = q_col
)

Arguments

Value

A dfdr_tbl (tibble subclass) with one row per precursor and required columns id, is_decoy, q, pep, run, score. Metadata are stored in attr(x, "meta").

Examples

library(tibble)

rep <- tibble(
  Precursor.Id = c("P1", "P1", "P2"),
  Decoy = c(0L, 0L, 1L),
  Q.Value = c(0.01, 0.02, 0.03),
  PEP = c(0.02, 0.01, 0.9)
)

x <- diann_global_precursor(rep, q_col = "Q.Value", q_max_export = 0.5)
x

Description

Constructs a run-specific universe by aggregating a DIA-NN report table to one row per (run, Precursor.Id). The run column is detected automatically unless provided. For each group, the minimum q-value is used and is_decoy is TRUE if any row is a decoy.

Usage

diann_runxprecursor(
  rep,
  q_col = "Q.Value",
  run_col = NULL,
  pep_col = NULL,
  score_col = NULL,
  q_max_export = NA_real_,
  id_mode = c("id", "runxid"),
  unit = "runxprecursor",
  scope = "runwise",
  q_source = q_col
)

Arguments

Value

A dfdr_tbl with one row per run-by-precursor unit. The returned table includes id, run, is_decoy, q, pep, and score. Metadata are stored in attr(x, "meta").

Examples

library(tibble)

rep <- tibble(
  Run = c("r1", "r1", "r2", "r2"),
  Precursor.Id = c("P1", "P1", "P1", "P2"),
  Decoy = c(0L, 0L, 1L, 0L),
  Q.Value = c(0.01, 0.02, 0.03, 0.02),
  PEP = c(0.02, 0.01, 0.9, 0.05)
)

x <- diann_runxprecursor(rep, q_col = "Q.Value", run_col = "Run", id_mode = "runxid")
x

Description

Adds simple, ASCII-only flags and a coarse overall status to a headline diagnostics table (typically produced by dfdr_headline or the headline table inside dfdr_run_all). The heuristics are intended for quick triage in reports; they do not replace manual review.

Usage

flag_headline(headline_tbl)

Arguments

Details

Rendering as icons (if desired) can be handled downstream (e.g. in an HTML template); this function returns plain text labels for portability.

Value

A tibble (or data frame) with the same rows as headline_tbl and additional columns:

flag_Dalpha

Flag based on D_alpha (decoy support).

flag_CV

Flag based on CV_hat (stability/variability).

flag_Dwin

Flag based on D_alpha_win (local tail support).

flag_IPE

Flag based on IPE (internal PEP calibration error).

flag_FDR

Flag comparing FDR_hat to the nominal alpha.

flag_equalchance

Flag based on effect_abs (equal-chance deviation).

status

Overall triage status: "VALID", "CAUTION", or "REVIEW_NEEDED".

interpretation

A short human-readable interpretation string.

Examples

library(tibble)

headline_tbl <- tibble(
  list = c("A", "B"),
  alpha = 0.01,
  D_alpha = c(5, 80),
  CV_hat = c(0.35, 0.10),
  D_alpha_win = c(2, 30),
  IPE = c(0.12, 0.02),
  FDR_hat = c(0.02, 0.009),
  effect_abs = c(0.18, 0.05)
)

flag_headline(headline_tbl)

Description

Constructs a "postprocessor universe" by selecting (competing) the single best scoring entry (target or decoy) per run + spectrum_id from mokapot PSM outputs. This yields one row per spectrum per run and can be used for downstream target-decoy diagnostics.

Usage

mokapot_competed_universe(
  raw,
  run_col = "run",
  spectrum_id_col = "spectrum_id",
  score_col = "mokapot score",
  q_col = "mokapot q-value",
  pep_col = "mokapot PEP",
  id_mode = c("runxid", "id"),
  unit = "psm",
  scope = "global",
  q_source = "mokapot q-value",
  q_max_export = 1
)

Arguments

Value

An object of class dfdr_tbl (a tibble subclass) with one row per competed run + spectrum_id. The returned table contains the standard columns required by diagFDR: id, is_decoy, q, pep, run, and score. Metadata are stored in attr(x, "meta").

Examples

library(tibble)

raw <- tibble(
  run = c("r1", "r1"),
  spectrum_id = c("1001", "1001"),
  `mokapot score` = c(2.0, 1.0),      # target wins
  `mokapot q-value` = c(0.01, 0.5),
  `mokapot PEP` = c(0.02, 0.6),
  is_target = c(TRUE, FALSE)
)

x <- mokapot_competed_universe(raw, id_mode = "runxid")
x

Description

Prints a compact header with attached metadata (unit, scope, q-source, etc.) and then falls back to the default tibble/data.frame print method.

Usage

## S3 method for class 'dfdr_tbl'
print(x, ...)

Arguments

Value

Returns x invisibly (called for its printing side effect).

Examples

library(tibble)

df <- tibble(
  id = as.character(1:3),
  run = "run1",
  is_decoy = c(FALSE, TRUE, FALSE),
  score = c(10, 9, 8),
  q = c(0.01, 0.02, 0.03),
  pep = c(0.01, NA, 0.03)
)
x <- as_dfdr_tbl(df, unit = "psm", scope = "global", q_source = "toy_q")
x

Description

Reads a MaxQuant msms.txt file and returns a dfdr_tbl at the PSM level. q-values are reconstructed by target-decoy counting (TDC) using MaxQuant Score (higher is better) and the Reverse column as the decoy indicator ("+" for decoy).

Usage

read_dfdr_maxquant_msms(
  path,
  pep_mode = c("drop", "sanitize", "strict"),
  exclude_contaminants = TRUE,
  add_decoy = 1L,
  unit = "psm",
  scope = "global",
  provenance = list()
)

Arguments