exonsBy {ensembldb} | R Documentation

## Retrieve annotation data from an Ensembl based package

### Description

Retrieve gene/transcript/exons annotations stored in an Ensembl based database package generated with the `makeEnsembldbPackage` function. Parameter `filter` enables to define filters to retrieve only specific data. Alternatively, a global filter might be added to the `EnsDb` object using the `addFilter` method.

### Usage

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

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

    ## S4 method for signature 'EnsDb'
    intronsByTranscript(x, ..., use.names = FALSE)

    ## S4 method for signature 'EnsDb'
    exonsByOverlaps(x, ranges, maxgap = -1L, minoverlap = 0L,
            type = c("any", "start", "end"), columns = listColumns(x, "exon"),
            filter = AnnotationFilterList())

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

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

    ## S4 method for signature 'EnsDb'
    transcriptsByOverlaps(x, ranges, maxgap = -1L,
            minoverlap = 0L, type = c("any", "start", "end"),
            columns = listColumns(x, "tx"), filter = AnnotationFilterList())

    ## S4 method for signature 'EnsDb'
    promoters(x, upstream = 2000, downstream = 200,
            use.names = TRUE, ...)

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

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

    ## S4 method for signature 'EnsDb'
    cdsBy(x, by = c("tx", "gene"), columns = NULL,
            filter = AnnotationFilterList(), use.names = FALSE)

    ## S4 method for signature 'EnsDb'
    fiveUTRsByTranscript(x, columns = NULL,
            filter = AnnotationFilterList())

    ## S4 method for signature 'EnsDb'
    threeUTRsByTranscript(x, columns = NULL,
            filter = AnnotationFilterList())

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

### Arguments

(In alphabetic order)

`...` | For `promoters`: additional arguments to be passed to the `transcripts` method. For `intronsByTranscript`: additional arguments such as `filter`.
`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.
`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. For `cdsBy`: whether cds should be fetched by transcript of by gene.
`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). For `cdsBy`: this argument is only supported for for `by="tx"`.
`downstream` | For method `promoters`: the number of nucleotides downstream of the transcription start site that should be included in the promoter region.
`filter` | A filter describing which results to retrieve from the database. Can be a single object extending `AnnotationFilter`, an `AnnotationFilterList` object combining several such objects or a `formula` representing a filter expression (see examples below or `AnnotationFilter` for more details). Use the `supportedFilters` method to get an overview of supported filter classes and related fields.
`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.
`maxgap` | For `exonsByOverlaps` and `transcriptsByOverlaps`: see `exonsByOverlaps` in `GenomicFeatures` for more information.
`minoverlap` | For `exonsByOverlaps` and `transcriptsByOverlaps`: see `exonsByOverlaps` in `GenomicFeatures` for more information.
`order.by` | Character vector specifying the column(s) by which the result should be ordered. This can be either in the form of `"gene_id, seq_name"` or `c("gene_id", "seq_name")`.
`order.type` | If the results should be ordered ascending (`asc`, default) or descending (`desc`).
`ranges` | For `exonsByOverlaps` and `transcriptsByOverlaps`: a `GRanges` object specifying the genomic regions.
`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.
`type` | For `exonsByOverlaps` and `transcriptsByOverlaps`: see `exonsByOverlaps` in `GenomicFeatures` for more information.
`upstream` | For method `promoters`: the number of nucleotides upstream of the transcription start site that should be included in the promoter region.
`use.names` | For `cdsBy` and `exonsBy`: only for `by="gene"`: use the names of the genes instead of their IDs as names of the resulting `GRangesList`.
`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 column contains a `list` of Entrezgene identifiers to accommodate the potential 1:n mapping between Ensembl genes and Entrezgene IDs.

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.

Many `EnsDb` databases provide also protein related annotations. See `listProteinColumns` for more information.

### 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` or, if not provided, by `seq_name` and chromosomal start coordinate, but 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 `exonsByOverlaps` and `transcriptsByOverlaps`: a `GRanges` with the exons or transcripts overlapping the specified regions.

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 `cdsBy`: a `GRangesList` with `GRanges` per either transcript or exon specifying the start and end coordinates of the coding region of the transcript or gene.

For `fiveUTRsByTranscript`: a `GRangesList` with `GRanges` for each protein coding transcript representing the start and end coordinates of full or partial exons that constitute the 5' untranslated region of the transcript.

For `threeUTRsByTranscript`: a `GRangesList` with `GRanges` for each protein coding transcript representing the start and end coordinates of full or partial exons that constitute the 3' untranslated region of the transcript.

### 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.

intronsByTranscript

  Retrieve introns by transcripts. Filters can also be passed to the function. For more information see the `intronsByTranscript` method in the `GenomicFeatures` package.

exonsByOverlaps

  Retrieve exons overlapping specified genomic ranges. For more information see the `exonsByOverlaps` method in the `GenomicFeatures` package. The functionality is to some extent similar and redundant to the `exons` method in combination with `GRangesFilter` filter.

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.

