# The database manager in OmnipathR

Denes Turei1*

1Institute for Computational Biomedicine, Heidelberg University

*turei.denes@gmail.com

#### 16 July 2025

#### Abstract

The database manager is an API within OmnipathR which is able to load various datasets, keep track of their usage and remove them after an expiry period. Currently it supports a few Gene Ontology and UniProt datasets, but easily can be extended to cover all datasets in the package.

#### Package

OmnipathR 3.17.4

# Contents

1 Institute for Computational Biomedicine, Heidelberg University

# 1 Available datasets

To see a full list of datasets call the `omnipath_show_db` function:

    library(OmnipathR)
    omnipath_show_db()

    ## # A tibble: 24 × 10
    ##    name               last_used lifetime package   loader         loader_param latest_param loaded db    key
    ##  * <chr>              <dttm>       <int> <chr>     <chr>          <list>       <lgl>        <lgl>  <lis> <chr>
    ##  1 Gene Ontology (ba… NA             300 OmnipathR go_ontology_d… <named list> NA           FALSE  <lgl> go_b…
    ##  2 Gene Ontology (fu… NA             300 OmnipathR go_ontology_d… <named list> NA           FALSE  <lgl> go_f…
    ##  3 Gene Ontology (AG… NA             300 OmnipathR go_ontology_d… <named list> NA           FALSE  <lgl> go_a…
    ##  4 Gene Ontology (As… NA             300 OmnipathR go_ontology_d… <named list> NA           FALSE  <lgl> go_a…
    ##  5 Gene Ontology (ge… NA             300 OmnipathR go_ontology_d… <named list> NA           FALSE  <lgl> go_s…
    ##  6 Gene Ontology (Ca… NA             300 OmnipathR go_ontology_d… <named list> NA           FALSE  <lgl> go_c…
    ##  7 Gene Ontology (Dr… NA             300 OmnipathR go_ontology_d… <named list> NA           FALSE  <lgl> go_d…
    ##  8 Gene Ontology (Ch… NA             300 OmnipathR go_ontology_d… <named list> NA           FALSE  <lgl> go_c…
    ##  9 Gene Ontology (me… NA             300 OmnipathR go_ontology_d… <named list> NA           FALSE  <lgl> go_m…
    ## 10 Gene Ontology (pl… NA             300 OmnipathR go_ontology_d… <named list> NA           FALSE  <lgl> go_p…
    ## # ℹ 14 more rows

It returns a tibble where each dataset has a human readable name and a key which can be used to refer to it. We can also check here if the dataset is currently loaded, the time it’s been last used, the loader function and its arguments.

# 2 Access a dataset

Datasets can be accessed by the `get_db` function. Ideally you should call this function every time you use the dataset. The first time it will be loaded, the subsequent times the already loaded dataset will be returned. This way each access is registered and extends the expiry time. Let’s load the human UniProt-GeneSymbol table. Above we see its key is `up_gs`.

    up_gs <- get_db('up_gs')
    up_gs

    ## # A tibble: 20,469 × 2
    ##    From       To
    ##    <chr>      <chr>
    ##  1 A0A087X1C5 CYP2D7
    ##  2 A0A0B4J2F0 PIGBOS1
    ##  3 A0A0C5B5G6 MT-RNR1
    ##  4 A0A0K2S4Q6 CD300H
    ##  5 A0A0U1RRE5 NBDY
    ##  6 A0A1B0GTW7 CIROP
    ##  7 A0AV02     SLC12A8
    ##  8 A0AV96     RBM47
    ##  9 A0AVF1     IFT56
    ## 10 A0AVI4     TMEM129
    ## # ℹ 20,459 more rows

This dataset is a two columns data frame of SwissProt IDs and Gene Symbols. Looking again at the datasets, we find that this dataset is loaded now and the `last_used` timestamp is set to the time we called `get_db`:

    omnipath_show_db()

    ## # A tibble: 24 × 10
    ##    name               last_used lifetime package   loader         loader_param latest_param loaded db    key
    ##  * <chr>              <dttm>       <int> <chr>     <chr>          <list>       <list>       <lgl>  <lis> <chr>
    ##  1 Gene Ontology (ba… NA             300 OmnipathR go_ontology_d… <named list> <lgl [1]>    FALSE  <lgl> go_b…
    ##  2 Gene Ontology (fu… NA             300 OmnipathR go_ontology_d… <named list> <lgl [1]>    FALSE  <lgl> go_f…
    ##  3 Gene Ontology (AG… NA             300 OmnipathR go_ontology_d… <named list> <lgl [1]>    FALSE  <lgl> go_a…
    ##  4 Gene Ontology (As… NA             300 OmnipathR go_ontology_d… <named list> <lgl [1]>    FALSE  <lgl> go_a…
    ##  5 Gene Ontology (ge… NA             300 OmnipathR go_ontology_d… <named list> <lgl [1]>    FALSE  <lgl> go_s…
    ##  6 Gene Ontology (Ca… NA             300 OmnipathR go_ontology_d… <named list> <lgl [1]>    FALSE  <lgl> go_c…
    ##  7 Gene Ontology (Dr… NA             300 OmnipathR go_ontology_d… <named list> <lgl [1]>    FALSE  <lgl> go_d…
    ##  8 Gene Ontology (Ch… NA             300 OmnipathR go_ontology_d… <named list> <lgl [1]>    FALSE  <lgl> go_c…
    ##  9 Gene Ontology (me… NA             300 OmnipathR go_ontology_d… <named list> <lgl [1]>    FALSE  <lgl> go_m…
    ## 10 Gene Ontology (pl… NA             300 OmnipathR go_ontology_d… <named list> <lgl [1]>    FALSE  <lgl> go_p…
    ## # ℹ 14 more rows

