The Nightscout IOB-COB website

22 Feb
Guides > Labs > The Nightscout IOB-COB website

Note: The IOB-COB branch has been deprecated. While certain features from the branch described below are not in use, the current master and dev branches do support IOB and COB.

Introduction

The Nigthscout IOB-COB website is an optional and experimental website that tracks insulin and carbohydrates on board based on Nightscout Care Portal data and a user-defined therapy profile.  IOB-COB displays a predictive trend estimating future blood sugar levels over the next three hours.  IOB-COB uses a subset of the code developed by Dana M. Lewis and Scott Leibrand for the #DIYPS project.  

Is IOB-COB right for me?

There are a few things to consider before you setup an IOB-COB website.  IOB-COB is the embodiment of #WeAreNotWaiting.  It is a development branch of cgm-remote-monitor code that is less stable than either the dev or master branches.  Developers may update the code multiple times per week without notification, and with only limited testing.  There are no public release announcements for IOB-COB updates.  Sometimes a code update will break things unexpectedly.  If you setup an IOB-COB website, you will want to keep track of the IOB-COB branch on GitHub and update your fork when you’re ready to incorporate the updates.  We caution against using IOB-COB as your primary or only Nightscout website.  As with anything Nightscout-related, the performance relies solely with the user.

IOB-COB Fundamentals

There are a number of terms and concepts that must be understood in order to take full advantage of an IOB-COB website.  You may already be familiar with most if not all of these, based on your existing diabetes care plan.

First, an IOB-COB website requires a profile for the person with diabetes.  The IOB-COB profile as similar to an insulin pump profile.  The IOB-COB profile includes four key metrics that control the predictive trend shown on the website.

  • Duration of insulin action (dia) is the length of time that insulin remains active and available in the body after a bolus.  For fast acting insulin such as Novolog and Humalog, this is commonly 3-5 hours.
  • Sensitivity Factor (sens) or Correction Factor is a value that indicates how much one unit of insulin will lower your blood glucose. For example, if your correction factor is 50, one unit of insulin will lower your blood glucose by 50mg/dL.
  • Insulin to carbohydrate ratio (carbratio) expresses how many grams of carbohydrate are covered by one unit of insulin. For example, if your insulin-to-carbohydrate ratio is 1:15, then you need to deliver one unit of insulin to cover every fifteen grams of carbohydrates you eat.
  • Carbohydrate absorption rate (carbs_hr) is the rate at which carbohydrate is digested by the body and absorbed into the blood stream.  Absorption rate is measured in carbs per hour.  Scott and Dana wrote a great blog post explaining the concept and how to test yourself.

The IOB-COB website uses the previous four metrics to calculate insulin and carbs on board as well as blood glucose impact.

  • Insulin on board is the amount of insulin that is still active in the body from previous insulin boluses.  The length of time that insulin remains “on board” or active depends on each individual’s DIA.  IOB in Nightscout depends on accurate, manual Care Portal data entry and is not derived from any pump data.
  • Carbohydrates on board is the amount of carbohydrate still being digested by the body from previous meals, snacks and carb corrections.   The length of time carbs remain on board is influenced by the amount of carbs eaten and each individual’s carbohydrate absorption rate.  COB in Nightscout depends on accurate, manual Care Portal data entry and is not derived from any pump data.
  • Blood Glucose Impact represents the current impact of your active insulin and currently-digesting carbohydrates, measured in mg/dL per 5 minutes.  BGI shows you what your 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, your BG is currently doing what you’d expect based on current insulin and carb activity.  If, on the other hand, the actual BG change and the predicted BGI are very different, your BGs are not behaving as predicted, so the purple prediction line may not end up reflecting reality. BGI accuracy depends on an accurate IOB-COB profile and accurate basal insulin rates in addition to accurate, manual Care Portal data entry.

Many definitions for this section were paraphrased from the OmniPod Insulin Pump Glossary.

IOB-COB in Nightscout

User Interface

