glucose360 0.0.1__py3-none-any.whl → 0.0.2__py3-none-any.whl

glucose360/features.py

@@ -4,11 +4,12 @@ import configparser
 from multiprocessing import Pool
 import os
 from scipy.integrate import trapezoid
+from importlib import resources
+from glucose360.preprocessing import load_config
 
-dir_path = os.path.dirname(os.path.realpath(__file__))
-config_path = os.path.join(dir_path, "config.ini")
-config = configparser.ConfigParser()
-config.read(config_path)
+# Initialize config at module level
+config = load_config()
+INTERVAL = int(config["variables"]["interval"])
 ID = config['variables']['id']
 GLUCOSE = config['variables']['glucose']
 TIME = config['variables']['time']
@@ -266,6 +267,19 @@ def HBGI(df: pd.DataFrame) -> float:
     BG = np.maximum(0, BG_formula(df[GLUCOSE]))
     return np.mean(10 * (BG ** 2))
 
+def BGRI(df: pd.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).
+
+    :param df: Pandas DataFrame with pre-processed CGM data
+    :return: BGRI value
+    """
+    return LBGI(df) + HBGI(df)
+
+
 def COGI(df: pd.DataFrame) -> float:
     """Calculates the Continuous Glucose Monitoring Index (COGI) for the given CGM trace.
 
@@ -341,6 +355,42 @@ def GRADE_hyper(df: pd.DataFrame) -> float:
     df_GRADE = GRADE_formula(df)
     return np.sum(df_GRADE[df_GRADE[GLUCOSE] > 140]["GRADE"]) / np.sum(df_GRADE["GRADE"]) * 100
 
