ras_box_calibrate: Calibrate the Box-Scan Threshold on Null Profiles

In RAS: Regional Association Score for Genome-Wide Association Studies

Calibrate the Box-Scan Threshold on Null Profiles

Description

Turns a set of null scan profiles into the threshold that ras_box_detect needs. Null profiles are obtained by running the same scan (ras_scan or ras_scan_external, with the same settings) on the same genotypes with the phenotype permuted, or with a phenotype simulated under the null.

Usage

ras_box_calibrate(
  null_profiles,
  alpha = 0.05,
  widths = .ras_box_default_widths(),
  gamma = 0.5,
  length_ratio = 1,
  calib = NULL,
  edge = c("open", "strict"),
  method = c("order", "gumbel")
)

Arguments

null_profiles	A list of numeric vectors, or a matrix with one null profile per row. All profiles should have the length of the profile that will be analysed, or the length that length_ratio refers to.
alpha	Numeric. Target family-wise error rate. Default 0.05.
widths	Integer vector. Window widths in grid points. Default c(5, 8, 11, 14, 17, 20, 24, 28, 34, 42, 55, 75, 100). Widths that do not fit the profile are dropped.
gamma	Numeric. Exponent of the level factor. Default 0.5.
length_ratio	Numeric. If the profile to be analysed is length_ratio times longer than the null profiles, the null maxima are fitted by a Gumbel law (method of moments) and the (1-\alpha)^{1/length\_ratio} quantile is returned as threshold_scaled. That number is an extrapolation past the data; null_exceed_scaled reports how many null maxima reach it, and a null of the full length is always preferable. Default 1.
calib	Integer vector. Indices of the profiles used to set the threshold; the remaining profiles, if any, give a held-out error rate (fwer_holdout). Default: all profiles.
edge	"open" (default) or "strict". With "strict" both flanks must lie inside the profile, so a region at a chromosome end can never be reported. With "open" a flank that runs off the profile is truncated, and dropped altogether when fewer than 3 points remain; the window then only has to stand above the side that exists (and above the background).
method	Character. "order" (default): the threshold is the order statistic k = \lceil (B+1)(1-\alpha) \rceil of the B null maxima, which bounds the family-wise error rate by \alpha exactly but needs B \ge 1/\alpha profiles and is noisy for small B. "gumbel": the 1-\alpha quantile of a Gumbel law fitted to the null maxima by the method of moments; stable from about 20 profiles on, at the price of a slightly liberal threshold (in a permutation study on a 224-point profile, 20 to 50 profiles gave 97 to 98 percent of the 200-profile order-statistic threshold and a realised error rate of about 0.07 for \alpha = 0.05).

Details

level0 is the median of the null profiles' medians. Both thresholds are always computed and returned (threshold_order, threshold_gumbel); threshold is the one selected by method.

Value

An object of class "ras_box_calibration": a list with level0, threshold, threshold_order, threshold_gumbel, threshold_scaled, method, length_ratio, maxT (the maximum score of every null profile), calib, alpha, gumbel (fitted location and scale), null_exceed_scaled, fwer_holdout (NA when no profile was held out), widths, gamma, edge.

See Also

ras_box_detect, which consumes the result.

Examples

## 60 short synthetic null profiles (a real calibration uses several
## hundred profiles from the actual scan on permuted phenotypes)
set.seed(2)
nulls <- lapply(1:60, function(k) 0.7 + abs(rnorm(200, sd = 0.3)))
cal <- ras_box_calibrate(nulls, alpha = 0.05, calib = 1:40)
cal$threshold
cal$fwer_holdout           # error rate on the 20 held-out profiles

y <- nulls[[41]]; y[91:110] <- y[91:110] + 6
ras_box_detect(seq_along(y), y, calibration = cal)$regions

RAS documentation built on Nov. 3, 2026, 1:07 a.m.