forecose 0.1.0__tar.gz

forecose-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+dist/
+pydexcom.egg-info/
+__pycache__/
+.venv/
+build/
+.mypy_cache/
+.pytest_cache/
+.DS_Store
+.ruff_cache
+uv.lock
+docs/

forecose-0.1.0/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "python-envs.defaultEnvManager": "ms-python.python:system"
+}

forecose-0.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: forecose
+Version: 0.1.0
+Summary: A time-series forecasting extension for pydexcom using Google's TimesFM
+Author: Alexander Sadler
+Requires-Python: >=3.9
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: pydexcom
+Requires-Dist: timesfm[torch]>=2.0.0
+Description-Content-Type: text/markdown
+
+A time-series forecasting extension for [pydexcom](https://github.com/gagebenne/pydexcom) using Google's [TimesFM](https://github.com/google-research/timesfm). Used to predict immediate, short term blood glucose readings.
+
+> All modelling and forecasting is performed locally on your device. The only external connections made are with:
+> - Dexcom Share API: fetching CGM readings following the `pydexcom` approach.
+> - HuggingFace: one-time download of the forecasting model weights on the first run.
+
+## Quick Start
+1. Ensure that you have installed the pydexcom package and [enabled the Share service](https://provider.dexcom.com/education-research/cgm-education-use/videos/setting-dexcom-share-and-follow) within your [Dexcom G7 / G6 / G5 / G4](https://www.dexcom.com/apps).
+
+`pip install pydexcom`
+
+2. Initialise `pydexcom` with your Dexcom credentials (below shows the simplist route, refere to pydexcom for further instruction).
+
+```python
+>>> from pydexcom import Dexcom
+>>> dexcom = Dexcom(username="username", password="password")
+```
+
+3. Generate a prediction.
+
+```python
+>>> from forecose import DexcomForecast
+>>> forecaster = DexcomForecast.from_dexcom( 
+        dexcom=dexcom,      # pull recent readings from your active 'Dexcom' session
+        context_len=288,    # uses prior day's readings as context
+        horizon=12          # predicts the next hour
+    )
+>>> predictions = forecaster.forecast()
+>>> print(predictions.head())
+                         timestamp  predicted_glucose       q10       q25       q50       q75       q90
+0 2026-06-25 11:01:19.199000+01:00           8.243370  8.244899  8.125346  8.214749  8.266071  8.309934
+1 2026-06-25 11:06:19.199000+01:00           8.050682  8.073329  7.738788  8.018662  8.208736  8.303193
+2 2026-06-25 11:11:19.199000+01:00           7.897943  7.879324  7.332723  7.783697  8.082028  8.256586
+3 2026-06-25 11:16:19.199000+01:00           7.767045  7.738261  6.965607  7.621467  8.026337  8.236394
+4 2026-06-25 11:21:19.199000+01:00           7.615633  7.667328  6.668064  7.442780  7.972524  8.216294
+```

forecose-0.1.0/README.md

@@ -0,0 +1,36 @@
+A time-series forecasting extension for [pydexcom](https://github.com/gagebenne/pydexcom) using Google's [TimesFM](https://github.com/google-research/timesfm). Used to predict immediate, short term blood glucose readings.
+
+> All modelling and forecasting is performed locally on your device. The only external connections made are with:
+> - Dexcom Share API: fetching CGM readings following the `pydexcom` approach.
+> - HuggingFace: one-time download of the forecasting model weights on the first run.
+
+## Quick Start
+1. Ensure that you have installed the pydexcom package and [enabled the Share service](https://provider.dexcom.com/education-research/cgm-education-use/videos/setting-dexcom-share-and-follow) within your [Dexcom G7 / G6 / G5 / G4](https://www.dexcom.com/apps).
+
+`pip install pydexcom`
+
+2. Initialise `pydexcom` with your Dexcom credentials (below shows the simplist route, refere to pydexcom for further instruction).
+
+```python
+>>> from pydexcom import Dexcom
+>>> dexcom = Dexcom(username="username", password="password")
+```
+
+3. Generate a prediction.
+
+```python
+>>> from forecose import DexcomForecast
+>>> forecaster = DexcomForecast.from_dexcom( 
+        dexcom=dexcom,      # pull recent readings from your active 'Dexcom' session
+        context_len=288,    # uses prior day's readings as context
+        horizon=12          # predicts the next hour
+    )
+>>> predictions = forecaster.forecast()
+>>> print(predictions.head())
+                         timestamp  predicted_glucose       q10       q25       q50       q75       q90
+0 2026-06-25 11:01:19.199000+01:00           8.243370  8.244899  8.125346  8.214749  8.266071  8.309934
+1 2026-06-25 11:06:19.199000+01:00           8.050682  8.073329  7.738788  8.018662  8.208736  8.303193
+2 2026-06-25 11:11:19.199000+01:00           7.897943  7.879324  7.332723  7.783697  8.082028  8.256586
+3 2026-06-25 11:16:19.199000+01:00           7.767045  7.738261  6.965607  7.621467  8.026337  8.236394
+4 2026-06-25 11:21:19.199000+01:00           7.615633  7.667328  6.668064  7.442780  7.972524  8.216294
+```

forecose-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "forecose"
+version = "0.1.0"
+authors = [
+    {name = "Alexander Sadler"}
+]
+description = "A time-series forecasting extension for pydexcom using Google's TimesFM"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "numpy",
+    "pandas",
+    "pydexcom",
+    "timesfm[torch]>=2.0.0"
+]

forecose-0.1.0/src/forecose/__init__.py

@@ -0,0 +1,5 @@
+from .forecose import DexcomForecast
+
+__all__ = [
+    "DexcomForecast"
+]

forecose-0.1.0/src/forecose/forecose.py

@@ -0,0 +1,116 @@
+"""Dexcom prediction class."""
+
+import numpy as np
+
+import pandas as pd
+
+import timesfm
+
+from pydexcom import Dexcom
+
+class DexcomForecast:
+    """Class for a time-series forecasting model construction of CGM data."""
+
+    def __init__(
+            self,
+            cgm_history: np.ndarray,
+            last_timestamp: pd.Timestamp,
+            sampling_interval: pd.Timedelta,
+            context_len: int = 288,
+            horizon: int = 12
+    ) -> None:
+        """
+        Compiles the TimesFM model.
+        """
+        self.context_len = context_len
+        self.horizon = horizon
+
+        self.cgm_history = cgm_history[-self.context_len:]
+        self.last_timestamp = last_timestamp
+        self.sampling_interval = sampling_interval
+
+        # initalise and compile the TimesFM model
+        self.model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
+            "google/timesfm-2.5-200m-pytorch"
+        )
+        self.model.compile(
+            timesfm.ForecastConfig(
+                max_context=self.context_len,
+                max_horizon=self.horizon,
+                normalize_inputs=True,
+                use_continuous_quantile_head=True,
+                infer_is_positive=True,
+                fix_quantile_crossing=True,
+            )
+        )
+
+    @classmethod
+    def from_dexcom(
+        cls,
+        dexcom: Dexcom,
+        context_len: int = 288,
+        horizon: int = 12
+    ):
+        """Pull data from an active pydexcom session."""
+        if not isinstance(dexcom, Dexcom):
+            raise TypeError("Expected an object of type pydexcom.Dexcom.")
+        
+        # extract data
+        readings = dexcom.get_glucose_readings(
+            minutes=1440, max_count=context_len
+        )
+        if not readings:
+            raise RuntimeError("No readings returned from Dexcom Share API.")
+        
+        # process data structures
+        df = pd.DataFrame(
+            [{"Time": r.datetime, "Glucose": r.mmol_l} for r in reversed(readings)]
+        )
+        df["Time"] = pd.to_datetime(df["Time"], utc=True).dt.tz_convert("Europe/London")
+        df = df.sort_values("Time").reset_index(drop=True)
+
+        cgm_history = df["Glucose"].to_numpy(dtype=float)
+        last_timestamp = df["Time"].iloc[-1]
+        sampling_interval = pd.Timedelta(df["Time"].diff().median())
+
+        # return instance
+        return cls(
+            cgm_history=cgm_history,
+            last_timestamp=last_timestamp,
+            sampling_interval=sampling_interval,
+            context_len=context_len,
+            horizon=horizon
+        )
+    
+    def forecast(self) -> pd.DataFrame:
+        """Returns point and quantile forecasts of time series data."""
+        if len(self.cgm_history) == 0:
+            raise ValueError("No historical data provided for forecasting.")
+        
+        # run inference
+        point_forecast, quantile_forecast = self.model.forecast(
+            horizon=self.horizon,
+            inputs=[self.cgm_history],
+        )
+
+        point_vals = point_forecast[0]
+        quant_vals = quantile_forecast[0]
+
+        future_timestamps = pd.date_range(
+            start=self.last_timestamp + self.sampling_interval,
+            periods=self.horizon,
+            freq=self.sampling_interval,
+        )
+
+        # compile
+        forecast_df = pd.DataFrame({
+            "timestamp": future_timestamps,
+            "predicted_glucose": np.clip(point_vals, *(2.2, 22.2)),
+            "q10": np.clip(quant_vals[:, 0], *(2.2, 22.2)),
+            "q25": np.clip(quant_vals[:, 1], *(2.2, 22.2)),
+            "q50": np.clip(quant_vals[:, 4], *(2.2, 22.2)),
+            "q75": np.clip(quant_vals[:, 7], *(2.2, 22.2)),
+            "q90": np.clip(quant_vals[:, 8], *(2.2, 22.2)),
+        })
+
+        return forecast_df

forecose-0.1.0/tests/test_forecast.py

@@ -0,0 +1,64 @@
+import pytest
+import numpy as np
+import pandas as pd
+from unittest.mock import patch, MagicMock
+from forecose import DexcomForecast
+
+@pytest.fixture
+def sample_cgm_data():
+    """Sample CGM data for prior 24 hours."""
+    return np.random.uniform(4.0, 10.0, size=288)
+
+@pytest.fixture
+def mock_timesfm_model():
+    """
+    Mocks the TimesFM model to return dummy arrays.
+    """
+    with patch("forecose.forecose.timesfm.TimesFM_2p5_200M_torch.from_pretrained") as mock_model:
+        instance = mock_model.return_value
+        mock_point = np.array([[5.5] * 12])
+        mock_quantiles = np.zeros((1, 12, 10))
+
+        # quantiles
+        mock_quantiles[0, :, 0] = 4.0
+        mock_quantiles[0, :, 1] = 4.5
+        mock_quantiles[0, :, 4] = 5.0
+        mock_quantiles[0, :, 7] = 6.5
+        mock_quantiles[0, :, 8] = 7.0
+
+        instance.forecast.return_value = (mock_point, mock_quantiles)
+        yield instance
+
+def test_forecaster_structure(sample_cgm_data, mock_timesfm_model):
+    """Verifies the forecast method returns the correct pd.DataFrame structure."""
+
+    last_time = pd.Timestamp.now(tz="UTC")
+    interval = pd.Timedelta(minutes=5)
+
+    forecaster = DexcomForecast(
+        cgm_history=sample_cgm_data,
+        last_timestamp=last_time,
+        sampling_interval=interval,
+        context_len=288,
+        horizon=12
+    )
+
+    df = forecaster.forecast()
+
+    assert len(df) == 12
+
+    assert list(df.columns) == ["timestamp", "predicted_glucose", "q10", "q25", "q50", "q75", "q90"]
+
+    assert df["timestamp"].iloc[0] == last_time + interval
+    assert df["timestamp"].iloc[1] == last_time + (2 * interval)
+
+def test_forecaster_empty_history():
+    """Verifies the model blocks execution if no data is passed from the Dexcom Share API."""
+    forecaster = DexcomForecast(
+        cgm_history=np.array([]),
+        last_timestamp=pd.Timestamp.now(tz="UTC"),
+        sampling_interval=pd.Timedelta(minutes=5)
+    )
+
+    with pytest.raises(ValueError, match="No historical data provided"):
+        forecaster.forecast()