Product Guide

Data Summarization (Lens)

Not only is clinical data messy, it is also often duplicated and not tailored to the questions a clinician needs to answer. Zus Lenses offer a summarized view of clinical data that are most relevant to a patient’s care team.

Suggest Edits

What is a Lens?

A Zus Lens is a set of FHIR resources derived from a patient’s raw resources that have been structurally normalized, de-duplicated, summarized, and tagged. Alongside Zus Data Enrichment, a Lens helps you extract signal quickly from raw data with just one API call.

Deduplication: Clinical data are aligned based on their appropriate Zus-enriched codings and a single resource is written per unique data type based on the patient’s history.

Structural Normalization: Zus helps reduce noisy data by normalizing clinical data into single FHIR resources representing unique data or events.

Medications Medication data comes from four different FHIR resources: MedicationStatement, MedicationRequest, MedicationDispense, and MedicationAdministration. Zus aligns these various resources together based on their Zus-enriched codings and writes a single MedicationStatement per unique medication based on the Patient’s history.

Episodes of Care Data from Admissions, Discharges, and Transfers (ADT) is transformed into Encounter resources. In addition, Zus gets ADT data from Continuity of Care Documents (CCDs) that can provide contextual information such as notes, administered medications, and completed procedures, among others. Zus creates a single unique EpisodeofCare for each unique hospitalization based on these data.

Summarization: Zus summarizes the history for each data type in a single resource, so you have one source for answering questions such as: “what was the last activity for this medication?” or “what is the current status?” Additionally, you may just want to present what is currently applicable and active for the patient today. Lenses help with both of these scenarios and you can access them simply by specifying the related tag of the Lens you want (see below).

Lens resources are created after Zus enriches newly created resources and are rewritten every time a new relevant resource is created with no work or intervention needed by you.

How Are Lenses Represented?

Zus-Derived Lens Resources

Lens resources are aggregated, summarized versions of Builder-generated and third party resources in the Zus Aggregated Profile (ZAP). You can identify a Lens resource by the presence of a “Lens Tag,” which is a meta tag generated by Zus.

Lens Tag example:

"meta": {
    "tag": [
        {
            "system": "https://zusapi.com/lens",
            "code": "ActiveMedications"
        }
    ]
}

❗

Lens Permissions

Builder users and app clients are NOT permitted to create, modify, or delete Lens resources. Any attempt to do so will result in a 403 error.

Medication Lenses

Summary Lens

The medication resources for a patient (i.e., MedicationStatement, MedicationRequest, MedicationDispense, and MedicationAdministration), are aligned and de-duplicated by common RxNorm (or their available CodeSystem if mapping to RxNorm was not possible). Zus then writes new Lens MedicationStatement resources with a specific tag for easy identification:

"meta": {
    "tag": [
        {
            "system": "https://zusapi.com/summary",
            "code": "Common"  
        }
    ]
}

You can query for a patient's Medication Summary Lens resources by filtering on the tag, as shown below:

{{fhir_url}}/MedicationStatement?_tag=https://zusapi.com/summary|Common&patient.identifier=https://zusapi.com/fhir/identifier/universal-id|{{universal_patient_id}}

Zus determines the value for each field in the summarized resource primarily based on the value on the raw resource with the latest real-world event date. This latest real-world event date is then used to populate the DateAsserted field of the summarized resource. The derivedFrom property on the Summary Lens resource references the resources the Summary Lens was compiled from. The status field is set to active for any Summary Lens that has activity within the last 180 days or 365 days into the future, and where the latest status among the raw resources is not one of: completed, entered-in-error, stopped, or not-taken.

Active Medication Lens

Active Medication Lenses are a subset of Summary Lenses that have a status of Active. The status is set to active for any Summary Lens that has activity within the last 180 days or 365 days into the future, and where the latest status among the raw resources is not completed, entered-in-error, stopped, or not-taken. This Lens helps answer the question: “What medications is this patient most likely on currently?”

Active Medication Lenses have the following tag:

"meta": {
    "tag": [
        {
            "system": "https://zusapi.com/lens",
            "code": "ActiveMedications"
        }
    ]
}

Because Active Medication Lens resources are a subset of Summary Lenses, they also contain the summary tag.

You can query for a patient's Active Medication Lens resources by filtering on the tag, as shown below:

{{fhir_url}}/MedicationStatement?_tag=https://zusapi.com/lens|ActiveMedications&patient.identifier=https://zusapi.com/fhir/identifier/universal-id|{{universal_patient_id}}

Condition Lenses

Summary Lens

The Condition resources of a patient are aligned and de-duplicated by common SNOMED CT (or the available CodeSystem if mapping to SNOMED CT is not available). Zus creates these new, de-duplicated Conditions Summary resources with the following tag:

