%\VignetteIndexEntry{Introduction}
%\VignettePackage{refGenome}
\documentclass[a4paper]{article}

\usepackage{hyperref}
\usepackage[utf8]{inputenc}

% Imported from Biobase package:
\newcommand{\R}{{\textsf{R}}}
\newcommand{\code}[1]{{\texttt{#1}}}
\newcommand{\term}[1]{{\emph{#1}}}
\newcommand{\Rpackage}[1]{\textsf{#1}}
\newcommand{\Rfunction}[1]{\texttt{#1}}
\newcommand{\Robject}[1]{\texttt{#1}}
\newcommand{\Rclass}[1]{{\textit{#1}}}
\newcommand{\Rmethod}[1]{{\textit{#1}}}
\newcommand{\Rfunarg}[1]{{\textit{#1}}}


\newcommand{\rtx}[1]{{\textsf{#1}}}
\newcommand{\rcl}[1]{{\texttt{#1}}}
\newcommand{\rfc}[1]{{\texttt{#1}}}
\newcommand{\robj}[1]{{\texttt{#1}}}

\title{Using refGenome package}
\author{Wolfgang Kaisers, CBiBs HHU Dusseldorf}
\date{\today}

\setlength\parindent{0pt} % \noindent for each paragraph

\begin{document}
\maketitle
\SweaveOpts{concordance=TRUE}


<<echo=FALSE>>=
options(width=60)
@


%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\section{\rcl{refGenome} package}

The \rcl{refGenome} package provides functionality for managing of genome
annotation data, especially for Ensembl and UCSC data.


%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%

\section{Object types inside refGenome package}

The central classes inside this package are \rcl{refGenome} derived (S4)
classes.
The class contains two slots: ev (\rcl{environment}) and basedir
(\rcl{character}).
All annotation data is kept in data.frames inside the \robj{ev} slot.
Saving and loading \rcl{refGenome} derived objects works on the complete
content of the environment.
This mechanism also avoids generation of copies and allows addition of
new data inside of member functions. The basedir slot keeps a path on a
hard-disc which is intended as location where data files and object
versions can be kept.\\

The package contains three derived class lineages \rcl{refGenome},
\rcl{refExons} and \rcl{refJunctions}.
For each lineage there are classes for Ensembl and UCSC defined,
e.g. \rcl{ensemblGenome} and \rcl{ucscGenome}.
The exon classes focus on annotated exon positions and the junction classes
focus on adjacent exons.\\

%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\subsection{Creation of empty refGenome objects}

Empty objects of \rcl{refGenome} derived classes can be created with
\rfc{ensembleGenome()} or \rfc{ucscGenome()}.
After creation of an empty object the first step usually is to set the basedir
address:
<<>>=
library(refGenome)
beg <- ensemblGenome()
basedir(beg) <- system.file("extdata", package="refGenome")
@

The "basedir" folder is intended to contain all data which is associated with
the current annotation set, e.g. downloaded gtf files, saved object data,
saved SQLite versions of the data and potenially  sequence information.
In order to fill an empty object, annotation data has to be imported from
external files.

%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\subsection{Importing annotation data}

The basic importing mechanism for \rcl{refGenome} objects is to import a
"gtf" file.
Therefore, the "gtf" files have to be downloaded.
The download source and mechanism is explained for \rcl{ensemblGenome} and
\rcl{ucscGenome} separately.
There are specialized mechanisms in order to provide additional information
either from within the gtf file (ensembl) or via other external files (ucsc).

%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\subsection{Saving and loading data}

The data content of \rcl{refGenome} objects can be saved and re-loaded in
several ways.
One way is the \rfc{saveGenome} method where the content is written into a
compressed ".RData" file.
One alternative is to write the content into a SQLite database via
\rfc{writeDB}.


%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\section{Ensembl Genomes}

The \rcl{ensemblGenome} class is specialized for managing annotation data
for ensemble Genomes.

%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\subsection{Download and import data}

For ensemblGenome objects, gtf files can be downloaded from Ensemble servers.
Therefore, go to\\
\newline
\url{http://www.ensembl.org/info/data/ftp/index.html}\\
\newline
and choose a file from the "Gene sets" column.
They are labeled "GTF".
For example Version 62 of human genomic annotation can be downloaded from\\
\newline
\url{ftp://ftp.ensembl.org/pub/release-80/gtf/homo_sapiens/Homo_sapiens.GRCh38.80.gtf.gz}\\
\newline
A copy of the obtained file should then be placed in the the "basedir"
directory. With the appropriate setting of basedir,
annotation data can be imported with:
<<echo=TRUE>>=
ens_gtf <- "hs.ensembl.62.small.gtf"
read.gtf(beg, ens_gtf)
beg
@
The top lines of the contained table are shown when the object is printed.


%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\section{UCSC Genomes}

Downloading of annotation data for UCSC genomes is a bit more complicated
than for Ensemble Genomes because additional data must be downloaded in
separate files.
The Homepage for UCSC browser can be found under:\\
%
\newline
\url{http://genome.ucsc.edu/}\\
\newline
%
In order to import UCSC annotation data into \rcl{refGenome} objects files
containing the data have to be downloaded from the USCS Table Browser which
can be found under:\\
%
\newline
\url{http://genome.ucsc.edu/cgi-bin/hgTables}\\
\newline
%
or by following the "Table Browser" link in the left panel on the homepage.
On the Table Browser:\\
%
\begin{itemize}
  \item Select genome, assembly and track (UCSC genes)
  \item Choose table (knownGene)
  \item Choose output format (GTF -gene transfer format for knownGene table)
  \item Insert a name for the output file
  \item Download the file (get output)
\end{itemize}
\vspace{1 em}
%
The basic table to be imported is "knownGene".
The knownGene table has to be downloaded in GTF format (otherwise the read.gtf
function will complain about "wrong number of columns").\\
\newline
%
In order to extend the available information additionally the tables "kgXref",
"knownToEnsembl" and "knownIsoforms" can be downloaded and imported.
These tables come in plain "csv" format. Select "all fields from selected table"
as output format.\\
\newline
%
Do not use "add custom tracks" or modify the tables elsewhere tracks because
the importing functions will check for apropriate number of columns.\\
\newline
%
After downloading, all tables should be placed into a separate folder
which we from now on call "basedir".\rcl{ucscGenome} objects keep a
\rfc{basedir} as standard location for all writing and reading procedures.\\
%
<<eval=FALSE>>=
uc <- ucscGenome()
basedir(uc) <- "/my/ucsc/basedir"
read.gtf(uc, "ucsc_knownGene.gtf")
addXref(uc, "kgXref.csv")
addEnsembl(uc, "knownToEnsembl.csv")
addIsoforms(uc, "ucsc_knownisoforms.csv")
@


%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\subsection{Load stored data}

Once, annotation data is imported and stored, \rcl{ucscGenome} objects can
be restored with the \rfc{loadGenome} function which is shown below on example
data:

<<eval=TRUE>>=
ucfile <- system.file("extdata", "hs.ucsc.small.RData", package="refGenome")
uc <- loadGenome(ucfile)
ensfile <- system.file("extdata", "hs.ensembl.62.small.RData", package="refGenome")
ens <- loadGenome(ensfile)
@


%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\section{Extracting data subsets}

There are specialized functions for extracting data for multiple purposes.

%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\subsection{Extracting data for sets of \texttt{seqid}'s}

For preparation of \texttt{seqid} based extraction, the contained
\texttt{seqid}'s can be tabled:

<<echo=TRUE>>=
tableSeqids(ens)
@


Extraction of subsets based on \texttt{seqid} can be done with
\texttt{extractSeqids}.
The sequence id's for extraction are specified as regular expression:
<<echo=TRUE>>=
en1 <- extractSeqids(ens, "^1$")
en1
@

It looks cumbersome for single chromosomes but allows extraction of complex
patterns.

%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\subsection{Extracting primary assembly data}

Usually the interesting part of the annotation data is the the primary assembly
(where alternative haplotypes are excluded).
Therefore functions which return the proper terms are supplied:

<<echo=TRUE>>=
ensPrimAssembly()
ucPrimAssembly()
@

Extraction of primary assembly \texttt{seqid}'s i is done by:
<<echo=TRUE>>=
enpa<-extractSeqids(ens,ensPrimAssembly())
tableSeqids(enpa)
ucpa<-extractSeqids(uc,ucPrimAssembly())
tableSeqids(ucpa)
@

%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\subsection{Extract features}

Subsets defined by \texttt{features} can allso be tabled and extracted:
<<echo=TRUE>>=
tableFeatures(enpa)
enpf<-extractFeature(enpa,"exon")
enpf
@


%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\subsection{Extract data for single genes and transcripts}

There are some functions which extract objects that contain data for single
genes (or transcripts).
These functions provide a closer insight into specific regeions.\\
\newline
%
Objects which contain data for vectors of gene-names can be extracted with
<<echo=TRUE>>=
dxe <- extractByGeneName(enpa, "DDX11L1")
dxu <- extractByGeneName(ucpa, "DDX11L1")
@
%
When gene-names did not match in the gtf-table of the object,
a message including all names of not matching gene-names will be printed.
When no gene-name matches, a message will be printed and the function
returns \Robject{NULL}, which can be tested for later on.\\
\\
Additionally subsets can also be extacted based on gene-id
<<echo=TRUE>>=
dxe <- extractByGeneId(enpa, "ENSG00000223972")
dxu <- extractByGeneId(ucpa, "ENSG00000223972")
@
%
From these extracts we can view the contained transcripts with the
\rfc{tableTranscript.id} function:
<<echo=TRUE>>=
tableTranscript.id(enpa)
tableTranscript.id(ucpa)
@

Data for interesting transcripts can be extracted by \rfc{extractTranscript}:
<<echo=TRUE>>=
extractTranscript(ens, "ENST00000456328")
extractTranscript(uc, "uc010nxr.1")
@



%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\section{Accumulate data for whole genes}

The function \Rfunction{getGenePositions} accumulates position data for whole
genes.
Genes are grouped by \code{gene\_name}.
For both, \Rclass{ensemblGenome} and \Rclass{ucscGenome} the \code{gene\_name}
column is not present after the standard gtf-import.
For \Rclass{ucscGenome}, \Rfunction{addXref} must be used.
Respective warnings are thrown.

<<echo=TRUE>>=
gpe <- getGenePositions(ens)
gpe
gpu <- getGenePositions(uc)
gpu
@
%
There is a slight difference between both results:
The last column is \code{gene\_id} for \Rclass{ensemblGenome} and
\code{clusterID} for \Rclass{ucscGenome}.
This is due to different information which is available for each.



%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\section{Exon and splice-junction based views (only for Ensembl genomes)}

%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\subsection{Extract exon based table}

Exon based view on annotation data can be obtained with \rfc{ensemblExons}
which returns an object of class \rcl{ensemblExons}.
Basically \rfc{ensemblExons} calls \rfc{extractFeature} for feature type "exon".
Information about presence of cds start or end and start-codon or stop-codon
is added.

<<echo=FALSE>>=
enex <- refExons(ens)
ucex <- refExons(uc)
@

<<>>=
enex
@


%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\subsection{Extract splice-junction based views from \rcl{ensemblExons}}

From \rcl{ensemblExons} information about adjacency of exons (which defines
annotated splice-sites) can be obtained by putting exons with equal
transcript\_id and subsequent exon\_number side by side.\\
%
The start and end positions of adjacent exons are renamed to lstart, lend
and rstart and rend.
The "l" prefix refers to the exon with lower start and end coordinates
(i.e. left, lower exon\_number).
The "r" prefix refers to the exons with higher start and end coordinates
(i.e. right, higher exon\_number).\\
%
Setting \robj{coding=TRUE} will restrict the result to exons for which
\robj{source} and \robj{gene\_biotype} equal "protein\_coding".
%
<<>>=
jens <- getSpliceTable(ens)
jens
juc <- getSpliceTable(uc)
juc
@

This generally leads to repeated occurrence of start and and positons when a
splice-junction is contained in multiple transcripts.
Additionally a handful splice-sites with multiple gene-id's are present.\\
%
The \rfc{unifyJunc} therefore calculates \robj{nGenes} which represents
the multiplicity of each gene-id at each splice-site and then selects a
gene-id for which nGenes is maximal.\\
%
\rfc{unifyJuncs} adds a \robj{uid} column to the basic \robj{gtf} table
which identifies each seqid, left-end, right-start combination uniquely.
\rfc{unifyJuncs} also adds a new \robj{ujs} table inside the contained
environment.\\
%
\rfc{getUnifiedJuncs} takes the result of \rfc{unifyJuncs} and adds
gene\_name and strand information.
%
<<>>=
ujens <- unifyJuncs(jens)
ujuc <- unifyJuncs(juc)
jeg <- getGenePositions(jens)
jug <- getGenePositions(juc)
ujens
jug
@
%
The result tables of \rfc{unifyJuncs} and \rfc{getGenePositions} are stored
inside the internal environment of \rcl{ensemblJunctions}.
From there, the results can easily be reproduced without recalculation.
The tables are automatically included in \rfc{saveGenome} and
\rfc{load.ensembl.juncs} mechanisms.


%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\section{Overlapping}

The overlap function is used to supply annotation for genomic ranges.
The function takes two \rcl{data.frame}'s which contain query (qry) and
reference (ref) ranges respectively.
Each dataset will be identified by it's id.\\
\newline
%
The routine assumes that query and reference tables are ascending sorted by
column 'start'.
Otherwise the result will be incorrect (i.e. missing hits).
The function assumes that there is no overlap between reference ranges.
It will otherwise return only one, possibly arbitrary, hit per query range.\\
\newline
%
The function returns a \rcl{data.frame}. For each query range, there will be
one row.\\
%
<<echo=TRUE>>=
qry<-data.frame(
                  id=1:6,
                  start=c(10,18,61,78,82,110),
                  end=c(15,22,63,87,90,120))
ref<-data.frame(
                  id=1:5,
                  start=c(20,40,60,80,100),
                  end=c(25,45,65,85,105))
overlap(qry,ref)
@
%
The query and reference record are identified by "queryid" and "refid".
The type of overlap is encoded in the "overlap" column.
The overlap encodings are explained as follows:
%
\begin{itemize}
  \item \textbf{no}. The query range does not overlap with any reference ranges.
  \item \textbf{l}   The query range overhangs the matching reference range on the left (lower coordinate) side.
  \item \textbf{n}   The query range is completely contained within a reference range. There is no overhang.
  \item \textbf{b}   The query range overhangs the matching reference range on both sides.
  \item \textbf{r}   The query range overhangs the matching reference range on the right (higher coordinate) side.
\end{itemize}
%
The added "leftDiff" and "rightDiff" columns contain the distance between
the query and reference range boundaries:
leftDiff is the difference between the left (lower coordinate) margins and
rightDiff is the difference between the right (higher coordinate) margins.

\subsection{Overlapping for splice-junctions}

The \rfc{overlapJuncs} function is specialized for annotation of
splice events in BAM alignment data.
The function takes two arguments: a \rcl{data.frame} providing query
data and a \rcl{refJunctions} object providing annotation data.


\subsubsection{Query data}

Query data for \rfc{overlapJuncs} are BAM alignment gap-sites.
These gap-sites are defined by one or multiplle gapped alignments of RNA-seq
reads to a reference genome.
Due to the splicing process, a variable fraction of the reads align in
two or more fractions to the reference genome.
Two adjacent alignment fractions define the position of a gap-site.\\
%
The position of the alignment fractions are named \textbf{lstart} and
\textbf{lend} for the left (i.e. lower genomic coordinates) alignment
interval and \textbf{rstart} and \textbf{rend} for the right
(i.e. higher genomic coordinates) alignment interval.\\
%
The two genomic intervals of a gap-site implicitly define a third interval:
The gap in between (alignment gap).\\
%
The biological meaning of gap-sites is that alignment gaps correspond to
introns and the left and right align regions correspond to adjacent
exon boundaries.\\
%
Due to the fact that gapped alignments do not cover whole exons,
the inner boundaries of gap-sites are biological meaningful and the
outer boundaries of gap-sites usually are technical artifacts.\\
%
Therefore the \rfc{overlapJuncs} function searches and rates overlaps by inner
gap boundaries (lend, rstart) whereas the outer boundaries solely define whether
any overlap with annotated splice-sites is present.\\

\paragraph{The query data.frame} defines one gap-site in each row.
Therefore the table is expected to contain the following columns:
\begin{itemize}
    \item \textbf{id}: Consecutive (unique) integral values.
    \item \textbf{seqid}: Character values for reference sequence
        itentifiers (e.g. 'chr1' or '1').
    \item \textbf{lstart}: Position of first nucleotide of left
        alignment region
    \item \textbf{lend}: Position of last nucleotide of left alignment
        region.
    \item \textbf{rstart}: Position of first nucleotide of right
        alignment region.
    \item \textbf{rend}: Position of last nucleotide of right alignment
        region.
\end{itemize}
All genomic positions are 1-based (i.e. first position of sequence has
position 1).

<<>>=
# + + + + + + + + + + + + + + + + + + #
# A) Example query  data
# + + + + + + + + + + + + + + + + + + #
##                          1       2       3       4       5       6       7 ##
qry <- data.frame(id = 1:7, seqid = "1",
            lstart = c(10100L, 11800L, 12220L, 12220L, 12220L, 32000L, 40000L),
            lend =   c(10100L, 12000L, 12225L, 12227L, 12227L, 32100L, 40100L),
            rstart = c(10200L, 12200L, 12057L, 12613L, 12650L, 32200L, 40200L),
            rend =   c(10300L, 12250L, 12179L, 12620L, 12700L, 32300L, 40300L))
##                          1       2       3       4       5       6       7 ##
@


\subsubsection{Reference data}

The reference data for the \rfc{overlapJuncs} function is can be obtaied
from a \rcl{refGenome} object with the \rfc{getSpliceJuncs} function.

<<>>=
ensfile <- system.file("extdata", "hs.ensembl.62.small.RData",
                                            package="refGenome")
# Load Ensembl genome
ens <- loadGenome(ensfile)
# Calculate junction positions:
junc <- getSpliceTable(ens)
@

\subsubsection{Overlapping results}

Junction based annotation of annotation gap-sites is done by the
\rfc{overlapJuncs} function.
<<>>=
res <- overlapJuncs(qry, junc)
@


The \rfc{overlapJuncs} function returns a \rcl{data.frame}. As an overlap
result is returned for every query record, the output and the query data.frame
contain the same number of rows.\\
%
The first two columns (qid and refid) provide the query id (the id from the
qry data.frame) and a refid (the id for the identified optimal overlap).
Records without overlap can be identified withe a refid value of 0.\\
%
The validity of the overlap is defined by the distance of the inner boundaries
between the query and the reference site. The distance for the left alignment
region is given in \rcl{ldiff} and the distance for the right alignment
region is given in \rcl{rdiff}. The sum of the absolute ldiff and rdiff
values is given by \rcl{sod} (sum of distances). The optimal hit is defined
as the one with the lowest sod value. An exact hit will have sod=0.\\
%
The result table provides gene\_id, transcript\_id, gene\_name and strand.


%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\section{Workflows}
%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%

%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\subsection{Establish a standard set of refGenome objects for Ensembl}

The following example assumes, that a downloaded \textit{GTF} file has been
downloaded and unzipped into a target location (endir):

<<eval=FALSE>>=
library(refGenome)
endir <- "/.../refGenomes/hsEns76"

# + + + + + + + + + + + + + + + + + + + + + + + + #
# Read GTF
# + + + + + + + + + + + + + + + + + + + + + + + + #
en76 <- ensemblGenome()
basedir(en76) <- endir
read.gtf(en76, "Homo_sapiens.GRCh38.76.gtf")
saveGenome(en76, "en76.RData")

# + + + + + + + + + + + + + + + + + + + + + + + + #
# Extract primary assembly
# + + + + + + + + + + + + + + + + + + + + + + + + #
enpa76 <- extractSeqids(en76, ensPrimAssembly())
saveGenome(enpa76, "enpa76.RData")

# + + + + + + + + + + + + + + + + + + + + + + + + #
# Extract Exons
# + + + + + + + + + + + + + + + + + + + + + + + + #
enex76 <- refExons(enpa76)
saveGenome(enex76, "enex76.RData")

# + + + + + + + + + + + + + + + + + + + + + + + + #
# Extract Junctions
# + + + + + + + + + + + + + + + + + + + + + + + + #
enjc76 <- getSpliceTable(enpa76)
saveGenome(enjc76, "enjc76.RData")

# + + + + + + + + + + + + + + + + + + + + + + + + #
# Extract data.frame
# + + + + + + + + + + + + + + + + + + + + + + + + #
# enju76 <- unifyJuncs(enjc76)
@


%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%
\section{Gene model}
%% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %%

Genomic annotation data expands into a complex variety of qualities
for each gene. The \rcl{geneModel} and \rcl{transcriptModel} classes
capture qualities for single genes and transcripts.


\subsection{geneModel objects}

Gene model objects contain collected data for one single gene
for example gene-name, gene-id and strand as well as tables with
coordinates for single exons and a list of transcript objects.

<<>>=
ensfile<-system.file("extdata",
    "hs.ensembl.62.small.RData", package="refGenome")
ens<-loadGenome(ensfile)

gt <- getGeneTable(ens)
gene_id <- as.character(gt$gene_id[1])
gm <- geneModel(ens, gene_id)
@

<<fig=TRUE>>=
plot(gm)
@

Further exploration of exons can be done using \rcl{transcriptModel}
objects which is the appropriate method when a gene consists
of many transcripts or many exons.

\subsection{transcriptModel object}

Objects of class \rcl{transcriptModel} contain data on single transcripts
like gene-id, gene-name, strand or coordinates.

Transcript objects can be extracted from \rcl{geneModel} objects
by name and by index which is the usual way to create
\rcl{transcriptModel} objects.

\subsubsection{Extraction by index}
<<>>=
tr <- getTranscript(gm, 1)
tr
@

\subsubsection{Extraction by ID}
<<>>=
tr <- getTranscript(gm, "ENST00000450305")
tr
@

From a \rcl{transcriptModel} object, exon and CDS tables can be extracted.

<<>>=
getExonData(tr)
@


<<>>=
getCdsData(tr)
@


\section{Gene model objects}

\subsection{Gene model}

Gene model objects organize data for single genes.
The Gene model objects are created using gene-id's from \rcl{refGenome}
objects as shown below.

<<>>=
ensfile<-system.file("extdata",
    "hs_en82_grch38_small.gtf", package="refGenome")

en82s <- ensemblGenome()
basedir(en82s) <- dirname(ensfile)
read.gtf(en82s, "hs_en82_grch38_small.gtf")
gt <- getGeneTable(en82s)
@


<<>>=
gm <- geneModel(en82s, "ENSG00000227232")
@

Upon 'interior=FALSE' in \rfc{geneModel} function internal gene structure
elements (exons, transcripts) are not extracted.

\subsection{Transcript model}

Transcipt model objects contain data for a single transcript.
They are intended for use inside \rcl{geneModel} objects.

<<>>=
tr <- getTranscript(gm, 1)
tr
@


\end{document}
