round glucose values via "round-to-even" before classifying

ewollesen · ewollesen · commit e8e00d6b77de · 2025-06-20T12:43:38.000-06:00
The aim is to maintain consistency with the front end, and be easy to
explain when values don't align with other interpretations due to
rounding differences.

BACK-3800
diff --git a/data/types/blood/glucose/glucose.go b/data/types/blood/glucose/glucose.go
@@ -1,9 +1,12 @@
 package glucose
 
 import (
+	"math"
+
 	"github.com/tidepool-org/platform/data"
 	dataBloodGlucose "github.com/tidepool-org/platform/data/blood/glucose"
 	"github.com/tidepool-org/platform/data/types/blood"
+	"github.com/tidepool-org/platform/errors"
 	"github.com/tidepool-org/platform/structure"
 )
 
@@ -33,3 +36,112 @@ func (g *Glucose) Normalize(normalizer data.Normalizer) {
 		g.Value = dataBloodGlucose.NormalizeValueForUnits(g.Value, units)
 	}
 }
+
+// Classify the datum based on ADA thresholds.
+//
+// It pretends to handle values in mg/dL, but all values received by platform are normalized
+// into mmol/L upon reception, so being able to classify values in other units is of limited
+// use.
+func (g *Glucose) Classify() (RangeClassification, error) {
+	switch {
+	case g.Units == nil:
+		return RangeInvalid, errors.New("unhandled units: nil")
+	case g.Value == nil:
+		return RangeInvalid, errors.New("unhandled value: nil")
+	case *g.Units == dataBloodGlucose.MgdL:
+		return g.classify(thresholdsMgdL)
+	case *g.Units == dataBloodGlucose.MmolL:
+		return g.classify(thresholdsMmolL)
+	default:
+		return RangeInvalid, errors.Newf("unhandled units: %s", *g.Units)
+	}
+}
+
+// RangeClassification of a blood glucose value, e.g. Low, Very Low, etc.
+type RangeClassification int
+
+const (
+	RangeInvalid RangeClassification = iota
+	RangeVeryLow
+	RangeLow
+	RangeTarget
+	RangeHigh
+	RangeVeryHigh
+	RangeExtremelyHigh
+)
+
+type classificationThresholds struct {
+	VeryLow  float64
+	Low      float64
+	Target   float64
+	High     float64
+	VeryHigh float64
+	// Precision to round to for these thresholds/units.
+	Precision int
+}
+
+func (g *Glucose) classify(thresholds classificationThresholds) (RangeClassification, error) {
+	if g.Value == nil {
+		return RangeInvalid, errors.New("unhandled value: nil")
+	}
+	// Rounded values are used for all classifications. To not do so risks introducing
+	// inconsistency between frontend, backend, and other reports. See BACK-3800 for
+	// details.
+	rounded := roundToEvenWithPrecision(*g.Value, thresholds.Precision)
+	switch {
+	case rounded < thresholds.VeryLow:
+		return RangeVeryLow, nil
+	case rounded < thresholds.Low:
+		return RangeLow, nil
+	case rounded <= thresholds.Target:
+		return RangeTarget, nil
+	case rounded <= thresholds.High:
+		return RangeHigh, nil
+	case rounded <= thresholds.VeryHigh:
+		return RangeVeryHigh, nil
+	default:
+		return RangeExtremelyHigh, nil
+	}
+}
+
+func roundToEvenWithPrecision(v float64, decimals int) float64 {
+	if decimals < 1 {
+		return math.RoundToEven(v)
+	}
+	coef := math.Pow(10, float64(decimals))
+	return math.RoundToEven(v*coef) / coef
+}
+
+const (
+	ThresholdMmolLVeryLow  float64 = 3    // Source: https://doi.org/10.2337/dc24-S006
+	ThresholdMmolLLow      float64 = 3.9  // Source: https://doi.org/10.2337/dc24-S006
+	ThresholdMmolLTarget   float64 = 10   // Source: https://doi.org/10.2337/dc24-S006
+	ThresholdMmolLHigh     float64 = 13.9 // Source: https://doi.org/10.2337/dc24-S006
+	ThresholdMmolLVeryHigh float64 = 19.4 // Source: BACK-2963
+)
+
+var thresholdsMmolL = classificationThresholds{
+	VeryLow:   ThresholdMmolLVeryLow,
+	Low:       ThresholdMmolLLow,
+	Target:    ThresholdMmolLTarget,
+	High:      ThresholdMmolLHigh,
+	VeryHigh:  ThresholdMmolLVeryHigh,
+	Precision: 1,
+}
+
+const (
+	ThresholdMgdLVeryLow  float64 = 54  // Source: https://doi.org/10.2337/dc24-S006
+	ThresholdMgdLLow      float64 = 70  // Source: https://doi.org/10.2337/dc24-S006
+	ThresholdMgdLTarget   float64 = 180 // Source: https://doi.org/10.2337/dc24-S006
+	ThresholdMgdLHigh     float64 = 250 // Source: https://doi.org/10.2337/dc24-S006
+	ThresholdMgdLVeryHigh float64 = 350 // Source: BACK-2963
+)
+
+var thresholdsMgdL = classificationThresholds{
+	VeryLow:   ThresholdMgdLVeryLow,
+	Low:       ThresholdMgdLLow,
+	Target:    ThresholdMgdLTarget,
+	High:      ThresholdMgdLHigh,
+	VeryHigh:  ThresholdMgdLVeryHigh,
+	Precision: 0,
+}
diff --git a/data/types/blood/glucose/glucose_test.go b/data/types/blood/glucose/glucose_test.go
@@ -481,4 +481,107 @@ var _ = Describe("Glucose", func() {
 			),
 		)
 	})
