Features

features.ADRR(df: DataFrame) → float

Calculates the Average Daily Risk Range (ADRR) for the given CGM trace.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the ADRR for the given CGM trace

Return type:

float

features.BGRI(df: DataFrame) → float

Calculates the Blood Glucose Risk Index (BGRI).

BGRI is the overall glucose-risk score obtained by summing the Low Blood Glucose Index (LBGI) and the High Blood Glucose Index (HBGI).

Parameters:

df – Pandas DataFrame with pre-processed CGM data

Returns:

BGRI value

features.BG_formula(ser: Series) → Series

Calculates the Average Daily Risk Range (ADRR) for the given CGM trace.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the ADRR for the given CGM trace

Return type:

float

features.COGI(df: DataFrame) → float

Calculates the Continuous Glucose Monitoring Index (COGI) for the given CGM trace.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the COGI for the given CGM trace

Return type:

float

features.CONGA(df: DataFrame, n: int = 24) → float

Calculates the Continuous Overall Net Glycemic Action (CONGA) for the given CGM trace.

Parameters:

• df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

• n (int, optional) – the difference in time (in hours) between observations used to calculate CONGA, defaults to 24

Returns:

the CONGA for the given CGM trace

Return type:

float

features.CV(df: DataFrame) → float

Calculates the coefficient of variation (CV) for the given CGM trace

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing the preprocessed CGM data to calculate the CV for

Returns:

the CV of the given CGM trace

Return type:

float

features.FBG(df: DataFrame) → float

features.GMI(df: DataFrame) → float

Calculates the Glucose Management Indicator (GMI) for the given CGM trace

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing the preprocessed CGM data to calculate the GMI for

Returns:

the GMI of the given CGM trace

Return type:

float

features.GRADE(df: DataFrame) → float

Calculates the Glycaemic Risk Assessment Diabetes Equation (GRADE) for the given CGM trace.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the GRADE for the given CGM trace

Return type:

float

features.GRADE_eugly(df: DataFrame) → float

Calculates the Glycaemic Risk Assessment Diabetes Equation (GRADE) for solely the glucose values in target range (70-140 mg/dL) within the given CGM trace.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the euglycemic GRADE for the given CGM trace

Return type:

float

features.GRADE_eugly_absolute(df: DataFrame) → float

Returns the absolute GRADE contribution from euglycemic values.

This function sums the GRADE scores for readings in the target glucose range (70–140 mg/dL) without normalizing to the total GRADE.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the absolute euglycemic GRADE for the given CGM trace

Return type:

float

features.GRADE_formula(df: DataFrame) → DataFrame

Transforms each glucose value within the given CGM trace as needed to help calculate the Glycaemic Risk Assessment Diabetes Equation (GRADE).

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the LBGI for the given CGM trace

Return type:

float

features.GRADE_hyper(df: DataFrame) → float

Calculates the Glycaemic Risk Assessment Diabetes Equation (GRADE) for solely the glucose values in hyperglycemic range (>140 mg/dL) within the given CGM trace.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the hyperglycemic GRADE for the given CGM trace

Return type:

float

features.GRADE_hyper_absolute(df: DataFrame) → float

Returns the absolute GRADE contribution from hyperglycemic values.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the absolute hyperglycemic GRADE for the given CGM trace

Return type:

float

features.GRADE_hypo(df: DataFrame) → float

Calculates the Glycaemic Risk Assessment Diabetes Equation (GRADE) for solely the glucose values in hypoglycemic range (<70 mg/dL) within the given CGM trace.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the hypoglycemic GRADE for the given CGM trace

Return type:

float

features.GRADE_hypo_absolute(df: DataFrame) → float

Returns the absolute GRADE contribution from hypoglycemic values.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the absolute hypoglycemic GRADE for the given CGM trace

Return type:

float

features.GRI(df: DataFrame) → float

Calculates the Glycemia Risk Index (GRI) for the given CGM trace.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the GRI for the given CGM trace

