Glucose Predictions

Since version 3.5.0 Spike can predict glucose trends for up to 4h. In order to achieve this, part of the OpenAPS (oref0) algorithm has been ported into Spike. The algorithm has been heavily modified and it is used for predictions as well as IOB/COB calculations.

Predictions are available to masters, followers and Loop/OpenAPS users ("Loop/OpenAPS User" option enabled in Settings > Treatments).

Although part of the oref0 algorithm is now available in Spike, Loop/OpenAPS users still need to have the "Loop/UserAPS User" setting enabled. This will make Spike fetch IOB/COB and predictions directly from Nightscout and is needed because Spike does not account for basals (yet). So, if you're a Loop/OpenAPS user make sure you turn on the Loop/OpenAPS setting in Settings > Treatments to make sure Spike stays in sync with your APS (using Nightscout as a proxy).

Important Note

It's important to have in mind that if Spike tells you that your predicted BG in 2h is 100mg/dL it does NOT mean that in 2h time your BG is going to be 100mg/dL... it means that IF current conditions are maintained (how much your BG is currently going up/down, how much IOB/COB you have, etc), then your BG SHOULD be 100mg/dL in 2h time (as long as DIA, ISF, I:C, etc. are correctly inserted in Spike). Note the IF, it's subtle BUT VERY IMPORTANT. Predictions are ever changing, that's why every time you get a new reading from the transmitter or insert a new treatment, Spike recalculates them.

Configuration

Before using predictions, some settings can/should be configured.

Note: It's imperative that you configure your ISF (Insulin Sensitivity Factor) and I:C (Insulin to Carbohydrate Ratio) in Spike's settings. Both are used in all calculations needed to determine future glucose trends. If no ISF or I:C is found, Spike will default to an ISF of 50mg/dL and an I:C of 1U:10g which may result in inaccurate predictions. To configure your ISF and I:C please head over to Settings > Treatments > Profile and scroll down to the bottom of the screen.

Predictions are disabled by default when you first install/upgrade Spike. Once ISF and I:C have been set up, predictions can be enabled by pressing the predictions pill at the upper right corner of the glucose chart screen and pressing the enable switch (enabled = blue, disabled = grey).

Once predictions have been turned on the user will be presented with a few more settings and additional information. We will be focusing only on the settings now and will address the rest later on.

• Enabled: As stated above, this switch is used to enable or disable predictions all together. This setting is available for masters, followers and Loop/OpenAPS users.
• Duration: How far into the future should Spike predict your glucose values. Spike can predict up to 4h into the future but not for all chart views. When viewing the chart in 1h mode, predictions are available for up to 30min, 3h mode can predict up to 1h30min, 6h mode can predict up to 3h and both the 12/24h modes can predict up to 4h. Durations for each chart mode are saved separately inside Spike's internal database which means you can set durations independently for each chart mode and they will persist on app/system restarts. This setting is available for masters, followers and Loop/OpenAPS users.
• Include IOB/COB: This setting will tell Spike if current IOB/COB should be taken into account when performing the required calculations that will determine future glucose trends. Accounting for IOB/COB will make predictions MUCH more powerful. If this setting is off, Spike will calculate predictions only taking into account the current glucose trend and momentum. This setting is available only for masters and followers, NOT Loop/OpenAPS users.
• Single Prediction Curve: Spike can show up to 4 prediction curves simultaneously (IOB, COB, UAG & ZT... we will address them later on). When this setting is enabled Spike will only display the default curve, ignoring the other ones (Spike automatically tries to determine which of the curves is the most relevant/accurate one at any specific moment in time and will mark it as the default one). This setting should only be enabled for newbie users. More advanced users are advised to leave this setting off and have all prediction curves displayed in Spike's chart to have a better understanding of all possible future glucose scenarios. This setting is available for masters, followers and OpenAPS users. It's NOT available to Loop users because Loop only uses one prediction curve making this setting irrelevant.
• Refresh Predictions: This feature is only available for Loop/OpenAPS users. This is because, for these specific users, Spike will fetch predictions directly from Nightscout instead of calculating them in-app. This ensures predictions displayed in Spike are the same as the ones displayed in the user's APS. Because Spike is fetching predictions directly from Nightscout, sometimes they can be a few minutes out of sync. If the user wants to force a refresh instead of waiting for Spike to do the fetch automatically he/she can press the "Refresh Predictions" button which will make Spike immediately connect to Nightscout and fetch the latest available prediction data. This feature will only be visible to users that have the "Loop/OpenAPS User" setting enabled in Settings > Treatments.