There are some key changes to the IOB-COB website user interface when compared to a standard Nightscout website.

  • Insulin and carbs on board is listed in the top center of the web page.
  • The upper trend line shows five hours of history instead of 2.5 hours and is condensed and shifted left to make room for a longer prediction trend.
  • Instead of a ‘cone of confidence’ that predicts blood glucose levels for 30 minutes in the future, a single purple line predicts blood glucose levels over the next three hours.
  • Raw BG is enabled and displayed when noise is present by default.
  • Blood glucose impact is tracked to the right of blood glucose delta
  • The lower trend line shows four days of history rather than two
    Screen Shot 2015-02-21 at 3.03.35 PM
  • If you turn on ‘Retrospective lookback’ in your website settings panel and set a value in minutes, you will see a blue trend line that represents what the IOB-COB prediction algorithm would have predicted that many minutes before. For example, if you set “retrospective lookback” to 60, you can see if you have been consistently running higher or lower than predicted at certain times of day, after correction boluses, after meals, etc.  This allows you to see where your basals, ratios, etc. may be incorrect and require adjustment, and also allows you to update your profile collection to model whether a particular change to your ratios improves the predictions and brings them closer to reality, or not.
    Screen Shot 2015-02-26 at 12.47.06 AM

IOB-COB Profile

As part of the IOB-COB website setup, you will create a therapy profile for the person with diabetes.  The IOB-COB profile is similar to a pump profile, containing user-specific values for the ratios and other factors described above in the IOB-COB Fundamentals section.  The profile is stored as a document in a new collection in your Mongo database.

Current limitations

There are a number of limitations with IOB-COB that you should be aware of before setting up a website.  This list will change over time as new features and functionality are added.

  • IOB-COB profile does not store basal insulin rates or factor them into predictions
  • IOB-COB profile does not allow for multiple profiles or time-based profile settings.  You have one value for DIA, one value for I:C ratio, one value for Carb absorption rate, and one value for sensitivity factor / correction factor.
  • IOB-COB website prediction trend does not operate correctly when website is using MMOL display.
  • IOB-COB website buttons for audio, settings, and care portal are not directly clickable.  You must click below the icon to click the button.
  • Currently the pebble endpoint will only display IOB using a 3 hour DIA, even if you have your profile set differently. The website will display and IOB estimate using the DIA you set in your profile but it will not match your pump’s calculation. Always defer to your pump’s IOB calculation.
  • Currently the pebble will display IOB to two decimal points (eg 3.43) but the website displays one (eg 3.4).

You can monitor the status and progress of IOB-COB development on GitHub

Setup an IOB-COB website

Prerequisites

Your existing Nightscout setup should meet the following prerequisites before you setup an IOB-COB website.

Setup Outline

You have three major steps to setup an IOB-COB profile, assuming you have met the prerequisites listed above.

  • Add an IOB-COB profile to your Mongo database
  • Update your copy of IOB-COB code on GitHub
  • Deploy a new IOB-COB website to Azure or Heroku
  • Install a “Nightscout” or “CGM in the Cloud” Pebble watchface for your IOB-COB site

IOB-COB Profile Setup

Login to your Mongolab account, then click on the Mongo database you plan to use for IOB-COB.  If you already use Care Portal, you should add the IOB-COB profile to the database that contains your Care Portal treatments collection.

Click + Add Collection

addcollection

Name the new Collection: profile

Profile Collection

Click on the newly created profile collection and then click + Add document

addadoc

Copy and paste the example profile below into the “Create Document” window. Be sure to use your own values for carbratio, carbs_hr, dia (insulin duration) and sens (correction factor).

{
"carbratio": 12,
"carbs_hr": 30,
"dia": 3,
"sens": 54
} 

Screen Shot 2015-02-28 at 11.38.40 AM

Click create and go back.

Screen Shot 2015-03-01 at 12.03.31 AM

Your profile collection should now have 1 document.

Update Github

For your new website, you will deploy the wip/iob-cob branch of cgm-remote-monitor rather than the master branch.  Before you create your website, you must make sure your Github repository contains the most recent code.

First, login to your Github account.

Click on your username in the upper right corner of the webpage and then click cgm-remote-monitor to open your copy of the Nightscout code.  This should take you to your copy of cgm-remote-monitor.

Screen Shot 2015-03-01 at 12.09.00 AM

Click on the branch drop down menu, then type “wip/iob-cob” and press enter.  This will create a new “wip/iob-cob” branch (if necessary) and switch you to that branch.

Screen Shot 2015-02-28 at 11.46.29 AM  Screen Shot 2015-02-28 at 11.48.04 AM

Click on the small green button on the left to create a pull request.  This will update your copy of the wip/iob-cob branch to the latest version.

Screen Shot 2014-11-01 at 11.36.34 PM

You will see a screen that looks like the picture below.

Screen Shot 2015-02-28 at 11.48.27 AM