"meta": {
    "tag": [
        {
            "system": "https://zusapi.com/summary",
            "code": "Common"  
        }
    ]
}

You can query for a patient's Condition Summary Lens resources by filtering on the tag, as shown below:

{{fhir_url}}/Condition?_tag=https://zusapi.com/summary|Common&patient.identifier=https://zusapi.com/fhir/identifier/universal-id|{{universal_patient_id}}

Zus determines the value for each field in the Summary Lens resource primarily based on the value on the raw resource with the latest real-world event date.

Chronic Conditions Lens

Chronic Conditions are a subset of Conditions Summary Lenses that have an enriched Chronic Conditions Indicator (CCI) value of “Chronic”, “Both”, or null (i.e., if there is no mapping from the coding to CCI value). This Lens informs care team users about what chronic problems their patients are most likely currently dealing with. You can find the enriched CCI value in a Condition resource codeable concept in the following extension:

{  
  "extension": [  
    {  
      "url": "<https://zusapi.com/terminology/enrichment>",  
      "valueString": "CCI"  
    }  
  ],  
  "system": "<http://www.hcupus.ahrq.gov/toolssoftware/chronic_icd10/chronic_icd10.jsp>",  
  "code": "C",  
  "display": "Chronic",  
  "userSelected": false  
}

Chronic Conditions Lens resources have the following tag:

"meta": {
    "tag": [
        {
            "system": "https://zusapi.com/lens",
            "code": "ChronicConditions"
        }
    ]
}

Since Condition Lens resources are a subset of Summary Lenses, they also contain the summary tag

You can query for a patient's Chronic Conditions Lens resources by filtering on the tag, as shown below:

{{fhir_url}}/Condition?_tag=https://zusapi.com/lens|ChronicConditions&patient.identifier=https://zusapi.com/fhir/identifier/universal-id|{{universal_patient_id}}

Transition of Care Lens

The Transitions of Care Lens aggregates and summarizes Encounter FHIR resources for each patient into EpisodeOfCare FHIR resources. Inpatient, emergency, observation, and preadmit encounters that have matching visit IDs and/or any encounters that occur near each other temporally (within 36 hours) for a given patient will be grouped together and summarized into a Zus created and managed EpisodeOfCare resource.

Grouping Logic

First, Zus groups all encounters with the same visit ID together. Then we create temporal windows of these groups, collecting all encounters that occur within 36 hours of the previous encounter. These windows are then summarized into an EpisodeOfCare lens output resource.

Data Model

The output of the Transitions of Care Lens are EpisodeOfCare FHIR resources which Zus creates and manages.

FieldNote
resource.meta.tagAll transitions of care lens output resources will include this tag:
{ "system": "https://zusapi.com/summary", "code": "TransitionsOfCare" }
resource.extension with "url": "https://zusapi.com/lens/extension/aggregatedFrom"The Zus aggregated from extension lists the Encounter resources that were used to generate this output resource.
resource.extension with "url": "https://zusapi.com/lens/extension/dischargeDisposition"The Zus discharge disposition extension denotes the most recent discharge disposition for the episode.
resource.extension with "url": "https://zusapi.com/lens/extension/dischargeLocation"The Zus discharge location extension denotes the location of the most recent inpatient encounter in the episode.
resource.extension with "url": "https://zusapi.com/lens/extension/admittingLocation"The Zus admitting location extension denotes the location of the most recent emergency encounter in the episode.
resource.extension with "url": "https://zusapi.com/lens/extension/encounterClass"The Zus encounter class extension denotes the most recent “encounter class” in the episode. Expected codes are:EMER (emergency), IMP(inpatient), OBSENC (observation), and PRENC (preadmit).
resource.extension with "url": "https://zusapi.com/lens/extension/dischargeNarrative"The Zus discharge narrative extension is a list of references to Binarys that have a discharge narrative for the episode.

The preferredDischargeNarrative nested extension noted by "url": "https://zusapi.com/lens/extension/preferredDischargeNarrative" indicates which document will provide the most valuable content relating to that episode of care. Zus is matching codes based on the Commonwell/Carequality document standardization project.
resource.diagnosisThe diagnosis field includes all diagnoses from all encounters that are part of this episode.

Diagnoses from emergency encounters will have an admitting diagnosis extension on them.

Diagnoses from all other encounters will have a discharge diagnosis extension on them.
resource.periodThe period will begin at the start of the first occurring encounter that is part of this episode.

The period will end at the end of the last occurring encounter that is part of this episode. Null values are possible if the supporting encounters do not have a start or end period.
resource.patientThe patient will be the Zus Universal Patient.

Here is a mocked example of a single EpisodeOfCare for a single patient created by the Transitions of Care Lens in JSON format:

