OmnipathR Cache System

Overview

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.

Cache directory

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

Data structures

Cache records

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 identifier
  • url – the original URL
  • post – HTTP POST parameters, if any
  • payload – HTTP body payload, if any
  • ext – file extension (derived from the URL)
  • versions – a named list of version entries

Versions

A single cache record can have multiple versions, numbered sequentially. Each version tracks:

  • number – version identifier (character: “1”, “2”, …)
  • path – absolute path to the cached file
  • dl_started – timestamp when the download started
  • dl_finished – timestamp when the download completed
  • status – one of unknown, started, ready, failed, deleted

When a resource is re-downloaded, a new version is appended rather than overwriting the existing one.

The cache database (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.

Core operations

Saving and loading

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.

Searching

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

Removing entries

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

Cleanup

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.

Cache key generation

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.

Locking

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

Session info

## R version 4.6.0 (2026-04-24)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 24.04.4 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               LC_TIME=en_US.UTF-8       
##  [4] LC_COLLATE=en_US.UTF-8     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: Etc/UTC
## tzcode source: system (glibc)
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] OmnipathR_4.1.0  BiocStyle_2.41.0
## 
## loaded via a namespace (and not attached):
##  [1] xfun_0.58           bslib_0.11.0        httr2_1.2.2         tzdb_0.5.0          vctrs_0.7.3        
##  [6] tools_4.6.0         generics_0.1.4      parallel_4.6.0      curl_7.1.0          tibble_3.3.1       
## [11] RSQLite_3.53.1      blob_1.3.0          pkgconfig_2.0.3     R.oo_1.27.1         checkmate_2.3.4    
## [16] readxl_1.5.0        lifecycle_1.0.5     compiler_4.6.0      stringr_1.6.0       progress_1.2.3     
## [21] htmltools_0.5.9     sys_3.4.3           buildtools_1.0.0    sass_0.4.10         yaml_2.3.12        
## [26] later_1.4.8         pillar_1.11.1       crayon_1.5.3        jquerylib_0.1.4     tidyr_1.3.2        
## [31] R.utils_2.13.0      cachem_1.1.0        sessioninfo_1.2.3   zip_2.3.3           tidyselect_1.2.1   
## [36] rvest_1.0.5         digest_0.6.39       stringi_1.8.7       dplyr_1.2.1         purrr_1.2.2        
## [41] maketools_1.3.2     fastmap_1.2.0       cli_3.6.6           logger_0.4.2        magrittr_2.0.5     
## [46] utf8_1.2.6          XML_3.99-0.23       readr_2.2.0         withr_3.0.2         prettyunits_1.2.0  
## [51] backports_1.5.1     rappdirs_0.3.4      bit64_4.8.2         lubridate_1.9.5     timechange_0.4.0   
## [56] rmarkdown_2.31      httr_1.4.8          igraph_2.3.2        bit_4.6.0           otel_0.2.0         
## [61] cellranger_1.1.0    R.methodsS3_1.8.2   hms_1.1.4           memoise_2.0.1       evaluate_1.0.5     
## [66] knitr_1.51          tcltk_4.6.0         rlang_1.2.0         Rcpp_1.1.1-1.1      glue_1.8.1         
## [71] DBI_1.3.0           selectr_0.5-1       BiocManager_1.30.27 xml2_1.5.2          vroom_1.7.1        
## [76] jsonlite_2.0.0      R6_2.6.1            fs_2.1.0