Fit Prediction-Synchronized Local Polynomial Smoothing

Experimental R reference implementation of prediction-synchronized local polynomial smoothing (PS-LPS). For fixed local polynomial parameters, PS-LPS fits one local polynomial chart per anchor and adds a quadratic penalty that synchronizes chart predictions on overlap points.

Usage

fit.ps.lps(
  X,
  y,
  foldid = NULL,
  support.size = NULL,
  degree = 2L,
  kernel = "gaussian",
  chart.dim = NULL,
  support.grid = NULL,
  degree.grid = NULL,
  kernel.grid = NULL,
  auto.chart.support.metric = c("coordinates", "operator", "both"),
  auto.chart.selection.metric = c("coordinates", "operator"),
  chart.dim.grid = NULL,
  selection.strategy = c("grid", "sparse_kd", "plateau_kd"),
  chart.dim.max = NULL,
  design.margin = 2L,
  lambda.sync.grid = c(0, 0.001, 0.01, 0.1, 1, 10),
  lambda.sync.search = c("grid", "guarded"),
  lambda.sync.selection = c("cv", "fixed"),
  local.candidate.search = c("screened", "full", "subgrid"),
  local.candidate.search.control = list(),
  lambda.sync.search.control = list(),
  lambda.diagnostics = c("all", "selected"),
  lambda.ridge = 1e-08,
  design.basis = c("monomial", "weighted.qr", "weighted.qr.drop",
    "orthogonal.polynomial.drop"),
  design.drop.tol = sqrt(.Machine$double.eps),
  ridge.multiplier.grid = NULL,
  ridge.condition.max = Inf,
  sync.neighbor.size = NULL,
  overlap.weight = c("normalized.product", "product"),
  chart.activation = c("none", "subject.od"),
  chart.activation.response = NULL,
  chart.activation.control = list(),
  ps.lps.geometry.cache = NULL,
  ps.lps.local.pca.supports = NULL,
  cv.folds = 5L,
  cv.seed = 1L
)

Arguments