{
    "fullUrl": "https://api.zusapi.com/fhir/EpisodeOfCare/3ca3ddf4-5808-4c37-a70d-340a9bb288a7",
    "resource": {
        "resourceType": "EpisodeOfCare",
        "id": "3ca3ddf4-5808-4c37-a70d-340a9bb288a7",
        "meta": {
            "extension": [
                {
                    "url": "https://zusapi.com/stream",
                    "valueString": "zus"
                },
                {
                    "url": "https://zusapi.com/created-at",
                    "valueInstant": "2023-12-04T18:42:23.176+00:00"
                }
            ],
            "versionId": "3",
            "lastUpdated": "2023-12-06T14:30:09.309+00:00",
            "source": "#oPJqrr6aRcqDT6zN",
            "tag": [
                {
                    "system": "https://zusapi.com/accesscontrol/owner",
                    "code": "builder/5e0f86eb-bb0b-4543-8489-262fcbf661da",
                    "display": "zus-health-lens"
                },
                {
                    "system": "https://zusapi.com/summary",
                    "code": "TransitionsOfCare"
                }
            ]
        },
        "extension": [
            {
                "url": "https://zusapi.com/lens/extension/aggregatedFrom",
                "extension": [
                    {
                        "url": "https://zusapi.com/lens/extension/aggregatedFrom",
                        "valueReference": {
                            "reference": "Encounter/9ff3e597-dea9-4030-a0bb-faed510c62ae",
                            "type": "Encounter"
                        }
                    },
                    {
                        "url": "https://zusapi.com/lens/extension/aggregatedFrom",
                        "valueReference": {
                            "reference": "Encounter/b04dddba-2c9a-4a40-8059-582fb3ea1fdb",
                            "type": "Encounter"
                        }
                    }
                ]
            },
            {
                "url": "https://zusapi.com/lens/extension/dischargeDisposition",
                "valueCodeableConcept": {
                    "coding": [
                        {
                            "display": "Discharged to home health"
                        }
                    ],
                    "text": "Discharged to home health"
                }
            },
            {
                "url": "https://zusapi.com/lens/extension/dischargeLocation",
                "valueReference": {
                    "reference": "Location/4e193be5-fc7e-4ead-99c7-5d45e6342196",
                    "type": "Location",
                    "display": "Mock Healthcare Facility"
                }
            },
            {
                "url": "https://zusapi.com/lens/extension/admittingLocation",
                "valueReference": {
                    "reference": "Location/62d66292-17c3-4e06-9fec-97352ef8cb41",
                    "type": "Location",
                    "display": "Mock Healthcare Facility 2"
                }
            },
            {
                "url": "https://zusapi.com/lens/id",
                "valueString": "6f29897a-db0e-41af-b666-3f7c2eb0417a"
            },
            {
                "url": "https://zusapi.com/fhir/identifier/universal-id",
                "valueString": "17029ef4-c018-4f24-a627-b3b68f094114"
            },
            {
                "url": "https://zusapi.com/lens/extension/encounterClass",
                "valueCoding": {
                    "system": "https://terminology.hl7.org/2.1.0/ValueSet-v3-ActEncounterCode.html",
                    "code": "IMP",
                    "display": "inpatient",
                    "userSelected": false
                }
            },
            {
                "url": "https://zusapi.com/lens/extension/dischargeNarrative",
                "valueReference": {
                    "reference": "Binary/24cc6185-1ae7-4cdc-b923-b593c9d9df02",
                    "type": "Binary"
                }
            },
            {
                "url": "https://zusapi.com/lens/extension/dischargeNarrative",
                "valueReference": {
                    "extension": [
                        {
                            "url": "https://zusapi.com/lens/extension/preferredDischargeNarrative",
                            "valueBoolean": true
                        }
                    ],
                    "reference": "Binary/2d556f1f-fcba-4abe-b117-5e97676d83b2",
                    "type": "Binary"
                }
            }
        ],
        "identifier": [
            {
                "type": {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                            "code": "VN",
                            "display": "visit number"
                        }
                    ],
                    "text": "visit number"
                },
                "value": "000001"
            }
        ],
        "status": "finished",
        "diagnosis": [
            {
                "condition": {
                    "reference": "Condition/cbd9e03d-29cc-4aaa-93ea-8e04c33c1b6a"
                },
                "role": {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/diagnosis-role",
                            "code": "AD",
                            "display": "Admitting diagnosis"
                        }
                    ]
                }
            },
            {
                "condition": {
                    "reference": "Condition/6434ced9-bc03-4477-8a31-9c4801213fc3"
                },
                "role": {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/diagnosis-role",
                            "code": "DD",
                            "display": "Discharge diagnosis"
                        }
                    ]
                }
            }
        ],
        "patient": {
            "reference": "Patient/95fd00c0-ca37-47e5-a570-f10f588e8a99",
            "type": "Patient"
        },
        "period": {
            "start": "2023-09-02T18:07:00.000000+00:00",
            "end": "2023-09-05T19:51:00.000000+00:00"
        }
    },
    "search": {
        "mode": "match"
    }
}

