EnsDb-exonsBy: Retrieve annotation data from an Ensembl based package

In jotsetung/ensembldb-old: Utilities to create and use an Ensembl based annotation database

Description

Retrieve gene/transcript/exons annotations stored in an Ensembl based database package generated with the makeEnsembldbPackage function.

Usage

## S4 method for signature 'EnsDb'
exons(x, columns=listColumns(x,"exon"),
                        filter, order.by, order.type="asc",
                        return.type="GRanges")

## S4 method for signature 'EnsDb'
exonsBy(x, by=c("tx", "gene"),
                          columns=listColumns(x, "exon"), filter)

## S4 method for signature 'EnsDb'
transcripts(x, columns=listColumns(x, "tx"),
                              filter, order.by, order.type="asc",
                              return.type="GRanges")

## S4 method for signature 'EnsDb'
transcriptsBy(x, by=c("gene", "exon"),
                                columns=listColumns(x, "tx"), filter)

## S4 method for signature 'EnsDb'
genes(x, columns=listColumns(x, "gene"), filter,
                        order.by, order.type="asc",
                        return.type="GRanges")

## S4 method for signature 'EnsDb'
disjointExons(x, aggregateGenes=FALSE,
                                includeTranscripts=TRUE, filter, ...)

## S4 method for signature 'GRangesList'
toSAF(x, ...)

## S4 method for signature 'EnsDb'
getGenomeFaFile(x, pattern="dna.toplevel.fa")

Arguments

(In alphabetic order)

...	Additional arguments. Not used.
aggregateGenes	For disjointExons: When FALSE (default) exon fragments that overlap multiple genes are dropped. When TRUE, all fragments are kept and the gene_id metadata column includes all gene IDs that overlap the exon fragment.
columns	Columns to be retrieved from the database tables. Default values for genes are all columns from the gene database table, for exons and exonsBy the column names of the exon database table table and for transcript and transcriptBy the columns of the tx data base table (see details below for more information). Note that any of the column names of the database tables can be submitted to any of the methods (use listTables or listColumns methods for a complete list of allowed column names).
by	For exonsBy: wheter exons sould be fetched by genes or by transcripts; as in the corresponding function of the GenomicFeatures package. For transcriptsBy: whether transcripts should be fetched by genes or by exons; fetching transcripts by cds as supported by the transcriptsBy method in the GenomicFeatures package is currently not implemented.
filter	A filter object extending BasicFilter or a list of such object(s) to select specific entries from the database (see examples below).
includeTranscripts	For disjointExons: When TRUE (default) a tx_name metadata column is included that lists all transcript IDs that overlap the exon fragment. Note: this is different to the disjointExons function in the GenomicFeatures package, that lists the transcript names, not IDs.
order.by	Name of one of the columns above on which the results should be sorted.
order.type	If the results should be ordered ascending (asc, default) or descending (desc).
pattern	For method getGenomeFaFile: the pattern to be used to identify the fasta file representing genomic DNA sequence.
return.type	Type of the returned object. Can be either "data.frame", "DataFrame" or "GRanges". In the latter case the return object will be a GRanges object with the GRanges specifying the chromosomal start and end coordinates of the feature (gene, transcript or exon, depending whether genes, transcripts or exons was called). All additional columns are added as metadata columns to the GRanges object.
x	For toSAF a GRangesList object. For all other methods an EnsDb instance.

Details

A detailed description of all database tables and the associated attributes/column names is also given in the vignette of this package. An overview of the columns is given below:

gene_id

the Ensembl gene ID of the gene.

gene_name

the name of the gene (in most cases its official symbol).

entrezid

the NCBI Entrezgene ID of the gene; note that this can also be a ";" separated list of IDs for Ensembl genes mapped to more than one Entrezgene.

gene_biotype

the biotype of the gene.

gene_seq_start

the start coordinate of the gene on the sequence (usually a chromosome).

gene_seq_end

the end coordinate of the gene.

