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

data/blood/glucose/glucose.go

@@ -2,7 +2,9 @@ package glucose
 
 import (
 	"math"
+	"slices"
 
+	"github.com/tidepool-org/platform/errors"
 	"github.com/tidepool-org/platform/pointer"
 )
 
@@ -70,6 +72,10 @@ func NormalizeUnits(units *string) *string {
 	return units
 }
 
+// NormalizeValueForUnits converts Mg/dL values to Mmol/L.
+//
+// Values paired with any other units (including nil or typos) are NOT normalized or
+// modified, but are returned as-is.
 func NormalizeValueForUnits(value *float64, units *string) *float64 {
 	if value != nil && units != nil {
 		switch *units {
@@ -82,6 +88,33 @@ func NormalizeValueForUnits(value *float64, units *string) *float64 {
 	return value
 }
 
+// NormalizeValueForUnitsSafer behaves like NormalizeValueForUnits, but with more safety.
+//
+// Where "safety" means returning an error in certain cases where its namesake would return
+// the original value.
+//
+// Notable cases include:
+//   - when units is nil but values is not
+//   - when units are not a recognized value in Units()
+func NormalizeValueForUnitsSafer(value *float64, units *string) (float64, error) {
+	if units == nil {
+		return 0, errors.New("unable to normalize: unhandled units: nil")
+	}
+	if !slices.Contains(Units(), *units) {
+		return 0, errors.Newf("unable to normalize: unhandled units: %s", *units)
+	}
+	if value == nil {
+		return 0, errors.New("unable to normalize: unhandled value: nil")
+	}
+	normalized := NormalizeValueForUnits(value, units)
+	if normalized == nil {
+		// The only time this should happen is when a nil value was passed, and that case is
+		// covered above, but it's better to be safe than sorry.
+		return 0, errors.New("unable to normalize: normalization returned nil")
+	}
+	return *normalized, nil
+}
+
 func ValueRangeForRateUnits(rateUnits *string) (float64, float64) {
 	if rateUnits != nil {
 		switch *rateUnits {

data/types/blood/glucose/glucose.go

@@ -1,9 +1,14 @@
 package glucose
 
 import (
+	"cmp"
+	"math"
+	"slices"
+
 	"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 +38,102 @@ func (g *Glucose) Normalize(normalizer data.Normalizer) {
 		g.Value = dataBloodGlucose.NormalizeValueForUnits(g.Value, units)
 	}
 }
+
+func roundToEvenWithDecimalPlaces(v float64, decimals int) float64 {
+	if decimals == 0 {
+		return math.RoundToEven(v)
+	}
+	coef := math.Pow10(decimals)
+	return math.RoundToEven(v*coef) / coef
+}
+
+type Classification string
+
+const (
+	ClassificationInvalid Classification = "invalid"
+
+	VeryLow       = "very low"
+	Low           = "low"
+	InRange       = "in range"
+	High          = "high"
+	VeryHigh      = "very high"
+	ExtremelyHigh = "extremely high"
+)
+
+type classificationThreshold struct {
+	Name      Classification
+	Value     float64
+	Inclusive bool
+}
+
+type Classifier []classificationThreshold
+
+func (c Classifier) Classify(g *Glucose) (Classification, error) {
+	// All values are normalized to MmolL before classification. To not do so risks
+	// introducing inconsistency between frontend, backend, and/or other reports. See
+	// BACK-3800 for details.
+	normalized, err := dataBloodGlucose.NormalizeValueForUnitsSafer(g.Value, g.Units)
+	if err != nil {
+		return ClassificationInvalid, errors.Wrap(err, "unable to classify")
+	}
+	// Rounded values are used for all classifications. To not do so risks introducing
+	// inconsistency between frontend, backend, and/or other reports. See BACK-3800 for
+	// details.
+	rounded := roundToEvenWithDecimalPlaces(normalized, 1)
+	sortThresholds(c)
+	for _, threshold := range c {
+		if threshold.Includes(rounded) {
+			return threshold.Name, nil
+		}
+	}
+	// Ensure your highest threshold has a value like math.MaxFloat64 to avoid this.
+	return ClassificationInvalid, errors.Newf("unable to classify value: %v", *g)
+}
+
+func sortThresholds(ts []classificationThreshold) {
+	slices.SortFunc(ts, func(i, j classificationThreshold) int {
+		if valueCmp := cmp.Compare(i.Value, j.Value); valueCmp != 0 {
+			return valueCmp
+		}
+		if !i.Inclusive && j.Inclusive {
+			return -1
+		} else if i.Inclusive == j.Inclusive {
+			return 0
+		} else {
+			return 1
+		}
+	})
+}
+
+// Config helps summaries report the configured thresholds.
+//
+// These will get wrapped up into a Config returned with the summary report. A simple map
+// provides flexibility until we better know how custom classification ranges are going to
+// work out.
+func (c Classifier) Config() map[Classification]float64 {
+	config := map[Classification]float64{}
+	for _, classification := range c {
+		config[classification.Name] = classification.Value
+	}
+	return config
+}
+
+// TidepoolADAClassificationThresholdsMmolL for classifying glucose values.
+//
+// In addition to the standard ADA ranges, the Tidepool-specifiic "extremely high" range is
+// added.
+var TidepoolADAClassificationThresholdsMmolL = Classifier([]classificationThreshold{
+	{Name: VeryLow, Value: 3, Inclusive: false},                    // Source: https://doi.org/10.2337/dc24-S006
+	{Name: Low, Value: 3.9, Inclusive: false},                      // Source: https://doi.org/10.2337/dc24-S006
+	{Name: InRange, Value: 10, Inclusive: true},                    // Source: https://doi.org/10.2337/dc24-S006
+	{Name: High, Value: 13.9, Inclusive: true},                     // Source: https://doi.org/10.2337/dc24-S006
+	{Name: VeryHigh, Value: 19.4, Inclusive: true},                 // Source: https://doi.org/10.2337/dc24-S006
+	{Name: ExtremelyHigh, Value: math.MaxFloat64, Inclusive: true}, // Source: BACK-2963
+})
+
+func (c classificationThreshold) Includes(value float64) bool {
+	if c.Inclusive && value <= c.Value {
+		return true
+	}
+	return value < c.Value
+}

data/types/blood/glucose/glucose_test.go

@@ -481,4 +481,143 @@ var _ = Describe("Glucose", func() {
 			),
 		)
 	})
+
+	Context("Classify", func() {
+		var MmolL = pointer.FromAny(dataBloodGlucose.MmolL)
+		var MgdL = pointer.FromAny(dataBloodGlucose.MgdL)
+
+		checkClassification := func(value float64, expected glucose.Classification) {
+			GinkgoHelper()
+			datum := dataTypesBloodGlucoseTest.NewGlucose(MmolL)
+			datum.Value = pointer.FromAny(value)
+			got, err := glucose.TidepoolADAClassificationThresholdsMmolL.Classify(datum)
+			Expect(err).To(Succeed())
+			Expect(got).To(Equal(expected))
+		}
+
+		checkClassificationMgdL := func(value float64, expected glucose.Classification) {
+			GinkgoHelper()
+			datum := dataTypesBloodGlucoseTest.NewGlucose(MgdL)
+			datum.Value = pointer.FromAny(value)
+			got, err := glucose.TidepoolADAClassificationThresholdsMmolL.Classify(datum)
+			Expect(err).To(Succeed())
+			Expect(got).To(Equal(expected))
+		}
+
+		It("classifies 2.9 as very low", func() {
+			checkClassification(2.9, "very low")
+		})
+
+		It("classifies 3.0 as low", func() {
+			checkClassification(3.0, "low")
+		})
+
+		It("classifies 3.8 as low", func() {
+			checkClassification(3.8, "low")
+		})
+
+		It("classifies 3.9 as in range", func() {
+			checkClassification(3.9, "in range")
+		})
+
+		It("classifies 10.0 as in range", func() {
+			checkClassification(10.0, "in range")
+		})
+
+		It("classifies 10.1 as high", func() {
+			checkClassification(10.1, "high")
+		})
+
+		It("classifies 13.9 as high", func() {
+			checkClassification(13.9, "high")
+		})
+
+		It("classifies 14.0 as very high", func() {
+			checkClassification(14.0, "very high")
+		})
+
+		It("classifies 19.4 as very high", func() {
+			checkClassification(19.4, "very high")
+		})
+
+		It("classifies 19.5 as extremely high", func() {
+			checkClassification(19.5, "extremely high")
+		})
+
+		When("its classification depends on rounding", func() {
+			It("classifies 2.95 as low", func() {
+				checkClassification(2.95, "low")
+			})
+
+			It("classifies 3.85 as low", func() {
+				checkClassification(3.85, "low")
+			})
+
+			It("classifies 10.05 as in range", func() {
+				checkClassification(10.05, "in range")
+			})
+		})
+
+		When("it doesn't recognize the units", func() {
+			It("returns an error", func() {
+				badUnits := "blah"
+				datum := dataTypesBloodGlucoseTest.NewGlucose(&badUnits)
+				datum.Value = pointer.FromAny(5.0)
+				_, err := glucose.TidepoolADAClassificationThresholdsMmolL.Classify(datum)
+				Expect(err).To(MatchError(ContainSubstring("unable to normalize: unhandled units")))
+			})
+		})
+
+		It("can handle values in mg/dL", func() {
+			checkClassificationMgdL(100.0, "in range")
+		})
+
+		When("it's value is nil", func() {
+			It("returns an error", func() {
+				datum := dataTypesBloodGlucoseTest.NewGlucose(MmolL)
+				datum.Value = nil
+				_, err := glucose.TidepoolADAClassificationThresholdsMmolL.Classify(datum)
+				Expect(err).To(MatchError(ContainSubstring("unable to normalize: unhandled value")))
+			})
+		})
+
+		When("it's units are nil", func() {
+			It("returns an error", func() {
+				datum := dataTypesBloodGlucoseTest.NewGlucose(nil)
+				datum.Value = pointer.FromAny(5.0)
+				_, err := glucose.TidepoolADAClassificationThresholdsMmolL.Classify(datum)
+				Expect(err).To(MatchError(ContainSubstring("unable to normalize: unhandled units")))
+			})
+		})
+
+		Context("tests from product", func() {
+			It("classifies 69.5 mg/dL as Low", func() {
+				checkClassificationMgdL(69.5, "in range")
+			})
+
+			It("classifies 70.0 mg/dL as In Range", func() {
+				checkClassificationMgdL(70, "in range")
+			})
+
+			It("classifies 180.4 mg/dL as In Range", func() {
+				checkClassificationMgdL(180.4, "in range")
+			})
+
+			It("classifies 180.5 mg/dL as In Range", func() {
+				checkClassificationMgdL(180.5, "in range")
+			})
+
+			It("classifies 181.0 mg/dL as In Range", func() {
+				checkClassificationMgdL(181, "in range")
+			})
+
+			It("classifies 10.05 mmol/L as in range", func() {
+				checkClassification(10.05, "in range")
+			})
+
+			It("classifies 10.15 mmol/L as High", func() {
+				checkClassification(10.15, "high")
+			})
+		})
+	})
 })