Return type:

float

features.GVP(df: DataFrame) → float

Calculates the Glucose Variability Percentage (GVP) for the given CGM trace.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the GVP for the given CGM trace

Return type:

float

features.HBGI(df: DataFrame) → float

Calculates the High Blood Glucose Index (HBGI) for the given CGM trace.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the HBGI for the given CGM trace

Return type:

float

features.IGC(df: DataFrame, hyper_limit: int = 140, hypo_limit: int = 80, hyper_a: float = 1.1, hyper_c: float = 30, hypo_b: float = 2, hypo_d: float = 30) → float

Calculates the Index of Glycemic Control (IGC) for the given CGM trace.

Parameters:

• df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

• hyper_limit (int, optional) – upper limit of target range (above which would hyperglycemia), defaults to 140 mg/dL

• hypo_limit (int, optional) – lower limit of target range (above which would hypoglycemia), defaults to 80 mg/dL

• hyper_a (float, optional) – exponent utilized for Hyperglycemia Index calculation, defaults to 1.1

• hyper_c (float, optional) – constant to help scale Hyperglycemia Index the same as other metrics (e.g. LBGI, HBGI, and GRADE), defaults to 30

• hypo_b (float, optional) – exponent utilized for Hypoglycemia Index calculation, defaults to 2

• hypo_d (float, optional) – constant to help scale Hypoglycemia Index the same as other metrics (e.g. LBGI, HBGI, and GRADE), defaults to 30

Returns:

the IGC for the given CGM trace

Return type:

float

features.LBGI(df: DataFrame) → float

Calculates the Low Blood Glucose Index (LBGI) for the given CGM trace.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the LBGI for the given CGM trace

Return type:

float

features.LSBG(df: DataFrame) → float

Calculates the Lowest Sleeping Blood Glucose (LSBG).

Defined as the mean of the six lowest consecutive glucose measures between 23:30 and 06:30 (spanning midnight) for each day, averaged over all days.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the LSBG for the given CGM trace

Return type:

float

features.MAG(df: DataFrame) → float

Calculates the Mean Absolute Glucose (MAG) for the given CGM trace.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the MAG for the given CGM trace

Return type:

float

features.MAGE(df: DataFrame, short_ma: int = 5, long_ma: int = 32, max_gap: int = 180) → float

Calculates the Mean Amplitude of Glycemic Excursions (MAGE) for the given CGM trace. Algorithm for calculating MAGE is based on iglu’s implementation (please cite their papers found in the README).

Parameters:

• df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

• short_ma (int, optional) – number of data points utilized to calculate short moving average values, defaults to 5

• long_ma (int, optional) – number of data points utilized to calculate long moving average values, defaults to 32

• max_gap (int, optional) – number of minutes a gap between CGM data points can be without having to split the MAGE calculation into multiple segments, defaults to 180

Returns:

the MAGE for the given CGM trace

Return type:

float

features.MAGE_helper(df: DataFrame, short_ma: int = 5, long_ma: int = 32) → float

Calculates the Mean Amplitude of Glycemic Excursions (MAGE) for a specific segment of a CGM trace. Algorithm for calculating MAGE is based on iglu’s implementation (please cite their papers found in the README), and this method is a helper for the MAGE() function.

Parameters:

• df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data without significant gaps (as defined in the MAGE() function)

• short_ma (int, optional) – number of data points utilized to calculate short moving average values, defaults to 5

• long_ma (int, optional) – number of data points utilized to calculate long moving average values, defaults to 32

Returns:

the MAGE for the given segment of a CGM trace

Return type:

float

features.MODD(df: DataFrame, lag: int = 1) → float

Calculates the Mean Difference Between Glucose Values Obtained at the Same Time of Day (MODD) for the given CGM trace.

Parameters:

• df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

• lag (int, optional) – the difference in time (in days) between observations used to calculate MODD, defaults to 1

Returns:

the MODD for the given CGM trace

Return type:

float