seq_name

the name of the sequence the gene is encoded (usually a chromosome).

seq_strand

the strand on which the gene is encoded

seq_coord_system

the coordinate system of the sequence.

tx_id

the Ensembl transcript ID.

tx_biotype

the biotype of the transcript.

tx_seq_start

the chromosomal start coordinate of the transcript.

tx_seq_end

the chromosomal end coordinate of the transcript.

tx_cds_seq_start

the start coordinate of the coding region of the transcript (NULL for non-coding transcripts).

tx_cds_seq_end

the end coordinate of the coding region.

exon_id

the ID of the exon. In Ensembl, each exon specified by a unique chromosomal start and end position has its own ID. Thus, the same exon might be part of several transcripts.

exon_seq_start

the chromosomal start coordinate of the exon.

exon_seq_end

the chromosomal end coordinate of the exon.

exon_idx

the index of the exon in the transcript model. As noted above, an exon can be part of several transcripts and thus its position inside these transcript might differ.

Also, the vignette provides examples on how to retrieve sequences for genes/transcripts/exons.

Value

For exons, transcripts and genes, a data.frame, DataFrame or a GRanges, depending on the value of the return.type parameter. The result is ordered as specified by the parameter order.by, NOT by any ordering of values in eventually submitted filter objects.

For exonsBy, transcriptsBy: a GRangesList, depending on the value of the return.type parameter. The results are ordered by the value of the by parameter.

For toSAF: a data.frame with column names "GeneID" (the group name from the GRangesList, i.e. the ID by which the GRanges are split), "Chr" (the seqnames from the GRanges), "Start" (the start coordinate), "End" (the end coordinate) and "Strand" (the strand).

For disjointExons: a GRanges of non-overlapping exon parts.

For getGenomeFaFile: a FaFile-class object with the genomic DNA sequence.

Methods and Functions

exons

Retrieve exon information from the database. Additional columns from transcripts or genes associated with the exons can be specified and are added to the respective exon annotation.

exonsBy

Retrieve exons grouped by transcript or by gene. This function returns a GRangesList as does the analogous function in the GenomicFeatures package. Using the columns parameter it is possible to determine which additional values should be retrieved from the database. These will be included in the GRanges object for the exons as metadata columns. The exons in the inner GRanges are ordered by the exon index within the transcript (if by="tx"), or increasingly by the chromosomal start position of the exon or decreasingly by the chromosomal end position of the exon depending whether the gene is encoded on the + or - strand (for by="gene"). The GRanges in the GRangesList will be ordered by the name of the gene or transcript.

transcripts

Retrieve transcript information from the database. Additional columns from genes or exons associated with the transcripts can be specified and are added to the respective transcript annotation.

transcriptsBy

Retrieve transcripts grouped by gene or exon. This function returns a GRangesList as does the analogous function in the GenomicFeatures package. Using the columns parameter it is possible to determine which additional values should be retrieved from the database. These will be included in the GRanges object for the transcripts as metadata columns. The transcripts in the inner GRanges are ordered increasingly by the chromosomal start position of the transcript for genes encoded on the + strand and in a decreasing manner by the chromosomal end position of the transcript for genes encoded on the - strand. The GRanges in the GRangesList will be ordered by the name of the gene or exon.

genes

Retrieve gene information from the database. Additional columns from transcripts or exons associated with the genes can be specified and are added to the respective gene annotation.

disjointExons

This method is identical to disjointExons defined in the GenomicFeatures package. It creates a GRanges of non-overlapping exon parts with metadata columns of gene_id and exonic_part. Exon parts that overlap more than one gene can be dropped with aggregateGenes=FALSE.

toSAF

Reformats a GRangesList object into a data.frame corresponding to a standard SAF (Simplified Annotation Format) file (i.e. with column names "GeneID", "Chr", "Start", "End" and "Strand"). Note: this method makes only sense on a GRangesList that groups features (exons, transcripts) by gene.

