Python SDK - Working with OMOP medical 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"])  # {"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([201826, 4329847, 1112807])
for concept in result["data"]["concepts"]:
    print(f"{concept['concept_id']}: {concept['concept_name']}")

# With optional parameters
result = client.concepts.batch(
    [201826, 4329847, 1112807],
    include_relationships=True,
    include_synonyms=True,
    include_mappings=True,
    vocabulary_filter=["SNOMED"],
    standard_only=False,  # default
)

# Check summary
print(f"Retrieved: {result['data']['summary']['successful_retrievals']}")
print(f"Failed: {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=["SNOMED"],
    domain_ids=["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"]:
    print(f"{rel['relationship_id']}: {rel['concept_2']['concept_name']}")

# Check pagination
print(f"Page {result['meta']['pagination']['page']} of {result['meta']['pagination']['total_pages']}")
print(f"Total relationships: {result['meta']['pagination']['total_items']}")

# Filter by relationship type and vocabulary
result = client.relationships.get(
    201826,
    relationship_ids=["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=["Condition"]
)

# Basic related concepts
result = client.concepts.related(201826, page_size=10)
for related in result["data"]:
    print(f"{related['concept_name']} ({related['relationship_id']}): {related['relationship_score']:.2f}")

# Filter by relationship type and minimum score
result = client.concepts.related(
    201826,
    relationship_types=["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([201826, 4329847])
for source_id, recommendations in result["data"].items():
    print(f"\nRecommendations for concept {source_id}:")
    for rec in recommendations[:5]:
        print(f"  - {rec['concept_name']} ({rec['vocabulary_id']}) via {rec['relationship_id']}")

# With filters
result = client.concepts.recommended(
    [201826],
    relationship_types=["Has finding", "Associated finding"],
    vocabulary_ids=["SNOMED", "LOINC"],
    domain_ids=["Condition", "Measurement"],
    standard_only=True,
    page_size=50
)

# Access pagination metadata
print(f"Page {result['meta']['pagination']['page']} of {result['meta']['pagination']['total_pages']}")
print(f"Total recommendations: {result['meta']['pagination']['total_items']}")

# Flat format (default) - separate arrays for ancestors and descendants
result = client.hierarchy.get(
    201826,
    max_levels=3,
    vocabulary_ids=["SNOMED"],
)

print(f"Total ancestors: {result['data']['total_ancestors']}")
print(f"Total descendants: {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
print(f"Nodes: {len(nodes)}, Edges: {len(edges)}")

# Advanced filtering options
result = client.hierarchy.get(
    201826,
    domain_ids=["Condition"],
    relationship_types=["Is a"],
    max_results=100,
    include_invalid=False,
)

result = client.hierarchy.ancestors(
    201826,
    max_levels=3,
    vocabulary_ids=["SNOMED"],     # Filter to specific vocabularies
    relationship_types=["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
print(f"Ancestors of: {result['concept_name']}")

# Access ancestors
for ancestor in result["ancestors"]:
    level = ancestor.get("hierarchy_level", 0)
    print(f"{'  ' * level}{ancestor['concept_name']}")

# Access hierarchy summary
print(f"Max depth: {result['hierarchy_summary']['max_hierarchy_depth']}")

# Access pagination
print(f"Page {result['meta']['pagination']['page']} of {result['meta']['pagination']['total_pages']}")

result = client.hierarchy.descendants(
    201826,
    max_levels=2,
    vocabulary_ids=["SNOMED"],     # Filter to specific vocabularies
    relationship_types=["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=["Condition"],      # Filter by domain
    page=1,
    page_size=100,
)

# Access descendants
for descendant in result["descendants"]:
    print(descendant["concept_name"])

# Access pagination
print(f"Page {result['meta']['pagination']['page']} of {result['meta']['pagination']['total_pages']}")

# Get relationship types with pagination
result = client.relationships.types(page=1, page_size=100)

for rel_type in result["data"]:
    print(f"{rel_type['relationship_id']}: {rel_type['relationship_name']}")

# Access pagination
print(f"Total types: {result['meta']['pagination']['total_items']}")

# 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"])  # {"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",
)

# Get all relationships with pagination
result = client.concepts.relationships(201826)
for rel in result["data"]["relationships"]:
    print(f"{rel['relationship_id']}: {rel['concept_2']['concept_name']}")

# Filter by relationship type and vocabulary
result = client.concepts.relationships(
    201826,
    relationship_ids=["Is a", "Subsumes"],
    vocabulary_ids=["SNOMED"],
    standard_only=True,
)

# Include reverse relationships
result = client.concepts.relationships(
    201826,
    include_reverse=True,
    domain_ids=["Condition"],
)