How Nightscout Calculates Total Basal Insulin
An interactive AI-enhanced guide to understanding the sophisticated reconciliation algorithm at the heart of Nightscout’s insulin reporting.
The Core Concept: Plan vs. Actual
The central finding of the analysis is that total basal insulin is not a single number stored in the database. It’s calculated by a clever reconciliation process that compares the therapy *plan* with what *actually* happened. This separation is the key to Nightscout’s accuracy.
The Plan
`profile` collection
This represents the user’s intended therapy. It’s a pre-programmed, time-segmented **Scheduled Basal Rate** that defines the default insulin delivery for different times of the day. It’s the baseline expectation.
The Actual
`treatments` collection
This is a chronological log of real-world events. When an automated system or user makes a **Temporary Basal Rate (TBR)** adjustment (e.g., to correct a high BG), it’s recorded here. These are the deviations from the plan.
The Basal Data Pipeline
Data doesn’t just appear; it flows through a modular system of plugins. These plugins act as bridges, translating data from various devices into a standard format that Nightscout can understand and store. Hover over the nodes below to see their role in the pipeline.
DIY Loop Systems
Insulin Pumps
Manual Entry
Uploader Plugins (`loop`, `pump`, `openaps`)
MongoDB Database
Reporting Engine
The Algorithm Simulator
This is where the magic happens. The chart below shows a 24-hour period with a simple scheduled basal rate. Use the buttons to add temporary basals, then click “✨ Explain Scenario” to get an AI-powered analysis of the event.
Scheduled Total
24.0 U
Actual Delivered
24.0 U
Net Change
0.0 U
Data Deep Dive
The calculation algorithm relies on specific fields within the MongoDB `profile` and `treatments` collections. Explore the tabs below to see the raw structure of the data that drives the entire process.
Key Takeaways & Recommendations
For Developers
To accurately calculate insulin statistics, you **must** query both `profile` and `treatments` collections. A naive summation or reliance on a single data source will produce incorrect results.
Your logic must implement the reconciliation algorithm to achieve parity with Nightscout’s native reports, correctly handling time-variant profiles and overlapping temporary basals.
For Researchers & Clinicians
The accuracy of all aggregate reports (like Total Daily Dose) depends entirely on the completeness of the data in the `treatments` collection.
Be aware of the “garbage-in, garbage-out” principle. Data gaps from uploader issues (e.g., dead phone battery, poor connectivity) will cause Nightscout to default to the scheduled basal, potentially skewing the calculated totals. Always consider data integrity when using Nightscout for clinical analysis.
Get a Personalized Summary
Select your role, and Gemini AI will create a custom summary of the key takeaways for you.
Created with Gemini’s Deep Research.