i2b2

Category: Clinical research data warehouse model

i2b2 organizes clinical research data around patient, visit, and observation tables. Convert-Pheno reads exported i2b2 tables and groups their contents by patient. It does not connect to a live i2b2 database. The current tests use the documented table profile. Local ontology conventions vary between i2b2 installations and should be reviewed in the generated output.

RoleInput

Accepted inputCSV/TSV tables, directory, or ZIP package

Main outputBFF, PXF, OMOP-CDM

ProcessingGrouped by PATIENT_NUM in memory

Star-schema facts and optional visit context are grouped into patient records before target conversion

What You Need

Provide UTF-8 CSV or TSV table exports, either individually, in a directory, or inside one ZIP package. Gzip-compressed table files are also accepted.

Table	Requirement and use
PATIENT_DIMENSION	Required; creates one person record per PATIENT_NUM
OBSERVATION_FACT	Required; supplies diagnoses, measurements, procedures, medications, and other findings
VISIT_DIMENSION	Optional; adds encounter context through _visit
CONCEPT_DIMENSION	Optional; supplies labels for CONCEPT_CD values

convert-pheno \
  -ii2b2 i2b2-export/ \
  -obff individuals.json

Use -opxf phenopackets.json for PXF, or -oomop --out-dir omop_out/ --ohdsi-db for OMOP-CDM tables. The clinical mapping is built in. For entity-aware BFF output, an optional compact Mapping V2 file can name the synthesized dataset and cohort.

What Is Converted

i2b2 content	Main BFF target
patient identifier, sex, birth date, death date	individual identity, demographics, and vital status
numeric and LOINC observations	measures
recognized diagnosis facts	diseases
recognized procedure facts	interventionsOrProcedures
recognized medication facts	treatments
other clinical facts	phenotypicFeatures
encounter links	private _visit context on mapped events

Modifier rows remain in source provenance but are not emitted as separate clinical events.

Terminology And Source Data

i2b2 installations often use local ontology prefixes. Convert-Pheno preserves those source identifiers rather than guessing a standard crosswalk. When OMOP is the target, use --term-audit terminology.xlsx to review vocabulary resolution and fallbacks.

Raw patient and fact rows are retained under info.i2b2 by default. Use --no-source-info to omit them while retaining the converted fields.

Current Boundaries

Input is non-streaming and must fit in memory. The supported profile covers the four tables listed above; additional i2b2 dimensions and installation-specific ontology behavior require independent review.

For the field-level contract, see i2b2 to BFF.