sugarsense-units

Blood glucose unit conversion (mg/dL to mmol/L and back), CGM trend arrows, glucose zone classification, time in range and GMI helpers for Ruby. No dependencies.

Extracted from Sugar Sense, a CGM monitoring app for iOS, Apple Watch and Android that connects to FreeStyle Libre, Dexcom and Nightscout and shares glucose with family in real time. These are the exact conventions the app uses in production, published so other diabetes tools can reuse them instead of re-deriving the math.

This library is informational only. It contains no insulin dosing logic and gives no medical advice.

Install

gem install sugarsense-units

Usage

require "sugarsense-units"

SugarSense::Units.mgdl_to_mmol(100)            # => 5.55
SugarSense::Units.format_glucose(120, :mmol)   # => "6.7"  (display form, 1 decimal)
SugarSense::Units.trend_arrow(2)               # => "↘"
SugarSense::Units.classify_zone(65)            # => :low
SugarSense::Units.gmi(154)                     # => 6.99  (approximates lab A1C, %)

SugarSense::Units.time_in_range([50, 60, 100, 150, 200, 300])
# => { total: 6,
#      counts:  { very_low: 1, low: 1, in_range: 2, high: 1, very_high: 1 },
#      percent: { very_low: 16.67, low: 16.67, in_range: 33.33, high: 16.67, very_high: 16.67 } }

Conventions

These match the Sugar Sense production apps and backend:

  • All math is done in mg/dL; mmol/L is a display conversion (factor 0.0555, shown with 1 decimal).
  • Trend codes are integers 1 to 5: 1 ↓ falling fast, 2 ↘ falling, 3 → steady, 4 ↗ rising, 5 ↑ rising fast (the same scheme Dexcom, Libre and Nightscout data can be normalized to).
  • Zones: :very_low, :low, :in_range, :high, :very_high, with boundaries inclusive on the out-of-range side (a value exactly at the low limit is :low, exactly at the high limit is :high).
  • Default thresholds are 55 / 70 / 180 / 250 mg/dL (DEFAULT_THRESHOLDS), aligned with ADA guidance. Every method accepts custom thresholds.

About Sugar Sense

Sugar Sense turns CGM data into real-time monitoring for the whole family: glucose on the lock screen and Apple Watch, low and high alerts, an automated emergency call on urgent lows, and a Care Circle so loved ones can follow along. There is also a web dashboard and a free download page.

License

MIT