FLAIR 101

A practical, top-to-bottom guide for an external user - a method developer, a site data steward, or someone authoring a new benchmark task.

FLAIR is a federated ICU benchmark: the code travels to the data, and only aggregate JSON ever leaves a site. You develop and self-evaluate against the public MIMIC-CLIF dataset; the same code later runs unmodified behind a hospital's firewall.

What FLAIR is

The model-to-data loop. A model is built and validated against public MIMIC-CLIF, reviewed, then shipped to each consortium site. Each site runs it against its own CLIF tables and returns a small bundle of aggregate-only JSON. Patient-level rows never move.

The package:

package	CLI	what it gives you
`flair-benchmark`	`flair`	the library: task catalog, cohort builder, feature extractors, report builder

Privacy guarantees baked into the library:

No patient rows leave a site - outputs are JSON aggregates only.
Cell-count suppression: any count < 10 is written as "<10" in table1.json.
Demographic subgroups with n < 10 are dropped entirely from the fairness block of hospitalization_level.json.

Install & first config

The PyPI release is coming soon (v1):

pip install flair-benchmark          # core library + `flair` CLI
pip install "flair-benchmark[viz]"   # add matplotlib for local sanity-check PNGs

Scaffold the two config files from the CLI:

flair init-config --out .
# writes clif_config.json + feature_config.yaml (pass --force to overwrite)

clif_config.json tells FLAIR where your CLIF data lives and how to read it:

field	meaning
`site`	`"mimic"` triggers the deterministic random 75/25 split (MIMIC dates are shifted); any other name gets the temporal 75/25 split and is used as a label/prefix
`data_directory`	root folder of your CLIF parquet/CSV files
`filetype`	`"parquet"` or `"csv"`
`timezone`	the site's local IANA time zone - stripped to local wall-clock
`stitch_time_interval_hours`	gap (default `6`) below which hospitalizations merge into one stitched hospitalization
`cache_directory`	where intermediate artifacts are cached

End-to-end quickstart

# 0. install + scaffold
pip install "flair-benchmark[viz]"
flair init-config --out .
#   …edit clif_config.json: set data_directory + timezone…

# 1. see what tasks exist
flair list-tasks

# 2. build a cohort  ->  cohort.parquet + cohort.table1.json
flair load-task icu_daily_mortality \
  --clif-config clif_config.json --out cohort.parquet

# 3. engineer features  ->  ELF medication event parquet, cut per stay at its
#    latest feature_cutoff_dttm (filter each row to its own cutoff before training;
#    for vitals/labs/resp call clifpy's create_wide_dataset yourself)
flair fe-meds --feature-config feature_config.yaml \
  --task cohort.parquet --out meds.parquet

# 4. …train YOUR model -> preds.parquet
#    (hospitalization_join_id, prediction_id, split, label, y_prob)…

# 5. build the report bundle  (continuous | episodic)
flair build-report preds.parquet --task icu_daily_mortality \
  --cohort cohort.parquet --mode continuous --out ./report/

Follow the sidebar for the detail on each step.

CLIF data layer →