> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omophub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# R SDK - Working with OMOP medical concepts

> Work with OMOP medical concepts in the OMOPHub R SDK - retrieve, search, and inspect concept details, synonyms, and relationships for R analytics code.

## Get a Concept

Retrieve a concept by its OMOP concept ID:

```r theme={null}
concept <- client$concepts$get(201826)
print(concept$concept_name)   # "Type 2 diabetes mellitus"
print(concept$vocabulary_id)  # "SNOMED"
print(concept$domain_id)      # "Condition"
```

## Get by Vocabulary Code

Look up a concept using a vocabulary-specific code:

```r theme={null}
# Get SNOMED concept by its code
concept <- client$concepts$get_by_code("SNOMED", "44054006")
print(concept$concept_name)  # "Type 2 diabetes mellitus"

# Get ICD-10-CM concept
concept <- client$concepts$get_by_code("ICD10CM", "E11")

# Include synonyms and relationships
concept <- client$concepts$get_by_code(
  "SNOMED",
  "44054006",
  include_synonyms = TRUE,
  include_relationships = TRUE
)
print(concept$synonyms)       # List of synonym names
print(concept$relationships)  # list(parents = [...], children = [...])

# Specify vocabulary release version
concept <- client$concepts$get_by_code(
  "SNOMED",
  "44054006",
  vocab_release = "2025.2"
)
```

## Batch Get Concepts

Retrieve multiple concepts in a single request (max 100):

```r theme={null}
# Basic batch request
result <- client$concepts$batch(c(201826, 4329847, 1112807))
for (concept in result$data$concepts) {
  cat(sprintf("%s: %s\n", concept$concept_id, concept$concept_name))
}

# With optional parameters
result <- client$concepts$batch(
  c(201826, 4329847, 1112807),
  include_relationships = TRUE,
  include_synonyms = TRUE,
  include_mappings = TRUE,
  vocabulary_filter = c("SNOMED"),
  standard_only = FALSE  # default
)

# Check summary
cat(sprintf("Retrieved: %d\n", result$data$summary$successful_retrievals))
cat(sprintf("Failed: %d\n", result$data$summary$failed_retrievals))
```

## Autocomplete Suggestions

Get concept suggestions for autocomplete functionality:

```r theme={null}
# Basic suggestions with pagination
result <- client$concepts$suggest("diab", page_size = 10)
for (concept in result$data) {
  print(concept$concept_name)
}

# Check pagination metadata
print(result$meta$pagination$total_items)
print(result$meta$pagination$has_next)

# Filter by vocabulary and domain
result <- client$concepts$suggest(
  "diab",
  vocabulary_ids = c("SNOMED"),
  domain_ids = c("Condition"),
  page_size = 20
)

# Navigate pages
result <- client$concepts$suggest("diab", page = 2, page_size = 10)
```

## Get Relationships

Get relationships for a concept:

```r theme={null}
# Get all relationships with pagination
result <- client$relationships$get(201826)
for (rel in result$data$relationships) {
  cat(sprintf("%s: %s\n", rel$relationship_id, rel$concept_2$concept_name))
}

# Check pagination
cat(sprintf("Page %d of %d\n",
  result$meta$pagination$page,
  result$meta$pagination$total_pages
))
cat(sprintf("Total relationships: %d\n", result$meta$pagination$total_items))

# Filter by relationship type and vocabulary
result <- client$relationships$get(
  201826,
  relationship_ids = c("Is a", "Subsumes"),
  vocabulary_ids = "SNOMED",
  standard_only = TRUE,
  page = 1,
  page_size = 50
)

# Include reverse relationships
result <- client$relationships$get(
  201826,
  include_reverse = TRUE,
  domain_ids = c("Condition")
)
```

## Navigate Hierarchy

### Get Complete Hierarchy

Get both ancestors and descendants in a single request:

```r theme={null}
# Flat format (default) - separate arrays for ancestors and descendants
result <- client$hierarchy$get(
  201826,
  max_levels = 3,
  vocabulary_ids = c("SNOMED")
)

cat(sprintf("Total ancestors: %d\n", result$data$total_ancestors))
cat(sprintf("Total descendants: %d\n", result$data$total_descendants))

# Graph format for visualization (D3.js, Cytoscape, etc.)
graph <- client$hierarchy$get(
  201826,
  format = "graph",
  max_levels = 3
)

nodes <- graph$data$nodes  # Concept nodes
edges <- graph$data$edges  # Relationship edges
cat(sprintf("Nodes: %d, Edges: %d\n", length(nodes), length(edges)))

# Advanced filtering options
result <- client$hierarchy$get(
  201826,
  domain_ids = c("Condition"),
  relationship_types = c("Is a"),
  max_results = 100,
  include_invalid = FALSE
)
```

