Architecture

Design principles

Native Sentinel CDM support

YAML connectors map data to FDA Sentinel CDM v8.2.2 table structures with standardized code types ("10" ICD-10, "C4" CPT, "ND" NDC).

On-the-fly transformation

SQL is generated dynamically at query time and runs directly on raw data — no intermediate table management.

Unified composable API

Three interoperable layers: Table/Column → EventFrame → Cohort. Shared IR and one compiler to SQLAlchemy. Lazy until .to_df() / .to_sql() / .attrition().

Database agnostic

Single API across PostgreSQL, Redshift, Snowflake, BigQuery, and MySQL. Dialect-specific SQL is handled internally.

Layers

Layer 2  Cohort          .entry() .include() .exclude() .attrition()
Layer 1  EventFrame      .matching() .occurring() .first_per_patient()
Layer 0  Table / Column  dx.code.startswith("E11") & …
         IR (_internal/ir) → compiler → sqlalchemy.Select

Preferred path: YAML connector → Database → author at Layer 0/1/2 → shared IR → one compiler → SQLAlchemy → DataFrame.

Core components

Component	Location	Role
Connector system	`encodebox/connectors/`	YAML → Pydantic models → registry
Database	`encodebox/database.py`	Bound connector + domain accessors
EventFrame	`encodebox/frame/`	Layer 1 verbs
Cohort	`encodebox/cohort/`	Layer 2 study definition + attrition
IR / compiler	`encodebox/_internal/ir/`	Sole SQLAlchemy compilation path
Legacy shims	`encodebox/_compat.py`	Deprecation wrappers for old helpers

Getting started

Data model

Guides

API reference

Design principles

Layers

Core components

Consecutive gaps

Transparent SQL

​Design principles

​Layers

​Core components

​Consecutive gaps

​Transparent SQL

Design principles

Layers

Core components

Consecutive gaps

Transparent SQL