Time in Range

calculateEnhancedTIR

Import: @glucoseiq/core

calculateEnhancedTIR(readings: GlucoseReading[], options?: EnhancedTIROptions): EnhancedTIRResult

Calculates Enhanced Time-in-Range metrics per International Consensus 2019.

Provides detailed breakdown of glucose readings across five clinical ranges:

• Very Low (<54 mg/dL / 3.0 mmol/L): Level 2 Hypoglycemia
• Low (54-69 mg/dL / 3.0-3.8 mmol/L): Level 1 Hypoglycemia
• In Range (70-180 mg/dL / 3.9-10.0 mmol/L): Target Range
• High (181-250 mg/dL / 10.1-13.9 mmol/L): Level 1 Hyperglycemia
• Very High (>250 mg/dL / >13.9 mmol/L): Level 2 Hyperglycemia

Returns: Enhanced TIR result with detailed metrics and target assessment

import { calculateEnhancedTIR, type GlucoseReading } from '@glucoseiq/core'

const readings: GlucoseReading[] = [
  { value: 120, unit: 'mg/dL', timestamp: '2024-01-01T08:00:00Z' },
  { value: 95, unit: 'mg/dL', timestamp: '2024-01-01T08:05:00Z' },
]
const result = calculateEnhancedTIR(readings)
console.log(`TIR: ${result.inRange.percentage}%`)
console.log(`Meets targets: ${result.meetsTargets.tirMeetsGoal}`)

Throws: If readings array is empty

Throws: If readings contain invalid glucose values or units

Throws: If population or thresholds are unsupported

See: International Consensus on Time in Range (2019)

Remarks: - Calculation accepts any nonempty array of valid glucose rows

• summary.dataQuality is poor below 3 days, fair from 3 days, good from 7 days, and excellent from 14 days; coverage below 70% is always poor
• For retrospective interpretation, separately assess the documented 14-day and 70% timestamp-coverage sufficiency guidance
• Standard targets: TIR >70%, cumulative TBR <4%, Level 2 TBR <1%, cumulative TAR <25%, Level 2 TAR <5%
• Overriding any range threshold changes targetBasis to configured-ranges; population percentage goals then apply to those configured ranges, not consensus ranges
• Verify data quality and sensor accuracy before drawing conclusions
• Summary duration estimates occupied 5-minute timestamp slots; invalid timestamps do not add duration
• Each occupied slot is divided among its distinct observations and zones; exact duplicates count once and integer minutes are conserved
• Percentages and reading counts still classify raw input rows, so callers should resolve conflicting duplicate observations before analysis

calculatePregnancyTIR

Import: @glucoseiq/core

calculatePregnancyTIR(readings: GlucoseReading[], options?: PregnancyTIROptions): PregnancyTIRResult

Calculates pregnancy-specific Time-in-Range metrics per ADA 2024 guidelines.

Uses tighter target range for pregnancy: 63-140 mg/dL (3.5-7.8 mmol/L). The quantified type 1 diabetes pregnancy targets are TIR >70%, total TBR <4%, Level 2 TBR <1%, and TAR <25%.

Returns: Pregnancy TIR result with target assessment and recommendations

import { calculatePregnancyTIR, type GlucoseReading } from '@glucoseiq/core'

const readings: GlucoseReading[] = [
  { value: 100, unit: 'mg/dL', timestamp: '2024-01-01T08:00:00Z' },
]
const result = calculatePregnancyTIR(readings)
console.log(`TIR: ${result.inRange.percentage}%`)
console.log(`Meets pregnancy targets: ${result.meetsPregnancyTargets}`)

Throws: If readings array is empty

Throws: If readings contain invalid glucose values or units

Throws: If options.unit is unsupported

See: ADA Standards of Care (2024)

Remarks: - Target range: 63-140 mg/dL (3.5-7.8 mmol/L)

• meetsPregnancyTargets applies the quantified type 1 diabetes pregnancy targets
• For type 2 and gestational diabetes, the range is endorsed but the cited guideline does not quantify percentage goals
• Summary duration estimates occupied 5-minute timestamp slots; invalid timestamps do not add duration
• Each occupied slot is divided among its distinct observations and primary ranges; exact duplicates count once and integer minutes are conserved
• Percentages and reading counts still classify raw input rows, so callers should resolve conflicting duplicate observations before analysis
• This is informational only and does not constitute medical advice

calculateTIR

Import: @glucoseiq/core

calculateTIR(readings: GlucoseReading[], target: { max: number; min: number }): TIRResult

Calculates Time in Range (TIR) metrics for glucose readings. Returns the percentage of readings in, below, and above the specified target range. This legacy API compares numeric values directly: every reading and both target bounds must use one homogeneous unit. Use calculateEnhancedTIR when readings carry mixed units that need normalization.

Returns: Object with in-range, below-range, and above-range percentages

See: https://care.diabetesjournals.org/content/42/8/1593

calculateTITR

Import: @glucoseiq/core

calculateTITR(readings: GlucoseReading[], options?: TITROptions): TITRResult

Calculates Time in Tight Range (TITR), the percentage of readings within a tighter 70-140 mg/dL band than standard TIR (70-180). The library's configurable default benchmark is 50%.

Unlike calculateTIR, input readings are normalized to mg/dL first, so mixed-unit series are handled correctly. Thresholds are always mg/dL.

Returns: Tight-range breakdown with target assessment

import { calculateTITR, type GlucoseReading } from '@glucoseiq/core'

const readings: GlucoseReading[] = [
  { value: 110, unit: 'mg/dL', timestamp: '2024-01-01T08:00:00Z' },
  { value: 7.2, unit: 'mmol/L', timestamp: '2024-01-01T08:05:00Z' },
]
const result = calculateTITR(readings, { target: 50 })
result.inRange

See: International Consensus on Time in Range (2019)

calculateTimeInRange

Import: @glucoseiq/core

calculateTimeInRange(readings: number[], lower: number, upper: number): number

Calculates the percentage of glucose readings within a specified numeric range.

Returns: Percentage of readings within the specified range (0-100)

getTIRSummary

Import: @glucoseiq/core

getTIRSummary(result: TIRResult): string

Formats the in-range, below-range, and above-range percentages in a TIRResult.

Returns: String summarizing in-range, below-range, and above-range percentages (e.g., 'In Range: 70%, Below: 10%, Above: 20%')

groupByDay

Import: @glucoseiq/core

groupByDay(readings: GlucoseReading[]): Record<string, GlucoseReading[]>

Groups glucose readings by date (YYYY-MM-DD).

Returns: An object mapping each date string to an array of readings for that day.