InsuLearner: Estimating Insulin Pump Settings with Machine Learning

Author: Cameron Summers

Author's Website: www.CameronSummers.com

Project Surfaces

Open-source technical source of truth: InsuLearner on GitHub
Hosted product for people who do not want to run code locally: Insulearner Web
Public updates and release/blog context: CameronSummers.com

Warning:

This code can have significant impact on insulin dosing. There are no guardrails included here so it's possible to get poor results in some circumstances. Check with your doctor before making any changes to dosing settings.

Overview

This is the code underlying my article, where I describe the machine-learning approach used to estimate pump settings.

InsuLearner estimates:

Carbohydrate Ratio (CIR)
Basal Rate
Insulin Sensitivity Factor (ISF)

Supported data sources:

The model fits linear regression over aggregated carb/insulin windows and derives CIR + basal, then uses CSF (K) and CIR to estimate ISF.

Example settings plot

Dependencies

Python >=3.9,<4.0

Installation

pip install insulearner

Or for development:

git clone https://github.com/scaubrey/InsuLearner
cd InsuLearner
pip install -e .

Usage (CLI)

The package installs a CLI entrypoint: insulearner.

Tidepool Example

insulearner <your_tidepool_email> <your_tidepool_password> \
  --num_days 60 \
  --height_inches 72 \
  --weight_lbs 200 \
  --gender male

If you already know CSF:

insulearner <your_tidepool_email> <your_tidepool_password> --num_days 60 --CSF 4.2

Nightscout Example

insulearner --source nightscout \
  --nightscout_url https://your-site.example.com \
  --nightscout_token <token-if-used> \
  --nightscout_api_secret <api-secret-if-used> \
  --num_days 30 \
  --CSF 12.5

Notes:

--source defaults to tidepool.
For --source tidepool, positional tp_username tp_password are required.
For --source nightscout, --nightscout_url is required.

Nightscout compatibility note:

InsuLearner supports the main Nightscout data needed for analysis: entries, treatments, and profile.
Nightscout deployments vary in how they store and filter entries data. InsuLearner now handles common variants using date, mills, and created_at, with a client-side fallback when server-side filtering returns no rows.
Basal reconstruction remains the most deployment-specific part of Nightscout support, so results can still vary across custom setups, plugins, and treatment event conventions.
If you run into a compatibility issue, please open a GitHub issue and include a redacted sample of the relevant Nightscout JSON shape.

Key CLI Options

--num_days: number of days to analyze
--agg_period_window_size_hours: aggregation window size in hours (default: 24)
--agg_period_hop_size_hours: hop size in hours (default: 24)
--estimate_agg_boundaries: estimate aggregation boundaries via autocorrelation-like logic

Python API

from InsuLearner import (
    TidepoolUser,
    NightscoutUser,
    TidepoolAPI,
    NightscoutAPI,
    analyze_settings_lr,
)

Environment Variables for Tests (PyCharm-friendly)

Use .env.test in the repo root so you do not re-enter credentials each run.

Copy template:

cp .env.test.example .env.test

Fill values in .env.test.
Run tests from PyCharm or terminal. tests/conftest.py auto-loads .env.test.

Important:

.env.test is git-ignored.
.env.test.example is safe to commit.

Test Suite

Run all non-live tests:

pytest -q -m "not live"

Run all tests including live (requires credentials):

pytest -q

Run only live parity tests:

pytest -q -m "live"

Run lint:

ruff check .

CI

PR/Push CI runs non-live tests only.
Live API parity tests are split into a manual GitHub Actions workflow.

Release Process

See RELEASE.md for the checklist.

Acknowledgements

Special thanks to Tidepool for serving the diabetes community.

License

GPLv3

InsuLearner

Install / Use

README