Skip to content
Documentation
/
Diabetes Device Data Mode...
/
/
Bolus Calculator Records...
Last updated

Bolus Calculator Records (wizard)

Quick Summary

annotationsArray of Annotation (object) or Blood Glucose Out of Range (object)(Annotation Array)[ 0 .. 100 ] itemsunique

An array of annotations.

archivedTimestring(date-time)(Date/Time)read-only
Example: "2017-02-06T02:37:46Z"
archivedDatasetIdstring(Data Set ID)[ 17 .. 37 ] characters^(upid_[0-9a-f]{12}|upid_[0-9a-f]{32}|[0-9a-f...
Example: "ce8cc5f7595575945f91fc6710db6fef"
associationsArray of Association (blob) (object) or Association (datum) (object) or Association (image) (object) or Association (url) (object)(Association Array)

An array of associations for the resource.

clockDriftOffsetinteger(int64)(Clock Drift Offset)[ -86400000 .. 86400000 ]

Clock drift offset, expressed as milliseconds.

Example: 0
conversionOffsetinteger(int64)(Conversion Offset)

Conversion offset, expressed as milliseconds.

Example: 0
createdTimestring(date-time)(Date/Time)
Example: "2017-02-06T02:37:46Z"
createdUserIdstring(Tidepool User ID)^([0-9a-f]{10}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-...read-only

String representation of a Tidepool User ID. Old style IDs are 10-digit strings consisting of only hexadeximcal digits. New style IDs are 36-digit UUID v4

deduplicatorobject(Deduplicator Descriptor)
deletedTimestring(date-time)(Date/Time)
Example: "2017-02-06T02:37:46Z"
deletedUserIdstring(Tidepool User ID)^([0-9a-f]{10}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-...read-only

String representation of a Tidepool User ID. Old style IDs are 10-digit strings consisting of only hexadeximcal digits. New style IDs are 36-digit UUID v4

deviceIdstring(Device ID)non-empty

Globally unique to device and repeatable with each upload, e.g. device make and model with serial number

Example: "MMT-1711:12345678"
deviceTimestring(Date/Time without Timezone)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$
Example: "2017-02-06T02:37:46"
historyArray of objects(Event History [Proposed])

Revision history of the event

idstring(Data Set ID)[ 17 .. 37 ] characters^(upid_[0-9a-f]{12}|upid_[0-9a-f]{32}|[0-9a-f...required
Example: "ce8cc5f7595575945f91fc6710db6fef"
locationobject(Location)

Location information associated with the resource. One or both of name and gps must be specified.

modifiedTimestring(date-time)(Date/Time)
Example: "2017-02-06T02:37:46Z"
modifiedUserIdstring(Tidepool User ID)^([0-9a-f]{10}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-...read-only

String representation of a Tidepool User ID. Old style IDs are 10-digit strings consisting of only hexadeximcal digits. New style IDs are 36-digit UUID v4

notesArray of strings(Note Array)[ 1 .. 100 ] items

An array of 1 to 100 notes.

originobject(Origin)

External origin information for the source of the resource.

payloadobject(Payload)

Grab bag field for data that isn't yet part of the data model. The maximum size is 4K bytes.

sourcestring
Value"carelink"
tagsArray of strings(Tag Array)

An array of tags.

timestring(date-time)(Date/Time)required
Example: "2017-02-06T02:37:46Z"
timezonestring(Time Zone)
Example: "Europe/London"
timezoneOffsetinteger(int32)(Time Zone offset)[ -10080 .. 10080 ]

Time zone offset, expressed as positive or negative number of minutes from UTC.

Example: -420
typestring(Tidepool Data Type)required

Data type

Enum"wizard""alert""basal""bloodKetone""bolus""cbg""cgmSettings""controllerSettings""controllerStatus""deviceEvent"
Example: "upload"
uploadIdstring(Upload ID)[ 17 .. 32 ] characters^([0-9a-f]{32}|upid_[0-9a-f]{12})$

An upload identifier; this field should be the uploadId of the corresponding upload record

Example: "0d92d5c1c22117a18f3620b9e24d3c06"
bgInputBlood Value (mg/dL) (integer) or Blood Value (mmol/L) (number)(Blood Value (in mg/dL or mmol/L units))
One of:

An integer value representing a mg/dL value.

[ 0 .. 1000 ]
integer(int32)(Blood Value (mg/dL))[ 0 .. 1000 ]

An integer value representing a mg/dL value.

bgTargetBlood Glucose Target Value (mg/dL) (object) or Blood Glucose Target Value (mmol/L) (object)(Blood Glucose Target)
One of:

Blood glucose target values, in mg/dL

bolusany

The bolus event resulting from this wizard event.

carbInputinteger(int32)[ 0 .. 1000 ]

An integer encoding the PWD's carbohydrate input into the bolus calculator.

insulinCarbRationumber(double)[ 0 .. 250 ]

An integer encoding the grams of carbohydrate "covered" by one unit of insulin for the PWD.

insulinOnBoardnumber(float)[ 0 .. 250 ]

A floating point value representing units of insulin.

insulinSensitivityBlood Value (mg/dL) (integer) or Blood Value (mmol/L) (number)(Blood Value (in mg/dL or mmol/L units))
One of:

An integer value representing a mg/dL value.

[ 0 .. 1000 ]
integer(int32)(Blood Value (mg/dL))[ 0 .. 1000 ]

An integer value representing a mg/dL value.

recommendedobject(Insulin Recommended)

An object encoding the amount of insulin calculated as a recommended dose to "cover" the bgInput and carbInput, possibly taking into account the insulinOnBoard.

unitsstring
carbUnitsstring(Carbohydrate Units)
Enum"grams""exchanges"
Example: "grams"
guidstringDeprecated

A string ID. Added to each event during data processing in the Tidepool Uploader or upon ingestion by the platform data ingestion service.

Type (type)

For historical reasons, this type is currently called "wizard." However, Tidepool plans to migrate to the term "bolus calculator" in a future version as wizard is a Medtronic term.

The Tidepool bolus calculator event models user interactions with a bolus calculator. The bolus calculator event is intended to contain the values that were input into the wizard, as well as any recommendations that the calculator may have made. (This event does not automatically record whether the recommendations made were followed.)

Some insulin pumps record every user interaction with the bolus calculator, regardless of whether a bolus resulted from the interaction or not. However, only user interactions with the bolus calculator that result in a bolus event should be uploaded to Platform, to avoid noise in the data. The resulting bolus should also be included on the bolus calculator event — see linking events for details.

Blood Glucose Input (bgInput)

Like all blood glucose-related fields, the BG input should be uploaded in either mg/dL or mmol/L, as appropriate to how the data is retrieved from the device. However, all values will be converted to mmol/L on ingestion.

Bolus (bolus)

Only bolus calculator events that result in a bolus should be uploaded to Platform. When uploading through Platform, the bolus should only be submitted embedded within the appropriate bolus calculator event.

See linking events for more details on how events of different types are linked in Platform.

Carb Input (carbInput)

Not every use of a pump's bolus calculator involves the input of carbohydrates; a user may be using the calculator to program a correction bolus. Therefore, the carb input field is optional and should only be used when relevant.

Some devices have a separate field to enter a carbohydrate value on their bolus calculators. On such devices, Tidepool omits the carb input field altogether if a value was not entered. On other devices where the carbohydrate option is always part of the calculator, Tidepool reflects this as a carb input of 0.

Carb input does not necessarily map directly to carbohydrates consumed. A person with diabetes may consume carbohydrates that are not recorded through the bolus calculator: either if the user chooses to program a manual or quick bolus to "cover" carbohydrates ingested; or if the PwD consumes carbohydrates unnecessary to bolus for (e.g. carbohydrates consumed to treat hypoglycemia).

Insulin-To-Carb Ratio (insulinCarbRatio)

The insulin-to-carb (I:C) ratio is part of an insulin pump's settings. A user may program one I:C ratio to be used across-the-board, or particular ratios on a schedule per each 24-hour day. For more information on these persistent I:C ratios, see carb ratios.

Most pumps make it possible to change the I:C for the bolus currently being calculated, without also changing the pump settings. Therefore, the insulin-to-carb ratio value on a bolus calculation may not always match the expected ratio given the user's insulin pump settings at the time of the calculation.

Insulin On Board (insulinOnBoard)

The insulin on board (IOB) field encodes the pump's estimate of how much insulin is metabolically active in the person with diabetes' system from previous boluses. Some pumps use a simple linear function for estimating the metabolic uptake and consumption of insulin, while others use more complex functions. A key benefit of using an insulin pump is the ability to track IOB in order to avoid "stacking" boluses (taking more insulin on top of a dose that is still active, possibly resulting in hypoglycemia). It is important to include insulin on board in the data to audit bolusing behavior.

On many pumps, insulin on board is also taken into account for the calculation of the net bolus recommendation.

Recommended (recommended)

The embedded object recommended encodes an insulin delivery device's recommendations for insulin dosing across three fields:

Recommended: carb (recommended.carb)

Carb encodes the units of insulin recommended by the device to "cover" the total grams of carbohydrate input by the user into the bolus calculator. The value for carb may be > = 0, as not all boluses involve the ingestion of carbohydrates and may not include a recommended insulin dose to cover carbohydrates about to be ingested.

Recommended: correction (recommended.correction)

Correction encodes the units of insulin recommended by the device to bring the person with diabetes to their target BG given the input blood glucose. On some pumps, or depending on user preference, this value may be negative. A negative recommendation for correction indicates that — given the user's current blood glucose and insulin on board — low blood glucose is predicted and a reduction in insulin dosing (e.g. via a temporary basal rate) may be required in order to bring blood glucose to or within the target.

Recommended: net (recommended.net)

Net is the net number of units of insulin the bolus calculator recommended given the user's inputs. Generally, this net recommendation takes recommended carb, recommended correction, and insulin on board into account, but insulin delivery devices perform this calculation differently. Therefore, Tidepool has chosen to store the calculation's result, rather than make this calculation the responsibility of client applications.

Examples

Example (client)
{
    "type": "wizard",
    "bgInput": 2.109284236597303,
    "bgTarget": {
        "target": 5.82828539059781,
        "range": 1.3876869977613833
    },
    "bolus": "2eda6697f3ed430bb2d8b7c7a124fb13",
    "carbInput": 17,
    "insulinCarbRatio": 19,
    "insulinOnBoard": 21.949,
    "insulinSensitivity": 1.831746837045026,
    "recommended": {
        "carb": 1,
        "correction": -2.75,
        "net": 0
    },
    "units": "mmol/L",
    "clockDriftOffset": 0,
    "conversionOffset": 0,
    "deviceId": "DevId0987654321",
    "deviceTime": "2018-05-14T18:17:09",
    "guid": "757cdf1d-516d-47a3-87d3-3d4e8b71504f",
    "id": "09eb73043377472f82b2baf7adfdbc50",
    "time": "2018-05-14T08:17:09.353Z",
    "timezoneOffset": 600,
    "uploadId": "SampleUploadId"
}
Example (ingestion)
{
    "type": "wizard",
    "bgInput": 392,
    "bgTarget": {
        "target": 95,
        "range": 15
    },
    "bolus": {
        "type": "bolus",
        "subType": "normal",
        "normal": 8,
        "expectedNormal": 9.6,
        "clockDriftOffset": 0,
        "conversionOffset": 0,
        "deviceId": "DevId0987654321",
        "deviceTime": "2018-05-14T18:17:09",
        "time": "2018-05-14T08:17:09.353Z",
        "timezoneOffset": 600,
        "uploadId": "SampleUploadId"
    },
    "carbInput": 137,
    "insulinCarbRatio": 13,
    "insulinOnBoard": 24.254,
    "insulinSensitivity": 52,
    "recommended": {
        "carb": 10.5,
        "correction": 5.5,
        "net": 0
    },
    "units": "mg/dL",
    "clockDriftOffset": 0,
    "conversionOffset": 0,
    "deviceId": "DevId0987654321",
    "deviceTime": "2018-05-14T18:17:09",
    "time": "2018-05-14T08:17:09.353Z",
    "timezoneOffset": 600,
    "uploadId": "SampleUploadId"
}
Example (storage)
{
    "type": "wizard",
    "bgInput": 16.152676653942503,
    "bgTarget": {
        "low": 3.6079861941795968,
        "high": 6.938434988806917
    },
    "bolus": "22239d4d592b48ae920b28971cceb48b",
    "carbInput": 57,
    "insulinCarbRatio": 24,
    "insulinOnBoard": 24.265,
    "insulinSensitivity": 4.329583433015516,
    "recommended": {
        "carb": 2.5,
        "correction": 2.25,
        "net": 0
    },
    "units": "mmol/L",
    "_active": true,
    "_groupId": "abcdef",
    "_schemaVersion": 0,
    "_version": 0,
    "clockDriftOffset": 0,
    "conversionOffset": 0,
    "createdTime": "2018-05-14T08:17:14.353Z",
    "deviceId": "DevId0987654321",
    "deviceTime": "2018-05-14T18:17:09",
    "guid": "18d90ea0-5915-4e95-a8b2-cb22819ce696",
    "id": "087c94ccdae84eb5a76b8205a244ec6b",
    "time": "2018-05-14T08:17:09.353Z",
    "timezoneOffset": 600,
    "uploadId": "SampleUploadId"
}

Keep Reading

Previous page
Next page