count.hits: Count Gene-Lesion Hits

In GRIN2: Genomic Random Interval (GRIN)

Count Gene-Lesion Hits

Description

Computes the number of genomic lesions affecting each gene by lesion type and the number of unique subjects whose lesions overlap each gene for each lesion type.

Usage

count.hits(ov.data)

Arguments

ov.data

A list returned by find.gene.lsn.overlaps() containing gene-lesion overlap data, processed gene and lesion annotations, and supporting index objects. When exon-level analysis was requested, the list also contains gene- and chromosome-level exon target sizes and the lesion types designated for exon-level analysis.

Details

This function summarizes the output of find.gene.lsn.overlaps() by generating two matrices:

nhit.mtx

The total number of overlapping lesions affecting each gene, categorized by lesion type. Multiple lesions of the same type in the same subject are counted separately.

nsubj.mtx

The number of unique subjects with at least one overlapping lesion affecting each gene, categorized by lesion type. Multiple lesions of the same type affecting the same gene in one subject are counted once.

For example, if three separate mutations from the same subject overlap NOTCH1, all three lesions are counted in nhit.mtx, whereas that subject is counted once in nsubj.mtx.

Exon-level target sizes do not alter the hit or affected-subject counts. Gene-lesion overlaps are counted using the standard genomic coordinates of each gene, including for lesion types specified in exon_level. The gene-level exon target sizes, chromosome-level exon target sizes, and exon-level lesion-type specification are retained in the returned list for downstream GRIN probability calculations.

All genes represented in gene.data remain included in nhit.mtx and nsubj.mtx, regardless of whether they have a valid matching exon annotation. Genes without valid exon target sizes remain available for standard GRIN analyses but do not receive exon-level probability estimates for lesion types specified in exon_level.

Value

A list containing the following components:

lsn.data

Processed lesion data.

lsn.index

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

gene.data

Processed gene annotation data.

gene.index

A data.frame indexing genes by chromosome.

nhit.mtx

A numeric matrix in which rows correspond to genes and columns correspond to lesion types. Each value is the number of lesions of the specified type affecting the gene.

nsubj.mtx

A numeric matrix with the same dimensions as nhit.mtx. Each value is the number of unique subjects with at least one lesion of the specified type affecting the gene.

gene.lsn.data

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

glp.data

The combined gene and lesion position table. The cty column identifies the boundary type: 1 = gene start, 2 = lesion start, 3 = lesion end, and 4 = gene end.

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 have a value of NA. These genes remain included in the hit and affected-subject counts and in standard GRIN analyses, but exon-level probability calculations are not performed for lesion types specified in exon_level. 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. This object is retained for use in downstream exon-level probability calculations. Returns NULL when exon-level analysis was not requested.

exon_level

Character vector specifying the lesion types designated for exon-level analysis. 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.

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, prob.hits

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

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

# Count lesions and affected subjects for each gene and lesion type
count.nsubj.nhits <- count.hits(gene.lsn.overlap)

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