features.Q_score(df: DataFrame, hyper_limit: int = 180) → float

Composite Q-Score.

Q = 8

• (MBG − 140.4) / 30.6

• (daily_range − 135) / 52.2

• (t_hypo − 0.6) / 1.2

• (t_hyper − 6.2) / 5.7

• (MODD − 32.4) / 16.2

All glucose values and constants are in mg/dL; t_hypo and t_hyper are hours/day spent < 70 mg/dL and > 160 mg/dL, respectively.

Parameters:

• df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

• hyper_limit (int, optional) – upper limit of target range (above which would hyperglycemia), defaults to 180 mg/dL, previously 160 mg/dL

Returns:

the Q-Score for the given CGM trace

Return type:

float

features.ROC(df: DataFrame, timedelta: int = 15) → Series

Returns a Pandas Series with the rate of change in glucose values at every data point

Parameters:

• df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

• timedelta (int, optional) – difference in time (in minutes) to utilize when calculating differences between data points, defaults to 15

Returns:

a Pandas Series with the rate of change in glucose values at every data point

Return type:

‘pandas.Series’

features.SD(df: DataFrame) → float

Calculates the standard deviation for the given CGM trace

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing the preprocessed CGM data to calculate the standard deviation for

Returns:

the standard deviation of the given CGM trace

Return type:

float

features.TIME = 'Timestamp'

All of the metric-calculating functions are designed for DataFrames that contain only one patient’s data. For example, if ‘df’ is the outputted DataFrame from ‘import_data()’, ‘LBGI(df)’ would not be accurate. Instead, do ‘LBGI(df.loc[PATIENT_ID])’.

features.auc_daytime(df: DataFrame) → float

Calculates the mean daytime AUC (Area Under the Curve) of glucose between 06:30 and 23:30 for each day, and then averages these daily AUCs.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the mean daytime AUC

Return type:

float

features.comprehensive_glucose_pentagon(df: DataFrame) → dict[str, float]

features.compute_features(id: str, data: DataFrame) → dict[str, any]

Calculates statistics and metrics for a single patient within the given DataFrame

Parameters:

• id (str) – the patient to calculate features for

• data ('pandas.DataFrame') – Pandas DataFrame containing preprocessed CGM data for one or more patients

Returns:

a dictionary (with each key referring to the name of a statistic or metric)

Return type:

dict[str, any]

features.create_features(dataset: DataFrame) → DataFrame

Takes in a multiindexed Pandas DataFrame containing CGM data for multiple patients/datasets, and returns a single indexed Pandas DataFrame containing summary metrics in the form of one row per patient/dataset

Parameters:

dataset ('pandas.DataFrame') – a Pandas DataFrame containing the CGM data to calculate metrics for

Returns:

a Pandas DataFrame with each row representing a patient in ‘dataset’ and each column representing a specific statistic or metric

Return type:

‘pandas.DataFrame’

features.daily_range_helper(df: DataFrame) → float

Mean of the daily glucose ranges (max – min) across all complete days. Helper function for Q-Score.

Returns NaN if no valid data are available.

features.eA1c(df: DataFrame) → float

Calculates the estimated A1c (eA1c) for the given CGM trace

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing the preprocessed CGM data to calculate the eA1c for

Returns:

the eA1c of the given CGM trace

Return type:

float

features.glucose_pentagon(df: DataFrame, hbA1c: float | None = None, hyper_thr: int = 160) → dict[str, float]

features.hyper_index(df: DataFrame, limit: int = 140, a: float = 1.1, c: float = 30) → float

Calculates the Hyperglycemia Index for the given CGM trace.

Parameters:

• df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

• limit (int, optional) – upper limit of target range (above which would hyperglycemia), defaults to 140 mg/dL

• a (float, optional) – exponent utilized for Hyperglycemia Index calculation, defaults to 1.1

• c (float, optional) – constant to help scale Hyperglycemia Index the same as other metrics (e.g. LBGI, HBGI, and GRADE), defaults to 30

