You can install the latest version of CGMprocessing directly from GitHub using the remotes package. First, make sure you have remotes installed:

install.packages("remotes")

Then, you can install CGMprocessing using the following command:

remotes::install_github("alicelouisejane/CGMprocessing")

If you encounter any issues during installation, please open an issue on the GitHub repository page

The goal of CGMprocessing is to provide functions for preparing, cleaning and analyzing Continuous Glucose Monitoring (CGM) data for clinical diabetes studies. Glycemic variables and definitions are inline with the International Consensus on Use of Continuous Glucose Monitoring: Danne 2017 and Battelino 2023. This package also includes a specific function for use in the context of diabetes exercise studies, which splits up CGM into specific time periods post-exercise. Specific outputs are inline with CGM outputs in exercise recommendations in type 1 diabetes: Riddell 2017.

This code was developed based off work by T. Vigers

This README is written as a tutorial for CGM analysis, including in the context of exercise. This an updated and more in depth explanation of the general pipeline that was developed and used in publishing a PhD Thesis and peer reviewed research

See parameters for explanations of the arguments per each function. You will find this in the man file on this GitHub:

• cleanCGM

• exercise_split

• analyseCGM output

• intervention_split output

• /data-raw: raw data from sensor

Automatically created:

• /data-clean: data ran through cleanCGM function or own cleaning pipeline to be inline with the format of a cleanCGM output

• /additional: Folder for output csv of gap information and percentage expected wear information over the study output from cleanCGM

• /graphs: Folder of CGM trace graphs created when saveplot=T in cleanCGM

• /data-….: Folders for the split exercise files generated by exercise_split Jump to exercise_split output to see list of all folders created for each split time period

❗Important: This package is optimized for raw Dexcom or Libre CGM data and can work with pre-aggregated clinical study CGM data. Raw CGM files usually have an ID number within the filename. If this is the case leave the filename as is. If raw files don’t have this then edit the filenames so they are uniquely identified with the a subject ID number. If you are using already pre-aggregated data from another study ie. JAEB you will need to ensure that your identification variable is a combination of the subject ID, visit number and device number to ensure everything is uniquely identified. If you are working with pre-processed data, or other CGM device types ensure you check data structures and edit code as appropriate to fit your needs❗

Functionality: cleanCGM() is a function written to clean CGM data for simpler file outputs for further analysis. Variable names are standardized, high and low limits (sensor type dependent) converted from text to values, gaps identified and imputed with the last known glucose value only if the gap is ≤20minutes. Percentage wear/ sensor drop out information is calculated , including number of gaps and the total time imputed,and output in seperate files. Option for working with pre-aggregated data from clinical studies (**please read **Introduction to CGM analysis). Additional option for calibration if working with older sensor data.

❗ Important: If you don’t want to use this function and want to clean your own data, but want to use exercise_split or analyseCGM, then ensure data is in the the correct format see example at the end of the cleanCGM section: Jump to cleanCGM output❗

• Function can take raw files from Dexcom, Libre or other (pre-aggregated data) from an input folder directory, or specified pre-aggregated file Files can be of any format, csv is preferred. **Important: Raw files should have subject ID/unique identifiers within filename ID_optional.ext **

• If using raw data then devicetype will be combined with participant id from file name and to create the overall id variable in cleanCGM. This will be output as the ID in the cleaned file. NOTE: if using pre-aggrgated CGM data then your ID column within the raw data file needs to already be formatted as participant ID_visit number_device type.

• The output of the cleanCGM() will give the final variable names as: id,date ,timestamp, sensorglucose

• Additional variables are required for cleaning steps but are not included in the final output of the clean file: eventype. This variable is to identifiy if the value was a sensor glucose value, a scan glucose value (libre 1 only) or other event. Cleaning filters for only sensor glucose values.

NOTE on gap filling - Gaps where the sensor has dropped out for 20 min or less are added into the timeseries where the glucose value is carried forward from the last known value. E.g. if working with data of 5 min intervals, a gap of 10 mins would mean adding in 1 row between the two timestamps where the drop out occurred, a gap of 15 min would mean adding 2 rows and 20 mins would mean adding 3 rows, each with the corresponding sequential timestamp and carried forward glucose value.