#### Hierarchy Get Parameters

| Parameter            | Type      | Default  | Description                         |
| -------------------- | --------- | -------- | ----------------------------------- |
| `concept_id`         | integer   | required | The concept ID                      |
| `format`             | character | "flat"   | Response format ("flat" or "graph") |
| `vocabulary_ids`     | character | NULL     | Filter to specific vocabularies     |
| `domain_ids`         | character | NULL     | Filter to specific domains          |
| `max_levels`         | integer   | 10       | Maximum hierarchy levels (max 20)   |
| `max_results`        | integer   | NULL     | Maximum results per direction       |
| `relationship_types` | character | NULL     | Relationship types to follow        |
| `include_invalid`    | logical   | TRUE     | Include deprecated/invalid concepts |

### Get Ancestors

Find parent concepts in the hierarchy:

```r theme={null}
result <- client$hierarchy$ancestors(
  201826,
  max_levels = 3,
  vocabulary_ids = c("SNOMED"),     # Filter to specific vocabularies
  relationship_types = c("Is a"),   # Relationship types to follow
  include_distance = TRUE,          # Include hierarchy_level field
  include_paths = FALSE,            # Include path information
  include_invalid = FALSE,          # Exclude deprecated concepts
  page = 1,
  page_size = 100
)

# Access source concept info
cat(sprintf("Ancestors of: %s\n", result$concept_name))

# Access ancestors
for (ancestor in result$ancestors) {
  level <- ancestor$hierarchy_level %||% 0
  cat(sprintf("%s%s\n", strrep("  ", level), ancestor$concept_name))
}

# Access hierarchy summary
cat(sprintf("Max depth: %d\n", result$hierarchy_summary$max_hierarchy_depth))

# Access pagination
cat(sprintf("Page %d of %d\n",
  result$meta$pagination$page,
  result$meta$pagination$total_pages
))
```

#### Ancestors Parameters

| Parameter            | Type      | Default  | Description                                    |
| -------------------- | --------- | -------- | ---------------------------------------------- |
| `concept_id`         | integer   | required | The concept ID                                 |
| `vocabulary_ids`     | character | NULL     | Filter to specific vocabularies                |
| `max_levels`         | integer   | NULL     | Maximum hierarchy levels to traverse           |
| `relationship_types` | character | NULL     | Relationship types to follow (default: "Is a") |
| `include_paths`      | logical   | FALSE    | Include path information                       |
| `include_distance`   | logical   | TRUE     | Include hierarchy\_level field                 |
| `include_invalid`    | logical   | TRUE     | Include deprecated/invalid concepts            |
| `page`               | integer   | 1        | Page number                                    |
| `page_size`          | integer   | 100      | Results per page                               |

### Get Descendants

Find child concepts in the hierarchy:

```r theme={null}
result <- client$hierarchy$descendants(
  201826,
  max_levels = 2,
  vocabulary_ids = c("SNOMED"),     # Filter to specific vocabularies
  relationship_types = c("Is a"),   # Relationship types to follow
  include_distance = TRUE,          # Include hierarchy_level field
  include_paths = FALSE,            # Include path information
  include_invalid = FALSE,          # Exclude deprecated concepts
  domain_ids = c("Condition"),      # Filter by domain
  page = 1,
  page_size = 100
)

# Access descendants
for (descendant in result$descendants) {
  print(descendant$concept_name)
}

# Access pagination
cat(sprintf("Page %d of %d\n",
  result$meta$pagination$page,
  result$meta$pagination$total_pages
))
```

#### Descendants Parameters

| Parameter            | Type      | Default  | Description                                    |
| -------------------- | --------- | -------- | ---------------------------------------------- |
| `concept_id`         | integer   | required | The concept ID                                 |
| `vocabulary_ids`     | character | NULL     | Filter to specific vocabularies                |
| `max_levels`         | integer   | 10       | Maximum hierarchy levels (max 20)              |
| `relationship_types` | character | NULL     | Relationship types to follow (default: "Is a") |
| `include_distance`   | logical   | TRUE     | Include hierarchy\_level field                 |
| `include_paths`      | logical   | FALSE    | Include path information                       |
| `include_invalid`    | logical   | TRUE     | Include deprecated/invalid concepts            |
| `domain_ids`         | character | NULL     | Filter by domains                              |
| `page`               | integer   | 1        | Page number                                    |
| `page_size`          | integer   | 100      | Results per page                               |

## Get Relationship Types

Get available relationship types from the OMOP CDM:

