pystatistics 4.6.0__tar.gz → 4.6.2__tar.gz

pystatistics-4.6.2/.release/UNRELEASED.md

@@ -0,0 +1,12 @@
+# Unreleased Changes
+
+> This file tracks all changes since the last stable release.
+> Updated by whoever makes a change, on whatever machine.
+> Synced via git so all sessions (Mac, Linux, etc.) see the same state.
+>
+> When ready to release, run: `python .release/release.py --status`
+> and follow the manual release flow in the script docstring.
+
+## Changes
+
+*(empty — no unreleased changes yet)*

{pystatistics-4.6.0 → pystatistics-4.6.2}/CHANGELOG.md

@@ -1,5 +1,108 @@
 # Changelog
 
+## 4.6.2
+
+STL decomposition rewritten to match R exactly and now as fast as R's
+compiled implementation; ETS gains automatic model selection and R-matched
+parameter estimation; `ndiffs` default aligned with R.
+
+- **`stl()` returned a materially wrong decomposition on trending series —
+  fixed by a full rewrite.** On strongly trending data (e.g. the monthly CO2
+  benchmark) the previous implementation leaked much of the trend into the
+  seasonal component: the extracted "seasonal" had a range of ~83 where the
+  true seasonal amplitude is ~6, and the reported trend could *decrease* while
+  the data rose — the components always summed back to the data, so the error
+  was invisible without an external reference. `stl()` is now an exact
+  implementation of the STL procedure (Cleveland, Cleveland, McRae &
+  Terpenning, 1990) and reproduces R's `stats::stl` component-for-component:
+  across a reference suite (CO2, AirPassengers, monthly sunspots, lynx, Nile;
+  periodic, robust, custom-window, and partial-period variants) the largest
+  seasonal/trend/remainder difference vs R is below 1e-10.
+- **`stl()` now exposes the full STL parameter set and uses R's defaults.**
+  New parameters: `seasonal_degree` (default 0, as in R — previously the
+  seasonal smoother was effectively degree 1), `trend_degree`,
+  `lowpass_window`, `lowpass_degree`, and the evaluation strides
+  `seasonal_jump` / `trend_jump` / `lowpass_jump` (R's `ceiling(window/10)`
+  defaults; set to 1 to evaluate the loess at every point instead of
+  interpolating). Behaviour changes: `seasonal_window` defaults to
+  `"periodic"` (R has no default and `"periodic"` is the standard published
+  choice); `robust=True` now runs R's iteration counts (1 inner, 15 outer
+  passes); the series must be longer than `2 * period` (R's rule); and window
+  spans must be odd integers >= 3 — even spans raise a `ValidationError`
+  where R silently rounds them up. The result's `info` now reports the
+  resolved windows/degrees/jumps and the final robustness weights.
+- **`stl()` now matches R's speed.** The smoother is compiled with `numba`,
+  so it is as fast as R's Fortran `stats::stl` — non-robust decompositions
+  run faster than R and robust decompositions match it (previously it was
+  3-15x slower). Results are unchanged (still within 1e-10 of R). The
+  compiled kernel builds on first use in a session (a few seconds, once) and
+  is cached on disk for subsequent runs, the same one-time cost the ARIMA
+  routines already carry.
+- **`ets()` now performs automatic model selection, matching
+  `forecast::ets`.** The model string accepts a `"Z"` wildcard per component
+  and defaults to `model="ZZZ"` (select everything), as in R. Candidates
+  consistent with the fixed letters are enumerated under R's rules (additive
+  error with multiplicative season excluded; multiplicative components
+  require strictly positive data; seasonal candidates need `2 <= period <=
+  24` and enough data), each is fitted, and the model minimising the new `ic`
+  parameter (`"aicc"` default, `"aic"`, `"bic"`) is returned. The full
+  candidate table, the criterion values, and any skipped candidates with
+  reasons are disclosed in `solution.info["selection"]`. Explicit requests
+  that cannot be honoured (e.g. `model="MZZ"` on data with zeros or
+  negatives, a seasonal letter with `period=1`) raise instead of being
+  silently adjusted. A fully specified model string (no `"Z"`) is always
+  fitted exactly as written. Note two consequences of the new default:
+  automatic AICc selection needs at least 5 observations (shorter series
+  raise with a suggested remedy — pick a concrete model or `ic="aic"`), and
+  `period` must now be a true integer (float periods raise a clear error
+  instead of crashing).
+- **ETS parameter estimation aligned with `forecast::ets` (changes fitted
+  results).** The optimiser now searches R's parameter region exactly — the
+  smoothing parameters obey `beta <= alpha` and `gamma <= 1 - alpha`, the
+  damping `phi` is bounded to `[0.8, 0.98]`, and a seasonal model estimates
+  one fewer initial state (the last is fixed by the seasonal normalisation,
+  as in R). As a result the reported parameter count `k` for seasonal models
+  now matches R's, so AIC/AICc/BIC values line up with `forecast::ets`, and
+  fitted parameters/log-likelihoods for a given model can differ slightly
+  from earlier versions. Smoothing parameters fixed outside R's region now
+  raise a clear error instead of being quietly clamped. On automatic
+  selection the chosen model still occasionally differs from `forecast::ets`
+  on near-tied candidate tables, but now only because the two optimisers land
+  on different optima — in every such case the model this package selects
+  scores at least as well under R's own criterion; the disclosed candidate
+  table makes any selection auditable.
+- **`ets()` no longer emits a spurious `RuntimeWarning` about overflow.** A
+  benign internal overflow warning could surface during fitting on some
+  series; the computation was always correct, and the warning is now gone.
+  Fitted results are unchanged.
+- **`ndiffs()` now defaults to the KPSS test, matching `forecast::ndiffs`.**
+  KPSS and ADF have opposite null hypotheses and can recommend a different
+  number of differences on borderline series; pass `test="adf"` for the
+  previous behaviour. Both tests are numerically unchanged.
+- **ETS log-likelihood reporting convention documented (no numeric
+  change).** `ets()` reports the full Gaussian log-likelihood; R's
+  `forecast::ets` prints Hyndman's concentrated form. The two differ by the
+  exact constant `0.5*n*[log(n/(2*pi)) - 1]` (e.g. 88.36 at n=100) with the
+  same parameter count, so AIC/AICc/BIC differences, model rankings, and
+  automatic selection are identical — only the printed numbers differ. The
+  convention is now stated on the result's `log_likelihood`/`aic`/`aicc`/
+  `bic` accessors.
+
+## 4.6.1
+
+Performance: faster automatic smoothing-parameter selection for Gaussian
+additive models with more than one smooth term.
+
+- `gam()` with the default Gaussian family now selects its smoothing parameters
+  using an exact analytic gradient of the GCV/REML criterion instead of a
+  finite-difference approximation. The old search cost grew with the number of
+  smooth terms; the new one does not. On a 2000-point cubic-regression-spline
+  benchmark the fit is roughly 2× faster with four smooths and 3× faster with
+  six. The selected model is unchanged — same smoothing parameters, effective
+  degrees of freedom, coefficients and fitted values as before. Single-smooth
+  fits and generalized (Poisson, binomial, Gamma) additive models are
+  unaffected.
+
 ## 4.6.0
 
 Generalized additive models (`gam()`) received a full numerical rewrite. The

