aidR: CareLink export format
In aidR: Reading and Standardizing Automated Insulin Delivery Data

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(aidR)

Overview

path <- system.file("extdata", "carelink_example.csv", package = "aidR")

A CareLink (Medtronic) export is a single semicolon-delimited .csv (or .xlsx) file. The file is divided into sections separated by marker rows of the form -------;MiniMed 780G MMT-1886;Pump;XXXXXXXXXX;-------. Each section has its own header row and its own set of columns:

writeLines(readLines(path, n = 10))

How aidR detects this format

aidR identifies a CareLink export by the keyword MiniMed in the first line.

Sections and the data types they produce

To inspect the files, we parse the export with clean = FALSE, which returns the full information provided by CareLink:

data <- parse_data(id = "1", paths = path, clean = FALSE)

Because all information is present in one file, most of the parsing work happens up front: the file is split into sections, and the large "Pump" section is then split further into individual event types based on which columns are populated on each row.

The list below describes the different sections and the information we can get from it.

Header block (first rows, before the first -------): patient, pump, and sensor information. aidR reads the pump name (e.g. MiniMed 780G MMT-1886) and sensor name (e.g. Guardian™ 4 Sensor) from here.
Pump section: split by event type into
scheduled basal rates. Note: these are the programmed rates of the active basal pattern, i.e. what the pump would deliver in manual mode. They are not the basal insulin effectively delivered: in automated mode the pump adjusts delivery on its own, and in manual mode suspends and temporary basal rates override the schedule.

r head(data$scheduled_basal_rates)

boluses. Records whether a bolus was normal, square-wave, or dual-wave, along with the delivered volume and, for extended boluses, the duration.

r head(data$bolus)

bolus wizard (BWZ) entries, i.e. the carbohydrates communicated to the bolus calculator together with the resulting recommendation.

r head(data$bwz)

self-monitored blood glucose (SMBG) entries.

r head(data$SMBG)

alerts and alarms raised by the pump.

r head(data$alerts)

prime events (tubing/cannula fills).

r head(data$prime)

temp basal events.

r head(data$temp_basal)

correction-bolus information (not present in this example).

r head(data$corr_bolus_info)

sensor calibrations.

r head(data$sensor_calibration)

insulin action curve changes.

r head(data$insulin_action_curve)

device change events.

r head(data$device_changes)

Aggregated Auto Insulin Data section: daily aggregated insulin delivered in automated mode. Interestingly, this number does not match any of the total aggregates from the PDF export, so it is unclear what this actually refers to.

head(data$aggr_auto_insulin)

Sensor section: CGM data.

head(data$cgm)

Cleaning files

When parse_data is run with clean = TRUE, the cleaned data types are built from the following raw files and attributes:

| Cleaned data type | Used files | Used attributes of clean = FALSE | |-------------------|------------------------|-----------------| | cgm | carelink_example.csv | data$cgm | | bolus | carelink_example.csv | data$bolus | | carbs | carelink_example.csv | data$bwz | | SMBG | carelink_example.csv | data$SMBG | | total_bolus | carelink_example.csv | data$bolus |

Note that a CareLink export contains no usable basal data - cgm, bolus, carbs, and SMBG are the core data types available from this platform (see the notes below).

Notes

CGM and SMBG values are reported in mg/dL or mmol/L depending on account settings; aidR converts to mg/dL automatically.
timezone_offset is always NA, since CareLink exports report only local (wall-clock) time.
CareLink does report a daily insulin aggregate, but this number does not match any of the daily aggregates displayed in a PDF export. It is unclear what this number refers to, and aidR therefore does not use this number. Therefore, total_bolus is summed from the cleaned bolus data and carries source = "summed".
The basal rates from the Pump section are the scheduled basal rates (possibly interrupted by reservoir changes and rewinds), and not the basal insulin effectively delivered. aidR therefore does not use them to build a cleaned basal data type, and consequently reports no total_basal for CareLink. If you need the schedule itself, it is available from parse_data(clean = FALSE) as data$scheduled_basal_rates.
link_id is always NA for bolus and carbs: the export does not record which carbohydrate entry triggered which bolus. Matching them by timestamp and amount is not implemented.