Getting Started with omophub

The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

Introduction

The omophub package provides an R interface to the OMOPHub API for accessing OHDSI ATHENA standardized medical vocabularies. This vignette demonstrates basic usage patterns.

Installation

Install from GitHub:

# install.packages("devtools")
devtools::install_github("omophub/omophub-R")

Authentication

The package requires an API key from OMOPHub.

Set your API key as an environment variable:

Sys.setenv(OMOPHUB_API_KEY = "your_api_key_here")

Or add it to your .Renviron file for persistence:

OMOPHUB_API_KEY=your_api_key_here

Creating a Client

library(omophub)

# Create client (reads API key from environment)
client <- OMOPHubClient$new()

# Or provide API key explicitly
client <- OMOPHubClient$new(api_key = "your_api_key")

# With additional options
client <- OMOPHubClient$new(
  api_key = "your_api_key",
  timeout = 30,
  max_retries = 3,
  vocab_version = "2025.1"
)

Getting Concepts

Retrieve a concept by its OMOP concept ID:

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

Get a concept by vocabulary-specific code:

concept <- client$concepts$get_by_code("SNOMED", "44054006")
print(concept$concept_name)
# [1] "Type 2 diabetes mellitus"

Batch Operations

Retrieve multiple concepts in a single request:

result <- client$concepts$batch(c(201826, 4329847, 1112807))
for (concept in result$concepts) {
  cat(sprintf("%s: %s\n", concept$concept_id, concept$concept_name))
}

Searching Concepts

Basic search:

results <- client$search$basic("diabetes mellitus", page_size = 10)
for (concept in results$data) {
  cat(sprintf("%s: %s\n", concept$concept_id, concept$concept_name))
}

Search with filters:

results <- client$search$basic(
  "heart attack",
  vocabulary_ids = "SNOMED",
  domain_ids = "Condition",
  page_size = 20
)

Semantic Search

Search using natural language queries powered by neural embeddings:

# Natural language search - understands clinical intent
results <- client$search$semantic("high blood sugar levels")
for (r in results$data$results) {
  cat(sprintf("%s (similarity: %.2f)\n", r$concept_name, r$similarity_score))
}

Filter semantic search results:

results <- client$search$semantic(
  "heart attack",
  vocabulary_ids = "SNOMED",
  domain_ids = "Condition",
  threshold = 0.5
)

Fetch all semantic search results with automatic pagination:

all_results <- client$search$semantic_all(
  "chronic kidney disease",
  page_size = 50,
  max_pages = 5,
  progress = TRUE
)
print(nrow(all_results))

Similarity Search

Find concepts similar to a reference concept:

# Find concepts similar to Type 2 diabetes mellitus
similar <- client$search$similar(concept_id = 201826)
for (s in similar$similar_concepts) {
  cat(sprintf("%s (score: %.2f)\n", s$concept_name, s$similarity_score))
}

Search by natural language query with different algorithms:

# Semantic similarity (neural embeddings)
similar <- client$search$similar(
  query = "high blood pressure",
  algorithm = "semantic"
)

# Lexical similarity (string matching)
similar <- client$search$similar(
  query = "high blood pressure",
  algorithm = "lexical"
)

# Hybrid (combined - default)
similar <- client$search$similar(
  query = "high blood pressure",
  algorithm = "hybrid",
  include_scores = TRUE,
  include_explanations = TRUE
)

Autocomplete

Get suggestions for autocomplete:

suggestions <- client$concepts$suggest("diab", page_size = 5)
for (s in suggestions$suggestions) {
  print(s$suggestion)
}

Pagination

Manual Pagination

# First page
results <- client$search$basic("diabetes", page = 1, page_size = 50)

# Check pagination info
print(results$meta$total_items)
print(results$meta$has_next)

# Get next page if available
if (isTRUE(results$meta$has_next)) {
  page2 <- client$search$basic("diabetes", page = 2, page_size = 50)
}

Automatic Pagination

Fetch all results as a tibble:

all_results <- client$search$basic_all(
  "diabetes",
  page_size = 100,
  max_pages = 5,
  progress = TRUE
)

# Results are a tibble
print(nrow(all_results))
print(names(all_results))

Hierarchy Navigation

Get ancestors (parent concepts):

result <- client$hierarchy$ancestors(201826, max_levels = 3)
for (ancestor in result$ancestors) {
  print(ancestor$concept_name)
}

Get descendants (child concepts):

result <- client$hierarchy$descendants(201826, max_levels = 2)
for (descendant in result$descendants) {
  print(descendant$concept_name)
}

Concept Mappings

Find how a concept maps to other vocabularies:

result <- client$mappings$get(201826)
for (mapping in result$mappings) {
  cat(sprintf("%s: %s\n",
              mapping$target_vocabulary_id,
              mapping$target_concept_name))
}

Map to specific vocabularies:

result <- client$mappings$get(
  201826,
  target_vocabulary = "ICD10CM"
)

Error Handling

Use tryCatch to handle errors:

tryCatch(
  {
    concept <- client$concepts$get(999999999)
  },
  omophub_not_found = function(e) {
    message("Concept not found: ", e$message)
  },
  omophub_api_error = function(e) {
    message("API error: ", e$message)
  }
)

Further Resources

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.