convertIdentifiers {sparrow} | R Documentation

## Converts internal feature identifiers in a GeneSetDb to a set of new ones.

### Description

The various GeneSetDb data providers (MSigDb, KEGG, etc). limit the identifier types that they return. Use this function to map the given identifiers to whichever type you like.

### Usage

    convertIdentifiers(
      x,
      from = NULL,
      to = NULL,
      id.type = c("ensembl", "entrez", "symbol"),
      xref = NULL,
      extra.cols = NULL,
      allow.cartesian = FALSE,
      min_support = 3,
      top = TRUE,
      ...
    )

    ## S4 method for signature 'BiocSet'
    convertIdentifiers(
      x,
      from = NULL,
      to = NULL,
      id.type = c("ensembl", "entrez", "symbol"),
      xref = NULL,
      extra.cols = NULL,
      allow.cartesian = FALSE,
      min_support = 3,
      top = TRUE,
      ...
    )

    ## S4 method for signature 'GeneSetDb'
    convertIdentifiers(
      x,
      from = NULL,
      to = NULL,
      id.type = c("ensembl", "entrez", "symbol"),
      xref = NULL,
      extra.cols = NULL,
      allow.cartesian = FALSE,
      min_support = 3,
      top = TRUE,
      ...
    )

### Arguments

`x` | The GeneSetDb with identifiers to convert
`from, to` | If you are doing identifier and/orspecies conversion using babelgene, `to` is the species you want to convert to, and `from` is the species of `x`. If you are only doing id type conversion within the same species, specify the current species in `from`. If you are providing a data.frame map of identifiers in `xref`, `to` is the name of the column that holds the new identifiers, and `from` is the name of the column that holds the current identifiers.
`id.type` | If you are using babelgene conversion, this specifies the type of identifier you want to convert to. It can be any of `"ensembl"`, `"entrez"`, or `"symbol"`.
`xref` | a data.frame used to map current identifiers to target ones.
`extra.cols` | a character vector of columns from `to` to add to the features of the new GeneSetDb. If you want to keep the original identifiers of the remapped features, include `"original_id"` as one of the values here.
`allow.cartesian` | a boolean used to temporarily set the `datatable.allow.cartesian` global option. If you are doing a 1:many map of your identifiers, you may trigger this error. You can temporarily turn this option/error off by setting `allow.cartesian = TRUE`. The option will be restored to its "pre-function call" value `on.exit`.
`min_support, top` | Parameters used in the internal call to `babelgene::orthologs()`
`...` | pass through args (not used)

### Details

For best results, provide your own identifier mapping reference, but we provide a convenience wrapper around the `babelgene::orthologs()` function to change between identifier types and species.

When there are multiple target id's for the source id, they will all be returned. When there is no target id for the source id, the soucre feature will be axed.

### Value

A new GeneSetDb object with converted identifiers. We try to retain any metadata in the original object, but no guarantees are given. If `id_type` was stored previously in the collectionMetadata, that will be dropped.

### Methods (by class)

- `BiocSet`: converts identifiers in a BiocSet

- `GeneSetDb`: converts identifiers in a GeneSetDb

### Custom Mapping

You need to provide a data.frame via the `xref` paramater that has a column for the current identifiers and another column for the target identifiers. The columns are specified by the `from` and `to` paramters, respectively.

### Convenience identifier and species mapping

If you don't provide a data.frame, you can provide a species name. We will rely on the babelgene package for the conversion, so you will have to provide a species name that it recognizes.

### Species and Identifier Conversion via babelgene

We plan to provide a quick wrapper to babelgene's ortholog mapping function to make identifier conversion a easier through this function. You can track this in sparrow issue #2.

### Examples

    # You can convert the identifiers within a GeneSetDb to some other type
    # by providing a "translation" table. Check out the unit tests for more
    # examples.
    gdb <- exampleGeneSetDb() # this has no symbols in it

    # Define a silly conversion table.
    xref <- data.frame(
      current_id = featureIds(gdb),
      new_id = paste0(featureIds(gdb), "_symbol"))
    gdb2 <- convertIdentifiers(gdb, from = "current_id", to = "new_id",
                               xref = xref, extra.cols = "original_id")
    geneSet(gdb2, name = "BIOCARTA_AGPCR_PATHWAY")

    # Convert entrez to ensembl id's using babelgene
    ## Not run:
    # The conversion functionality via babelgene isn't yet implemented, but
    # will look like this.

    # 1. convert the human entrez identifiers to ensembl
    gdb.ens <- convertIdentifiers(gdb, "human", id.type = "ensembl")

    # 2. convert the human entrez to mouse entrez
    gdb.entm <- convertIdentifiers(gdb, "human", "mouse", id.type = "entrez")

    # 3. convert the human entrez to mouse ensembl
    gdb.ensm <- convertIdentifiers(gdb, "human", "mouse", id.type = "ensembl")

    ## End(Not run)

[Package sparrow version 1.0.3 Index]