Tidepool Data Science Simulator

-- Project Status: Active

-- Project Disclaimer: This work is in Production

Project Objective

The purpose of this project is to enable simulation of patient metabolism and the interactions of controllers such as Tidepool Loop. The current phase is for supporting FDA risk analysis. The longer term goal is to support many activities such as Tidepool Loop performance analysis and evaluation of algorithms for settings optimization.

Ongoing development

This project supports ongoing risk assessment for Tidepool Loop. Changes (including exploring proposed changes) to the algorithm and new features all may require new development.

Project Description

During refactoring of the FDA risk analysis it became clear that increased generality/abstraction in an object-oriented approach to that code would support multiple projects of interest to Tidepool and Tidepool Data Science. The current state of this project is a generic simulator that facilitates answering questions around Tidepool Loop risk, Tidepool Loop performance, data-driven user modeling, and many others.

The refactored code on which this is based is in /notebooks/TEMPLATE_Run_Risk_Scenario_in_pyloopkit_in_colab_v0_5.ipynb

Technologies

• Python
• Anaconda for our virtual environments
• Pandas for working with data (99% of the time)
• Plotly for visualization
• Pytest for testing
• Travis for continuous integration testing
• Black for code style
• JSLint for linting
• Numpy docstring format

Getting Started with the Conda Virtual Environment

1. Install Miniconda. CAUTION for python virtual env users: Anaconda will automatically update your .bash_profile so that conda is launched automatically when you open a terminal. You can deactivate with the command conda deactivate or you can edit your bash_profile.
2. If you are new to Anaconda check out their getting started docs.
3. Clone this repo (for help see this tutorial).
4. In a terminal, navigate to the directory where you cloned this repo.
5. Run conda update -n base -c defaults conda to update to the latest version of conda
6. Run conda env create -f conda-environment.yml. This will download all of the package dependencies and install them in a conda (python) virtual environment.
7. Run conda env list to get a list of conda environments and select the environment that was created from the environmental.yml file (hint: environment name is at the top of the file)
8. Run conda activate <conda-env-name> or source activate <conda-env-name> to start the environment.
9. Run deactivate to stop the environment.

[bugfix] setup.py's packages=[...] omitted projects and validation (2026-07-21). This repo's local dev environment uses an editable (PEP 660) install, whose finder maps the whole top-level package to the source directory and lets Python's namespace-package resolution fill in every subpackage regardless of this list — so the gap was invisible in day-to-day development. It only bites a genuine non-editable install (a real pip install . producing a wheel/sdist, as needed for a distributed .app bundle): confirmed via an actual bdist_wheel build that, before this fix, loop_risk_v2_0.py and the whole validation/ package were silently excluded from the built wheel. Added tidepool_data_science_simulator.projects, tidepool_data_science_simulator.projects.risk, and tidepool_data_science_simulator.validation to the list; re-verified the same way that all four validation/ modules and projects/risk/*.py are now included. Limitation: other projects.* subpackages (icgm, loop_guardrails, swift_api, etc.) remain undeclared — out of scope here since nothing in this project's plan needs them distributed; revisit if a future packaging effort does.

Getting Started with this project

1. Current FDA scenarios are being kept scenario_configs/tidepool_risk_v2/loop_risk_v2_0 within this repo.
2. Exploratory iCGM sensitivity analyses are located in tidepool_data_science_simulator/projects/icgm within this repo.
3. Analysess of proposed Tidepool Loop therapy settings guardrails are located in tidepool_data_science_simulator/projects/loop_guardrails within this repo.

Using Swift Loop

In order to use the Swift implementation of the Loop Algorithm, you need:

• A machine running MacOS with XCode installed.
• To clone the LoopAlgorithmToPython respository with the built dylib (see Build Dynamic Library in the associated README).
• The tidepool-data-science-swift.yml conda environment installed and activated (see Getting Started with the Conda Virtual Environment).
  • Note - the conda environment assumes both the data-science-simulator and LoopAlgorithmToPython repositories are in the same directory.
• After installing/updating the swift environment, run ./scripts/build_swift_lib.sh to rebuild libLoopAlgorithmToPython.dylib from source against whatever loop_to_python_api is currently installed. The dylib checked into the LoopAlgorithmToPython repo can go stale relative to its own Swift source (a new exported function added without the binary being rebuilt), which shows up as a confusing AttributeError: dlsym(...): symbol not found at runtime. Re-run this script any time you hit that error.

[bugfix] conda-environment-swift.yml's data-science-models dependency is temporarily pinned to sf/incorporate_pa (2026-07-21), not main. VirtualPatient.instantiate_metabolism_model() (tidepool_data_science_simulator/models/patient.py:540-553) calls SimpleMetabolismModel(...) with physical-activity params (w_hr, a, tau, n) that only exist on that branch; main doesn't have them yet, so any env built against main fails every test that instantiates a metabolism model (insulin-model comparison, IOB consistency, physical-activity effect tests). Cautions: sf/incorporate_pa is an unmerged personal branch in the data-science-models repo — this pin is a stopgap, not a permanent dependency choice. Rollback note (High regression risk — core metabolism model): if this branch is abandoned or its physical-activity API changes shape before merging, revert the pin in conda-environment-swift.yml to git+https://github.com/tidepool-org/data-science-models (main) and re-pin patient.py:540-553's call accordingly (or roll back the physical-activity integration in patient.py to match whatever main supports at that time). Once sf/incorporate_pa merges to main, drop the @sf/incorporate_pa ref entirely.

Using the SwiftLoopController class

The SwiftLoopController class can be directly substituted for the LoopController class when setting up simulator experiments.

The SwiftLoopController can be selected via configuration override by specifying "controller": { "id": "swift"} instead of "controller": {"id": "pyloopkit_v1"}.

Contributing Guide

1. All are welcome to contribute to this project.
2. Naming convention for notebooks is [short_description]-[initials]-[date_created]-[version], e.g. initial_data_exploration-jqp-2020-04-25-v-0-1-0.ipynb. A short _ delimited description, the creator's initials, date of creation, and a version number,
3. Naming convention for data files, figures, and tables is [PHI (if applicable)]-[short_description]-[date created or downloaded]-[code_version], e.g. raw_project_data_from_mnist-2020-04-25-v-0-1-0.csv, or project_data_figure-2020-04-25-v-0-1-0.png.

NOTE: PHI data is never stored in github and the .gitignore file includes this requirement as well.

Important TODOs

• Integrate iCGM sensor and analysis scenarios (size: medium)
• Testing and cleanup (size: medium to large)
• Integrate visuals and metrics repos (size: small)
• Surface all parameters for configuration (size: small)
• Control randomness via config seed(s) (size: small)
• Speed up Pyloopkit, possible in this code base (size: medium to large)

Tidepool Contributors

Current Tidepool Contributors

Name (with github link)
Mark Connolly
Shawn Foster
Pete Schwamb

Previous Tidepool Contributors

Name (with github link)
Ed Nykaza
Jason Meno
Cameron Summers
Anna Quinlan
Eden Grown-Haeberli