Fit Model-Averaged Local Polynomial Smoothing

Fits the current model-averaged local polynomial smoother (MALPS) on a supplied coordinate matrix. MALPS fits local polynomial regressions around observed anchor points and averages all positive-weight local predictions at each training point. The current implementation supports supplied coordinates, observed or supplied coordinate anchors, fixed support parameters, deterministic cross-validation and exact dense GCV over support parameters, local PCA chart coordinates, ordinary and weighted new-response refits, coordinate-space new-point prediction, linear-smoother diagnostics, and fixed-selection bootstrap uncertainty summaries. Graph-geodesic supports are available for training and refit; graph-geodesic new-point prediction is deferred.

Usage

fit.malps(
  X,
  y,
  graph = NULL,
  adj.list = NULL,
  weight.list = NULL,
  graph.stage = "final",
  anchor.index = NULL,
  anchor.coordinates = NULL,
  degree = 2L,
  degree.grid = NULL,
  support.type = c("adaptive.radius", "knn", "fixed.radius"),
  support.size = NULL,
  support.grid = NULL,
  radius = NULL,
  radius.grid = NULL,
  min.support = NULL,
  min.support.grid = NULL,
  support.buffer = 3L,
  kernel = c("epanechnikov", "triangular", "gaussian", "tricube"),
  kernel.grid = NULL,
  model.weight.rule = c("none", "condition", "support", "boundary", "quality"),
  duplicate.action = c("keep", "error"),
  coordinate.method = c("coordinates", "local.pca"),
  chart.dim = NULL,
  support.metric = c("auto", "coordinates", "graph.geodesic"),
  auto.chart.support.metric = c("coordinates", "operator", "both"),
  auto.chart.selection.metric = c("coordinates", "operator"),
  support.selection = c("fixed", "cv", "gcv"),
  foldid = NULL,
  cv.folds = 5L,
  cv.loss = c("rmse", "mae", "mse"),
  cv.repeats = 1L,
  cv.seed = NULL,
  cv.one.se = FALSE,
  gcv.exact.max.n = 1000L,
  local.solver = c("auto", "normal.equations", "qr", "svd"),
  normal.equations.max.condition = 1e+08,
  robust.iterations = 0L,
  robust.tuning.constant = 6,
  verbose = FALSE,
  ...
)

Arguments

X

Numeric coordinate matrix with one row per observation.

y

Numeric response vector with length nrow(X).

graph

Optional supported dgraphs graph object, for example from dgraphs::create.rknn.graph(). When support.metric = "graph.geodesic" or "auto" with a graph supplied, weighted shortest-path distances from this graph are used for support construction.

adj.list

Optional 1-based undirected adjacency list. Must be supplied together with weight.list when using a supplied graph payload.

weight.list

Optional positive edge-length list parallel to adj.list. Edge weights are interpreted as graph lengths.

graph.stage

Graph lifecycle stage used when graph is a dgraphs graph object. Supported stages include "final", "raw", and "pruned" when those payloads are available on the supplied graph.

anchor.index

Optional integer vector of observed rows used as local model anchors. Defaults to all rows when anchor.coordinates is NULL.

anchor.coordinates

Optional numeric coordinate matrix of off-sample local model anchors with the same number of columns as X. This option is currently supported only with coordinate support distances, not with support.metric = "graph.geodesic".

degree

Local polynomial degree, one of 0L, 1L, or 2L.

degree.grid

Optional degree grid used when support.selection is "cv" or "gcv".

support.type

Support construction rule. "knn" uses exactly support.size nearest observations including the anchor itself for full-data local fitting supports. Prediction supports are then rebuilt from the induced local radius, so tied targets at the kNN boundary can be covered even when they were not part of the exact-size fitting support. "adaptive.radius" uses a radius large enough to include at least min.support observations. "fixed.radius" uses the supplied radius.

support.size

Number of nearest observations for support.type = "knn". If NULL, defaults to min.support.

support.grid

Optional kNN support-size grid used when support.selection is "cv" or "gcv".

radius

Radius for support.type = "fixed.radius" and optional base radius for support.type = "adaptive.radius".

radius.grid

Optional radius grid used when support.selection is "cv" or "gcv".

min.support

Minimum positive-weight support size. If NULL, defaults to the local polynomial design size plus support.buffer.

min.support.grid

Optional minimum-support grid used when support.selection is "cv" or "gcv".

support.buffer

Nonnegative integer added to the local design size when deriving the default min.support.

kernel

Kernel used for local fitting and model averaging.

kernel.grid

Optional kernel grid used when support.selection is "cv" or "gcv".

model.weight.rule

Optional per-anchor model-quality multiplier applied to the ordinary kernel averaging weights. "none" preserves the kernel-only averaging from earlier phases. "condition" downweights poorly conditioned local designs with \(q_u^{\mathrm{cond}}=1/\max(\kappa_u,1)\). "support" upweights anchors with larger positive fitting supports using support size divided by the maximum support size. "boundary" downweights asymmetric boundary-like supports with \(q_u^{\mathrm{bdry}}=1/(1+b_u)\). "quality" multiplies these three component weights. For every non-"none" rule, diagnostics$model.weight.raw stores the selected unnormalized rule multiplier, while model.weights and diagnostics$model.weight store the final multipliers after median-one normalization over positive raw values. Raw zero or non-finite multipliers are retained diagnostically but are replaced by a tiny positive final floor before prediction averaging, so model-quality rules reweight existing prediction support rather than removing anchors from support membership. These weights affect prediction averaging only; they do not change local supports or local coefficient estimation.

