Understanding Zus data

Patient table structure

In Zus data marts, an important concept to understand is the structure of the patient table.

In this table, each row has a unique id that refers to a distinct FHIR patient resource. Each patient resource refers to a copy of a patient’s data from a single organization - for example, from a specific hospital or pharmacy.

These organizations each have their own version of the clinical data for a given patient, and Zus aggregates this data to help our customers make sense of it. Therefore, each individual human represented in Zus may have multiple patient resources with data about them from different sources. Zus ties together these different patient resources via our Universal Patient Identifier (UPID).

To illustrate the structure of the patient table, you can query for all distinct patient IDs and UPIDs from the patient table. You will find that there are more unique patient IDs than UPIDs, because a single patient (represented by a single UPID), can have multiple patient resources from different organizations contributing data.

Important reminder: While a given human should only ever have a single UPID at any given time, that UPID can change over time. Users should not assume that a UPID for a given patient will never change.

📘

Sample query available here

Data source column

Zus retrieves external patient data from a variety of data sources. The source of a given patient resource (and all data associated with that patient resource) is available in the data_source column. The following query will calculate the total number of patients with data by data source. Additional details about the data_source column are available here.

📘

Sample query available here

Data enrichment

Zus cleans up real-world data and makes it easier for customers to analyze through data enrichment.
For example, while Zus receives conditions data with a variety of codesets (ICD-9, ICD-10, etc.), Zus normalizes condition codes to SNOMED where possible to provide a common analytical codeset. Users can count the number of distinct patients by SNOMED-coded Condition resource using the following query:

📘

Sample query available here

Likewise, Zus normalizes medication codes to RxNorm where possible for the following Medication-related resources: MedicationStatement, MedicationRequest, MedicationDispense, MedicationAdministration (an explanation of the differences between these resource types is available here). Users can count the number of distinct patients by RxNorm-coded MedicationStatement resource using the following query:

📘

Sample query available here

Lens tables

In addition to data enrichment, Zus helps customers make sense of raw clinical data through intelligent summarization in the form of a Zus Lens. A Zus Lens is a set of FHIR resources derived from a patient’s raw clinical data, and Lenses are separated into their own tables for easy identification and access.

As an example, a user can calculate the number of de-duplicated encounters by encounter type from the Lens_Encounter table using the following query:

📘

Sample query available here

Likewise, a user can count the number of distinct patients by RxNorm-coded MedicationStatement resources from the Lens_RxNorm_Medication_Statement table using the following query:

📘

Sample query available here

The benefit of this query (rather than querying the Medication_Statement table directly) is that the medication summary lens summarizes and de-duplicates medications across all medication-related resources for a given patient (i.e., MedicationStatement, MedicationRequest, MedicationDispense, and MedicationAdministration). So rather than having to query four tables, a user only needs to query one.

UPID / internal ID mapping

Often, Zus customers will want to join Zus data with data from other systems (e.g. EHR data, claims data). To do so, customers need a query that returns a 1:1 mapping between the Zus UPID and their own internal identifier. The following query provides such a mapping to an internal identifier labeled with system https://organizationName.com/ID.

📘

Sample query available here

If you've written your patients to Zus with your organization's internal identifier, all you need to do to customize the query and create your own mapping is replace https://organizationName.com/ID with your organization's own internal identifier system.

Linking Conditions to Encounters

A common analysis among Zus customers is to link a condition in the Condition table to an Encounter and a Practitioner, to better understand the context of a diagnosis.

One way to attempt this is to try to join the ENCOUNTER and PRACTITIONER tables to the CONDITION table, using the ENCOUNTER_ID, RECORDER_PRACTITIONER_ID, and ASSERTER_PRACTITIONER_IDcolumns in the Condition table. However, this approach will often yield poor results, as those columns in the CONDITION table are typically not well populated.

Instead, the way the data is structured is that the ENCOUNTER table links to the ENCOUNTER_DIAGNOSIS table, and then to the CONDITION table. Similarly, you can link from the ENCOUNTER table to the ENCOUNTER_PARTICIPANT table, and then to the PRACTITIONER table. The sample query linked below illustrates this approach.

📘

Sample query available here

Joining in this manner, you will find that not all conditions map to an encounter or practitioner. All conditions will map to a source document, but that source document may not define an encounter and practitioner, hence why there are conditions without an associated encounter.