omophub: R Client for the 'OMOPHub' Medical Vocabulary API

Description

Provides an R interface to the 'OMOPHub' API for accessing 'OHDSI ATHENA' standardized medical vocabularies. Supports concept search, vocabulary exploration, hierarchy navigation, relationship queries, and concept mappings with automatic pagination and rate limiting.

Provides an R interface to the OMOPHub API for accessing OHDSI ATHENA standardized medical vocabularies. Supports concept search, vocabulary exploration, hierarchy navigation, relationship queries, and concept mappings with automatic pagination and rate limiting.

Main Client

The main entry point is the OMOPHubClient R6 class which provides access to all API resources:

library(omophub)
client <- OMOPHubClient$new()

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

# Get a specific concept
concept <- client$concepts$get(201826)

Authentication

Set your API key using one of these methods:

• Environment variable: OMOPHUB_API_KEY

• Explicit argument: OMOPHubClient$new(api_key = "your_key")

• Keyring: set_api_key("your_key", store = "keyring")

Resources

The client provides access to these resources:

• concepts: Concept lookup and batch operations

• search: Basic and advanced concept search

• vocabularies: Vocabulary listing and details

• domains: Domain listing and concept filtering

• hierarchy: Ancestor and descendant navigation

• relationships: Concept relationships

• mappings: Concept mappings between vocabularies

Author(s)

Maintainer: Alex Chen alex@omophub.com [copyright holder]

Other contributors:

• Observational Health Data Science and Informatics [copyright holder]

See Also

Useful links:

• https://github.com/omopHub/omophub-R

• https://docs.omophub.com

• https://omophub.github.io/omophub-R/

• https://omophub.com

• Report bugs at https://github.com/omopHub/omophub-R/issues

Package Attach Hook

Description

Package Attach Hook

Usage

.onAttach(libname, pkgname)

Arguments

Package Load Hook

Description

Package Load Hook

Usage

.onLoad(libname, pkgname)

Arguments

Concepts Resource

Description

R6 class providing access to concept operations.

Value

A list containing the concept data.

A list containing the concept data with optional relationships and synonyms.

A list with concepts and any failures.

A list with suggestions and pagination metadata.

Related concepts with relationship scores.

Relationships data.

Recommendations grouped by source concept ID with pagination metadata.

Methods

Public methods

• ConceptsResource$new()

• ConceptsResource$get()

• ConceptsResource$get_by_code()

• ConceptsResource$batch()

• ConceptsResource$suggest()

• ConceptsResource$related()

• ConceptsResource$relationships()

• ConceptsResource$recommended()

• ConceptsResource$print()

• ConceptsResource$clone()

Method new()

Create a new ConceptsResource.

Usage

ConceptsResource$new(base_req)

Arguments

Method get()

Get a concept by ID.

Usage

ConceptsResource$get(
  concept_id,
  include_relationships = FALSE,
  include_synonyms = FALSE,
  include_hierarchy = FALSE,
  vocab_release = NULL
)

Arguments

Method get_by_code()

Get a concept by vocabulary and code.

Usage

ConceptsResource$get_by_code(
  vocabulary_id,
  concept_code,
  include_relationships = FALSE,
  include_synonyms = FALSE,
  include_hierarchy = FALSE,
  vocab_release = NULL
)

Arguments

Method batch()

Get multiple concepts by IDs.

Usage

ConceptsResource$batch(
  concept_ids,
  include_relationships = FALSE,
  include_synonyms = FALSE,
  include_mappings = FALSE,
  vocabulary_filter = NULL,
  standard_only = TRUE
)

Arguments

Method suggest()

Get concept suggestions (autocomplete).

Usage

ConceptsResource$suggest(
  query,
  page = 1,
  page_size = 10,
  vocabulary_ids = NULL,
  domain_ids = NULL,
  vocab_release = NULL
)

Arguments

Method related()

Get related concepts.

Usage

ConceptsResource$related(
  concept_id,
  relationship_types = NULL,
  min_score = NULL,
  page_size = 20,
  vocab_release = NULL
)

Arguments

Method relationships()

Get concept relationships.

