CLIF Data Dictionary 3.0.0

Notes:

• ADT represents the patient’s physical location, NOT the patient “status”.
• Procedural areas and operating rooms should be mapped to Procedural. Pre/Intra/Post-procedural/OR EHR data (such as anesthesia flowsheet records from Labs, Vitals, Scores, Respiratory Support) are not currently represented in CLIF.
• room_id and bed_id are free-text identifiers carried through from source EHR data — no standardization across sites is required. bed_id is optional.

Example:

Notes:

• Sites will need to identify their code status orders. Additionally, sites may have separate orders for “comfort measures only” not found within the code status order that, if available, should be pulled to map it to allow_natural_death.

Example:

Example:

Notes:

• If a patient is discharged to Home/Hospice, then discharge_category == hospice.
• Mortality Outcomes: Mortality is identified by discharge_category == "expired". Some studies also include discharge_category == "hospice" (i.e., both “expired” and “hospice”) when defining death outcomes.
• The geographical indicators (zipcode_nine_digit, zipcode_five_digit, census_block_code, census_block_group_code, census_tract, state_code, county_code) should be added if they are available in your source dataset. zipcode_nine_digit is preferred over zipcode_five_digit, and census_block_code is ideal for census based indicators. The choice of geographical indicators may differ depending on the project.
• If a patient is transferred between different hospitals within a health system, a new hospitalization_id should be created.
• If a patient is initially seen in an ER in hospital A and then admitted to inpatient status in hospital B, one hospitalization_id should be created for data from both stays.
• A hospitalization_joined_id can also be created from a CLIF table from contiguous hospitalization_ids.
• Geo-based Indices (ADI, SVI):
  • ADI: Calculate the Area Deprivation Index at the census block-group level. Provide census_block_group_code when possible, or zipcode_nine_digit (9-digit ZIP) that can be cross-walked to a block group. Avoid using 5-digit ZIP or census-tract values for ADI—they are not validated and will add error.
  • SVI: The Social Vulnerability Index is published at census_tract (full 11-digit FIPS).

Example:

Notes:

• All lab values must be reported using the lab’s reference units linked above in permissible values. Only the listed reference units are permissible for respective lab categories in the CLIF labs table. Sites must ensure that any raw laboratory values are converted to the reference units during the ETL process. Entries with other units must be transformed prior to loading into CLIF.
• The lab_value field often has non-numeric entries that are useful to make project-specific decisions. A site may choose to keep the lab_value field as a character and create a new field lab_value_numeric that only parses the character field to extract the numeric part of the string.
• For fluid-panel and source-specific labs, the analyte name is stored in lab_category (e.g. ldh, creatinine, amylase) and the fluid it was run on is captured in lab_specimen_category (plasma_blood, pleural, peritoneal, urine, bal). The same lab_category can therefore appear with different specimen sources and order panels — the panel is recorded in lab_order_category.

Example:

Example:

Notes:

• Include combination medications when mapping medication names to respective categories. Eg. ACETAMIN-CALCIUM-MAG-CAFFEINE ORAL -> acetaminophen
• Include trial drugs when mapping medication names to respective categories… Eg. ACETAMINOPHEN (IRB 140122) 325 MG ORAL TAB -> acetaminophen

Example:

Notes:

• Continuous medications are included in this table when given as boluses.
• The med_dose_unit constraint is per-category — sites cannot mix units within a single med_category.

Example:

Example:

Example:

Example:

Example:

Example:

Notes:

Expected setting values for each device_category and mode_category

• device_category == “imv”

E = Expected ventilator setting for the mode, P = possible ventilator setting for the mode.

• device_category == “nippv”

mode_category is ps_or_cpap and the fio2_set, peep_set, and either pressure_support_set OR peak_inspiratory_pressure_set (IPAP) is required.

• device_category == “cpap”

mode_category is ps_or_cpap and the fio2_set and peep_set are required.

• device_category == “hfnc”

mode_category is NA and the fio2_set and lpm_set are required.

• device_category == “face_mask”

mode_category is NA
lpm_set is required.
fio2_set is possible.

• device_category == “trach_collar” or “nasal_cannula”

mode_category is NA
lpm_set is required

Example:

Notes:

• measured_dttm is optional. It captures when the vital was actually measured at the bedside, which can differ from recorded_dttm (the EHR entry time) — for example, vitals written down on paper and entered later at shift change. Sites whose source data does not distinguish the two timestamps may omit this column or leave it null.

