1 Introduction

In this document are presented different aspects of biodb in more details: the object oriented programming model adopted, its architecture, how to configure the package, how to create connectors and delete them, understanding the request scheduler, how to tune the logging system.

2 Object oriented programming (OOP) model

In R, you may already know the two classical OOP models S3 and S4. S4 is certainly the most used model, and is based on an original system of generic methods that can be specialized for each class.

Two more recent OOP models exist in R: Reference Classes (aka RC or R5 from package methods) and R6 (from package R6). These two models are very similar. The biodb package uses a mix of RC and R6, but will switch completely to R6 in a near future.

They both implement an object model and based on references. This means that each object is unique, never copied and accessed through references. In this system, the created objects are not copied, but their reference are copied. Any modification of an object in one part of the code, will be visible from all other parts of the code. This means that when you pass an instance to a function, that function is able to modify the instance.

Also, in RC and R6, the functions are attached to the object. In other words, the mechanism to call a function on a object is different from S4. The calling mechanism is thus slightly different, in RC or R6 we write myObject$myFunction() instead of myFunction(myObject) in S4.

See Reference Classes chapter from package methods and this introduction to R6 for more details.

3 Initialization & termination

biodb uses an initialization/termination scheme. You must first initialize the library by creating an instance of the main class BiodbMain:

mybiodb <- biodb::newInst()
## INFO  [16:51:37.593] Loading definitions from package biodb version 1.2.1.

And when you are done with the library, you have to terminate the instance explicitly:

mybiodb$terminate()
## INFO  [16:51:37.690] Closing BiodbMain instance...

We will need a biodb instance for the rest of this vignette. Let us call the constructor again:

mybiodb <- biodb::newInst()
## INFO  [16:51:37.702] Loading definitions from package biodb version 1.2.1.

4 Management classes

Several class instances are attached to the biodb instance for managing different aspects of biodb: creating connectors, configuring biodb, accessing the cache system, etc.

See table 1 for a list of these instances and their purpose.

Table 1: The management classes
Only one instance is created for each of theses classes, and attached to the BiodbMain instance,
Class Method to get the instance Description
BiodbConfig mybiodb$getConfig() Access to configuration values, and modification.
BiodbDbsInfo mybiodb$getDbsInfo() Databases information (name, description, request frequency, etc).
BiodbEntryFields mybiodb$getEntryFields() Entry fields information (description, type, cardinality, etc).
BiodbFactory mybiodb$getFactory() Creation of connectors and entries.
BiodbPersistentCache mybiodb$getPersistentCache() Cache system on disk.
BiodbRequestScheduler mybiodb$getRequestScheduler() Send requests to web servers, respecting the frequency limit for each database server.

5 Configuration

Several configuration values are defined inside the definitions.yml file of biodb. New configuration values can also be defined in extension packages.

To get a list of the existing configuration keys with their current value, run:

mybiodb$getConfig()
## Biodb configuration instance.
##   Values:
##      allow.huge.downloads :  TRUE 
##      autoload.extra.pkgs :  FALSE 
##      cache.all.requests :  TRUE 
##      cache.directory :  NA 
##      cache.read.only :  FALSE 
##      cache.system :  TRUE 
##      compute.fields :  TRUE 
##      dwnld.chunk.size :  NA 
##      dwnld.timeout :  3600 
##      entries.sep :  | 
##      force.locale :  TRUE 
##      intra.field.name.sep :  . 
##      multival.field.sep :  ; 
##      offline :  FALSE 
##      persistent.cache.impl :  custom 
##      proton.mass :  1.007276 
##      svn.binary.path :   
##      test.functions :  NA 
##      use.cache.for.local.db :  FALSE 
##      useragent :  NA

To get a data frame of all keys with their title (short description), type and default value, call (result in 2):

x <- mybiodb$getConfig()$listKeys()

Table 2: List of keys with some of their parameters
key title type default
allow.huge.downloads Authorize download of big files. logical TRUE
autoload.extra.pkgs Enable automatic loading of extension packages. logical FALSE
cache.all.requests Enable caching of all requests and their results. logical TRUE
cache.directory Path to the cache folder. character NA
cache.read.only Set cache system in read only mode. logical FALSE
cache.system Enable cache system. logical TRUE
use.cache.for.local.db Enable the use of the cache system also for local databases. logical FALSE
dwnld.chunk.size The number of new entries to wait before saving them into the cache. integer NA
dwnld.timeout Download timeout in seconds. integer 3600
compute.fields Enable automatic computing of missing fields. logical TRUE
force.locale Force change of current locale for the application. logical TRUE
multival.field.sep The separator used for concatenating values. character ;
intra.field.name.sep The separator use for building a field name. character .
entries.sep The separator used between values from different entries. character |
offline Stops sending requests to the network. logical FALSE
persistent.cache.impl The implementation to use for the persistent cache. character custom
proton.mass The mass of one proton. numeric 1.0072765
svn.binary.path The path to the svn binary. character
test.functions List of functions to test. character NA
useragent The application name and contact address to send to the contacted web server. character NA

