ras_box_detect: Detect Elevated Regions with the Box Scan

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

Detect Elevated Regions with the Box Scan

Description

The box-scan region detector, the alternative to the changepoint detector (ras_detect + ras_validate) selected with detector = "box" in ras. It reports intervals [\tau_L, \tau_R] of the scan profile whose mean stands above both adjacent flanks and above the profile background, which lets it delimit broad plateau-shaped association regions as well as sharp peaks.

Usage

ras_box_detect(
  x,
  y,
  threshold = NULL,
  calibration = NULL,
  scaled = FALSE,
  level0 = NULL,
  widths = NULL,
  gamma = NULL,
  edge = NULL,
  floor = 0.2,
  max_regions = Inf,
  keep_stat = FALSE
)

Arguments

x	Numeric vector. Grid positions of the profile (scan$x, the SNP index of each grid point).
y	Numeric vector. The scan profile (scan$y), same length as x.
threshold	Numeric. Keep regions with T_box >= threshold. Either threshold or calibration must be supplied.
calibration	A ras_box_calibrate result. Supplies threshold (or threshold_scaled when scaled = TRUE), level0, widths, gamma and edge; an explicitly supplied argument overrides the calibrated value.
scaled	Logical. With a calibration whose length_ratio > 1, use its threshold_scaled (the threshold extrapolated to a profile that many times longer than the null profiles) instead of threshold. Default FALSE.
level0, widths, gamma, edge	As in ras_box_stat; NULL (default) takes the value from calibration when one is given and the ras_box_stat default otherwise.
floor	Numeric. Windows with T below this value are never considered, whatever the threshold. Default 0.2.
max_regions	Integer. Stop after this many regions. Default Inf.
keep_stat	Logical. Also return the full ras_box_stat table as element stat. Default FALSE (the table has one row per window start and width, so it is large for a chromosome-length profile).

Details

Windows are scored with ras_box_stat and taken greedily by score; a window is dropped when it touches an already accepted one expanded by 10 + max(5, width/2) grid points, which removes side lobes. Each accepted window becomes one region; its anchor is the highest point of the profile inside it.

The threshold is a property of the null distribution of the maximum score along a profile and therefore depends on the profile's length and on the scan settings. Obtain it with ras_box_calibrate from null profiles produced by the same scan on permuted phenotypes; the order statistic it returns controls the family-wise error rate at the requested level without any distributional assumption.

Value

A list that plot.ras and print.ras accept as a detection element:

detector

"box".

regions

Data frame with one row per region, ordered by decreasing score: tau_L, tau_R (grid indices), pos_L, pos_R (the same boundaries in x units), width, T_box, contrast, height, anchor_idx, anchor_pos, anchor_y. NULL when nothing reaches the threshold.

tau_hats

Numeric vector. Anchor positions in x units (the same role as in ras_validate's result).

all.changepoints, all.p.values

Anchor positions and their T_box scores, so that the candidate overlay of plot.ras works.

left.slopes, right.slopes

NULL; the box scan estimates no slopes.

threshold, level0, level, level_factor

The threshold used, the null level, the median of y and the resulting level factor.

stat

The ras_box_stat table when keep_stat = TRUE, otherwise NULL.

See Also

ras_box_calibrate for the threshold, ras_box_stat for the statistic, ras_detect for the changepoint detector, ras which calls this function when detector = "box".

Examples

set.seed(1)
x <- seq(1, 6000, by = 10)                 # 600 grid points
y <- 0.7 + abs(rnorm(600, sd = 0.3))       # null-like background
y[301:342] <- y[301:342] + 8               # a 42-point plateau
det <- ras_box_detect(x, y, threshold = 2)
det$regions[, c("tau_L", "tau_R", "pos_L", "pos_R", "T_box")]

## a window inside the plateau scores about 0: only its edges are reported
S <- ras_box_stat(y)
max(S$T[S$w == 20 & S$i >= 305 & S$i + 19 <= 338])

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