Understanding Predictions

As stated earlier, Spike can display up to 4 prediction curves simultaneously. A curve is only visible on screen if it adds relevance to the entire context. For instance, the COB curve will only display if there's active COB at that moment in time.

Lets go through each one of those curves:

• IOB (Insulin On Board): This is a predicted BG curve that is based on insulin only. If no insulin (IOB) is present, this predicted BG curve will only take into account the current BG trend and things like "BG momentum". When insulin is present, this predicted BG curve represents how BG SHOULD behave based on insulin activity alone. The keyword here is "SHOULD" because Spike is relying on mathematical models to predict the future. Because the human body is ever changing, Spike recalculates predictions every time it receives new data (a reading from the transmitter, a treatment input from the user, etc.) which means predictions are also be ever changing.
• COB (Carbs On Board): Uses carbs and insulin (if available) together in predicting the BG curve.\n\nThis prediction line will show an S-curve shape immediately after entering carbs that starts out flat (in line with current BG trends) and then rises sharply after about an hour before flattening out. A typical meal absorption time of about 3 hours is assumed which is then adjusted over time as Spike gradually relies more on actual observed carb absorption data (carb absorption is determined by looking at how BG trend is behaving over time). The COB predictive curve can only go so far in its prediction of BGs because it is limited to the carbs entered, unlike the UAG curve.\n\nCOB predicts how BG SHOULD behave in the presence of carbs and/or insulin.
• UAG (UnAnnounced Glucose): Uses "floating carbs" and insulin (if available) together in predicting the BG curve. Unlike the COB predictive BG curve, UAG is not restricted to the carb entry provided by the user. In a way, it doesn’t "trust" carb entries as much. It fact-checks carb entries by looking (retrospectively) at glucose deviation comparisons. UAG is predicting the future BGs based on the slope (rate of change) of actual BGs during periods where Spike believes unannounced glucose is present, either by having meals that are not logged into Spike, by under counting carbs in a meal or by sudden glucose spikes released by the liver into the blood stream caused by stress, the dawn phenomenon, etc. If BGs are rising during a meal or glucose spike and they continue to rise beyond what was predicted on carbs alone (strong deviations happening), UAG is going to carry that prediction forward... regardless of the carbs entered. And it will carry that forward until the slope stops and things settle down. While COB and IOB predictive BG curves show how BG SHOULD behave based on current trend and IOB/COB alone, the UAG predictive BG curve show how BG IS ACTUALLY behaving based on current trend, IOB/COB and expected/unexpected glucose deviations. The UAG curve is the same as the UAM curve in OpenAPS, it was renamed in Spike for simplicity.
• ZT (Zero Temp): Prediction BG curve representing a scenario where a zero temp is given (zero basal insulin). ZT predicts how BG SHOULD behave in the absence of basal insulin. Because Spike is not (yet) compatible with logging basal treatments, the ZT prediction curve is only available to OpenAPS users and it is fetched directly from the user's Nightscout site.

Spike will constantly analyze all available prediction curves and will mark the default one (the one it considers the most relevant/precise at any moment in time) with a purple color. The default prediction curve is the one used to determine the final predicted BG value that appears on the prediction pill, fullscreen view, Today Widget, Apple Watch complication and app. The default curve is also the one displayed when activating the "Single Prediction Curve" setting described above.

