# BridgeDbR Tutorial

# Introduction

BridgeDb is a combination of an application programming interface (API), library, and set of data files for mapping identifiers for identical objects (Iersel et al. 2010). Because BridgeDb is use by projects in bioinformatics, like WikiPathways (Pico et al. 2008) and PathVisio (Iersel et al. 2008), identifier mapping databases are available for gene products (including proteins), metabolites, and metabolic conversions. We are also working on a disease database mapping file.

Questions can be directed to the BridgeDb Google Group.

The Bioconductor BridgeDbR package page describes how to install the package. After installation, the library can be loaded with the following command:

    library(BridgeDbR)

    ## Loading required package: rJava

*Note: if you have trouble with rJava (required package), please read the general information or follow the instructions here for Ubuntu.

# Concepts

BridgeDb has a few core concepts which are explained in this section. Much of the API requires one to be familiar with these concepts, though some are not always applicable. The first concept is an example of that: organisms, which do not apply to metabolites.

## Organisms

However, for genes the organism is important: the same gene has different identifiers in different organisms. BridgeDb identifies organisms by their latin name and with a two character code. Because identifier mapping files provided by PathVisio have names with these short codes, it can be useful to have a conversion method:

    code <- getOrganismCode("Rattus norvegicus")
    code

    ## [1] "Rn"

## Data Sources

Identifiers have a context and this context is often a database. For example, metabolite identfiers can be provided by the Human Metabolome Database (HMDB), ChemSpider, PubChem, ChEBI, and many others. Similarly, gene product identifiers can be provided by databases like Ensembl, (NCBI) Entrez Gene, Uniprot etc. Such a database providing identifiers is called a data source in BridgeDb.

Importantly, each such data source is identified by a human readable long name and by a short system code. This package has methods to interconvert one into the other:

    fullName <- getFullName("Ce")
    fullName

    ## [1] "ChEBI"

    code <- getSystemCode("ChEBI")
    code

    ## [1] "Ce"

## Identifier Patterns

Another useful aspect of BridgeDb is that it knows about the patterns of identifiers. If this pattern is unique enough, it can be used used to automatically find the data sources that match a particular identifier. For example:

    getMatchingSources("HMDB00555")

    ##  [1] "HGNC"                             "NCI Pathway Interaction Database"
    ##  [3] "EMBL"                             "LipidBank"
    ##  [5] "GitHub"                           "HMDB"
    ##  [7] "NCBI Protein"                     "ICD-11"
    ##  [9] "SUPFAM"                           "Wikipedia"
    ## [11] "KEGG Pathway"                     "SWISS-MODEL"
    ## [13] "VMH metabolite"

    getMatchingSources("ENSG00000100030")

    ##  [1] "HGNC"                             "NCI Pathway Interaction Database"
    ##  [3] "EMBL"                             "LipidBank"
    ##  [5] "GitHub"                           "NCBI Protein"
    ##  [7] "ICD-11"                           "Ensembl"
    ##  [9] "SUPFAM"                           "Wikipedia"
    ## [11] "SWISS-MODEL"                      "VMH metabolite"
    ## [13] "OpenTargets"

You may notice unexpected datasources in the results. That often means that the matcher for the identifier structure for that resources is very general. For example, the identifier for Wikipedia can be more or less any string.

## Identifier Mapping Databases

The BridgeDb package primarily provides the software framework, and not identifier mapping data. Identifier Mapping databases can be downloaded from various websites. The package knows about the download location (provided by PathVisio), and we can query for all gene product identifier mapping databases:

    getBridgeNames()

## Downloading

The package provides a convenience method to download such identifier mapping databases. For example, we can save the identifier mapping database for rat to the current folder with:

    dbLocation <- getDatabase("Rattus norvegicus", location = getwd())

The dbLocation variable then contains the location of the identifier mapping file that was downloaded.

Mapping databases can also be manually downloaded for genes, metabolites, and gene variants from https://bridgedb.github.io/data/gene_database/:

- Genes, Transcripts, and Proteins
- Metabolites
- Metabolic Interactions

Add the dbLocation with the following lines (first obtain in which folder, aka working directory ‘wd’, you are currently). Add the correct folder location at the dots:

    getwd()
    dbLocation <- ("/home/..../BridgeDb/wikidata_diseases.bridge")

## Loading Databases

Once you have downloaded an identifier mapping database, either manually or via the `getDatabase()` method, you need to load the database for the identifier mappings to become available. It is important to note that the location given to the `loadDatabase()` method is ideally an absolute path.

    mapper <- loadDatabase(dbLocation)

# Mapping Identifiers

With a loaded database, identifiers can be mapped. The mapping method uses system codes. So, to map the human Entrez Gene identifier (system code: L) 196410 to Affy identifiers (system code: X) we use:

    location <- getDatabase("Homo sapiens")
    mapper <- loadDatabase(location)
    map(mapper, "L", "196410", "X")

## Using compact resource identifiers

