prob.hits: Find Probability of Locus Hit

In GRIN2: Genomic Random Interval (GRIN)

Find Probability of Locus Hit

Description

Computes the probability that each genomic locus, such as a gene or regulatory region, is affected by one or more types of genomic lesions. Statistical significance for lesion enrichment is estimated using a convolution of independent but non-identically distributed Bernoulli probabilities.

Usage

prob.hits(hit.cnt, chr.size = NULL)

Arguments

hit.cnt	A list returned by count.hits() containing the number of subjects and lesions affecting each locus by lesion type, together with the processed lesion and gene annotations. When exon-level analysis was requested in prep.gene.lsn.data(), this object also contains the gene- and chromosome-level exon target sizes and the lesion types designated for exon-level analysis.
chr.size	A data.frame containing chromosome sizes for the 22 autosomes and the X and Y chromosomes. It must contain the following columns: chrom Chromosome identifier. size Chromosome length in base pairs.

Details

For each lesion type and chromosome, the function calculates the probability that each lesion overlaps each affected locus according to the relative sizes of the lesion, locus, and chromosome. These probabilities are combined across lesions and subjects using the Poisson-binomial distribution to estimate the probability of observing the recorded number of lesions or affected subjects by chance.

For lesion types not designated for exon-level analysis, locus size is calculated using the complete genomic boundaries in gene.data, and chromosome length is obtained from chr.size.

For lesion types designated for exon-level analysis, the function instead uses the total annotated exon size of each gene and the total annotated exon target size of the corresponding chromosome. Lesion types specified in exon_level must therefore contain only exonic lesions. For example, when mutations are analyzed at the exon level, 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 exon-level specification and target sizes are carried through the GRIN workflow within hit.cnt; users therefore specify the exon-level lesion types only once when calling prep.gene.lsn.data().

Genes without a valid matching exon annotation remain in analyses of lesion types that use standard genomic coordinates. For lesion types designated for exon-level analysis, their lesion-specific p-values and q-values are returned as NA. Ordered constellation statistics are also returned as NA for genes that do not have a complete set of lesion-specific probabilities.

The function calculates lesion-specific p-values for:

Number of affected subjects

The probability of observing the recorded number of unique subjects with at least one lesion affecting the locus.

Number of lesion hits

The probability of observing the recorded total number of lesions affecting the locus.

False discovery rate-adjusted q-values are calculated using the method of Pounds and Cheng. When more than one lesion type is present, the function also calculates ordered p- and q-values representing constellations of one or more lesion types affecting the same locus.

Value

A list containing the following components:

gene.hits

A data.frame containing locus annotations; the numbers of lesion hits and affected subjects by lesion type; lesion-specific p-values and q-values for hit counts (⁠p.nhit.*⁠ and ⁠q.nhit.*⁠) and affected-subject counts (⁠p.nsubj.*⁠ and ⁠q.nsubj.*⁠); and, when multiple lesion types are present, ordered constellation p-values and q-values (p1.nhit, p2.nhit, ..., q1.nhit, q2.nhit, ... and the corresponding nsubj columns).

lsn.data

Processed input lesion data.

gene.data

Processed input gene annotation data.

gene.lsn.data

A data.frame in which each row represents a locus overlapped by a genomic lesion.

chr.size

Chromosome size information used for standard chromosome-level calculations.

gene.index

A data.frame indexing loci by chromosome.

lsn.index

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

gene.exon.size

A numeric vector containing the exon target size for each gene. Genes without a valid matching exon annotation have a value of NA; exon-level probability calculations are not performed for those genes. Returns NULL when exon-level analysis was not requested.

exon.chrom.size

A data.frame containing the genome-wide annotated exon target size for each chromosome. These values provide the chromosome-level exonic search space used for lesion types designated for exon-level analysis. Returns NULL when exon-level analysis was not requested.

exon_level

A character vector specifying the lesion types evaluated 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

Examples

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

# 1) 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"
)

# 2) Identify overlapping gene-lesion events
gene.lsn.overlap <- find.gene.lsn.overlaps(prep.gene.lsn)

# 3) Count subjects and lesions affecting each gene
count.nsubj.nhits <- count.hits(gene.lsn.overlap)

# 4) Compute p- and q-values for lesion enrichment
hits.prob <- prob.hits(count.nsubj.nhits, hg38_chrom_size)

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