Example metrics

All metric functions in iglu will produce the output in a tibble form. See documentation on tibbles with vignette(‘tibble’) or ?tbl_df-class.

Some metric functions, like above_percent(), will return multiple values for a single subject.

above_percent(example_data_1_subject)
#> # A tibble: 1 x 5
#>   id        above_140 above_180 above_200 above_250
#>   <fct>         <dbl>     <dbl>     <dbl>     <dbl>
#> 1 Subject 1      26.7      8.40      3.70     0.446

When a dataframe is passed, subject id will always be printed in the id column, and metrics will be printed in the following columns.

As discussed above, just the glucose vector can be supplied for the single subject case.

above_percent(example_data_1_subject$gl)
#> # A tibble: 1 x 4
#>   above_140 above_180 above_200 above_250
#>       <dbl>     <dbl>     <dbl>     <dbl>
#> 1      26.7      8.40      3.70     0.446

However, it is not recommended to pass just glucose values whenever the time and subject are also available, because this output will not contain the subject ID.

The list of target values for the above_percent metric is a parameter that can be changed:

above_percent(example_data_1_subject, targets = c(100, 200, 300))
#> # A tibble: 1 x 4
#>   id        above_100 above_200 above_300
#>   <fct>         <dbl>     <dbl>     <dbl>
#> 1 Subject 1      74.4      3.70         0

Many metrics have parameters that can be changed. To see available parameters for a given metric, see the documentation i.e. ?above_percent or help(above_percent).

Not all metric functions return multiple values. Many, like MAGE() (Mean Amplitude of Glycemic Excursions), will return just a single value for each subject, producing a column for value and a column for subject id (if a dataframe is passed), as well as a row for each subject.

mage(example_data_5_subject)
#> # A tibble: 5 x 2
#>   id         mage
#>   <fct>     <dbl>
#> 1 Subject 1  53.4
#> 2 Subject 2  78.2
#> 3 Subject 3  76.6
#> 4 Subject 4  42.9
#> 5 Subject 5  90.0

CGMS2DayByDay()

Observe that the timestamps in the first rows are not evenly spaced. Linear interpolation is used where appropriate for computation of metrics that require a time component with equally spaced measurements. Time intervals within large gaps between variables will not be interpolated, but instead will be treated as missing values.

Functions requiring linear interpolation call the CGMS2DayByDay() function on the data automatically. This function can be explicitly called by the user to test on their datasets. Note that this function is only designed for one subject at a time. Below we will look at the structure of this functions output.

str(CGMS2DayByDay(example_data_1_subject))
#> List of 3
#>  $ gd2d        : num [1:14, 1:288] NA 112.2 92 90.1 143.1 ...
#>  $ actual_dates: Date[1:14], format: "2015-06-06" "2015-06-07" ...
#>  $ dt0         : num 5

The first part of the output, gd2d, is the interpolated grid of values. The function determined that the frequency of the measurements for this sensor was 5 minutes, so for each of the 14 days (the rows) there are 288 columns (the 5 minute intervals). The second part of the output, actual_dates, is a vector of dates corresponding to the ros in the gd2d output. The final part is just the dt0, parameter, which is detected automatically but can also be specified.

str(CGMS2DayByDay(example_data_1_subject, dt0 = 10))
#> List of 3
#>  $ gd2d        : num [1:14, 1:144] NA 111.1 92.9 89.1 138.2 ...
#>  $ actual_dates: Date[1:14], format: "2015-06-06" "2015-06-07" ...
#>  $ dt0         : num 10

Note that the final part of the output reflects our input, and there are now only 144 columns instead of 288.

The CGMS2DayByDay function also allows specification of the maximum allowable gap to interpolate values across (default is 45 minutes) and a string corresponding to time zone (default is the timezone of the user’s system).

All functions for metrics requiring linear interpolation will accept the following three parameters that are passed on to CGMS2DayByDay():

• “dt0” - Time frequency (numeric) for interpolation. Default will automatically match the frequency of the data
• “inter_gap” - Maximum allowable gap in minutes (numeric) for interpolation
• “tz” - String corresponding to timezone where the data’s measurements were recorded

In the example_data_5_subject dataset, it is important to specify tz = ‘EST’, because a Daylight Savings Time shift can cause miscalculations if the wrong timezone is used. A proper call for this dataset, being recorded in EST, would be:

CGMS2DayByDay(example_data_1_subject, tz = 'EST')

Examples of proper metric function calls will be shown in the next section.

Example metrics

Need to add references to ‘tz’ in these examples.

Some metric functions, like conga() (Continuous Overlapping Net Glycemic Action), will return just a single value for each subject, resulting in a 2 column tibble (1 column for id and 1 for the single value).

conga(example_data_1_subject, tz = 'EST')
#> # A tibble: 1 x 2
#>   id        conga
#>   <fct>     <dbl>
#> 1 Subject 1  37.0

Note that even though we are working with a single subject, a dataframe with glucose values, time, and subject id’s must be passed. Functions for metrics requiring the time component for calculation can not be passed a vector of glucose values.

sd_measures(), which computes 6 unique standard deviation subtypes, requires linear interpolation and returns multiple values for each subject.

sd_measures(example_data_5_subject)
#> # A tibble: 5 x 7
#>   id          SdW SdHHMM SdWSH  SdDM   SdB SdBDM
#>   <fct>     <dbl>  <dbl> <dbl> <dbl> <dbl> <dbl>
#> 1 Subject 1  26.4   19.6  6.54  16.7  27.9  24.0
#> 2 Subject 2  36.7   22.8  7.62  52.0  48.0  35.9
#> 3 Subject 3  42.9   14.4  9.51  12.4  42.8  42.5
#> 4 Subject 4  24.5   12.9  6.72  16.9  25.5  22.0
#> 5 Subject 5  50.0   29.6 12.8   23.3  50.3  45.9