Skip to content

Seasonality, ARMA and meboot: close the port gaps against R 13.3 - #150

Closed
gitRasheed wants to merge 9 commits into
rasheed/partial-momentsfrom
rasheed/timeseries
Closed

gitRasheed wants to merge 9 commits into
rasheed/partial-momentsfrom
rasheed/timeseries

Conversation

@gitRasheed

@gitRasheed gitRasheed commented Nov 2, 2026 •

Copy link
Copy Markdown
Collaborator

nns_seas, nns_arma, nns_meboot and nns_mc differed from R 13.3 on odd-length series, tied periods, interval construction and vector drift arguments, and several invalid arguments gave silent wrong results or raw IndexErrors. Each change brings Python to R 13.3.

Stacked on #149; merge with a merge commit.

Changes

  • nns_seas keeps a period only if Period < n/2 under integer division, as R does. For a period-3 series of length 13, Python returned periods [3, 6, 1] and R [3, 1]. Only odd n changes.
  • nns_seas orders tied CVs by insertion order, as R's sort does. A length-10 alternating series with modulo=[7, 12] and mod_only=False now picks best period 2, as in R, instead of 1.
  • The nns_seas CV scan is vectorised with bit-identical CVs. n = 1e5 goes from 0.74 s to 0.10 s (R 0.33 s). A series with mean exactly 0 and lag-1 autocorrelation 0 raised ZeroDivisionError; it now gives R's Inf.
  • nns_arma(method="lin") with one lag and pred_int raised TypeError. It now returns R's Estimates/Lower/Upper table, and lin.resid equals R's on AirPassengers for (lag, h) = (12, 12), (12, 5) and (7, 20).
  • Nonlin intervals with several lags include lin.resid, as R does. For AirPassengers with lags [12, 24], lin.resid is 3.35757575757577, equal to R, and the mean band width over seeds 1-5 goes from 248.4 to 255.1 (R 258.2).
  • nns_meboot keeps the level expand_sd step with xmin/xmax unless force_clt is set, as NNS_meboot.R:158-159 does. Defaults are unaffected.
  • nns_meboot recycles rho, target_drift and target_drift_scale like R's Vectorize, so target_drift=[1, 7] returns one result per drift instead of raising. In nns_mc, a given target_drift takes precedence over target_drift_scale, as in R's NNS.MC.
  • nns_arma validates training_set, numeric lags and the weights length, and treats seasonal_factor=None as R's NULL. h = 1 with pred_int works, and nns_arma_optim(pred_int=None) returns empty bounds like R's numeric(0). Valid inputs give the same results.
  • conventions.md no longer claims R weights numeric multi-lag seasonal factors by reverse steps; R 13.3 and Python both use seasonal.factor[i].

Tests

New parity tests and cache entries for NNS.seas, NNS.ARMA.pred_int and NNS.ARMA.optim.custom, an invariant pinning the vectorised seasonal statistics to a transcription of R's cv_or_fallback, and invariants for the ARMA validation, meboot and MC changes. The parity cache encodes unpatched R 13.3.

Review

GPT-6.1 Sol reviewed this slice and raised one finding, which we rejected: a single-step forecast's lower interval still takes abs() of the lower quantile. That matches R 13.3 here, and #173 drops the abs() as OVVO-Financial/NNS#87 does. At the top of the stack the reviewer's case gives -10.9115.

R's NNS_seas.cpp keeps a period only if Period < n/2 with C++ integer
division, so for odd n the period floor(n/2) (two points per subsample) is
dropped. Python compared against the float n/2.0 and kept it.

Example: c(1,2,3,1,2,3,1,2,3,1,2,3,1) (n = 13) gave periods [3, 6, 1] in
Python and [3, 1] in R. For N(10, 1) noise (seed 4) with n = 21 the best
period was 10 in Python and 1 in R; with n = 201 it was 100 vs 94.