Table: Definitions of the standardized variables

cgmvariable_dictionary.xlsx included as part of this package is a dictionary used to rename variables of interest with standardization of the names from the raw CGM files (as above) without much user input.

• Optional argument in cleanCGM allows for custom CGM dictionaries to be used if the names of the raw data CGM files are different to what is pre-specified or you are using other sensors. Construct you dictionary exactly as below replacing the old_vars with your raw CGM files variable names of interest that matches with the new_vars. Do not change the new_vars. Edit your type of device and expecteddaysofwear relavent to the lifetime of one of these sensors. for eg. A Dexcom g6/7 sensor lasts 10 days, a Libre sensor lasts 14 days.

Table: Example of dictionary for renaming old variables in raw CGM data files, edit as required. “Type” column in this dictionary is only for user only for reference, sensor type is specified as an argument in the function.Ensure you enter the lifetime of the sensor used. Example is of some variable names I have come across in each of the sensors- Always check you data to see what the variable names are and edit this dictionary. If you have a mixed download of CGM of files, I recommend separating into folders by sensor type to avoid confusion before processing. Additionally please note the use of ID_VISIT_DEVICEID in the type other. This is used to ensure unique identification in clinical study data that has been pre-aggregated. Device id is also kept for use in raw files, however if you purposefully have more than one device (ie a 30 day wear file) then this will not effect outputs of analyseCGM but you must specify this. However, the percentage_data_collected_info.xlsx will be per unique device.

• This is an optional argument which is sensor dependent. Also some JAEB studies have CGM that had calibration requirements. This requires the device argument to be set to “other” or “dexcomg4” if you are know you are using an old type of dexcom.

How it works:

1. SMBG calibrations are matched to the closest CGM sensor value and compares them by absolute relative difference. Multiple calibrations are usually performed per day so the mean absolute relative difference (MARD) per day is generated.

2. A day of data should not be used if the MARD exceeds 20%. These days are excluded. A MARD>20% has be chosen as many things can impact the MARD (ie. sensor glucose can trail behind blood glucose in periods of exercise, or it can just be inherent sensitivity of the CGM device used) and this is probably the upper limit of MARD that we could expect from some old devices more info.

3. Days that don’t have calibrations (and should have done) are also excluded, however many studies that used CGM have the requirement in their protocol and hence if a patient didn’t calibrate or meet the requirement of number of calibrations per day then their data is usually excluded from study.

Newer sensors don’t require calibrations and have internal algorithms that keep the glucose values “calibrated”.

If your sensor requires calibration the easiest way to handle these are to preprocess the data like some example studies in JAEB are formatted ie. Wireless Innovation for Seniors with Diabetes Mellitus (WISDM) demonstrated in the example below. Calibrations work on having the calibration value identified in a record type variable.

👷Please Note Preprocessed data structures may all be different, so this part may not work as expected. Please review code and data structures and edit your code as necessary. 👷

Table: Example head of data structures that have calibration values. All CGM and SMBG calibrations are put into the same column and identified by a eventtype variable.

The function will output:

• Cleaned CGM files of the structure:

• gap_info.csv Which provides information on the gaps in the data. It contains the timestamp and length of gap (diff) per ID:

• percentage_data_collected_info.csv Which provides information about the quality of the CGM data. This file will be per unique device. This is why device id is an important variable to keep. Variables described below:

  1. percentage_expectedwear_overstudy -percentage wear that was expected over the study (usually expected lifetime of the sensor if it is a 10 day wear (dexcom) or 14 day wear (libre), but some studies might only require 3 days of wear, you can specify this in the function arguments). It evaluates the length of time from the maximum to minimum timestamp.

  2. percentage_datacollected_overstudy -percentage of actual data collected. This tells us if there was drop out from the sensor, counting the amount of time that the CGM actually measured.

  3. percentage_dropout_overstudy -percentage of time that was lost to drop out (inverse of the above)

