R/RAS-package.R

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

#' RAS: Regional Association Score for Genome-Wide Association Studies
#'
#' The RAS package implements the Regional Association Score method for
#' genome-wide association studies.  It converts per-SNP effect sizes into a
#' genomic \eqn{-\log_{10}(p)} time series and applies changepoint detection
#' to locate peaks that mark significant association regions.  The method
#' supports both continuous and binary traits.
#'
#' @section Option A — one call (recommended):
#' \code{\link{ras}} runs the complete pipeline and returns a \code{"ras"}
#' object; use \code{\link{plot.ras}} to visualise results.
#' \preformatted{
#' 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
#' }
#'
#' @section Option B — step-by-step (advanced):
#' \code{\link{ras_scan}} \eqn{\to} \code{\link{ras_detect}} \eqn{\to}
#' \code{\link{ras_validate}} \eqn{\to} \code{\link{plot.ras}}
#' \preformatted{
#' ## Step 1: compute averaged -log10(p) profile
#' scan     <- ras_scan(geno, phenotype, covariates,
#'                      covariate_cols = c("age", "sex", paste0("pc", 1:10)),
#'                      is_continuous = TRUE, chrom = 1, save_dir = "results/")
#'
#' ## Step 2: first-pass changepoint detection
#' detected <- ras_detect(scan$x, scan$y,
#'                        window_size = 3000,
#'                        slope.p.values.threshold.left  = 1e-10,
#'                        slope.p.values.threshold.right = 1e-20)
#'
#' ## Step 3: second-pass validation
#' final    <- ras_validate(detected, x = scan$x, y = scan$y,
#'                          this.skip = 10, p.value.threshold = 1e-10)
#'
#' ## Step 4: plot
#' result   <- structure(
#'   list(scan = scan, detection = final, chrom = 1, save_dir = "results/"),
#'   class = "ras")
#'
#' plot(result)
#' plot(result, zoom = TRUE)
#' }
#'
#' @section Stage 1 — Scan:
#' \code{\link{ras_scan}} performs \strong{num_rep} independent 50/50
#' train/hold-out splits.  In each repetition it fits per-SNP regressions on
#' the training half (\code{\link{compute_gwas_weights}}), builds a weighted
#' dosage matrix for the hold-out half (\code{\link{compute_pgs_matrix}}),
#' and runs a forward scan (\code{\link{screen_forward_max_region}}) that
#' slides an expanding window and records the minimum \eqn{p}-value at each
#' grid position.  The \eqn{-\log_{10}(p)} vectors are averaged across
#' repetitions.  For continuous traits, covariates are residualised from the
#' training phenotype each repetition (no hold-out leakage); for binary
#' traits, logistic regression is used in the scan step.
#'
#' @section Stage 2 — First-pass changepoint detection:
#' \code{\link{ras_detect}} slides a window of width \strong{cp_window_size}
#' across the profile.  At each position \code{\link{get_break_points}} fits
#' a segmented linear model and applies the Davies test.  A candidate is
#' retained only when three conditions all hold: Davies \eqn{p <}
#' \strong{cp_p_threshold}, left-side slope significantly positive
#' (\code{\link{slope_test}}, \eqn{p <} \strong{cp_slope_left}), and
#' right-side slope significantly negative (\eqn{p <} \strong{cp_slope_right}).
#' Each accepted candidate is snapped to the nearest local peak via
#' \code{\link{get_local_maximum}}.
#'
#' @section Stage 3 — Second-pass validation:
#' \code{\link{ras_validate}} re-tests each first-pass candidate with local
#' Davies tests on both sides within a window of half-width
#' \strong{second_window_size}.  A candidate is accepted if either side passes
#' \eqn{p <} \strong{second_p_threshold}.  Candidates with
#' \eqn{-\log_{10}(p) \le} \strong{min_signal} at the estimated position are
#' discarded regardless.
#'
#' @section Stage 4 — Plots:
#' \code{\link{plot.ras}} with \code{zoom = FALSE} produces two files: the
#' RAS scan profile with detected changepoints highlighted, and a dual-axis
#' overlay with Davies test significance at every candidate.
#' \code{\link{plot.ras}} with \code{zoom = TRUE} produces a multi-panel
#' figure with one zoomed panel per changepoint.
#'
#' @author
#' Jiahe Jin \email{jiahe.jin@yale.edu} (maintainer),
#' Yiran Jiang \email{yiran.jiang@uky.edu},
#' Heping Zhang \email{heping.zhang@yale.edu}
#'
#' @seealso
#' \itemize{
#'   \item \code{\link{compute_gwas_weights}}
#'   \item \code{\link{compute_pgs_matrix}}
#'   \item \code{\link{get_break_points}}
#'   \item \code{\link{get_local_maximum}}
#'   \item \code{\link{plot.ras}}
#'   \item \code{\link{print.ras}}
#'   \item \code{\link{ras}}
#'   \item \code{\link{ras_detect}}
#'   \item \code{\link{ras_memory}}
#'   \item \code{\link{ras_scan}}
#'   \item \code{\link{ras_validate}}
#'   \item \code{\link{release_memory}}
#'   \item \code{\link{screen_forward_max_region}}
#'   \item \code{\link{slope_test}}
#' }
#'
#' @importFrom grDevices dev.off pdf png rgb
#' @importFrom graphics abline arrows axis legend lines mtext par plot plot.new rect segments text
#' @importFrom stats as.formula binomial coef df.residual glm lm na.omit pt
#' @useDynLib RAS, .registration = TRUE
"_PACKAGE"