Module 301 — Code structure for quantitative modelling systems

import json
import os
from dataclasses import dataclass
from datetime import datetime

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt

# -----------------------------
# 1) Data layer
# -----------------------------
def make_synthetic_series(T: int, seed: int) -> pd.DataFrame:
    rng = np.random.default_rng(seed)
    t = np.arange(T)

    # weak persistence + seasonality + regime change noise
    season = 0.4 * np.sin(2 * np.pi * t / 5)
    sigma = np.ones(T) * 0.7
    sigma[T // 2:] = 1.4

    y = np.zeros(T)
    for k in range(1, T):
        y[k] = 0.25 * y[k - 1] + season[k] + sigma[k] * rng.normal()

    idx = pd.date_range("2024-01-01", periods=T, freq="B")
    return pd.DataFrame({"y": y}, index=idx)

# -----------------------------
# 2) Feature layer
# -----------------------------
def build_features(df: pd.DataFrame, cfg: dict) -> pd.DataFrame:
    d = df.copy()
    lags = cfg["features"]["lags"]
    for L in lags:
        d[f"lag{L}"] = d["y"].shift(L)

    # target horizon
    h = cfg["target"]["horizon"]
    d["y_target"] = d["y"].shift(-h)

    # drop NA created by lags/target shift
    d = d.dropna().copy()
    return d

# -----------------------------
# 3) Model layer (fit/predict/score)
# -----------------------------
@dataclass
class OLSModel:
    feature_cols: list
    beta: np.ndarray | None = None

    def fit(self, train: pd.DataFrame) -> "OLSModel":
        X = np.column_stack([np.ones(len(train))] + [train[c].values for c in self.feature_cols])
        y = train["y_target"].values
        self.beta = np.linalg.lstsq(X, y, rcond=None)[0]
        return self

    def predict(self, data: pd.DataFrame) -> np.ndarray:
        if self.beta is None:
            raise RuntimeError("Model is not fitted.")
        X = np.column_stack([np.ones(len(data))] + [data[c].values for c in self.feature_cols])
        return X @ self.beta

    def score(self, data: pd.DataFrame) -> dict:
        y_true = data["y_target"].values
        y_hat = self.predict(data)
        rmse = float(np.sqrt(np.mean((y_true - y_hat) ** 2)))
        mae = float(np.mean(np.abs(y_true - y_hat)))
        return {"rmse": rmse, "mae": mae}

# -----------------------------
# 4) Evaluation layer (rolling CV)
# -----------------------------
def rolling_folds(n: int, L_train: int, B_test: int):
    starts = list(range(0, n - (L_train + B_test) + 1, B_test))
    return [(s, s + L_train, s + L_train + B_test) for s in starts]

def evaluate(model_cls, df_feat: pd.DataFrame, cfg: dict) -> pd.DataFrame:
    L_train = cfg["split"]["train_len"]
    B_test = cfg["split"]["test_len"]

    folds = rolling_folds(len(df_feat), L_train, B_test)
    rows = []

    for i, (a, b, c) in enumerate(folds, start=1):
        tr = df_feat.iloc[a:b]
        te = df_feat.iloc[b:c]

        model = model_cls(feature_cols=cfg["features"]["cols"]).fit(tr)
        metrics = model.score(te)

        rows.append({
            "fold": i,
            "test_start": str(te.index.min().date()),
            "test_end": str(te.index.max().date()),
            **metrics
        })

    return pd.DataFrame(rows)

# -----------------------------
# 5) Reporting layer (plots + artefacts)
# -----------------------------
def make_run_dir(base_dir="runs") -> str:
    ts = datetime.now().strftime("%Y-%m-%d_%H%M%S")
    run_dir = os.path.join(base_dir, f"{ts}_run")
    os.makedirs(os.path.join(run_dir, "plots"), exist_ok=True)
    return run_dir

def save_json(path: str, obj: dict):
    with open(path, "w", encoding="utf-8") as f:
        json.dump(obj, f, indent=2)

def report(run_dir: str, cfg: dict, fold_df: pd.DataFrame):
    # Save config snapshot
    save_json(os.path.join(run_dir, "config.json"), cfg)

    # Save fold metrics
    fold_path = os.path.join(run_dir, "fold_metrics.csv")
    fold_df.to_csv(fold_path, index=False)

    # Aggregate metrics
    summary = {
        "rmse_mean": float(fold_df["rmse"].mean()),
        "rmse_std": float(fold_df["rmse"].std(ddof=0)),
        "mae_mean": float(fold_df["mae"].mean()),
        "n_folds": int(len(fold_df)),
    }
    save_json(os.path.join(run_dir, "metrics.json"), summary)

    # Plot RMSE by fold
    plt.figure(figsize=(7.5, 3.5))
    plt.plot(fold_df["fold"], fold_df["rmse"], marker="o")
    plt.title("Rolling CV: RMSE by fold")
    plt.xlabel("Fold")
    plt.ylabel("RMSE")
    plt.tight_layout()
    plt.savefig(os.path.join(run_dir, "plots", "rmse_by_fold.png"))
    plt.show()

    # Minimal notes for handover
    notes = [
        "# Run notes",
        f"- Target horizon: {cfg['target']['horizon']}",
        f"- Features: {cfg['features']['cols']}",
        f"- Split: rolling train_len={cfg['split']['train_len']}, test_len={cfg['split']['test_len']}",
        f"- RMSE mean: {summary['rmse_mean']:.4f}",
        "",
        "Safe usage statement:",
        "- This run is a baseline evidence pack for structure and reproducibility.",
        "- Do not interpret as production performance.",
    ]
    with open(os.path.join(run_dir, "notes.md"), "w", encoding="utf-8") as f:
        f.write("\n".join(notes))

    return summary

# -----------------------------
# 6) Runner (configuration-driven)
# -----------------------------
cfg = {
    "seed": 123,
    "data": {"T": 700},
    "target": {"horizon": 1},
    "features": {
        "lags": [1, 2, 3, 5],
        "cols": ["lag1", "lag2", "lag3", "lag5"]
    },
    "split": {"train_len": 240, "test_len": 60},
}

df_raw = make_synthetic_series(T=cfg["data"]["T"], seed=cfg["seed"])
df_feat = build_features(df_raw, cfg)

run_dir = make_run_dir()
fold_df = evaluate(OLSModel, df_feat, cfg)
summary = report(run_dir, cfg, fold_df)

print("Run directory:", run_dir)
print("Summary:", summary)