{pystatistics-4.6.0 → pystatistics-4.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pystatistics
-Version: 4.6.0
+Version: 4.6.2
 Summary: GPU-accelerated statistical computing for Python
 Project-URL: Homepage, https://sgcx.org/technology/pystatistics/
 Project-URL: Documentation, https://sgcx.org/docs/pystatistics/
@@ -418,6 +418,35 @@ pip install pystatistics[dev]
 
 ## What's New
 
+### 4.6.2 — STL matches R exactly and runs as fast; ETS automatic model selection
+
+`stl()` was rewritten after validation showed it leaking trend into the
+seasonal component on trending series (on the monthly CO2 benchmark the old
+"seasonal" had a range of ~83 where the truth is ~6). It is now an exact
+implementation of the STL procedure and reproduces R's `stats::stl`
+component-for-component (differences below 1e-10 across a reference suite
+including robust fits), with the full STL parameter set exposed
+(`seasonal_degree`, `trend_degree`, `lowpass_window`, jumps, and a
+`"periodic"` default seasonal window). The smoother is compiled, so it now
+runs as fast as R's Fortran implementation — faster for non-robust
+decompositions, on par for robust ones. `ets()` now auto-selects its model
+like `forecast::ets`: the new default `model="ZZZ"` tries every admissible
+error/trend/season combination and returns the best by AICc, with the full
+candidate table disclosed on the result; explicit component requests that
+cannot be honoured raise instead of being silently adjusted. ETS parameter
+estimation now matches R's parameter region as well, so fitted parameters
+and information criteria (AIC/AICc/BIC) line up with `forecast::ets`.
+`ndiffs()` now defaults to the KPSS test, matching `forecast::ndiffs`.
+
+### 4.6.1 — faster multi-smooth Gaussian GAMs
+
+`gam()` with the default Gaussian family now selects its smoothing parameters
+with an exact analytic gradient of the GCV/REML criterion instead of finite
+differences, so fits with several smooth terms no longer slow down as terms are
+added — about 2× faster with four smooths and 3× with six on a typical fit.
+Estimates are unchanged, and single-smooth and generalized (Poisson, binomial,
+Gamma) additive models are unaffected.
+
 ### 4.6.0 — generalized additive models rewritten to match `mgcv`
 
 `gam()` received a full numerical rewrite. Automatic smoothing-parameter

{pystatistics-4.6.0 → pystatistics-4.6.2}/README.md

@@ -371,6 +371,35 @@ pip install pystatistics[dev]
 
 ## What's New
 
+### 4.6.2 — STL matches R exactly and runs as fast; ETS automatic model selection
+
+`stl()` was rewritten after validation showed it leaking trend into the
+seasonal component on trending series (on the monthly CO2 benchmark the old
+"seasonal" had a range of ~83 where the truth is ~6). It is now an exact
+implementation of the STL procedure and reproduces R's `stats::stl`
+component-for-component (differences below 1e-10 across a reference suite
+including robust fits), with the full STL parameter set exposed
+(`seasonal_degree`, `trend_degree`, `lowpass_window`, jumps, and a
+`"periodic"` default seasonal window). The smoother is compiled, so it now
+runs as fast as R's Fortran implementation — faster for non-robust
+decompositions, on par for robust ones. `ets()` now auto-selects its model
+like `forecast::ets`: the new default `model="ZZZ"` tries every admissible
+error/trend/season combination and returns the best by AICc, with the full
+candidate table disclosed on the result; explicit component requests that
+cannot be honoured raise instead of being silently adjusted. ETS parameter
+estimation now matches R's parameter region as well, so fitted parameters
+and information criteria (AIC/AICc/BIC) line up with `forecast::ets`.
+`ndiffs()` now defaults to the KPSS test, matching `forecast::ndiffs`.
+
+### 4.6.1 — faster multi-smooth Gaussian GAMs
+
+`gam()` with the default Gaussian family now selects its smoothing parameters
+with an exact analytic gradient of the GCV/REML criterion instead of finite
+differences, so fits with several smooth terms no longer slow down as terms are
+added — about 2× faster with four smooths and 3× with six on a typical fit.
+Estimates are unchanged, and single-smooth and generalized (Poisson, binomial,
+Gamma) additive models are unaffected.
+
 ### 4.6.0 — generalized additive models rewritten to match `mgcv`
 
 `gam()` received a full numerical rewrite. Automatic smoothing-parameter

{pystatistics-4.6.0 → pystatistics-4.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pystatistics"
-version = "4.6.0"
+version = "4.6.2"
 description = "GPU-accelerated statistical computing for Python"
 readme = "README.md"
 license = "MIT"

{pystatistics-4.6.0 → pystatistics-4.6.2}/pystatistics/__init__.py

@@ -16,7 +16,7 @@ Usage:
     result = fit(design)
 """
 
-__version__ = "4.6.0"
+__version__ = "4.6.2"
 __author__ = "Hai-Shuo"
 __email__ = "contact@sgcx.org"
 

{pystatistics-4.6.0 → pystatistics-4.6.2}/pystatistics/gam/_criteria.py

@@ -33,6 +33,7 @@ from scipy.optimize import minimize
 
 from pystatistics.core.exceptions import ValidationError
 from pystatistics.gam._edf import influence_matrix, logdet_penalized, total_edf
+from pystatistics.gam._gradient import gcv_gradient, reml_gradient_gauss
 from pystatistics.gam._pirls import (
     PenaltyRoot,
     PirlsFit,
@@ -235,6 +236,33 @@ def select_lambdas(
             return ubre_score(fit.deviance, n, edf, scale=1.0)
         return gcv_score(fit.deviance, n, edf)
 
+    # Analytic-gradient path (Gaussian-identity only): the constant IRLS
+    # weights make the criterion an exact closed form of log(lambda), so the
+    # outer L-BFGS-B is driven by the analytic gradient (one inner fit per
+    # step) instead of scipy's finite differences (2m+1 fits per step). GLM
+    # families keep the finite-difference `objective` above (their weights
+    # depend on beta -> an implicit d beta/d rho term not implemented here).
+    use_analytic = _is_gauss_identity(family)
+
+    def value_and_grad(
+        log_lam: NDArray[np.floating[Any]],
+    ) -> tuple[float, NDArray[np.floating[Any]]]:
+        lam = np.exp(np.asarray(log_lam, dtype=np.float64))
+        fit = fit_fixed_lambda(
+            y, X, roots, lam, family, tol_inner, max_iter,
+            smooth_names=smooth_names, gaussian_cache=gauss_cache,
+        )
+        edf = total_edf(influence_matrix(fit.R, fit.R_x, fit.piv, fit.rank))
+        if method_u == "REML":
+            return (
+                reml_score(fit, y, family, roots, lam),
+                reml_gradient_gauss(fit, roots, lam, n),
+            )
+        return (
+            gcv_score(fit.deviance, n, edf),
+            gcv_gradient(fit, roots, lam, n, edf),
+        )
+
     # REML support check up front (fail before burning optimizer time).
     if method_u == "REML" and not (
         family.dispersion_is_fixed or _is_gauss_identity(family)
@@ -257,28 +285,44 @@ def select_lambdas(
     # the same data in different units (panel-verified). Normalize by the
     # objective at the starting point so the same fit is selected at every
     # response scale.
-    f0 = objective(log_lam0)
+    f0 = value_and_grad(log_lam0)[0] if use_analytic else objective(log_lam0)
     ref = max(abs(f0), 1e-300)
 
-    def objective_scaled(log_lam: NDArray[np.floating[Any]]) -> float:
-        return objective(log_lam) / ref
-
-    # eps: the FD step must sit WELL above the inner P-IRLS convergence
-    # noise floor or the quasi-Newton curvature estimate is built from
-    # noise and the line search collapses short of the optimum (observed
-    # on the flat Gamma-log GCV surface: effective evaluation noise
-    # ~1e-9 relative even at tol_inner=1e-12, so eps=1e-6 gave gradient
-    # noise the SAME size as the true gradient). eps=1e-4 keeps gradient
-    # noise ~1e-5 while the induced position error (~eps/2 in log-lambda)
-    # is a ~0.005% sp perturbation — far inside the optimizer tolerance
-    # tier of the validation contract.
-    result = minimize(
-        objective_scaled,
-        log_lam0,
-        method="L-BFGS-B",
-        bounds=bounds,
-        options={"maxiter": 200, "ftol": 1e-12, "gtol": 1e-9, "eps": 1e-4},
-    )
+    if use_analytic:
+        def fun_scaled(
+            log_lam: NDArray[np.floating[Any]],
+        ) -> tuple[float, NDArray[np.floating[Any]]]:
+            val, grad = value_and_grad(log_lam)
+            return val / ref, grad / ref
+
+        result = minimize(
+            fun_scaled,
+            log_lam0,
+            method="L-BFGS-B",
+            jac=True,
+            bounds=bounds,
+            options={"maxiter": 200, "ftol": 1e-12, "gtol": 1e-9},
+        )
+    else:
+        def objective_scaled(log_lam: NDArray[np.floating[Any]]) -> float:
+            return objective(log_lam) / ref
+
+        # eps: the FD step must sit WELL above the inner P-IRLS convergence
+        # noise floor or the quasi-Newton curvature estimate is built from
+        # noise and the line search collapses short of the optimum (observed
+        # on the flat Gamma-log GCV surface: effective evaluation noise
+        # ~1e-9 relative even at tol_inner=1e-12, so eps=1e-6 gave gradient
+        # noise the SAME size as the true gradient). eps=1e-4 keeps gradient
+        # noise ~1e-5 while the induced position error (~eps/2 in log-lambda)
+        # is a ~0.005% sp perturbation — far inside the optimizer tolerance
+        # tier of the validation contract.
+        result = minimize(
+            objective_scaled,
+            log_lam0,
+            method="L-BFGS-B",
+            bounds=bounds,
+            options={"maxiter": 200, "ftol": 1e-12, "gtol": 1e-9, "eps": 1e-4},
+        )
 
     # A coordinate sitting ON a search bound is fine when the criterion has
     # asymptoted there (|gradient| small): lambda -> inf is the CORRECT

pystatistics-4.6.2/pystatistics/gam/_gradient.py

@@ -0,0 +1,139 @@
+"""Analytic gradient of the GAM smoothing-parameter criterion (Gaussian).
+
+For the Gaussian-identity model the outer smoothing-parameter search can be
+driven by the EXACT gradient of the GCV / Laplace-REML score with respect to
+``rho = log(lambda)`` instead of finite differences, cutting the per-outer-step
+cost from ``2m+1`` inner fits to a single fit for ``m`` smooths (mgcv's
+``gam.fit3``/``newton`` does the same; this is the A.3 pattern of the mixed
+module — Wood 2011 — specialised to constant IRLS weights).
+
+Because the weights are constant (``W = I``), the criterion depends on ``rho``
+only through the closed-form penalized solve, with no implicit
+``d beta / d rho`` weight term. Writing ``A = X'X + S_lambda`` (``A = R'R`` for
+the augmented triangle ``R``), ``H = A^{-1} X'X`` the influence matrix and
+``beta`` the penalized coefficients:
+
+    d edf / d rho_j       = -lambda_j * tr(A^{-1} S_j H)
+    d D   / d rho_j       =  2 * lambda_j * (A^{-1} S_lambda beta)' (S_j beta)
+    d(D + penalty)/d rho_j =  lambda_j * beta' S_j beta        (envelope theorem)
+
+from which GCV = n D / (n - edf)^2 and the profiled Laplace-REML score follow
+by the chain rule (see each function). Every term is an O(p^3) operation on the
+p-by-p factors the fit already produced — ``A^{-1}`` is the posterior
+covariance evaluated at unit scale. Pure numpy.
+
+Scope: Gaussian-identity ONLY. For GLM families the IRLS weights depend on
+``beta``, so the score gains an implicit ``d beta / d rho`` term (the full Wood
+2011 form) that this module deliberately does not implement; those families
+keep the finite-difference path in ``_criteria.select_lambdas``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from pystatistics.gam._edf import influence_matrix, posterior_covariance
+from pystatistics.gam._pirls import PenaltyRoot, PirlsFit
+
+
+def _penalty_terms(
+    roots: list[PenaltyRoot],
+    lambdas: NDArray[np.floating[Any]],
+    p: int,
+) -> tuple[list[tuple[float, NDArray[np.floating[Any]], int]],
+           NDArray[np.floating[Any]]]:
+    """Per-smooth ``(lambda_j, S_j, rank_j)`` and the assembled ``S_lambda``.
+
+    ``S_j`` is the full ``(p, p)`` penalty (zero outside the smooth's block),
+    reconstructed from the cached eigen square root (``rows' rows = S_j``);
+    ``S_lambda = sum_j lambda_j S_j`` matches the fit's ``B_lam' B_lam``.
+    """
+    terms: list[tuple[float, NDArray[np.floating[Any]], int]] = []
+    s_lam = np.zeros((p, p), dtype=np.float64)
+    for root, lam in zip(roots, lambdas):
+        s, e = root.block
+        sj = np.zeros((p, p), dtype=np.float64)
+        sj[s:e, s:e] = root.rows.T @ root.rows
+        s_lam += float(lam) * sj
+        terms.append((float(lam), sj, root.rank))
+    return terms, s_lam
+
+
+def gcv_gradient(
+    fit: PirlsFit,
+    roots: list[PenaltyRoot],
+    lambdas: NDArray[np.floating[Any]],
+    n: int,
+    edf: float,
+) -> NDArray[np.floating[Any]]:
+    """``d GCV / d rho`` for the Gaussian-identity model, ``rho = log lambda``.
+
+    ``GCV = n D / (n - edf)^2`` so, with ``tau = n - edf``,
+
+        d GCV / d rho_j = n * D'_j / tau^2 + 2 n D * edf'_j / tau^3
+
+    using ``D'_j = 2 lambda_j (A^{-1} S_lambda beta)'(S_j beta)`` and
+    ``edf'_j = -lambda_j tr(A^{-1} S_j H)``.
+    """
+    p = fit.R.shape[0]
+    a_inv = posterior_covariance(fit.R, fit.piv, fit.rank, 1.0)  # A^{-1}
+    h = influence_matrix(fit.R, fit.R_x, fit.piv, fit.rank)
+    terms, s_lam = _penalty_terms(roots, lambdas, p)
+    beta = fit.beta
+    d = fit.deviance
+    tau = n - edf
+    # p_vec = A^{-1} S_lambda beta  (so D'_j = 2 lambda_j p_vec' S_j beta)
+    p_vec = a_inv @ (s_lam @ beta)
+
+    grad = np.empty(len(terms), dtype=np.float64)
+    for j, (lam, sj, _rank_j) in enumerate(terms):
+        sj_beta = sj @ beta
+        d_dev = 2.0 * lam * float(p_vec @ sj_beta)
+        # edf'_j = -lambda_j tr(A^{-1} S_j H)
+        d_edf = -lam * float(np.einsum("ab,ba->", a_inv @ sj, h))
+        grad[j] = n * d_dev / tau**2 + 2.0 * n * d * d_edf / tau**3
+    return grad
+
+
+def reml_gradient_gauss(
+    fit: PirlsFit,
+    roots: list[PenaltyRoot],
+    lambdas: NDArray[np.floating[Any]],
+    n: int,
+) -> NDArray[np.floating[Any]]:
+    """``d V / d rho`` for the Gaussian-identity Laplace-REML score.
+
+    The score reduces (constants dropped) to
+
+        V = (n - M_p)/2 * log(D + penalty) + (log|A| - log|S_lambda|_+)/2
+
+    so, with ``phi = (D + penalty)/(n - M_p)``, ``d(D+penalty)/d rho_j``
+    collapsing to ``lambda_j beta' S_j beta`` (envelope),
+    ``d log|A|/d rho_j = lambda_j tr(A^{-1} S_j)`` and
+    ``d log|S_lambda|_+/d rho_j = rank_j``:
+
+        d V / d rho_j = lambda_j beta'S_j beta / (2 phi)
+                        + lambda_j tr(A^{-1} S_j) / 2 - rank_j / 2
+    """
+    p = fit.R.shape[0]
+    a_inv = posterior_covariance(fit.R, fit.piv, fit.rank, 1.0)  # A^{-1}
+    terms, _s_lam = _penalty_terms(roots, lambdas, p)
+    beta = fit.beta
+    rank_s = sum(r.rank for r in roots)
+    m_p = max(fit.rank - rank_s, 0)
+    d_p = fit.deviance + fit.penalty
+    phi = d_p / (n - m_p)
+
+    grad = np.empty(len(terms), dtype=np.float64)
+    for j, (lam, sj, rank_j) in enumerate(terms):
+        b_sj_b = float(beta @ (sj @ beta))
+        tr_ainv_sj = float(np.einsum("ab,ba->", a_inv, sj))
+        grad[j] = (
+            lam * b_sj_b / (2.0 * phi)
+            + 0.5 * lam * tr_ainv_sj
+            - 0.5 * rank_j
+        )
+    return grad

{pystatistics-4.6.0 → pystatistics-4.6.2}/pystatistics/timeseries/__init__.py

@@ -13,13 +13,22 @@ Public API:
     ndiffs(x)       - Estimate differences for stationarity (matches R forecast::ndiffs)
     adf_test(x)     - Augmented Dickey-Fuller unit root test (matches R tseries::adf.test)
     kpss_test(x)    - KPSS stationarity test (matches R tseries::kpss.test)
-    ets(y)          - Fit an ETS state space model (matches R forecast::ets)
+    ets(y)          - Fit an ETS state space model (matches R forecast::ets,
+                      including "Z"-wildcard automatic selection; default
+                      model="ZZZ". Reported log-likelihood/AIC use the full-
+                      Gaussian convention — R's concentrated numbers differ by
+                      a constant in n; model rankings/selection are identical.
+                      See timeseries._ets_fit and ._ets_select docstrings.)
     forecast_ets(f) - Forecast from a fitted ETS model
     arima(y)        - Fit an ARIMA model (matches R stats::arima)
     forecast_arima(f, y) - Forecast from a fitted ARIMA model
     auto_arima(y)   - Automatic ARIMA order selection (matches R forecast::auto.arima)
     decompose(x)    - Classical time series decomposition (matches R stats::decompose)
-    stl(x)          - STL decomposition (matches R stats::stl)
+    stl(x)          - STL decomposition (matches R stats::stl; identical parameters
+                      reproduce R's components to floating-point noise. Interface
+                      divergences, both deliberate: seasonal_window defaults to
+                      "periodic" where R requires it explicitly, and even/short
+                      loess spans raise instead of being silently rounded up.)
 """
 
 from pystatistics.timeseries._acf import acf, pacf
@@ -28,7 +37,8 @@ from pystatistics.timeseries._stationarity import adf_test, kpss_test
 from pystatistics.timeseries._common import (
     ACFParams, ACFSolution, StationarityParams, StationaritySolution,
 )
-from pystatistics.timeseries._ets_fit import ets, ETSParams, ETSSolution
+from pystatistics.timeseries._ets_fit import ETSParams, ETSSolution
+from pystatistics.timeseries._ets_select import ets
 from pystatistics.timeseries._ets_forecast import forecast_ets, ETSForecast
 from pystatistics.timeseries._ets_models import ETSSpec
 from pystatistics.timeseries._arima_solution import ARIMAParams, ARIMASolution
@@ -41,8 +51,9 @@ from pystatistics.timeseries._arima_order import (
     auto_arima, AutoARIMAParams, AutoARIMASolution,
 )
 from pystatistics.timeseries._decomposition import (
-    decompose, stl, DecompositionParams, DecompositionSolution,
+    decompose, DecompositionParams, DecompositionSolution,
 )
+from pystatistics.timeseries._stl import stl
 
 __all__ = [
     "acf",