screen_forward_max_region_original: Forward Scan of the RAS Profile (Pure-R, In-Memory)
In RAS: Regional Association Score for Genome-Wide Association Studies

screen_forward_max_region_original

R Documentation

Forward Scan of the RAS Profile (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 (screen_forward_max_region) is the compiled, disk-backed implementation; this function is kept for reference and gives the same results. Slides an expanding window across the genome, accumulating weighted genotype contributions and testing association with the hold-out phenotype at each position.

Usage

screen_forward_max_region_original(
  geno,
  pgs.mat,
  this.df,
  num_signals,
  start.point = 1,
  save.directory = tempdir(),
  this.chrome = 1,
  min_window_size = 5,
  max_window_size = 100,
  isSimulation = TRUE,
  this.repetition = 1,
  screening_round = 1,
  isPlot = FALSE,
  skip1 = 100,
  skip2 = 5,
  is_continuous,
  covariate_formula = NULL,
  scan_test = c("glm", "score"),
  signal.starts = NULL,
  signal.window.size = NULL
)

Arguments

`geno`	Matrix of genotype dosages (`n` samples `\times` `N` variants).
`pgs.mat`	Matrix of pre-computed per-variant PGS contributions (`n_{\text{holdout}} \times N`), as returned by `compute_pgs_matrix`.
`this.df`	Data frame containing the hold-out phenotype in a column named `phenotype2` and any covariate columns named in `covariate_formula`. Rows must correspond to hold-out individuals.
`num_signals`	Integer. Number of true signals; used only for simulation plots (`isSimulation = TRUE`) to draw reference lines. Pass `-1` for real data.
`start.point`	Integer. Starting SNP index for the scan. Default `1`.
`save.directory`	Character. Directory for optional PDF plots (only used when `isPlot = TRUE`). Defaults to `tempdir()` so nothing is written outside the session's temporary area unless the caller chooses an explicit path.
`this.chrome`	Integer. Chromosome number for non-simulation plot filenames. Default `1`.
`min_window_size`	Integer. Minimum scan window half-size. Default `5`.
`max_window_size`	Integer. Maximum scan window half-size. Default `100`.
`isSimulation`	Logical. If `TRUE`, use simulation-mode plot filenames and draw true-signal reference lines. Default `TRUE`.
`this.repetition`	Integer. Repetition index used in plot filenames. Default `1`.
`screening_round`	Integer. Number of forward screening rounds. Only a single round is implemented; values other than `1` raise an error. Default `1`.
`isPlot`	Logical. If `TRUE`, save a PDF of the scan profile to `save.directory`. Default `FALSE` (no file is written).
`skip1`	Integer. Step size for the primary SNP position grid. Default `100`.
`skip2`	Integer. Step size for growing the window within each grid position. Default `5`.
`is_continuous`	Logical. If `TRUE`, the per-window PGS p-value is obtained from a linear model via an exact Frisch-Waugh-Lovell residualisation (numerically identical to `lm(phenotype2 ~ this.pgs + covariates)` but the covariate factorisation is done once instead of per window). If `FALSE`, a binary trait is used (see `scan_test`).
`covariate_formula`	Character. Right-hand side covariates (without the PGS term `this.pgs`) in the scan regression formula. If `NULL`, a default formula with sex, age, age-squared, age-sex interaction, and the first ten ancestry PCs is used.
`scan_test`	Character. Test used for the binary branch (`is_continuous = FALSE`). `"glm"` (default) fits a full logistic regression per window and reports the Wald p-value of the PGS term, preserving the original behaviour. `"score"` fits the covariate-only null logistic model once and evaluates a Rao score test for the PGS term at each window, which is asymptotically equivalent but avoids per-window iterative fitting (typically 1-2 orders of magnitude faster at scale). Ignored when `is_continuous = TRUE` (the continuous branch always uses `lm`).
`signal.starts`	Integer vector. True signal start positions for simulation reference lines. Default `NULL`.
`signal.window.size`	Integer. Width of each true signal window for simulation reference lines. Default `NULL`.

Details

At each grid position j \in \{1, 1 + \texttt{skip1}, \ldots, N\} the function builds a polygenic score (PGS) by accumulating columns of pgs.mat from a growing symmetric window [j - w + 1,\; j + w - 1] for w \in \{0, \texttt{min\_window\_size}, \ldots, \texttt{max\_window\_size}\}. The accumulation is incremental: only the newly added columns are summed at each step, avoiding redundant computation.

At window size w = 0, only column j of pgs.mat is used (the single-SNP PGS). For each window size the PGS is tested against phenotype2 via lm (continuous) or glm(family = binomial()) (binary). The minimum p-value over all window sizes is stored for position j.

The final return value is -\log_{10} of these per-position minimum p-values.

Value

Numeric vector of length \lceil N / \texttt{skip1} \rceil. Each element is the -\log_{10}(p)-value at the corresponding grid position, where the p-value is the minimum over all tested window sizes.

Examples


set.seed(3)
n_samp <- 80; n_snp <- 50
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)
weights  <- rnorm(n_snp)
leftout  <- 31:80
pgs_mat  <- compute_pgs_matrix(geno, leftout, weights)

scan_df           <- data.frame(matrix(rnorm(50 * 12), 50, 12))
colnames(scan_df) <- c("age", "sex", "age_squared", "age_sex",
                       paste0("pc", 1:8))
scan_df$phenotype2 <- rnorm(50)

p_vec <- screen_forward_max_region_original(
  geno              = geno,
  pgs.mat           = pgs_mat,
  this.df           = scan_df,
  num_signals       = -1,
  is_continuous     = TRUE,
  covariate_formula = paste(c("age", "sex"), collapse = " + "),
  skip1             = 5,
  skip2             = 5,
  min_window_size   = 2,
  max_window_size   = 8,
  isPlot            = FALSE
)
plot(seq(1, n_snp, by = 5), p_vec, type = "l",
     xlab = "SNP index", ylab = expression(-log[10](p)))

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