---
title: "Transcript Annotation Database for *Oryza sativa*"
author: "Kabilan S"
date: "2026-08-10"
output: BiocStyle::html_document
vignette: >
  %\VignetteIndexEntry{Transcript Annotation Database for Oryza sativa}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# Introduction

**TxDb.Osativa.MSU.RGAP7** is a Bioconductor-compatible transcript annotation
package for *Oryza sativa* generated from the official **Rice Genome Annotation
Project (RGAP) Release 7** GFF3 annotation based on the **IRGSP-1.0** reference
genome (also known as MSU7).

The package provides genomic coordinates and transcript models, including genes,
transcripts, exons, coding sequences (CDS), and promoter regions. It is intended
for downstream genomic analyses using Bioconductor packages such as
**GenomicFeatures**, **GenomicRanges**, **Signac**, **ArchR**, and **ChIPseeker**.

The TxDb object is retrieved from **AnnotationHub** using its corresponding
AnnotationHub record.

# Installation

Install the package and its dependencies from Bioconductor with:

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

BiocManager::install(c(
    "TxDb.Osativa.MSU.RGAP7",
    "AnnotationHub",
    "GenomicFeatures",
    "GenomicRanges"
))
```

# Loading packages

```{r loading, message=FALSE, warning=FALSE}
library(TxDb.Osativa.MSU.RGAP7)
library(AnnotationHub)
library(GenomicFeatures)
library(GenomicRanges)
```

# Retrieve the TxDb object from AnnotationHub

The TxDb object is available through `AnnotationHub`:

```{r annotationhub, message=FALSE, warning=FALSE}
ah <- AnnotationHub::AnnotationHub()
TxDb.Osativa.MSU.RGAP7 <- ah[["AH122276"]]
```

Check the class of the retrieved object:

```{r class}
class(TxDb.Osativa.MSU.RGAP7)
```

# TxDb file summary

Display the transcript database:

```{r summary}
TxDb.Osativa.MSU.RGAP7
```

A summary can also be obtained with:

```{r summary-function}
summary(TxDb.Osativa.MSU.RGAP7)
```

# Chromosome information

The chromosome and sequence information can be examined with `seqinfo()`:

```{r chromosome}
seqinfo(TxDb.Osativa.MSU.RGAP7)
```

# Available chromosomes

The available sequence levels can be obtained with:

```{r avl-chromosomes}
seqlevels(TxDb.Osativa.MSU.RGAP7)
```

The 12 nuclear chromosomes of the IRGSP-1.0 / MSU7 assembly contain the vast
majority of annotated genes.

`ChrUn` represents unanchored contigs, that is, sequences that could not be
placed on a chromosome.

`ChrSy` represents the Syngenta pseudomolecule, a separate assembly containing
additional sequence not present in the main IRGSP-1.0 build.

# Gene annotations

Retrieve all annotated genes:

```{r gene-annotations}
gene_annotations <- genes(TxDb.Osativa.MSU.RGAP7)
gene_annotations
```

# Transcript annotations

Retrieve transcript annotations:

```{r transcript-annotations}
transcript_annotations <- transcripts(TxDb.Osativa.MSU.RGAP7)
head(transcript_annotations)
```

# Exon annotations

Retrieve exon annotations:

```{r exon-annotations}
exon_annotations <- exons(TxDb.Osativa.MSU.RGAP7)
head(exon_annotations)
```

# Coding sequence (CDS) annotations

Retrieve coding sequence annotations:

```{r cds}
cds_annotations <- cds(TxDb.Osativa.MSU.RGAP7)
head(cds_annotations)
```

# Promoter regions

Extract promoter regions 2 kb upstream and 200 bp downstream of transcription
start sites:

```{r promoters}
promoter_annotations <- promoters(
    TxDb.Osativa.MSU.RGAP7,
    upstream = 2000,
    downstream = 200
)
head(promoter_annotations)
```

# Transcripts grouped by gene

Transcripts can be grouped by gene using `transcriptsBy()`:

```{r transcripts-by-gene}
tx_by_gene <- GenomicFeatures::transcriptsBy(
    TxDb.Osativa.MSU.RGAP7,
    by = "gene"
)
tx_by_gene
```

# Exons grouped by transcript

Exons can be grouped by transcript using `exonsBy()`:

```{r exons-by-transcript}
exons_by_transcript <- GenomicFeatures::exonsBy(
    TxDb.Osativa.MSU.RGAP7,
    by = "tx"
)
exons_by_transcript
```

# Converting MSU identifiers to RAP-DB identifiers

Gene models in this database are keyed by MSU locus identifiers
(`LOC_Os##g#####`). Many rice resources instead use RAP-DB identifiers
(`Os##g#######`). The `msu_to_rap()` function translates between the two,
preserving input order and dropping identifiers that cannot be converted.

```{r msu-to-rap}
if (requireNamespace("riceidconverter", quietly = TRUE)) {
    library(riceidconverter)

    msu_ids <- c(
        "LOC_Os01g01010",
        "LOC_Os01g01019",
        "LOC_Os01g01040"
    )

    rap_ids <- msu_to_rap(msu_ids)
    print(rap_ids)
}
```

# Session information

```{r sessioninfo}
sessionInfo()
```