+
+	Context("Classify", func() {
+		var MmolL = pointer.FromAny(dataBloodGlucose.MmolL)
+		var MgdL = pointer.FromAny(dataBloodGlucose.MgdL)
+
+		checkClassification := func(value float64, expectedRange glucose.RangeClassification) {
+			GinkgoHelper()
+			datum := dataTypesBloodGlucoseTest.NewGlucose(MmolL)
+			datum.Value = pointer.FromAny(value)
+			got, err := datum.Classify()
+			Expect(err).To(Succeed())
+			Expect(got).To(Equal(expectedRange))
+		}
+
+		It("classifies 2.9 as very low", func() {
+			checkClassification(2.9, glucose.RangeVeryLow)
+		})
+
+		It("classifies 3.0 as low", func() {
+			checkClassification(3.0, glucose.RangeLow)
+		})
+
+		It("classifies 3.8 as low", func() {
+			checkClassification(3.8, glucose.RangeLow)
+		})
+
+		It("classifies 3.9 as on target", func() {
+			checkClassification(3.9, glucose.RangeTarget)
+		})
+
+		It("classifies 10.0 as on target", func() {
+			checkClassification(10.0, glucose.RangeTarget)
+		})
+
+		It("classifies 10.1 as high", func() {
+			checkClassification(10.1, glucose.RangeHigh)
+		})
+
+		It("classifies 13.9 as high", func() {
+			checkClassification(13.9, glucose.RangeHigh)
+		})
+
+		It("classifies 14.0 as very high", func() {
+			checkClassification(14.0, glucose.RangeVeryHigh)
+		})
+
+		It("classifies 19.4 as very high", func() {
+			checkClassification(19.4, glucose.RangeVeryHigh)
+		})
+
+		It("classifies 19.5 as extremely high", func() {
+			checkClassification(19.5, glucose.RangeExtremelyHigh)
+		})
+
+		When("its classification depends on rounding", func() {
+			It("classifies 2.95 as low", func() {
+				checkClassification(2.95, glucose.RangeLow)
+			})
+
+			It("classifies 3.85 as low", func() {
+				checkClassification(3.85, glucose.RangeLow)
+			})
+
+			It("classifies 10.05 as on target", func() {
+				checkClassification(10.05, glucose.RangeTarget)
+			})
+		})
+
+		When("it doesn't recognize the units", func() {
+			It("returns an error", func() {
+				datum := dataTypesBloodGlucoseTest.NewGlucose(pointer.FromAny("blah"))
+				datum.Value = pointer.FromAny(5.0)
+				_, err := datum.Classify()
+				Expect(err).To(MatchError(ContainSubstring("unhandled units")))
+			})
+		})
+
+		It("can handle values in mg/dL", func() {
+			datum := dataTypesBloodGlucoseTest.NewGlucose(MgdL)
+			datum.Value = pointer.FromAny(100.0)
+			got, err := datum.Classify()
+			Expect(err).To(Succeed())
+			Expect(got).To(Equal(glucose.RangeTarget))
+		})
+
+		When("it's value is nil", func() {
+			It("returns an error", func() {
+				datum := dataTypesBloodGlucoseTest.NewGlucose(MmolL)
+				datum.Value = nil
+				_, err := datum.Classify()
+				Expect(err).To(MatchError(ContainSubstring("unhandled value: nil")))
+			})
+		})
+
+		When("it's units are nil", func() {
+			It("returns an error", func() {
+				datum := dataTypesBloodGlucoseTest.NewGlucose(nil)
+				datum.Value = pointer.FromAny(5.0)
+				_, err := datum.Classify()
+				Expect(err).To(MatchError(ContainSubstring("unhandled units: nil")))
+			})
+		})
+	})
 })
