Fit a Chart-Kernel Smoother — fit.chart.kernel • geosmooth

Fits a local chart-kernel field by evaluating a Nadaraya–Watson style smoother at each evaluation point. The function is a general fitted-field model, not an occupation-density wrapper: density workflows should call normalize.density on the returned fit.

Usage

fit.chart.kernel(
  X,
  y,
  X.eval = NULL,
  support.size = min(15L, nrow(X)),
  kernel = c("gaussian", "tricube", "epanechnikov", "triangular"),
  bandwidth.multiplier = 1,
  support.grid = NULL,
  kernel.grid = NULL,
  bandwidth.multiplier.grid = NULL,
  foldid = NULL,
  cv.folds = 5L,
  cv.seed = 1L,
  coordinate.method = c("coordinates", "local.pca"),
  chart.dim = NULL,
  chart.dim.grid = NULL,
  selection.strategy = c("grid", "sparse_kd", "plateau_kd"),
  chart.dim.max = NULL,
  geometry.margin = 0L,
  auto.chart.support.metric = c("coordinates", "operator", "both"),
  auto.chart.selection.metric = c("coordinates", "operator"),
  quadrature.weights = NULL,
  denominator.floor = sqrt(.Machine$double.eps),
  return.details = TRUE
)

Arguments

X: Numeric matrix with one row per source/support point.
y: Numeric response or mass vector of length nrow(X).
X.eval: Optional numeric matrix of evaluation points. Defaults to X.
support.size: Number of source points in each local support.
kernel: Kernel name. Supported values are "gaussian", "tricube", "epanechnikov", and "triangular".
bandwidth.multiplier: Positive multiplier applied to the local support radius.
support.grid: Optional integer candidate neighborhood sizes. If supplied, or if foldid is supplied, the function performs row-wise cross-validation and refits the selected candidate on all rows.
kernel.grid: Optional kernel candidates for cross-validation.
bandwidth.multiplier.grid: Optional bandwidth-multiplier candidates for cross-validation.
foldid: Optional positive integer vector assigning source rows to cross-validation folds.
cv.folds: Number of folds used when foldid is not supplied.
cv.seed: Random seed used to generate folds when foldid is not supplied.
coordinate.method: Local coordinate method. "coordinates" uses centered ambient coordinates. "local.pca" projects centered support points onto a local PCA basis.
chart.dim: Local PCA dimension when coordinate.method = "local.pca". If NULL, the dimension is min(ncol(X), support.size - 1). The deployable input-only policies "auto" and "local.auto" use the same local-PCA dimension diagnostics as fit.lps; "auto" resolves one global chart dimension, while "local.auto" resolves one dimension per evaluation anchor.
chart.dim.grid: Optional candidate chart dimensions for experimental row-wise cross-validation. 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.
geometry.margin: Nonnegative integer subtracted from the local-PCA rank cap min(ncol(X), support.size - 1). The default zero applies only the Nadaraya–Watson chart-geometry requirement; this is not a local polynomial design margin.
auto.chart.support.metric: Support system used by chart.dim = "auto" or "local.auto". Chart-kernel smoothers currently use coordinate supports for both coordinate and operator diagnostics.
auto.chart.selection.metric: Which auto chart-dimension diagnostic to use when both coordinate and operator summaries are requested.
quadrature.weights: Optional positive reference-measure weights q_i. Defaults to unit weights.
denominator.floor: Positive floor used when the local denominator is numerically zero.
return.details: Logical; if TRUE, keep per-evaluation diagnostics.

Value

A list with class "chart_kernel" containing fitted.values, source/evaluation supports, selected controls, and denominator diagnostics.

Details

For an evaluation point $x_u$, the method chooses a local support $U_u$, builds either centered ambient coordinates or a local PCA chart, and computes $$ \widehat f(x_u) = \frac{\sum_{i\in U_u} y_i K_h(z_{ui})} {\sum_{i\in U_u} q_i K_h(z_{ui})}. $$ Here $z_{ui}$ is the local chart coordinate of $x_i-x_u$, $q_i$ is an optional quadrature weight, and $K_h$ is the selected kernel.

Examples

X <- matrix(seq(0, 1, length.out = 21), ncol = 1)
y <- exp(-20 * (X[, 1] - 0.5)^2)
fit.chart.kernel(X, y, support.size = 7L, kernel = "gaussian")
#> Chart-kernel smoothing 
#>   Training rows: 21 ; evaluation rows: 21 ; responses: 1 
#>   Observed responses: 21 ; nonfinite fitted entries: 0 
#>   Output: finite output 
#>   Convergence: unavailable (no stored stopping certificate) 
#>   Selected: support.size=7, kernel=gaussian, cv.rmse.observed=NA 
#>   Prediction scope: stored evaluation rows; supply X.eval when fitting