Returns:

the Hyperglycemia Index for the given CGM trace

Return type:

float

features.hypo_index(df: DataFrame, limit: int = 80, b: float = 2, d: float = 30) → float

Calculates the Hypoglycemia Index for the given CGM trace.

Parameters:

• df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

• limit (int, optional) – lower limit of target range (above which would hypoglycemia), defaults to 80 mg/dL

• b (float, optional) – exponent utilized for Hypoglycemia Index calculation, defaults to 2

• d (float, optional) – constant to help scale Hypoglycemia Index the same as other metrics (e.g. LBGI, HBGI, and GRADE), defaults to 30

Returns:

the Hypoglycemia Index for the given CGM trace

Return type:

float

features.j_index(df: DataFrame) → float

Calculates the J-Index for the given CGM trace.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the J-Index for the given CGM trace

Return type:

float

features.m_value(df: DataFrame, r: int = 100) → float

Calculates the M-value for the given CGM trace.

Parameters:

• df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

• r (int, optional) – a reference value utilized for calculating the M-value, defaults to 100

Returns:

the M-value for the given CGM trace

Return type:

float

features.mean(df: DataFrame) → float

Calculates the mean glucose level for the given CGM trace

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing the preprocessed CGM data to calculate the mean glucose for

Returns:

the mean glucose level of the given CGM trace

Return type:

float

features.mean_24h(df: DataFrame) → float

Calculates the Mean 24-h starting from 23:30 to the next day’s 23:30 for each day.

For each date d, the 24-hour window is from d 23:30 to (d+1) 23:30. We compute the mean glucose within this window for each day, then average across all days.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the mean 24-h BG value for the given CGM trace

Return type:

float

features.mean_24h_auc(df: DataFrame) → float

Calculates the mean 24-hour AUC (Area Under the Curve) using the trapezoidal rule, with a 24-hour period defined from 23:30 of one day to 23:30 of the next day.

For each date d, the 24-hour period is from d 23:30 to (d+1) 23:30. The AUC for that day is the integral of glucose over time. We then average over all days to get the mean 24-hour AUC.

Integration is done using scipy.integrate.trapezoid with actual timestamps as ‘x’.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the mean 24-hour AUC for the given CGM trace (23:30–23:30)

Return type:

float

features.mean_absolute_differences(df: DataFrame) → float

Calculates the Mean Absolute Differences for the given CGM trace.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the mean absolute differences for the given CGM trace

Return type:

float

features.mean_daytime(df: DataFrame) → float

Calculates the mean daytime glucose, defined as the mean of all measures between 06:30 and 23:30 for each day, averaged across all days.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the mean daytime glucose level

Return type:

float

features.mean_nocturnal(df: DataFrame) → float

Calculates the mean nocturnal glucose, defined as the mean of all measures between 23:30 and 06:30 for each day, averaged across all days.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the mean nocturnal glucose level

Return type:

float

features.median_absolute_deviation(df: DataFrame, constant: float = 1.4826) → float

Calculates the Median Absolute Deviation for the given CGM trace.

Parameters:

• df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

• constant (float, optional) – factor to multiply median absolute deviation by, defaults to 1.4826

Returns:

the median absolute deviation for the given CGM trace

Return type:

float

features.nocturnal_auc(df: DataFrame) → float

Calculates the mean nocturnal AUC (Area Under the Curve) of glucose between 23:30 and 06:30 for each day, and then averages these daily AUCs.

For each date d, we define the nocturnal period as d 23:30 to (d+1) 06:30.

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the mean nocturnal AUC

Return type:

float

features.number_readings(df: DataFrame)

features.percent_time_above_range(df: DataFrame, limit: int = 180) → float

Returns the percent of total time the given CGM trace’s glucose levels were above a given threshold (inclusive)

Parameters:

• df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

• limit (int, optional) – the threshold for calculating the percent time above, defaults to 180

Returns:

the percentage of total time the glucose levels within the given CGM trace were above the given threshold (inclusive)