diff --git a/summary/types/glucose.go b/summary/types/glucose.go
@@ -2,7 +2,6 @@ package types
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"math"
 	"strconv"
@@ -14,6 +13,7 @@ import (
 	"github.com/tidepool-org/platform/data/blood/glucose"
 	glucoseDatum "github.com/tidepool-org/platform/data/types/blood/glucose"
 	"github.com/tidepool-org/platform/data/types/blood/glucose/continuous"
+	"github.com/tidepool-org/platform/errors"
 )
 
 const MaxRecordsPerBucket = 60 // one per minute max
@@ -162,31 +162,38 @@ func (rs *GlucoseRanges) Finalize(days int) {
 	}
 }
 
-func (rs *GlucoseRanges) Update(record *glucoseDatum.Glucose) {
-	normalizedValue := *glucose.NormalizeValueForUnits(record.Value, record.Units)
+func (rs *GlucoseRanges) Update(record *glucoseDatum.Glucose) error {
+	classification, err := record.Classify()
+	if err != nil {
+		return err
+	}
+
+	rs.Total.UpdateTotal(record)
 
-	if normalizedValue < veryLowBloodGlucose {
+	switch classification {
+	case glucoseDatum.RangeVeryLow:
 		rs.VeryLow.Update(record)
 		rs.AnyLow.Update(record)
-	} else if normalizedValue > veryHighBloodGlucose {
-		rs.VeryHigh.Update(record)
-		rs.AnyHigh.Update(record)
-
-		// VeryHigh is inclusive of extreme high, this is intentional
-		if normalizedValue >= extremeHighBloodGlucose {
-			rs.ExtremeHigh.Update(record)
-		}
-	} else if normalizedValue < lowBloodGlucose {
+	case glucoseDatum.RangeLow:
 		rs.Low.Update(record)
 		rs.AnyLow.Update(record)
-	} else if normalizedValue > highBloodGlucose {
-		rs.AnyHigh.Update(record)
-		rs.High.Update(record)
-	} else {
+	case glucoseDatum.RangeTarget:
 		rs.Target.Update(record)
+	case glucoseDatum.RangeHigh:
+		rs.High.Update(record)
+		rs.AnyHigh.Update(record)
+	case glucoseDatum.RangeVeryHigh:
+		rs.VeryHigh.Update(record)
+		rs.AnyHigh.Update(record)
+	case glucoseDatum.RangeExtremelyHigh:
+		rs.ExtremeHigh.Update(record)
+		rs.VeryHigh.Update(record)
+		rs.AnyHigh.Update(record)
+	default:
+		errMsg := "WARNING: unhandled classification %v; THIS SHOULD NEVER OCCUR"
+		return errors.Newf(errMsg, classification)
 	}
-
-	rs.Total.UpdateTotal(record)
+	return nil
 }
 
 func (rs *GlucoseRanges) CalculateDelta(current, previous *GlucoseRanges) {
@@ -237,7 +244,9 @@ func (b *GlucoseBucket) Update(r data.Datum, lastData *time.Time) (bool, error)
 		return false, nil
 	}
 
-	b.GlucoseRanges.Update(record)
+	if err := b.GlucoseRanges.Update(record); err != nil {
+		return false, err
+	}
 	b.LastRecordDuration = GetDuration(record)
 
 	return true, nil
diff --git a/summary/types/glucose_test.go b/summary/types/glucose_test.go
@@ -337,42 +337,42 @@ var _ = Describe("Glucose", func() {
 			glucoseRecord := NewGlucoseWithValue(continuous.Type, bucketTime, VeryLowBloodGlucose-0.1)
 			Expect(glucoseRanges.Total.Records).To(Equal(0))
 			Expect(glucoseRanges.VeryLow.Records).To(Equal(0))
-			glucoseRanges.Update(glucoseRecord)
+			Expect(glucoseRanges.Update(glucoseRecord)).To(Succeed())
 			Expect(glucoseRanges.VeryLow.Records).To(Equal(1))
 			Expect(glucoseRanges.Total.Records).To(Equal(1))
 
 			By("adding a Low value")
 			glucoseRecord = NewGlucoseWithValue(continuous.Type, bucketTime, LowBloodGlucose-0.1)
 			Expect(glucoseRanges.Low.Records).To(Equal(0))
-			glucoseRanges.Update(glucoseRecord)
+			Expect(glucoseRanges.Update(glucoseRecord)).To(Succeed())
 			Expect(glucoseRanges.Low.Records).To(Equal(1))
 			Expect(glucoseRanges.Total.Records).To(Equal(2))
 
 			By("adding a Target value")
 			glucoseRecord = NewGlucoseWithValue(continuous.Type, bucketTime, InTargetBloodGlucose+0.1)
 			Expect(glucoseRanges.Target.Records).To(Equal(0))
-			glucoseRanges.Update(glucoseRecord)
+			Expect(glucoseRanges.Update(glucoseRecord)).To(Succeed())
 			Expect(glucoseRanges.Target.Records).To(Equal(1))
 			Expect(glucoseRanges.Total.Records).To(Equal(3))
 
 			By("adding a High value")
 			glucoseRecord = NewGlucoseWithValue(continuous.Type, bucketTime, HighBloodGlucose+0.1)
 			Expect(glucoseRanges.High.Records).To(Equal(0))
-			glucoseRanges.Update(glucoseRecord)
+			Expect(glucoseRanges.Update(glucoseRecord)).To(Succeed())
 			Expect(glucoseRanges.High.Records).To(Equal(1))
 			Expect(glucoseRanges.Total.Records).To(Equal(4))
 
 			By("adding a VeryHigh value")
 			glucoseRecord = NewGlucoseWithValue(continuous.Type, bucketTime, VeryHighBloodGlucose+0.1)
 			Expect(glucoseRanges.VeryHigh.Records).To(Equal(0))
-			glucoseRanges.Update(glucoseRecord)
+			Expect(glucoseRanges.Update(glucoseRecord)).To(Succeed())
 			Expect(glucoseRanges.VeryHigh.Records).To(Equal(1))
 			Expect(glucoseRanges.Total.Records).To(Equal(5))
 
 			By("adding a High value")
 			glucoseRecord = NewGlucoseWithValue(continuous.Type, bucketTime, ExtremeHighBloodGlucose+0.1)
 			Expect(glucoseRanges.ExtremeHigh.Records).To(Equal(0))
-			glucoseRanges.Update(glucoseRecord)
+			Expect(glucoseRanges.Update(glucoseRecord)).To(Succeed())
 			Expect(glucoseRanges.ExtremeHigh.Records).To(Equal(1))
 			Expect(glucoseRanges.VeryHigh.Records).To(Equal(2))
 			Expect(glucoseRanges.Total.Records).To(Equal(6))
