funcast 0.1.0__py3-none-any.whl

funcast/__init__.py

@@ -0,0 +1,19 @@
+"""
+FunCast — Prévision fonctionnelle avec covariates.
+
+Référence : Sezgin et al. (2025), "FunCast: a forecasting model for
+functional data using covariates", Statistics and Computing.
+"""
+
+from funcast.basis import bspline_basis, fourier_basis, get_basis
+from funcast.model import FunCast
+from funcast.selection import select_h_rrss
+
+__version__ = "0.1.0"
+__all__ = [
+    "FunCast",
+    "get_basis",
+    "bspline_basis",
+    "fourier_basis",
+    "select_h_rrss",
+]

funcast/basis.py

@@ -0,0 +1,102 @@
+"""
+Functional basis for FunCast.
+"""
+
+import numpy as np
+from scipy.interpolate import BSpline
+
+
+def bspline_basis(t: np.ndarray, n_basis: int, degree: int = 3) -> np.ndarray:
+    """
+    Create a cubic B-spline basis matrix.
+
+    Parameters
+    ----------
+    t : np.ndarray
+        Evaluation points.
+    n_basis : int
+        Number of basis functions.
+    degree : int
+        Spline degrees. Default is 3.
+
+    Returns
+    -------
+    B : np.ndarray
+        Basis matrix.
+    """
+    n_basis = max(n_basis, degree + 1)
+
+    t_min, t_max = t.min(), t.max()
+    n_inner = n_basis - degree - 1
+
+    if n_inner > 0:
+        inner_knots = np.linspace(t_min, t_max, n_inner + 2)[1:-1]
+    else:
+        inner_knots = np.array([])
+
+    knots = np.concatenate(
+        [np.repeat(t_min, degree + 1), inner_knots, np.repeat(t_max, degree + 1)]
+    )
+
+    B = np.zeros((len(t), n_basis))
+    for j in range(n_basis):
+        coef = np.zeros(n_basis)
+        coef[j] = 1.0
+        spl = BSpline(knots, coef, degree)
+        B[:, j] = spl(t)
+    return B
+
+
+def fourier_basis(t: np.ndarray, n_basis: int) -> np.ndarray:
+    """
+    Create a Fourier basis.
+
+    Parameters
+    ----------
+    t : np.ndarray
+        Evaluation points.
+    n_basis : int
+        Number of basis functions.
+
+    Returns
+    -------
+    B : np.ndarray
+        Basis matrix.
+    """
+    T = t.max() - t.min()
+    B = np.ones((len(t), n_basis))
+    for k in range(1, n_basis):
+        freq = (k + 1) // 2
+        if k % 2 == 1:
+            B[:, k] = np.cos(2 * np.pi * freq * t / T)
+        else:
+            B[:, k] = np.sin(2 * np.pi * freq * t / T)
+    return B
+
+
+def get_basis(t: np.ndarray, n_basis: int, basis_type: str = "bspline") -> np.ndarray:
+    """
+    Create a basis of functions.
+
+    Parameters
+    ----------
+    t : np.ndarray
+        Evaluation points.
+    n_basis : int
+        Number of basis functions.
+    basis_type : str
+        Type of function basis, "bspline" or "fourier". Default is "bspline".
+
+    Returns
+    -------
+    B : np.ndarray
+        Basis matrix.
+    """
+    if basis_type == "bspline":
+        return bspline_basis(t, n_basis)
+    elif basis_type == "fourier":
+        return fourier_basis(t, n_basis)
+    else:
+        raise ValueError(
+            f"unknown basis_type : '{basis_type}'. Choose 'bspline' or 'fourier'."
+        )

funcast/model.py

