OMOPHub R SDK

R client for the OMOPHub API, providing access to OHDSI ATHENA standardized medical vocabularies.

Installation

You can install the development version of omophub from GitHub:

# install.packages("pak")
pak::pak("omopHub/omophub-R")

Authentication

Set your API key using one of these methods:

# Option 1: Environment variable (recommended)
Sys.setenv(OMOPHUB_API_KEY = "your_api_key")

# Option 2: Use the helper function
library(omophub)
set_api_key("your_api_key")

# Option 3: Store securely in system keyring
set_api_key("your_api_key", store = "keyring")

Quick Start

library(omophub)

# Create a client
client <- OMOPHubClient$new()

# Search for concepts
results <- client$search$basic("diabetes")
results$data

# Get a specific concept
concept <- client$concepts$get(201826)
concept$concept_name
# [1] "Type 2 diabetes mellitus"

# Get concept by vocabulary code
concept <- client$concepts$get_by_code("SNOMED", "44054006")

# Batch lookup multiple concepts
batch <- client$concepts$batch(c(201826, 320128, 4329847))

# Get concept ancestors (hierarchy)
ancestors <- client$hierarchy$ancestors(201826)

# Get concept mappings to another vocabulary
mappings <- client$mappings$get(201826, target_vocabularies = "ICD10CM")

Resources

The client provides access to these resources:

Pagination

For large result sets, use automatic pagination:

# Fetch all results automatically
all_results <- client$search$basic_all("diabetes", page_size = 100)

# Or paginate manually
page1 <- client$search$basic("diabetes", page = 1, page_size = 20)
page2 <- client$search$basic("diabetes", page = 2, page_size = 20)

Vocabulary Versioning

Specify a vocabulary version when creating the client:

client <- OMOPHubClient$new(vocab_version = "2025.2")

Error Handling

The package uses structured error classes:

tryCatch(
  {
    result <- client$concepts$get(999999999)
  },
  omophub_api_error = function(e) {
    message("API error: ", conditionMessage(e))
  },
  omophub_auth_error = function(e) {
    message("Authentication failed")
  }
)

Examples

The package includes comprehensive examples in inst/examples/:

Run an example:

# After installing the package
example_path <- system.file("examples", "basic_usage.R", package = "omophub")
source(example_path)

Documentation

• Full Documentation
• API Reference
• Examples

License

MIT License - see LICENSE for details.

Support

• GitHub Issues
• Documentation