The above table contains also a reference to the dataset, and the arguments passed to the loader function:

    d <- omnipath_show_db()
    d %>% dplyr::pull(db) %>% magrittr::extract2(16)

    ## # A tibble: 20,469 × 2
    ##    From       To
    ##    <chr>      <chr>
    ##  1 A0A087X1C5 CYP2D7
    ##  2 A0A0B4J2F0 PIGBOS1
    ##  3 A0A0C5B5G6 MT-RNR1
    ##  4 A0A0K2S4Q6 CD300H
    ##  5 A0A0U1RRE5 NBDY
    ##  6 A0A1B0GTW7 CIROP
    ##  7 A0AV02     SLC12A8
    ##  8 A0AV96     RBM47
    ##  9 A0AVF1     IFT56
    ## 10 A0AVI4     TMEM129
    ## # ℹ 20,459 more rows

    d %>% dplyr::pull(latest_param) %>% magrittr::extract2(16)

    ## $to
    ## [1] "genesymbol"
    ##
    ## $organism
    ## [1] 9606

If we call `get_db` again, the timestamp is updated, resetting the expiry counter:

    up_gs <- get_db('up_gs')
    omnipath_show_db()

    ## # A tibble: 24 × 10
    ##    name               last_used lifetime package   loader         loader_param latest_param loaded db    key
    ##  * <chr>              <dttm>       <int> <chr>     <chr>          <list>       <list>       <lgl>  <lis> <chr>
    ##  1 Gene Ontology (ba… NA             300 OmnipathR go_ontology_d… <named list> <lgl [1]>    FALSE  <lgl> go_b…
    ##  2 Gene Ontology (fu… NA             300 OmnipathR go_ontology_d… <named list> <lgl [1]>    FALSE  <lgl> go_f…
    ##  3 Gene Ontology (AG… NA             300 OmnipathR go_ontology_d… <named list> <lgl [1]>    FALSE  <lgl> go_a…
    ##  4 Gene Ontology (As… NA             300 OmnipathR go_ontology_d… <named list> <lgl [1]>    FALSE  <lgl> go_a…
    ##  5 Gene Ontology (ge… NA             300 OmnipathR go_ontology_d… <named list> <lgl [1]>    FALSE  <lgl> go_s…
    ##  6 Gene Ontology (Ca… NA             300 OmnipathR go_ontology_d… <named list> <lgl [1]>    FALSE  <lgl> go_c…
    ##  7 Gene Ontology (Dr… NA             300 OmnipathR go_ontology_d… <named list> <lgl [1]>    FALSE  <lgl> go_d…
    ##  8 Gene Ontology (Ch… NA             300 OmnipathR go_ontology_d… <named list> <lgl [1]>    FALSE  <lgl> go_c…
    ##  9 Gene Ontology (me… NA             300 OmnipathR go_ontology_d… <named list> <lgl [1]>    FALSE  <lgl> go_m…
    ## 10 Gene Ontology (pl… NA             300 OmnipathR go_ontology_d… <named list> <lgl [1]>    FALSE  <lgl> go_p…
    ## # ℹ 14 more rows

# 3 Where are the loaded datasets?