Usage

ConceptsResource$relationships(
  concept_id,
  relationship_ids = NULL,
  vocabulary_ids = NULL,
  domain_ids = NULL,
  include_invalid = FALSE,
  standard_only = FALSE,
  include_reverse = FALSE,
  vocab_release = NULL
)

Arguments

Method recommended()

Get recommended concepts using OHDSI Phoebe algorithm.

Usage

ConceptsResource$recommended(
  concept_ids,
  relationship_types = NULL,
  vocabulary_ids = NULL,
  domain_ids = NULL,
  standard_only = TRUE,
  include_invalid = FALSE,
  page = 1,
  page_size = 100
)

Arguments

Method print()

Print resource information.

Usage

ConceptsResource$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

ConceptsResource$clone(deep = FALSE)

Arguments

Domains Resource

Description

R6 class providing access to domain operations.

Value

Domain list.

Paginated concepts.

Methods

Public methods

• DomainsResource$new()

• DomainsResource$list()

• DomainsResource$concepts()

• DomainsResource$print()

• DomainsResource$clone()

Method new()

Create a new DomainsResource.

Usage

DomainsResource$new(base_req)

Arguments

Method list()

List all domains.

Usage

DomainsResource$list(include_stats = FALSE)

Arguments

Method concepts()

Get concepts in a domain.

Usage

DomainsResource$concepts(
  domain_id,
  vocabulary_ids = NULL,
  standard_only = FALSE,
  include_invalid = FALSE,
  page = 1,
  page_size = 50
)

Arguments

Method print()

Print resource information.

Usage

DomainsResource$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

DomainsResource$clone(deep = FALSE)

Arguments

Hierarchy Resource

Description

R6 class providing access to hierarchy operations (ancestors and descendants).

Value

For flat format: ancestors, descendants arrays with level/total counts. For graph format: nodes and edges arrays for visualization.

Ancestors with hierarchy summary.

Descendants with hierarchy summary.

Methods

Public methods

• HierarchyResource$new()

• HierarchyResource$get()

• HierarchyResource$ancestors()

• HierarchyResource$descendants()

• HierarchyResource$print()

• HierarchyResource$clone()

Method new()

Create a new HierarchyResource.

Usage

HierarchyResource$new(base_req)

Arguments

Method get()

Get complete concept hierarchy (ancestors and descendants).

Usage

HierarchyResource$get(
  concept_id,
  format = "flat",
  vocabulary_ids = NULL,
  domain_ids = NULL,
  max_levels = 10,
  max_results = NULL,
  relationship_types = NULL,
  include_invalid = FALSE
)

Arguments

Method ancestors()

Get concept ancestors.

Usage

HierarchyResource$ancestors(
  concept_id,
  vocabulary_ids = NULL,
  max_levels = NULL,
  relationship_types = NULL,
  include_paths = FALSE,
  include_distance = TRUE,
  include_invalid = FALSE,
  page = 1,
  page_size = 100
)

Arguments

Method descendants()

Get concept descendants.

Usage

HierarchyResource$descendants(
  concept_id,
  vocabulary_ids = NULL,
  max_levels = 10,
  relationship_types = NULL,
  include_distance = TRUE,
  include_paths = FALSE,
  include_invalid = FALSE,
  domain_ids = NULL,
  page = 1,
  page_size = 100
)

Arguments

Method print()

Print resource information.

Usage

HierarchyResource$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

HierarchyResource$clone(deep = FALSE)

Arguments

Mappings Resource

Description

R6 class providing access to mapping operations.

Value

Mappings for the concept.

Mapping results with summary.

Methods

Public methods

• MappingsResource$new()

• MappingsResource$get()

• MappingsResource$map()

• MappingsResource$print()

• MappingsResource$clone()

Method new()

Create a new MappingsResource.

Usage

MappingsResource$new(base_req)

Arguments

Method get()

Get mappings for a concept.

Usage

MappingsResource$get(
  concept_id,
  target_vocabulary = NULL,
  include_invalid = FALSE,
  vocab_release = NULL
)

Arguments

Method map()

Map concepts to a target vocabulary.

