POST /convert/v1/fhirr4toomop
This operation converts a FHIR R4 bundle (including one from CDA-to-FHIR, HL7-to-FHIR, or Combine Bundles) into the Observational Medical Outcomes Partnership (OMOP) Common Data Model v5.4 format.
Contents
The input for the OMOP conversion is a FHIR R4 bundle for a single patient.
The output for the OMOP conversion is a ZIP archive, so specify accept: application/zip
in your request header. The ZIP archive contains multiple Comma-Separated Value (CSV) files, one for each supported OMOP data table. See data tables for a complete list of contents.
If the input data is invalid (such as improperly-formatted FHIR data), the ZIP archive will not be created. Instead, the response will be a FHIR Operation Outcome in JSON format detailing the errors.
However, in many cases Rosetta can continue processing even when there are issues with the input data, such as missing fields or unexpected data types. In such cases, issues are reported in a custom file in the ZIP archive named PROCESSING_LOG.csv
. This processing log categorizes issues as:
Error
are omitted from the final output.
Rosetta uses v5.4 of the OMOP Common Data Model (CDM) specification, with a few exceptions described in Processing Notes.
There are several nuances involved in converting data from FHIR to OMOP, discussed below.
In OMOP, the main ID field in each data table uses the integer
data type, but Rosetta uses string values representing paths within the FHIR bundle. For example: a person_id
of Patient/35b77437-425d-419c-90b5-af4bc433ebe9
or an observation_id
of Procedure/7.2ed0fe30094a46e7bf6b3ebe69ead24a
describe the FHIR resource type and ID within the FHIR bundle where the data originated.
Additionally, the following mapping exists between OMOP identifiers and FHIR identifiers:
OMOP Field | FHIR Equivalent | Notes |
person_id |
Patient.id |
|
condition_id |
Condition.id |
Certain FHIR resources may have inline conditions. For example, the diagnosis field of a FHIR Encounter may list a condition directly, rather than referencing an independent Condition resource. In such cases, Rosetta will generate a condition row with an identifier derived from the parent resource, such as Encounter/[Encounter.id]/diagnosis/[sequence #] . |
With the exception of ID fields (mentioned above), Rosetta will enforce the data types defined in the OMOP standard. When importing OMOP data into a database, ensure your schema aligns with those data types.
Rosetta will enforce primary and foreign key references (including concept_ids
, which should reference standard OMOP concepts as of export time).
By the nature of the specification, OMOP is lossy. It focuses on standard, validated data most suitable for analysis, and assumes that any necessary data cleanup has been performed prior to OMOP export. Rows containing errors are dropped from the output, as described in error handling.
OMOP does not include names and patient identifiers (such as SSN or MRNs) from the FHIR input, though it does include personally-identifiable information like date of birth.
As part of the OMOP conversion, Rosetta will attempt to match coded values within the bundle to corresponding concepts from OMOP’s Standard Vocabularies, and populate several potential fields for each data row:
condition_concept_id
or observation_concept_id
) will contain the corresponding OMOP concept ID if the concept is designated standard. If no standard concept was found, this will be set to a concept ID of 0 (“no matching concept”).condition_source_concept_id
or procedure_source_concept_id
) will contain the corresponding OMOP concept ID if the concept is designated non-standard.condition_source_value
or procedure_source_value
) will contain a string value that combines the original source code and display name.For example, a condition was originally coded with the ICD-10 code J45.5 (severe persistent asthma). Rosetta finds a corresponding OMOP concept 45591559, which is non-standard. OMOP contains a cross-walk mapping from 45591559 to the standard OMOP concept 4145356. Thus, the data will be:
Field | Value |
---|---|
condition_concept_id |
4145356 (standard) |
condition_source_concept_id |
45591559 (non-standard) |
condition_source_value |
J45.5 severe persistent asthma (original) |
OMOP requires that certain domains go into specific data tables, which may differ from their original FHIR resource. For example, a FHIR Procedure may be placed into the OMOP MEASUREMENT
table rather than the PROCEDURE_OCCURRENCE
table.
FHIR Bundles and OMOP contents are verbose, so the example below just shows a small sample to illustrate how the data is structured. For a more complete example, try out the API in one of the Quickstart Tools.
{
"resourceType": "Bundle",
"type": "batch-response",
"entry": [
{
"resource": {
"resourceType": "Patient",
"id": "35b77437-425d-419c-90b5-af4bc433ebe9",
... (patient fields)
}
},
{
"resource": {
"resourceType": "Procedure",
"id": "7.2ed0fe30094a46e7bf6b3ebe69ead24a",
... (encounter fields)
}
},
{
"resource": {
"resourceType": "Procedure",
"id": "7.14e26bb09d7649b2a6ce10f794ca8960",
... (encounter fields)
}
},
...
]
}
PERSON.csv:
person_id,gender_concept_id,year_of_birth,month_of_birth,day_of_birth,birth_datetime,race_concept_id,ethnicity_concept_id,location_id,provider_id,care_site_id,person_source_value,gender_source_value,gender_source_concept_id,race_source_value,race_source_concept_id,ethnicity_source_value,ethnicity_source_concept_id
Patient/35b77437-425d-419c-90b5-af4bc433ebe9,8532,1956,8,13,1956-08-13T00:00:00.0000000,0,0,,,,35b77437-425d-419c-90b5-af4bc433ebe9,female,,,,,
OBSERVATION.csv:
observation_id,person_id,observation_concept_id,observation_date,observation_datetime,observation_type_concept_id,value_as_number,value_as_string,value_as_concept_id,qualifier_concept_id,unit_concept_id,provider_id,visit_occurrence_id,visit_detail_id,observation_source_value,observation_source_concept_id,unit_source_value,qualifier_source_value,value_source_value,observation_event_id,obs_event_field_concept_id
Procedure/7.2ed0fe30094a46e7bf6b3ebe69ead24a,Patient/35b77437-425d-419c-90b5-af4bc433ebe9,0,2009-07-01,2009-07-01T12:00:00.0000000,32817,,,,,,,,,465 Treatment for Upper Respiratory Infection,,,,,,
Procedure/7.14e26bb09d7649b2a6ce10f794ca8960,Patient/35b77437-425d-419c-90b5-af4bc433ebe9,0,2009-06-07,2009-06-07T20:30:00.0000000,32817,,,,,,,,,OtherThymusOperations Oth thorac op thymus NOS,,,,,,
etc.