Concept Ranges For Different Factors - Technical

• Introduction

• Architecture

• Business Flow

• Strict Ranges

• Schema changes

Introduction

This is a technical documentation for “factor-based” concept ranges. For the background of these ranges, refer to the main documentation.

The criteria field in the concept_reference_range table allows for the dynamic and flexible validation of observations based on various patient attributes.

Architecture

The key challenge in implementing this feature was to design a system that does not require extensive changes to the existing database structure while still being robust and flexible enough to handle a variety of criteria based on different patient factors.

The solution involves introducing two new tables:

• concept_reference_range: This table holds the absolute, critical, and normal ranges along with a criteria column. The criteria column contains a coded function that performs validation checks, such as those based on age or gender, using the Velocity engine for evaluation.

• obs_reference_range: This table stores the validated reference ranges for observation numeric values after the criteria have been applied.

These tables allow for storage of different ranges. However, concept_reference_range includes criteria expressions for factors - which can be combinations for different factors like age and gender. For example:

• concept_numeric able:

  • concept_id: 1, name: “Systolic blood pressure”, hi_critical: 130.0, hi_normal: 120.0, hi_absolute: 120.0, low_critical: 100.0, low_normal: 150.0, low_absolute: 120.0

  • concept_id: 2, name: “Temperature”, hi_critical: 40.0, hi_normal: 37.0, hi_absolute: 37.0, low_critical: 35.0, low_normal: 36.5, low_absolute: 36.8

• concept_reference_range Table:

  • concept_reference_range_id: 1, concept_id: 1, criteria: ”$patient.getAgeInMonths() > 1 && $patient.getAgeInMonths() < 3”, hi_critical: 100.0, hi_normal: 80.0, hi_absolute: 80.0, low_critical: 50.0, low_normal: 64.0, low_absolute: 60.0

  • concept_reference_range_id: 2, concept_id: 1, criteria: ”$patient.getAge() > 18 && $patient.getAge() < 70”, hi_critical: 130.0, hi_normal: 120.0, hi_absolute: 120.0, low_critical: 60.0, low_normal: 80.0, low_absolute: 90.0

This design allows for easy updates and expansions of criteria without requiring changes to the underlying database schema.

Business Logic Flow

Strict Ranges

When multiple reference ranges, of one concept numeric, are evaluated to true, then we use the strictest range.

• For instance:-
  ConceptReferenceRange1 has ranges 60-140.
  ConceptReferenceRange2 has ranges 80-150
  -> The ObsReferenceRange will have range 80-140. In other words, the highest lower bound and lowest higher bound is picked.

Schema changes

This section details the new tables and relationships added to the OpenMRS data model to support factor-based concept ranges.

Note: The complete data model is documented here. This document only highlights the new schema additions relevant to factor-based concept ranges.

1. concept_reference_range Table

The concept_reference_range table is designed to store detailed reference ranges for concepts, along with criteria that determine when these ranges apply.

Table Structure:

Relationship:

1:N relationship with concept_numeric: A single concept can have multiple reference ranges based on different criteria.

2. obs_reference_range Table

The obs_reference_range table records the validated reference range for a specific observation (Obs).

Table Structure:

Relationship:

Has 1:1 relationship with obs: Each observation has one associated reference range.