To get the description of a key, run:

mybiodb$getConfig()$getDescription('cache.directory')
## [1] "The directory in which cache files are stored. The default location depends on your operating system and the choice between the custom persistent cache and the Bioconductor persistent cache."

To get a value, run:

mybiodb$getConfig()$get('cache.directory')
## [1] NA

To set a field value, run:

mybiodb$getConfig()$set('cache.directory', '~/my.biodb.cache')

If the field is boolean, you can use the following methods instead:

mybiodb$getConfig()$enable('offline')
## INFO  [16:51:37.838] Enable offline.
mybiodb$getConfig()$disable('offline')
## INFO  [16:51:37.841] Disable offline.

Configuration keys have default values. You can get a key’s default value with this call:

mybiodb$getConfig()$getDefaultValue('cache.directory')
## NULL

Environment variables can be used to overwrite default values. To get the name of the environment variable associated with a particular key, call the following method:

mybiodb$getConfig()$getAssocEnvVar('cache.directory')
## [1] "BIODB_CACHE_DIRECTORY"

6 Databases information

Before creating any connector, you can information on the available databases and their connector classes.

Getting the databases info instance will print you a list of all available database connector classes:

mybiodb$getDbsInfo()
## Biodb databases information instance.
## The following databases are defined:
##   comp.csv.file: Compound CSV File connector class.
##   comp.sqlite: Compound SQLite connector class.
##   mass.csv.file: Mass spectra CSV File connector class.
##   mass.sqlite: Mass spectra SQLite connector class.

If you want more information on one particular connector, run:

mybiodb$getDbsInfo()$get('mass.csv.file')
## Mass spectra CSV File class.
##   Class: mass.csv.file.
##   Package: biodb.
##   Description: A connector to handle a mass spectra database stored inside a CSV file. It is possible to choose the separator for the CSV file, as well as match the column names with the biodb entry fields...
##   Entry content type: tsv.

7 Available database connectors

This package is delivered with two connectors for local databasses: MassCsvFile annd MassSqlite. However it is extendable, and in fact other packages already exist or will soon be made available on Bioconductor or GitHub for accessing other databases like ChEBI, Uniprot, HMDB, KEGG, Massbank or Lipidmaps. You may also write your own connector by extending biodb. If you are interested, a vignette explains what you need to do in details.

When creating the instance of the BiodbMain class you should have received a message like “Loading definitions from package …” if any extending package has also been installed on your system. Connector definitions found in extending packages are automatically loaded when instantiating BiodbMain, thus you do not need to call library() to individually load each extending package.

To get a list of available connectors, simply print information about your BiodbMain instance:

mybiodb

8 Creating connectors

Connectors are created through the factory instance.

To get the factory instance, run:

mybiodb$getFactory()
## Biodb factory instance.

Here is the creation of a Compound CSV File connector, using TSV file:

chebi.tsv <- system.file("extdata", "chebi_extract.tsv", package='biodb')
conn <- mybiodb$getFactory()$createConn('comp.csv.file', url=chebi.tsv)
conn
## INFO  [16:51:37.887] Loading file database "/tmp/RtmpYXnmRN/Rinst2721392ee22cea/biodb/extdata/chebi_extract.tsv". 
## Compound CSV File instance.
##   Class: comp.csv.file.
##   Package: biodb.
##   Description: A connector to handle a compound database stored inside a CSV file. It is possible to choose the separator for the CSV file, as well as match the column names with the biodb entry fields..
##   Entry content type: tsv.
##   URLs: base.url: /tmp/RtmpYXnmRN/Rinst2721392ee22cea/biodb/extdata/chebi_extract.tsv.
##   ID: comp.csv.file.
## The following fields have been defined: accession, formula, monoisotopic.mass, molecular.mass, kegg.compound.id, name, smiles, description.

The connector instance allows you to send requests to the database to retrieve entries directly with getEntry():

conn$getEntry('1018')
## Biodb Compound CSV File entry instance 1018.

or run more complex queries like a search:

conn$searchForEntries(list(monoisotopic.mass=list(value=136.05, delta=0.1)))
## [1] 1390

See vignette Manipulating entry objects to learn how to access database entries and manipulate them.

