Concepts

concept <- client$concepts$get(201826)
print(concept$concept_name)   # "Type 2 diabetes mellitus"
print(concept$vocabulary_id)  # "SNOMED"
print(concept$domain_id)      # "Condition"

# 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"
)

# 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 = TRUE  # default
)

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

# 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 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")
)

# 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)))

result <- client$hierarchy$ancestors(
  201826,
  max_levels = 3,
  vocabulary_ids = c("SNOMED"),  # Filter to specific vocabularies
  include_distance = TRUE,        # Include hierarchy_level field
  include_invalid = FALSE         # Exclude deprecated concepts
)

# 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))

result <- client$hierarchy$descendants(
  201826,
  max_levels = 2,
  vocabulary_ids = c("SNOMED"),  # Filter to specific vocabularies
  include_distance = TRUE,        # Include hierarchy_level field
  include_invalid = FALSE,        # Exclude deprecated concepts
  domain_ids = c("Condition")     # Filter by domain
)

# 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
))

# 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 = [...])

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

# 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"
)

# 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))