edrft 0.1.0__tar.gz

edrft-0.1.0/CITATION.cff

@@ -0,0 +1,25 @@
+cff-version: 1.2.0
+message: "If you use edRFT in academic work, please cite this software and the associated article."
+title: "edRFT"
+version: "0.1.0"
+date-released: "2026-06-25"
+authors:
+  - family-names: "Bhambu"
+    given-names: "Aryan"
+license: "MIT"
+repository-code: "https://github.com/statsdl/edRFT"
+preferred-citation:
+  type: article
+  title: "Deep random vector functional link transformer network with multiple output layers for significant wave height forecasting"
+  authors:
+    - family-names: "Bhambu"
+      given-names: "Aryan"
+    - family-names: "Gao"
+      given-names: "Ruobin"
+    - family-names: "Suganthan"
+      given-names: "Ponnuthurai Nagaratnam"
+    - family-names: "Natarajan"
+      given-names: "Selvaraju"
+  journal: "Applied Soft Computing"
+  year: 2025
+  start: "114136"

edrft-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aryan Bhambu
+
+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.

edrft-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include CITATION.cff
+include requirements.txt
+recursive-include examples *.py
+recursive-include docs *.rst

edrft-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: edrft
+Version: 0.1.0
+Summary: RFT and edRFT models for significant wave-height time-series forecasting.
+Author: Aryan Bhambu
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/statsdl/edRFT
+Project-URL: Issues, https://github.com/statsdl/edRFT/issues
+Keywords: edrft,rft,rvfl,transformer,wave-height,forecasting
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: torch>=2.0
+Provides-Extra: tuning
+Requires-Dist: hyperopt>=0.2.7; extra == "tuning"
+Requires-Dist: setuptools<81; extra == "tuning"
+Provides-Extra: wave
+Requires-Dist: hyperopt>=0.2.7; extra == "wave"
+Requires-Dist: pandas>=1.3; extra == "wave"
+Requires-Dist: setuptools<81; extra == "wave"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: hyperopt>=0.2.7; extra == "dev"
+Requires-Dist: pandas>=1.3; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: setuptools<81; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# edRFT
+
+`edrft` provides Random Vector Functional Link Transformer models for
+significant wave-height forecasting:
+
+- `RFTRegressor`: a shallow randomized transformer encoder with ridge readout.
+- `EDRFTRegressor`: an ensemble deep RFT with one output layer per hidden layer.
+- Hyperopt/TPE tuning using the default edRFT search ranges.
+- NDBC wave forecasting experiment helpers that do not write result artifacts.
+
+The public package uses the model naming: `RFT` and `edRFT`. Older `rft` and
+`edrft` script names are retained only under legacy files for traceability.
+
+## Installation
+
+Core install:
+
+```bash
+git clone https://github.com/statsdl/edRFT.git
+cd edRFT
+pip install .
+```
+
+Wave experiment dependencies:
+
+```bash
+pip install ".[wave]"
+```
+
+Development:
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from edrft import EDRFTRegressor, make_forecasting_frame
+
+series = np.sin(np.linspace(0, 16, 240))
+X, y = make_forecasting_frame(series, order=4)
+
+model = EDRFTRegressor(n_layers=3, n_hidden=32, random_state=0)
+model.fit(X[:180], y[:180])
+pred = model.predict(X[180:])
+```
+
+## Wave Forecasting Example
+
+```bash
+python examples/run_wave_forecasting.py \
+  --data-dir wave \
+  --stations 46001h \
+  --years 2017 \
+  --seeds 0 \
+  --look-back 48 \
+  --horizon 4 \
+  --layers 10 \
+  --max-evals 100
+```
+
+The runner prints metrics to stdout only. It follows the original scripts:
+
+- NDBC features: `WDIR`, `WSPD`, `GST`, `APD`, `WVHT`
+- Missing sentinel cleanup
+- Default look-back window: 48
+- Default forecasting horizon: 4
+- Min-max scaling to `[-1, 1]`
+- Chronological split: 70% train, 10% validation, 20% test
+- Hyperopt/TPE tuning with 100 evaluations by default
+- Train+validation final fit
+- RMSE, MAPE, MASE, and timing output
+
+## Hyperopt Tuning
+
+```python
+from edrft.tuning import layerwise_tune_edrft
+
+result = layerwise_tune_edrft(
+    X,
+    y,
+    n_layers=10,
+    validation_fraction=0.1 / 0.8,
+    max_evals=100,
+    random_state=0,
+)
+```
+
+## Repository Notes
+
+Supported package code lives in `src/edrft`.
+
+The `legacy/`, `DeepRVFL_/`, `ForecastLib.py`, and old experiment scripts are
+retained for traceability. They are not included in the PyPI wheel and are not
+the supported package API.
+
+## PyPI Release
+
+The publish workflow uses PyPI Trusted Publishing. Configure the PyPI trusted
+publisher with:
+
+- owner: `statsdl`
+- repository: `edRFT`
+- workflow: `publish.yml`
+- environment: `pypi`
+
+## License
+
+MIT
+
+## Reference
+
+If you use edRFT in your work, please cite:
+
+```bibtex
+@article{bhambu2025deep,
+  title={Deep random vector functional link transformer network with multiple output layers for significant wave height forecasting},
+  author={Bhambu, Aryan and Gao, Ruobin and Suganthan, Ponnuthurai Nagaratnam and Selvaraju, Natarajan},
+  journal={Applied Soft Computing},
+  pages={114136},
+  year={2025},
+  publisher={Elsevier}
+}
+```
+

edrft-0.1.0/README.md

@@ -0,0 +1,128 @@
+# edRFT
+
+`edrft` provides Random Vector Functional Link Transformer models for
+significant wave-height forecasting:
+
+- `RFTRegressor`: a shallow randomized transformer encoder with ridge readout.
+- `EDRFTRegressor`: an ensemble deep RFT with one output layer per hidden layer.
+- Hyperopt/TPE tuning using the default edRFT search ranges.
+- NDBC wave forecasting experiment helpers that do not write result artifacts.
+
+The public package uses the model naming: `RFT` and `edRFT`. Older `rft` and
+`edrft` script names are retained only under legacy files for traceability.
+
+## Installation
+
+Core install:
+
+```bash
+git clone https://github.com/statsdl/edRFT.git
+cd edRFT
+pip install .
+```
+
+Wave experiment dependencies:
+
+```bash
+pip install ".[wave]"
+```
+
+Development:
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from edrft import EDRFTRegressor, make_forecasting_frame
+
+series = np.sin(np.linspace(0, 16, 240))
+X, y = make_forecasting_frame(series, order=4)
+
+model = EDRFTRegressor(n_layers=3, n_hidden=32, random_state=0)
+model.fit(X[:180], y[:180])
+pred = model.predict(X[180:])
+```
+
+## Wave Forecasting Example
+
+```bash
+python examples/run_wave_forecasting.py \
+  --data-dir wave \
+  --stations 46001h \
+  --years 2017 \
+  --seeds 0 \
+  --look-back 48 \
+  --horizon 4 \
+  --layers 10 \
+  --max-evals 100
+```
+
+The runner prints metrics to stdout only. It follows the original scripts:
+
+- NDBC features: `WDIR`, `WSPD`, `GST`, `APD`, `WVHT`
+- Missing sentinel cleanup
+- Default look-back window: 48
+- Default forecasting horizon: 4
+- Min-max scaling to `[-1, 1]`
+- Chronological split: 70% train, 10% validation, 20% test
+- Hyperopt/TPE tuning with 100 evaluations by default
+- Train+validation final fit
+- RMSE, MAPE, MASE, and timing output
+
+## Hyperopt Tuning
+
+```python
+from edrft.tuning import layerwise_tune_edrft
+
+result = layerwise_tune_edrft(
+    X,
+    y,
+    n_layers=10,
+    validation_fraction=0.1 / 0.8,
+    max_evals=100,
+    random_state=0,
+)
+```
+
+## Repository Notes
+
+Supported package code lives in `src/edrft`.
+
+The `legacy/`, `DeepRVFL_/`, `ForecastLib.py`, and old experiment scripts are
+retained for traceability. They are not included in the PyPI wheel and are not
+the supported package API.
+
+## PyPI Release
+
+The publish workflow uses PyPI Trusted Publishing. Configure the PyPI trusted
+publisher with:
+
+- owner: `statsdl`
+- repository: `edRFT`
+- workflow: `publish.yml`
+- environment: `pypi`
+
+## License
+
+MIT
+
+## Reference
+
+If you use edRFT in your work, please cite:
+
+```bibtex
+@article{bhambu2025deep,
+  title={Deep random vector functional link transformer network with multiple output layers for significant wave height forecasting},
+  author={Bhambu, Aryan and Gao, Ruobin and Suganthan, Ponnuthurai Nagaratnam and Selvaraju, Natarajan},
+  journal={Applied Soft Computing},
+  pages={114136},
+  year={2025},
+  publisher={Elsevier}
+}
+```
+