All the connectors inherit from super class BiodbConn, hence they share a set of common methods like getEntryIds(), getEntry() and searchForEntries(). Moreover a connector may be specialized as a connector to a compound database or to a mass spectra database, in which case they will inherit specific methods. In the case of a mass spectra database, it will be methods targeted toward mass spectra like getNbPeaks(), searchForMassSpectra(), msmsSearch(), etc. In the case of a compound database, it will be annotateMzValues(). Those methods are generic and thus can be used with any connector inheriting the super class.

When creating a connector, the factory keeps a reference to it in a list. If you try to create again the same connector, the method createConn() will throw an error. However to can use the getConn() method to get back the connector instance from its identifier or database name (if there is only one instance for the database):

conn <- mybiodb$getFactory()$getConn('comp.csv.file')

The factory is also responsible for creating the BiodbEntry objects, and as for the connectors, it stores them into a list (called the “volatile cache”). When asking again for the same entry, the factory will return the reference is has kept in the list.

To delete a connector, which is a good thing to do if you are not done with biodb but you have finished using a particular connector, run:

mybiodb$getFactory()$deleteConn(conn)
## INFO  [16:51:38.001] Connector "comp.csv.file" deleted.

This will free all memory used for this connector, including the created entries. Be careful to do not keep those entry objects in some variable on your side, otherwise the memory will not be released by R.

9 Request scheduler

The BiodbRequestScheduler instance is responsible for sending requests to web server, taking care of respecting the frequency specified by the scheduler.n and scheduler.t parameters, and for receiving results and saving them to cache.

The cache is used to give back a result immediately without contacting the server, in case the exact same request has already been run previously.

You do not have to interact with the request scheduler, it runs as a back end component.

10 Entry fields information

The BiodbEntryFields instance stores information about all entry fields declared inside definitions YAML files.

Get the entry fields instance:

mybiodb$getEntryFields()
## Biodb entry fields information instance.

Get information about a field:

mybiodb$getEntryFields()$get('monoisotopic.mass')
## Entry field "monoisotopic.mass".
##   Description: Monoisotopic mass, in u (unified atomic mass units) or Da (Dalton). It is computed using the mass of the primary isotope of the elements including the mass defect (mass difference between neutron and proton, and nuclear binding energy). Used with high resolution mass spectrometers. See https://en.wikipedia.org/wiki/Monoisotopic_mass.
##   Class: double.
##   Type: mass.
##   Cardinality: one.
##   Aliases: exact.mass.

The object returned is a BiodbEntryField instance. See the help page of this class to get a list of all methods you can call on such an instance.

11 Persistent cache system

The persistent cache system is responsible for saving entry contents and results of web server requests onto disk, and reuse them later to avoid recontacting the web server.

Run the following method to get the instance of the BiodbPersistentCache class:

mybiodb$getPersistentCache()
## Biodb persistent cache system instance.
##   The used implementation is: custom.
##   The path to the cache system is: ~/my.biodb.cache.
##   The cache is readable.
##   The cache is writable.

It is possible to delete files from the cache directly from the persistent cache instance. However it is a lot preferable to do it from the connector instance. If we open an instance of the ChEBI example connector from the vignette Creating a new connector. :

source(system.file("extdata", "ChebiExConn.R", package='biodb'))
source(system.file("extdata", "ChebiExEntry.R", package='biodb'))
mybiodb$loadDefinitions(system.file("extdata", "chebi_ex.yml", package='biodb'))
conn <- mybiodb$getFactory()$createConn('chebi.ex')

And load some entry:

entry <- conn$getEntry('17001')
## INFO  [16:51:38.104] Create cache folder "~/my.biodb.cache/chebi.ex-0c5076ac2a43d16dbce503a44b09f649" for "chebi.ex-0c5076ac2a43d16dbce503a44b09f649".

The entry is now downloaded into the cache system. We can check that with the following call:

mybiodb$getPersistentCache()$fileExist(conn$getCacheId(), name='17001', ext=conn$getEntryFileExt())
## Warning: `fileExist()` was deprecated in biodb 1.1.0.
## Please use `fileExists()` instead.
## [1] TRUE

And get the path to the cache file:

mybiodb$getPersistentCache()$getFilePath(conn$getCacheId(), name='17001', ext=conn$getEntryFileExt())
## [1] "~/my.biodb.cache/chebi.ex-0c5076ac2a43d16dbce503a44b09f649/17001.xml"

If we delete the entry content from the cache:

conn$deleteAllEntriesFromPersistentCache()

The file does not exist anymore:

