R/RiskyCNV-package.R

In RiskyCNV: Risk Analysis of Genomic Copy Number Variation

#' RiskyCNV: A General-Purpose CNV Analysis Workflow for Disease Risk Stratification
#'
#' Provides a complete seven-step workflow for copy number variation (CNV)
#' analysis applicable to any disease or condition where genomic copy number
#' data is available. The package supports three classification approaches:
#' built-in grading and risk stratification presets for seven major disease
#' types (prostate, breast, colorectal, lung, cervical, lymphoma, melanoma)
#' based on clinically validated scoring systems; an automatic mode that
#' derives a normalised Risk Score from the data itself using min-max
#' normalisation and adaptive binning; and fully user-defined custom
#' thresholds for any disease type not covered by the presets. Downstream
#' functions for CNV aberration detection, recurrence analysis, gene
#' annotation, CNV matrix generation, and CNV-RNA expression correlation
#' are disease-type agnostic and work with any genomic dataset.
#'
#' @section Workflow:
#' The recommended analysis pipeline proceeds in seven steps:
#' \enumerate{
#'   \item \code{\link{extract_metadata}} — Classify samples into grade or
#'     stage groups based on a clinical scoring parameter. Supports
#'     disease-specific presets, auto mode, and custom thresholds.
#'   \item \code{\link{classify_risk}} — Stratify samples into risk
#'     categories. Supports disease-specific presets, auto mode, and
#'     custom thresholds.
#'   \item \code{\link{aberration}} — Detect CNV gains and losses from
#'     segmented CNV data using a user-defined effect size threshold.
#'   \item \code{\link{recurrent}} — Identify CNV regions that recur
#'     across multiple samples within a risk group.
#'   \item \code{\link{annotate}} — Annotate recurrent CNV regions with
#'     gene symbols using genomic range overlaps.
#'   \item \code{\link{create_CNVMatrix}} — Construct a sample x gene
#'     CNV expression matrix.
#'   \item \code{\link{correlate_with_expr}} — Compute Pearson correlations
#'     between CNV profiles and RNA expression data.
#' }
#'
#' @section Classification Modes:
#' \describe{
#'   \item{Disease presets}{Built-in clinically validated thresholds for
#'     prostate (ISUP/Gleason), breast (Nottingham), colorectal (Dukes),
#'     lung (IASLC/TNM), cervical (FIGO), lymphoma (Ann Arbor/Lugano),
#'     and melanoma (Breslow depth).}
#'   \item{Auto mode}{Automatically computes a normalised Risk Score using
#'     min-max normalisation. Group boundaries are determined adaptively
#'     based on distribution skewness — equal-width for symmetric
#'     distributions, quantile-based for skewed distributions. Works for
#'     any numeric scoring column without prior knowledge of the scoring
#'     system.}
#'   \item{Custom mode}{Users supply their own threshold functions for any
#'     disease type, scoring system, or number of groups.}
#' }
#'
#' @section Supported Disease Types (Built-in Presets):
#' prostate (ISUP/Gleason), breast (Nottingham/NGS), colorectal (Dukes),
#' lung (IASLC/TNM), cervical (FIGO), lymphoma (Ann Arbor/Lugano), and
#' melanoma (Breslow depth).
#'
#' @references
#' \itemize{
#'   \item Epstein JI, et al. (2016). \emph{Am J Surg Pathol}, 40(2):244-252.
#'   \item Elston CW & Ellis IO. (1991). \emph{Histopathology}, 19(5):403-410.
#'   \item Dukes CE. (1932). \emph{J Pathol Bacteriol}, 35:323-332.
#'   \item Goldstraw P, et al. (2016). \emph{J Thorac Oncol}, 11(1):39-51.
#'   \item Bhatla N, et al. (2019). \emph{Int J Gynaecol Obstet},
#'     145(1):129-135.
#'   \item Cheson BD, et al. (2014). \emph{J Clin Oncol}, 32(27):3059-3068.
#'   \item Breslow A. (1970). \emph{Ann Surg}, 172(5):902-908.
#' }
#'
#' @docType package
#' @name RiskyCNV
"_PACKAGE"

#' @importFrom utils read.csv read.table write.csv
#' @importFrom rlang .data
NULL