# An introduction to biodbNcbi

Pierrick Roger

#### 4 June 2025

#### Abstract

How to use the NCBI Gene, CCDS, Pubchem Comp and Pubchem Subst connectors and their methods.

#### Package

biodbNcbi 1.13.0

# 1 Introduction

biodbNcbi is a biodb extension package that implements a connector to the NCBI databases (Sayers et al. 2022) Gene, CCDS (Pruitt et al. 2009; Harte et al. 2012; Farrell et al. 2013), Pubchem Comp and Pubchem Subst (Kim et al. 2015).

# 2 Installation

Install using Bioconductor:

    if (!requireNamespace("BiocManager", quietly=TRUE))
        install.packages("BiocManager")
    BiocManager::install('biodbNcbi')

# 3 Initialization

The first step in using biodbNcbi, is to create an instance of the biodb class `Biodb` from the main biodb package. This is done by calling the constructor of the class:

    mybiodb <- biodb::newInst()

During this step the configuration is set up, the cache system is initialized and extension packages are loaded.

We will see at the end of this vignette that the biodb instance needs to be terminated with a call to the `terminate()` method.

# 4 Creating a connector to Gene

In biodb the connection to a database is handled by a connector instance that you can get from the factory. biodbNcbi implements a connector to a remote database. Here is the code to instantiate a connector:

    gene <- mybiodb$getFactory()$createConn('ncbi.gene')

    ## Loading required package: biodbNcbi

Creating other connectors follow the same process:

    ccds <- mybiodb$getFactory()$createConn('ncbi.ccds')
    pubchem.comp <- mybiodb$getFactory()$createConn('ncbi.pubchem.comp')
    pubchem.subst <- mybiodb$getFactory()$createConn('ncbi.pubchem.subst')

# 5 Accessing entries

To get the number of entries stored inside the database, run:

    gene$getNbEntries()

    ## [1] 86928561

To get some of the first entry IDs (accession numbers) from the database, run:

    ids <- gene$getEntryIds(2)
    ids

    ## [1] "301209632" "301209630"

To retrieve entries, use:

    entries <- gene$getEntry(ids)

    ## INFO  [17:43:42.747] Get entry content(s) for 2 id(s)...

    entries

    ## [[1]]
    ## Biodb NCBI Gene entry instance 301209632.
    ##
    ## [[2]]
    ## Biodb NCBI Gene entry instance 301209630.

To convert a list of entries into a dataframe, run:

    x <- mybiodb$entriesToDataframe(entries)
    x

    ##   accession gene.symbol ncbi.gene.id
    ## 1 301209632       cas1e    301209632
    ## 2 301209630       cas5e    301209630

# 6 Accessing efetch web service

efetch web service is accessible through the `wsEfetch()` method, available on Entrez connectors: `ncbi.gene`, `ncbi.pubchem.comp` and `ncbi.pubchem.subst`.

Get the a Gene entry as an XML object and print the `Entrezgene_prot` node:

    entryxml <- gene$wsEfetch('2833', retmode='xml', retfmt='parsed')
    XML::getNodeSet(entryxml, "//Entrezgene_prot")

    ## [[1]]
    ## <Entrezgene_prot>
    ##   <Prot-ref>
    ##     <Prot-ref_name>
    ##       <Prot-ref_name_E>G protein-coupled receptor 9</Prot-ref_name_E>
    ##       <Prot-ref_name_E>IP-10 receptor</Prot-ref_name_E>
    ##       <Prot-ref_name_E>Mig receptor</Prot-ref_name_E>
    ##       <Prot-ref_name_E>chemokine (C-X-C motif) receptor 3</Prot-ref_name_E>
    ##       <Prot-ref_name_E>chemokine receptor 3</Prot-ref_name_E>
    ##       <Prot-ref_name_E>interferon-inducible protein 10 receptor</Prot-ref_name_E>
    ##     </Prot-ref_name>
    ##     <Prot-ref_desc>C-X-C chemokine receptor type 3</Prot-ref_desc>
    ##   </Prot-ref>
    ## </Entrezgene_prot>
    ##
    ## attr(,"class")
    ## [1] "XMLNodeSet"

The object returned is an `XML::XMLInternalDocument`.

# 7 Accessing esearch web service

esearch web service is accessible through the `wsEsearch()` method, available on Entrez connectors: `ncbi.gene`, `ncbi.pubchem.comp` and `ncbi.pubchem.subst`.