mybiodb$getPersistentCache()$fileExist(conn$getCacheId(), name='17001', ext=conn$getEntryFileExt())
## Warning: `fileExist()` was deprecated in biodb 1.1.0.
## Please use `fileExists()` instead.
## [1] FALSE

But the entry object is still in memory. We need to delete entry instances with the following call:

conn$deleteAllEntriesFromVolatileCache()

Note that the results of web server requests are still inside the cache folder. In order to force a new downloading of data, we need to erase those files too. The following call will erase all cache files associated with a connector, including the files deleted by deleteAllEntriesFromPersistentCache():

conn$deleteWholePersistentCache()
## INFO  [16:51:39.402] Erasing all files in "~/my.biodb.cache/chebi.ex-0c5076ac2a43d16dbce503a44b09f649".

12 Logging messages

biodb uses the lgr package for logging messages. The lgr instance used by biodb can be gotten by calling:

biodb::getLogger()
## <Logger> [info] biodb
## 
## inherited appenders:
##   console: <AppenderConsole> [all] -> console

See the lgr home page for demonstration on how to use it.

You can use the following biodb short cuts to send messages of different levels. To send an information message:

biodb::logInfo("%d entries have been processed.", 12)
## INFO  [16:51:39.424] 12 entries have been processed.

To send a debug message:

biodb::logDebug("The file %s has been written.", 'myfile.txt')

To send a trace message:

biodb::logTrace("%d bytes written.", 1284902)

In addition biodb defines two methods to throw an error or a warning and log this error or warning at the same time. These are biodb::error() and biodb::warn().

By default the lgr package displays information messages. If you want to silence all messages, just run lgr::lgr$remove_appender(1). This is will remove the default appender and silence all messages from all packages using lgr, including biodb. However if you just want to silence biodb messages, run:

biodb::getLogger()$set_threshold(300)

Information messages are now silenced:

biodb::logInfo("hello")

For enabling again:

biodb::getLogger()$set_threshold(400)

And messages are echoed again:

biodb::logInfo("hello")
## INFO  [16:51:39.489] hello

13 Closing biodb instance

Do not forget to terminate your biodb instance once you are done with it:

mybiodb$terminate()
## INFO  [16:51:39.502] Closing BiodbMain instance... 
## INFO  [16:51:39.504] Connector "chebi.ex" deleted.

14 Session information

sessionInfo()
## R version 4.1.1 (2021-08-10)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 20.04.3 LTS
## 
## Matrix products: default
## BLAS:   /home/biocbuild/bbs-3.14-bioc/R/lib/libRblas.so
## LAPACK: /home/biocbuild/bbs-3.14-bioc/R/lib/libRlapack.so
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_GB              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       
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] biodb_1.2.1      BiocStyle_2.22.0
## 
## loaded via a namespace (and not attached):
##  [1] progress_1.2.2      tidyselect_1.1.1    xfun_0.28          
##  [4] bslib_0.3.1         purrr_0.3.4         vctrs_0.3.8        
##  [7] generics_0.1.1      htmltools_0.5.2     BiocFileCache_2.2.0
## [10] yaml_2.2.1          utf8_1.2.2          blob_1.2.2         
## [13] XML_3.99-0.8        rlang_0.4.12        jquerylib_0.1.4    
## [16] pillar_1.6.4        withr_2.4.2         glue_1.5.0         
## [19] DBI_1.1.1           rappdirs_0.3.3      bit64_4.0.5        
## [22] dbplyr_2.1.1        lifecycle_1.0.1     plyr_1.8.6         
## [25] stringr_1.4.0       memoise_2.0.0       evaluate_0.14      
## [28] knitr_1.36          fastmap_1.1.0       curl_4.3.2         
## [31] fansi_0.5.0         highr_0.9           Rcpp_1.0.7         
## [34] openssl_1.4.5       filelock_1.0.2      BiocManager_1.30.16
## [37] cachem_1.0.6        jsonlite_1.7.2      bit_4.0.4          
## [40] hms_1.1.1           chk_0.7.0           askpass_1.1        
## [43] digest_0.6.28       stringi_1.7.5       bookdown_0.24      
## [46] dplyr_1.0.7         bitops_1.0-7        tools_4.1.1        
## [49] magrittr_2.0.1      sass_0.4.0          RCurl_1.98-1.5     
## [52] RSQLite_2.2.8       tibble_3.1.6        crayon_1.4.2       
## [55] pkgconfig_2.0.3     ellipsis_0.3.2      prettyunits_1.1.1  
## [58] assertthat_0.2.1    rmarkdown_2.11      httr_1.4.2         
## [61] lgr_0.4.3           R6_2.5.1            compiler_4.1.1

15 References