getGenomeFaFile

Returns a FaFile-class (defined in Rsamtools) with the genomic sequence of the genome build matching the Ensembl version of the EnsDb object. The file is retrieved using the AnnotationHub package. See the vignette for an example to work with such files.

Note

Ensembl defines genes not only on standard chromosomes, but also on patched chromosomes and chromosome variants. Thus it might be advisable to restrict the queries to just those chromosomes of interest (e.g. by specifying a SeqnameFilter(c(1:22, "X", "Y"))). In addition, also so called LRG genes (Locus Reference Genomic) are defined in Ensembl. Their gene id starts with LRG instead of ENS for Ensembl genes, thus, a filter can be applied to specifically select those genes or exclude those genes (see examples below).

Author(s)

Johannes Rainer

See Also

makeEnsembldbPackage, BasicFilter, listColumns, lengthOf

Examples

library(EnsDb.Hsapiens.v75)

######   genes
##
## get all genes endcoded on chromosome Y
AllY <- genes(EnsDb.Hsapiens.v75, filter=SeqnameFilter("Y"))
AllY

## return result as DataFrame.
AllY.granges <- genes(EnsDb.Hsapiens.v75,
                      filter=SeqnameFilter("Y"),
                      return.type="DataFrame")
AllY.granges

## include all transcripts of the gene and their chromosomal
## coordinates, sort by chrom start of transcripts and return as
## GRanges.
AllY.granges.tx <- genes(EnsDb.Hsapiens.v75,
                         filter=SeqnameFilter("Y"),
                         columns=c("gene_id", "seq_name",
                             "seq_strand", "tx_id", "tx_biotype",
                             "tx_seq_start", "tx_seq_end"),
                         order.by="tx_seq_start")
AllY.granges.tx



######   transcripts
##
## get all transcripts of a gene
Tx <- transcripts(EnsDb.Hsapiens.v75,
                  filter=GeneidFilter("ENSG00000184895"),
                  order.by="tx_seq_start")
Tx

## get all transcripts of two genes along with some information on the
## gene and transcript
Tx <- transcripts(EnsDb.Hsapiens.v75,
                  filter=GeneidFilter(c("ENSG00000184895",
                      "ENSG00000092377")),
                      columns=c("gene_id", "gene_seq_start",
                          "gene_seq_end", "gene_biotype", "tx_biotype"))
Tx



######   exons
##
## get all exons of the provided genes
Exon <- exons(EnsDb.Hsapiens.v75,
              filter=GeneidFilter(c("ENSG00000184895",
                  "ENSG00000092377")),
              order.by="exon_seq_start",
              columns=c( "gene_id", "gene_seq_start",
                  "gene_seq_end", "gene_biotype"))
Exon



#####    exonsBy
##
## get all exons for transcripts encoded on chromosomes X and Y.
ETx <- exonsBy(EnsDb.Hsapiens.v75, by="tx",
               filter=SeqnameFilter(c("X", "Y")))
ETx
## get all exons for genes encoded on chromosome 1 to 22, X and Y and
## include additional annotation columns in the result
EGenes <- exonsBy(EnsDb.Hsapiens.v75, by="gene",
                  filter=SeqnameFilter(c("X", "Y")),
                  columns=c("gene_biotype", "gene_name"))
EGenes

## Note that this might also contain "LRG" genes.
length(grep(names(EGenes), pattern="LRG"))

## to fetch just Ensemblgenes, use an GeneidFilter with value
## "ENS%" and condition "like"


#####    transcriptsBy
##
TGenes <- transcriptsBy(EnsDb.Hsapiens.v75, by="gene",
                        filter=SeqnameFilter(c("X", "Y")))
TGenes

## convert this to a SAF formatted data.frame that can be used by the
## featureCounts function from the Rsubreader package.
head(toSAF(TGenes))

jotsetung/ensembldb-old documentation built on May 19, 2019, 9:41 p.m.