• CGM traces graphed When saveplot=T the graph as below is outputted with some information on the number of days present and number of hours this CGM was worn for (each line is a unique date). Also includes the amount of data the sensor actually collected over wear time, giving you an indication of the amount of sensor drop out. When dealing with combined clinial study data this graph will output for each individual in the study as well as for the overall cohort.

Functionality: exercise_split() is a function written to split up a CGM file (cleaned by cleanCGM or another way) into relevant time periods post exercise. Exercise splitting is based on an exercisefile- a list of exercise timestamps for every person in study Jump to exercisefile - List of exercise time stamps for the structure of this. Function takes files in the same structure as outputted from cleanCGM output. These split files can then be individually ran through analyseCGM or taken for further analysis. This does not yet work with pre-aggregated data, this works with individual files as unique individuals per study time

In the diabetes exercise literature it is usual to assess:

• 6 hours post exercise (In this function you can alter the 6 hours to be any number of hours)

• Overnight post exercise (00:00-06:00)

• 24 hours post exercise

• The time from exercise end up until 00:00

• The next day post exercise (06:00-24:00 ie. midnight of that next day)

• File required for exercise splitting, listing the start and end time of each exercise. Type column can be changed to whatever type of exercise/event/instance etc. it is.

It should be structured as below:

• Folders holding each time period split are created automatically in your outputdirectory as below:

• The files in this folder are named automatically corresponding to the time period they are in eg. files in data-after_24 are named as: ID_exercisetype_24.csv, for data-after_0000_0600 are named as: ID_exercisetype_00_06.csv etc.

❗ Important: File naming structure is required for the analyseCGM function. Creating a unique file for each individual for each time period allows us to get a global table of CGM metrics for each of these time periods which is easier to then taken on for further analysis.❗

• For ease the folder data-all are all the files in one folder. You can then point ot this one folder when you run analyseCGM.

These files are structured slightly differently to the cleanCGM output with the addition of the variables:

• type: relating to the type of exercise/event/instance of exercise etc which is specified in the exercisefile

• start_split: Sensor glucose timestamp where the split began ie. the closest within the CGM interval that matched the start of exercise

• startdatetime: Exercise start timestamp from exercise file

• finishdatetime: Exercise end timestamp from exercise file

• diff: The raw time difference between the sesnsor glucose timestamp exercise end timestamp. If negative this is during exercise.

• diff_disc: The discrete time interval created from the diff variable. During exercise is set to 0 and follows consecutively ie. time within the first hour after exercise is set to 1, second hour is 2 etc.

❗ Important: analyseCGM when exercise=T relies on the diff_disc variable to create the time in range during exercise and post exercise metrics.❗

Also output are:

• exercisecharacterisitcs.xlsx which is a summary of just the exact sensor glucose at the start and end time of exercise

• all_CGM.csv which is all data from everyone with respect to exercise as below:

___

Functionality: intervention_split() a more generic version of exercise_split, it is a function written to split up a CGM file (cleaned by cleanCGM or another way) into before or after identified time(s) of intervention. Intervention splitting is based on an interventionfile- a list of dates of an intervention for every person in study Jump to interventionfile - List of intervention dates for the structure of this. Function takes files in the same structure as outputted from cleanCGM output. The resulting split files can then be individually ran through analyseCGM or taken for further analysis. This function works for pre-aggregated data if specificed in the funcitons parameters.

• File required for intervention splitting, listing the date of each intervention and specifying the type of intervention. Intervention column assigns the labels in the resulting files so ensure it is something you can understand. All patients can be in this one file. Enter dates in chosen standardized date format.

It should be structured as below:

• Folders of data-before_intervention and data-after_intervention

• If data was not pre aggregated, files will be of each individual ID with the intervention type specified in the filenames. This is also repeated in the id column within the file. This will allow analyseCGM() to create metrics for the specific times before or after intervention for each ID. (if data was preaggregated it will be the same but all within one file of before intervention and after intervention).

Functionality: analyseCGM() is a function written to create consensus glycemic metrics based off definitions outlined International Consensus on Use of Continuous Glucose Monitoring:Danne 2017 Battelino 2023. For definitions Jump to analyseCGM output. Function takes files in the same structure as outputted from cleanCGM or exercise_split.

