R/order.index.lsn.data.R

In GRIN2: Genomic Random Interval (GRIN)

#' Order and Index Lesion Data
#'
#' @description
#' Orders lesion data by lesion type, chromosome, and patient identifier and
#' creates an index identifying contiguous rows for each lesion
#' type-chromosome-patient combination. This helper function prepares lesion
#' data for downstream GRIN overlap analyses.
#'
#' @usage
#' order.index.lsn.data(lsn.data)
#'
#' @param lsn.data A `data.frame` containing lesion data in GRIN-compatible
#' format with the following columns:
#' \describe{
#'   \item{"ID"}{Patient identifier.}
#'   \item{"chrom"}{Chromosome identifier on which the lesion is located.}
#'   \item{"loc.start"}{Lesion start position in base pairs.}
#'   \item{"loc.end"}{Lesion end position in base pairs.}
#'   \item{"lsn.type"}{Lesion type assigned to the genomic alteration.}
#' }
#'
#' @details
#' Lesions are ordered by lesion type, chromosome, and patient identifier.
#' Consecutive rows sharing the same lesion type, chromosome, and patient are
#' represented by a single entry in `lsn.index`.
#'
#' For example, if a patient has one lesion of a given type on a chromosome,
#' `row.start` and `row.end` are identical. If multiple lesions of the same type
#' occur on that chromosome for the same patient, the index spans the
#' corresponding rows.
#'
#' An `lsn.row` column is added to the ordered lesion data and is used
#' internally by downstream GRIN functions.
#'
#' @return
#' A list with two components:
#' \describe{
#'   \item{lsn.data}{The input lesion data ordered by lesion type, chromosome,
#'   and patient identifier, with an added `lsn.row` column.}
#'   \item{lsn.index}{A `data.frame` with five columns: `lsn.type`, `chrom`,
#'   `ID`, `row.start`, and `row.end`, identifying the range of rows
#'   corresponding to each lesion type-chromosome-patient combination.}
#' }
#'
#' @export
#'
#' @references
#' Pounds, S., et al. (2013). A genomic random interval model for statistical
#' analysis of genomic lesion data.
#'
#' Cao, X., Elsayed, A. H., & Pounds, S. B. (2023). Statistical Methods
#' Inspired by Challenges in Pediatric Cancer Multi-omics.
#'
#' @author
#' Abdelrahman Elsayed \email{abdelrahman.elsayed@stjude.org} and
#' Stanley Pounds \email{stanley.pounds@stjude.org}
#'
#' @seealso \code{\link{prep.gene.lsn.data}}
#'
#' @examples
#' data(lesion_data)
#'
#' # Order lesion data and create lesion type-chromosome-patient row indices
#' ordered.lsn <- order.index.lsn.data(lesion_data)
#'
order.index.lsn.data=function(lsn.data)  # lesion data provided by the user in a GRIN compatible format
{
  if (!is.data.frame(lsn.data))
    stop("'lsn.data' must be a data frame.")

  required.cols=c("ID","chrom","loc.start","loc.end","lsn.type")
  if (!all(required.cols %in% colnames(lsn.data)))
    stop("'lsn.data' must contain the columns: ",
         paste(required.cols,collapse=", "), ".")

  if (nrow(lsn.data)==0)
    stop("'lsn.data' must contain at least one row.")

  l=nrow(lsn.data)
  lsn.ord=order(lsn.data[,"lsn.type"],
                lsn.data[,"chrom"],
                lsn.data[,"ID"])
  lsn.data=lsn.data[lsn.ord,]

  lsn.chng=which((lsn.data[-1,"lsn.type"]!=lsn.data[-l,"lsn.type"])|
                   (lsn.data[-1,"chrom"]!=lsn.data[-l,"chrom"])|
                   (lsn.data[-1,"ID"]!=lsn.data[-l,"ID"]))

  lsn.start=c(1,lsn.chng+1)
  lsn.end=c(lsn.chng,l)

  lsn.index=cbind.data.frame(lsn.type=lsn.data[lsn.start,"lsn.type"],
                             chrom=lsn.data[lsn.start,"chrom"],
                             ID=lsn.data[lsn.start,"ID"],
                             row.start=lsn.start,
                             row.end=lsn.end)

  lsn.data$lsn.row=1:l

  res=list(lsn.data=lsn.data,
           lsn.index=lsn.index)

  return(res)
}