ras_original: RAS Pipeline (Pure-R, In-Memory)
In RAS: Regional Association Score for Genome-Wide Association Studies

ras_original

R Documentation

RAS Pipeline (Pure-R, In-Memory)

Description

This is the pure-R, in-memory implementation that RAS 1.0.x shipped under the plain name. Since 1.1.0 the plain name (ras) is the compiled, disk-backed implementation; this function is kept for reference and gives the same results. Detect significant association regions in GWAS data. Returns an object of class "ras".

Usage

ras_original(
  geno,
  phenotype,
  covariates,
  covariate_cols,
  is_continuous,
  num_rep = 5,
  skip1 = 10,
  skip2 = 20,
  chrom = 1,
  save_dir = file.path(tempdir(), "RAS"),
  min_window_size = 5,
  max_window_size = 100,
  scan_test = c("glm", "score"),
  cp_p_threshold = 0.01,
  cp_window_size = 3000,
  cp_min_length = 10,
  cp_slope_check_window = 30,
  cp_slope_left = 1e-10,
  cp_slope_right = 1e-20,
  second_window_size = 50,
  second_p_threshold = 1e-10,
  min_signal = 2.5,
  detector = c("changepoint", "box"),
  box_threshold = NULL,
  box_calibration = NULL,
  box_level0 = NA_real_,
  run_plots = TRUE,
  plot_device = "pdf",
  plot_p_threshold = 8,
  plot_y_cap = NULL
)

Arguments

`geno`	Matrix of genotype dosages (`n` samples `\times` `N` variants). Rows must be aligned with phenotype and covariates.
`phenotype`	Numeric vector of length `n`. Raw phenotype values. For continuous traits the function residualises covariates from the training phenotype internally each repetition; pass the original un-residualised values here.
`covariates`	Data frame with `n` rows aligned with geno. Must contain all columns named in covariate_cols; additional columns (e.g., an ID column) are silently ignored.
`covariate_cols`	Character vector of column names in covariates to include in the regression models.
`is_continuous`	Logical. `TRUE` for quantitative traits, `FALSE` for binary (case/control) traits.
`num_rep`	Integer. Number of independent 50/50 splits to average over. Default `5`.
`skip1`	Integer. Step size for the primary SNP position grid (`seq(1, N, by = skip1)`). Default `10`.
`skip2`	Integer. Sub-step used to grow the scan window at each grid position. Default `20`.
`chrom`	Integer. Chromosome number used in saved file names. Default `1`.
`save_dir`	Character. Directory for intermediate `.rds` output files; created recursively if it does not exist. Defaults to a per-session subdirectory of `tempdir()`; set an explicit path to keep the outputs.
`min_window_size`	Integer. Minimum scan window half-size passed to `screen_forward_max_region_original`. Default `5`.
`max_window_size`	Integer. Maximum scan window half-size passed to `screen_forward_max_region_original`. Default `100`.
`scan_test`	Character. Per-window test for binary traits, passed to `screen_forward_max_region_original`. `"glm"` (default) fits a full logistic model per window (Wald p-value); `"score"` fits the null logistic model once and uses a Rao score test per window (asymptotically equivalent, much faster at scale). Has no effect for continuous traits.
`cp_p_threshold`	Numeric. Davies test p-value threshold for first-pass candidate changepoints. Default `0.01`.
`cp_window_size`	Integer. Sliding window width for first-pass detection. Default `3000`.
`cp_min_length`	Integer. Minimum segment length before and after a candidate changepoint. Default `10`.
`cp_slope_check_window`	Integer. Half-width of the local window used to verify slope direction around each candidate. Default `30`.
`cp_slope_left`	Numeric. One-tailed p-value threshold for the left-side slope test (tests that the slope to the left of the candidate is significantly positive). Default `1e-10`.
`cp_slope_right`	Numeric. One-tailed p-value threshold for the right-side slope test (tests that the slope to the right is significantly negative). Default `1e-20`.
`second_window_size`	Integer. Half-window size for second-pass local Davies tests. Default `50`.
`second_p_threshold`	Numeric. Davies test p-value threshold for second-pass validation. Default `1e-10`.
`min_signal`	Numeric. Minimum `-\log_{10}(p)` scan value required to retain a validated changepoint (passed to `ras_validate`); also used as the low-signal colour boundary in all diagnostic plots. Default `2.5`.
`detector`	Character. Which region detector to run on the scan profile: `"changepoint"` (default) is the original two-pass detector, `ras_detect_original` followed by `ras_validate`, which reports single changepoint positions; `"box"` is the box-scan region detector `ras_box_detect`, which reports intervals `[\tau_L, \tau_R]` and also delimits broad plateau-shaped regions. The `cp_`, `second_` and `min_signal` arguments apply to `"changepoint"` only; the `box_*` arguments to `"box"` only.
`box_threshold`	Numeric. Threshold on the box-scan score for `detector = "box"`. Required unless `box_calibration` is given; see `ras_box_calibrate` for how to obtain it.
`box_calibration`	A `ras_box_calibrate` result for `detector = "box"`; supplies the threshold and `level0`.
`box_level0`	Numeric. Typical median of a null profile for the box scan's level factor (see `ras_box_stat`). `NA` (default) takes it from `box_calibration` when one is given and disables the level factor otherwise.
`run_plots`	Logical. If `TRUE` (default), saves diagnostic plots via `plot_ras_scan` and `plot_ras_zoom_regions`.
`plot_device`	Character. Output device for plots: `"pdf"` (default), `"png"`, or `"screen"`.
`plot_p_threshold`	Numeric. Significance reference line drawn on plots (on the `-\log_{10}` scale). Default `8`.
`plot_y_cap`	Numeric or `NULL`. If provided, the y-axis is capped at this value and positions above the cap are annotated with arrows. Default `NULL` (no cap).

Details

For a stage-by-stage description of the pipeline see RAS.

Two region detectors are available for Stage 2. The default detector = "changepoint" reproduces the published method and the results of earlier versions of this package exactly. detector = "box" runs ras_box_detect instead; it needs a threshold, which is a property of the null distribution of the scan and is obtained with ras_box_calibrate from null profiles (the same scan on permuted phenotypes).

Value

Invisibly returns a named list with two elements:

scan

A list with elements:

x: Integer vector. SNP position index grid seq(1, N, by = skip1).
y: Numeric vector (same length as x). Averaged -\log_{10}(p)-value profile across all repetitions.

detection

For detector = "changepoint", the list returned by ras_validate with elements:

tau_hats: Integer vector. Validated changepoint positions (re-mapped to genomic coordinates via this.start and this.skip).
all.changepoints: Integer vector. All candidate positions examined during the first pass, re-mapped to genomic coordinates.
all.p.values: Numeric vector. -\log_{10}(p) Davies test values for every candidate in all.changepoints.
left.slopes: Numeric vector. Estimated left-side slopes at each validated changepoint.
right.slopes: Numeric vector. Estimated right-side slopes at each validated changepoint.
detector: "changepoint".

For detector = "box", the list returned by ras_box_detect: regions (one row per interval with pos_L, pos_R, T_box, ...), tau_hats (the anchor of each interval) and the threshold used.

Plot files (if run_plots = TRUE) are written to save_dir with names chr-<chrom>-cp-plot.<ext>, chr-<chrom>-cp-p-values-plot.<ext>, and chr-<chrom>-zoom.<ext>.

Simple (recommended)

## one call does everything
result <- ras_original(geno, phenotype, covariates,
              covariate_cols = c("age", "sex", paste0("pc", 1:10)),
              is_continuous  = TRUE,
              chrom = 1, save_dir = "results/")

print(result)             # detected changepoint positions
plot(result)              # full-chromosome scan profile
plot(result, zoom = TRUE) # zoomed view around each changepoint

For step-by-step control see ras_scan_original, ras_detect_original, ras_validate.

Examples


set.seed(42)
n_samp <- 80; n_snp <- 60
geno <- matrix(
  sample(0:2, n_samp * n_snp, replace = TRUE, prob = c(0.6, 0.3, 0.1)),
  nrow = n_samp, ncol = n_snp)
pheno <- rnorm(n_samp)
cov_df <- data.frame(age = rnorm(n_samp), sex = rbinom(n_samp, 1, 0.5))
cov_df$age_squared <- cov_df$age^2
cov_df$age_sex     <- cov_df$age * cov_df$sex
for (i in 1:10) cov_df[[paste0("pc", i)]] <- rnorm(n_samp)

result <- ras_original(
  geno              = geno,
  phenotype         = pheno,
  covariates        = cov_df,
  covariate_cols    = c("age", "sex", "age_squared", "age_sex",
                        paste0("pc", 1:10)),
  is_continuous     = TRUE,
  num_rep           = 2,
  skip1             = 1,        # every SNP on the grid: a 60-point profile
  skip2             = 2,
  min_window_size   = 2,
  max_window_size   = 10,
  # detector settings scaled down to the 60-point toy profile (the defaults
  # are tuned for genome-scale grids with tens of thousands of points)
  cp_window_size        = 30,
  cp_min_length         = 5,
  cp_slope_check_window = 5,
  cp_slope_left         = 1e-3,
  cp_slope_right        = 1e-3,
  second_window_size    = 10,
  second_p_threshold    = 1e-3,
  chrom             = 1,
  save_dir          = tempdir(),
  run_plots         = TRUE,
  plot_device       = "pdf"
)

cat("Detected changepoints:", result$detection$tau_hats, "\n")
plot(result$scan$x, result$scan$y, type = "l",
     xlab = "SNP index", ylab = expression(-log[10](p)),
     main = "RAS scan profile")

## The box-scan region detector on the same scan profile. In the one-call
## form this is ras_original(..., detector = "box", box_threshold = 2); the threshold
## would normally come from ras_box_calibrate() on null profiles.
result_box <- result
result_box$detection <- ras_box_detect(result$scan$x, result$scan$y,
                                       threshold = 2)
print(result_box)

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