edrft 0.1.0__py3-none-any.whl

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/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/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)

edrft/models.py

@@ -0,0 +1,266 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Literal
+
+import numpy as np
+import torch
+import torch.nn as nn
+
+Aggregation = Literal["median", "mean"]
+
+
+@dataclass(frozen=True)
+class RFTLayerParams:
+    """Hyperparameters for one RFT hidden layer."""
+
+    n_hidden: int = 64
+    regularization: float = 1e-3
+    input_scale: float = 0.1
+    transformer_layers: int = 1
+    num_heads: int = 1
+    dropout: float = 0.0
+
+
+def _as_2d(values: np.ndarray | Iterable[float], name: str) -> np.ndarray:
+    array = np.asarray(values, dtype=np.float32)
+    if array.ndim == 1:
+        array = array.reshape(-1, 1)
+    if array.ndim != 2:
+        raise ValueError(f"{name} must be a 1D or 2D array.")
+    if not np.all(np.isfinite(array)):
+        raise ValueError(f"{name} contains NaN or infinite values.")
+    return array
+
+
+def _ridge_solve(design: np.ndarray, target: np.ndarray, regularization: float) -> np.ndarray:
+    penalty = float(regularization) * np.eye(design.shape[1], dtype=np.float64)
+    penalty[-1, -1] = 0.0
+    left = design.T @ design + penalty
+    right = design.T @ target
+    try:
+        return np.linalg.solve(left, right)
+    except np.linalg.LinAlgError:
+        return np.linalg.pinv(left) @ right
+
+
+class _RandomTransformerBlock(nn.Module):
+    def __init__(
+        self,
+        n_features: int,
+        n_hidden: int,
+        input_scale: float,
+        transformer_layers: int,
+        num_heads: int,
+        dropout: float,
+    ) -> None:
+        super().__init__()
+        heads = int(num_heads) if n_features % int(num_heads) == 0 else 1
+        encoder_layer = nn.TransformerEncoderLayer(
+            d_model=n_features,
+            nhead=max(1, heads),
+            dim_feedforward=int(n_hidden),
+            dropout=float(dropout),
+            activation="relu",
+            batch_first=True,
+        )
+        self.encoder = nn.TransformerEncoder(encoder_layer, num_layers=int(transformer_layers))
+        self.projection = nn.Linear(n_features, int(n_hidden))
+        self.activation = nn.Tanh()
+        self.input_scale = float(input_scale)
+        self.reset_parameters()
+
+    def reset_parameters(self) -> None:
+        for parameter in self.encoder.parameters():
+            if parameter.ndim > 1:
+                nn.init.uniform_(parameter, -self.input_scale, self.input_scale)
+            else:
+                nn.init.zeros_(parameter)
+        nn.init.uniform_(self.projection.weight, -self.input_scale, self.input_scale)
+        nn.init.uniform_(self.projection.bias, -self.input_scale, self.input_scale)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        encoded = self.encoder(x.unsqueeze(1)).squeeze(1)
+        return self.activation(self.projection(encoded))
+
+
+class RFTRegressor:
+    """Random Vector Functional Link Transformer regressor.
+
+    Hidden transformer weights are randomly initialized and fixed. Only the
+    output readout is solved with ridge regression.
+    """
+
+    def __init__(
+        self,
+        n_hidden: int = 64,
+        regularization: float = 1e-3,
+        input_scale: float = 0.1,
+        transformer_layers: int = 1,
+        num_heads: int = 1,
+        dropout: float = 0.0,
+        random_state: int | None = None,
+        device: str = "cpu",
+    ) -> None:
+        self.n_hidden = n_hidden
+        self.regularization = regularization
+        self.input_scale = input_scale
+        self.transformer_layers = transformer_layers
+        self.num_heads = num_heads
+        self.dropout = dropout
+        self.random_state = random_state
+        self.device = device
+
+    def fit(self, X: np.ndarray | Iterable[float], y: np.ndarray | Iterable[float]) -> "RFTRegressor":
+        X_arr = _as_2d(X, "X")
+        y_arr = _as_2d(y, "y").astype(np.float64)
+        if X_arr.shape[0] != y_arr.shape[0]:
+            raise ValueError("X and y must contain the same number of samples.")
+        torch.manual_seed(0 if self.random_state is None else int(self.random_state))
+        self.block_ = _RandomTransformerBlock(
+            X_arr.shape[1],
+            int(self.n_hidden),
+            float(self.input_scale),
+            int(self.transformer_layers),
+            int(self.num_heads),
+            float(self.dropout),
+        ).to(self.device)
+        self.block_.eval()
+        hidden = self._hidden(X_arr)
+        design = self._design(X_arr, hidden)
+        self.coef_ = _ridge_solve(design, y_arr, float(self.regularization))
+        self.n_features_in_ = X_arr.shape[1]
+        self.n_outputs_ = y_arr.shape[1]
+        return self
+
+    def predict(self, X: np.ndarray | Iterable[float]) -> np.ndarray:
+        self._check_fitted()
+        X_arr = _as_2d(X, "X")
+        if X_arr.shape[1] != self.n_features_in_:
+            raise ValueError(f"Expected {self.n_features_in_} features, got {X_arr.shape[1]}.")
+        pred = self._design(X_arr, self._hidden(X_arr)) @ self.coef_
+        return pred.ravel() if self.n_outputs_ == 1 else pred
+
+    def _hidden(self, X: np.ndarray) -> np.ndarray:
+        with torch.no_grad():
+            tensor = torch.as_tensor(X, dtype=torch.float32, device=self.device)
+            return self.block_(tensor).cpu().numpy().astype(np.float64)
+
+    @staticmethod
+    def _design(X: np.ndarray, hidden: np.ndarray) -> np.ndarray:
+        return np.hstack([hidden, X.astype(np.float64), np.ones((X.shape[0], 1))])
+
+    def _check_fitted(self) -> None:
+        if not hasattr(self, "coef_"):
+            raise RuntimeError("The model must be fitted before prediction.")
+
+
+class EDRFTRegressor:
+    """Ensemble deep RFT regressor with one ridge readout per layer."""
+
+    def __init__(
+        self,
+        n_layers: int = 3,
+        n_hidden: int = 64,
+        regularization: float = 1e-3,
+        input_scale: float = 0.1,
+        transformer_layers: int = 1,
+        num_heads: int = 1,
+        dropout: float = 0.0,
+        aggregation: Aggregation = "median",
+        random_state: int | None = None,
+        device: str = "cpu",
+        layer_params: list[RFTLayerParams | dict] | None = None,
+    ) -> None:
+        self.n_layers = n_layers
+        self.n_hidden = n_hidden
+        self.regularization = regularization
+        self.input_scale = input_scale
+        self.transformer_layers = transformer_layers
+        self.num_heads = num_heads
+        self.dropout = dropout
+        self.aggregation = aggregation
+        self.random_state = random_state
+        self.device = device
+        self.layer_params = layer_params
+
+    def fit(self, X: np.ndarray | Iterable[float], y: np.ndarray | Iterable[float]) -> "EDRFTRegressor":
+        X_arr = _as_2d(X, "X")
+        y_arr = _as_2d(y, "y").astype(np.float64)
+        if X_arr.shape[0] != y_arr.shape[0]:
+            raise ValueError("X and y must contain the same number of samples.")
+
+        torch.manual_seed(0 if self.random_state is None else int(self.random_state))
+        state = X_arr
+        self.layers_ = []
+        for params in self._resolved_layer_params():
+            block = _RandomTransformerBlock(
+                state.shape[1],
+                params.n_hidden,
+                params.input_scale,
+                params.transformer_layers,
+                params.num_heads,
+                params.dropout,
+            ).to(self.device)
+            block.eval()
+            with torch.no_grad():
+                hidden = block(torch.as_tensor(state, dtype=torch.float32, device=self.device))
+            hidden_np = hidden.cpu().numpy().astype(np.float64)
+            design = np.hstack([hidden_np, X_arr.astype(np.float64), np.ones((X_arr.shape[0], 1))])
+            coef = _ridge_solve(design, y_arr, params.regularization)
+            self.layers_.append({"block": block, "coef": coef, "params": params})
+            state = hidden_np.astype(np.float32)
+
+        self.n_features_in_ = X_arr.shape[1]
+        self.n_outputs_ = y_arr.shape[1]
+        return self
+
+    def predict(self, X: np.ndarray | Iterable[float], return_layers: bool = False) -> np.ndarray:
+        self._check_fitted()
+        X_arr = _as_2d(X, "X")
+        if X_arr.shape[1] != self.n_features_in_:
+            raise ValueError(f"Expected {self.n_features_in_} features, got {X_arr.shape[1]}.")
+        state = X_arr
+        outputs = []
+        for layer in self.layers_:
+            with torch.no_grad():
+                hidden = layer["block"](torch.as_tensor(state, dtype=torch.float32, device=self.device))
+            hidden_np = hidden.cpu().numpy().astype(np.float64)
+            design = np.hstack([hidden_np, X_arr.astype(np.float64), np.ones((X_arr.shape[0], 1))])
+            outputs.append(design @ layer["coef"])
+            state = hidden_np.astype(np.float32)
+
+        stacked = np.stack(outputs, axis=0)
+        if return_layers:
+            result = np.moveaxis(stacked, 0, 1)
+        elif self.aggregation == "mean":
+            result = np.mean(stacked, axis=0)
+        elif self.aggregation == "median":
+            result = np.median(stacked, axis=0)
+        else:
+            raise ValueError("aggregation must be 'mean' or 'median'.")
+        return result.ravel() if self.n_outputs_ == 1 and result.ndim == 2 else result
+
+    def _resolved_layer_params(self) -> list[RFTLayerParams]:
+        if self.layer_params is None:
+            return [
+                RFTLayerParams(
+                    self.n_hidden,
+                    self.regularization,
+                    self.input_scale,
+                    self.transformer_layers,
+                    self.num_heads,
+                    self.dropout,
+                )
+                for _ in range(int(self.n_layers))
+            ]
+        params = []
+        for item in self.layer_params:
+            params.append(item if isinstance(item, RFTLayerParams) else RFTLayerParams(**item))
+        if not params:
+            raise ValueError("layer_params cannot be empty.")
+        return params
+
+    def _check_fitted(self) -> None:
+        if not hasattr(self, "layers_"):
+            raise RuntimeError("The model must be fitted before prediction.")