Encounter Lens

The Encounter resources for a patient are deduplicated by date and enriched encounter class. The Encounter class is added by Zus Enrichment and ensures that Encounters are properly categorized as Ambulatory, Inpatient, Emergency, etc.

If we are unable to categorize an Encounter do to a lack of provided codings or other context, we add a label of Unknown. Because those uncategorized encounters generally contain non-patient interactions like med orders, they are not summarized into an encounter lens.

Encounter Lenses include a summary tag for easy identification:

"meta": {  
    "tag": [  
        {  
            "system": "https://zusapi.com/lens",  
            "code": "Encounters"  
        }  
    ]  
}

You can query for a patient's Encounter Summary Lens resources by filtering on the tag, as shown below:

{{fhir_url}}/Encounter?_tag=https://zusapi.com/summary|Common&patient.identifier=https://zusapi.com/fhir/identifier/universal-id|{{universal_patient_id}}

Here is an example of a mocked Encounter Lens resource:

{
 "resourceType": "Encounter",
 "id": "7bdd-47fa-accf-6e1f2b855555",


 "class": {
   "system": "https://terminology.hl7.org/2.1.0/ValueSet-v3-ActEncounterCode.html",
   "code": "AMB",
   "display": "ambulatory"
 },
 "status": "finished",
 "subject": {
   "reference": "Patient/8804-4728-95cf-3ab4af655555",
   "type": "Patient"
 },
 "diagnosis": [
   {
     "condition": {
       "reference": "Condition/6a10-4cd0-b377-d2aa13555555"
     }
   }
 ],
 "extension": [
   {
     "extension": [
       {
         "url": "https://zusapi.com/lens/extension/aggregatedFrom",
         "valueReference": {
           "reference": "Encounter/da3f-4b69-9b15-9e3099655555",
           "type": "Encounter"
         }
       },
       {
         "url": "https://zusapi.com/lens/extension/aggregatedFrom",
         "valueReference": {
           "reference": "Encounter/0b43-414e-a925-58b9d1a55555",
           "type": "Encounter"
         }
       },
       {
         "url": "https://zusapi.com/lens/extension/aggregatedFrom",
         "valueReference": {
           "reference": "Encounter/7d22-40e5-a453-5d3a7d055555",
           "type": "Encounter"
         }
       }
     ],
     "url": "https://zusapi.com/lens/extension/aggregatedFrom"
   },
   {
     "url": "https://zusapi.com/lens/id",
     "valueString": "8326-c94e-4fd4-aabe-4fa744655555"
   },
   {
     "url": "https://zusapi.com/fhir/identifier/universal-id",
     "valueString": "7fb1-40ff-8e63-b3f4e0355555"
   }
 ],
 "identifier": [
   {
     "system": "urn:oid:1.2.840.114350.1.13.280.2.7.3.698084.8",
     "value": "1484343255"
   },
   {
     "system": "urn:oid:1.2.840.114350.1.13.280.2.7.3.698084.8",
     "value": "1484345497"
   },
   {
     "system": "urn:oid:1.2.840.114350.1.13.280.2.7.3.698084.8",
     "value": "1484616178"
   }
 ],
 "location": [
   {
     "location": {
       "reference": "Location/5073-74ae-4d80-877d-5c628e055555"
     }
   },
   {
     "location": {
       "reference": "Location/deb-9491-46dc-91f6-46deace55555"
     }
   }
 ],
 "meta": {
   "extension": [
     {
       "url": "https://zusapi.com/stream",
       "valueString": "zus"
     },
     {
       "url": "https://zusapi.com/created-at",
       "valueInstant": "2024-06-25T20:10:17.143+00:00"
     }
   ],
   "versionId": "1",
   "lastUpdated": "2024-06-25T20:10:16.545+00:00",
   "tag": [
     {
       "system": "https://zusapi.com/summary",
       "code": "Common"
     },
     {
       "system": "https://zusapi.com/accesscontrol/owner",
       "code": "builder/bb0b-4543-8489-262fcbf55555"
     }
   ]
 },
 "participant": [
   {
     "individual": {
       "reference": "Practitioner/7-fbf9-44ec-bc65-3b1becf55555"
     }
   },
   {
     "individual": {
       "reference": "Practitioner/ddfe-4be4-8442-1587a1e55555"
     }
   }
 ],
 "period": {
   "start": "2023-11-20T09:51:00-05:00",
   "end": "2023-11-21T16:57:00-05:00"
 }
}

Updated about 1 month ago