---
title: "GENCODE AnnotationHub"
author: "Paul Ruiz Pinto"
date: "`r BiocStyle::doc_date()`"
output:
  BiocStyle::html_document:
    toc: true
    toc_float: true
vignette: >
  %\VignetteIndexEntry{GENCODE v50 annotation through AnnotationHub}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>"
)
```

# Introduction

`GENCODEHub` provides stable AnnotationHub access to annotation resources
derived from GENCODE human release 50 for GRCh38.p14 and Ensembl release 116.
The collection is useful when an analysis needs the original GTF attributes in
feature-specific `GRanges` objects or gene--transcript structure in a `TxDb`.
It complements general Ensembl and UCSC annotation clients by distributing a
fixed, documented GENCODE release with persistent AnnotationHub identifiers.

The collection contains a `GRanges` with every imported GTF row, separate
`GRanges` objects for each GTF feature type, and a `TxDb` database. The files
are hosted in
[Zenodo record 21784647](https://doi.org/10.5281/zenodo.21784647) and are
downloaded only when selected through AnnotationHub.

# Installation

Install `GENCODEHub` from Bioconductor with the version of R associated with
the current Bioconductor release.

```{r installation, eval=FALSE}
if (!requireNamespace("BiocManager", quietly = TRUE)) {
    install.packages("BiocManager")
}
BiocManager::install("GENCODEHub")
```

# Available resources

| Resource | AH ID | Contents | Class | Download |
|---|---|---|---|---:|
| `annotation` | `AH122277` | every imported GTF row | `GRanges` | 34.8 MB |
| `gene` | `AH122278` | gene features and attributes | `GRanges` | 1.3 MB |
| `transcript` | `AH122279` | transcript data | `GRanges` | 8.5 MB |
| `exon` | `AH122280` | exon features and attributes | `GRanges` | 22.4 MB |
| `CDS` | `AH122281` | CDS features and phase | `GRanges` | 11.6 MB |
| `UTR` | `AH122282` | untranslated-region features | `GRanges` | 10.2 MB |
| `start_codon` | `AH122283` | start-codon features | `GRanges` | 4.2 MB |
| `stop_codon` | `AH122284` | stop-codon features | `GRanges` | 4.7 MB |
| `Selenocysteine` | `AH122285` | selenocysteine features | `GRanges` | 4 KB |
| `TxDb` | `AH122286` | gene/transcript/exon/CDS relations | `TxDb` | 344.2 MB |

The feature-specific `GRanges` resources retain the original `type` and all
metadata columns imported from the GTF. The `TxDb` supports structural queries
but does not retain every GTF attribute.

# Discover resources

Create one AnnotationHub connection and reuse it throughout the session.
Subsetting a hub lists metadata; double-bracket extraction downloads and loads
one selected resource.

```{r create-hub}
library(AnnotationHub)
library(GENCODEHub)

hub <- AnnotationHub(ask = FALSE)
resources <- gencodeV50Resources(hub)
resources
```

`gencodeResources()` queries all records associated with `GENCODEHub`, while
`gencodeV50Resources()` returns the ten release 50 records in AH-ID order.
Detailed production status and file sizes are available without downloading
the resource files.

```{r resource-information}
getInfoOnIds(hub, names(resources))
```

# Retrieve a selected resource

The standard AnnotationHub interface and the package helper are equivalent.
The small selenocysteine resource is used here so that the vignette exercises
the production download and dispatch path without a large transfer.

```{r retrieve-selenocysteine}
selenocysteine <- hub[["AH122285"]]
selenocysteine_from_helper <- gencodeV50("Selenocysteine", hub)
stopifnot(identical(selenocysteine, selenocysteine_from_helper))
selenocysteine
```

The gene resource is suitable for gene-body overlap and gene-level
transcription start site annotation.

```{r retrieve-genes}
genes <- gencodeV50("gene", hub)
genes
```

# Identifiers, coordinates, and sequence information

Identifiers are retained as supplied by GENCODE, including version suffixes.

```{r inspect-gene-attributes}
head(S4Vectors::mcols(genes)[, c("gene_id", "gene_name", "gene_type")])
GenomeInfoDb::seqinfo(genes)
```

The ranges use one-based, closed coordinates and GENCODE chromosome names
(`chr1` through `chr22`, `chrX`, `chrY`, and `chrM`). The genome identifier is
`GRCh38`; the assembly provenance `GRCh38.p14` is recorded in the objects and
AnnotationHub metadata. The source GTF does not provide chromosome lengths, so
`seqlengths()` are `NA`. The imported `GRanges` objects do not set `chrM`
circularity; the `TxDb` records `chrM` as circular.

# Derive transcription start sites

Gene and transcript resources contain the original source ranges. A
strand-aware, one-base transcription start site can be derived without fixing
a promoter width in the distributed annotation.

```{r derive-tss}
gene_tss <- GenomicRanges::resize(
    genes,
    width = 1L,
    fix = "start"
)
gene_tss
```

# TxDb structural annotation

The TxDb record is substantially larger than the feature-specific resources.
Its metadata can be inspected without downloading the 344 MB SQLite file.

```{r txdb-information}
getInfoOnIds(hub, "AH122286")
```

Load it when transcript, exon, and coding-sequence relationships are required.
This deliberately unevaluated example avoids downloading the large database
during every vignette build; the evaluated examples above exercise the same
AnnotationHub download and cache mechanism.

```{r retrieve-txdb, eval=FALSE}
txdb <- hub[["AH122286"]]
txdb <- gencodeV50("TxDb", hub)
GenomicFeatures::transcripts(txdb)
```

# Provenance and citation

The resources were generated from the official GENCODE release 50
comprehensive gene annotation on the reference chromosomes:

```text
https://ftp.ebi.ac.uk/pub/databases/gencode/Gencode_human/
release_50/gencode.v50.annotation.gtf.gz
```

The source checksum, transformation procedure, resource counts, build session,
and resource checksums are recorded in the Zenodo deposit and in
`inst/scripts/make-data.R`. For reproducible analyses, record the GENCODE
release, genome assembly, AH ID, `snapshotDate(hub)`, package version, and
Zenodo DOI. Cite the applicable publication listed on the
[GENCODE project website](https://www.gencodegenes.org/pages/publications.html),
the Zenodo record, and `GENCODEHub`.

```{r reproducibility-record}
snapshotDate(hub)
packageVersion("GENCODEHub")
```

# Session information

```{r session-information}
sessionInfo()
```