edrft/tuning.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+import numpy as np
+from hyperopt import STATUS_OK, Trials, fmin, hp, tpe
+
+from .metrics import root_mean_squared_error
+from .models import EDRFTRegressor, RFTLayerParams, RFTRegressor
+
+Scorer = Callable[[np.ndarray, np.ndarray], float]
+
+
+@dataclass(frozen=True)
+class TuningResult:
+    model: Any
+    best_params: dict[str, Any]
+    best_score: float
+    history: list[dict[str, Any]]
+
+
+def default_rft_space(seed: int = 0) -> dict[str, Any]:
+    """Hyperopt space matching the RFT/default edRFT search ranges."""
+
+    return {
+        "n_hidden": hp.quniform("n_hidden", 32, 1024, 32),
+        "regularization": hp.uniform("regularization", 0, 1),
+        "input_scale": hp.uniform("input_scale", 0, 1),
+        "transformer_layers": hp.choice("transformer_layers", [1, 2, 3, 4, 5]),
+        "num_heads": hp.choice("num_heads", [2, 4, 6, 8]),
+        "dropout": hp.uniform("dropout", 0, 0.5),
+        "random_state": seed,
+    }
+
+
+def default_edrft_layer_space() -> dict[str, Any]:
+    return {
+        "n_hidden": hp.quniform("n_hidden", 32, 1024, 32),
+        "regularization": hp.uniform("regularization", 0, 1),
+        "input_scale": hp.uniform("input_scale", 0, 1),
+        "transformer_layers": hp.choice("transformer_layers", [1, 2, 3, 4, 5]),
+        "num_heads": hp.choice("num_heads", [2, 4, 6, 8]),
+        "dropout": hp.uniform("dropout", 0, 0.5),
+    }
+
+
+def tune_rft(
+    X,
+    y,
+    space: dict[str, Any] | None = None,
+    scorer: Scorer = root_mean_squared_error,
+    validation_fraction: float = 0.2,
+    max_evals: int = 100,
+    random_state: int = 0,
+    refit: bool = True,
+) -> TuningResult:
+    return _tune(
+        RFTRegressor,
+        X,
+        y,
+        default_rft_space(random_state) if space is None else space,
+        scorer,
+        validation_fraction,
+        max_evals,
+        random_state,
+        refit,
+    )
+
+
+def layerwise_tune_edrft(
+    X,
+    y,
+    n_layers: int = 10,
+    layer_space: dict[str, Any] | None = None,
+    scorer: Scorer = root_mean_squared_error,
+    validation_fraction: float = 0.2,
+    max_evals: int = 100,
+    random_state: int = 0,
+    refit: bool = True,
+    fixed_params: dict[str, Any] | None = None,
+) -> TuningResult:
+    if n_layers <= 0:
+        raise ValueError("n_layers must be positive.")
+    X_arr = np.asarray(X, dtype=np.float32)
+    y_arr = np.asarray(y, dtype=np.float32)
+    X_train, X_val, y_train, y_val = _split(X_arr, y_arr, validation_fraction)
+    selected: list[RFTLayerParams] = []
+    history = []
+    fixed_params = dict(fixed_params or {})
+    space = default_edrft_layer_space() if layer_space is None else layer_space
+
+    for layer_index in range(n_layers):
+        layer_history = []
+
+        def objective(params):
+            clean = _clean_params(params)
+            if layer_index > 0:
+                clean["n_hidden"] = selected[0].n_hidden
+            candidate = selected + [RFTLayerParams(**clean)]
+            model = EDRFTRegressor(layer_params=candidate, random_state=random_state, **fixed_params).fit(
+                X_train, y_train
+            )
+            score = float(scorer(y_val, model.predict(X_val)))
+            record = {"layer": layer_index + 1, "score": score, **clean}
+            layer_history.append(record)
+            history.append(record)
+            return {"loss": score, "status": STATUS_OK}
+
+        fmin(
+            objective,
+            space=space,
+            algo=tpe.suggest,
+            max_evals=max_evals,
+            trials=Trials(),
+            rstate=np.random.default_rng(random_state + layer_index),
+            show_progressbar=False,
+        )
+        best = min(layer_history, key=lambda item: item["score"])
+        selected.append(
+            RFTLayerParams(
+                n_hidden=int(best["n_hidden"]),
+                regularization=float(best["regularization"]),
+                input_scale=float(best["input_scale"]),
+                transformer_layers=int(best["transformer_layers"]),
+                num_heads=int(best["num_heads"]),
+                dropout=float(best["dropout"]),
+            )
+        )
+
+    final_X, final_y = (X_arr, y_arr) if refit else (X_train, y_train)
+    best_params = {"layer_params": [param.__dict__ for param in selected], **fixed_params}
+    return TuningResult(
+        model=EDRFTRegressor(layer_params=selected, random_state=random_state, **fixed_params).fit(final_X, final_y),
+        best_params=best_params,
+        best_score=min(item["score"] for item in history if item["layer"] == n_layers),
+        history=history,
+    )
+
+
+def _tune(estimator_cls, X, y, space, scorer, validation_fraction, max_evals, random_state, refit):
+    X_arr = np.asarray(X, dtype=np.float32)
+    y_arr = np.asarray(y, dtype=np.float32)
+    X_train, X_val, y_train, y_val = _split(X_arr, y_arr, validation_fraction)
+    history = []
+
+    def objective(params):
+        clean = _clean_params(params)
+        model = estimator_cls(**clean).fit(X_train, y_train)
+        score = float(scorer(y_val, model.predict(X_val)))
+        history.append({"score": score, **clean})
+        return {"loss": score, "status": STATUS_OK}
+
+    fmin(
+        objective,
+        space=space,
+        algo=tpe.suggest,
+        max_evals=max_evals,
+        trials=Trials(),
+        rstate=np.random.default_rng(random_state),
+        show_progressbar=False,
+    )
+    best = min(history, key=lambda item: item["score"])
+    best_params = {key: value for key, value in best.items() if key != "score"}
+    final_X, final_y = (X_arr, y_arr) if refit else (X_train, y_train)
+    return TuningResult(
+        model=estimator_cls(**best_params).fit(final_X, final_y),
+        best_params=best_params,
+        best_score=float(best["score"]),
+        history=history,
+    )
+
+
+def _split(X, y, validation_fraction):
+    if not 0 < validation_fraction < 1:
+        raise ValueError("validation_fraction must be between 0 and 1.")
+    n_val = max(1, int(round(len(X) * validation_fraction)))
+    return X[:-n_val], X[-n_val:], y[:-n_val], y[-n_val:]
+
+
+def _clean_params(params):
+    clean = dict(params)
+    for key in ("n_hidden", "transformer_layers", "num_heads", "random_state"):
+        if key in clean:
+            clean[key] = int(clean[key])
+    if "n_hidden" in clean:
+        clean["n_hidden"] = max(1, clean["n_hidden"])
+    for key in ("regularization", "input_scale", "dropout"):
+        if key in clean:
+            clean[key] = float(clean[key])
+    return clean

