grin.stats: Execute the GRIN Statistical Framework

In GRIN2: Genomic Random Interval (GRIN)

Execute the GRIN Statistical Framework

Description

Executes the Genomic Random Interval (GRIN) statistical framework to determine whether genomic loci, such as genes or regulatory regions, are affected by genomic lesions more frequently than expected by chance. The function evaluates the enrichment of individual lesion types and, when multiple lesion types are present, constellations of complementary lesion types affecting the same locus.

By default, GRIN models each lesion type using the complete genomic interval of each locus and the complete size of the corresponding chromosome. Optionally, selected lesion types can be evaluated using exon-level gene and chromosome target sizes when the analysis is restricted to exonic lesions.

Usage

grin.stats(
  lsn.data,
  gene.data,
  chr.size,
  exons.annotation = NULL,
  exon.chrom.size = NULL,
  exon_level = NULL
)

Arguments

lsn.data	A data.frame containing genomic lesion data in GRIN-compatible format. The following five columns are required: ID Sample, subject, or patient identifier. chrom Chromosome on which the lesion is located. loc.start Genomic start coordinate of the lesion in base pairs. loc.end Genomic end coordinate of the lesion in base pairs. lsn.type Lesion category, such as mutation, breakpoint, gain, amplification, or deletion. For single nucleotide variants, loc.start and loc.end should generally be identical. Copy-number alterations should be represented by their genomic boundaries, whereas structural rearrangements should generally be represented by separate rows for their individual breakpoints.
gene.data	A data.frame containing the genomic annotation for the loci to be analyzed. The following four columns are required: gene Gene or locus identifier, typically an Ensembl gene identifier. chrom Chromosome on which the locus is located. loc.start Genomic start coordinate of the locus in base pairs. loc.end Genomic end coordinate of the locus in base pairs. The rows in gene.data define the locus universe analyzed by GRIN.
chr.size	A data.frame containing complete chromosome lengths used for lesion types evaluated with the standard GRIN model. It must contain chrom, the chromosome identifier, and size, the chromosome length in base pairs. Chromosome identifiers must be represented consistently across the input datasets.
exons.annotation	An optional data.frame containing exon coordinates used to calculate gene-level exon target sizes. This argument is required when exon_level is specified. Exons should be provided from one representative transcript per gene to avoid counting alternative exons from multiple transcripts more than once. We recommend using the MANE Select transcript for protein-coding genes and the Ensembl canonical transcript for non-protein-coding genes. Compatible exon annotation data for supported genome assemblies can be obtained using get.ensembl.annotation. The following columns are required: gene Gene identifier matching the identifier system used in gene.data. Multiple rows may represent different exons of the same gene. chrom Chromosome on which the exon is located. loc.start Exon start coordinate in base pairs. loc.end Exon end coordinate in base pairs. When a user-provided exons.annotation is used, a valid matching exon annotation must be provided for every gene in gene.data. Genes without a valid matching exon annotation remain available for standard GRIN analyses, but exon-level probabilities are not calculated for those genes.
exon.chrom.size	An optional data.frame containing the genome-wide exon target size for each chromosome. This argument is required when exon_level is specified and must contain chrom and size. A pre-generated dataset for GRCh38 is provided with the package as hg38_exon_chrom_size and can be loaded using data(hg38_exon_chrom_size). These chromosome-level target sizes should be derived using the same genome assembly and representative-transcript selection procedure as exons.annotation.
exon_level	An optional character vector specifying lesion types that should be modeled using exon-level gene and chromosome target sizes. Each value must exactly match a category in lsn.data$lsn.type. Lesions belonging to these types must be restricted to exonic regions before running GRIN. 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 analysis. Lesion types not included in exon_level use the standard GRIN model. The default is NULL.

Details

GRIN uses a null probability model in which each lesion is assumed to occur uniformly along the chromosome on which it was observed. Under this model, the overlap of each lesion with a locus of interest is an independent Bernoulli trial with success probability proportional to the sum of the lengths of the lesion and the locus and inversely proportional to the chromosome length.

For each subject, the probabilities of all lesions belonging to that subject are combined to calculate the probability that at least one of the subject's lesions affects the locus.These subject-specific probabilities are convolved across subjects to obtain the null probability distribution for the number of subjects with at least one lesion affecting the locus. Statistical significance is determined by comparing the observed number of affected subjects with this null distribution. GRIN also evaluates the significance of the observed total number of lesion hits. P-values are adjusted for multiple testing using the Benjamini-Hochberg false discovery rate procedure together with the Pounds and Cheng estimator of the proportion of true null hypotheses, pi.hat = min(1, 2 * mean(p)).

The genomic target space depends on the lesion type. For lesion types not specified in exon_level, GRIN uses the complete locus interval from gene.data and complete chromosome length from chr.size. For lesion types specified in exon_level, GRIN instead uses the summed exon length of each gene from exons.annotation and the genome-wide exon target size of the chromosome from exon.chrom.size. This provides an exon-specific target space for analyses restricted to exonic variants.

When multiple lesion types are present, GRIN additionally calculates ordered constellation p-values and q-values to evaluate evidence that a locus is affected by one, two, or more complementary lesion types.

Value

A list containing the following components:

gene.hits

A data.frame containing one row per gene or locus, including lesion-hit counts (nhit.*), affected-subject counts (nsubj.*), and their corresponding lesion-specific p-values and q-values (p.nhit.*, q.nhit.*, p.nsubj.*, and q.nsubj.*). When multiple lesion types are present, ordered constellation p-values and q-values (p1.*, p2.*, ..., q1.*, q2.*, ...) are also returned.

lsn.data

Input lesion data with the internal lsn.row index added.

gene.data

Input gene or locus annotation data with the internal gene.row index added.

gene.lsn.data

A data.frame containing detected gene-lesion overlaps and their corresponding gene, lesion, and subject information.

chr.size

Chromosome-size reference used for standard GRIN calculations.

gene.index

A data.frame indexing genes or loci by chromosome.

lsn.index

A data.frame indexing lesion groups by lesion type, chromosome, and subject.

gene.exon.size

Numeric vector containing gene-level exon target sizes. Returns NULL when exon-level analysis was not requested.

exon.chrom.size

A data.frame containing chromosome-level exon target sizes. Returns NULL when exon-level analysis was not requested.

exon_level

Character vector identifying lesion types modeled using exon-level target sizes. Returns NULL when exon-level analysis was 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.

Pounds, S., and Cheng, C. (2006). Robust estimation of the false discovery rate.

Cao, X., Elsayed, A. H., & Pounds, S. B. (2023). Statistical Methods Inspired by Challenges in Pediatric Cancer Multi-omics.

See Also

prep.gene.lsn.data, find.gene.lsn.overlaps, count.hits, prob.hits, get.ensembl.annotation

Examples

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

# Example 1: Run GRIN using standard gene and chromosome target sizes
grin.results <- grin.stats(
  lsn.data = lesion_data,
  gene.data = hg38_gene_annotation,
  chr.size = hg38_chrom_size
)

# Example 2: Model mutations using exon-level target sizes
grin.exon.results <- grin.stats(
  lsn.data = lesion_data,
  gene.data = hg38_gene_annotation,
  chr.size = hg38_chrom_size,
  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.