Click the base fork box and select your fork from the dropdown menu (username/cgm-remote-monitor).  This will change the base fork to your repository.

Screen Shot 2015-02-28 at 12.04.23 PM

Click the button to “compare across forks”

Screen Shot 2015-02-28 at 11.48.43 AM

Click on the head fork button. Select nightscout/cgm-remote-monitor from the drop down menu.

Screen Shot 2015-02-28 at 12.07.10 PM

Click the green “Create pull request” button.

Screen Shot 2015-02-28 at 12.09.38 PM

Enter a title and comment into the appropriate boxes and click green “Create pull request” button on the bottom right.

Screen Shot 2014-11-01 at 11.41.46 PM

Scroll down the page of changes to the code until you see the green “Merge pull request” button. Click on it.

Screen Shot 2014-11-01 at 11.42.00 PM

A “Confirm merge” button will appear. Click on it.

Screen Shot 2014-11-01 at 11.42.05 PM

Scroll back to the top of the page. If you see a purple “Merged” button, you’ve successfully created and updated the code you need to create an IOB-COB site.

Screen Shot 2015-02-28 at 12.11.42 PM

Deploy your IOB-COB website

Now that your code on GitHub is updated to the latest version you will create your IOB-COB website.  You can easily deploy on either Heroku or Azure.

Heroku

To deploy to Heroku, you will follow the instructions in the How to Heroku lab with the following two differences.

  1. Before you deploy to Heroku, you must login to GitHub and go to your personal cgm-remote-monitor repository.  Then, you must switch from the Master branch to the wip/iob-cob branch.  To switch, click where it says “branch: master” and choose “wip/iob-cob” from  the drop down box.Screen Shot 2015-03-01 at 12.44.16 AMAfter switching to the “wip/iob-cob” branch, scroll down the page to the Readme file.  You should see a purple “Deploy to Heroku” button.  Click that, and follow the instructions in the How to Heroku lab.
  2. Using the “Deploy to Heroku” button automatically creates a new Mongo database for each website.  If you plan to use a pre-existing database for IOB-COB, you will need to remove the automatically created Mongo database, then point your Heroku site to your preferred Mongo database.  Use the following steps to do so.Login to the Heroku Dashboard and click the Resources tab.Click Edit to the right of the Add-ons section.Screen Shot 2015-03-01 at 12.57.53 AMThen, click the red circle to delete the Mongo database and click Save.Screen Shot 2015-03-01 at 12.58.23 AM

    Click on the Settings tab, then click “Reveal Config Vars” and then click Edit.

    Screen Shot 2015-03-01 at 12.58.52 AM
    Add a new variable called MONGO_CONNECTION and set the value to the Mongo URI for your preferred database.  Also verify that the value for MONGO_COLLECTION is correct for the database you are using with IOB-COB.

    Screen Shot 2015-03-01 at 12.59.41 AM

Azure

Log into your Azure account (click on PORTAL).

Click on the Website name in the left menu

Click on “+NEW” in the lower left.

azure 2 setup

Click on QUICK CREATE then enter a name for your new website. Click on CREATE WEBSITE.

azure 2 setupb

Click on the web site name, and you will see a welcome page stating ‘Your site has been created!

On the top navigation menus, click on CONFIGURE as shown below:azure-newsitenavbar

