Skip to main content

OMOP-CDM

Category: Observational health data model

OMOP CDM is OHDSI's standardized relational model for observational health data. Convert-Pheno reads SQL or table-file exports rather than connecting to a live OMOP database, and it can write the supported OMOP-CDM tables as CSV.

RoleInput and output
Accepted inputSQL, CSV, and gzipped exports
Main outputOMOP-CDM CSV tables
Notes--stream for large OMOP-to-BFF runs
Representative OMOP table joins through person and concept identifiers
Representative OMOP tables joined through person and concept identifiers

Supported directions are:

  • OMOP input: PostgreSQL-style SQL dumps or one CSV file per table, with optional gzip compression
  • OMOP output: CSV tables written from the normalized BFF representation
Supported OMOP versions

The implemented mappings target OMOP CDM 5.3 and 5.4.

For the evaluated OMOP-CDM to Beacon v2 workflow, see the published study and its tutorial repository.

Longitudinal OMOP data

VISIT_OCCURRENCE.visit_occurrence_id is retained under the BFF _visit extension because Beacon v2 individuals has no direct equivalent for OMOP visits. The extension is emitted only when VISIT_OCCURRENCE is supplied.

OMOP As Input​

Download the tested OMOP CSV inputs: PERSON, CONCEPT, and DRUG_EXPOSURE. Keep table files together and pass them as one OMOP input request.

Accepted source layouts are:

  • one .sql or .sql.gz database export
  • one or more .csv or .csv.gz table exports

For split files, the table name is inferred from each filename. A practical conversion normally needs PERSON, CONCEPT or --ohdsi-db, and at least one clinical table such as CONDITION_OCCURRENCE, DRUG_EXPOSURE, MEASUREMENT, OBSERVATION, or SPECIMEN.

Use OMOP input recipes for individuals, biosamples, Phenopackets, and streaming commands.

Input Controls​

  • --max-lines-sql defaults to 500. For SQL dumps it limits rows read per selected table; in non-streaming conversion it also limits emitted individuals. Raise it for complete runs.
  • --omop-tables limits processing to named clinical tables. PERSON and CONCEPT remain required and do not need to be listed.
  • --ohdsi-db checks the Athena-OHDSI lookup database when an OMOP input concept is not available in the supplied CONCEPT table. It is required for OMOP output, where it resolves active standard concepts in the expected OMOP domain.
  • Gzip input and output reduce storage but add CPU overhead, which can be noticeable during streaming.

SPECIMEN and Biosamples​

OMOP SPECIMEN rows can become first-class Beacon biosamples. When SPECIMEN.quantity is present, it is also emitted as a sample-level biosamples.measurements entry. The unit is resolved from unit_concept_id, with unit_source_value as a fallback label.

OMOP SPECIMEN has no measurement-concept field for quantity, so the Beacon assayCode uses the local CURIE OMOP:SPECIMEN.quantity with label Specimen quantity.

OMOP vocabulary prefixes in generated identifiers

When an identifier is built from CONCEPT.vocabulary_id and CONCEPT.concept_code, whitespace in the vocabulary prefix becomes an underscore. For example, Type Concept becomes Type_Concept:OMOP4976929. This keeps identifiers usable in APIs and indexes.

Source Provenance​

Original rows are retained by default under fields such as info.PERSON.OMOP_columns and biosamples.info.SPECIMEN.OMOP_columns. This supports mapping review and source-level queries. Use --no-source-info to omit these copied rows.

Memory and Streaming​

The default --no-stream mode groups all rows for each person_id in memory. This produces consolidated individual records but memory use grows with the number of rows and tables.

--stream processes clinical rows incrementally and is intended for large exports. It currently supports individuals-only BFF output. PERSON and CONCEPT are still loaded into memory, as is VISIT_OCCURRENCE when provided. Streamed files are not consolidated into one record per person; linkage is retained through identifiers for downstream storage.

Generated BFF can be checked with Beacon v2 CBI Tools.

OMOP As Output​

OMOP output consists of table CSV files such as PERSON.csv, CONDITION_OCCURRENCE.csv, MEASUREMENT.csv, and other supported tables. The files are written under --out-dir; --out-name TABLE=FILE can override an individual table filename.

BFF, PXF, CSV, REDCap, CDISC-ODM, cBioPortal, Dataset-JSON, Dataset-XML, and FHIR/mCODE input can reach this output through the supported normalization routes. See Choose a Conversion for commands and BFF to OMOP for the field-level mapping.

Developers using in-memory or HTTP(s) interfaces should use the dedicated Module and API pages rather than format-page payload examples.