Changes public results only for odd-length series where floor(n/2) passed
the CV test; Python now matches R on those. Even n is unaffected.
R sorts the period table on the CV only (std::sort, which for 16 or fewer
rows is libstdc++'s insertion sort and keeps tied rows in insertion order).
Python used np.lexsort((periods, coef)), breaking CV ties by ascending
period. Tied rows are common: every modulo-added period and the period-1
row carry CV = VarCV.

Example: c(-1,1,-1,1,...) (n = 10) with modulo = c(7,12), mod.only = FALSE
gave best.period 1 in Python and 2 in R. With a stable argsort on the CV
Python now gives 2.

For tables of more than 16 rows R uses introsort, whose tie order is
implementation-defined; the stable sort keeps Python deterministic there.
Only the order of exactly tied periods changes.
The period scan ran per-element Python loops for every subsample mean and
sd (n * H(n/2) * 3 iterations). Periods whose reverse-stride subsamples have
the same length are now gathered into one matrix and reduced with
np.cumsum along the rows. cumsum accumulates sequentially like the C++
loops in R's NNS_seas.cpp (np.sum would use pairwise summation), so every
CV is bit-identical to before: 264 series x {no modulo, modulo 12,
modulo c(7,12) mod.only FALSE} compared with np.array_equal, including 21
exactly zero-mean (acf fallback) cases. A new invariant test pins the
vectorised statistics to an element-by-element transcription of R's
cv_or_fallback.

Removed dead code: _mean and _mean_exact were identical, so the exact_cv
flag and the "recompute if within 1e-12 of VarCV" branch recomputed the same
value; _cv_or_fallback duplicated _cv_stat; _sample_sd and _reverse_step were
unused.

Also fixes a crash: a series with mean exactly 0 and lag-1 autocorrelation
exactly 0 (e.g. c(2,0,0,-2,0)) raised ZeroDivisionError from 0.0 ** -1.0.
R's pow(0, -1) gives Inf; Python now does too and matches R (parity tests
added). libm pow is kept for 1/|acf| because 1/x differs from it in the
last bit for about 0.1% of inputs.

Timings (N(10,1), one call, cache cleared):
  n = 1e3: 0.0049 s -> 0.0035 s   (R 0.002 s)
  n = 1e4: 0.072 s  -> 0.018 s    (R 0.006 s)
  n = 1e5: 0.74 s   -> 0.10 s     (R 0.33 s)

Public results are unchanged apart from the former ZeroDivisionError case.
nns_arma(method="lin", seasonal_factor=<one lag>, pred_int=p) raised
TypeError("non-numeric argument to binary operator"), imitating an old R
failure. R 13.3 returns the Estimates / Lower / Upper table for this, the
forecasting vignette's headline configuration (lin, sf = 12) plus intervals.

The vectorised lin branch now returns its per-component regression
forecasts as well and feeds them to the same interval code as the
recursive branch. As in R, lin.resid is mean(abs(e - mean(e))) over
unlist(Lin.Regression.Estimates), the unweighted component forecasts in
component order. For AirPassengers it equals R's value exactly for
(lag, h) = (12, 12), (12, 5) and (7, 20): 64.4107744107744,
25.5733333333333, 14.9639735702894.

Point forecasts are unchanged. The invariant test that pinned the old
TypeError now checks the returned intervals; an exactly linear series still
fails in meboot with R's message.
R's recursive loop runs the per-lag linear fits when method is lin, both or
means, *or* when pred.int is numeric (ARMA.R:250), and the interval
residual lin.resid = mean(abs(e - mean(e))) is taken from the last step's
linear forecasts e. Python skipped the linear fits for method="nonlin", so
lin.resid was always 0 and nonlin bands were too narrow whenever more than
one lag is used (with one lag e has a single element and lin.resid is 0 on
both sides).

