R/order.index.gene.data.R

In GRIN2: Genomic Random Interval (GRIN)

#' Order and Index Gene Annotation Data
#'
#' @description
#' Orders gene annotation data by chromosome and genomic coordinates and creates
#' an index identifying the rows corresponding to each chromosome. This helper
#' function is used to prepare gene annotation data for downstream GRIN overlap
#' analyses.
#'
#' @usage
#' order.index.gene.data(gene.data)
#'
#' @param gene.data A `data.frame` containing gene annotation information,
#' either provided by the user or obtained using `get.ensembl.annotation`.
#' The data frame must contain the following columns:
#' \describe{
#'   \item{"gene"}{Gene identifier, typically an unversioned Ensembl gene ID.}
#'   \item{"chrom"}{Chromosome identifier on which the gene is located.}
#'   \item{"loc.start"}{Gene start position in base pairs.}
#'   \item{"loc.end"}{Gene end position in base pairs.}
#' }
#'
#' @details
#' Genes are ordered by chromosome, start position, and end position.
#' Consecutive rows belonging to the same chromosome are represented by a
#' single entry in `gene.index`, which records the first and last corresponding
#' row in the ordered gene annotation data.
#'
#' A `gene.row` column is added to the ordered gene annotation data and is used
#' internally by downstream GRIN functions.
#'
#' @return
#' A list with two components:
#' \describe{
#'   \item{gene.data}{The input gene annotation data ordered by chromosome,
#'   `loc.start`, and `loc.end`, with an added `gene.row` column.}
#'   \item{gene.index}{A `data.frame` with three columns: `chrom`,
#'   `row.start`, and `row.end`, identifying the range of rows corresponding
#'   to each chromosome in the ordered gene annotation data.}
#' }
#'
#' @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}},
#' \code{\link{get.ensembl.annotation}}
#'
#' @examples
#' data(hg38_gene_annotation)
#'
#' # Order gene annotation data and create chromosome-specific row indices
#' ordered.genes <- order.index.gene.data(hg38_gene_annotation)
#'
order.index.gene.data=function(gene.data)  # gene annotation data
{
  if (!is.data.frame(gene.data))
    stop("'gene.data' must be a data frame.")

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

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

  g=nrow(gene.data)
  gene.ord=order(gene.data[,"chrom"],
                 gene.data[,"loc.start"],
                 gene.data[,"loc.end"])
  gene.data=gene.data[gene.ord,]

  new.chrom=which(gene.data[-1,"chrom"]!=gene.data[-g,"chrom"])
  chr.start=c(1,new.chrom+1)
  chr.end=c(new.chrom,g)

  gene.index=cbind.data.frame(chrom=gene.data[chr.start,"chrom"],
                              row.start=chr.start,
                              row.end=chr.end)

  gene.data$gene.row=1:g

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

  return(res)
}