```r theme={null}
# Get relationship types with pagination
result <- client$relationships$types(page = 1, page_size = 100)

for (rel_type in result$data) {
  cat(sprintf("%s: %s\n", rel_type$relationship_id, rel_type$relationship_name))
}

# Access pagination
cat(sprintf("Total types: %d\n", result$meta$pagination$total_items))
```

## With Options

Include synonyms, relationships, hierarchy, and specify vocabulary release:

```r theme={null}
# Get concept with synonyms
concept <- client$concepts$get(
  201826,
  include_synonyms = TRUE
)

# Get concept with synonyms and relationships
concept <- client$concepts$get(
  201826,
  include_synonyms = TRUE,
  include_relationships = TRUE
)
print(concept$relationships)  # list(parents = [...], children = [...])

# Get concept with hierarchy information
concept <- client$concepts$get(
  201826,
  include_hierarchy = TRUE
)
print(concept$hierarchy)  # Ancestor/descendant summary

# Specify vocabulary release version
concept <- client$concepts$get(
  201826,
  vocab_release = "2025.2"
)
```

### Parameters

| Parameter               | Type      | Default  | Description                                  |
| ----------------------- | --------- | -------- | -------------------------------------------- |
| `concept_id`            | integer   | required | The OMOP concept ID                          |
| `include_relationships` | logical   | FALSE    | Include related concepts (parents/children)  |
| `include_synonyms`      | logical   | FALSE    | Include concept synonyms                     |
| `include_hierarchy`     | logical   | FALSE    | Include hierarchy information                |
| `vocab_release`         | character | NULL     | Specific vocabulary release (e.g., "2025.2") |

## Get Concept Relationships

Get detailed relationships for a concept with filtering options:

```r theme={null}
# Get all relationships
result <- client$concepts$relationships(201826)
for (rel in result$data$relationships) {
  cat(sprintf("%s: %s\n", rel$relationship_id, rel$concept_2$concept_name))
}

# Filter by relationship type and vocabulary
result <- client$concepts$relationships(
  201826,
  relationship_ids = c("Is a", "Subsumes"),
  vocabulary_ids = "SNOMED",
  standard_only = TRUE
)

# Include reverse relationships
result <- client$concepts$relationships(
  201826,
  include_reverse = TRUE,
  domain_ids = c("Condition")
)
```

### Relationships Parameters

| Parameter          | Type      | Default  | Description                                     |
| ------------------ | --------- | -------- | ----------------------------------------------- |
| `concept_id`       | integer   | required | The concept ID                                  |
| `relationship_ids` | character | NULL     | Filter by relationship type IDs                 |
| `vocabulary_ids`   | character | NULL     | Filter by target vocabulary IDs                 |
| `domain_ids`       | character | NULL     | Filter by target domain IDs                     |
| `include_invalid`  | logical   | TRUE     | Include relationships to invalid concepts       |
| `standard_only`    | logical   | FALSE    | Only include relationships to standard concepts |
| `include_reverse`  | logical   | FALSE    | Include reverse relationships                   |
| `vocab_release`    | character | NULL     | Specific vocabulary release version             |

## Get Related Concepts

Find concepts related to a given concept:

```r theme={null}
# Basic related concepts
result <- client$concepts$related(201826, page_size = 10)
for (related in result$data) {
  cat(sprintf("%s (%s): score %.2f\n",
    related$concept_name,
    related$relationship_id,
    related$relationship_score
  ))
}

# Filter by relationship type and minimum score
result <- client$concepts$related(
  201826,
  relationship_types = c("Is a", "Maps to"),
  min_score = 0.5,
  page_size = 20
)

# Specify vocabulary release
result <- client$concepts$related(
  201826,
  vocab_release = "2025.1"
)
```

## Get Recommended Concepts

Get curated concept recommendations using the OHDSI Phoebe algorithm:

```r theme={null}
# Basic recommendations for diabetes-related concepts
result <- client$concepts$recommended(c(201826, 4329847))
for (source_id in names(result$data)) {
  cat(sprintf("\nRecommendations for concept %s:\n", source_id))
  for (rec in head(result$data[[source_id]], 5)) {
    cat(sprintf("  - %s (%s) via %s\n",
      rec$concept_name,
      rec$vocabulary_id,
      rec$relationship_id
    ))
  }
}

# With filters
result <- client$concepts$recommended(
  c(201826),
  relationship_types = c("Has finding", "Associated finding"),
  vocabulary_ids = c("SNOMED", "LOINC"),
  domain_ids = c("Condition", "Measurement"),
  standard_only = TRUE,
  page_size = 50
)

# Access pagination metadata
cat(sprintf("Page %d of %d\n",
  result$meta$pagination$page,
  result$meta$pagination$total_pages
))
cat(sprintf("Total recommendations: %d\n", result$meta$pagination$total_items))
```