Skip to contents

Get started

Source: vignettes/Ratdb.Rmd
Ratdb.Rmd

Rat.db is an R package designed to simplify access to the Stockholm International Peace Research Institute (SIPRI) Arms Transfers Database (ATDB). It provides functions for retrieving arms transfer data efficiently, allowing researchers and analysts to work with SIPRI’s data in a structured and reproducible manner in R. The package handles API requests, formats responses into tidy data, and offers caching options to optimize performance.

⚙️ Installation

You can install the development version of Rat.db from GitHub with:

# install.packages("devtools")
devtools::install_github("datapumpernickel/Rat.db")

💲🔁️ Usage

Retrieving Arms Transfer Data

The core function of Rat.db is atdb_get_data(), which retrieves arms transfer data from SIPRI’s ATDB.

library(Rat.db)
atdb_get_data(verbose = FALSE, start_year, end_year, cache = TRUE)

Parameters:

  • verbose: Logical. If TRUE, prints additional details about the query process. Default is FALSE.
  • start_year: Numeric. The start of the date range to query.
  • end_year: Numeric. The end of the date range to query.
  • cache: Logical. If TRUE, caches the response to avoid redundant requests. Default is FALSE.
  • tidy_cols Logical. If TRUE, formats the column headers to a tidy format. Default is TRUE

Example Usage: 

# Retrieve data from 2000 to 2020, using cache
arms_data <- atdb_get_data(start_year = 2000, end_year = 2020)

# Retrieve data without using cache
arms_data_no_cache <- atdb_get_data(start_year = 2000, end_year = 2020, cache = TRUE)

🗄️ Caching Behavior

By default, Rat.db uses a disk-based caching system to store API responses. This prevents redundant queries to the SIPRI database, improving performance and reducing server load. However, keep in mind that this could prevent you from getting the most recent data, if the SIPRI data has been renewed, but you are still using cached data. This is why caching is by default disabled.

Default Cache Settings:

  • Maximum Cache Size: 1GB (1024 * 1024^2 bytes)
  • Maximum Cache Age: 1 year (606024*365 seconds)
  • Maximum Cached Entries: Unlimited (Inf)

Changing Cache Settings:

Users can override the default cache settings by setting environment variables before loading the package:

Sys.setenv(RATDB_CACHE_MAX_SIZE = "500 * 1024^2")  # Set max cache size to 500MB
Sys.setenv(RATDB_CACHE_MAX_AGE = "60*60*24*180")  # Set max cache age to 180 days
Sys.setenv(RATDB_CACHE_MAX_N = "500")             # Limit cache to 500 entries

Clearing the Cache

If needed, users can manually prune the cache by running:

cachem::cache_disk(dir = tools::R_user_dir('Rat.db', which = 'cache'))$prune()

This will remove expired entries, ensuring that outdated data is not used in queries. However, this also happens automatically with every request where cache = TRUE.

You can also run destroy() to fully delete the cache. Note however, this requires a session restart to work with the package again afterwards.

cachem::cache_disk(dir = tools::R_user_dir('Rat.db', which = 'cache'))$destroy()