edrft/wave.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from time import perf_counter
+from typing import Iterable
+
+import numpy as np
+
+from .data import chronological_split, load_ndbc_wave_file
+from .metrics import mean_absolute_percentage_error, mean_absolute_scaled_error, root_mean_squared_error
+from .models import EDRFTRegressor, RFTRegressor
+from .tuning import layerwise_tune_edrft, tune_rft
+
+
+@dataclass(frozen=True)
+class WaveRunResult:
+    station: str
+    year: str
+    seed: int
+    model: str
+    rmse: float
+    mape: float
+    mase: float
+    tuning_seconds: float
+    training_seconds: float
+    testing_seconds: float
+    best_params: dict
+
+
+def prepare_wave_supervised(
+    path: str | Path,
+    look_back: int = 48,
+    horizon: int = 4,
+    features: list[str] | None = None,
+    order: int | None = None,
+):
+    """Prepare NDBC wave data using wave forecasting lag and horizon settings."""
+
+    if order is not None:
+        look_back = order
+    if look_back <= 0 or horizon <= 0:
+        raise ValueError("look_back and horizon must be positive.")
+    frame = load_ndbc_wave_file(path, features=features)
+    values = frame.to_numpy(dtype=float)[1:]
+    target = frame["WVHT"].to_numpy(dtype=float)[1:]
+    n_samples = values.shape[0] - look_back - horizon + 1
+    if n_samples <= 0:
+        raise ValueError("series is too short for the requested look_back and horizon.")
+    X = np.zeros((n_samples, values.shape[1] * look_back), dtype=np.float32)
+    y = np.zeros(n_samples, dtype=np.float32)
+    for i in range(n_samples):
+        X[i] = values[i : i + look_back].ravel()
+        y[i] = target[i + look_back + horizon - 1]
+    return X, y
+
+
+def run_wave_experiment(
+    data_dir: str | Path = "wave",
+    stations: Iterable[str] = ("46001h",),
+    years: Iterable[str] = ("2017",),
+    seeds: Iterable[int] = (0,),
+    look_back: int = 48,
+    horizon: int = 4,
+    n_layers: int = 10,
+    max_evals: int = 100,
+    order: int | None = None,
+) -> list[WaveRunResult]:
+    """Run RFT and edRFT on NDBC files without writing result files."""
+
+    if order is not None:
+        look_back = order
+    data_dir = Path(data_dir)
+    results: list[WaveRunResult] = []
+    for year in years:
+        for station in stations:
+            X, y = prepare_wave_supervised(
+                data_dir / f"{station}{year}.txt.gz",
+                look_back=look_back,
+                horizon=horizon,
+            )
+            train_idx, val_idx, full_train_idx, test_idx = chronological_split(len(X), 0.1, 0.2)
+            scaled = _scaled_splits(X, y, train_idx, val_idx, full_train_idx, test_idx)
+            for seed in seeds:
+                results.append(
+                    _run_rft(
+                        station,
+                        year,
+                        seed,
+                        scaled,
+                        max_evals=max_evals,
+                    )
+                )
+                results.append(
+                    _run_edrft(
+                        station,
+                        year,
+                        seed,
+                        scaled,
+                        n_layers=n_layers,
+                        max_evals=max_evals,
+                    )
+                )
+    return results
+
+
+def _run_rft(station, year, seed, scaled, max_evals):
+    train, val, full_train, test, inverse_y, history = scaled
+    tune_X = np.vstack([train[0], val[0]])
+    tune_y = np.concatenate([train[1], val[1]])
+
+    start = perf_counter()
+    tuned = tune_rft(
+        tune_X,
+        tune_y,
+        validation_fraction=len(val[1]) / len(tune_y),
+        max_evals=max_evals,
+        random_state=seed,
+        refit=False,
+    )
+    tuning_seconds = perf_counter() - start
+
+    start = perf_counter()
+    model = RFTRegressor(**tuned.best_params).fit(*full_train)
+    training_seconds = perf_counter() - start
+
+    start = perf_counter()
+    pred = model.predict(test[0])
+    testing_seconds = perf_counter() - start
+    return _result(station, year, seed, "RFT", test[1], pred, inverse_y, history, tuning_seconds, training_seconds, testing_seconds, tuned.best_params)
+
+
+def _run_edrft(station, year, seed, scaled, n_layers, max_evals):
+    train, val, full_train, test, inverse_y, history = scaled
+    tune_X = np.vstack([train[0], val[0]])
+    tune_y = np.concatenate([train[1], val[1]])
+
+    start = perf_counter()
+    tuned = layerwise_tune_edrft(
+        tune_X,
+        tune_y,
+        n_layers=n_layers,
+        validation_fraction=len(val[1]) / len(tune_y),
+        max_evals=max_evals,
+        random_state=seed,
+        refit=False,
+    )
+    tuning_seconds = perf_counter() - start
+
+    start = perf_counter()
+    model = EDRFTRegressor(layer_params=tuned.best_params["layer_params"], random_state=seed).fit(*full_train)
+    training_seconds = perf_counter() - start
+
+    start = perf_counter()
+    pred = model.predict(test[0])
+    testing_seconds = perf_counter() - start
+    return _result(station, year, seed, "edRFT", test[1], pred, inverse_y, history, tuning_seconds, training_seconds, testing_seconds, tuned.best_params)
+
+
+def _scaled_splits(X, y, train_idx, val_idx, full_train_idx, test_idx):
+    x_min = X[train_idx].min(axis=0)
+    x_range = np.maximum(X[train_idx].max(axis=0) - x_min, 1e-12)
+    y_min = y[train_idx].min()
+    y_range = max(float(y[train_idx].max() - y_min), 1e-12)
+
+    def scale_x(values):
+        return 2 * ((values - x_min) / x_range) - 1
+
+    def scale_y(values):
+        return 2 * ((values - y_min) / y_range) - 1
+
+    def inverse_y(values):
+        return ((np.asarray(values, dtype=float) + 1) / 2) * y_range + y_min
+
+    return (
+        (scale_x(X[train_idx]), scale_y(y[train_idx])),
+        (scale_x(X[val_idx]), scale_y(y[val_idx])),
+        (scale_x(X[full_train_idx]), scale_y(y[full_train_idx])),
+        (scale_x(X[test_idx]), scale_y(y[test_idx])),
+        inverse_y,
+        y[train_idx],
+    )
+
+
+def _result(station, year, seed, model, y_true, y_pred, inverse_y, history, tuning, training, testing, best_params):
+    truth = inverse_y(y_true)
+    pred = inverse_y(y_pred)
+    return WaveRunResult(
+        station=station,
+        year=year,
+        seed=seed,
+        model=model,
+        rmse=root_mean_squared_error(truth, pred),
+        mape=mean_absolute_percentage_error(truth, pred),
+        mase=mean_absolute_scaled_error(truth, pred, history),
+        tuning_seconds=tuning,
+        training_seconds=training,
+        testing_seconds=testing,
+        best_params=best_params,
+    )