On the chart screen's header, when the "Single Prediction Curve" setting is disabled and Spike is displaying multiple prediction curves simultaneously, a small legend will be visible and will indicate which curves are being displayed on the chart as well as their respective name and color. Pressing a prediction curve name will show a popup to the user explaining what the curve represents.

Additional Information

When pressing the predictions pill located in the upper right corner of the chart screen, the user is presented with additional sub-pills with various kinds of information aimed at giving the user a better understanding of what is currently going on with its glucose values and trends as well prediction curves. Pressing each sub-pill will show a popup with a brief explanation of what it means. Pressing the pill or popup again will dismiss it.

• Last Update From NS: How long ago did Spike fetch prediction's data from Nightscout. Available to Loop/OpenAPS users only.
• Time Until High: Approximate time, in minutes, until BG reaches the user's high threshold defined in Settings > General. This pill is only visible if Spike predicts BG values will fall over the high threshold during the duration of predictions selected by the user. Available to masters, followers and Loop/OpenAPS users.
• Time Until Low: Approximate time, in minutes, until BG reaches the user's low threshold defined in Settings > General. This pill is only visible if Spike predicts BG values will fall under the low threshold during the duration of predictions selected by the user. Available to masters, followers and Loop/OpenAPS users.
• Treatments Outcome: Final BG outcome of all active insulin/carbs treatments. This is the same outcome given by the Bolus Calculator. Available to masters, followers and Loop/OpenAPS users.
• Treatments Effect: The effect that all active insulin/carbs treatments will have on the user's BG (outcome - latest BG reading).
• BG Velocity Per Minute: How much BG is rising/falling each minute. This info is also synced to the dedicated Spike Apple Watch app. Available to masters, followers and Loop/OpenAPS users.
• Predicted Minimum BG: Lowest predicted value that Spike has made for the user's future BG. Available to masters, followers and OpenAPS users. NOT available to Loop users.
• Predicted UAG BG: Predicted BG taking only into account the UAG (UnAnnounced Glucose) curve and prediction's duration selected by the user. Available to masters, followers and OpenAPS users. NOT available to Loop users.
• Predicted COB BG: Predicted BG taking only into account the COB (Carbs On Board) curve and prediction's duration selected by the user. Available to masters, followers and OpenAPS users. NOT available to Loop users.
• Predicted IOB BG: Predicted BG taking only into account the IOB (Insulin On Board) curve and prediction's duration selected by the user. Available to masters, followers and OpenAPS users. NOT available to Loop users.
• Eventual BG: Predicted BG after DIA (hours) considering the user's current IOB and COB. Available to masters, followers and OpenAPS users. NOT available to Loop users.
• BG Impact: Current impact of active insulin and currently digesting carbohydrates. It shows what the BG “should” be doing, assuming insulin and carbohydrate activity are the only major contributing factors. For example, if BG delta is +2 mg/dL and BGI is +2.6 mg/dL, the user's BG is currently doing what is expect based on current insulin and carb activity (both delta and BG impact are similar). If, on the other hand, the actual BG change (delta) and the predicted BGI are very different, the user's BGs are not behaving as predicted, so the purple prediction line may not end up reflecting reality. This can happen due to incorrect ISF/I:C settings, unlogged or incorrectly logged insulin/carbs or external factors like stress, etc.
• Deviation: How much actual BG change is deviating from BG Impact. A high positive/negative deviation number means your BGs are not behaving as predicted, so the purple prediction line may not end up reflecting reality.

Colors

As stated above, Spike supports up to 4 prediction curves.

