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

Installation

Install using Bioconductor:

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

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.

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')

Accessing entries

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

gene$getNbEntries()

## INFO  [04:22:40.331] Create cache folder "/github/home/.cache/R/biodb/ncbi.gene-b6d7417e507eb4f1a2e0047bde5295e8" for "ncbi.gene-b6d7417e507eb4f1a2e0047bde5295e8".

## [1] 81981917

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

ids <- gene$getEntryIds(2)
ids

## [1] "96154291" "96154289"

To retrieve entries, use:

entries <- gene$getEntry(ids)

## INFO  [04:22:41.046] Get entry content(s) for 2 id(s)...

entries

## [[1]]
## Biodb NCBI Gene entry instance 96154291.
## 
## [[2]]
## Biodb NCBI Gene entry instance 96154289.

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

x <- mybiodb$entriesToDataframe(entries)
x

##   accession ncbi.gene.id
## 1  96154291     96154291
## 2  96154289     96154289

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.

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"

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')

## INFO  [04:22:42.553] Create cache folder "/github/home/.cache/R/biodb/ncbi.pubchem.comp-e80afa72f6aa7425ca0c72f99f7b9d75" for "ncbi.pubchem.comp-e80afa72f6aa7425ca0c72f99f7b9d75".

XML::getNodeSet(infoxml, "//Field[1]")

## [[1]]
## <Field>
##   <Name>ALL</Name>
##   <FullName>All Fields</FullName>
##   <Description>All terms from all searchable fields</Description>
##   <TermCount>1151299328</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"

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  [04:22:42.787] Closing BiodbMain instance...
## INFO  [04:22:42.788] Connector "ncbi.gene" deleted.
## INFO  [04:22:42.800] Connector "ncbi.ccds" deleted.
## INFO  [04:22:42.801] Connector "ncbi.pubchem.comp" deleted.
## INFO  [04:22:42.801] Connector "ncbi.pubchem.subst" deleted.

Session information

sessionInfo()

## R version 4.4.1 (2024-06-14)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 24.04.1 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=C              
##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
##  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## time zone: Etc/UTC
## tzcode source: system (glibc)
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] biodbNcbi_1.11.0 BiocStyle_2.33.1
## 
## loaded via a namespace (and not attached):
##  [1] rappdirs_0.3.3       sass_0.4.9           utf8_1.2.4          
##  [4] generics_0.1.3       bitops_1.0-9         stringi_1.8.4       
##  [7] RSQLite_2.3.7        hms_1.1.3            digest_0.6.37       
## [10] magrittr_2.0.3       evaluate_1.0.1       fastmap_1.2.0       
## [13] blob_1.2.4           plyr_1.8.9           jsonlite_1.8.9      
## [16] progress_1.2.3       DBI_1.2.3            BiocManager_1.30.25 
## [19] httr_1.4.7           fansi_1.0.6          XML_3.99-0.17       
## [22] jquerylib_0.1.4      cli_3.6.3            rlang_1.1.4         
## [25] chk_0.9.2            crayon_1.5.3         dbplyr_2.5.0        
## [28] bit64_4.5.2          withr_3.0.2          cachem_1.1.0        
## [31] yaml_2.3.10          tools_4.4.1          memoise_2.0.1       
## [34] biodb_1.13.0         dplyr_1.1.4          filelock_1.0.3      
## [37] curl_5.2.3           buildtools_1.0.0     vctrs_0.6.5         
## [40] R6_2.5.1             BiocFileCache_2.13.2 lifecycle_1.0.4     
## [43] stringr_1.5.1        bit_4.5.0            pkgconfig_2.0.3     
## [46] pillar_1.9.0         bslib_0.8.0          glue_1.8.0          
## [49] Rcpp_1.0.13          lgr_0.4.4            xfun_0.48           
## [52] tibble_3.2.1         tidyselect_1.2.1     sys_3.4.3           
## [55] knitr_1.48           htmltools_0.5.8.1    rmarkdown_2.28      
## [58] maketools_1.3.1      compiler_4.4.1       prettyunits_1.2.0   
## [61] askpass_1.2.1        RCurl_1.98-1.16      openssl_2.2.2