Skip to content

Quickstart

This page walks you through your first CGMPy analysis in ~5 minutes.

1. Install

If you haven't already:

pip install cgmpy
# or, for the full development setup:
pip install cgmpy[dev,docs,agata]

See Installation for details.

2. Get a CSV

CGMPy ships with a small synthetic dataset in tests/fixtures/data/dm.csv. You can also download a sample CGM export from any device and try with that — see Data formats for the expected columns.

3. Run the high-level facade

The simplest entry point is GlucoseAnalysis. It wraps loading, metric computation, and plotting in one class.

from pathlib import Path
from cgmpy import GlucoseAnalysis

# Adjust this to your CSV path
CSV_PATH = Path("tests/fixtures/data/dm.csv")

analysis = GlucoseAnalysis(str(CSV_PATH))

# 1. Human-readable summary
print(analysis.get_summary_string())

# 2. Programmatic access to every metric
report = analysis.get_comprehensive_report()
print(f"Time in Range: {report['time_in_range']['tir']:.1f} %")
print(f"Mean glucose:  {report['basic']['mean']:.1f} mg/dL")
print(f"GMI:           {report['basic']['gmi']:.1f} %")

# 3. Render the AGP dashboard
analysis.plot_comprehensive_dashboard()

You should see something like:

=== GlucoseAnalysis Summary ===
Records:    1 728 (24h)
Mean:       142.3 mg/dL
GMI:        6.7 %
TIR (70-180): 64.5 %
TAR (>180):    28.0 %
TBR (<70):     7.5 %
...

4. Use the modular API

If you need finer control, drop down to the modular classes.

from cgmpy import GlucoseData
from cgmpy.metrics.targets import get_targets
from cgmpy import GlucoseAnalysis

# Load
data = GlucoseData(str(CSV_PATH))

# Compute metrics
analysis = GlucoseAnalysis(data=data)
print(f"TIR: {analysis.TIR():.1f} %")
print(f"Mean: {analysis.mean():.1f} mg/dL")
print(f"GMI: {analysis.gmi():.1f} %")
print(f"CV: {analysis.cv():.1f} %")

5. Plot

All plot methods are available on the GlucoseAnalysis facade:

analysis.plot_agp()
analysis.histogram()
analysis.plot_time_in_range()
analysis.plot_comprehensive_dashboard()

For direct access to individual plot functions, import from the plotting submodules:

from cgmpy.plotting import agp, daily_plots, statistical_plots

agp.plot_agp(data.data)
daily_plots.day_graph(data.data)
statistical_plots.histogram(data.data)

6. Cross-validate with AGATA

from cgmpy import AgataAnalysis

agata = AgataAnalysis(data_source=str(CSV_PATH))
agata_results = agata.run()

See AGATA integration for details.

Where to go next

Sample data

If you do not have a CSV at hand, the repo includes three anonymized synthetic datasets:

File Size Profile
tests/fixtures/data/dm.csv 1 728 rows Type 1 Diabetes
tests/fixtures/data/nodm.csv 1 440 rows Non-diabetic subject
tests/fixtures/data/pregnancy.csv 4 320 rows Pregnancy trace

Never replace these with real data — see Security policy.