add type hints; bump

Author: CamDavidsonPilon

AGENTS.md

@@ -0,0 +1,46 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+This is a small Python package with a `src/` layout:
+- `src/grpredict/__init__.py`: core implementation (`CultureGrowthEKF`, moving statistics helpers).
+- `src/grpredict/__init__.pyi` and `src/grpredict/py.typed`: typing surface for consumers.
+- `tests/`: pytest suite (`test_ekf.py`, `test_moving_accumulators.py`).
+- `build/` and `dist/`: packaging artifacts; treat as generated output.
+
+Keep new code close to existing modules unless there is a clear boundary that justifies a new file.
+
+## Build, Test, and Development Commands
+Use the local virtual environment (`.venv`) when available.
+
+```bash
+source .venv/bin/activate
+pip install -e ".[dev]"      # editable install + pytest/black/mypy
+pytest -v                      # full test suite (matches CI)
+pytest tests/test_ekf.py -q    # run one file during iteration
+python -m mypy src             # type-check package code
+python -m build                # build sdist/wheel into dist/
+```
+
+CI (`.github/workflows/ci.yaml`) runs tests on Python 3.11 with `pytest -v`.
+
+## Coding Style & Naming Conventions
+- Follow standard Python style: 4-space indentation, `snake_case` for functions/variables, `PascalCase` for classes.
+- Preserve explicit type hints on public functions and tests.
+- Keep functions focused and readable; prefer straightforward logic over clever abstractions.
+- Use `black` formatting conventions (configured via default behavior unless specified otherwise).
+
+## Testing Guidelines
+- Framework: `pytest`.
+- Test files must be named `test_*.py`; test functions should start with `test_`.
+- Add targeted tests for behavior changes before broad refactors.
+- During development, run individual tests first, then the full suite before opening a PR.
+
+## Commit & Pull Request Guidelines
+Recent history favors short, imperative commit subjects (for example: `adding ci`, `Update README.md`).
+- Keep commit titles concise and action-oriented.
+- In PRs, include: problem statement, implementation summary, and test evidence (`pytest` output or equivalent).
+- Link related tickets/issues when applicable and call out any API/behavior changes explicitly.
+
+## Security & Configuration Tips
+- Never commit secrets or local environment files (`.env`, `.envrc`).
+- Validate changes against typed interfaces (`.pyi`/`py.typed`) when modifying public APIs.

CHANGELOG.md

@@ -0,0 +1,7 @@
+## 26.2.10
+
+Adding type hints
+
+## 25.6.1
+
+Initial release

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "grpredict"
-version = "25.6.1"
+version = "26.2.10"
 description = "Estimate growth curves using an Extended Kalman Filter"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -43,6 +43,8 @@ dev = [
     "mypy"
 ]
 
+[tool.setuptools.package-data]
+grpredict = ["py.typed", "*.pyi"]
 
 [tool.setuptools.packages.find]
-where = ["src"]
+where = ["src"]

src/grpredict/__init__.py

@@ -1,7 +1,13 @@
 # -*- coding: utf-8 -*-
 from __future__ import annotations
+from collections.abc import Sequence
 from math import sqrt
+from typing import Any
 from typing import Optional
+from typing import TypeAlias
+
+FloatVectorLike: TypeAlias = Any
+FloatMatrixLike: TypeAlias = Any
 
 class ExponentialMovingAverage:
     """
@@ -12,7 +18,7 @@ class ExponentialMovingAverage:
     Ex: if alpha = 0, use latest value only.
     """
 
-    def __init__(self, alpha: float):
+    def __init__(self, alpha: float) -> None:
         if alpha < 0 or alpha > 1:
             raise ValueError
         self.value: Optional[float] = None
@@ -51,7 +57,7 @@ def __init__(
         ema_alpha: Optional[float] = None,
         initial_std_value: Optional[float] = None,
         initial_mean_value: Optional[float] = None,
-    ):
+    ) -> None:
         self._var_value = initial_std_value**2 if initial_std_value is not None else None
         self.value: Optional[float] = initial_std_value if initial_std_value is not None else None
         self.alpha = alpha
