get.ensembl.annotation: Retrieve Ensembl Annotation Data

In GRIN2: Genomic Random Interval (GRIN)

Retrieve Ensembl Annotation Data

Description

Retrieves pre-generated and versioned Ensembl annotation resources for use with GRIN2. Annotation files are downloaded from the GRIN2 annotation repository, verified using MD5 checksums, and cached locally by default for subsequent analyses.

Usage

get.ensembl.annotation(
  genome.assembly = "Human_GRCh38",
  ensembl.version = 110L,
  annotation.type = c("gene", "exon", "regulatory", "all"),
  cache = TRUE,
  cache.dir = NULL,
  force.download = FALSE,
  quiet = FALSE
)

Arguments

genome.assembly	Character string specifying the genome assembly. Currently supported: "Human_GRCh38".
ensembl.version	Integer specifying the Ensembl release. Currently supported: 110.
annotation.type	Character string specifying the annotation resource to retrieve. One of "gene", "exon", "regulatory", or "all". Specifying "all" retrieves all three annotation resources.
cache	Logical indicating whether downloaded annotation files should be cached locally. Default is TRUE. Cached files are verified against their expected MD5 checksums before use.
cache.dir	Optional character string specifying the directory in which annotation files should be cached. If NULL, the standard GRIN2 user cache directory is used.
force.download	Logical indicating whether annotation files should be downloaded again even when valid cached copies are available. Default is FALSE.
quiet	Logical indicating whether download and status messages should be suppressed. Default is FALSE.

Details

GRIN2 uses pre-generated, versioned annotation resources to provide reproducible genomic analyses without requiring a live connection to Ensembl BioMart during annotation retrieval. This function downloads resources from the GRIN2 annotation repository when a valid cached copy is unavailable, when force.download = TRUE, or when a cached file fails checksum verification. Internet access is therefore required for the initial download. Once a valid resource has been cached, it can be reused without an internet connection.

The available annotation resources include:

Gene annotation

Gene-level annotation based on the specified Ensembl release. The resource includes protein-coding genes as well as non-coding gene biotypes, including long non-coding RNAs (lncRNAs), microRNAs (miRNAs), small nuclear RNAs (snRNAs), small nucleolar RNAs (snoRNAs), pseudogenes, and other annotated gene types. Each gene is represented by its Ensembl gene identifier and genomic interval, together with gene name, biotype, strand, chromosome band, and gene description where available. The columns gene, chrom, loc.start, and loc.end provide the genomic interval required by GRIN2.

Exon annotation

The exon annotation represents one selected transcript per gene. For protein-coding genes, the MANE Select transcript is used when available. MANE (Matched Annotation from NCBI and EMBL-EBI) Select identifies a representative transcript with matching exon structure and sequence between Ensembl/GENCODE and RefSeq. For genes without a selected MANE transcript, including non-coding genes, the Ensembl Canonical transcript is used as the representative transcript. The Ensembl Canonical transcript is the representative transcript designated by Ensembl for a gene.

This resource is used primarily for exon-level GRIN2 analyses, in which selected lesion types, such as mutations and indels, can be evaluated using exon-based rather than whole-gene target sizes when the analysis is restricted to protein-altering alterations. It can be supplied to grin.stats through the exons.annotation, exon.chrom.size, and exon_level arguments.

This resource is used primarily for exon-level GRIN2 analyses, in which selected lesion types are evaluated using exon-based rather than whole-gene target sizes. It can be supplied together with chromosome-level exon target sizes through the exons.annotation, exon.chrom.size, and exon_level arguments used in the GRIN2 analysis workflow.

The resource contains the individual exons belonging to the selected transcript for each gene and includes exon genomic start and end coordinates, exon number, Ensembl exon identifier, transcript identifier, transcript biotype, transcript start and end coordinates, canonical-transcript status, MANE Select status, and gene-level annotation including gene name, gene boundaries, gene biotype, description, strand, and chromosome band. In this resource, loc.start and loc.end specifically represent the genomic start and end coordinates of each exon.

Regulatory annotation

Regulatory annotation based on the Ensembl Regulatory Build. The current GRCh38/Ensembl 110 resource contains predicted enhancer regions, predicted promoter regions, CTCF-binding sites, and open chromatin regions, together with gene intervals used to establish relationships between regulatory elements and nearby genes.

Regulatory features are additionally annotated with genes whose genomic intervals overlap the regulatory feature, the nearest upstream and downstream genes, their Ensembl gene identifiers, and the genomic distance between each regulatory feature and the corresponding nearest gene. The resource also reports genes located within 500 kb upstream and within 500 kb downstream of each regulatory feature. These fields facilitate interpretation of regulatory regions that may influence nearby genes even when the regulatory element does not directly overlap a gene.

Annotation resources are downloaded only when required. When cache = TRUE, a successfully downloaded and checksum-verified file is stored in the GRIN2 user cache and reused in subsequent calls. Annotation files are verified against their expected checksums before use. If a cached file fails checksum verification, a fresh copy is downloaded and verified. A newly downloaded file that does not match the expected checksum is rejected and the function returns an error.

Value

If annotation.type is "gene", "exon", or "regulatory", the corresponding annotation data frame is returned. If annotation.type = "all", a named list with elements gene, exon, and regulatory is returned.

Examples

## Not run: 
# Requires internet access if a valid cached copy is unavailable.
gene.annotation <- get.ensembl.annotation(
  genome.assembly = "Human_GRCh38",
  ensembl.version = 110,
  annotation.type = "gene"
)

head(gene.annotation)

## End(Not run)

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