duplicate.action

How duplicate coordinate rows should be handled. "keep" allows duplicates, records duplicate diagnostics, and preserves observed-anchor self-inclusion. "error" rejects duplicate rows. Jittering duplicates is deliberately not implemented.

coordinate.method

Coordinate system used for each local polynomial design. "coordinates" uses supplied coordinates centered at the anchor. "local.pca" uses a deterministic local PCA chart estimated from the anchor support.

chart.dim

Local chart dimension for coordinate.method = "local.pca". If NULL, defaults to ncol(X). The special value "auto" estimates a single observed-data local PCA dimension without using responses, truth values, latent coordinates, or labels. For coordinate.method = "coordinates", chart.dim must be NULL.

support.metric

Distance system used for support construction. "coordinates" uses Euclidean distances in X. "graph.geodesic" uses weighted shortest-path distances from graph or adj.list/weight.list. "auto" uses graph geodesic distances when graph input is supplied and coordinate distances otherwise.

auto.chart.support.metric

Support system used when chart.dim = "auto". "coordinates" uses Euclidean coordinate neighborhoods, "operator" uses the resolved MALPS support metric, and "both" computes both diagnostics side by side.

auto.chart.selection.metric

Which auto chart-dimension diagnostic to use for the fitted MALPS model when both diagnostics are available. The default "coordinates" preserves historical behavior.

support.selection

"fixed" for a single support profile, "cv" to tune support parameters by cross-validation, or "gcv" to tune support parameters by exact dense generalized cross-validation. The GCV path is cached across candidates and is exact for fixed-weight linear MALPS fits; it rejects robust residual reweighting.

foldid

Optional integer fold assignments. If supplied, cv.repeats is forced to one.

cv.folds

Number of folds generated when foldid = NULL.

cv.loss

Cross-validation loss.

cv.repeats

Number of independent fold assignments generated when foldid = NULL.

cv.seed

Optional seed for generated folds.

cv.one.se

Logical; use a one-standard-error rule for support selection.

gcv.exact.max.n

Maximum number of observations allowed for exact dense GCV support selection. Larger datasets should use "cv" until a sparse or trace-estimated GCV path is implemented.

local.solver

Local weighted least-squares solver. "auto" uses normal equations only for full-rank, well-conditioned local designs and otherwise falls back to SVD.

normal.equations.max.condition

Maximum local design condition number for normal equations under local.solver = "auto".

robust.iterations

Number of Cleveland-style robust residual reweighting iterations applied inside each local polynomial fit. The default 0L preserves ordinary MALPS. Positive values multiply the geometric fitting weights by Tukey bisquare residual weights recomputed from the local fit.

robust.tuning.constant

Positive bisquare tuning constant. The default 6 matches the usual LOWESS convention in which residuals are scaled by 6 * median(abs(residuals)).

verbose

Logical; reserved for future progress messages.

...

Reserved for future extensions. Supplying unused arguments is an error.

Value

A list of class "malps" with fitted values, local model coefficients, supports, averaging weights, diagnostics, and selection metadata.

Details

Current development benchmarks suggest using the plain MALPS defaults for production-style fits unless a specific diagnostic motivates a non-default option: support.selection = "cv", robust.iterations = 0L, model.weight.rule = "none", and observed anchors (anchor.coordinates = NULL). Exact GCV selection (support.selection = "gcv") is a useful faster option for fixed-weight, non-robust MALPS fits, especially exploratory continuous smoothing runs, but it is not yet the universal default. Binary responses are treated as numeric conditional-expectation targets; fitted values are not clipped inside the smoother. Grid anchors, empirical-Bayes shrinkage, robust local residual reweighting, and conservative/smoothed GCV selection remain experimental controls rather than default recommendations.

Graph construction is supplied by dgraphs or by explicit adj.list/weight.list payloads. Coordinate MALPS paths and graph-geodesic payload validation are package-local; shortest-path distances are computed through dgraphs.

Choosing controls

First fit: supply X, y, degree, and support.type with a suitable support.size or radius. Coordinate-distance fits support new predictions.

Selection: support and degree grids, foldid, and cv.folds govern held-out selection. Robust refits recompute residual weights; selection is not automatically repeated by refit.

Geometry: support.metric, graph inputs, anchors, and chart controls determine the local models. Graph-geodesic fits require aligned vertices and do not currently predict at new targets.

Numerics: local.solver, conditioning controls, and robust weighting have distinct meanings. Keep their defaults until diagnostics identify a need.

Diagnostics: inspect selected, model weights, and stored local fits. smoother.matrix allocates a dense matrix and applies only to fixed weighting; its max.n guard makes that cost explicit.

Examples

X <- matrix(seq(0, 1, length.out = 20), ncol = 1)
fit <- fit.malps(X, sin(2 * pi * X[, 1]), degree = 1L,
                 support.type = "knn", support.size = 8L)
head(fit$fitted.values)
#> [1] 0.1557620 0.3688829 0.5792770 0.7653744 0.9067175 0.9798134