Next, scroll down the page until you find the CONNECTION STRINGS (it will be over three quarters of the way down the page. You will see this:azure-connectionstring

On the row that is there, look to the right and click on the down arrow and select CUSTOM.

Name the row mongo (left box).  The Value is your mongo connection uri from the mongolab account (it is written on your worksheet).

FOR EXAMPLE:
mongodb://sallyuser:sallypassword@ds012345.mongolab.com:12345/mycgm

Should look something like the following:

azure-mongo

Create a second row by clicking in one of the boxes in the next row.

Change the type to CUSTOM in the drop down on the far right of the new row.

Name the second row mongo_collection.

For this row’s Value, enter the name of your collection. If you followed the example, the name of your collection might be one word, e.g. MYCGM.

It should look something like this:

azure-mongo_collection

Click on SAVE at the bottom of the page.

azure-config-save

When finished, the section will look like this:

configure connection strings

If you need to ever edit or see the values of your connection strings, click Show Connection Strings

azure-connectionstring-show

and then you will see something like below (with your own information, of course):azure-connectionstring-show2

IF you made any changes to the connection strings, click SAVE at the bottom of the page, or proceed to next step.

You need to enable Care Portal.

ENABLE – value careportal
API_SECRET
 – value must be at least 12 characters long.  You can pick any 12 characters you want (numbers and letters, NO special characters). If this variable is set too short, your Azure site will not work. You will only see a white screen.
(Note: If you choose to use API, this is the password that you’ll set in the uploader API setting.)

Make sure both are changed to CUSTOM.

It will look like this:

Screen Shot 2015-01-12 at 6.28.28 PM

If you want to set custom alarm values do so now.

You can copy & paste the names below the picture into the app settings in Azure.

The glucose numbers must be in mg/dl.  mmol does not work to set these up.  To get mg/dl from mmol, multiply mmol by 18. 

mmol x 18 = mg/dl.

KEY                         Definition
BG_HIGH – This is the number that will trigger the Urgent High Alarm.  This is typically higher than the BG_Target_Top.

BG_LOW – This is the number that will trigger the Urgent Low Alarm.  This is typically lower than the BG_Target_Bottom.

BG_TARGET_TOP – This is the number that triggers the High Alarm, as it approaches Urgent High/ BG_High.  It is typically lower than the BG_High.

BG_TARGET_BOTTOM – This is the number that triggers the Low Alarm, as it approaches Urgent Low/ BG_Low.  It is typically higher than the BG_Low.

ALARM_TYPES – This defines how/when the alarms are sounded. The values to choose are SIMPLE and PREDICT.  These are case sensitive and MUST be entered in lower case.

The default is Predict which is the same as all previous versions of Nightscout.  Once you enter ANY BG values, the alarm type automatically becomes SIMPLE without entering a value.

simple alarms are very similar to how the alarms are sounded on your Dexcom receiver – once the glucose level reaches that number, the alarms will sound. Please note – the value you enter into the configuration must be all lowercase.

predict alarms will alert you in advance of the levels, based on a predictive algorithm.  This is the Default alarm and is the same as all previous versions of Nightscout. Please note – the value you enter into the configuration must be all lowercase.

You can change these after you’ve set them to customize them in any way you choose.

CLICK ON SAVE AT THE BOTTOM OF THE SCREEN.

mmol Users: You can make you site automatically display in mmol in all web browsers (but not the pebble) by following the instructions below.

Add one entry to the app settings:

In the Box for KEY type or paste this: DISPLAY_UNITS

In the Box for VALUE type or paste this: mmol

Screen Shot 2015-01-13 at 4.59.36 PM

CLICK ON SAVE AT THE BOTTOM OF THE SCREEN.

Again, once you have made all the setting changes you want and have enabled Care Portal and raw data, be sure you SAVE.

Now you need to deploy your Github code.

Github to Azure

From Azure Portal, in the top navigation menu, click on the DASHBOARD menu:

azure-dash-menu

On the right ‘Quick Glance‘ menu, click on the ‘Set up deployment from source control‘ link

azure-quickglance

Select Github

azure source code

Authorize Github/Azure access.

Find cgm-remote-monitor:

azure choose repository2

 

The default branch of code to deploy is master as shown above. You already have a site running the master code. In the BRANCH TO DEPLOY text box type wip/iob-cob.

Confirm, watch the site deploy, it should deploy automatically.

azure waiting for deploymentazure active deployment

Verify operation by visiting your site, e.g.

https://YOURWEBSITE.azurewebsites.net.

Pebble Setup

Many people rely on the Pebble as their primary or only view to their Nightscout data.  We recommend that you use a separate watchface for your IOB-COB website, simply because the IOB-COB website code is less stable than the master branch.  You can use a single watchface, however your IOB-COB website then becomes a single point of failure for viewing NIghtscout data on your Pebble watch.

In the Pebble Store, you can find a slot 1 and slot 2 watchface listed under “Nightscout” as well as “CGM in the Cloud”.  You can install up to four watchfaces with alarms from the Pebble store.  Be aware that “CGM in the Cloud” watchfaces labeled SLEEP do not have vibration alarms.

To view IOB on your Pebble watch, you need to do the following:

  • Install a Nightscout or CGM in the Cloud version 7.0 watchface
  • Set the endpoint in the watchface settings to your new IOB-COB website
  • Set the “T1 Name” to IOB
  • You may need to switch from and to the watchface to get the T1 Name field to change to IOB

IOB-COB Usage Examples

Coming soon…