edrft-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+edrft/__init__.py,sha256=ZtIFqVd4Xk-kpKKGPNHZHoKokpBVIPtrRY8QIlOkUfg,551
+edrft/data.py,sha256=LkHp-BJR_KSKIOVkUXY6jPWfYQAKZUQ4ZizwjniKcCI,2215
+edrft/metrics.py,sha256=6q1yofHAhwD5rICVBdq5Ncqucctwo1lBwOH78o5o7rQ,982
+edrft/models.py,sha256=GnLiTQ1A82HwVz-Na7kF8bQVRyauWnAswk12NEF_NUI,10062
+edrft/tuning.py,sha256=vLq46ciebAfNv57FMHBenvySgD2CVBlRdHQFcMCHU7Y,6544
+edrft/wave.py,sha256=O0u0pLTNUqkctfTxel96RJsD5j7qk5T32lhGmKQIW_0,6544
+edrft-0.1.0.dist-info/licenses/LICENSE,sha256=o-oucML3-pP9uO0PIFnQXUcXY8i8DiyRZieAsyPJLfY,1069
+edrft-0.1.0.dist-info/METADATA,sha256=p5VaSadudLh9HL1FqMeGyNyQ-ZtFw16B7TQi6Pk68-M,4389
+edrft-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+edrft-0.1.0.dist-info/top_level.txt,sha256=zKAm5kZBsSXevNfPi2mpMTt9ROQo5HI2ZbBjhAm8RhE,6
+edrft-0.1.0.dist-info/RECORD,,

edrft-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

edrft-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+edrft