Skip to content

alx-heor

Configuration-driven HEOR analytics library for multi-source claims data analysis.

Python 3.10+ License

Why alx-heor?

Working with claims data across multiple vendors (IQVIA, Optum, Komodo, MDV) typically means maintaining separate codebases with duplicated logic. alx-heor solves this with a configuration-driven approach:

  • Multi-Source Support

    One codebase works across IQVIA, Optum, Komodo, and MDV. No more copy-paste between projects.

  • Configuration-Driven

    Column names, table patterns, and business logic are configurable instead of hardcoded.

  • Memory-Efficient

    Optimized for large datasets with batching, streaming, and smart SQL generation.

  • Well-Documented

    Comprehensive docstrings, type hints, and usage examples for every function.

Quick Example

Build a gMG cohort with diagnosis criteria, required medications, and enrollment requirements:

from alx_heor.database import RedshiftConnection
from alx_heor.cohort import (
    get_cohort, CohortCriteria, DiagnosisCriteria,
    MedicationCriteria, EnrollmentCriteria,
)

conn = RedshiftConnection().connect()

result = get_cohort(
    conn,
    source="iqvia",
    schema="iqvia_pharmetrics_2024q3",
    criteria=CohortCriteria(
        # Primary diagnosis: gMG with 2+ claims, 30 days apart
        primary_diagnosis=DiagnosisCriteria(
            codes=["G700", "G7000", "G7001"],
            min_count=2,
            days_apart=30,
            label="gMG diagnosis",
        ),
        # Require C5 inhibitor post-index
        required_medications=[
            MedicationCriteria(
                generic_names=["eculizumab", "ravulizumab"],
                window_start=0,
                label="C5 inhibitor post-index",
            ),
        ],
        # Enrollment: 6 months pre, 12 months post
        enrollment=EnrollmentCriteria(
            months_before=6,
            months_after=12,
        ),
        # Adults only
        min_age=18,
    ),
    start_year=2015,
    end_year=2024,
)

print(result.summary())

df_cohort = result.df_cohort
print(f"Final cohort: {len(df_cohort):,} patients")

Output: 

Attrition Table
============================================================
gMG diagnosis: 45,231
Adults (18+): 42,105 (-3,126, 93.1%)
Valid sex: 41,892 (-213, 99.5%)
C5 inhibitor post-index: 8,234 (-33,658, 19.7%)
Continuous enrollment: 6,891 (-1,343, 83.7%)
============================================================
Final cohort: 6,891 patients

Installation

# Basic install
pip install -e .

# With development tools
pip install -e ".[dev,docs]"

Supported Data Sources

Source Database Status
IQVIA Pharmetrics Redshift Supported
Optum DOD Redshift Planned
Komodo Snowflake Planned
Loopback Redshift Planned
MDV (Japan) Redshift Planned

Modules

Module Description
cohort High-level cohort building with attrition tracking
claims Claims data processing and filtering
enrollment Enrollment validation and censoring logic
medications Medication lookups and classification
database Database connectors (Redshift, Snowflake)
config Data source configurations and column mappings

Next Steps