sugarsense-units 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dcc1213237aae5f99e43cf1f88dc91a40e62e8e285227223961022d23863c13b
+  data.tar.gz: 5ef263aaa45acd74d33487b2a7657e702c566e4b6f208df7464953bf8426aa27
+SHA512:
+  metadata.gz: 6d7833ba0a82dc6e8a2761807dae113954a856edf8855240176e0b9ae436c7577602a81d1bbdb6fe8652ebf9796718797f8f2b51cea3a84f0c9c9c6ba2d0fbf0
+  data.tar.gz: 7bbe2fb05bbf457f2a62d902235e5422ff0188c6dd9b9d64991b71564b0105bf8a2d066753e3db0ff8834cd5b05106d0596bcfeb7c9b65924bddc88dea830016

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sugar Sense (https://sugarsense.io)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,47 @@
+# 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](https://sugarsense.io), a CGM monitoring app for iOS, Apple Watch and Android that connects to FreeStyle Libre, Dexcom and [Nightscout](https://nightscout.github.io/) 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
+
+```sh
+gem install sugarsense-units
+```
+
+## Usage
+
+```ruby
+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](https://sugarsense.io) 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](https://app.sugarsense.io) and a free [download page](https://sugarsense.io/download).
+
+## License
+
+MIT

data/lib/sugarsense/units/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module SugarSense
+  module Units
+    VERSION = "0.1.0"
+  end
+end

data/lib/sugarsense/units.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "units/version"
+
+# Glucose unit and zone helpers, extracted from Sugar Sense (https://sugarsense.io).
+# All internal math is mg/dL; mmol/L exists only as a display conversion.
+# This library is informational only and contains no dosing logic.
+module SugarSense
+  module Units
+    MMOL_PER_MGDL = 0.0555
+
+    # ADA-aligned defaults used by Sugar Sense for new accounts (mg/dL).
+    DEFAULT_THRESHOLDS = { very_low: 55, low: 70, high: 180, very_high: 250 }.freeze
+
+    # CGM trend codes: 1 falling fast, 2 falling, 3 steady, 4 rising, 5 rising fast.
+    TREND_ARROWS = { 1 => "↓", 2 => "↘", 3 => "→", 4 => "↗", 5 => "↑" }.freeze
+    TREND_NAMES = {
+      1 => "falling_fast", 2 => "falling", 3 => "steady", 4 => "rising", 5 => "rising_fast"
+    }.freeze
+
+    module_function
+
+    # mg/dL -> mmol/L (unrounded float). Use format_glucose for the display form.
+    def mgdl_to_mmol(mgdl)
+      Float(mgdl) * MMOL_PER_MGDL
+    end
+
+    # mmol/L -> mg/dL, rounded to the nearest whole number.
+    def mmol_to_mgdl(mmol)
+      (Float(mmol) / MMOL_PER_MGDL).round
+    end
+
+    # Display formatting identical to the Sugar Sense apps:
+    # mmol/L is shown with exactly 1 decimal, mg/dL as a whole number.
+    # Rounding goes through Rational so the exact value of the IEEE double is
+    # rounded, matching JavaScript's toFixed(1) (100 mg/dL displays as "5.5");
+    # Ruby's own %.1f and Float#round(1) both give "5.6" for the same double.
+    def format_glucose(mgdl, unit = :mgdl)
+      case unit
+      when :mmol
+        mmol = Float(mgdl) * MMOL_PER_MGDL
+        format("%.1f", (Rational(mmol) * 10).round / 10.0)
+      when :mgdl then Float(mgdl).round.to_s
+      else raise ArgumentError, "unit must be :mgdl or :mmol"
+      end
+    end
+
+    def trend_arrow(code)
+      TREND_ARROWS.fetch(code, "")
+    end
+
+    def trend_name(code)
+      TREND_NAMES.fetch(code, "")
+    end
+
+    # Zone boundaries are inclusive on the out-of-range side:
+    #   :very_low  value <= very_low
+    #   :low       very_low < value <= low
+    #   :in_range  low < value < high
+    #   :high      high <= value < very_high
+    #   :very_high value >= very_high
+    def classify_zone(mgdl, thresholds = DEFAULT_THRESHOLDS)
+      v = Float(mgdl)
+      t = validate_thresholds(thresholds)
+      return :very_high if v >= t[:very_high]
+      return :very_low if v <= t[:very_low]
+      return :high if v >= t[:high]
+      return :low if v <= t[:low]
+
+      :in_range
+    end
+
+    # Five-band distribution over an array of mg/dL values.
+    # Returns { total:, counts: {zone => n}, percent: {zone => Float} }.
+    def time_in_range(readings, thresholds = DEFAULT_THRESHOLDS)
+      t = validate_thresholds(thresholds)
+      counts = { very_low: 0, low: 0, in_range: 0, high: 0, very_high: 0 }
+      readings.each { |v| counts[classify_zone(v, t)] += 1 }
+      total = readings.length
+      percent = counts.transform_values { |c| total.zero? ? 0.0 : c * 100.0 / total }
+      { total: total, counts: counts, percent: percent }
+    end
+
+    # Glucose Management Indicator (approximates lab A1C, %) from mean mg/dL.
+    # International consensus formula (Bergenstal et al., 2018).
+    def gmi(mean_mgdl)
+      3.31 + 0.02392 * Float(mean_mgdl)
+    end
+
+    def validate_thresholds(t)
+      unless t[:very_low] < t[:low] && t[:low] < t[:high] && t[:high] < t[:very_high]
+        raise ArgumentError, "thresholds must satisfy very_low < low < high < very_high"
+      end
+
+      t
+    end
+  end
+end

data/lib/sugarsense-units.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "sugarsense/units"

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: sugarsense-units
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sugar Sense
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-08-01 00:00:00.000000000 Z
+dependencies: []
+description: 'Glucose helpers extracted from the Sugar Sense CGM monitoring app: mg/dL
+  to mmol/L conversion, trend arrow codes, glucose zone classification, time in range
+  distribution and the GMI formula. Informational only, contains no dosing logic.'
+email:
+- info@sugarsense.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/sugarsense-units.rb
+- lib/sugarsense/units.rb
+- lib/sugarsense/units/version.rb
+homepage: https://sugarsense.io
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://sugarsense.io
+  documentation_uri: https://www.rubydoc.info/gems/sugarsense-units
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Blood glucose unit conversion, CGM trend arrows, zone classification and
+  time in range helpers.
+test_files: []