+def GRADE_eugly_absolute(df: pd.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.
+
+    :param df: a Pandas DataFrame containing preprocessed CGM data
+    :type df: 'pandas.DataFrame'
+    :return: the absolute euglycemic GRADE for the given CGM trace
+    :rtype: float
+    """
+    df_GRADE = GRADE_formula(df)
+    return np.sum(df_GRADE[(df_GRADE[GLUCOSE] >= 70) & (df_GRADE[GLUCOSE] <= 140)]["GRADE"])
+
+def GRADE_hypo_absolute(df: pd.DataFrame) -> float:
+    """Returns the absolute GRADE contribution from hypoglycemic values.
+
+    :param df: a Pandas DataFrame containing preprocessed CGM data
+    :type df: 'pandas.DataFrame'
+    :return: the absolute hypoglycemic GRADE for the given CGM trace
+    :rtype: float
+    """
+    df_GRADE = GRADE_formula(df)
+    return np.sum(df_GRADE[df_GRADE[GLUCOSE] < 70]["GRADE"])
+
+def GRADE_hyper_absolute(df: pd.DataFrame) -> float:
+    """Returns the absolute GRADE contribution from hyperglycemic values.
+
+    :param df: a Pandas DataFrame containing preprocessed CGM data
+    :type df: 'pandas.DataFrame'
+    :return: the absolute hyperglycemic GRADE for the given CGM trace
+    :rtype: float
+    """
+    df_GRADE = GRADE_formula(df)
+    return np.sum(df_GRADE[df_GRADE[GLUCOSE] > 140]["GRADE"])
+
 def GRADE(df: pd.DataFrame) -> float:
     """Calculates the Glycaemic Risk Assessment Diabetes Equation (GRADE) for the given CGM trace.
 
@@ -416,15 +466,27 @@ def hypo_index(df: pd.DataFrame, limit: int = 80, b: float = 2, d: float = 30) -
     BG = df[GLUCOSE].dropna()
     return np.sum(np.power(limit - BG[BG < limit], b)) / (BG.size * d)
 
-def IGC(df: pd.DataFrame) -> float:
+def IGC(df: pd.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.
 
     :param df: a Pandas DataFrame containing preprocessed CGM data
     :type df: 'pandas.DataFrame'
+    :param hyper_limit: upper limit of target range (above which would hyperglycemia), defaults to 140 mg/dL
+    :type hyper_limit: int, optional
+    :param hypo_limit: lower limit of target range (above which would hypoglycemia), defaults to 80 mg/dL
+    :type hypo_limit: int, optional
+    :param hyper_a: exponent utilized for Hyperglycemia Index calculation, defaults to 1.1
+    :type hyper_a: float, optional
+    :param hyper_c: constant to help scale Hyperglycemia Index the same as other metrics (e.g. LBGI, HBGI, and GRADE), defaults to 30
+    :type hyper_c: float, optional
+    :param hypo_b: exponent utilized for Hypoglycemia Index calculation, defaults to 2
+    :type hypo_b: float, optional
+    :param hypo_d: constant to help scale Hypoglycemia Index the same as other metrics (e.g. LBGI, HBGI, and GRADE), defaults to 30
+    :type hypo_d: float, optional
     :return: the IGC for the given CGM trace
     :rtype: float
     """
-    return hyper_index(df) + hypo_index(df)
+    return hyper_index(df, hyper_limit, hyper_a, hyper_c) + hypo_index(df, hypo_limit, hypo_b, hypo_d)
 
 def j_index(df: pd.DataFrame) -> float:
     """Calculates the J-Index for the given CGM trace.
@@ -446,9 +508,7 @@ def CONGA(df: pd.DataFrame, n: int = 24) -> float:
     :return: the CONGA for the given CGM trace
     :rtype: float
     """
-    config.read('config.ini')
-    interval = int(config["variables"]["interval"])
-    period = n * (60 / interval)
+    period = n * (60 / INTERVAL)
     return np.std(df[GLUCOSE].diff(periods=period))
 
 # lag is in days
@@ -462,10 +522,7 @@ def MODD(df: pd.DataFrame, lag: int = 1) -> float:
     :return: the MODD for the given CGM trace
     :rtype: float
     """
-    config.read('config.ini')
-    interval = int(config["variables"]["interval"])
-    period = lag * 24 * (60 / interval)
-    
+    period = lag * 24 * (60 / INTERVAL)
     return np.mean(np.abs(df[GLUCOSE].diff(periods=period)))
 
 def mean_absolute_differences(df: pd.DataFrame) -> float:
@@ -504,6 +561,7 @@ def MAG(df: pd.DataFrame) -> float:
 
 def MAGE(df: pd.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).
 
    :param df: a Pandas DataFrame containing preprocessed CGM data
    :type df: 'pandas.DataFrame'
@@ -518,16 +576,13 @@ def MAGE(df: pd.DataFrame, short_ma: int = 5, long_ma: int = 32, max_gap: int =
    """
    data = df.reset_index(drop=True)
 
-   config.read('config.ini')
-   interval = int(config["variables"]["interval"])
-
    missing = data[GLUCOSE].isnull()
    # create groups of consecutive missing values
    groups = missing.ne(missing.shift()).cumsum()
    # group by the created groups and count the size of each group, then apply it where values are missing
    size_of_groups = data.groupby([groups, missing])[GLUCOSE].transform('size').where(missing, 0)
    # filter groups where size is greater than 0 and take their indexes
-   indexes = size_of_groups[size_of_groups.diff() > (max_gap / interval)].index.tolist()
+   indexes = size_of_groups[size_of_groups.diff() > (max_gap / INTERVAL)].index.tolist()
 
    if not indexes: # no gaps in data larger than max_gap
       return MAGE_helper(df, short_ma, long_ma)
@@ -544,7 +599,7 @@ def MAGE(df: pd.DataFrame, short_ma: int = 5, long_ma: int = 32, max_gap: int =
 
 def MAGE_helper(df: pd.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, and this method is a helper for the MAGE() function.
+   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.
 
    :param df: a Pandas DataFrame containing preprocessed CGM data without significant gaps (as defined in the MAGE() function)
    :type df: 'pandas.DataFrame'
@@ -573,8 +628,9 @@ def MAGE_helper(df: pd.DataFrame, short_ma: int = 5, long_ma: int = 32) -> float
    averages["MA_Long"] = averages[GLUCOSE].rolling(window=long_ma, min_periods=1).mean()
 
    # fill in leading NaNs due to moving average calculation
-   averages["MA_Short"].iloc[:short_ma-1] = averages["MA_Short"].iloc[short_ma-1]
-   averages["MA_Long"].iloc[:long_ma-1] = averages["MA_Long"].iloc[long_ma-1]
+   averages.loc[:(short_ma - 2), "MA_Short"] = averages.at[short_ma - 1, "MA_Short"]
+   averages.loc[:(long_ma - 2),  "MA_Long"]  = averages.at[long_ma - 1,  "MA_Long"]
+
    averages["DELTA_SL"] = averages["MA_Short"] - averages["MA_Long"]
    
    # get crossing points
@@ -694,12 +750,10 @@ def ROC(df: pd.DataFrame, timedelta: int = 15) -> pd.Series:
    :return: a Pandas Series with the rate of change in glucose values at every data point
    :rtype: 'pandas.Series'
    """
-   config.read('config.ini')
-   interval = int(config["variables"]["interval"])
-   if timedelta < interval:
+   if timedelta < INTERVAL:
       raise Exception("Given timedelta must be greater than resampling interval.")
 
-   positiondelta = round(timedelta / interval)
+   positiondelta = round(timedelta / INTERVAL)
    return df[GLUCOSE].diff(periods=positiondelta) / timedelta
 
 def number_readings(df: pd.DataFrame):
@@ -957,6 +1011,231 @@ def nocturnal_auc(df: pd.DataFrame) -> float:
 
     return np.nan if not daily_aucs else np.mean(daily_aucs)
 
+def daily_range_helper(df: pd.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.
+    """
+    valid = df.dropna(subset=[GLUCOSE]).copy()
+    if valid.empty:
+        return np.nan
+
+    valid['date'] = valid[TIME].dt.date
+    day_ranges = valid.groupby('date')[GLUCOSE].apply(lambda x: x.max() - x.min())
+    return day_ranges.mean()
+
+def Q_score(df: pd.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.
+
+    :param df: a Pandas DataFrame containing preprocessed CGM data
+    :type df: 'pandas.DataFrame'
+    :param hyper_limit: upper limit of target range (above which would hyperglycemia), defaults to 180 mg/dL, previously 160 mg/dL
+    :type hyper_limit: int, optional
+    :return: the Q-Score for the given CGM trace
+    :rtype: float
+    """
+    mbg = mean(df)
+    drange = daily_range_helper(df)
+    modd = MODD(df)
+
+    # Convert %-of-time to hours/day
+    t_hypo = percent_time_below_range(df) / 100 * 24
+    t_hyper = percent_time_above_range(df, limit=hyper_limit) / 100 * 24
+
+    # If any component is missing, return NaN
+    if np.isnan([mbg, drange, modd, t_hypo, t_hyper]).any():
+        return np.nan
+
+    return (
+        8
+        + (mbg - 140.4) / 30.6
+        + (drange - 135) / 52.2
+        + (t_hypo - 0.6) / 1.2
+        + (t_hyper - 6.2) / 5.7
+        + (modd - 32.4) / 16.2
+    )
+
+def _n_days(df: pd.DataFrame) -> float:
+    """
+    Decimal number of (calendar) days covered by the dataframe.
+    Any partial day counts fractionally; e.g. 36 h = 1.5 days.
+    """
+    t0, t1 = df[TIME].min(), df[TIME].max()
+    if pd.isna(t0) or pd.isna(t1):
+        return np.nan
+    return (t1 - t0).total_seconds() / 86_400.0
+
+def _axis_linear(val: float,
+                 ref: float,
+                 max_val: float,
+                 r0: float = 14.0,
+                 r_max: float = 76.0) -> float:
+    """
+    Maps   ref → r0   and   max_val → r_max   with linear scaling.
+    Values ≤ ref are clamped to r0; values ≥ max_val are clamped to r_max.
+    """
+    if np.isnan(val):
+        return np.nan
+    if val <= ref:
+        return r0
+    if val >= max_val:
+        return r_max
+    return r0 + (r_max - r0) * (val - ref) / (max_val - ref)
+
+
+def _auc_above_helper(df: pd.DataFrame, thr: int = 180) -> float:
+    """Total AUC (mg · min dL⁻¹) **above** *thr* over the *full* time axis."""
+    bg = df[[TIME, GLUCOSE]].dropna().copy()
+    if bg.empty:
+        return 0.0
+    excess = np.maximum(bg[GLUCOSE] - thr, 0.0)
+    if excess.eq(0).all():
+        return 0.0
+    t = (bg[TIME] - bg[TIME].iloc[0]).dt.total_seconds() / 60.0  # minutes
+    return trapezoid(excess, x=t)
+
+
+def _auc_below_helper(df: pd.DataFrame, thr: int = 70) -> float:
+    """Total AUC (mg · min dL⁻¹) **below** *thr* over the *full* time axis."""
+    bg = df[[TIME, GLUCOSE]].dropna().copy()
+    if bg.empty:
+        return 0.0
+    deficit = np.maximum(thr - bg[GLUCOSE], 0.0)
+    if deficit.eq(0).all():
+        return 0.0
+    t = (bg[TIME] - bg[TIME].iloc[0]).dt.total_seconds() / 60.0
+    return trapezoid(deficit, x=t)
+
+
+def _intensity_helper(time_min: float, auc: float) -> float:
+    """Euclidean intensity of an excursion (minutes, mg · min dL⁻¹)."""
+    return float(np.hypot(time_min, auc))
+
+
+
+_GP_MAX = {
+    "HbA1c":     14.0,
+    "Mean":      250.0,
+    "SD":        150.0,
+    "TAbove":    1440.0,
+    "AUCAbove":  432_000.0
+}
+
+
+def glucose_pentagon(df: pd.DataFrame,
+                     hbA1c: float | None = None,
+                     hyper_thr: int = 160) -> dict[str, float]:
+
+    days = _n_days(df)
+    if np.isnan(days) or days == 0:
+        return {"Glucose_Pentagon_Area": np.nan,
+                "Glucose_Pentagon_GRP":  np.nan}
+
+    # ----- core metrics -------------------------------------------------
+    a1c       = hbA1c if hbA1c is not None else eA1c(df)
+    mean_glu  = mean(df)
+    sd_glu    = SD(df)
+
+    # convert to *minutes per day* and *AUC per day*
+    t_above   = (percent_time_above_range(df, hyper_thr) / 100 * 1440)
+    auc_above =  _auc_above_helper(df, hyper_thr) / days
+
+    axes = np.array([
+        _axis_linear(a1c,        5.5,  _GP_MAX["HbA1c"]),
+        _axis_linear(mean_glu,   90.0, _GP_MAX["Mean"]),
+        _axis_linear(sd_glu,     10.0, _GP_MAX["SD"]),
+        _axis_linear(t_above,     0.0, _GP_MAX["TAbove"]),
+        _axis_linear(auc_above,   0.0, _GP_MAX["AUCAbove"])
+    ])
+
+    theta = np.deg2rad(72)
+    area  = 0.5 * np.sum(axes * np.roll(axes, -1) * np.sin(theta))
+    grp   = area / 466.0
+
+    return {"Glucose_Pentagon_Area": area,
+            "Glucose_Pentagon_GRP":  grp}
+
+
+
+_CGP_MAX = {
+    "Mean":     250.0,
+    "CV":        60.0,
+    "ToR":     1440.0,
+    "Intensity": 432_002.0 
+}
+
+def _axis_cgp(val: float, kind: str, r0: float = 14.0, r_max: float = 76.0) -> float:
+    """
+    Returns the radial length (mm) for the selected CGP axis,
+    with hard clamping to the range [14, 76] to prevent
+    negative or oversized radii.
+    """
+    if np.isnan(val):
+        return np.nan
+    match kind:
+        case "Mean":
+            r =  ((val - 90.)*0.0217)**2.63 + 14.
+        case "CV":
+            r = (val - 17.)*0.92 + 14.
+        case "ToR":
+            r = (val*0.00614)**1.581 + 14.
+        case "IntHyper":
+            r = (val*0.000115)**1.51 + 14.
+        case "IntHypo":
+            r = np.exp(val*0.00057) + 13.
+        case _:
+            raise ValueError(kind)
+
+    return max(r0, min(r_max,r))
+
+def comprehensive_glucose_pentagon(df: pd.DataFrame) -> dict[str, float]:
+
+    days = _n_days(df)
+    if np.isnan(days) or days == 0:
+        return {"Comprehensive_Glucose_Pentagon_Area": np.nan,
+                "Comprehensive_Glucose_Pentagon_PGR":  np.nan}
+
+    mean_glu  = mean(df)
+    cv_       = CV(df)
+
+    tir_min   = percent_time_in_range(df) / 100 * 1440 * days
+    tor_min   = (1440*days - tir_min) / days
+
+    t_above   = percent_time_above_range(df, 180) / 100 * 1440
+    t_below   = percent_time_below_range(df, 70)  / 100 * 1440
+    auc_above =  _auc_above_helper(df, 180) / days
+    auc_below =  _auc_below_helper(df, 70)  / days
+
+    int_hyper = _intensity_helper(t_above, auc_above)
+    int_hypo  = _intensity_helper(t_below, auc_below)
+
+    axes = np.array([
+        _axis_cgp(mean_glu,  "Mean"),
+        _axis_cgp(cv_,       "CV"),
+        _axis_cgp(tor_min,   "ToR"),
+        _axis_cgp(int_hyper, "IntHyper"),
+        _axis_cgp(int_hypo,  "IntHypo")
+    ])
+
+    theta = np.deg2rad(72)
+    area  = 0.5 * np.sum(axes * np.roll(axes, -1) * np.sin(theta))
+    pgr   = area / 466.0
+
+    return {"Comprehensive_Glucose_Pentagon_Area": area,
+            "Comprehensive_Glucose_Pentagon_PGR":  pgr}
 
 def compute_features(id: str, data: pd.DataFrame) -> dict[str, any]:
    """Calculates statistics and metrics for a single patient within the given DataFrame
@@ -969,11 +1248,16 @@ def compute_features(id: str, data: pd.DataFrame) -> dict[str, any]:
    :rtype: dict[str, any]
    """
    summary = summary_stats(data)
+   gp = glucose_pentagon(data)
+   cgp = comprehensive_glucose_pentagon(data)
 
    features = {
       ID: id,
       "ADRR": ADRR(data),
+      "BGRI": BGRI(data),
       "COGI": COGI(data),
+      "Comprehensive Glucose Pentagon Area": cgp["Comprehensive_Glucose_Pentagon_Area"],
+      "Comprehensive Glucose Pentagon PGR": cgp["Comprehensive_Glucose_Pentagon_PGR"],
       "CONGA": CONGA(data),
       "CV": CV(data),
       "Daytime AUC": auc_daytime(data),
@@ -981,10 +1265,15 @@ def compute_features(id: str, data: pd.DataFrame) -> dict[str, any]:
       "FBG": FBG(data),
       "First Quartile": summary[1],
       "GMI": GMI(data),
+      "Glucose Pentagon Area": gp["Glucose_Pentagon_Area"],
+      "Glucose Pentagon GRP": gp["Glucose_Pentagon_GRP"],
       "GRADE": GRADE(data),
       "GRADE (euglycemic)": GRADE_eugly(data),
+      "GRADE (euglycemic absolute)": GRADE_eugly_absolute(data),
       "GRADE (hyperglycemic)": GRADE_hyper(data),
+      "GRADE (hyperglycemic absolute)": GRADE_hyper_absolute(data),
       "GRADE (hypoglycemic)": GRADE_hypo(data),
+      "GRADE (hypoglycemic absolute)": GRADE_hypo_absolute(data),
       "GRI": GRI(data),
       "GVP": GVP(data),
       "HBGI": HBGI(data),
@@ -1021,6 +1310,7 @@ def compute_features(id: str, data: pd.DataFrame) -> dict[str, any]:
       "Percent Time in Hypoglycemia (level 2)": percent_time_in_level_2_hypoglycemia(data),
       "Percent Time In Range (70-180)": percent_time_in_range(data),
       "Percent Time In Tight Range (70-140)": percent_time_in_tight_range(data),
+      "Q-Score": Q_score(data),
       "SD": SD(data),
       "Third Quartile": summary[3],
    }

glucose360/main.py

@@ -0,0 +1,13 @@
+import pandas as pd
+from glucose360.preprocessing import *
+from glucose360.features import *
+from glucose360.events import *
+from glucose360.plots import *
+
+def main():
+   df = import_data("datasets")
+   for index, row in create_features(df).iterrows():
+      print(row)
+
+if __name__ == "__main__":
+   main()