• For calculation of time spent variables data is checked to be consecutive. If timestamps are >20 min apart a missing row is added to the table to prevent events from running on if the time gap is >20 min. Gaps in the data are identified by cleanCGM (if used) and a summary file is outputted- Jump to cleanCGM output.

• General time spent variables are created for:

  • Above 10, 13.9, 16
  • Below 3
  • Range 3-<3.9, 3.9-10

• In addition to this hypo/hyperglycemia also have defined “excursions”:

  • Hyperglycemia (at levels >10 and >13.9 and 16)
  • Hypoglycemia (clinical excursion event beginning when <3 for 15min and ending when ≥3.9 for 15min)

The start of an excursion is when glucose goes above/below the specified value for 15 mins. If this doesn’t happen it is not defined as an excursion and isn’t included in the excursion time spent variables. The general time spent variables will include any time above/below the level regardless of if this is >15min.

🖋️ NOTE it is my recommendation that the general time spent variables are sufficient and the defined excursions or “clinical excursion” hypoglcemia are too stringent. You may miss important information if you just assess events that had to last >15min. This is particularly relevant if you use the Libre 1, 2 or Libre pro as this CGM measures glucose every 15min. Using general time above/below as your measures of hypo/hyperglycemia would give you a good indication of the lived experience of a patient and this, in my opinion, is most important. Excursion metrics are still required by the International Consensus on Use of Continuous Glucose Monitoring and hence why this function still generates them 🖋

Beginning of a CGM event: readings below 3 mmol/l for 15 min defines a clinically significant hypoglycemic event. Code checks if 4 consecutive rows are below 3 (4 rows in total: row 1 detected below 3mmol/l the next 3 rows = a time of 15 mins as 1 row is assumed as a 5 min reading). If this is the case then the first instance of dropping below 3 is marked as the start row of the clinical hypoglycemia CGM event.

End of a CGM event: readings for 15 min at ≥ 3.9 mmol/l. From the start row of the true hypoglycemic event defined above the code checks if the glucose in consecutive rows is ≥ 3.9 mmol/l and marks these values as hypoglycemia. At the row glucose becomes ≥ 3.9 the code checks if the next 3 rows remain ≥ 3.9 mmol/l (4 rows in total: row 1 detected ≥ 3.9 mmol/l the next 3 rows = a time of 15 mins as 1 row is assumed as a 5 min reading). If glucose dips below 3.9 again within these 4 rows then the event does not end. If the glucose stays ≥ 3.9 for these 4 rows the event ends at the first instance of ≥3.9.

If a missing row is present (inserted because the consecutive timestamps had a gap >20 min) the hypoglycemic event has to end at this point). 🖋️

• If the data you have are from a Libre below generation 3 (or any sensor that has 15min sampled data) then ensure your argument libre is set to TRUE in the analyseCGM() function.

• The analyseCGM function has a section that pseudo codes this kind of data to be “5min” data ie. Every row is repeated 2 more times (3 lots of 5 mins are in 15 mins). It doesn’t matter that the timestamps aren’t increasing by 5 min but having the number of rows corresponding to 5 min data is the important part, mainly for the clinical hypo excursion definition. Gaps in the data will still be identified as normal, as the repeated rows are only for the rows that were present in the data. Code section as below:

  table <- slice(table, rep(1:n(), each = 3))

• Additionally this ensures the true interval is tracked and inputted correctly in the output file

1. A .csv file called by default CGMupload containing CGM variables per each individual on each row

All CGM variables generated by analyseCGM are detailed below. For each individual, variables are generated automatically for all time, day time hours only and night time hours only:

Set argument exercise is set to TRUE. Analysis of exercise data is usually done for time periods post exercise. If you are using this function on exercise data, structured as periods of CGM data that are a certain time post exercise, ensure your files are structured as outputted from the exercise_split function

• Additional CGM metrics are created for exercise and are defined in analyseCGM output

• min_spent_7_15_exercise

• percent_time_7_15_exercise

• min_spent_5_12_exercise

• percent_time_5_12_exercise