AirPassengers, h = 12, seasonal_factor = [12, 24], method = "nonlin",
pred_int = 0.95: lin.resid is now 3.35757575757577 (R: 3.35757575757577,
reconstructed from R's generate.vectors/fast_lm on the extended series).
Mean band width over seeds 1-5: R 258.2, Python before 248.4, after 255.1.

Point forecasts are unchanged; only nonlin intervals with several lags
widen. The linear fits are only added when pred_int is given.
R disables the level-scale sd expansion for user bounds only inside
if (isTRUE(force.clt)) { expand.sd <- FALSE; force.clt <- FALSE }
(NNS_meboot.R:158-159). Python turned expand_sd and force_clt off whenever
xmin or xmax was given, so nns_meboot(x, xmin=0, force_clt=False,
expand_sd=True) skipped the expansion that R applies.

The level expansion only rescales replicates whose sd is below sd(x), so
the effect is small: on AirPassengers and monthly VIX (reps = 200,
rho = 0.5, xmin = 0, force_clt = False) the median replicate sd is the same
before and after (134.05 vs R 133.98; 6.603 vs R 6.617). A test checks
that the level step now runs in that configuration and is still skipped
with force_clt=True. Defaults (force_clt=True) are unaffected.
R wraps NNS.meboot in Vectorize(vectorize.args = c("rho", "target_drift",
"target_drift_scale")), so the documented example
NNS.meboot(x, rho = 0, target_drift = c(1, 7)) returns one result per drift.
Python only vectorised rho; a list target_drift reached
intercept + recon_slope * time and raised "operands could not be broadcast",
and a list target_drift_scale raised TypeError. nns_mc passed both through
and failed the same way.

nns_meboot now recycles rho, target_drift and target_drift_scale elementwise
to the longest length, as mapply does (pairs, not a cross product), warns
like R when the lengths are not multiples, and returns a list (a single dict
when every argument has length 1, as before). Results are produced in order
from one generator, so scalar calls are unchanged.

nns_mc: as in R's NNS.MC, a given target_drift now takes precedence and
target_drift_scale is ignored (Python let the scale win). A drift vector
longer than the rho grid is rejected instead of failing in zip().

AirPassengers, rho = 0, ensemble slope (reps = 5):
  target_drift = c(1, 7):         R 2.445 7.483   Python 2.433 7.457
  target_drift_scale = c(.5, 2):  R 2.559 5.785   Python 2.571 5.772
NNS.MC(x, by = 1, target_drift = c(1, 7)) gives the same replicate names
and the same recycling warning on both sides.
Argument gaps that gave silent wrong results or raw IndexError/TypeError
(AirPassengers unless noted; R 13.3 behaviour in brackets):

- training_set outside 1..n: 200 silently used the whole series, 0 raised
  IndexError [R errors for both]. Now ValueError.
- Series too short for automatic seasonality (n < 5 with
  seasonal_factor True/False, e.g. c(1,2) or c(1,2,3)): IndexError
  "index -1 is out of bounds" [R: "[y] must contain at least two
  observations." for nonlin/both, NaN for lin, 0 for means]. Now a
  ValueError that points to a numeric seasonal_factor; n < 2 is rejected
  for every configuration. Short series with a numeric lag still work
  (c(1,2,4), sf = 1: 5.8333333333333339 7.6401515151515156, as R).
- Numeric lags < 1 or > n: sf = 0 raised "slice step cannot be zero",
  sf = 200 raised IndexError [R errors]. Now ValueError.
- seasonal_factor = None raised TypeError from int(None). R treats NULL
  as FALSE (best.periods given), so Python now does too
  (317.5 392.25 on both sides); a string raises a clear TypeError.
- weights whose length differs from the number of lags were broadcast
  (weights = [1] with lags [12, 24] doubled the forecast) or failed inside
  NumPy. Now ValueError naming the lags.
- h = 1 with pred_int raised "incorrect number of dimensions", copying an R
  crash. A single forecast has no path for NNS.MC to bootstrap (meboot of
  one value returns the value), so the band is the estimate widened by
  lin.resid.
- nns_arma_optim(pred_int=None) raised TypeError. R 13.3 returns results
  with numeric(0) bounds; Python now returns empty arrays and the same
  results (parity test added). The optim plot skips the band then.
- bias.shift was returned as -0.0 when no bias was applied; now 0.0.

Results for valid inputs are unchanged.
- conventions.md: drop the paragraph claiming installed R weights numeric
  multi-lag seasonal factors by reverse steps 1:length(seasonal.factor) and
  that a strict xfail covers it. R 13.3 (ARMA.R:111) uses
  seasonal.factor[i]; Python matches it (seasonal_factor=[132, 276] and
  [12, 24, 36] agree with R exactly) and no such xfail exists.
- Same for the api_status.md table row and practical-examples note.
- Document the new nns_arma argument validation, seasonal_factor=None,
  h=1 intervals, nns_arma_optim(pred_int=None), and the nns_meboot
  vectorisation over target_drift / target_drift_scale.
@github-actions

github-actions Bot commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

Incorporated through NNS R 14.0 integration #192, merged as bd19c3303222af46da79d8c97f258248eb5674d2. Verified exact head 7f0654d583095ef70ae10d01e3fb35747c2eff3c is an ancestor of main; original commits and authorship are preserved. The integration includes the subsequent R14 compatibility corrections and passed the complete GitHub Python 3.11-3.14 matrix. This supersedes the separate landing, not the work or review history.

@github-actions github-actions Bot closed this Nov 7, 2026
@github-actions
github-actions Bot deleted the rasheed/timeseries branch November 7, 2026 18:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant