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

View source: R/pipeline.R

ras	R Documentation

RAS: Regional Association Score Analysis

Description

Detect significant association regions in GWAS data. Returns an object of class "ras".

Usage

ras(
  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,
  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`. Default `5`.
`max_window_size`	Integer. Maximum scan window half-size passed to `screen_forward_max_region`. Default `100`.
`scan_test`	Character. Per-window test for binary traits, passed to `screen_forward_max_region`. `"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`.
`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.

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

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

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(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, ras_detect, 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(
  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             = 5,
  skip2             = 5,
  min_window_size   = 2,
  max_window_size   = 10,
  chrom             = 1,
  save_dir          = tempdir(),
  run_plots         = TRUE,
  plot_device       = "png"
)

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

RAS documentation built on July 24, 2026, 5:06 p.m.