• Default: When multiple prediction curves are enabled, Spike will always try to determine the most accurate/relevant prediction curve and will use a purple color on it. When using the "Single Prediction Curve" option described above, that curve will also have a purple color. This color can be changed by going to Settings > Chart > Colors > BG Default Predictions. As a rule of thumb, he purple curve is the one Spike believes will reflect your future glucose values.
• IOB (Insulin On Board): Spike will always use the same color as the insulin markers on the chart (the markers that appear when the user adds a bolus treatment). The default color is blue and can be changed by going to Settings > Treatments > Insulin Marker Color.
• COB (Carbs On Board): Same as above, Spike will always use the same color as the carbs markers (the markers that appear when the user inserts a carb treatment). The default color is orange and can be changed by going to Settings > Treatments > Carbs Marker Color.
• UAG (UnAnnounced Glucose): The default color is grey and can be changed by going to Settings > Chart > Colors > BG UAG Predictions.
• ZT (Zero Temp): The default color is baby blue and can be changed by going to Settings > Chart > Colors > BG ZT Predictions. This setting is only available to OpenAPS users that have the "Loop/OpenAPS User" option enabled in Settings > Treatments.

Integration

Although Spike is capable of showing multiple prediction curves simultaneously (IOB, COB, UAG & ZT), it will constantly perform calculations to determine the most relevant prediction curve at that point in time and will apply a purple color to it. Calculations to determine the default prediction line are done every time a new BG reading arrives to Spike and/or a new treatment is added which means the default prediction curve chosen by Spike can change regularly. This default prediction curve is the one used to determine the final predicted blood glucose displayed in the following places:

• Predictions Pill: At the top right corner of the chart screen Spike will display the predicted BG for the desired prediction duration. This prediction value has a purple color.
• Fullscreen View: Along side IOB/COB values, predictions can be found on the lower part of the screen when activation the fullscreen view.
• Today Widget: The same predicted value seen on the chart's prediction pill is also synced to the Today Widget for a quick glance without the user having to unlock his/her device. Whatever prediction duration in selected in Spike settings is the one that will be synced to the Today Widget.
• Apple Watch Calendar Complication: Spike can also sync the predicted BG value to the Apple Watch Calendar Complication. This feature can be enabled by going to Settings > Watch. Due to space constrains, besides the current BG value, trend and arrow it will only be possible to also display IOB/COB, predictions or display name along side, not all at the same time.
• Dedicated Spike Apple Watch App: Predictions are also synced to the dedicated Spike Apple Watch app and are visible on the upper right corner of the user interface. Predictions (and the rest of the data) can be refreshed by force touching the watch screen and selecting the "Refresh" button.

Nightscout Sync

Prediction data (curves and variables) can be uploaded to Nightscout and visualized directly in Nightscout's glucose chart using the Nightscout OpenAPS plugin. This feature is only available to masters. Followers and Loop/OpenAPS users are not allowed to upload any pedictive data.

To use this feature we'll need to enable the OpenAPS plugin in your Nightscout site. Please perform the following steps (we'll use Heroku to exemplify):

Login to your Heroku dashboard using this link https://dashboard.heroku.com and afterwards click on your Nightscout's site name.

Press the "Settings" menu.

Press the "Reveal Config Vars" button.

Scroll down until you see the ENABLE field and press the pencil icon next to it.

Add a SPACE at the end of the field and write the word "openaps" (without quotes). Save your changes.

Scroll the page all the way up, click the upper right menu named "More" and click "Restart all dynos".

Open Spike on your iOS device, go to Settings > Share > Nightscout, enable the "Upload BG Predictions" option and save your settings.

Now, using your browser, visit your Nightscout site (if it was open previously make sure to refresh it), and activate the openaps plugin by clicking the right upper menu.

Now that the plugin has been activated, lets enable the prediction curves by pressing the "..." button at the upper right corner of the screen.

Afterwards you'll be able to visualize your glucose prediction curves on the Nightscout chart.

And you'll also have access to a new OpenAPS pill on the upper left side of the screen.

A side effect of uploading glucose predictions to Nightscout is that Spike will also upload IOB and COB values. Even if the user uses the oref0 IOB/COB algorithm (Settings > Treatments > Profile), IOB/COB values in Nightscout will stay in sync with Spike. Nightscout will stop doing IOB/COB calculations and instead will rely solely on values uploaded by Spike master.

Acknowledgements

Special thanks to my friends from the OpenAPS project (Dana Lewis & Scott Leibrand) for the original oref0 algorithm code and for their guidance. <3