The `map()` function also has support for compact resource identifiers (CURIEs) as explained in the Bioregistry.io paper (Hoyt et al. 2022). The previous example would then be as follows, where `ncbigene` is the Bioregistry.io prefix matching the `L` data source:

    location <- getDatabase("Homo sapiens")
    mapper <- loadDatabase(location)
    map(mapper, compactIdentifier="ncbigene:196410", "X")

## Mapping multiple identifiers

For mapping multiple identifiers, for example in a data frame, you can use the new “maps()” convenience method. Let’s assume we have a data frame, data, with a HMDB identifier in the second column, we can get Wikidata identifiers with this code:

    input <- data.frame(
        source = rep("Ch", length(data[, 2])),
        identifier = data[, 2]
    )
    wikidata <- maps(mapper, input, "Wd")

# Metabolomics

While you can download the gene and protein identifier mapping databases with the getDatabase() method, this mapping database cannot be used for metabolites. The mapping database for metabolites will have to be downloaded manually from Figshare, e.g. the February 2018 release version. A full overview of mappings files can be found in this Figshare collection.

Each mapping file record will allow you to download the .bridge file with the mappings.

If reproducibility is important to you, you can download the file with (mind you, these files are quite large):

    ## Set the working directory to download the Metabolite mapping file
    location <- "data/metabolites.bridge"
    checkfile <- paste0(getwd(), "/", location)

    ## Download the Metabolite mapping file (if it doesn't exist locally yet):
    if (!file.exists(checkfile)) {
        download.file(
            "https://figshare.com/ndownloader/files/26001794",
            location
        )
    }
    # Load the ID mapper:
    mapper <- BridgeDbR::loadDatabase(checkfile)

With this mapper you can then map metabolite identifiers:

    map(mapper, "456", source = "Cs", target = "Ck")

# References

# Session info

Here is the output of `sessionInfo()` on the system on which this document was compiled running pandoc 3.8.3:

    ## R version 4.6.0 (2026-04-24)
    ## Platform: x86_64-pc-linux-gnu
    ## Running under: Ubuntu 24.04.4 LTS
    ##
    ## Matrix products: default
    ## BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
    ## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
    ##
    ## locale:
    ##  [1] LC_CTYPE=en_US.UTF-8          LC_NUMERIC=C
    ##  [3] LC_TIME=en_US.UTF-8           LC_COLLATE=en_US.UTF-8
    ##  [5] LC_MONETARY=en_US.UTF-8       LC_MESSAGES=en_US.UTF-8
    ##  [7] LC_PAPER=en_US.UTF-8          LC_NAME=en_US.UTF-8
    ##  [9] LC_ADDRESS=en_US.UTF-8        LC_TELEPHONE=en_US.UTF-8
    ## [11] LC_MEASUREMENT=en_US.UTF-8    LC_IDENTIFICATION=en_US.UTF-8
    ##
    ## time zone: Etc/UTC
    ## tzcode source: system (glibc)
    ##
    ## attached base packages:
    ## [1] stats     graphics  grDevices utils     datasets  methods   base
    ##
    ## other attached packages:
    ## [1] BridgeDbR_2.23.0 rJava_1.0-18     BiocStyle_2.41.0
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] digest_0.6.39       R6_2.6.1            fastmap_1.2.0
    ##  [4] xfun_0.57           maketools_1.3.2     cachem_1.1.0
    ##  [7] knitr_1.51          htmltools_0.5.9     rmarkdown_2.31
    ## [10] buildtools_1.0.0    lifecycle_1.0.5     cli_3.6.6
    ## [13] sass_0.4.10         jquerylib_0.1.4     compiler_4.6.0
    ## [16] sys_3.4.3           tools_4.6.0         curl_7.1.0
    ## [19] evaluate_1.0.5      bslib_0.10.0        yaml_2.3.12
    ## [22] BiocManager_1.30.27 jsonlite_2.0.0      rlang_1.2.0

Hoyt, Charles Tapley, Meghan Balk, Tiffany J. Callahan, et al. 2022. “Unifying the Identification of Biomedical Entities with the Bioregistry.” Scientific Data 9 (1). https://doi.org/10.1038/S41597-022-01807-3.
Iersel, Martijn P. van, Thomas Kelder, Alexander R. Pico, et al. 2008. “Presenting and exploring biological pathways with PathVisio.” {Article}. BMC Bioinformatics (236 GRAYS INN RD, FLOOR 6, LONDON WC1X 8HL, ENGLAND) 9. https://doi.org/10.1186/1471-2105-9-399.
Iersel, Martijn van, Alexander Pico, Thomas Kelder, et al. 2010. “The BridgeDb Framework: Standardized Access to Gene, Protein and Metabolite Identifier Mapping Services.” BMC Bioinformatics 11 (1): 5+. https://doi.org/10.1186/1471-2105-11-5.
Pico, Alexander R., Thomas Kelder, Martijn P. van Iersel, Kristina Hanspers, Bruce R. Conklin, and Chris Evelo. 2008. “WikiPathways: Pathway Editing for the People.” PLoS Biol 6 (7): e184+. https://doi.org/10.1371/journal.pbio.0060184.