Usage

MappingsResource$map(
  source_concepts,
  target_vocabulary,
  mapping_type = NULL,
  include_invalid = FALSE,
  vocab_release = NULL
)

Arguments

Method print()

Print resource information.

Usage

MappingsResource$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

MappingsResource$clone(deep = FALSE)

Arguments

OMOPHub API Client

Description

R6 class for interacting with the OMOPHub vocabulary service. Provides access to OHDSI ATHENA standardized medical vocabularies.

Details

The client provides access to these resources:

• concepts: Concept lookup and batch operations

• search: Basic and advanced concept search

• vocabularies: Vocabulary listing and details

• domains: Domain listing and concept filtering

• hierarchy: Ancestor and descendant navigation

• relationships: Concept relationships

• mappings: Concept mappings between vocabularies

Value

A new OMOPHubClient object.

Active bindings

Methods

Public methods

• OMOPHubClient$new()

• OMOPHubClient$print()

• OMOPHubClient$clone()

Method new()

Create a new OMOPHub client.

Usage

OMOPHubClient$new(
  api_key = NULL,
  base_url = NULL,
  timeout = 30,
  max_retries = 3,
  vocab_version = NULL
)

Arguments

Method print()

Print client information.

Usage

OMOPHubClient$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

OMOPHubClient$clone(deep = FALSE)

Arguments

Examples

## Not run: 
# Create client (uses OMOPHUB_API_KEY env var)
client <- OMOPHubClient$new()

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

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

# Get a specific concept
concept <- client$concepts$get(201826)

# Use specific vocabulary version
client <- OMOPHubClient$new(vocab_version = "2025.1")

## End(Not run)

Relationships Resource

Description

R6 class providing access to relationship operations.

Value

Relationships data with pagination metadata.

Relationship types with pagination metadata.

Methods

Public methods

• RelationshipsResource$new()

• RelationshipsResource$get()

• RelationshipsResource$types()

• RelationshipsResource$print()

• RelationshipsResource$clone()

Method new()

Create a new RelationshipsResource.

Usage

RelationshipsResource$new(base_req)

Arguments

Method get()

Get relationships for a concept.

Usage

RelationshipsResource$get(
  concept_id,
  relationship_ids = NULL,
  vocabulary_ids = NULL,
  domain_ids = NULL,
  include_invalid = FALSE,
  standard_only = FALSE,
  include_reverse = FALSE,
  page = 1,
  page_size = 100,
  vocab_release = NULL
)

Arguments

Method types()

Get available relationship types from the OMOP CDM.

Usage

RelationshipsResource$types(page = 1, page_size = 100)

Arguments

Method print()

Print resource information.

Usage

RelationshipsResource$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

RelationshipsResource$clone(deep = FALSE)

Arguments

Search Resource

Description

R6 class providing access to search operations.

Value

Search results with pagination.

A tibble of all matching concepts.

Search results with facets and metadata.

Autocomplete suggestions.

Methods

Public methods

• SearchResource$new()

• SearchResource$basic()

• SearchResource$basic_all()

• SearchResource$advanced()

• SearchResource$autocomplete()

• SearchResource$print()

• SearchResource$clone()

Method new()

Create a new SearchResource.

Usage

SearchResource$new(base_req)

Arguments

Method basic()

Basic concept search.

Usage

SearchResource$basic(
  query,
  vocabulary_ids = NULL,
  domain_ids = NULL,
  concept_class_ids = NULL,
  standard_concept = NULL,
  include_synonyms = FALSE,
  include_invalid = FALSE,
  min_score = NULL,
  exact_match = FALSE,
  page = 1,
  page_size = 20,
  sort_by = NULL,
  sort_order = NULL
)

Arguments

Method basic_all()

Fetch all search results with automatic pagination.

Usage

SearchResource$basic_all(
  query,
  vocabulary_ids = NULL,
  domain_ids = NULL,
  page_size = 100,
  max_pages = Inf,
  progress = TRUE,
  ...
)

Arguments

Method advanced()

Advanced concept search with facets.

Usage

