Variability & Risk Metrics

calculateActivePercent

calculateActivePercent(readings: GlucoseReading[], options?: ActivePercentOptions): ActivePercentResult

Calculates the CGM active percent (wear time).

Returns — Active percent result, or result with NaN if insufficient data

See: https://doi.org/10.2337/dc17-1600

calculateADRR

calculateADRR(readings: GlucoseReading[]): number

Calculates the Average Daily Risk Range (ADRR).

Returns — ADRR value, or NaN if no valid readings

See: https://doi.org/10.2337/dc06-1085

calculateCONGA

calculateCONGA(readings: GlucoseReading[], options?: CONGAOptions): number

Calculates CONGA (Continuous Overall Net Glycemic Action).

Returns — CONGA value in mg/dL, or NaN if insufficient matched pairs

See: https://doi.org/10.1089/dia.2005.7.253

calculateGRADE

calculateGRADE(readings: number[], hypoThreshold?: number, hyperThreshold?: number, unit?: GlucoseUnit): GRADEResult

Calculates the GRADE score and its partitioned components.

Returns — GRADE result with overall score and percentage breakdown, or NaN fields if no valid data

See: https://doi.org/10.1111/j.1464-5491.2007.02119.x

calculateGRI

calculateGRI(input: GRIInput): GRIResult

Calculates the Glycemia Risk Index (GRI) from TIR zone percentages.

Returns — GRI result with composite score and risk zone

See: https://doi.org/10.1177/19322968221085273

calculateGVIPGS

calculateGVIPGS(readings: GlucoseReading[], options?: GVIPGSOptions): GVIPGSResult

Calculates GVI and PGS from glucose readings (Nightscout algorithm).

Returns — GVI, PGS, the mean glucose, and PTIR; NaN when there are no valid steps

calculateIGC

calculateIGC(readings: number[], options?: IGCOptions): IGCResult

Calculates Rodbard's hypo/hyper indices and IGC.

Returns — Hypo index, hyper index, and their sum (IGC); NaN fields if no valid readings

See: https://doi.org/10.1089/dia.2008.0132

calculateJIndex

calculateJIndex(readings: number[], unit?: GlucoseUnit): number

Calculates the J-Index for a glucose trace.

The J-Index captures both central tendency and variability in a single score. Higher values indicate worse glycemic control.

Returns — J-Index value, or NaN if fewer than 2 valid readings

See: https://doi.org/10.1055/s-2007-979906

calculateMODD

calculateMODD(readings: GlucoseReading[], options?: MODDOptions): number

Calculates Mean of Daily Differences (MODD).

Returns — MODD value in mg/dL, or NaN if insufficient matched pairs

See: https://doi.org/10.2337/diacare.3.1.58

clinicalMAGE

clinicalMAGE(readings: number[], options?: MAGEOptions): number

Calculates Mean Amplitude of Glycemic Excursions (MAGE). Implements Service FJ et al. (1970) methodology.

Returns — MAGE value, or NaN if insufficient data or no valid excursions

// Basic usage
glucoseMAGE([100, 120, 80, 160, 90, 140, 70, 180])
// Advanced usage
glucoseMAGE(readings, { shortWindow: 5, longWindow: 32, direction: 'auto' })

See: - https://pubmed.ncbi.nlm.nih.gov/5469118/ (Service FJ, et al. 1970)

• https://journals.sagepub.com/doi/10.1177/19322968211061165 (Fernandes NJ, et al. 2022)
• https://care.diabetesjournals.org/content/42/8/1593 (ADA 2019)

glucoseCoefficientOfVariation

glucoseCoefficientOfVariation(readings: number[]): number

Calculates the coefficient of variation (CV) for glucose values. CV = (SD / mean) × 100. Used to assess glycemic variability.

Returns — Coefficient of variation as a percentage, or NaN if <2 values or mean is 0

Throws — If readings is not an array

glucoseCoefficientOfVariation([100, 120, 140]) // 18.26
glucoseCoefficientOfVariation([100]) // NaN
glucoseCoefficientOfVariation([]) // NaN

See: ADA 2019: Glycemic Targets

glucoseGVP