Search for Gene entries by name and get the IDs of the matching entries (equivalent of running `gene$searchForEntries()`:

    gene$wsEsearch(term='"chemokine"[Gene Name]', retmax=10, retfmt='ids')

    ## [1] "395552"    "417536"    "128014773" "108261914" "128599176"

The same result can be obtained with a call to `searchForEntries()`:

    gene$searchForEntries(fields=list(name='chemokine'), max.results=10)

    ## [1] "395552"    "417536"    "128014773" "108261914" "128599176"

# 8 Accessing einfo web service

einfo web service is accessible through the `wsEinfo()` method, available on Entrez connectors: `ncbi.gene`, `ncbi.pubchem.comp` and `ncbi.pubchem.subst`.

Get PubChem Comp database information as an XML object and print information on first field:

    infoxml <- pubchem.comp$wsEinfo(retfmt='parsed')
    XML::getNodeSet(infoxml, "//Field[1]")

    ## [[1]]
    ## <Field>
    ##   <Name>ALL</Name>
    ##   <FullName>All Fields</FullName>
    ##   <Description>All terms from all searchable fields</Description>
    ##   <TermCount>1181640365</TermCount>
    ##   <IsDate>N</IsDate>
    ##   <IsNumerical>N</IsNumerical>
    ##   <SingleToken>N</SingleToken>
    ##   <Hierarchy>N</Hierarchy>
    ##   <IsHidden>N</IsHidden>
    ##   <IsTruncatable>Y</IsTruncatable>
    ##   <IsRangable>N</IsRangable>
    ## </Field>
    ##
    ## attr(,"class")
    ## [1] "XMLNodeSet"

# 9 Closing biodb instance

When done with your biodb instance you have to terminate it, in order to ensure release of resources (file handles, database connection, etc):

    mybiodb$terminate()

    ## INFO  [17:43:44.676] Closing BiodbMain instance...
    ## INFO  [17:43:44.679] Connector "ncbi.gene" deleted.
    ## INFO  [17:43:44.688] Connector "ncbi.ccds" deleted.
    ## INFO  [17:43:44.691] Connector "ncbi.pubchem.comp" deleted.
    ## INFO  [17:43:44.693] Connector "ncbi.pubchem.subst" deleted.

# 10 Session information

    sessionInfo()

    ## R version 4.5.0 (2025-04-11 ucrt)
    ## Platform: x86_64-w64-mingw32/x64
    ## Running under: Windows Server 2022 x64 (build 20348)
    ##
    ## Matrix products: default
    ##   LAPACK version 3.12.1
    ##
    ## locale:
    ## [1] LC_COLLATE=en_US.UTF-8  LC_CTYPE=en_US.UTF-8    LC_MONETARY=en_US.UTF-8
    ## [4] LC_NUMERIC=C            LC_TIME=en_US.UTF-8
    ##
    ## time zone: America/New_York
    ## tzcode source: internal
    ##
    ## attached base packages:
    ## [1] stats     graphics  grDevices utils     datasets  methods   base
    ##
    ## other attached packages:
    ## [1] biodbNcbi_1.13.0 BiocStyle_2.37.0
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] rappdirs_0.3.3       sass_0.4.10          generics_0.1.4
    ##  [4] bitops_1.0-9         stringi_1.8.7        RSQLite_2.4.0
    ##  [7] hms_1.1.3            digest_0.6.37        magrittr_2.0.3
    ## [10] evaluate_1.0.3       bookdown_0.43        fastmap_1.2.0
    ## [13] blob_1.2.4           plyr_1.8.9           jsonlite_2.0.0
    ## [16] progress_1.2.3       DBI_1.2.3            BiocManager_1.30.25
    ## [19] XML_3.99-0.18        httr2_1.1.2          jquerylib_0.1.4
    ## [22] cli_3.6.5            rlang_1.1.6          chk_0.10.0
    ## [25] crayon_1.5.3         dbplyr_2.5.0         bit64_4.6.0-1
    ## [28] withr_3.0.2          cachem_1.1.0         yaml_2.3.10
    ## [31] tools_4.5.0          memoise_2.0.1        biodb_1.17.0
    ## [34] dplyr_1.1.4          filelock_1.0.3       curl_6.2.3
    ## [37] vctrs_0.6.5          R6_2.6.1             BiocFileCache_2.99.5
    ## [40] lifecycle_1.0.4      stringr_1.5.1        bit_4.6.0
    ## [43] pkgconfig_2.0.3      pillar_1.10.2        bslib_0.9.0
    ## [46] glue_1.8.0           Rcpp_1.0.14          lgr_0.4.4
    ## [49] xfun_0.52            tibble_3.2.1         tidyselect_1.2.1
    ## [52] knitr_1.50           htmltools_0.5.8.1    rmarkdown_2.29
    ## [55] compiler_4.5.0       prettyunits_1.2.0    askpass_1.2.1
    ## [58] RCurl_1.98-1.17      openssl_2.3.3

# References

Farrell, Catherine M., Nuala A. O’Leary, Rachel A. Harte, Jane E. Loveland, Laurens G. Wilming, Craig Wallin, Mark Diekhans, et al. 2013. “Current status and new features of the Consensus Coding Sequence database.” Nucleic Acids Research 42 (D1): D865–D872. https://doi.org/10.1093/nar/gkt1059.

Harte, Rachel A., Catherine M. Farrell, Jane E. Loveland, Marie-Marthe Suner, Laurens Wilming, Bronwen Aken, Daniel Barrell, et al. 2012. “Tracking and coordinating an international curation effort for the CCDS Project.” Database 2012 (February). https://doi.org/10.1093/database/bas008.

Kim, Sunghwan, Paul A. Thiessen, Evan E. Bolton, Jie Chen, Gang Fu, Asta Gindulyte, Lianyi Han, et al. 2015. “PubChem Substance and Compound databases.” Nucleic Acids Research 44 (D1): D1202–D1213. https://doi.org/10.1093/nar/gkv951.

Pruitt, Kim D., Jennifer Harrow, Rachel A. Harte, Craig Wallin, Mark Diekhans, Donna R. Maglott, Steve Searle, et al. 2009. “The Consensus Coding Sequence (Ccds) Project: Identifying a Common Protein-Coding Gene Set for the Human and Mouse Genomes.” Genome Research 19 (7): 1316–23. https://doi.org/10.1101/gr.080531.108.

Sayers, Eric W., Evan E. Bolton, J. Rodney Brister, Kathi Canese, Jessica Chan, Donald C. Comeau, Ryan Connor, et al. 2022. “Database Resources of the National Center for Biotechnology Information.” Nucleic Acids Research 50 (D1): D20–D26. https://doi.org/10.1093/nar/gkab1112.