support for Series, list and ndarray -> return float or dict

Author: staskh

README.md

@@ -25,15 +25,15 @@ Unless noted, IGLU-R test compatability is considered successful if it achieves
 
 | Function | Description | IGLU-R test compatibility | list /ndarray /Series input | TZ | Comments |
 |----------|-------------|-------------|-------------------|----|----------|
-| above_percent | percentage of values above target thresholds| ✅ |✅ returns dict |||
-| active_percent | percentage of time CGM was active | ✅ | ✅ only Series(DatetimeIndex) returns dict[str:float]
+| above_percent | percentage of values above target thresholds| ✅ |✅ returns Dict[str,float] |||
+| active_percent | percentage of time CGM was active | ✅ | ✅ only Series(DatetimeIndex) returns Dict[str,float]|
 | adrr | average daily risk range | ✅ |✅ only Series(DatetimeIndex) returns float |
 | auc| Area Under Curve | 🟡 (0.01 precision) |✅ only Series(DatetimeIndex) returns float  || see [auc_evaluation.ipynb](https://github.com/staskh/iglu_python/blob/main/notebooks/auc_evaluation.ipynb)|
-| below_percent| percentage of values below target thresholds| ✅ | ✅ returns dict
+| below_percent| percentage of values below target thresholds| ✅ | ✅ returns Dict[str,float]|
 | cogi |Coefficient of Glucose Irregularity | ✅ | ✅ returns float
 | conga | Continuous Overall Net Glycemic Action |✅ | ✅ only Series(DatetimeIndex) returns float
 | cv_glu | Coefficient of Variation | ✅|  ✅ returns float |
-| cv_measures |Coefficient of Variation subtypes (CVmean and CVsd) |✅  |✅ only Series(DatetimeIndex) returns dict| | 
+| cv_measures |Coefficient of Variation subtypes (CVmean and CVsd) |✅  |✅ only Series(DatetimeIndex) returns Dict[str,float]| | 
 | ea1c |estimated A1C (eA1C) values| ✅ | ✅ returns float |
 | episode_calculation | Hypo/Hyperglycemic episodes with summary statistics|  ✅|  🟡 always returns DataFrame(s)|| |
 | gmi | Glucose Management Indicator | ✅ | ✅ returns float |
@@ -47,16 +47,16 @@ Unless noted, IGLU-R test compatability is considered successful if it achieves
 | hyper_index |Hyperglycemia Index| ✅ |✅ returns float |
 | hypo_index |Hypoglycemia Index| ✅ |✅ returns float |
 | igc |Index of Glycemic Control| ✅ |✅ returns float |
-| in_range_percent |percentage of values within target ranges| ✅ | ✅ returns dict
+| in_range_percent |percentage of values within target ranges| ✅ | ✅ returns Dict[str,float]|
 | iqr_glu |glucose level interquartile range|✅ |✅ returns float |
 | j_index |J-Index score for glucose measurements| ✅ |✅ returns float |
-| lbgi | Low Blood Glucose Index| ✅ |
-| m_value | M-value of Schlichtkrull et al | ✅ |
-| mad_glu | Median Absolute Deviation | ✅ |
-| mag | Mean Absolute Glucose| ✅ | || IMHO, Original R implementation has an error |
+| lbgi | Low Blood Glucose Index| ✅ |✅ returns float |
+| m_value | M-value of Schlichtkrull et al | ✅ |✅ returns float |
+| mad_glu | Median Absolute Deviation | ✅ |✅ returns float |
+| mag | Mean Absolute Glucose| ✅ | ✅ only Series(DatetimeIndex) returns float ||| IMHO, Original R implementation has an error |
 | mage | Mean Amplitude of Glycemic Excursions|  ✅ |✅ only Series(DatetimeIndex) returns float || See algorithm at [MAGE](https://irinagain.github.io/iglu/articles/MAGE.html) |
 | mean_glu | Mean glucose value | ✅ | ✅ returns float|
-| median_glu |Median glucose value| ✅ |
+| median_glu |Median glucose value| ✅ |✅ returns float |
 | modd | Mean of Daily Differences| ✅ |
 | pgs | Personal Glycemic State | ✅  | || |
 | quantile_glu |glucose level quantiles|  ✅ |

iglu_python/lbgi.py

@@ -6,7 +6,7 @@
 from .utils import check_data_columns
 
 
-def lbgi(data: Union[pd.DataFrame, pd.Series]) -> pd.DataFrame:
+def lbgi(data: Union[pd.DataFrame, pd.Series, np.ndarray, list]) -> pd.DataFrame|float:
     r"""
     Calculate the Low Blood Glucose Index (LBGI) for each subject.
 
@@ -21,15 +21,15 @@ def lbgi(data: Union[pd.DataFrame, pd.Series]) -> pd.DataFrame:
 
     Parameters
     ----------
-    data : Union[pd.DataFrame, pd.Series]
-        DataFrame with columns ['id', 'time', 'gl'] or Series of glucose values
+    data : Union[pd.DataFrame, pd.Series, np.ndarray, list]
+        DataFrame with columns ['id', 'time', 'gl'] or Series of glucose values, or a numpy array or list of glucose values
         in mg/dL
 
     Returns
     -------
-    pd.DataFrame
+    pd.DataFrame|float
         DataFrame with columns ['id', 'LBGI'] containing LBGI values for each subject
-        If input is a Series, returns DataFrame with single row and column 'LBGI'
+        If input is a Series, returns a float.
 
     References
     ----------
@@ -63,26 +63,18 @@ def lbgi(data: Union[pd.DataFrame, pd.Series]) -> pd.DataFrame:
            LBGI
     0  0.123456
     """
-    if isinstance(data, pd.Series):
-        lbgi_value = calculate_lbgi(data)
-        return pd.DataFrame({"LBGI": [lbgi_value]})
+    if isinstance(data, (pd.Series,list, np.ndarray)):
+        if isinstance(data, (np.ndarray, list)):
+            data = pd.Series(data)
+        return calculate_lbgi(data)
 
     # Check DataFrame format
     check_data_columns(data)
 
-    if len(data) == 0:
-        raise ValueError("Empty DataFrame provided")
-
-    # Calculate LBGI for each subject
-    results = []
-
-    for subject_id in data["id"].unique():
-        subject_data = data[data["id"] == subject_id]["gl"]
-        lbgi_value = calculate_lbgi(subject_data)
-        results.append({"id": subject_id, "LBGI": lbgi_value})
-
-    return pd.DataFrame(results)
-
+    out = data.groupby('id').agg(
+        LBGI = ("gl", lambda x: calculate_lbgi(x))
+    ).reset_index()
+    return out
 
 def calculate_lbgi(glucose_values: pd.Series) -> float:
     """

iglu_python/m_value.py

@@ -6,7 +6,7 @@
 from .utils import check_data_columns
 
 
-def m_value(data: Union[pd.DataFrame, pd.Series], r: float = 90) -> pd.DataFrame:
+def m_value(data: Union[pd.DataFrame, pd.Series, np.ndarray, list], r: float = 90) -> pd.DataFrame|float:
     r"""
     Calculate the M-value of Schlichtkrull et al. (1965) for each subject.
 
@@ -22,17 +22,16 @@ def m_value(data: Union[pd.DataFrame, pd.Series], r: float = 90) -> pd.DataFrame
 
     Parameters
     ----------
-    data : Union[pd.DataFrame, pd.Series]
-        DataFrame with columns 'id', 'time', and 'gl', or a Series of glucose values
+    data : Union[pd.DataFrame, pd.Series, np.ndarray, list]
+        DataFrame with columns 'id', 'time', and 'gl', or a Series of glucose values, or a numpy array or list of glucose values
     r : float, default=90
         A reference value corresponding to basal glycemia in normal subjects
 
     Returns
     -------
-    pd.DataFrame
+    pd.DataFrame|float
         DataFrame with 1 row for each subject, a column for subject id and a column
-        for M-value. If a Series of glucose values is passed, then a DataFrame
-        without the subject id is returned.
+        for M-value. If a Series of glucose values is passed, then a float is returned.
 
     References
     ----------
@@ -60,20 +59,26 @@ def m_value(data: Union[pd.DataFrame, pd.Series], r: float = 90) -> pd.DataFrame
     0   111.11
     """
     # Handle Series input
-    if isinstance(data, pd.Series):
-        return pd.DataFrame(
-            {"M_value": [1000 * np.mean(np.abs(np.log10(data / r)) ** 3)]}
-        )
+    if isinstance(data, (pd.Series,list, np.ndarray)):
+        if isinstance(data, (np.ndarray, list)):
+            data = pd.Series(data)
+        return m_value_single(data, r)
 
     # Handle DataFrame input
     data = check_data_columns(data)
 
-    # Calculate M-value for each subject
-    result = (
-        data.groupby("id")
-        .apply(lambda x: 1000 * np.mean(np.abs(np.log10(x["gl"] / r)) ** 3), include_groups=False)
-        .reset_index()
-    )
-    result.columns = ["id", "M_value"]
+    out = data.groupby('id').agg(
+        M_value = ("gl", lambda x: m_value_single(x, r))
+    ).reset_index()
+    return out
+
+def m_value_single(gl:  pd.Series, r: float = 90) -> float:
+    """
+    Calculate the M-value of Schlichtkrull et al. (1965) for a single subject.
+    """
+    gl = gl.dropna()
+    if len(gl) == 0:
+        return np.nan
+    m_value = 1000 * np.mean(np.abs(np.log10(gl / r)) ** 3)
+    return m_value
 
-    return result

iglu_python/mad_glu.py

@@ -7,8 +7,8 @@
 
 
 def mad_glu(
-    data: Union[pd.DataFrame, pd.Series], constant: float = 1.4826
-) -> pd.DataFrame:
+    data: Union[pd.DataFrame, pd.Series, np.ndarray, list], constant: float = 1.4826
+) -> pd.DataFrame|float:
     """
     Calculate Median Absolute Deviation (MAD) of glucose values.
 
@@ -18,19 +18,21 @@ def mad_glu(
 
     Parameters
     ----------
-    data : Union[pd.DataFrame, pd.Series]
-        DataFrame with columns 'id', 'time', and 'gl', or a Series of glucose values
+    data : Union[pd.DataFrame, pd.Series, np.ndarray, list]
+        DataFrame with columns 'id', 'time', and 'gl', or a Series of glucose values, 
+        or a numpy array or list of glucose values
     constant : float, default=1.4826
         Scaling factor to multiply the MAD value. The default value of 1.4826
         makes the MAD consistent with the standard deviation for normally
         distributed data.
 
     Returns
     -------
-    pd.DataFrame
+    pd.DataFrame|float
         DataFrame with columns:
         - id: subject identifier (if DataFrame input)
-        - MAD: MAD value (median absolute deviation of glucose values)
+        - MAD: MAD value (median absolute deviation of glucose values). 
+        If a Series of glucose values is passed, then a float is returned.
 
     Examples
     --------
@@ -51,26 +53,25 @@ def mad_glu(
     0  27.5
     """
     # Handle Series input
-    if isinstance(data, pd.Series):
-        # Calculate MAD for the Series
-        mad_val = np.median(np.abs(data - np.median(data))) * constant
-        return pd.DataFrame({"MAD": [mad_val]})
+    if isinstance(data, (pd.Series,list, np.ndarray)):
+        if isinstance(data, (np.ndarray, list)):
+            data = pd.Series(data)
+        return mad_glu_single(data, constant)
 
     # Handle DataFrame input
     data = check_data_columns(data)
 
-    # Calculate MAD for each subject
-    result = []
-    for subject in data["id"].unique():
-        subject_data = data[data["id"] == subject]
-        if len(subject_data.dropna(subset=["gl"])) == 0:
-            continue
+    out = data.groupby('id').agg(
+        MAD = ("gl", lambda x: mad_glu_single(x, constant))
+    ).reset_index()
+    return out
 
-        # Calculate MAD for this subject
-        mad_val = (
-            np.median(np.abs(subject_data["gl"] - np.median(subject_data["gl"])))
-            * constant
-        )
-        result.append({"id": subject, "MAD": mad_val})
-
-    return pd.DataFrame(result)
+def mad_glu_single(gl: pd.Series, constant: float = 1.4826) -> float:
+    """
+    Calculate Median Absolute Deviation (MAD) of glucose values for a single subject.
+    """
+    gl = gl.dropna()
+    if len(gl) == 0:
+        return np.nan
+    mad_val = np.median(np.abs(gl - np.median(gl))) * constant
+    return mad_val