CLIF data layer

The common schema FLAIR is anchored on, and how the library loads it.

FLAIR is anchored on the Common Longitudinal ICU data Format (CLIF) - a critical-care minimum dataset that harmonizes ICU EHR content into a small set of relational tables with standardized vocabularies (mCIDE) for vital-sign, lab, medication, and respiratory categories. Because CLIF standardizes the data elements themselves, a model meets the same coded vocabulary at every site, so FLAIR measures genuine cross-site generalizability.

The tables FLAIR uses

domain	CLIF table(s)
vitals	`vitals`
labs	`labs`
medications	`medication_admin_continuous`, `medication_admin_intermittent`
respiratory support	`respiratory_support`
assessments	`patient_assessments` (e.g. GCS, RASS) - read only by the vendored CLIF→MEDS ETL; no loader
CRRT	`crrt_therapy` - read only by the vendored CLIF→MEDS ETL; no loader
identity / timing	`hospitalization`, `patient`, `adt`
diagnoses	`hospital_diagnosis` (Charlson / Elixhauser in Table 1)
infection	`microbiology_culture` - a supported CLIF 2.1 table, but no shipped task reads it and there is no loader

Two equivalent ways to consume CLIF

Native clifpy tables - the canonical CLIF Python interface, one class per table.
MEDS-based event stream (ELF: Event Language Format) - CLIF's standardized event format for event-based models.

FLAIR supports both; nothing locks you into one representation. CLIF gives harmonized relational ICU tables; ELF converts those tables into a harmonized event stream with shared mCIDE codes, so event-based and transformer models can use the same tokens across sites. See ELF on GitHub.

How FLAIR loads CLIF

The loaders in flair_benchmark/cohort/clif.py wrap clifpy and standardize the load:

clifpy table.from_file(data_directory, filetype, timezone, filters)
        → pandas → polars (pd_to_pl) → strip timezone to local wall-clock

Public loaders (each filters by hospitalization_id - load_patient by patient_id - and, where relevant, category): load_hospitalization, load_patient, load_adt, load_vitals, load_labs, load_medication_admin_continuous / _intermittent, load_respiratory_support, load_hospital_diagnosis. base_icu_cohort(cfg, min_age=18, min_los_days=0.0) returns the adult-ICU starting frame most tasks build from.

Timezone note. clifpy returns tz-aware datetimes typed to cfg["timezone"]; FLAIR's pd_to_pl strips the tz so all datetimes are naive wall-clock already local to the site. A literal anchor like "07:00" in a task therefore means local hospital time.

Stitched hospitalizations

Adjacent hospitalizations less than stitch_time_interval_hours apart (default 6) are merged into a single stitched hospitalization, keyed by hospitalization_join_id (flair_benchmark/cohort/stitch.py). This is the stay-level grain: one entity even when it spans several raw hospitalizations, and a stitched hospitalization is never split across train and test.

Going deeper: clifpy directly

For custom work - pulling raw tables, or computing severity/comorbidity scores - use clifpy directly. FLAIR already uses clifpy's compute_sofa_polars (SOFA), calculate_cci (Charlson), and calculate_elix (Elixhauser) when building each task's Table 1.

← Overview Tasks & task maker →