SearchResource$advanced(
  query,
  vocabulary_ids = NULL,
  domain_ids = NULL,
  concept_class_ids = NULL,
  standard_concepts_only = FALSE,
  include_invalid = FALSE,
  relationship_filters = NULL,
  page = 1,
  page_size = 20
)

Arguments

Method autocomplete()

Get autocomplete suggestions.

Usage

SearchResource$autocomplete(
  query,
  vocabulary_ids = NULL,
  domains = NULL,
  max_suggestions = 10
)

Arguments

Method print()

Print resource information.

Usage

SearchResource$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

SearchResource$clone(deep = FALSE)

Arguments

Vocabularies Resource

Description

R6 class providing access to vocabulary operations.

Value

Paginated vocabulary list.

Vocabulary details including vocabulary_id, vocabulary_name, vocabulary_reference, vocabulary_version, vocabulary_concept_id.

Vocabulary statistics.

Domain statistics including concept counts and class breakdown.

List of all available domains with domain_id, domain_name, and description.

List of all available concept classes with concept_class_id, concept_class_name, and concept_class_concept_id.

Paginated concepts.

Methods

Public methods

• VocabulariesResource$new()

• VocabulariesResource$list()

• VocabulariesResource$get()

• VocabulariesResource$stats()

• VocabulariesResource$domain_stats()

• VocabulariesResource$domains()

• VocabulariesResource$concept_classes()

• VocabulariesResource$concepts()

• VocabulariesResource$print()

• VocabulariesResource$clone()

Method new()

Create a new VocabulariesResource.

Usage

VocabulariesResource$new(base_req)

Arguments

Method list()

List all vocabularies.

Usage

VocabulariesResource$list(
  include_stats = FALSE,
  include_inactive = FALSE,
  sort_by = "name",
  sort_order = "asc",
  page = 1,
  page_size = 100
)

Arguments

Method get()

Get vocabulary details.

Usage

VocabulariesResource$get(vocabulary_id)

Arguments

Method stats()

Get vocabulary statistics.

Usage

VocabulariesResource$stats(vocabulary_id)

Arguments

Method domain_stats()

Get statistics for a specific domain within a vocabulary.

Usage

VocabulariesResource$domain_stats(vocabulary_id, domain_id)

Arguments

Method domains()

Get all standard OHDSI domains.

Usage

VocabulariesResource$domains()

Method concept_classes()

Get all concept classes.

Usage

VocabulariesResource$concept_classes()

Method concepts()

Get concepts in a vocabulary.

Usage

VocabulariesResource$concepts(
  vocabulary_id,
  search = NULL,
  standard_concept = "all",
  include_invalid = FALSE,
  include_relationships = FALSE,
  include_synonyms = FALSE,
  sort_by = "name",
  sort_order = "asc",
  page = 1,
  page_size = 20
)

Arguments

Method print()

Print resource information.

Usage

VocabulariesResource$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

VocabulariesResource$clone(deep = FALSE)

Arguments

Abort with OMOPHub API Error

Description

Abort with OMOPHub API Error

Usage

abort_api_error(status, message, endpoint, call = rlang::caller_env())

Arguments

Abort with Authentication Error

Description

Abort with Authentication Error

Usage

abort_auth_error(message, call = rlang::caller_env())

Arguments

Abort with Rate Limit Error

Description

Abort with Rate Limit Error

Usage

abort_rate_limit(retry_after = NULL, call = rlang::caller_env())

Arguments

Abort with Validation Error

Description

Abort with Validation Error

Usage

abort_validation(message, arg = NULL, call = rlang::caller_env())

Arguments

Convert Boolean to API String

Description

Convert Boolean to API String

Usage

bool_to_str(x)

Arguments

Value

"true" or "false" string, or NULL if x is NULL.

Build Base OMOPHub Request

Description

Creates an httr2 request object with authentication, rate limiting, and retry logic configured.

Usage

build_request(
  base_url,
  api_key,
  timeout = 30,
  max_retries = 3,
  vocab_version = NULL
)

Arguments

Value

An httr2 request object.

Extract Error Message from API Response

Description

Extract Error Message from API Response