transcriptsByOverlaps

  Retrieve transcripts overlapping specified genomic ranges. For more information see `transcriptsByOverlaps` method in the `GenomicFeatures` package. The functionality is to some extent similar and redundant to the `transcripts` method in combination with `GRangesFilter` filter.

promoters

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

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. Note that column `"entrezid"` is a `list` of Entrezgene identifiers to accomodate the potential 1:n mapping between Ensembl genes and Entrezgene IDs.

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`.

cdsBy

  Returns the coding region grouped either by transcript or by gene. Each element in the `GRangesList` represents the cds for one transcript or gene, with the individual ranges corresponding to the coding part of its exons. For `by="tx"` additional annotation columns can be added to the individual `GRanges` (in addition to the default columns `exon_id` and `exon_rank`). Note that the `GRangesList` is sorted by its names.

fiveUTRsByTranscript

  Returns the 5' untranslated region for protein coding transcripts.

threeUTRsByTranscript

  Returns the 3' untranslated region for protein coding transcripts.

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.

### 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).

Depending on the value of the global option `"ucscChromosomeNames"` (use `getOption(ucscChromosomeNames, FALSE)` to get its value or `option(ucscChromosomeNames=TRUE)` to change its value) the sequence/chromosome names of the returned `GRanges` objects or provided in the returned `data.frame` or `DataFrame` correspond to Ensembl chromosome names (if value is `FALSE`) or UCSC chromosome names (if `TRUE`). This ensures a better integration with the `Gviz` package, in which this option is set by default to `TRUE`.

### Note

While it is possible to request values from a column `"tx_name"` (with the `columns` argument), no such column is present in the database. The returned values correspond to the ID of the transcripts.

### Author(s)

Johannes Rainer, Tim Triche

### See Also

`supportedFilters` to get an overview of supported filters. `makeEnsembldbPackage`, `listColumns`, `lengthOf`

`addFilter` for globally adding filters to an `EnsDb` object.

### Examples

    library(EnsDb.Hsapiens.v86)
    edb <- EnsDb.Hsapiens.v86

    ######   genes
    ##
    ## Get all genes encoded on chromosome Y
    AllY <- genes(edb, filter = SeqNameFilter("Y"))
    AllY

    ## Return the result as a DataFrame; also, we use a filter expression here
    ## to define which features to extract from the database.
    AllY.granges <- genes(edb,
                          filter = ~ seq_name == "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(edb,
                             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(edb,
                      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(edb,
                      filter = GeneIdFilter(c("ENSG00000184895",
                                              "ENSG00000092377")),
                      columns = c("gene_id", "gene_seq_start", "gene_seq_end",
                                  "gene_biotype", "tx_biotype"))
    Tx

    ######   promoters
    ##
    ## Get the bona-fide promoters (2k up- to 200nt downstream of TSS)
    promoters(edb, filter = GeneIdFilter(c("ENSG00000184895",
                                           "ENSG00000092377")))

    ######   exons
    ##
    ## Get all exons of protein coding transcript for the gene ENSG00000184895
    Exon <- exons(edb,
                  filter = ~ gene_id == "ENSG00000184895" &
                      tx_biotype == "protein_coding",
                  columns = c("gene_id", "gene_seq_start", "gene_seq_end",
                              "tx_biotype", "gene_biotype"))
    Exon

    #####    exonsBy
    ##
    ## Get all exons for transcripts encoded on chromosomes X and Y.
    ETx <- exonsBy(edb, 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(edb, 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"
    eg <- exonsBy(edb, by = "gene",
                  filter = AnnotationFilterList(SeqNameFilter(c("X", "Y")),
                                                GeneIdFilter("ENS", "startsWith")),
                  columns = c("gene_biotype", "gene_name"))
    eg
    length(grep(names(eg), pattern="LRG"))

    #####    transcriptsBy
    ##
    TGenes <- transcriptsBy(edb, 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))

    #####   transcriptsByOverlaps
    ##
    ir <- IRanges(start = c(2654890, 2709520, 28111770),
                  end = c(2654900, 2709550, 28111790))
    gr <- GRanges(rep("Y", length(ir)), ir)

    ## Retrieve all transcripts overlapping any of the regions.
    txs <- transcriptsByOverlaps(edb, gr)
    txs

    ## Alternatively, use a GRangesFilter
    grf <- GRangesFilter(gr, type = "any")
    txs <- transcripts(edb, filter = grf)
    txs

    ####    cdsBy
    ## Get the coding region for all transcripts on chromosome Y.
    ## Specifying also additional annotation columns (in addition to the default
    ## exon_id and exon_rank).
    cds <- cdsBy(edb, by = "tx", filter = SeqNameFilter("Y"),
                 columns = c("tx_biotype", "gene_name"))

    ####    the 5' untranslated regions:
    fUTRs <- fiveUTRsByTranscript(edb, filter = SeqNameFilter("Y"))

    ####    the 3' untranslated regions with additional column gene_name.
    tUTRs <- threeUTRsByTranscript(edb, filter = SeqNameFilter("Y"),
                                   columns = "gene_name")

[Package ensembldb version 2.6.8 Index]