Return type:

float

features.percent_time_below_range(df: DataFrame, limit: int = 70) → float

Returns the percent of total time the given CGM trace’s glucose levels were below a given threshold (inclusive)

Parameters:

• df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

• limit (int, optional) – the threshold for calculating the percent time below, defaults to 70

Returns:

the percentage of total time the glucose levels within the given CGM trace were below the given threshold (inclusive)

Return type:

float

features.percent_time_in_hyperglycemia(df: DataFrame) → float

Returns the percent of total time the given CGM trace’s glucose levels were within literature-defined ranges that indicate hyperglycemia

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the percentage of total time the glucose levels within the given CGM trace were in ranges indicating hyperglycemia (> 180 mg/dL)

Return type:

float

features.percent_time_in_hypoglycemia(df: DataFrame) → float

Returns the percent of total time the given CGM trace’s glucose levels were within literature-defined ranges that indicate hypoglycemia

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the percentage of total time the glucose levels within the given CGM trace were in ranges indicating hypoglycemia (< 70 mg/dL)

Return type:

float

features.percent_time_in_level_0_hyperglycemia(df: DataFrame) → float

Returns the percent of total time the given CGM trace’s glucose levels were within ranges that indicate level 0 hyperglycemia

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the percentage of total time the glucose levels within the given CGM trace were in ranges indicating level 0 hyperglycemia (140-180 mg/dL)

Return type:

float

features.percent_time_in_level_1_hyperglycemia(df: DataFrame) → float

Returns the percent of total time the given CGM trace’s glucose levels were within literature-defined ranges that indicate level 1 hyperglycemia

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the percentage of total time the glucose levels within the given CGM trace were in ranges indicating level 1 hyperglycemia (180-250 mg/dL)

Return type:

float

features.percent_time_in_level_1_hypoglycemia(df: DataFrame) → float

Returns the percent of total time the given CGM trace’s glucose levels were within literature-defined ranges that indicate level 1 hypoglycemia

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the percentage of total time the glucose levels within the given CGM trace were in ranges indicating level 1 hypoglycemia (54-70 mg/dL)

Return type:

float

features.percent_time_in_level_2_hyperglycemia(df: DataFrame) → float

Returns the percent of total time the given CGM trace’s glucose levels were within literature-defined ranges that indicate level 2 hyperglycemia

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the percentage of total time the glucose levels within the given CGM trace were in ranges indicating level 2 hyperglycemia (> 250 mg/dL)

Return type:

float

features.percent_time_in_level_2_hypoglycemia(df: DataFrame) → float

Returns the percent of total time the given CGM trace’s glucose levels were within literature-defined ranges that indicate level 2 hypoglycemia

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the percentage of total time the glucose levels within the given CGM trace were in ranges indicating level 2 hypoglycemia (< 54 mg/dL)

Return type:

float

features.percent_time_in_range(df: DataFrame, low: int = 70, high: int = 180) → float

Returns the percent of total time the given CGM trace’s glucose levels were between the given lower and upper bounds (inclusive)

Parameters:

• df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

• low (int, optional) – the lower bound of the acceptable glucose values, defaults to 70

• high (int, optional) – the upper bound of the acceptable glucose values, defaults to 180

Returns:

the percentage of total time the glucose levels within the given CGM trace were between the given bounds (inclusive)

Return type:

float

features.percent_time_in_tight_range(df: DataFrame)

Returns the percent of total time the given CGM trace’s glucose levels were within 70-140 mg/dL (inclusive)

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

the percentage of total time the glucose levels within the given CGM trace were within 70-140 mg/dL (inclusive)

Return type:

float

features.summary_stats(df: DataFrame) → list[float]

Calculates summary statistics (minimum, first quartile, median, third quartile, and maximum) for the given CGM trace

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing the preprocessed CGM data to calculate the five-point summary for

Returns:

a list containing the five-point summary for the given CGM trace

Return type:

list[float]