@@ -195,16 +201,19 @@ class CultureGrowthEKF:
 
     def __init__(
         self,
-        initial_state,
-        initial_covariance,
-        process_noise_covariance,
-        observation_noise_covariance,
-        angles: list[str],
+        initial_state: FloatVectorLike,
+        initial_covariance: FloatMatrixLike,
+        process_noise_covariance: FloatMatrixLike,
+        observation_noise_covariance: FloatMatrixLike,
+        angles: Sequence[str],
         outlier_std_threshold: float,
     ) -> None:
         import numpy as np
 
-        initial_state = np.asarray(initial_state)
+        initial_state = np.asarray(initial_state, dtype=float)
+        initial_covariance = np.asarray(initial_covariance, dtype=float)
+        process_noise_covariance = np.asarray(process_noise_covariance, dtype=float)
+        observation_noise_covariance = np.asarray(observation_noise_covariance, dtype=float)
 
         assert initial_state.shape[0] == 2
         assert (
@@ -228,10 +237,15 @@ def __init__(
             0.975, 0.80, initial_std_value=np.sqrt(observation_noise_covariance[0][0])
         )
 
-    def update(self, obs: list[float], dt: float, recent_dilution=False):
+    def update(
+        self,
+        obs: FloatVectorLike,
+        dt: float,
+        recent_dilution: bool = False,
+    ) -> tuple[FloatVectorLike, FloatMatrixLike]:
         import numpy as np
 
-        observation = np.asarray(obs)
+        observation = np.asarray(obs, dtype=float)
         assert observation.shape[0] == self.n_sensors, (observation, self.n_sensors)
 
         # Predict
@@ -287,7 +301,6 @@ def update(self, obs: list[float], dt: float, recent_dilution=False):
 
         # update gr process covariance if required
         nis = (residual_state[0] ** 2) / residual_covariance[0, 0]
-
         if nis > _NIS_THRESHOLD:
             self.process_noise_covariance[1, 1] *= 2
         else:
@@ -300,13 +313,14 @@ def update(self, obs: list[float], dt: float, recent_dilution=False):
 
         return self.state_, self.covariance_
 
-    def update_observation_noise_cov(self, residual_state):
+    def update_observation_noise_cov(self, residual_state: FloatVectorLike) -> FloatMatrixLike:
         """
         Exponentially-weighted measurement noise covariance.
         """
         import numpy as np
 
         lambda_ = 0.97  # controls the “memory” of the estimator. 0.97 means the filter effectively averages the last ≈ 1 / (1-0.97) ≈ 33 timesteps.
+        residual_state = np.asarray(residual_state, dtype=float)
         rrT = np.outer(residual_state, residual_state)
 
         observation_noise_covariance = lambda_ * self.observation_noise_covariance + (1.0 - lambda_) * rrT
@@ -317,7 +331,7 @@ def update_observation_noise_cov(self, residual_state):
 
         return observation_noise_covariance
 
-    def update_state_from_previous_state(self, state, dt: float):
+    def update_state_from_previous_state(self, state: FloatVectorLike, dt: float) -> FloatVectorLike:
         """
         Denoted "f" in literature, x_{k} = f(x_{k-1})
 
@@ -329,10 +343,10 @@ def update_state_from_previous_state(self, state, dt: float):
         """
         import numpy as np
 
-        od, rate = state
+        od, rate = np.asarray(state, dtype=float)
         return np.array([od * np.exp(rate * dt), rate])
 
-    def _J_update_observations_from_state(self, state_prediction):
+    def _J_update_observations_from_state(self, state_prediction: FloatVectorLike) -> FloatMatrixLike:
         """
         Jacobian of observations model, encoded as update_observations_from_state
 
@@ -362,7 +376,17 @@ def _J_update_observations_from_state(self, state_prediction):
             J[i, 0] = 1.0 if (angle != "180") else -exp(-(od - 1))
         return J
 
-    def update_covariance_from_old_covariance(self, state, covariance, dt: float, recent_dilution: bool):
+    def update_covariance_from_old_covariance(
+        self,
+        state: FloatVectorLike,
+        covariance: FloatMatrixLike,
+        dt: float,
+        recent_dilution: bool,
+    ) -> FloatMatrixLike:
+        import numpy as np
+
+        state = np.asarray(state, dtype=float)
+        covariance = np.asarray(covariance, dtype=float)
         Q = self.process_noise_covariance.copy().astype(float)
 
         if recent_dilution:
@@ -372,7 +396,7 @@ def update_covariance_from_old_covariance(self, state, covariance, dt: float, re
         jacobian = self._J_update_state_from_previous_state(state, dt)
         return jacobian @ covariance @ jacobian.T + Q
 
-    def update_observations_from_state(self, state_predictions):
+    def update_observations_from_state(self, state_predictions: FloatVectorLike) -> FloatVectorLike:
         """
         "h" in the literature, z_k = h(x_k).
 
@@ -388,7 +412,7 @@ def update_observations_from_state(self, state_predictions):
             obs[i] = od if (angle != "180") else np.exp(-(od - 1))
         return obs
 
-    def _J_update_state_from_previous_state(self, state, dt: float):
+    def _J_update_state_from_previous_state(self, state: FloatVectorLike, dt: float) -> FloatMatrixLike:
         """
         The prediction process is (encoded in update_state_from_previous_state)
 
@@ -410,7 +434,7 @@ def _J_update_state_from_previous_state(self, state, dt: float):
 
         J = np.zeros((2, 2))
 
-        od, rate = state
+        od, rate = np.asarray(state, dtype=float)
         J[0, 0] = np.exp(rate * dt)
         J[1, 1] = 1
 
@@ -419,9 +443,10 @@ def _J_update_state_from_previous_state(self, state, dt: float):
         return J
 
     @staticmethod
-    def _is_positive_definite(A) -> bool:
+    def _is_positive_definite(A: FloatMatrixLike) -> bool:
         import numpy as np
 
+        A = np.asarray(A, dtype=float)
         if np.array_equal(A, A.T):
             try:
                 return True

src/grpredict/__init__.pyi

@@ -0,0 +1,69 @@
+from collections.abc import Iterable, Sequence
+from typing import ClassVar, TypeAlias
+
+FloatVectorLike: TypeAlias = Iterable[float]
+FloatMatrixLike: TypeAlias = Iterable[Iterable[float]]
+
+
+class ExponentialMovingAverage:
+    value: float | None
+    alpha: float
+    def __init__(self, alpha: float) -> None: ...
+    def update(self, new_value: float) -> float: ...
+    def get_latest(self) -> float: ...
+    def clear(self) -> None: ...
+
+
+class ExponentialMovingStd:
+    value: float | None
+    alpha: float
+    ema: ExponentialMovingAverage
+    def __init__(
+        self,
+        alpha: float,
+        ema_alpha: float | None = None,
+        initial_std_value: float | None = None,
+        initial_mean_value: float | None = None,
+    ) -> None: ...
+    def update(self, new_value: float) -> float | None: ...
+    def get_latest(self) -> float: ...
+    def clear(self) -> None: ...
+
+
+class CultureGrowthEKF:
+    handle_outliers: ClassVar[bool]
+    process_noise_covariance: object
+    observation_noise_covariance: object
+    state_: object
+    covariance_: object
+    n_sensors: int
+    n_states: int
+    angles: Sequence[str]
+    outlier_std_threshold: float
+
+    def __init__(
+        self,
+        initial_state: FloatVectorLike,
+        initial_covariance: FloatMatrixLike,
+        process_noise_covariance: FloatMatrixLike,
+        observation_noise_covariance: FloatMatrixLike,
+        angles: Sequence[str],
+        outlier_std_threshold: float,
+    ) -> None: ...
+    def update(
+        self, obs: FloatVectorLike, dt: float, recent_dilution: bool = False
+    ) -> tuple[object, object]: ...
+    def update_observation_noise_cov(self, residual_state: FloatVectorLike) -> object: ...
+    def update_state_from_previous_state(self, state: FloatVectorLike, dt: float) -> object: ...
+    def _J_update_observations_from_state(self, state_prediction: FloatVectorLike) -> object: ...
+    def update_covariance_from_old_covariance(
+        self,
+        state: FloatVectorLike,
+        covariance: FloatMatrixLike,
+        dt: float,
+        recent_dilution: bool,
+    ) -> object: ...
+    def update_observations_from_state(self, state_predictions: FloatVectorLike) -> object: ...
+    def _J_update_state_from_previous_state(self, state: FloatVectorLike, dt: float) -> object: ...
+    @staticmethod
+    def _is_positive_definite(A: FloatMatrixLike) -> bool: ...