@@ -0,0 +1,347 @@
+"""
+FunCast model implementation.
+"""
+
+import numpy as np
+from scipy.linalg import lstsq
+from sklearn.base import BaseEstimator
+
+from funcast.basis import get_basis
+from funcast.selection import select_h_rrss
+
+if hasattr(np, "trapezoid"):
+    _trapezoid = np.trapezoid  # type: ignore[attr-defined]
+else:
+    _trapezoid = np.trapz  # type: ignore[attr-defined]
+
+
+class FunCast(BaseEstimator):
+    """
+    FunCast model.
+
+    Parameters
+    ----------
+    K : int, optionnal
+        Number of basis functions for the future of Y. Default is 10.
+    s : float, optionnal
+        Smoothing coefficient. Default is 0.5.
+    basis_type : str
+        Type of function basis, "bspline" or "fourier". Default is "bspline".
+    auto_h : bool, optionnal
+        If True, h_l is optimized with RRSS. Default is True.
+    h_list : list, optionnal
+        Values of h_l if auto_h is False. Default is None.
+    degree : int, optionnal
+        B-splines degree. Default is 3.
+    rcond : float or None, optionnal
+        Pseudo-inverse threshold. Default is None.
+    """
+
+    def __init__(
+        self,
+        K: int = 10,
+        s: float = 0.5,
+        basis_type: str = "bspline",
+        auto_h: bool = True,
+        h_list: list[int] | None = None,
+        degree: int = 3,
+        rcond: float | None = None,
+    ):
+        self.K = K
+        self.s = s
+        self.basis_type = basis_type
+        self.auto_h = auto_h
+        self.h_list = h_list
+        self.degree = degree
+        self.rcond = rcond
+
+    def _compute_h(
+        self,
+        covariates_past: list[np.ndarray],
+        t_past: np.ndarray,
+    ) -> list[int]:
+        """
+        Compute h_l for each covariate.
+
+        Parameters
+        ----------
+        covariates_past : list of array-like
+            Past of covariates.
+        t_past : array-like
+            Past timestamps.
+
+        Returns
+        -------
+        h_values : list
+            Values of h_l.
+        """
+        h_values = []
+        for ell, X in enumerate(covariates_past):
+            if self.auto_h:
+                h = select_h_rrss(
+                    X,
+                    t_past,
+                    basis_type=self.basis_type,
+                    degree=self.degree,
+                )
+            else:
+                if self.h_list is None or len(self.h_list) <= ell:
+                    raise ValueError(
+                        "h_list required and of length p+1 if auto_h=False."
+                    )
+                h = max(self.h_list[ell], self.degree + 1)
+            h_values.append(h)
+        return h_values
+
+    def _compute_q(self, h_values: list[int]) -> list[int]:
+        """
+        Compute q_l.
+
+        Parameters
+        ----------
+        h_values : list
+            Values of h_l.
+
+        Returns
+        -------
+        list
+            Values of q_l.
+        """
+        min_q = self.degree + 1
+        return [max(min_q, round((1 - self.s) * h)) for h in h_values]
+
+    def _project_covariates(
+        self,
+        covariates_past: list[np.ndarray],
+        t_past: np.ndarray,
+        h_values: list[int],
+    ) -> tuple[list[np.ndarray], list[np.ndarray]]:
+        """
+        Project each covariate on theta basis.
+
+        Parameters
+        ----------
+        covariates_past : list of array-like
+            Past of covariates.
+        t_past : array-like
+            Past timestamps.
+        h_values : list
+            Values of h_l.
+
+        Returns
+        -------
+        tuple
+            Expansion coefficients of the covariates.
+        """
+        C_list, theta_list = [], []
+        for X, h in zip(covariates_past, h_values):
+            theta = get_basis(t_past, h, self.basis_type)
+            thetaT_theta = theta.T @ theta
+            C, _, _, _ = lstsq(thetaT_theta, (X @ theta).T, cond=self.rcond)
+            C_list.append(C.T)
+            theta_list.append(theta)
+        return C_list, theta_list
+
+    def _compute_J_matrices(
+        self,
+        theta_list: list[np.ndarray],
+        t_past: np.ndarray,
+        q_values: list[int],
+    ) -> list[np.ndarray]:
+        """
+        Compute the inner product matrix.
+
+        Parameters
+        ----------
+        theta_list : list of array-like
+            Basis for covariates.
+        t_past : array-like
+            Past timestamps.
+        q_values : list
+            Values of q_l.
+
+        Returns
+        -------
+        J_list : list
+            Inner product matrix.
+        """
+        J_list = []
+        for theta, q_ell in zip(theta_list, q_values):
+            B_ell = get_basis(t_past, q_ell, self.basis_type)
+            integrand = theta[:, :, np.newaxis] * B_ell[:, np.newaxis, :]
+            J = _trapezoid(integrand, x=t_past, axis=0)
+            J_list.append(np.asarray(J))
+        return J_list
+
+    def _build_design_matrix(
+        self,
+        C_list: list[np.ndarray],
+        J_list: list[np.ndarray],
+        t_future: np.ndarray,
+        q_values: list[int],
+    ) -> np.ndarray:
+        """
+        Build the design matrix.
+
+        Parameters
+        ----------
+        C_list : list of array-like
+            Expansion coefficients of the covariates.
+        J_list : list
+            Inner product matrix.
+        t_future : array-like
+            Future timestamps.
+        q_values : list
+            Values of q_l.
+
+        Returns
+        -------
+        X_design : array-like
+            Design matrix.
+        """
+        n = C_list[0].shape[0]
+        m2 = len(t_future)
+        K = self.K
+        q_total = sum(q_values)
+        psi = get_basis(t_future, K, self.basis_type)
+        C_full = np.concatenate(C_list, axis=1)
+        X_design = np.zeros((n * m2, K * q_total))
+        for j, t_j in enumerate(t_future):
+            psi_t = psi[j, :]
+            xi_parts = []
+            for ell, (J, q_ell) in enumerate(zip(J_list, q_values)):
+                h_ell = J.shape[0]
+                c_start = sum(C_list[e].shape[1] for e in range(ell))
+                c_end = c_start + h_ell
+                c_i_ell = C_full[:, c_start:c_end]
+                cJ = c_i_ell @ J
+                block = np.einsum("k,nq->nkq", psi_t, cJ).reshape(n, K * q_ell)
+                xi_parts.append(block)
+            xi_j = np.concatenate(xi_parts, axis=1)
+            X_design[j::m2, :] = xi_j
+        return X_design
+
+    def fit(
+        self,
+        Y_past: np.ndarray,
+        Y_future: np.ndarray,
+        t_past: np.ndarray,
+        t_future: np.ndarray,
+        covariates_past: list[np.ndarray] | None = None,
+    ) -> "FunCast":
+        """
+        Fit FunCast.
+
+        Parameters
+        ----------
+        Y_past : array-like
+            Past of Y.
+        Y_future : array-like
+            Future of Y.
+        t_past : array-like
+            Past timestamps.
+        t_future : array-like
+            Future timestamps.
+        covariates_past : list of array-like
+            Past of covariates.
+
+        Returns
+        -------
+        self
+        """
+        all_covariates = [Y_past] + (covariates_past or [])
+
+        self.h_values_ = self._compute_h(all_covariates, t_past)
+        self.q_values_ = self._compute_q(self.h_values_)
+        self.C_list_, self.theta_list_ = self._project_covariates(
+            all_covariates, t_past, self.h_values_
+        )
+        self.J_list_ = self._compute_J_matrices(
+            self.theta_list_, t_past, self.q_values_
+        )
+
+        X_design = self._build_design_matrix(
+            self.C_list_, self.J_list_, t_future, self.q_values_
+        )
+        y = Y_future.ravel()
+        self.b_hat_, _, _, _ = lstsq(X_design, y, cond=self.rcond)
+
+        self.t_past_ = t_past
+        self.t_future_ = t_future
+        self.m2_ = Y_future.shape[1]
+        self.n_covariates_ = len(all_covariates)
+
+        return self
+
+    def predict(
+        self,
+        Y_past_new: np.ndarray,
+        covariates_past_new: list[np.ndarray] | None = None,
+    ) -> np.ndarray:
+        """
+        Predict the future of Y.
+
+        Parameters
+        ----------
+        Y_past_new : array-like
+            Past of Y for inference.
+        covariates_past_new : list of array-like
+            Past of covariates for inference.
+
+        Returns
+        -------
+        Y_pred : array-like
+            Prediction of Y.
+        """
+        all_new = [Y_past_new] + (covariates_past_new or [])
+
+        C_new_list = []
+        for X_new, theta, h in zip(all_new, self.theta_list_, self.h_values_):
+            thetaT_theta = theta.T @ theta
+            C_new, _, _, _ = lstsq(thetaT_theta, (X_new @ theta).T, cond=self.rcond)
+            C_new_list.append(np.asarray(C_new).T)  # ← np.asarray() clarifie le type
+
+        X_new_design = self._build_design_matrix(
+            C_new_list, self.J_list_, self.t_future_, self.q_values_
+        )
+
+        n_new = Y_past_new.shape[0]
+        y_pred = X_new_design @ self.b_hat_
+        return np.asarray(y_pred).reshape(n_new, self.m2_)
+
+    def score(
+        self,
+        Y_past: np.ndarray,
+        Y_future: np.ndarray,
+        covariates_past: list[np.ndarray] | None = None,
+        metric: str = "rmse",
+    ) -> float:
+        """
+        Compute RMSE and SMAPE.
+
+        Parameters
+        ----------
+        Y_past : array-like
+            Past of Y.
+        Y_future : array-like
+            Future of Y.
+        covariates_past : list of array-like or None, optionnal
+            Past of covariates. Default is None.
+        metric : string, optionnal
+            Evaluation metric, "rmse" or "smape". Default is "rmse".
+
+        Returns
+        -------
+        float
+            Metric value.
+        """
+        Y_pred = self.predict(Y_past, covariates_past)
+
+        if metric == "rmse":
+            return float(np.sqrt(np.mean((Y_future - Y_pred) ** 2)))
+        elif metric == "smape":
+            denom = np.abs(Y_future) + np.abs(Y_pred)
+            denom = np.where(denom == 0, 1e-8, denom)
+            return float(100 * np.mean(np.abs(Y_future - Y_pred) / denom))
+        else:
+            raise ValueError(f"metric inconnu : '{metric}'. Choisir 'rmse' ou 'smape'.")

funcast/selection.py

@@ -0,0 +1,73 @@
+"""
+Automatic selection of h_l with RRSS criterion.
+"""
+
+import warnings
+
+import numpy as np
+from scipy.linalg import lstsq
+
+from funcast.basis import get_basis
+
+
+def select_h_rrss(
+    X: np.ndarray,
+    t: np.ndarray,
+    h_candidates: list[int] | None = None,
+    basis_type: str = "bspline",
+    degree: int = 3,
+) -> int:
+    """
+    Selects h_l with RRSS criterion.
+
+    Parameters
+    ----------
+    X : array-like
+        Covariate realization.
+    t : array-like
+        Temporal grid.
+    h_candidates : list or None, optionnal
+        Candidates for h_l values. Default is None.
+    basis_type : str
+        Type of function basis. Default is "bspline"
+    degree : int
+        Spline degrees. Default is 3.
+
+    Returns
+    -------
+    h_opt : int
+        h_l value that minimizes RRSS.
+    """
+    n, m1 = X.shape
+    min_h = degree + 1
+
+    if h_candidates is None:
+        max_h = max(min_h + 1, min(m1 // 2, 30))
+        h_candidates = list(range(min_h, max_h + 1))
+    else:
+        h_candidates = [h for h in h_candidates if h >= min_h]
+
+    if not h_candidates:
+        warnings.warn(f"No valid candidate for h_l. Set h={min_h}.")
+        return min_h
+
+    best_h, best_rrss = h_candidates[0], np.inf
+
+    for h in h_candidates:
+        denom = m1 - h
+        if denom <= 0:
+            continue
+        try:
+            theta = get_basis(t, h, basis_type)
+            thetaT_theta = theta.T @ theta
+            C, _, _, _ = lstsq(thetaT_theta, (X @ theta).T)
+            X_hat = (theta @ C).T
+            residuals = X - X_hat
+            rrss = np.sqrt(np.sum(residuals**2) / (n * denom))
+            if rrss < best_rrss:
+                best_rrss = rrss
+                best_h = h
+        except np.linalg.LinAlgError:
+            continue
+
+    return best_h

funcast-0.1.0.dist-info/METADATA

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: funcast
+Version: 0.1.0
+Summary: Functional data forecasting with covariates (FunCast model)
+Project-URL: Homepage, https://github.com/SelmanSzgn/funcast
+Project-URL: Repository, https://github.com/SelmanSzgn/funcast
+Project-URL: Documentation, https://funcast.readthedocs.io
+Project-URL: Bug Tracker, https://github.com/SelmanSzgn/funcast/issues
+Author-email: Selman Sezgin <selman.szg@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Selman Sezgin
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+License-File: LICENSE
+Keywords: B-spline,forecasting,functional data analysis,statistics,time series
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: scipy>=1.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: myst-parser>=2.0; extra == 'docs'
+Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'docs'
+Requires-Dist: sphinx>=7.0; extra == 'docs'
+Provides-Extra: examples
+Requires-Dist: jupyter>=1.0; extra == 'examples'
+Requires-Dist: matplotlib>=3.7; extra == 'examples'
+Description-Content-Type: text/markdown
+
+Python implementation of the FunCast functional data forecasting model.
+
+## Paper reference
+
+Sezgin et al. (2025), *"Funcast: a forecasting model for functional data using covariates"*, under review at Journal of Statistical Planning and Inference (JSPI).
+
+Authors : Selman Sezgin (a, b), Julien Jacques (a), Kahina Mokrani (b) and Sylvain Allio (b)
+
+(a) ERIC, Université Lumière Lyon 2, Lyon, France
+
+(b) Orange Research, Belfort, France
+
+## Installation
+``
+pip install funcast
+``
+
+## Quick start
+```
+import numpy as np
+from funcast import FunCast
+
+n, m1, m2 = 50, 100, 20
+t_past   = np.linspace(0, 1, m1)
+t_future = np.linspace(1, 1.2, m2)
+Y_past   = np.random.randn(n, m1)
+Y_future = np.random.randn(n, m2)
+
+model = FunCast(K=8, s=0.5)
+model.fit(Y_past, Y_future, t_past, t_future)
+Y_pred = model.predict(Y_past)
+```

funcast-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+funcast/__init__.py,sha256=yieC42oHrighMK0HsqFAoZ5_cwHemzVeDyR1_7bz6Ds,490
+funcast/basis.py,sha256=7Dt4n4h64eC82uIBg3MrBWhTSDRiIokMMHD79WW5obA,2446
+funcast/model.py,sha256=cC8hNRiW-I0YdL_3NoFP3oUujjx_2bpUP_PQ5SCPk8o,10421
+funcast/selection.py,sha256=oATDIddwwRnosfEYOBIpD9BLq1U8WjZ5BYtQuqVi9EQ,1854
+funcast-0.1.0.dist-info/METADATA,sha256=w7a3Iknx8DRxfTTd7MIktskT_YxIxwG9mjYvUGAPv6w,3667
+funcast-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+funcast-0.1.0.dist-info/licenses/LICENSE,sha256=y_187Ur1UaN3ShFLycik_BY8GE_uTgR4HzuhfYBmImM,1077
+funcast-0.1.0.dist-info/RECORD,,

funcast-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

funcast-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 Selman Sezgin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.