X: Numeric covariate matrix.
y: Numeric response vector.
foldid: Optional integer cross-validation fold assignment.
support.size: Optional single neighborhood size for the fixed local setup path. Use support.grid for CV selection over neighborhood sizes.
degree: Single local polynomial degree for the fixed local setup path. Use degree.grid for CV selection over degrees.
kernel: Single kernel name for the fixed local setup path. Use kernel.grid for CV selection over kernels.
chart.dim: Chart dimension for the local PCA charts. A scalar fixes one dimension for all anchors; an integer vector supplies one local chart dimension per anchor. The special value "auto" estimates one global chart dimension from observed X only. The experimental special value "local.auto" estimates one local chart dimension per anchor, using the same local-PCA dimension rule as fit.lps.
support.grid: Candidate neighborhood sizes. When supplied, PS-LPS selects over support size, degree, kernel, and synchronization strength by materialized-fold CV. If both support.size and support.grid are absent, defaults to c(10L, 15L, 20L), matching fit.lps.
degree.grid: Candidate local polynomial degrees for grid selection. Defaults to the scalar degree.
kernel.grid: Candidate kernels for grid selection. Defaults to the scalar kernel.
auto.chart.support.metric: Support system used when chart.dim = "auto" or "local.auto". Because PS-LPS uses coordinate supports, "operator" is equivalent to "coordinates".
auto.chart.selection.metric: Which auto chart-dimension diagnostic to select when both diagnostics are requested.
chart.dim.grid: Optional candidate chart dimensions for experimental local-candidate selection. Numeric grids can be evaluated with selection.strategy = "sparse_kd".
selection.strategy: Candidate-selection strategy. "grid" evaluates the requested candidate grid. "sparse_kd" evaluates a sparse support-size by chart-dimension skeleton when chart.dim.grid is supplied. "plateau_kd" uses the same geometry-only support-size and chart-dimension plateau rule as fit.lps.
chart.dim.max: Optional explicit maximum chart dimension for the sparse coupled candidate family.
design.margin: Nonnegative integer feasibility margin used to screen local polynomial design size before candidate evaluation.
lambda.sync.grid: Candidate synchronization strengths.
lambda.sync.search: Lambda-search policy. "grid" evaluates the supplied grid exactly. "guarded" uses an experimental guarded coarse-to-refine search with boundary expansion.
lambda.sync.selection: Lambda-selection mode. "cv" performs the usual internal fold-weighted lambda selection. "fixed" treats the single value in lambda.sync.grid as preselected and skips internal lambda CV; this is intended for outer selection loops that already score scalar candidates.
local.candidate.search: Local-candidate search policy when support.grid, degree.grid, or kernel.grid contains more than one candidate. "screened" is the routine default: it first ranks candidates by ordinary LPS materialized-fold CV, then runs PS-LPS only on a screened subset plus guard candidates. "full" evaluates PS-LPS lambda search for every local candidate and is the exact audit/reference path. "subgrid" skips the ordinary-LPS screening pass and evaluates only a deterministic support/kernel guard subgrid; this is intended for high-dimensional preflight runs where the screening pass is itself too expensive.
local.candidate.search.control: Optional list controlling screened local-candidate search. Supported fields are top.n (default 8), max.candidates (default 12), neighbor.radius (default 1), and guard.support.quantiles (default c(0, 0.5, 1)).
lambda.sync.search.control: Optional list controlling guarded search. Supported fields are coarse.size (default 5), refine.radius (default 2), rel.tol (default 0.002), boundary.guard.rel.tol (default 0.01), boundary.expand (default TRUE), boundary.factor (default 3), max.boundary.expansions (default 2), and max.candidates (default 25). Boundary expansion may evaluate positive candidates outside the supplied lambda.sync.grid. max.candidates is a global cap on distinct evaluated candidates; a very small cap can prevent local refinement or boundary expansion.
lambda.diagnostics: Lambda-diagnostic evaluation policy. "all" computes synchronization-energy and local-GCV diagnostics for every evaluated lambda and is the audit/reference mode. "selected" computes those diagnostics only for the selected lambda, which is faster for routine selection.
lambda.ridge: Nonnegative scale-relative ridge used in the chart coefficient solve. Use 0 for the unregularized least-squares model.
design.basis: Local polynomial design backend. See fit.lps. In PS-LPS, "weighted.qr.drop" drops numerically dependent columns separately in each anchor chart before the synchronized system is assembled, and "orthogonal.polynomial.drop" builds each synchronized chart in a weighted-orthogonal polynomial basis.
design.drop.tol: Relative QR tolerance used by design.basis = "weighted.qr.drop" or design.basis = "orthogonal.polynomial.drop".
ridge.multiplier.grid: Optional nonnegative ridge multipliers for adaptive scale-relative ridge selection. When supplied, the solver uses the smallest multiplier whose penalized normal equations pass ridge.condition.max. If NULL, lambda.ridge is used as the single multiplier for backward compatibility.
ridge.condition.max: Maximum allowed condition number for adaptive ridge selection. Use Inf to disable the condition-number guard.
sync.neighbor.size: Number of nearby anchor pairs considered for synchronization from each anchor support.
overlap.weight: Overlap weighting rule.
chart.activation: Optional sparse-response chart activation rule. "none" preserves ordinary PS-LPS. "subject.od" is intended for subject-occupation density workflows and deactivates local charts with no subject mass, too few positive subject-visited support points, or only fringe occupation.
chart.activation.response: Optional nonnegative vector used only for chart.activation = "subject.od" to decide whether each chart is active. When omitted, y is used.
chart.activation.control: List controlling sparse chart activation; see fit.lps.
ps.lps.geometry.cache: Optional precomputed geometry cache used by occupation-density cross-validation. This is an implementation detail; ordinary callers should leave it as NULL.
ps.lps.local.pca.supports: Optional precomputed local-PCA supports used when activation-specific frames must be rebuilt. This is an implementation detail; ordinary callers should leave it as NULL.
cv.folds: Number of folds when foldid is absent.
cv.seed: Fold seed when foldid is absent.

Value

A list with fitted values, selected lambda, CV table, diagnostics, and fitted chart coefficients.

Examples

X <- matrix(seq(0, 1, length.out = 20), ncol = 1)
fit.ps.lps(
  X, sin(2 * pi * X[, 1]), support.size = 7L, degree = 1L,
  chart.dim = 1L, lambda.sync.grid = 0,
  lambda.sync.selection = "fixed", cv.folds = 2L
)
#> Prediction-synchronized local polynomial smoothing 
#>   Training rows: 20 ; evaluation rows: 20 ; responses: 1 
#>   Observed responses: 20 ; nonfinite fitted entries: 0 
#>   Output: finite output 
#>   Convergence: unavailable (no stored stopping certificate) 
#>   Selected: support.size=7, degree=1, kernel=gaussian, lambda.sync=0,
#>     lambda.ridge=1e-08, cv.rmse.observed=NA 
#>   Selection scores: stored in summary(fit)$criteria; conditional tuning scores.
#>   Prediction scope: stored training vertices only