edrft-0.1.0/docs/index.rst

@@ -0,0 +1,18 @@
+edRFT
+=====
+
+``edrft`` provides RFT and edRFT regressors for significant wave-height
+forecasting.
+
+Installation
+------------
+
+.. code-block:: bash
+
+   pip install edrft
+
+Optional wave experiment dependencies:
+
+.. code-block:: bash
+
+   pip install "edrft[wave]"

edrft-0.1.0/examples/run_wave_forecasting.py

@@ -0,0 +1,48 @@
+import argparse
+
+from edrft.wave import run_wave_experiment
+
+
+def parse_csv(value):
+    return tuple(item.strip() for item in value.split(",") if item.strip())
+
+
+def parse_seeds(value):
+    return tuple(int(item) for item in parse_csv(value))
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Run RFT/edRFT wave forecasting experiments.")
+    parser.add_argument("--data-dir", default="wave")
+    parser.add_argument("--stations", default="46001h")
+    parser.add_argument("--years", default="2017")
+    parser.add_argument("--seeds", default="0")
+    parser.add_argument("--look-back", type=int, default=48)
+    parser.add_argument("--order", type=int, default=None, help=argparse.SUPPRESS)
+    parser.add_argument("--horizon", type=int, default=4)
+    parser.add_argument("--layers", type=int, default=10)
+    parser.add_argument("--max-evals", type=int, default=100)
+    args = parser.parse_args()
+
+    results = run_wave_experiment(
+        data_dir=args.data_dir,
+        stations=parse_csv(args.stations),
+        years=parse_csv(args.years),
+        seeds=parse_seeds(args.seeds),
+        look_back=args.order if args.order is not None else args.look_back,
+        horizon=args.horizon,
+        n_layers=args.layers,
+        max_evals=args.max_evals,
+    )
+    for result in results:
+        print(
+            f"{result.year} {result.station} seed={result.seed} {result.model:5s} "
+            f"RMSE={result.rmse:.6f} MAPE={result.mape:.6f} MASE={result.mase:.6f} "
+            f"tune={result.tuning_seconds:.3f}s train={result.training_seconds:.3f}s "
+            f"test={result.testing_seconds:.3f}s"
+        )
+        print(f"best_params={result.best_params}")
+
+
+if __name__ == "__main__":
+    main()

