OmnipathR uses a local file-based cache to avoid redundant downloads.
Every resource downloaded through the package’s download machinery is
automatically stored in the cache directory and looked up on subsequent
requests. The cache keeps an inventory in a JSON file (cache.json) and
stores downloaded data as RDS files alongside it.
By default the cache lives under the platform’s user cache directory
(e.g. ~/.cache/OmnipathR on Linux). You can query or change it at any
time:
library(OmnipathR)
# Current cache directory
omnipath_get_cachedir()
# Change to a custom location
omnipath_set_cachedir("/tmp/my_omnipathr_cache")
# Reset to default
omnipath_set_cachedir()Each unique download is identified by a cache key: a SHA-1 hash of the URL, HTTP POST parameters and payload. A cache record stores:
key – the SHA-1 identifierurl – the original URLpost – HTTP POST parameters, if anypayload – HTTP body payload, if anyext – file extension (derived from the URL)versions – a named list of version entriesA single cache record can have multiple versions, numbered sequentially. Each version tracks:
number – version identifier (character: “1”, “2”, …)path – absolute path to the cached filedl_started – timestamp when the download starteddl_finished – timestamp when the download completedstatus – one of unknown, started, ready, failed, deletedWhen a resource is re-downloaded, a new version is appended rather than overwriting the existing one.
cache.json)All cache records are persisted in cache.json inside the cache directory.
This file is read into memory before any cache operation and written back
afterwards. A lock file (cache.lock) prevents concurrent writes.
Downloads are cached automatically by the package’s download functions. You can also interact with the cache directly:
# Save an R object into the cache
omnipath_cache_save(my_data, url = "https://example.com/data.tsv")
# Load it back
my_data <- omnipath_cache_load(url = "https://example.com/data.tsv")omnipath_cache_load returns NULL when no cached version is available.
The loaded object carries an origin = "cache" attribute so you can tell
whether data came from the network or the cache.
Find cache entries by URL pattern (regular expression):
# Find all cached BioMart queries
omnipath_cache_search("biomart")
# Find all cached OmniPath downloads
omnipath_cache_search("omnipathdb\\.org")Remove specific entries by key or URL:
# By URL
omnipath_cache_remove(url = "https://example.com/data.tsv")
# By key
key <- omnipath_cache_key(url = "https://example.com/data.tsv")
omnipath_cache_remove(key = key)Remove entries by age or status:
# Remove everything older than 30 days
omnipath_cache_remove(max_age = 30)
# Remove failed downloads
omnipath_cache_remove(status = "failed")
# Keep only the latest version of each entry
omnipath_cache_remove(only_latest = TRUE)Wipe the entire cache:
omnipath_cache_remove(wipe = TRUE)
# or equivalently:
omnipath_cache_wipe()Two cleanup functions keep the cache tidy:
omnipath_cache_clean_db() – removes database entries whose files have
been deleted outside the cache system (e.g. manually).omnipath_cache_clean() – removes orphaned files in the cache directory
that are not tracked in the database.omnipath_cache_autoclean() – keeps only the latest ready version of
each entry and removes the rest.Keys are deterministic SHA-1 hashes. The same URL and POST parameters always produce the same key:
omnipath_cache_key(url = "https://omnipathdb.org/interactions")
# [1] "95ee739b50bbfea2c48e5c86a64525084a1dab30"POST parameters and payloads are included in the hash, so different queries to the same endpoint receive different cache keys.
Cache operations that modify cache.json use a file-based lock
(cache.lock) to prevent corruption from concurrent access. If a lock is
left behind after a crash, you can remove it manually:
omnipath_unlock_cache_db()## R version 4.6.0 RC (2026-04-17 r89917)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 24.04.4 LTS
##
## Matrix products: default
## BLAS: /home/biocbuild/bbs-3.23-bioc/R/lib/libRblas.so
## LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.12.0 LAPACK version 3.12.0
##
## locale:
## [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C LC_TIME=en_GB
## [4] LC_COLLATE=C LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
## [7] LC_PAPER=en_US.UTF-8 LC_NAME=C LC_ADDRESS=C
## [10] LC_TELEPHONE=C LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
##
## time zone: America/New_York
## tzcode source: system (glibc)
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] OmnipathR_3.99.0 BiocStyle_2.39.0
##
## loaded via a namespace (and not attached):
## [1] xfun_0.57 bslib_0.10.0 httr2_1.2.2 websocket_1.4.4 processx_3.8.7
## [6] tzdb_0.5.0 vctrs_0.7.3 tools_4.6.0 ps_1.9.3 generics_0.1.4
## [11] parallel_4.6.0 curl_7.0.0 tibble_3.3.1 RSQLite_2.4.6 blob_1.3.0
## [16] pkgconfig_2.0.3 R.oo_1.27.1 checkmate_2.3.4 readxl_1.4.5 lifecycle_1.0.5
## [21] compiler_4.6.0 stringr_1.6.0 progress_1.2.3 chromote_0.5.1 htmltools_0.5.9
## [26] sass_0.4.10 yaml_2.3.12 tidyr_1.3.2 later_1.4.8 pillar_1.11.1
## [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.5 digest_0.6.39 stringi_1.8.7
## [41] dplyr_1.2.1 purrr_1.2.2 bookdown_0.46 fastmap_1.2.0 cli_3.6.6
## [46] logger_0.4.1 magrittr_2.0.5 utf8_1.2.6 XML_3.99-0.23 withr_3.0.2
## [51] readr_2.2.0 prettyunits_1.2.0 promises_1.5.0 backports_1.5.1 rappdirs_0.3.4
## [56] bit64_4.8.0 lubridate_1.9.5 timechange_0.4.0 rmarkdown_2.31 httr_1.4.8
## [61] igraph_2.3.0 bit_4.6.0 otel_0.2.0 cellranger_1.1.0 R.methodsS3_1.8.2
## [66] hms_1.1.4 memoise_2.0.1 evaluate_1.0.5 knitr_1.51 tcltk_4.6.0
## [71] rlang_1.2.0 Rcpp_1.1.1-1 glue_1.8.1 DBI_1.3.0 selectr_0.5-1
## [76] BiocManager_1.30.27 xml2_1.5.2 vroom_1.7.1 jsonlite_2.0.0 R6_2.6.1
## [81] fs_2.1.0