torchriver 0.1.1__py3-none-any.whl

torchriver/__init__.py

@@ -0,0 +1,23 @@
+"""TorchRiver: low-flow / drought forecasting for river time-series data."""
+
+from .configs import RiverDataConfig, RiverModelConfig, RiverTrainConfig, RiverUIConfig, TorchRiverWorkflow
+from .data import make_synthetic_data
+from .models import MODEL_REGISTRY, RiverCNNLSTM, build_model
+from .project import RiverProject
+from .serialization import load_river_model
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "RiverProject",
+    "load_river_model",
+    "RiverDataConfig",
+    "RiverModelConfig",
+    "RiverTrainConfig",
+    "RiverUIConfig",
+    "TorchRiverWorkflow",
+    "RiverCNNLSTM",
+    "MODEL_REGISTRY",
+    "build_model",
+    "make_synthetic_data",
+]

torchriver/cli.py

@@ -0,0 +1,40 @@
+"""Command-line helpers for TorchRiver."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from . import __version__
+from .project import RiverProject
+
+
+def smoke() -> None:
+    """Print package information; useful after pip install."""
+    print(f"torchriver {__version__} installed successfully")
+
+
+def synthetic_demo() -> None:
+    """Train a tiny synthetic demo and optionally save a .triver model."""
+    parser = argparse.ArgumentParser(description="Run a tiny TorchRiver synthetic training demo.")
+    parser.add_argument("--days", type=int, default=120)
+    parser.add_argument("--epochs", type=int, default=1)
+    parser.add_argument("--output", type=str, default="", help="Optional .triver output path")
+    args = parser.parse_args()
+
+    project = RiverProject(title="TorchRiver synthetic demo")
+    project.make_synthetic(days=args.days, station_codes=["R001", "R002"])
+    project.use_model("river_cnn_lstm", horizons=[7], lookback=14, hidden_dim=16)
+    project.train(epochs=args.epochs, batch_size=128, min_windows=3, verbose=False)
+    result = project.predict(station="R001", horizon=7)
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+
+    if args.output:
+        output = Path(args.output)
+        project.save_model(output, include_recent_data=True)
+        print(f"saved: {output}")
+
+
+if __name__ == "__main__":
+    smoke()

torchriver/configs.py

@@ -0,0 +1,130 @@
+"""Configuration objects for TorchRiver."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterable, List, Optional
+
+
+@dataclass
+class RiverDataConfig:
+    """Configuration for loading and normalizing river data."""
+
+    source: str = "synthetic"
+    path: Optional[str] = None
+    dataset_url: Optional[str] = None
+    nrows: Optional[int] = None
+    mapping: Optional[Dict[str, str]] = None
+    station_names: Optional[Dict[str, str]] = None
+    fallback_synthetic: bool = True
+    synthetic_days: int = 240
+    synthetic_station_codes: List[str] = field(default_factory=lambda: ["R001", "R002", "R003"])
+    column_names: Optional[Dict[str, str]] = None
+
+
+@dataclass
+class RiverModelConfig:
+    """Configuration for a TorchRiver model family."""
+
+    name: str = "river_cnn_lstm"
+    horizons: List[int] = field(default_factory=lambda: [7, 14, 30])
+    lookback: int = 30
+    window_mode: str = "per_station"
+    device: str = "auto"
+    legacy_sigmoid: bool = False
+    hidden_dim: int = 64
+    dropout: float = 0.0
+    balance_classes: bool = True
+    model_kwargs: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class RiverTrainConfig:
+    """Configuration for training."""
+
+    epochs: int = 2
+    batch_size: int = 512
+    lr: float = 0.001
+    validation_split: float = 0.2
+    balance_classes: Optional[bool] = None
+    seed: int = 42
+    min_windows: int = 5
+    verbose: bool = True
+
+
+@dataclass
+class RiverUIConfig:
+    """Configuration for the Gradio interface."""
+
+    title: str = "River Low-Flow Early Warning System"
+    lang: str = "en"
+    direction: str = "ltr"
+    labels: Dict[str, str] = field(default_factory=dict)
+    logo: Optional[str] = None
+    share: bool = False
+    api: bool = True
+    output_mode: str = "text"
+
+
+@dataclass
+class TorchRiverWorkflow:
+    """Advanced workflow wrapper combining data, model, training, and UI configs."""
+
+    data: RiverDataConfig
+    model: RiverModelConfig = field(default_factory=RiverModelConfig)
+    train_config: RiverTrainConfig = field(default_factory=RiverTrainConfig)
+    ui: RiverUIConfig = field(default_factory=RiverUIConfig)
+
+    def run(self):
+        """Run loading, cleaning, model selection, and training. Returns the project."""
+        from .project import RiverProject
+
+        project = RiverProject(title=self.ui.title, lang=self.ui.lang, direction=self.ui.direction)
+        if self.data.source == "kaggle":
+            project.load_kaggle(
+                self.data.dataset_url or self.data.path or "",
+                nrows=self.data.nrows,
+                mapping=self.data.mapping,
+                station_names=self.data.station_names,
+                fallback_synthetic=self.data.fallback_synthetic,
+            )
+        elif self.data.source == "folder":
+            project.load_folder(self.data.path or "", nrows=self.data.nrows, mapping=self.data.mapping, station_names=self.data.station_names)
+        elif self.data.source == "file":
+            project.load_file(self.data.path or "", nrows=self.data.nrows, mapping=self.data.mapping, station_names=self.data.station_names)
+        elif self.data.source == "url":
+            project.load_url(self.data.dataset_url or self.data.path or "", nrows=self.data.nrows, mapping=self.data.mapping, station_names=self.data.station_names)
+        elif self.data.source == "synthetic":
+            project.make_synthetic(
+                days=self.data.synthetic_days,
+                station_codes=self.data.synthetic_station_codes,
+                station_names=self.data.station_names,
+                column_names=self.data.column_names,
+            )
+        else:
+            raise ValueError(f"Unknown data source: {self.data.source!r}")
+
+        project.clean()
+        project.use_model(
+            self.model.name,
+            horizons=self.model.horizons,
+            lookback=self.model.lookback,
+            device=self.model.device,
+            window_mode=self.model.window_mode,
+            balance_classes=self.model.balance_classes,
+            legacy_sigmoid=self.model.legacy_sigmoid,
+            hidden_dim=self.model.hidden_dim,
+            dropout=self.model.dropout,
+            **self.model.model_kwargs,
+        )
+        project.train(
+            epochs=self.train_config.epochs,
+            batch_size=self.train_config.batch_size,
+            lr=self.train_config.lr,
+            validation_split=self.train_config.validation_split,
+            balance_classes=self.train_config.balance_classes,
+            seed=self.train_config.seed,
+            min_windows=self.train_config.min_windows,
+            verbose=self.train_config.verbose,
+        )
+        return project