edrft-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "edrft"
+version = "0.1.0"
+description = "RFT and edRFT models for significant wave-height time-series forecasting."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "Aryan Bhambu"},
+]
+keywords = ["edrft", "rft", "rvfl", "transformer", "wave-height", "forecasting"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "numpy>=1.21",
+    "torch>=2.0",
+]
+
+[project.optional-dependencies]
+tuning = [
+    "hyperopt>=0.2.7",
+    "setuptools<81",
+]
+wave = [
+    "hyperopt>=0.2.7",
+    "pandas>=1.3",
+    "setuptools<81",
+]
+dev = [
+    "build",
+    "hyperopt>=0.2.7",
+    "pandas>=1.3",
+    "pytest",
+    "setuptools<81",
+    "twine",
+]
+
+[project.urls]
+Homepage = "https://github.com/statsdl/edRFT"
+Issues = "https://github.com/statsdl/edRFT/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.black]
+line-length = 99
+target-version = ["py38"]
+
+[tool.isort]
+profile = "black"
+multi_line_output = 3
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+addopts = "-ra -q"
+testpaths = ["tests"]

edrft-0.1.0/requirements.txt

@@ -0,0 +1,2 @@
+numpy>=1.21
+torch>=2.0

edrft-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

edrft-0.1.0/setup.py

@@ -0,0 +1,4 @@
+from setuptools import setup
+
+
+setup()

edrft-0.1.0/src/edrft/__init__.py