glucoseGVP(readings: GlucoseReading[]): number

Glycemic Variability Percentage (GVP): the percentage by which the length of the glucose trace exceeds the length of a flat line over the same time.

GVP = (L / L0 − 1) × 100, where L = Σ √(Δt² + Δglucose²) and L0 = Σ Δt (Δt in minutes, Δglucose in mg/dL).

Returns — GVP as a percentage, or NaN if < 2 readings or no time span

See: https://doi.org/10.1089/dia.2017.0187

glucoseHBGI

glucoseHBGI(readings: number[], unit?: GlucoseUnit): number

Calculates the High Blood Glucose Index (HBGI).

Quantifies the risk and extent of hyperglycemia from a glucose trace. Higher values indicate greater hyperglycemia risk.

Risk categories (Kovatchev 2006):

• < 4.5: low risk
• 4.5 - 9.0: moderate risk

• 9.0: high risk

Returns — HBGI value, or NaN if no valid readings

See: https://doi.org/10.2337/dc06-1085

glucoseLBGI

glucoseLBGI(readings: number[], unit?: GlucoseUnit): number

Calculates the Low Blood Glucose Index (LBGI).

Quantifies the risk and extent of hypoglycemia from a glucose trace. Higher values indicate greater hypoglycemia risk.

Risk categories (Kovatchev 2006):

• < 1.1: low risk
• 1.1 - 2.5: moderate risk

• 2.5: high risk

Returns — LBGI value, or NaN if no valid readings

See: https://doi.org/10.2337/dc06-1085

glucoseMAG

glucoseMAG(readings: GlucoseReading[]): number

Mean Absolute Glucose change rate (MAG): total absolute glucose change divided by total elapsed time, in mg/dL per hour.

Returns — MAG in mg/dL per hour, or NaN if < 2 readings or no time span

See: https://doi.org/10.1186/cc9002

glucoseMAGE

glucoseMAGE(readings: number[], options?: MAGEOptions): number

Calculates Mean Amplitude of Glycemic Excursions (MAGE) for glucose values. Implements Service FJ et al. (1970) methodology.

Returns — MAGE value, or NaN if insufficient data or no valid excursions

glucoseMAGE([100, 120, 80, 160, 90, 140, 70, 180])
glucoseMAGE(readings, { direction: 'ascending', shortWindow: 5, longWindow: 32 })

See: - https://pubmed.ncbi.nlm.nih.gov/5469118/ (Service FJ, et al. 1970)

• https://journals.sagepub.com/doi/10.1177/19322968211061165 (Fernandes NJ, et al. 2022)
• https://care.diabetesjournals.org/content/42/8/1593 (ADA 2019)

glucoseMValue

glucoseMValue(readings: number[], options?: MValueOptions): number

Calculates the Schlichtkrull M-value for a glucose series.

Returns — The M-value, or NaN if there are no valid (finite, > 0) readings

See: https://pubmed.ncbi.nlm.nih.gov/14163158/

glucosePercentiles

glucosePercentiles(readings: number[], percentiles: number[]): Record<number, number>

Calculates specified percentiles from an array of glucose values using the nearest-rank method. Used for glucose variability assessment.

Returns — Object mapping percentile to value, or {} if input is empty

Throws — If readings or percentiles is not an array

glucosePercentiles([100, 120, 140, 160, 180], [10, 50, 90]) // { 10: 100, 50: 140, 90: 180 }
glucosePercentiles([], [10, 50, 90]) // {}

See: - https://en.wikipedia.org/wiki/Percentile

• https://www.ncbi.nlm.nih.gov/pmc/articles/PMC7445493/ (ISPAD 2019)

glucoseStandardDeviation

glucoseStandardDeviation(readings: number[]): number

Calculates the unbiased sample standard deviation (SD) of glucose values. Uses n-1 in the denominator (sample SD), as recommended in research guidelines.

Returns — Standard deviation, or NaN if fewer than 2 values

Throws — If readings is not an array

glucoseStandardDeviation([100, 120, 140]) // 20
glucoseStandardDeviation([]) // NaN

See: - ADA 2019: Glycemic Targets

• ISPAD 2019