athena-client 1.0.18

An unofficial Python SDK for interacting with the OHDSI Athena Concepts API.

athena-client

An unofficial Python SDK for interacting with the OHDSI Athena Concepts API. Easily search, explore, and analyze medical concepts without any additional setup.
Developed by Alvaro A. Alvarez P. ([e-mail]).
This project is provided as-is, without warranty of any kind.

Looking for advanced concept exploration, mapping, and best practices? See the Concept Exploration Guide for a comprehensive tutorial on robust usage, advanced workflows, and real-world examples.

Responsible Usage Notice: Please use this package responsibly. Avoid making excessive or automated requests to the Athena API, as this may result in your IP being rate-limited or blocked by the API provider. Always use filters and limits where possible, and respect the terms of service of the OHDSI Athena API.

Installation

Basic Installation (Recommended)

For standard use, install with:

pip install athena-client

This provides essential Athena API functionalities like concept search and exploration without database integration.

Alternatively, explicitly specify:

pip install "athena-client[core]"

Both methods offer the same functionality.

---

Quick Start

from athena_client import Athena

# Initialize Athena client (uses public Athena API by default)
athena = Athena()

# Search for concepts
results = athena.search("aspirin")

# Different ways to handle results
concept_list = results.all()
top_three = results.top(3)
as_json = results.to_json()
as_df = results.to_df()

# Detailed information for a specific concept
details = athena.details(concept_id=1127433)

# Concept relationships
relationships = athena.relationships(concept_id=1127433)

# Concept graph
graph = athena.graph(concept_id=1127433, depth=3)

# Comprehensive summary
summary = athena.summary(concept_id=1127433)

---

CLI Quick Start

Athena CLI allows rapid concept search and exploration:

athena search "aspirin" --limit 3 --output json
athena details 1127433
athena relationships 1127433
athena graph 1127433 --depth 3
athena summary 1127433

---

Optional Extras

Additional functionalities can be installed separately:

pip install athena-client[cli]      # Command-line interface
pip install athena-client[async]    # Async client support
pip install athena-client[pandas]   # pandas DataFrame support
pip install athena-client[yaml]     # YAML format support
pip install athena-client[crypto]   # HMAC authentication
pip install athena-client[all]      # All optional dependencies

---

Experimental: Database Integration (Advanced Users)

Warning: Database integration features are experimental, subject to change, and may encounter errors.

Experimental database integration allows validation and concept set generation against your local OMOP database. Use these features cautiously.

Installation for Database Support

For specific database integrations:

• PostgreSQL:

  pip install "athena-client[postgres]"
  

• Google BigQuery:

  pip install "athena-client[bigquery]"
  

Reducing Dependency Conflicts (Advanced)

To minimize dependency issues:

• Use specific extras when installing.
• For BigQuery integration, use Python 3.9 and SQLAlchemy < 1.5.0.

Database Usage Example

import asyncio
from athena_client import Athena

DB_CONNECTION_STRING = "postgresql://user:pass@localhost/omop_cdm"

async def main():
    athena = Athena()
    concept_set = await athena.generate_concept_set(
        query="Type 2 Diabetes",
        db_connection_string=DB_CONNECTION_STRING
    )
    print(concept_set)

asyncio.run(main())

---

Experimental CLI Database Example

export OMOP_DB_CONNECTION="postgresql://user:pass@localhost/omop"
athena generate-set "Type 2 Diabetes" --output json

---

Troubleshooting Common Issues

• Dependency installation problems: Ensure Python version compatibility and correct extras.
• PostgreSQL build errors: Install PostgreSQL development tools (brew install postgresql on macOS).
• BigQuery SQLAlchemy conflicts: Only use Python 3.9 with BigQuery integration.

---

Exporting CLI Results to Files (JSON, YAML, CSV)

You can export CLI search results to various formats:

athena search "aspirin" --output json | tail -n +2 > aspirin_concepts.json
athena search "aspirin" --output yaml | tail -n +2 > aspirin_concepts.yaml
athena search "aspirin" --output csv  | tail -n +2 > aspirin_concepts.csv

Note: The tail -n +2 removes warning lines (such as large query warnings) to ensure the output file is valid for the chosen format.

---

Version Compatibility

• Python: >= 3.9, < 3.13
• SQLAlchemy: >= 1.4.0 (BigQuery limited to <1.5.0)
• pandas: >= 1.3.0, < 3.0.0
• pydantic: >= 2.0.0
• httpx: >= 0.18.0
• cryptography: >= 36.0.0