prep.gene.lsn.data: Prepare Gene and Lesion Data for GRIN Analysis

In GRIN2: Genomic Random Interval (GRIN)

Prepare Gene and Lesion Data for GRIN Analysis

Description

Prepares and indexes gene and lesion data for downstream GRIN (Genomic Random Interval) analysis. The function merges and orders gene and lesion coordinates to support efficient computation of overlaps between genes and genomic lesions. When requested, it also prepares gene- and chromosome-level exon target sizes for lesion types restricted to exonic regions.

Usage

prep.gene.lsn.data(lsn.data,
                   gene.data,
                   exons.annotation = NULL,
                   exon.chrom.size = NULL,
                   exon_level = NULL,
                   mess.freq = 10)

Arguments

lsn.data	A data.frame containing lesion data in GRIN-compatible format. The following five columns are required: ID Unique patient identifier. chrom Chromosome on which the lesion is located. loc.start Start position of the lesion in base pairs. loc.end End position of the lesion in base pairs. lsn.type Type of genomic lesion, such as mutation, breakpoint, gain, amplification, heterozygous deletion, or homozygous deletion.
gene.data	A data.frame containing gene annotation data with the following four required columns: gene Ensembl gene identifier. chrom Chromosome on which the gene is located. loc.start Start position of the gene in base pairs. loc.end End position of the gene in base pairs.
exons.annotation	An optional data.frame containing exon annotation data. This argument is required when exon_level is specified. The exon annotation may contain the same gene set as gene.data or a subset of those genes. Genes in gene.data without a valid matching exon annotation remain in standard GRIN analyses, but exon-level probabilities are not computed for those genes. Compatible exon annotation data for supported genome assemblies can be retrieved using get.ensembl.annotation(). The following four columns are required: gene Ensembl gene identifier of the gene to which each annotated exon belongs. Multiple rows may therefore share the same gene identifier, with each row representing a different exon of that gene. chrom Chromosome on which the exon is located. loc.start Start position of the exon in base pairs. loc.end End position of the exon in base pairs.
exon.chrom.size	An optional data.frame containing the total annotated exon target size for each chromosome. This argument is required when exon_level is specified and must contain: chrom Chromosome identifier. size Total annotated exon target size for the chromosome in base pairs. The chromosome-level exon sizes should be derived from a genome-wide exon annotation using the same genome assembly and representative-transcript selection procedure used to construct exons.annotation. A compatible chromosome-level exon-size dataset is provided with GRIN2 and can be loaded using data(hg38_exon_chrom_size). Corresponding annotation data can also be obtained using get.ensembl.annotation().
exon_level	An optional character vector specifying the lesion types that should use exon-level target sizes in downstream GRIN probability calculations. Lesions belonging to these types must be restricted to exonic regions before analysis. For example, when mutations are specified for exon-level analysis, exonic variants such as missense, nonsense, frameshift, and synonymous mutations may be included, whereas intronic and other non-coding mutations should be excluded before running the analysis. The default is NULL.
mess.freq	Integer specifying the frequency of progress messages. The default is 10.

Details

The function first orders and indexes the lesion data by lesion type, chromosome, and subject and orders the gene annotation by chromosome and genomic position. Gene and lesion boundaries are then combined into a unified genomic position table.

The cty column in the combined table identifies the boundary represented by each row:

1

Gene start.

2

Lesion start.

3

Lesion end.

4

Gene end.

The resulting table and index objects are used by find.gene.lsn.overlaps() to identify gene-lesion overlaps.

When exon_level is specified, exon lengths are calculated from exons.annotation and summed to determine the exon target size for each matched gene. Chromosome-level exon target sizes are not calculated by this function and must instead be supplied through exon.chrom.size. exons.annotation may contain all genes in gene.data or only a subset. Genes without matching exon annotations remain available for lesion types analyzed using standard genomic coordinates, but their gene-level exon target sizes are recorded as missing and exon-level probabilities are not computed for those genes.

Gene-lesion overlaps continue to be determined using the complete genomic coordinates of each gene, including when exon_level is specified. Exon annotation is used only to calculate exon-based target sizes for downstream probability calculations. Therefore, lesion types specified in exon_level must contain only exonic lesions; non-exonic lesions must be removed by the user before running the analysis.

Lesion types not included in exon_level continue to use the standard chromosome-level GRIN workflow.

Exact duplicate exon records are removed before gene-level exon sizes are calculated. Incomplete or malformed exon records are excluded with a warning.

Value

A list with the following components:

lsn.data

Processed lesion data, including indices identifying the range of rows in gene.lsn.data corresponding to each lesion.

gene.data

Processed gene annotation data, including indices identifying the range of rows in gene.lsn.data corresponding to each gene.

gene.lsn.data

Combined and ordered data.frame of gene and lesion positions. The cty column encodes the position type: 1 = gene start, 2 = lesion start, 3 = lesion end, and 4 = gene end.

gene.index

Index data.frame indicating the ordered start and end rows for each chromosome in the gene data.

lsn.index

Index data.frame indicating the ordered start and end rows for lesion groups defined by lesion type, chromosome, and subject.

gene.exon.size

Numeric vector containing the total annotated exon target size for each gene, aligned by gene.row. Genes without a valid matching exon annotation receive NA and are excluded from probability calculations for lesion types specified in exon_level. Returned as NULL when exon_level = NULL.

exon.chrom.size

A data.frame containing chromosome identifiers in the chrom column and total genome-wide annotated exon target sizes in the size column. Returned as NULL when exon_level = NULL.

exon_level

The character vector of lesion types designated for exon-level analysis. Returns NULL when exon-level preprocessing is not requested.

Author(s)

Abdelrahman Elsayed [e-mail] and Stanley Pounds [e-mail]

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.

See Also

order.index.gene.data, order.index.lsn.data, find.gene.lsn.overlaps

Examples

data(lesion_data)
data(hg38_gene_annotation)
data(example_exon_annotation)
data(hg38_exon_chrom_size)

# Prepare gene and lesion data using the optional arguments
# for exon-level analysis
prep.gene.lsn <- prep.gene.lsn.data(
  lsn.data = lesion_data,
  gene.data = hg38_gene_annotation,
  exons.annotation = example_exon_annotation,
  exon.chrom.size = hg38_exon_chrom_size,
  exon_level = "mutation"
)

GRIN2 documentation built on Aug. 22, 2026, 5:09 p.m.