Metadata-Version: 2.4
Name: athena-client
Version: 1.0.17
Summary: Production-ready Python SDK for the OHDSI Athena Concepts API
Author: Alvaro A. Alvarez P. 
License-Expression: MIT
Project-URL: Homepage, https://github.com/username/athena-client
Project-URL: Documentation, https://athena-client.readthedocs.io
Project-URL: Issues, https://github.com/username/athena-client/issues
Requires-Python: <3.13,>=3.9
Description-Content-Type: text/markdown
Requires-Dist: orjson>=3.9.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings
Requires-Dist: httpx>=0.18.0
Requires-Dist: backoff>=2.0.0
Requires-Dist: pandas<3.0.0,>=1.3.0
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=10.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: cryptography>=36.0.0
Requires-Dist: psycopg2-binary>=2.9.0
Provides-Extra: core
Requires-Dist: orjson>=3.9.0; extra == "core"
Requires-Dist: pydantic>=2.0.0; extra == "core"
Requires-Dist: pydantic-settings; extra == "core"
Requires-Dist: httpx>=0.18.0; extra == "core"
Requires-Dist: backoff>=2.0.0; extra == "core"
Provides-Extra: all
Requires-Dist: athena-client[async]; extra == "all"
Requires-Dist: athena-client[pandas]; extra == "all"
Requires-Dist: athena-client[cli]; extra == "all"
Requires-Dist: athena-client[yaml]; extra == "all"
Requires-Dist: athena-client[crypto]; extra == "all"
Requires-Dist: athena-client[db]; extra == "all"
Provides-Extra: async
Requires-Dist: httpx>=0.18.0; extra == "async"
Requires-Dist: backoff>=2.0.0; extra == "async"
Provides-Extra: pandas
Requires-Dist: pandas<3.0.0,>=1.3.0; extra == "pandas"
Provides-Extra: cli
Requires-Dist: click>=8.0.0; extra == "cli"
Requires-Dist: rich>=10.0.0; extra == "cli"
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"
Provides-Extra: crypto
Requires-Dist: cryptography>=36.0.0; extra == "crypto"
Provides-Extra: postgres
Requires-Dist: sqlalchemy>=1.4.0; extra == "postgres"
Requires-Dist: psycopg2-binary>=2.9.0; extra == "postgres"
Provides-Extra: bigquery
Requires-Dist: sqlalchemy>=1.4.0; extra == "bigquery"
Requires-Dist: sqlalchemy-bigquery; extra == "bigquery"
Provides-Extra: db
Requires-Dist: athena-client[postgres]; extra == "db"
Requires-Dist: athena-client[bigquery]; extra == "db"
Provides-Extra: dev
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: cyclonedx-bom>=3.15.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pip-audit>=2.6; extra == "dev"
Requires-Dist: pytest>=8.2; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-asyncio[mode-auto]>=0.23; extra == "dev"
Requires-Dist: hypothesis>=6.103; extra == "dev"
Requires-Dist: vcrpy>=6.0; extra == "dev"
Requires-Dist: rich>=13.7; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
Requires-Dist: bandit>=1.7.5; extra == "dev"
Requires-Dist: cyclonedx-python-lib>=5.2.0; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Requires-Dist: pandas-stubs; extra == "dev"
Requires-Dist: sqlalchemy-stubs; extra == "dev"
Requires-Dist: hatch; extra == "dev"
Requires-Dist: hatchling; extra == "dev"

# athena-client

[![SBOM](https://img.shields.io/badge/SBOM-available-blue)](sbom.json)

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. (alvaro1@stanford.edu).  
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](CONCEPT_EXPLORATION_GUIDE.md) for a comprehensive tutorial on robust usage, advanced workflows, and real-world examples.

## Installation

### Basic Installation (Recommended)

For standard use, install with:

```bash
pip install athena-client
```

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

Alternatively, explicitly specify:

```bash
pip install "athena-client[core]"
```

Both methods offer the same functionality.

---

## Quick Start

```python
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:

```bash
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:

```bash
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:

  ```bash
  pip install "athena-client[postgres]"
  ```

* Google BigQuery:

  ```bash
  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

```python
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

```bash
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:

```bash
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

---

This README provides clarity on basic use, separates experimental features, and outlines recommended practices clearly.