Example:

Notes:

• The revision_id is rank-ordered per (hospitalization_id, note_id) by revision_dttm ascending
• The triplet (hospitalization_id, note_id, revision_id) matches the [hospitalization_id]__[note_id]_[revision_id].txt naming convention used for just-in-time provisioned note text

Example:

Notes:

• This table, together with misc_icu_orders, replaces the former key_icu_orders table (issue #218). Both tables share identical fields and differ only in the kinds of orders each contains.
• order_status_category standardizes the order lifecycle to sent, completed, resulted, or canceled.

Example:

Notes:

• The input_category field maps input_name to a controlled vocabulary defined in the input_category mCIDE dictionary
• input_category values roll up into input_group for higher-level aggregation (e.g., iv_fluids, blood_products, nutrition)

Example:

Notes:

• measurement_value is interpreted in the units defined by measurement_category (mmHg for pressures, L/min for cardiac output, L/min/m² for indices, etc.).
• The measurement_category field standardizes invasive hemodynamic data:

Example:

Notes:

• The table covers ECMO, LVAD, and RVAD support, distinguished by support_category.
• The setting_name / setting_category / setting_value tuple replaces the prior wide-format columns (flow, sweep_set, fdO2_set, control_parameter_*). To represent multiple settings recorded at the same recorded_dttm, emit one row per setting.
• config_category permissible values are conditional on support_category (e.g., cp, 2_5, 5, 5_5, rp, rp_flex apply to lvad & device_category == impella; heartware, heartmate2, heartmate3 apply to lvad; central applies to lvad or rvad).

Example:

Example:

Example:

Notes:

• This table, together with consult_orders, replaces the former key_icu_orders table (issue #218).
• order_status_category standardizes the order lifecycle to sent, completed, resulted, or canceled.

Example:

Notes:

• Each model_id row is unique. Sites should retain historical rows for retired model versions and use is_live to flag the active deployment(s).
• model_category is the mCIDE-controlled cross-site identifier; sites map their local model_name to this standardized vendor_modelname snake_case label.
• Official alert thresholds are intentionally not a column. Threshold tiers vary by site, change over time, and are often multi-tier (green/yellow/red); they are documented as remarks in the model_category mCIDE entry and are otherwise managed at the project / config-file level.
• is_live distinguishes models firing live alerts to clinicians from models running silently / in shadow mode.

Example:

Notes:

• output_value must be a positive number. output_unit reports its unit: mL for quantitative fluid volumes, or occurrences for unmeasured/counted events (e.g., number of emesis episodes)
• lda_id links an output to a specific line, drain, or airway (LDA) device when attributable to one (e.g., a Foley, JP drain, or chest tube)
• Ultrafiltration output from dialysis should reflect net ultrafiltration only (do not include removal of replacement fluid in CVVH or CVVHDF)

Example:

Example:

Notes:

• Distinguishing IHD from IUF: Intermittent hemodialysis (ihd) and isolated ultrafiltration (iuf) share the same operational parameters in this table; the distinguishing feature is the dialysate bath. IHD uses a dialysate bath containing potassium and calcium (recorded in potassium_bath and calcium_bath), whereas IUF does not. These two fields therefore capture the difference between IHD and IUF.
• Fluid volumes: This table records RRT machine settings and rates, not fluid volumes. Net ultrafiltration (fluid removed from the patient) is captured in the output table under output_group = ultrafiltration, and replacement/dialysate fluids delivered during RRT are captured in the input table under input_group = renal_replacement_fluids.

RRT Modalities and Parameter Usage:

Example:

Notes:

• Join scores to model_registry on model_id to resolve the model name, category, version, and live status.
• A row does not imply that an alert was triggered. Threshold-derived alert categories are project-specific and resolved in code, not stored here.
• All recorded_dttm values must be timezone-aware UTC.
• Sites with very large score volumes are encouraged to partition the on-disk parquet by model_id (or model_id and date) to keep query costs manageable.

Example:

Notes:

• Composite key is (hospitalization_id, airway_id). airway_id maps to the Epic LDA ID where applicable.
• removed_dttm is null if the airway is still in place at the time of data extraction.
• airway_category is mCIDE-controlled — see clif_airway_categories.csv for the canonical permissible values.
• airway_size is the device size as recorded (e.g., 7.5 mm internal diameter for an ETT, 8 Fr for an NPA). Unit conventions follow the source EHR.
• is_cuffed is 1 if the device has an inflatable cuff (typical for ETTs and most tracheostomy tubes), 0 otherwise (typical for NPA/OPA).

Example:

Example:

Notes:

• Composite key is (hospitalization_id, drain_id). drain_id maps to the Epic LDA ID where applicable.
• removed_dttm is null if the drain is still in place at the time of data extraction.
• drain_category is mCIDE-controlled — see clif_drain_categories.csv for the canonical permissible values.
• anatomical_location is unstandardized free text (e.g., “right pleural”, “subhepatic”) because drain placement sites are too heterogeneous to enumerate.

Example:

Notes:

• Grain is one row per ED encounter; together (hospitalization_id, ed_encounter_id) identifies a row. A hospitalization may have multiple ED encounters if the patient bounced back, but typically there is one.
• triage_system_category and triage_acuity_category are separated so non-ESI sites (e.g., CTAS-based) can still encode acuity on the common 5-level scale.
• ed_disposition_category (final ED outcome) and ed_destination_category (physical destination after the ED) are separated so transfers, observation admissions, and AMA / LWBS outcomes are not conflated with destination.
• ed_destination_category permissibles intentionally align with hospitalization.discharge_category so post-ED transitions and final hospital discharges share a vocabulary.
• ed_observation_status is a binary flag. Observation duration, ED length of stay, and boarding duration should be derived from ed_arrival_dttm / ed_disposition_dttm / ed_departure_dttm rather than persisted.

Example:

Notes:

• Composite key is (hospitalization_id, line_id). line_id maps to the Epic LDA ID where applicable.
• removed_dttm is null if the line is still in place at the time of data extraction.
• line_category and line_site are mCIDE-controlled — see clif_line_categories.csv and clif_line_sites.csv for the canonical permissible values.
• line_site is optional and typically null for lines that don’t have a meaningful laterality (e.g., a PIV in the antecubital fossa not coded by side).
• lumen_count is optional but recommended for central lines and dialysis catheters.

Example:

Notes:

• Composite key is (patient_id, recorded_dttm, attribute_category). The same attribute can be recorded multiple times over a patient’s lifetime, with newer rows superseding older ones.

• attribute_category and attribute_group form a deterministic rollup — every attribute_category maps to exactly one attribute_group (e.g., housing_status → health_related_social_needs). Sites do not need to populate attribute_group independently if it can be derived.

• attribute_value_category permissibles are conditional on attribute_category. The column-level permissible list is the union of all attribute value sets. The conditional validity per category:

  attribute_category	attribute_group	permissible attribute_value_category
  alcohol_use	substance_use_behavior	none, social, heavy, unknown
  employment_status	sociodemographic	full_time, part_time, unemployed, retired, student, disabled, unknown
  financial_strain	health_related_social_needs	none, present, unknown
  food_insecurity	health_related_social_needs	secure, insecure, unknown
  functional_status	functional	independent, partially_dependent, fully_dependent, unknown
  housing_status	health_related_social_needs	housed, unstable, undomiciled, unknown
  interpersonal_safety	health_related_social_needs	safe, unsafe, unknown
  marital_status	sociodemographic	single, married, divorced, widowed, separated, unknown
  organ_donor	care_preferences	yes, no, unknown
  pregnancy_status	reproductive	pregnant, postpartum, not_pregnant, unknown
  smoking_status	substance_use_behavior	current, former, never, unknown
  social_isolation	health_related_social_needs	connected, isolated, unknown
  substance_use	substance_use_behavior	active, history, none, unknown
  transportation_barrier	health_related_social_needs	none, present, unknown
  utility_insecurity	health_related_social_needs	secure, insecure, unknown

• Per the steering committee discussion, BMI is intentionally excluded (it belongs on vitals), isolation status belongs on adt, and insurance belongs on hospitalization. Advance-directive content rolls up under organ_donor / care_preferences.

Example:

Notes:
Source indices from validated and publicly available datasets.

Example:

Example:

Notes:

• One row per radiology_accession. The accession is the natural key within a site.
• All four *_category fields are mCIDE-controlled. See the 3.0 radiology mCIDE folder for the canonical permissible values.
• radiology_report_text is free text; sites that cannot share narratives may leave it null and join to a separately-governed text store via radiology_accession.
• radiology_capture_dttm (image acquisition) and radiology_report_dttm (final read) typically differ — the capture time is what should be used for clinical-event timing.

Example:

Example: