Loop Features in Development
This page provides documentation for selected features you can add to your Loop app as customizations. Some of these features are included in the development (dev) branch and some are proposed to be added to the development branch. These changes happen through a formal process called a “Pull Request”, often abbreviated as PR. The number associated with the pull request uniquely identifies where the code changes are stored for evaluation. Several of the PR documented on this page have been merged (added to) dev. The PR, even after they are merged and closed, are still available at GitHub, so the PR links posted below continue to work.
This page is devoted to describing features proposed or added to dev that are available as part of the Customization Select script. If you want to add one of these features, go to that link for detailed instructions.
WARNING: These are development features and you are responsible for understanding them prior to use. Please join the zulipchat development stream and review each PR conversation (see link associated with each feature). If you have specific comments or questions, use the zulipchat link.
The Algorithm Experiments feature is a combination of PR 1988: Glucose Based Partial Application and PR 2008: Integral Retrospective Correction. The Customization (for main, 3.2.x, only) adds them as a pair. Both were added to dev in late June 2023. In addition to those links that explain the feature, some testing was done comparing how Loop responds to the same glucose pattern with those features disabled and enabled. See Algorithm Experiments Testing for those results.
The other feature on this page is still in the Pull Request process. If you want PR 2002: Profiles, you need to add it to your code whether you are running main (3.2.x) or dev version.
Once these customizations are added to your version of Loop, each feature can be individually turned on and off. The features on this page are different from the CustomTypeOne LoopPatches in that each feature is selectable inside the Loop app and is subject to guardrails within Loop. Over time, some items in the CustomTypeOne LoopPatches may be converted to a formal PR. For example the Switcher patch in the CustomTypeOne LoopPatches is replaced by Glucose Based Partial Application (PR 1988). Depending on what version you are modifying and the customizations you have applied, the script automatically selects code that is compatible.
The Loop Features in Development options provided by the Customization Select Script are:
- Profiles (PR 2002)
- Save and load named Profiles, which contain a subset of your Therapy Settings
- Algorithm Experiments (affects delivery of insulin by Loop):
- NOTE: These were merged into dev on 25-June-2023 so will show up as incompatible with dev (already in the code); they can be applied to released Loop (main branch, 3.2.x)
If you have never used the Customization Select Script before, please go to that link and read about it.
All users:
- Sometimes a PR is updated based on conversations with the developers and the community
- When that happens, it may take a few days before the customizations in this script are updated
- Once they are updated, however, run the CustomizationSelect script again and you will be offered an updated version for any feature you have already added to your code
- Sometimes features are requested that can be added, but not in a manner that would be acceptable as a long-term solution
- In those cases, the customization may not match what is in the formal pull request
- An example is the ability to load the current profile name to Nightscout
Users of Loop dev branch:
- Sometimes updates to the dev code require the PR to be modified to maintain compatibility
- When that happens, it may take a few days before the customizations are updated
- In that case, keep using the older versions of dev
For those who previously had PR 1988 and PR 2008 added via customization using the Mac-Xcode build method, you need to start fresh. The update feature is not available. A fresh clone is a good idea. For those using Browser Build, you always start with a fresh clone.
Algorithm Experiments
Algorithm Experiments provide two methods that modify the way in which Loop doses insulin. Each one is off by default and can be enabled or disabled separately.
Do you also use CustomTypeOne LoopPatches? If so, be aware that the temp basal / auto bolus switcher patch is removed when you use Algorithm Experiments. Instead, turn on Glucose Based Application Factor, which replaces the functionality. You may need to adjust settings. See Switcher Patch for more information.
With the next release of Loop, Algorithm Experiments will be included.
Loop Docs has a section devoted to these two Algorithm Experiments that is currently located on the Loop Development page. It it anticipated these features will be available in the next release. At that time, the links will be updated to a new location.
The zulipchat discussion for these experiments is under the development stream, Algorithm Experiments topic.
The formal PR and feature details are summarized at these links:
After the initial merge of Integral Retrospective Correction into dev, an additional modification was added (PR 2028).
This was added to the customization script on 27-Jul-2023. If you are running this customization with released Loop code, please run the Customization Script again.
Loop Settings Screen with Algorithm Experiments
The graphic below shows an updated Loop Settings screen that included Algorithm Experiments as added to the development branch (dev) in late June 2023.
The Glucose Based Partial Application and Integral Retrospective Correction are grouped under the Algorithm Experiments section. The default setting for each customization is to be off. This image shows both disabled. If you tap on a row, the information screen is presented with the enable/disable slider at the bottom of the screen.
PR 2002: Profiles
The Profile feature is crafted to swiftly save and transition between therapy setting subsets tailored to your needs.
This is a work in progress, but even with the current code, it is quite useful. After adding this customization, the Profiles row is found on the Loop Settings screen below the Therapy Settings option. A pump must be added to Loop for the Profiles screen to be visible.
On 20 January 2024, this feature was enhanced to upload the name of the current Profile to Nightscout. This was added at the request of caregivers who also use Loop Follow. Note that only the current Profile is uploaded to Nightscout.
- Therapy Settings included in the saved Profile
- Basal Rate Schedule
- Correction Schedule
- Carb Ratio Schedule
- Insulin Senstivity Factor Schedule
The User can save new profiles (from their current Therapy Settings), and they can load, rename or delete saved profiles
- The Profiles are saved in the local Loop Storage on the users phone
- To edit an existing profile that is currently selected
- Edit Therapy Settings and Save
- Go to the Profiles screen and Update the profile
- To create a new profile
- Edit Therapy Settings and Save
- Go to the Profiles screen and Cancel instead of updating the profile
- Tap on the + sign to create a new Saved Profile and name it
- To load a Saved Profile
- Go to the Profiles screen and select the desired profile
- After reviewing the settings, select the Load Profile button to update to those saved Therapy settings
Loop Settings Screen with Profiles Added
The graphic below shows an updated Loop Settings screen when the profiles customizations is added.
The Profiles feature is accessed by tapping on the Profiles button underneath Therapy Settings.
Reverse Chronology of Updates
- As of 13 September 2023 an enhancement was added – graphics above are from this version
- An information screen is presented when you select the “i”
- The Profile that was last saved from your Therapy Settings is now indicated with a check mark
- If you modified Therapy Settings (basal, correction, CR or ISF) after saving a profile – you are offered the choice to update the named profile
- If you choose not to update the named profile, you can save it as a new profile
- You can reorder the profiles in the list by holding and dragging
- As of 20 January 2024, the current Profile name is uploaded to Nightscout, (but still not to Tidepool)
- To accommodate the requirements of Nightscout, the “.” and “<” characters cannot be used in a profile name
- Any existing, or new, profile names will automatically have those characters replaced with an underscore (“_”) – feel free to rename again, just find something other than “.” or “<” to use – they will be replaced when you save
- The length of the name is now truncated to 32 characters to improve legibility in Nightscout and in LoopFollow
- There are slight differences in Nightscout behavior for 14.2.6 and 15.0.2, with 15.0.2 recommended
- Nightcout: Dashboard display shows the current Profile name on the left side plot
- Nightscout: Edit Profiles shows the current Profile name
- Nightscout: Reports: Profiles are a side-by-side display of identical profiles called Default and current Profile name
- Sometimes when the user renames a profile, the old name may be displayed in Nightscout: Reports: Profiles
- Nightscout: Reports: Day-to-Day plot is the one active at midnight and has same naming issues as the Reports: Profiles
The formal PR is found at https://github.com/LoopKit/Loop/pull/2002.
PR 1988: Glucose Based Partial Application Factor
On 25 June 2023, this feature was added to the dev branch of Loop and LoopWorkspace. The Customization Select script is updated to provide main branch customizations that match the final look and feel of what was added to dev.
PR 1988 provides an experimental feature to modify the behavior of Automatic Bolus Dosing Strategy with a Glucose Based Partial Application factor.
- The new feature is found on the Loop Settings screen in a new section called `Algorithm Experiments`
- Click on the row for Glucose Based Partial Application to read the screen explaining the method and to enable or disable (default) the option
- This feature only applies to Automatic Bolus
- When enabled, Loop gradually increases the Automatic Bolus percentage from a value similar to the speed provided by Temp Basal method when glucose is near correction range to a higher percentage as glucose rises
- The lower Bolus Percentage (20%) is used until glucose is more than 10 mg/dL higher than the Looper’s current correction range lower bound (including overrides)
- The higher Bolus Percentage (80%) is reached when glucose reaches 200 mg/dL (11.1 mmol/L)
- There is no change to the Loop model that calculates the recommended bolus
This experimental feature removes the need for the CustomTypeOne LoopPatches Switcher patch. (The Switcher Patch toggles between Temp Basal and Automatic Bolus (using a constant percentage of 40%) at a fixed glucose threshold.) For those users of the CustomTypeOne LoopPatches, the script automatically updates the version of CustomTypeOne LoopPatches to one compatible with the Glucose Based Partial Application Factor. This modified version of LoopPatches does not include the Switcher patch.
The graphic above shows the effective bolus application for various dosing strategies when Loop predicts more insulin is required. This factor is multiplied times the Loop recommended bolus with each Loop cycle (5 minutes).
- The Temp Basal is the slowest to provide recommended insulin
- Some people find the constant factor of 40% for the Automatic Bolus method to be too aggressive when glucose is close to correction range
- Some people find Loop not aggressive enough as glucose rises
- This feature provides a gradually increasing factor as glucose rises
- The value at which the factor begins to increase from 20% depends on the user’s lower bound for their correction range
- The factor reaches 80% when glucose reaches 200 mg/dL (11.1 mmol/L)
- This feature does not modify the model Loop uses to calculate the recommended bolus
The formal PR is found at https://github.com/LoopKit/Loop/pull/1988.
Early zulipchat discussions are found under development stream Glucose Based Partial Application Factor topic.
Once this feature was merged into dev, the zulipchat discussion moved to zulipchat Algorithm Experiments.
PR 2008: Integral Retrospective Correction
On 25 June 2023, this feature was added to the dev branch of Loop and LoopWorkspace. The Customization Select script is updated to provide main branch customizations that match the final look and feel of what was added to dev.
After the initial merge of Integral Retrospective Correction into dev, an additional modification was added (PR 2028) and incorporated in the customization script on 27-Jul-2023. If you are running this customization with released Loop code, please run the Customization Script again. This limits the aggressiveness of IRC in some situations.
Integral Retrospective Correction (IRC) provides an experimental feature to modify the calculation of recommended insulin delivery. Please apply with care – you may find your settings require an adjustment when you enable this feature. (The most common change is a slight increase to the ISF number.)
- The new feature is found on the Loop Settings screen in a new section called `Algorithm Experiments`
- By tapping on the row for Integral Retrospective Correction, you are shown a screen explaining the method and allowed to enable or disable (default) it at the bottom of the screen
- This feature applies to any type of Dosing Strategy – it modifies the calculation of recommended insulin
The formal PR is found at https://github.com/LoopKit/Loop/pull/2008.
The updated change is found at https://github.com/LoopKit/Loop/pull/2028.
Initial zulipchat discussion on is found under development stream Integral Retrospective Correction topic.
Once this feature was merged into dev, the zulipchat discussion moved to zulipchat Algorithm Experiments.
Algorithm Experiments Glucose Tests
This section shows the changes expected with the Algorithm Experiments for two cases:
- An Unannounced Meal
- A night with repeated low glucose (Very Bad Night)
Graphics below show what Loop does in response to a glucose pattern with the algorithm experiment features disabled or enabled. For each glucose pattern, the graphics show the Loop Dosing results for Glucose Based Partial Application (GBPA) turned Off or On (with IRC off), Integral Retrospective Correction (IRC) turned Off or On (with GBPA off), and all 4 combinations of these options.
The solid black line in each plot shows how Loop behaves with algorithm experiments turned off. The dashed, dotted and dash-dot lines are labeled to indicate which feature(s) is enabled.
In real life:
- Dosing insulin sooner lowers glucose sooner
- Increasing insulin can help a stuck on high situation
- If your settings are wrong, getting more insulin sooner might worsen a low
Not in real life:
- For these tests, the glucose values do not react to changes in dosing
These experiments do not a represent a closed-loop outcome. The sole purpose is to measure the dosing difference for the same glucose pattern with different settings enabled.
Unannounced Meal Tests
The glucose pattern shows an unannounced meal.
Unannounced Meal: Effect of Glucose Based Partial Application
The graphics below show the glucose pattern (top chart) and the Insulin On Board (IOB) (lower chart). When GBPA is enabled, the IOB goes up sooner (so insulin will start acting sooner), but once the glucose returns close to the correction range (100 to 120 mg/dL), the IOB is essentially the same with and without GBPA enabled.
Unannounced Meal: Effect of Integral Retrospective Correction
The graphics below show the input glucose pattern (top chart) and the Insulin On Board (IOB) (lower chart). When IRC is enabled, overall the IOB goes up sooner and to a higher value. People who struggle with “stuck on high” or tend to underestimate their meals, should consider enabling IRC. However, see what happens in the Low Scenario: Effect of IRC to understand the associated risks if settings are not appropriate.
- Notice that initially, the IOB curve with IRC-enabled is slightly lower than with IRC-disabled
- This is a consequence of the modification made to IRC found in response to real-time testing
- For details, see PR-2028: Mitigate IRC and Momentum stacking
- The developers believe this improves the safety of IRC and perhaps Loop overall
Unannounced Meal Tests: All Settings
This graphic overlays all 4 setting pairs shown in the prior two plots.
Remember that these experiments do not a represent a closed-loop outcome. The sole purpose is to measure the dosing difference for the same glucose pattern with different settings enabled.
Very Bad Night Glucose Pattern
The glucose pattern below was an actual “very bad night”.
If either of the algorithm experiments had been turned on, this night could have been even worse.
Please – make sure your settings are “close”. In this case, the Insulin Sensitivity Factor was about 20% too strong (number was too low).
Scenario:
- A Looper, using Loop main, had switched to Automatic Bolus (40% partial fraction) a week or so before this night
- They were “expert” at entering carbs and bolusing for meals, and did not notice that their insulin sensitivity factor (ISF) was too strong (the number was too low)
- They experienced some significant lows overnight and their measured glucose was slow to respond to the low treatments
- Because of their ISF setting, Loop gave more insulin than they actually needed when it detected glucose rising, so they had multiple low glucose events
- No carb entries were entered into Loop overnight
- Their calculated IOB as reported on Nightscout never went negative
Glucose Pattern:
- Only the beginning part of the glucose pattern was used for the dosing experiments
- Initially, the Loop history is the same for the different tests, but over time, the dose differences are not represented in glucose changes (as they would be for a true closed-loop experiment)
- Notice that all the dosing is identical regardless of settings for the initial drop in glucose, it is only when glucose begins to rise that there are differences
- GBPA changes the fraction of recommended dose provided per Loop cycle (it makes no change to the recommanded value)
- IRC changes the recommended value
Very Bad Night Actual
The graphics below show the actual CGM glucose pattern (top chart) and the Loop Insulin On Board (IOB) (lower chart) for this Very Bad Night.
Very Bad Night: Effect of Glucose Based Partial Application
The graphics below show the glucose pattern (top chart) and the Insulin On Board (IOB) (lower chart) for Automatic Bolus with constant 40% partial application and Automatic Bolus with Glucose Based Partial Application enabled (GBPA On).
With GPBA enabled, the insulin dosing is higher when glucose is higher for the same glucose pattern.
Very Bad Night: Effect of Integral Retrospective Correction
The graphics below show the glucose pattern (top chart) and the Insulin On Board (IOB) (lower chart) for Loop using Automatic Bolus with a constant 40% application factor compared to the same glucose pattern when Integral Retrospective Correction (IRC) is enabled. The insulin dosing is greater at higher glucose with IRC enabled.
It is strongly recommended that the Insulin Sensitivity Factor (ISF) as well as other settings be close to correct. (This ISF was about 20% stronger than needed.)
- These curves include the modification made to IRC found in response to real-time testing
- For details, see PR-2028: Mitigate IRC and Momentum stacking
- Without that change, the IOB was even higher with IRC enabled
Very Bad Night: Effect of Experimental Settings
This graphic overlays all 4 setting pairs shown in the prior two plots.
Remember that these experiments do not a represent a closed-loop outcome. The sole purpose is to measure the dosing difference for the same glucose pattern with different settings enabled.
