funcast 0.1.0__tar.gz

funcast-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  # Job 1: code quality (ruff and mypy)
+  # -----------------------------------
+  quality:
+    name: Code Quality
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout du code
+        uses: actions/checkout@v4
+
+      - name: Installation de Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Installation des dépendances
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Ruff — vérification du linting
+        run: ruff check src/ tests/
+
+      - name: Ruff — vérification du formatage
+        run: ruff format --check src/ tests/
+
+      - name: Mypy — vérification des types
+        run: mypy src/funcast/
+
+  # Job 2: Tests on Python 3.10, 3.11 and 3.12
+  # ------------------------------------------
+  tests:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Checkout du code
+        uses: actions/checkout@v4
+
+      - name: Installation de Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Installation des dépendances
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lancement des tests avec pytest
+        run: pytest
+
+      - name: Upload du rapport de couverture
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: .coverage

funcast-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+venv/
+.venv/
+env/
+.env/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+examples/*.png
+.ipynb_checkpoints/
+docs/build/
+docs/source/api/_autosummary/

funcast-0.1.0/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.

funcast-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,32 @@
+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/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

funcast-0.1.0/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

funcast-0.1.0/docs/source/api/basis.rst

@@ -0,0 +1,7 @@
+funcast.basis
+=============
+
+.. automodule:: funcast.basis
+   :members:
+   :undoc-members:
+   :show-inheritance:

funcast-0.1.0/docs/source/api/funcast.rst

@@ -0,0 +1,7 @@
+funcast.model
+=============
+
+.. autoclass:: funcast.FunCast
+   :members:
+   :undoc-members:
+   :show-inheritance:

funcast-0.1.0/docs/source/api/selection.rst

@@ -0,0 +1,7 @@
+funcast.selection
+=================
+
+.. automodule:: funcast.selection
+   :members:
+   :undoc-members:
+   :show-inheritance:

funcast-0.1.0/docs/source/changelog.md

@@ -0,0 +1,4 @@
+# Changelog
+
+```{include} ../../CHANGELOG.md
+```

funcast-0.1.0/docs/source/conf.py

@@ -0,0 +1,73 @@
+"""
+Sphinx configuration for FunCast documentation.
+"""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../../src"))
+
+project   = "FunCast"
+copyright = "2025, Sezgin"
+author    = "Sezgin"
+release   = "0.1.0"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "sphinx_autodoc_typehints",
+     "sphinx.ext.mathjax",
+    "myst_parser",
+]
+
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": False,
+    "private-members": False,
+    "show-inheritance": True,
+    "member-order": "bysource",
+}
+
+autosummary_generate = True
+
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_use_param = True
+napoleon_use_rtype = True
+
+typehints_fully_qualified = False
+always_document_param_types = True
+typehints_document_rtype = True
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy":  ("https://numpy.org/doc/stable", None),
+    "scipy":  ("https://docs.scipy.org/doc/scipy", None),
+    "sklearn": ("https://scikit-learn.org/stable", None),
+}
+
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+]
+
+html_theme = "sphinx_rtd_theme"
+
+html_theme_options = {
+    "navigation_depth":    4,
+    "collapse_navigation": False,
+    "sticky_navigation":   True,
+    "includehidden":       True,
+    "titles_only":         False,
+}
+
+html_static_path = ["_static"]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md":  "markdown",
+}

funcast-0.1.0/docs/source/contributing.md

@@ -0,0 +1,33 @@
+# Contributing
+
+## Development setup
+
+```bash
+git clone https://github.com/ton-username/funcast.git
+cd funcast
+pip install -e ".[dev,docs]"
+pre-commit install
+```
+
+## Running tests
+
+```bash
+pytest
+```
+
+## Building the documentation locally
+
+```bash
+cd docs
+make html
+```
+
+The documentation is then available at `docs/build/html/index.html`.
+
+## Submitting a pull request
+
+1. Fork the repository
+2. Create a feature branch : `git checkout -b feat/my-feature`
+3. Commit your changes : `git commit -m "feat: my feature"`
+4. Push : `git push origin feat/my-feature`
+5. Open a pull request on GitHub

funcast-0.1.0/docs/source/index.rst

@@ -0,0 +1,35 @@
+FunCast Documentation
+=====================
+
+**FunCast** is a Python package implementing the functional data forecasting
+model with covariates introduced in Sezgin et al. (2025).
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting Started
+
+   installation
+   quickstart
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User Guide
+
+   userguide/model
+   userguide/basis
+   userguide/selection
+
+.. toctree::
+   :maxdepth: 2
+   :caption: API Reference
+
+   api/funcast
+   api/basis
+   api/selection
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Development
+
+   changelog
+   contributing

funcast-0.1.0/docs/source/installation.md

@@ -0,0 +1,21 @@
+# Installation
+
+## Stable release
+
+```
+pip install funcast
+```
+
+## Development version
+```
+git clone https://github.com/SelmanSzgn/funcast.git
+cd funcast
+pip install -e ".[dev]"
+```
+
+## Dependencies
+
+Python >= 3.10\
+numpy >= 1.24\
+scipy >= 1.10\
+scikit-learn >= 1.3

funcast-0.1.0/docs/source/quickstart.md

@@ -0,0 +1,36 @@
+# Quick start
+
+## Simple example
+
+```python
+import numpy as np
+from funcast import FunCast
+
+# Timestamps
+t_past   = np.linspace(0, 1, 100)
+t_future = np.linspace(1, 1.25, 25)
+
+# Synthetic data
+rng = np.random.default_rng(42)
+n = 50
+Y_past = np.sin(2 * np.pi * t_past)   + 0.1 * rng.standard_normal((n, 100))
+Y_future = np.sin(2 * np.pi * t_future) + 0.1 * rng.standard_normal((n, 25))
+
+# Training
+model = FunCast(K=8, s=0.8)
+model.fit(Y_past, Y_future, t_past, t_future)
+
+# Prediction
+Y_pred = model.predict(Y_past)
+print(f"RMSE : {model.score(Y_past, Y_future):.4f}")
+```
+
+## Choosing the basis
+
+```python
+# B-spline (default)
+model_bs = FunCast(K=8, s=0.5, basis_type="bspline")
+
+# Fourier
+model_fo = FunCast(K=8, s=0.5, basis_type="fourier")
+```

funcast-0.1.0/docs/source/userguide/basis.md

@@ -0,0 +1,69 @@
+# Functional Bases
+
+## Overview
+
+FunCast represents functional data as linear combinations of basis
+functions. Two families are available :
+
+- **B-spline** : well suited for non-periodic signals
+- **Fourier**  : well suited for periodic signals
+
+## B-spline basis
+
+A B-spline basis of degree $d$ with $h$ functions is built from a
+knot sequence uniformly distributed over $[0, T]$.
+
+**Key properties :**
+
+- Local support : each function is non-zero only on a small interval
+- Partition of unity : the functions sum to 1 at every point
+- Smooth : $d-1$ times continuously differentiable
+
+```python
+from funcast.basis import bspline_basis
+import numpy as np
+
+t = np.linspace(0, 1, 100)
+B = bspline_basis(t, n_basis=8, degree=3)
+print(B.shape)   # (100, 8)
+```
+
+## Fourier basis
+
+A Fourier basis with $h$ functions is built from cosine and sine
+harmonics of increasing frequency.
+
+**Key properties :**
+
+- Global support : each function is non-zero everywhere
+- Orthogonal : the functions are orthogonal on $[0, T]$
+- Periodic : well adapted to seasonal or cyclic signals
+
+```python
+from funcast.basis import fourier_basis
+import numpy as np
+
+t = np.linspace(0, 1, 100)
+B = fourier_basis(t, n_basis=7)
+print(B.shape)   # (100, 7)
+```
+
+## Choosing the right basis
+
+| Situation | Recommended basis |
+|---|---|
+| Signal with trend, no periodicity | B-spline |
+| Seasonal or cyclic signal | Fourier |
+| Unknown structure | B-spline (default) |
+| Sharp local variations | B-spline |
+
+## Using `get_basis`
+
+The `get_basis` function is the recommended entry point :
+
+```python
+from funcast.basis import get_basis
+
+B_bs = get_basis(t, n_basis=8, basis_type="bspline")
+B_fo = get_basis(t, n_basis=8, basis_type="fourier")
+```

funcast-0.1.0/docs/source/userguide/model.md

@@ -0,0 +1,63 @@
+# The FunCast Model
+
+## Overview
+
+FunCast forecasts the future trajectory of a functional process $Y$
+over $[T, T+H]$ given its past trajectory over $[0, T]$ and optional
+covariates $X_1, \ldots, X_p$.
+
+## Four-step procedure
+
+### Step 1 — Choose K
+
+$K$ controls the richness of the future representation.
+A larger $K$ allows more complex future shapes but increases
+the risk of overfitting.
+
+**Recommended range** : $K \in [4, 15]$
+
+### Step 2 — Select $h_\ell$ via RRSS
+
+For each covariate (including $Y$ itself), $h_\ell$ is the number
+of basis functions used to represent it. It is selected automatically
+by minimizing the Regularized Residual Sum of Squares (RRSS, Eq. 10).
+
+### Step 3 — Compute $q_\ell$
+
+The smoothing parameter $q_\ell$ controls the resolution of the
+inner-product matrices :
+
+$$q_\ell = \max(\text{degree}+1, \lfloor (1-s) \cdot h_\ell \rceil)$$
+
+- $s = 0$ : no smoothing ($q_\ell = h_\ell$)
+- $s = 1$ : maximum smoothing ($q_\ell = \text{degree}+1$)
+
+### Step 4 — Solve the OLS problem
+
+The coefficient vector $\hat{\beta}$ is estimated by ordinary
+least squares.
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `K` | int | 10 | Number of basis functions ψ for future Y |
+| `s` | float | 0.5 | Smoothing coefficient ∈ [0, 1] |
+| `basis_type` | str | `'bspline'` | Basis type |
+| `auto_h` | bool | `True` | Auto-select hℓ via RRSS |
+| `h_list` | list | `None` | Manual hℓ values |
+| `degree` | int | 3 | B-spline degree |
+| `rcond` | float | `None` | Pseudo-inverse threshold |
+
+## Fitted attributes
+
+After calling `fit()`, the following attributes are available :
+
+| Attribute | Description |
+|---|---|
+| `h_values_` | Selected $h_\ell$ for each covariate |
+| `q_values_` | Computed $q_\ell$ for each covariate |
+| `b_hat_` | Estimated coefficient vector $\hat{\beta}$ |
+| `C_list_` | Projection coefficients for each covariate |
+| `J_list_` | Inner-product matrices |
+| `theta_list_` | Basis matrices for each covariate |