---
title: "Lag-window KAN forecasting with thangldKANr"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Lag-window KAN forecasting with thangldKANr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

```{r}
library(thangldKANr)
```

## Model

A Temporal KAN here is a Kolmogorov-Arnold Network applied to a
window of lagged values: for lags $\ell_1, \dots, \ell_p$ the input at time
$t$ is $(y_{t-\ell_1}, \dots, y_{t-\ell_p})$ and the target is $y_t$. With the
default basis each edge function is $\phi(u) = \sum_{k=0}^{K} c_k T_k(\tanh u)$
(any basis of `kan_bases()` can be chosen with `basis`) on the
standardized lags. With no hidden layer the model is an additive nonlinear
autoregression; hidden layers add interactions between lags. Optional
`log = TRUE` and `difference = TRUE` transform the series before windowing
and are inverted for forecasts.

The model is a forecasting tool, not a recurrent network: there is no state
carried across windows, and `predict()` gives one-step-ahead forecasts only.

## Leakage rules

* Windows are built from past values only (`thangld_temporal_kan_embed()`).
* The standardization constants are estimated on the training windows only;
  the last `n_val` windows (in time order) are held out for early stopping.
* `thangld_temporal_kan_rolling()` refits on $y_{1:t_0}$ for an origin $t_0$ and never
  uses a value after $t_0$ for that origin's forecast.

## Example: Canadian lynx (log scale)

The base R backend (`backend = "r"`) is used so the vignette builds without
libtorch; `backend = "torch"` follows the same trajectory in double precision.

```{r}
y <- log(as.numeric(datasets::lynx))
m <- thangld_temporal_kan(lags = 1:3, degree = 4, seed = 1)
m
fit <- thangld_temporal_kan_fit(m, y[1:100], n_val = 15, epochs = 150, lr = 0.02,
                        batch_size = 32, patience = 40, seed = 1, backend = "r")
fit$train$best_epoch
predict(fit)   # forecast of y[101]
y[101]
```

## Rolling-origin evaluation against baselines

Every origin from 100 to 113 forecasts the next value; the network is refitted
every 5 origins (expanding window). The naive forecast is the benchmark that a
forecasting model has to beat.

```{r}
r <- thangld_temporal_kan_rolling(thangld_temporal_kan(1:3, seed = 1), y, initial = 100,
                          refit_every = 5, n_val = 15, epochs = 100,
                          lr = 0.02, patience = 40, seed = 1, backend = "r")
r$metrics
```

```{r, fig.width = 6, fig.height = 3.5}
fc <- r$forecasts
plot(fc$index, fc$actual, type = "b", pch = 16, xlab = "t", ylab = "log lynx")
lines(fc$index, fc$kan, type = "b", col = 2)
lines(fc$index, fc$naive, type = "b", col = 4, lty = 2)
legend("topleft", c("actual", "temporal KAN", "naive"), col = c(1, 2, 4),
       lty = c(1, 1, 2), bty = "n")
```

The result above is a small illustration with 14 origins; it is not evidence
that the model beats simple methods on this series. A longer comparison with
naive, seasonal naive, Holt-Winters and a linear autoregression is in
`system.file("benchmarks", package = "thangldKANr")`.

## Validation

`thangld_temporal_kan_validate()` checks windows, scaling, the basis, analytic
against finite-difference gradients and the torch backend against the base R
oracle. The bundled reference test compares training on log lynx with
ChebyKAN (commit `5f7efdd`) run on lag windows that Python built itself.

```{r}
v <- thangld_temporal_kan_validate("r")
table(v$status)
```