The loaded datasets live in an environment which belong to the OmnipathR package. Normally users don’t need to access this environment. As we see below, `omnipath_show_db` presents us all information availble by directly looking at the environment:

    OmnipathR:::omnipathr.env$db$up_gs

    ## $name
    ## [1] "UniProt-GeneSymbol table"
    ##
    ## $last_used
    ## [1] "2025-07-16 20:53:36 EDT"
    ##
    ## $lifetime
    ## [1] 300
    ##
    ## $package
    ## [1] "OmnipathR"
    ##
    ## $loader
    ## [1] "uniprot_full_id_mapping_table"
    ##
    ## $loader_param
    ## $loader_param$to
    ## [1] "genesymbol"
    ##
    ## $loader_param$organism
    ## [1] 9606
    ##
    ##
    ## $latest_param
    ## $latest_param$to
    ## [1] "genesymbol"
    ##
    ## $latest_param$organism
    ## [1] 9606
    ##
    ##
    ## $loaded
    ## [1] TRUE
    ##
    ## $db
    ## # A tibble: 20,469 × 2
    ##    From       To
    ##    <chr>      <chr>
    ##  1 A0A087X1C5 CYP2D7
    ##  2 A0A0B4J2F0 PIGBOS1
    ##  3 A0A0C5B5G6 MT-RNR1
    ##  4 A0A0K2S4Q6 CD300H
    ##  5 A0A0U1RRE5 NBDY
    ##  6 A0A1B0GTW7 CIROP
    ##  7 A0AV02     SLC12A8
    ##  8 A0AV96     RBM47
    ##  9 A0AVF1     IFT56
    ## 10 A0AVI4     TMEM129
    ## # ℹ 20,459 more rows

# 4 How to extend the expiry period?

The default expiry of datasets is given by the option `omnipath.db_lifetime`. By calling `omnipath_save_config` this option is saved to the default config file and will be valid in all subsequent sessions. Otherwise it’s valid only in the current session.

    options(omnipath.db_lifetime = 600)
    omnipath_save_config()

# 5 Where are the datasets defined?

The built-in dataset definitions are in a JSON file shipped with the package. Easiest way to see it is by the git web interface.

# 6 How to add custom datasets?

Currently no API available for this, but it would be super easy to implement. It would be matter of providing a JSON similar to the above, or calling a function. Please open an issue if you are interested in this feature.

# 7 Session information

    sessionInfo()

    ## R version 4.5.1 (2025-06-13 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=C                           LC_CTYPE=English_United States.utf8
    ## [3] LC_MONETARY=English_United States.utf8 LC_NUMERIC=C
    ## [5] LC_TIME=English_United States.utf8
    ##
    ## time zone: America/New_York
    ## tzcode source: internal
    ##
    ## attached base packages:
    ## [1] stats     graphics  grDevices utils     datasets  methods   base
    ##
    ## other attached packages:
    ## [1] OmnipathR_3.17.4 BiocStyle_2.37.0
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] xfun_0.52           bslib_0.9.0         httr2_1.2.0         websocket_1.4.4     processx_3.8.6
    ##  [6] tzdb_0.5.0          vctrs_0.6.5         tools_4.5.1         ps_1.9.1            generics_0.1.4
    ## [11] parallel_4.5.1      curl_6.4.0          tibble_3.3.0        RSQLite_2.4.1       blob_1.2.4
    ## [16] pkgconfig_2.0.3     R.oo_1.27.1         checkmate_2.3.2     readxl_1.4.5        lifecycle_1.0.4
    ## [21] compiler_4.5.1      stringr_1.5.1       progress_1.2.3      chromote_0.5.1      htmltools_0.5.8.1
    ## [26] sass_0.4.10         yaml_2.3.10         tidyr_1.3.1         later_1.4.2         pillar_1.11.0
    ## [31] crayon_1.5.3        jquerylib_0.1.4     R.utils_2.13.0      cachem_1.1.0        sessioninfo_1.2.3
    ## [36] zip_2.3.3           tidyselect_1.2.1    rvest_1.0.4         digest_0.6.37       stringi_1.8.7
    ## [41] dplyr_1.1.4         purrr_1.1.0         bookdown_0.43       fastmap_1.2.0       archive_1.1.12
    ## [46] cli_3.6.5           logger_0.4.0        magrittr_2.0.3      utf8_1.2.6          XML_3.99-0.18
    ## [51] withr_3.0.2         readr_2.1.5         prettyunits_1.2.0   promises_1.3.3      backports_1.5.0
    ## [56] rappdirs_0.3.3      bit64_4.6.0-1       lubridate_1.9.4     timechange_0.3.0    rmarkdown_2.29
    ## [61] httr_1.4.7          igraph_2.1.4        bit_4.6.0           cellranger_1.1.0    R.methodsS3_1.8.2
    ## [66] hms_1.1.3           memoise_2.0.1       evaluate_1.0.4      knitr_1.50          tcltk_4.5.1
    ## [71] rlang_1.1.6         Rcpp_1.1.0          glue_1.8.0          DBI_1.2.3           selectr_0.4-2
    ## [76] BiocManager_1.30.26 xml2_1.3.8          vroom_1.6.5         jsonlite_2.0.0      R6_2.6.1
    ## [81] fs_1.6.6