Filter-classes {ensembldb} | R Documentation

## Filters supported by ensembldb

### Description

`ensembldb` supports most of the filters from the AnnotationFilter package to retrieve specific content from EnsDb databases. These filters can be passed to the methods such as `genes()` with the `filter` parameter or can be added as a global filter to an `EnsDb` object (see `addFilter()` for more details). Use `supportedFilters()` to get an overview of all filters supported by `EnsDb` object.

`seqnames`: accessor for the sequence names of the `GRanges` object within a `GRangesFilter`.

`seqnames`: accessor for the `seqlevels` of the `GRanges` object within a `GRangesFilter`.

`supportedFilters` returns a `data.frame` with the names of all filters and the corresponding field supported by the `EnsDb` object.

### Usage

    OnlyCodingTxFilter()

    ProtDomIdFilter(value, condition = "==")

    ProteinDomainIdFilter(value, condition = "==")

    ProteinDomainSourceFilter(value, condition = "==")

    UniprotDbFilter(value, condition = "==")

    UniprotMappingTypeFilter(value, condition = "==")

    TxSupportLevelFilter(value, condition = "==")

    TxExternalNameFilter(value, condition = "==")

    ## S4 method for signature 'GRangesFilter'
    seqnames(x)

    ## S4 method for signature 'GRangesFilter'
    seqlevels(x)

    ## S4 method for signature 'EnsDb'
    supportedFilters(object, ...)

### Arguments

`value` | The value(s) for the filter. For `GRangesFilter` it has to be a `GRanges` object.
`condition` | `character(1)` specifying the condition of the filter. For `character`-based filters (such as `GeneIdFilter`) `"=="`, `"!="`, `"startsWith"` and `"endsWith"` are supported. Allowed values for `integer`-based filters (such as `GeneStartFilter`) are `"=="`, `"!="`, `"<"`. `"<="`, `">"` and `">="`.
`x` | For `seqnames`, `seqlevels`: a `GRangesFilter` object.
`object` | For `supportedFilters`: an `EnsDb` object.
`...` | For `supportedFilters`: currently not used.

### Details

`ensembldb` supports the following filters from the `AnnotationFilter` package:

- `GeneIdFilter`: filter based on the Ensembl gene ID.

- `GeneNameFilter`: filter based on the name of the gene as provided Ensembl. In most cases this will correspond to the official gene symbol.

- `SymbolFilter` filter based on the gene names. `EnsDb` objects don't have a dedicated symbol column, the filtering is hence based on the gene names.

- `GeneBiotype`: filter based on the biotype of genes (e.g. `"protein_coding"`).

- `GeneStartFilter`: filter based on the genomic start coordinate of genes.

- `GeneEndFilter`: filter based on the genomic end coordinate of genes.

- `EntrezidFilter`: filter based on the genes' NCBI Entrezgene ID.

- `TxIdFilter`: filter based on the Ensembld transcript ID.