torchriver/data.py

@@ -0,0 +1,410 @@
+"""Data loading, schema mapping, cleaning, synthetic generation, and windows."""
+
+from __future__ import annotations
+
+import io
+import os
+import re
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Sequence, Tuple
+from urllib.parse import urlparse
+from urllib.request import urlopen
+
+import numpy as np
+import pandas as pd
+from sklearn.preprocessing import StandardScaler
+
+INTERNAL_COLUMNS = {
+    "date": "date",
+    "station": "station_code",
+    "station_name": "station",
+    "discharge": "discharge_m3s",
+    "low_flow_threshold": "low_flow_q10_threshold_m3s",
+    "target": "target_lowflow",
+}
+
+COLUMN_SYNONYMS = {
+    "date": ["date", "day", "timestamp", "time", "datetime", "measurement_date"],
+    "station": ["station_code", "station_id", "gauge_id", "site_no", "river_id", "stationcode", "gauge"],
+    "station_name": ["station", "station_name", "gauge_name", "river_name", "name", "site_name"],
+    "discharge": ["discharge_m3s", "discharge", "flow", "streamflow", "q_m3s", "q", "value", "runoff"],
+    "low_flow_threshold": ["low_flow_q10_threshold_m3s", "q10", "threshold", "low_flow_threshold", "critical_flow"],
+    "target": ["target_lowflow", "low_flow", "low_flow_flag", "drought", "label"],
+}
+
+EXCLUDED_COLS = [
+    "date",
+    "station_code",
+    "station",
+    "station_original",
+    "river",
+    "target_lowflow",
+]
+
+SUPPORTED_EXTENSIONS = [".csv", ".xlsx", ".xls", ".parquet", ".json", ".jsonl", ".feather", ".pkl", ".pickle"]
+
+
+def _norm(name: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "_", str(name).strip().lower()).strip("_")
+
+
+def infer_mapping(columns: Iterable[str], mapping: Optional[Dict[str, str]] = None) -> Dict[str, str]:
+    """Infer a user-column -> internal-column mapping.
+
+    The input ``mapping`` follows the public API style, e.g.
+    ``{"date": "day", "station": "gauge_id"}``. Returned mapping maps actual
+    dataframe columns to canonical TorchRiver columns.
+    """
+    columns = list(columns)
+    normalized_to_original = {_norm(c): c for c in columns}
+    result: Dict[str, str] = {}
+
+    if mapping:
+        for semantic_name, actual_col in mapping.items():
+            if actual_col is None:
+                continue
+            target = INTERNAL_COLUMNS.get(semantic_name, semantic_name)
+            if actual_col in columns:
+                result[actual_col] = target
+            else:
+                normalized = _norm(actual_col)
+                if normalized in normalized_to_original:
+                    result[normalized_to_original[normalized]] = target
+
+    already_targets = set(result.values())
+    for semantic_name, candidates in COLUMN_SYNONYMS.items():
+        target = INTERNAL_COLUMNS[semantic_name]
+        if target in already_targets:
+            continue
+        for candidate in candidates:
+            if _norm(candidate) in normalized_to_original:
+                result[normalized_to_original[_norm(candidate)]] = target
+                already_targets.add(target)
+                break
+    return result
+
+
+def apply_mapping(df: pd.DataFrame, mapping: Optional[Dict[str, str]] = None) -> Tuple[pd.DataFrame, Dict[str, str]]:
+    actual_mapping = infer_mapping(df.columns, mapping)
+    out = df.copy()
+    rename_map = {src: dst for src, dst in actual_mapping.items() if src != dst}
+    out = out.rename(columns=rename_map)
+    return out, actual_mapping
+
+
+def read_data_file(path: str | os.PathLike[str], nrows: Optional[int] = None) -> pd.DataFrame:
+    """Read a CSV, Excel, Parquet, JSON/JSONL, Feather, or Pickle file."""
+    path = str(path)
+    ext = Path(path).suffix.lower()
+    if ext == ".csv":
+        return pd.read_csv(path, nrows=nrows, low_memory=False)
+    if ext in {".xlsx", ".xls"}:
+        return pd.read_excel(path, nrows=nrows)
+    if ext == ".parquet":
+        df = pd.read_parquet(path)
+        return df.head(nrows) if nrows else df
+    if ext == ".json":
+        df = pd.read_json(path)
+        return df.head(nrows) if nrows else df
+    if ext == ".jsonl":
+        return pd.read_json(path, lines=True, nrows=nrows)
+    if ext == ".feather":
+        df = pd.read_feather(path)
+        return df.head(nrows) if nrows else df
+    if ext in {".pkl", ".pickle"}:
+        df = pd.read_pickle(path)
+        return df.head(nrows) if nrows else df
+    raise ValueError(f"Unsupported file type {ext!r}. Supported: {SUPPORTED_EXTENSIONS}")
+
+
+def _candidate_score(path: Path) -> int:
+    name = path.name.lower()
+    score = 0
+    if "combined" in name:
+        score += 8
+    if "elbe" in name:
+        score += 5
+    if "river" in name:
+        score += 4
+    if "station" in name or "gauge" in name:
+        score += 2
+    if path.suffix.lower() == ".csv":
+        score += 1
+    try:
+        score += min(path.stat().st_size // 1_000_000, 5)
+    except OSError:
+        pass
+    return score
+
+
+def find_data_file(folder: str | os.PathLike[str]) -> Path:
+    """Recursively find the most likely data file in a folder."""
+    root = Path(folder)
+    if not root.exists():
+        raise FileNotFoundError(f"Folder does not exist: {folder}")
+    candidates = [p for p in root.rglob("*") if p.is_file() and p.suffix.lower() in SUPPORTED_EXTENSIONS]
+    if not candidates:
+        raise FileNotFoundError(f"No supported data file found under {folder}")
+    return sorted(candidates, key=_candidate_score, reverse=True)[0]
+
+
+def _download_url_to_temp(url: str) -> Path:
+    suffix = Path(urlparse(url).path).suffix or ".data"
+    fd, temp_path = tempfile.mkstemp(suffix=suffix)
+    os.close(fd)
+    with urlopen(url) as response, open(temp_path, "wb") as f:
+        f.write(response.read())
+    return Path(temp_path)
+
+
+def load_url(url: str, nrows: Optional[int] = None) -> pd.DataFrame:
+    """Load a direct data URL or a ZIP URL containing a supported file."""
+    temp_path = _download_url_to_temp(url)
+    try:
+        if temp_path.suffix.lower() == ".zip":
+            extract_dir = Path(tempfile.mkdtemp(prefix="torchriver_url_"))
+            with zipfile.ZipFile(temp_path) as zf:
+                zf.extractall(extract_dir)
+            return read_data_file(find_data_file(extract_dir), nrows=nrows)
+        return read_data_file(temp_path, nrows=nrows)
+    finally:
+        try:
+            temp_path.unlink(missing_ok=True)
+        except Exception:
+            pass
+
+
+def load_kaggle_dataset(dataset_url: str, cache_dir: str | os.PathLike[str] = "~/.cache/torchriver", nrows: Optional[int] = None) -> pd.DataFrame:
+    """Download/read a Kaggle dataset without embedding any credentials.
+
+    Supported credential paths:
+    - ``KAGGLE_USERNAME`` and ``KAGGLE_KEY`` environment variables.
+    - Kaggle's standard ``~/.kaggle/kaggle.json``.
+    - Interactive prompts through ``opendatasets`` when available.
+    """
+    if not dataset_url:
+        raise ValueError("dataset_url is required for Kaggle loading")
+
+    cache_dir = Path(cache_dir).expanduser()
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    slug = dataset_url.rstrip("/").split("/")[-1]
+    dataset_folder = cache_dir / slug
+
+    if not dataset_folder.exists() or not any(dataset_folder.rglob("*")):
+        try:
+            import opendatasets as od  # type: ignore
+        except ImportError as exc:
+            raise ImportError("Install opendatasets to use load_kaggle: pip install opendatasets kaggle") from exc
+        od.download(dataset_url, data_dir=str(cache_dir))
+
+    data_path = find_data_file(dataset_folder if dataset_folder.exists() else cache_dir)
+    return read_data_file(data_path, nrows=nrows)
+
+
+def make_synthetic_data(
+    days: int = 600,
+    station_codes: Optional[Sequence[str]] = None,
+    station_names: Optional[Dict[str, str]] = None,
+    column_names: Optional[Dict[str, str]] = None,
+    seed: int = 42,
+) -> pd.DataFrame:
+    """Generate station-aware synthetic river data with realistic seasonality."""
+    rng = np.random.default_rng(seed)
+    station_codes = list(station_codes or ["R001", "R002", "R003"])
+    station_names = station_names or {code: f"River {i + 1}" for i, code in enumerate(station_codes)}
+    dates = pd.date_range(end=pd.Timestamp.today().normalize(), periods=days, freq="D")
+    frames: List[pd.DataFrame] = []
+
+    for i, code in enumerate(station_codes):
+        phase = rng.uniform(0, 2 * np.pi)
+        base = rng.uniform(70, 210)
+        amplitude = rng.uniform(20, 80)
+        trend = np.linspace(rng.uniform(-5, 5), rng.uniform(-10, 10), days)
+        day_index = np.arange(days)
+        season = np.sin(2 * np.pi * day_index / 365.25 + phase)
+        precipitation = np.maximum(0, rng.gamma(shape=1.5 + i * 0.15, scale=3.0, size=days) * (1 + 0.4 * season))
+        temperature = 12 + 12 * np.sin(2 * np.pi * (day_index - 80) / 365.25 + phase / 3) + rng.normal(0, 2, days)
+        ndwi = np.clip(0.2 + 0.35 * season + rng.normal(0, 0.12, days), -1, 1)
+        discharge = base + amplitude * season + 1.8 * precipitation - 0.8 * np.maximum(temperature - 25, 0) + trend + rng.normal(0, 8, days)
+        discharge = np.maximum(discharge, 1.0)
+        q10 = float(np.quantile(discharge, 0.10))
+        sdi_30 = (pd.Series(discharge).rolling(30, min_periods=1).mean() - np.mean(discharge)) / (np.std(discharge) + 1e-8)
+        target = (discharge < q10).astype(int)
+        frames.append(
+            pd.DataFrame(
+                {
+                    "date": dates,
+                    "station_code": str(code),
+                    "station": station_names.get(str(code), str(code)),
+                    "discharge_m3s": discharge,
+                    "low_flow_q10_threshold_m3s": q10,
+                    "sdi_30": sdi_30,
+                    "precipitation_mm": precipitation,
+                    "temperature_c": temperature,
+                    "ndwi": ndwi,
+                    "target_lowflow": target,
+                }
+            )
+        )
+    df = pd.concat(frames, ignore_index=True)
+    if column_names:
+        public_to_internal = {
+            "date": "date",
+            "station": "station_code",
+            "station_name": "station",
+            "discharge": "discharge_m3s",
+            "low_flow_threshold": "low_flow_q10_threshold_m3s",
+            "target": "target_lowflow",
+        }
+        rename = {internal: column_names[key] for key, internal in public_to_internal.items() if key in column_names}
+        df = df.rename(columns=rename)
+    return df
+
+
+def clean_river_dataframe(
+    df: pd.DataFrame,
+    mapping: Optional[Dict[str, str]] = None,
+    station_names: Optional[Dict[str, str]] = None,
+) -> Tuple[pd.DataFrame, Dict[str, str], Dict[str, str]]:
+    """Map and clean river data into TorchRiver's internal schema."""
+    if df is None or len(df) == 0:
+        raise ValueError("Input dataframe is empty")
+    out, actual_mapping = apply_mapping(df, mapping)
+
+    if "date" not in out.columns:
+        raise ValueError("No date column found. Provide mapping={'date': '<your_date_column>'}.")
+    if "station_code" not in out.columns:
+        # Single-station fallback is useful for custom files, but transparent.
+        out["station_code"] = "RIVER_001"
+    if "station" not in out.columns:
+        out["station"] = out["station_code"].astype(str)
+    if "discharge_m3s" not in out.columns:
+        raise ValueError("No discharge column found. Provide mapping={'discharge': '<your_flow_column>'}.")
+
+    out["date"] = pd.to_datetime(out["date"], errors="coerce")
+    out = out.dropna(subset=["date"]).copy()
+    out["station_code"] = out["station_code"].astype(str)
+    out["station"] = out["station"].astype(str)
+
+    # Preserve optional original naming for academic traceability.
+    if "station_original" not in out.columns:
+        out["station_original"] = out["station"].copy()
+
+    # Numeric conversion except core text/date fields.
+    non_numeric = {"date", "station_code", "station", "station_original", "river"}
+    for col in out.columns:
+        if col not in non_numeric:
+            out[col] = pd.to_numeric(out[col], errors="coerce")
+    out = out.replace([np.inf, -np.inf], np.nan)
+
+    if "low_flow_q10_threshold_m3s" not in out.columns:
+        out["low_flow_q10_threshold_m3s"] = out.groupby("station_code")["discharge_m3s"].transform(lambda s: s.quantile(0.10))
+    if "target_lowflow" not in out.columns:
+        out["target_lowflow"] = (out["discharge_m3s"] < out["low_flow_q10_threshold_m3s"]).astype(int)
+    else:
+        out["target_lowflow"] = pd.to_numeric(out["target_lowflow"], errors="coerce")
+        out["target_lowflow"] = out["target_lowflow"].fillna(0).astype(int).clip(0, 1)
+
+    out = out.sort_values(["station_code", "date"]).reset_index(drop=True)
+
+    # Fill numeric missing values inside each station first to prevent leakage.
+    numeric_cols = [c for c in out.columns if c not in non_numeric and pd.api.types.is_numeric_dtype(out[c])]
+    if numeric_cols:
+        out[numeric_cols] = out.groupby("station_code", group_keys=False)[numeric_cols].apply(lambda g: g.ffill().bfill())
+        out[numeric_cols] = out[numeric_cols].fillna(out[numeric_cols].median(numeric_only=True)).fillna(0)
+
+    out = out.replace([np.inf, -np.inf], np.nan)
+    if out[numeric_cols].isna().any().any():
+        out[numeric_cols] = out[numeric_cols].fillna(0)
+
+    station_name_map = {str(k): str(v) for k, v in (station_names or {}).items()}
+    observed_names = out.groupby("station_code")["station"].first().astype(str).to_dict()
+    observed_names.update(station_name_map)
+    out["station"] = out["station_code"].map(observed_names).fillna(out["station"].astype(str))
+
+    return out.reset_index(drop=True), actual_mapping, observed_names
+
+
+def choose_feature_columns(df: pd.DataFrame, user_features: Optional[Sequence[str]] = None) -> List[str]:
+    """Choose training features like the source notebook: numeric minus excluded columns."""
+    if user_features is not None:
+        missing = [c for c in user_features if c not in df.columns]
+        if missing:
+            raise ValueError(f"Requested feature columns not found: {missing}")
+        features = list(user_features)
+    else:
+        features = [c for c in df.columns if c not in EXCLUDED_COLS and pd.api.types.is_numeric_dtype(df[c])]
+    if not features:
+        raise ValueError("No numeric feature columns are available after exclusions")
+    return features
+
+
+def validate_for_training(df: pd.DataFrame, feature_cols: Sequence[str], lookback: int, horizons: Sequence[int], min_windows: int = 5) -> None:
+    if len(df) < lookback + min(horizons):
+        raise ValueError(f"Not enough rows for lookback={lookback} and horizons={list(horizons)}")
+    for required in ["station_code", "date", "discharge_m3s", "target_lowflow"]:
+        if required not in df.columns:
+            raise ValueError(f"Required column missing after cleaning: {required}")
+    y = df["target_lowflow"].dropna().astype(int)
+    if y.nunique() < 2:
+        raise ValueError(
+            "target_lowflow contains only one class. Check target distribution, threshold, or use more representative data."
+        )
+    feats = df[list(feature_cols)].replace([np.inf, -np.inf], np.nan)
+    if feats.isna().all().all():
+        raise ValueError("All feature values are NaN")
+    variances = feats.var(numeric_only=True).fillna(0)
+    if float(variances.sum()) <= 1e-12:
+        raise ValueError("All selected features are constant. Training would produce unreliable or constant predictions.")
+
+
+def fit_transform_features(df: pd.DataFrame, feature_cols: Sequence[str], scaler: Optional[StandardScaler] = None) -> Tuple[pd.DataFrame, StandardScaler]:
+    """Fit or apply a StandardScaler to feature columns only."""
+    out = df.copy()
+    if scaler is None:
+        scaler = StandardScaler()
+        out[list(feature_cols)] = scaler.fit_transform(out[list(feature_cols)])
+    else:
+        out[list(feature_cols)] = scaler.transform(out[list(feature_cols)])
+    return out, scaler
+
+
+def make_windows(
+    df: pd.DataFrame,
+    feature_cols: Sequence[str],
+    lookback: int = 30,
+    horizon: int = 7,
+    window_mode: str = "per_station",
+) -> Tuple[np.ndarray, np.ndarray]:
+    """Create sliding windows.
+
+    ``per_station`` prevents mixing rows between stations. ``legacy_global``
+    reproduces the original notebook's global row-order behavior.
+    """
+    if lookback <= 0 or horizon <= 0:
+        raise ValueError("lookback and horizon must be positive integers")
+    mode = window_mode.lower().strip()
+    Xs: List[np.ndarray] = []
+    ys: List[float] = []
+
+    def append_from_frame(frame: pd.DataFrame) -> None:
+        X = frame[list(feature_cols)].to_numpy(dtype=np.float32)
+        y = frame["target_lowflow"].to_numpy(dtype=np.float32)
+        n = len(frame) - lookback - horizon + 1
+        for idx in range(max(0, n)):
+            Xs.append(X[idx : idx + lookback])
+            ys.append(float(y[idx + lookback + horizon - 1]))
+
+    if mode == "per_station":
+        for _, group in df.sort_values(["station_code", "date"]).groupby("station_code", sort=False):
+            append_from_frame(group)
+    elif mode == "legacy_global":
+        append_from_frame(df.sort_values(["station_code", "date"]))
+    else:
+        raise ValueError("window_mode must be 'per_station' or 'legacy_global'")
+
+    if not Xs:
+        return np.empty((0, lookback, len(feature_cols)), dtype=np.float32), np.empty((0,), dtype=np.float32)
+    return np.stack(Xs).astype(np.float32), np.asarray(ys, dtype=np.float32)