@@ -0,0 +1,18 @@
+"""Random Vector Functional Link Transformer models."""
+
+from .data import chronological_split, make_forecasting_frame
+from .metrics import mean_absolute_scaled_error, mean_absolute_percentage_error, root_mean_squared_error
+from .models import EDRFTRegressor, RFTLayerParams, RFTRegressor
+
+__all__ = [
+    "EDRFTRegressor",
+    "RFTLayerParams",
+    "RFTRegressor",
+    "chronological_split",
+    "make_forecasting_frame",
+    "mean_absolute_percentage_error",
+    "mean_absolute_scaled_error",
+    "root_mean_squared_error",
+]
+
+__version__ = "0.1.0"

edrft-0.1.0/src/edrft/data.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+import numpy as np
+
+
+def make_forecasting_frame(
+    series: Iterable[float] | np.ndarray,
+    order: int = 48,
+    horizon: int = 4,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Convert a univariate or multivariate sequence into lagged samples."""
+
+    values = np.asarray(series, dtype=np.float32)
+    if values.ndim == 1:
+        values = values.reshape(-1, 1)
+    if values.ndim != 2:
+        raise ValueError("series must be a 1D or 2D array.")
+    if order <= 0 or horizon <= 0:
+        raise ValueError("order and horizon must be positive.")
+    n_samples = values.shape[0] - order - horizon + 1
+    if n_samples <= 0:
+        raise ValueError("series is too short for the requested order and horizon.")
+    X = np.zeros((n_samples, values.shape[1] * order), dtype=np.float32)
+    y = np.zeros((n_samples, values.shape[1]), dtype=np.float32)
+    for i in range(n_samples):
+        X[i] = values[i : i + order].ravel()
+        y[i] = values[i + order + horizon - 1]
+    return X, y.ravel() if y.shape[1] == 1 else y
+
+
+def chronological_split(n_samples: int, validation_fraction: float = 0.1, test_fraction: float = 0.2):
+    """Return train, validation, full-train, and test indexes in time order."""
+
+    test_len = int(test_fraction * n_samples)
+    val_len = int(validation_fraction * n_samples)
+    train_len = n_samples - val_len - test_len
+    if train_len <= 0:
+        raise ValueError("Not enough samples for the requested split.")
+    train = np.arange(train_len)
+    val = np.arange(train_len, train_len + val_len)
+    full_train = np.arange(train_len + val_len)
+    test = np.arange(train_len + val_len, n_samples)
+    return train, val, full_train, test
+
+
+def load_ndbc_wave_file(path: str | Path, features: list[str] | None = None) -> pd.DataFrame:
+    """Load an NDBC wave-height text file and clean sentinel missing values."""
+
+    import pandas as pd
+
+    features = features or ["WDIR", "WSPD", "GST", "APD", "WVHT"]
+    frame = pd.read_csv(path, sep=r"\s+", compression="infer")
+    frame = frame[features].replace(["99.0", "99.00", 99.0, 99.00], np.nan)
+    return frame.ffill().bfill().astype(float)

edrft-0.1.0/src/edrft/metrics.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import numpy as np
+
+
+def root_mean_squared_error(y_true, y_pred) -> float:
+    truth = np.asarray(y_true, dtype=float).ravel()
+    pred = np.asarray(y_pred, dtype=float).ravel()
+    return float(np.sqrt(np.mean((truth - pred) ** 2)))
+
+
+def mean_absolute_percentage_error(y_true, y_pred, epsilon: float = 1e-8) -> float:
+    truth = np.asarray(y_true, dtype=float).ravel()
+    pred = np.asarray(y_pred, dtype=float).ravel()
+    denom = np.maximum(np.abs(truth), epsilon)
+    return float(np.mean(np.abs((truth - pred) / denom)))
+
+
+def mean_absolute_scaled_error(y_true, y_pred, history, seasonality: int = 1) -> float:
+    truth = np.asarray(y_true, dtype=float).ravel()
+    pred = np.asarray(y_pred, dtype=float).ravel()
+    hist = np.asarray(history, dtype=float).ravel()
+    scale = np.mean(np.abs(hist[seasonality:] - hist[:-seasonality]))
+    if scale == 0:
+        return float("inf")
+    return float(np.mean(np.abs(truth - pred)) / scale)