- `TxNameFilter`: to be compliant with `TxDb` object from the `GenomicFeatures` package `tx_name` in fact represents the Ensembl transcript ID. Thus, the the `tx_id` and `tx_name` columns contain the same information and the `TxIdFilter` and `TxNameFilter` are in fact identical. The names of transcripts (i.e. the external name field in Ensembl are stored in column `"tx_external_name"` (and which can be filtered using the `TxExternalNameFilter`.

- `TxBiotypeFilter`: filter based on the transcripts' biotype.

- `TxStartFilter`: filter based on the genomic start coordinate of the transcripts.

- `TxEndFilter`: filter based on the genonic end coordinates of the transcripts.

- `ExonIdFilter`: filter based on Ensembl exon IDs.

- `ExonRankFilter`: filter based on the index/rank of the exon within the transcrips.

- `ExonStartFilter`: filter based on the genomic start coordinates of the exons.

- `ExonEndFilter`: filter based on the genomic end coordinates of the exons.

- `GRangesFilter`: Allows to fetch features within or overlapping specified genomic region(s)/range(s). This filter takes a `GRanges` object as input and, if `type = "any"` (the default) will restrict results to features (genes, transcripts or exons) that are partially overlapping the region. Alternatively, by specifying `condition = "within"` it will return features located within the range. In addition, the `GRangesFilter` `condition = "start"`, `condition = "end"` and `condition = "equal"` filtering for features with the same start or end coordinate or that are equal to the `GRanges`.

  Note that the type of feature on which the filter is applied depends on the method that is called, i.e. `genes()` will filter on the genomic coordinates of genes, `transcripts()` on those of transcripts and `exons()` on exon coordinates.

  Calls to the methods `exonsBy()`, `cdsBy()` and `transcriptsBy()` use the start and end coordinates of the feature type specified with argument `by` (i.e. `"gene"`, `"transcript"` or `"exon"`) for the filtering.

  If the specified `GRanges` object defines multiple regions, all features within (or overlapping) any of these regions are returned.

  Chromosome names/seqnames can be provided in UCSC format (e.g. `"chrX"`) or Ensembl format (e.g. `"X"`); see `seqlevelsStyle()` for more information.

- `SeqNameFilter`: filter based on chromosome names.

- `SeqStrandFilter`: filter based on the chromosome strand. The strand can be specified with `value = "+"`, `value = "-"`, `value = -1` or `value = 1`.

- `ProteinIdFilter`: filter based on Ensembl protein IDs. This filter is only supported if the `EnsDb` provides protein annotations; use the `hasProteinData()` method to check.

- `UniprotFilter`: filter based on Uniprot IDs. This filter is only supported if the `EnsDb` provides protein annotations; use the `hasProteinData()` method to check.

In addition, the following filters are defined by `ensembldb`:

- `TxExternalNameFilter`: filter based on the transcript's external name (if available).

- `TxSupportLevel`: allows to filter results using the provided transcript support level. Support levels for transcripts are defined by Ensembl based on the available evidences for a transcript with 1 being the highest evidence grade and 5 the lowest level. This filter is only supported on `EnsDb` databases with a db schema version higher 2.1.

- `UniprotDbFilter`: allows to filter results based on the specified Uniprot database name(s).

- `UniprotMappingTypeFilter`: allows to filter results based on the mapping method/type that was used to assign Uniprot IDs to Ensembl protein IDs.

- `ProtDomIdFilter`, `ProteinDomainIdFilter`: allows to retrieve entries from the database matching the provided filter criteria based on their protein domain ID (protein_domain_id).

- `ProteinDomainSourceFilter`: filter results based on the source (database/method) defining the protein domain (e.g. `"pfam"`).

- `OnlyCodingTxFilter`: allows to retrieve entries only for protein coding transcripts, i.e. transcripts with a CDS. This filter does not take any input arguments.

### Value

For `ProtDomIdFilter`: A `ProtDomIdFilter` object.

For `ProteinDomainIdFilter`: A `ProteinDomainIdFilter` object.

For `ProteinDomainSourceFilter`: A `ProteinDomainSourceFilter` object.

For `UniprotDbFilter`: A `UniprotDbFilter` object.

For `UniprotMappingTypeFilter`: A `UniprotMappingTypeFilter` object.

For `TxSupportLevel`: A `TxSupportLevel` object.

For `TxExternalNameFilter`: A `TxExternalNameFilter` object.

For `supportedFilters`: a `data.frame` with the names and the corresponding field of the supported filter classes.

### Note

For users of `ensembldb` version < 2.0: in the `GRangesFilter` from the `AnnotationFilter` package the `condition` parameter was renamed to `type` (to be consistent with the `IRanges` package). In addition, `condition = "overlapping"` is no longer recognized. To retrieve all features overlapping the range `type = "any"` has to be used.

Protein annotation based filters can only be used if the `EnsDb` database contains protein annotations, i.e. if `hasProteinData` is `TRUE`. Also, only protein coding transcripts will have protein annotations available, thus, non-coding transcripts/genes will not be returned by the queries using protein annotation filters.

### Author(s)

Johannes Rainer

### See Also

`supportedFilters()` to list all filters supported for `EnsDb` objects.

`listUniprotDbs()` and `listUniprotMappingTypes()` to list all Uniprot database names respectively mapping method types from the database.

`GeneIdFilter()` in the `AnnotationFilter` package for more details on the filter objects.

`genes()`, `transcripts()`, `exons()`, `listGenebiotypes()`, `listTxbiotypes()`.

`addFilter()` and `filter()` for globally adding filters to an `EnsDb`.

### Examples

    ## Create a filter that could be used to retrieve all informations for
    ## the respective gene.
    gif <- GeneIdFilter("ENSG00000012817")
    gif

    ## Create a filter for a chromosomal end position of a gene
    sef <- GeneEndFilter(10000, condition = ">")
    sef

    ## For additional examples see the help page of "genes".

    ## Example for GRangesFilter:
    ## retrieve all genes overlapping the specified region
    grf <- GRangesFilter(GRanges("11", ranges = IRanges(114129278, 114129328),
                                 strand = "+"), type = "any")
    library(EnsDb.Hsapiens.v86)
    edb <- EnsDb.Hsapiens.v86
    genes(edb, filter = grf)

    ## Get also all transcripts overlapping that region.
    transcripts(edb, filter = grf)

    ## Retrieve all transcripts for the above gene
    gn <- genes(edb, filter = grf)
    txs <- transcripts(edb, filter = GeneNameFilter(gn$gene_name))
    ## Next we simply plot their start and end coordinates.
    plot(3, 3, pch=NA, xlim=c(start(gn), end(gn)), ylim=c(0, length(txs)),
    yaxt="n", ylab="")
    ## Highlight the GRangesFilter region
    rect(xleft=start(grf), xright=end(grf), ybottom=0, ytop=length(txs),
    col="red", border="red")
    for(i in 1:length(txs)){
        current <- txs[i]
        rect(xleft=start(current), xright=end(current), ybottom=i-0.975, ytop=i-0.125, border="grey")
        text(start(current), y=i-0.5,pos=4, cex=0.75, labels=current$tx_id)
    }
    ## Thus, we can see that only 4 transcripts of that gene are indeed
    ## overlapping the region.

    ## No exon is overlapping that region, thus we're not getting anything
    exons(edb, filter = grf)

    ## Example for ExonRankFilter
    ## Extract all exons 1 and (if present) 2 for all genes encoded on the
    ## Y chromosome
    exons(edb, columns = c("tx_id", "exon_idx"),
          filter=list(SeqNameFilter("Y"),
                      ExonRankFilter(3, condition = "<")))

    ## Get all transcripts for the gene SKA2
    transcripts(edb, filter = GeneNameFilter("SKA2"))

    ## Which is the same as using a SymbolFilter
    transcripts(edb, filter = SymbolFilter("SKA2"))

    ## Create a ProteinIdFilter:
    pf <- ProteinIdFilter("ENSP00000362111")
    pf
    ## Using this filter would retrieve all database entries that are associated
    ## with a protein with the ID "ENSP00000362111"
    if (hasProteinData(edb)) {
        res <- genes(edb, filter = pf)
        res
    }

    ## UniprotFilter:
    uf <- UniprotFilter("O60762")
    ## Get the transcripts encoding that protein:
    if (hasProteinData(edb)) {
        transcripts(edb, filter = uf)
        ## The mapping Ensembl protein ID to Uniprot ID can however be 1:n:
        transcripts(edb, filter = TxIdFilter("ENST00000371588"),
            columns = c("protein_id", "uniprot_id"))
    }

    ## ProtDomIdFilter:
    pdf <- ProtDomIdFilter("PF00335")
    ## Also here we could get all transcripts related to that protein domain
    if (hasProteinData(edb)) {
        transcripts(edb, filter = pdf, columns = "protein_id")
    }

[Package ensembldb version 2.18.4 Index]