Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 15 additions & 5 deletions docs/conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -177,8 +177,10 @@ Classification is supported for numeric/logical/factor-like class-code targets.
inputs with fewer than four observations and for univariate `order="max"`; R
does not call `smooth.spline` there. Spline-eligible inputs use a private
fixed-`spar` cubic smoothing-spline adapter matching the `stats::smooth.spline`
subset used by `NNS.reg`: `spar = (dependence + 0.5) / 2`, R-style knots, and
R's interior-band trace ratio for lambda.
subset used by `NNS.reg`: `spar = (dependence + 0.5) / 2`, R's
`1e-6 * IQR(x)` tie grouping, `.nknots.smspl` knot thinning above 49 unique x,
the Fortran `sgram` penalty (with its `.3330` constant), R's interior-band
trace ratio for lambda, and a banded Cholesky solve.
Factor predictor expansion is supported through the public `nns_reg` path.
When combined with dimension reduction, factor predictors are expanded with
R's full-rank dummy convention before synthetic `x.star` coefficients are
Expand Down Expand Up @@ -522,9 +524,17 @@ rounds results to `digits`, matching R's default output convention.
`dy_dx(..., eval_point="overall")` maps to R's `dy.dx(..., eval.point =
"overall")` path and returns the mean fitted gradient from unsmoothed
`nns_reg`. Numeric `dy_dx` evaluation points use R's finite-difference grid
around smooth `nns_reg` point estimates and return a table-like dictionary with
`eval.point`, `first.derivative`, and `second.derivative`. Boundary-point
quirks follow installed R where covered by parity tests.
around smooth `nns_reg` point estimates, stepping by
`gravity(|diff(x)|) * h` for each bandwidth `h` in R's `h_s`, and return a
table-like dictionary with `eval.point`, `first.derivative`, and
`second.derivative`. At `min(x)` or `max(x)` the first derivative is R's
one-sided slope and the second derivative is NaN. As in R, bandwidths that
repeat in `h_s` (n < 49) are skipped; below n = 16, where every bandwidth
repeats and R's `dy.dx` fails, the port uses the distinct bandwidths.
`eval_point` must be given (a number, a vector, or `"overall"`).
`nns_diff` finds the inferred step like R's `uniroot(extendInt = "yes")`
(tolerance `.Machine$double.eps^0.25`), so iterations and convergence flags
match R.

NNS Python derivative parity is defined at the public input/output level, while
preserving R's cumulative finite-difference perturbation pattern for `dy_d`.
Expand Down
100 changes: 69 additions & 31 deletions src/nns/_reg_engine.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,6 @@

import math
import re
from itertools import pairwise
from typing import Any, Literal, cast

import numpy as np
Expand Down Expand Up @@ -521,58 +520,92 @@ def _derivative(rp: dict[str, NDArray[np.float64]]) -> dict[str, NDArray[np.floa
}


def _nknots_smspl(n: int) -> int:
"""R's ``stats:::.nknots.smspl``: number of inner knots for ``n`` unique x."""
if n < 50:
return n
a1, a2, a3, a4 = (math.log2(v) for v in (50.0, 100.0, 140.0, 200.0))
if n < 200:
value = 2.0 ** (a1 + (a2 - a1) * (n - 50) / 150)
elif n < 800:
value = 2.0 ** (a2 + (a3 - a2) * (n - 200) / 600)
elif n < 3200:
value = 2.0 ** (a3 + (a4 - a3) * (n - 800) / 2400)
else:
value = 200.0 + (n - 3200) ** 0.2
return math.trunc(value)


def _smooth_spline_predictor(
rx: NDArray[np.float64], ry: NDArray[np.float64], spar: float
) -> Any:
"""Faithful port of R's ``stats::smooth.spline(x, y, spar)``.
"""Port of R's ``stats::smooth.spline(x, y, spar)`` with default arguments.

R ties the smoothing parameter to dependence via an explicit ``spar`` rather
than delegating to GCV. This reproduces R's penalized cubic B-spline fit:
scale x to [0, 1], place clamped cubic knots at the unique abscissas, form
the weighted design cross-product and the second-derivative penalty (Sigma),
group x values closer than ``tol = 1e-6 * IQR(x)``, scale x to [0, 1], place
clamped cubic knots at ``.nknots.smspl(nx)`` of the unique abscissas (all of
them when ``nx < 50``), form the weighted design cross-product and the
second-derivative penalty Sigma exactly as Fortran ``sgram`` does (linear
interpolation of B'' on each knot interval, with its ``.3330`` constant),
then solve ``(X'WX + lambda * Sigma) c = X'W y`` with
``lambda = ratio * 256^(3*spar - 1)`` and ``ratio`` from R's partial diagonal
trace. Returns a callable evaluating the fit (with R's linear extrapolation
beyond the data range), or ``None`` when the fit is degenerate.
``lambda = ratio * 256^(3*spar - 1)`` and ``ratio`` from R's partial
diagonal trace. Returns a callable evaluating the fit (with R's linear
extrapolation beyond the data range), or ``None`` when R would refuse to fit.
"""
from scipy.interpolate import BSpline # type: ignore[import-untyped]
from scipy.linalg import solve # type: ignore[import-untyped]
from scipy.linalg import solveh_banded # type: ignore[import-untyped]

order = np.argsort(rx, kind="mergesort")
xs = np.asarray(rx, dtype=np.float64)[order]
ys = np.asarray(ry, dtype=np.float64)[order]
ux, inverse = np.unique(xs, return_inverse=True)
nx = ux.size
x_all = np.asarray(rx, dtype=np.float64)
y_all = np.asarray(ry, dtype=np.float64)
q25, q75 = np.quantile(x_all, [0.25, 0.75])
tol = 1e-6 * float(q75 - q25)
if not math.isfinite(tol) or tol <= 0.0:
return None
# R: xx <- round((x - mean(x)) / tol); one group per distinct rounded value,
# represented by its smallest x, with the group mean of y and weight = size.
rounded = np.round((x_all - float(np.mean(x_all))) / tol)
order = np.argsort(x_all, kind="mergesort")
xs = x_all[order]
ys = y_all[order]
rs = rounded[order]
is_start = np.concatenate(([True], rs[:-1] < rs[1:]))
nx = int(np.count_nonzero(is_start))
if nx < 4:
return None
wbar = np.bincount(inverse).astype(np.float64)
ybar = np.bincount(inverse, weights=ys) / wbar
ux = xs[is_start]
group = np.cumsum(is_start) - 1
wbar = np.bincount(group).astype(np.float64)
ybar = np.bincount(group, weights=ys) / wbar

x0 = ux[0]
r_ux = ux[-1] - ux[0]
if r_ux <= 0.0:
return None
xbar = (ux - x0) / r_ux
knot = np.concatenate(([xbar[0]] * 3, xbar, [xbar[-1]] * 3))
nk = nx + 2
nknots = _nknots_smspl(nx)
# R: xbar[seq.int(1, nx, length.out = nknots)] (fractional indices truncate).
inner = xbar[np.trunc(np.linspace(1.0, float(nx), nknots)).astype(np.intp) - 1]
knot = np.concatenate(([xbar[0]] * 3, inner, [xbar[-1]] * 3))
nk = nknots + 2
k = 3

design = BSpline.design_matrix(xbar, knot, k).toarray()
xtwx = design.T @ (wbar[:, None] * design)

sigma = np.zeros((nk, nk), dtype=np.float64)
gl_x, gl_w = np.polynomial.legendre.leggauss(4)
unique_knots = np.unique(knot)
basis = [BSpline(knot, np.eye(nk)[j], k) for j in range(nk)]
for a, b in pairwise(unique_knots):
if b <= a:
continue
mid = 0.5 * (a + b)
half = 0.5 * (b - a)
pts = mid + half * gl_x
wts = half * gl_w
d2 = np.column_stack([basis[j](pts, nu=2) for j in range(nk)])
sigma += (d2 * wts[:, None]).T @ d2
# Fortran sgram: on each knot interval B'' is linear; with y1 = B''(left)
# and y2 = B''(right) - y1, Sigma += w * (y1 y1' + (y2 y1' + y1 y2')/2
# + .3330 y2 y2'), where .3330 (not 1/3) is R's constant.
d2 = np.asarray(BSpline(knot, np.eye(nk), k)(inner, nu=2), dtype=np.float64)
y1 = d2[:-1]
y2 = d2[1:] - y1
width = np.diff(inner)[:, None]
cross = (width * y2).T @ y1
sigma = (
(width * y1).T @ y1
+ 0.5 * (cross + cross.T)
+ 0.333 * ((width * y2).T @ y2)
)

diag_h = np.diag(xtwx)
diag_s = np.diag(sigma)
Expand All @@ -582,8 +615,13 @@ def _smooth_spline_predictor(
ratio = float(diag_h[2 : nk - 3].sum()) / denom
lam = ratio * 256.0 ** (3.0 * spar - 1.0)

# R (sslvrg) solves the 4-band system with a banded Cholesky (LINPACK dpbfa).
system = xtwx + lam * sigma
banded = np.zeros((k + 1, nk), dtype=np.float64)
for offset in range(k + 1):
banded[k - offset, offset:] = np.diagonal(system, offset)
try:
coef = solve(xtwx + lam * sigma, design.T @ (wbar * ybar), assume_a="sym")
coef = solveh_banded(banded, design.T @ (wbar * ybar))
except np.linalg.LinAlgError:
return None
spline = BSpline(knot, coef, k, extrapolate=False)
Expand Down
Loading
Loading