Usage

extract_error_message(resp)

Arguments

Value

A character string with the error message.

Extract Pagination Metadata

Description

Extracts pagination metadata from an API response.

Usage

extract_pagination(response)

Arguments

Value

A list with pagination fields.

Get OMOPHub API Key

Description

Retrieves the OMOPHub API key from multiple sources in priority order:

1. Explicit argument

2. OMOPHUB_API_KEY environment variable

3. System keyring (if keyring package is installed)

Usage

get_api_key(key = NULL)

Arguments

Value

A character string containing the API key.

Examples

## Not run: 
# From environment variable
Sys.setenv(OMOPHUB_API_KEY = "your_api_key")
key <- get_api_key()

# Explicit key
key <- get_api_key("your_api_key")

## End(Not run)

Check if API Key is Available

Description

Checks whether an OMOPHub API key is available without throwing an error.

Usage

has_api_key()

Value

TRUE if an API key is available, FALSE otherwise.

Check if Error is Transient (Retryable)

Description

Check if Error is Transient (Retryable)

Usage

is_transient_error(resp)

Arguments

Value

TRUE if the error is transient and should be retried.

Join List Elements for Query Parameter

Description

Join List Elements for Query Parameter

Usage

join_params(x, sep = ",")

Arguments

Value

A single comma-separated string, or NULL if x is NULL/empty.

Create OMOPHub Concepts Result

Description

Creates an S3 object for concept search results.

Usage

new_omophub_concepts(data, meta = list())

Arguments

Value

An omophub_concepts S3 object.

Create OMOPHub Hierarchy Result

Description

Create OMOPHub Hierarchy Result

Usage

new_omophub_hierarchy(data, meta = list(), type = "hierarchy")

Arguments

Value

An omophub_hierarchy S3 object.

Create OMOPHub Mappings Result

Description

Create OMOPHub Mappings Result

Usage

new_omophub_mappings(data, meta = list())

Arguments

Value

An omophub_mappings S3 object.

Create OMOPHub Relationships Result

Description

Create OMOPHub Relationships Result

Usage

new_omophub_relationships(data, meta = list())

Arguments

Value

An omophub_relationships S3 object.

Create OMOPHub Vocabularies Result

Description

Create OMOPHub Vocabularies Result

Usage

new_omophub_vocabularies(data, meta = list())

Arguments

Value

An omophub_vocabularies S3 object.

Fetch All Paginated Results

Description

Fetches all pages of results and combines them into a single tibble.

Usage

paginate_all(fetch_fn, page_size = 100, max_pages = Inf, progress = TRUE)

Arguments

Value

A tibble containing all fetched results.

Create Lazy Pagination Iterator

Description

Creates an iterator that fetches pages on demand.

Usage

paginate_lazy(fetch_fn, page_size = 100)

Arguments

Value

An iterator object with next_page() and has_more() methods.

Perform GET Request

Description

Perform GET Request

Usage

perform_get(base_req, endpoint, query = NULL)

Arguments

Value

Parsed JSON response. For paginated endpoints, returns a list with data (the results) and meta (pagination info). For single-item endpoints, returns the unwrapped data directly.

Perform POST Request

Description

Perform POST Request

Usage

perform_post(base_req, endpoint, body = NULL, query = NULL)

Arguments

Value

Parsed JSON response (unwrapped from data field if present).

Set OMOPHub API Key

Description

Stores the OMOPHub API key in the specified location.

Usage

set_api_key(key, store = c("env", "keyring"))

Arguments

Value

Invisibly returns TRUE on success.

Examples

## Not run: 
# Store in environment (current session only)
set_api_key("your_api_key")

# Store securely in keyring (persistent)
set_api_key("your_api_key", store = "keyring")

## End(Not run)

Validate Concept ID

Description

Validate Concept ID

Usage

validate_concept_id(concept_id, arg = "concept_id", call = rlang::caller_env())

Arguments

Validate Page Parameters

Description

Validate Page Parameters

Usage

validate_pagination(
  page,
  page_size,
  max_page_size = 1000,
  call = rlang::caller_env()
)

Arguments