Construct a Local Polynomial Lifting Trend-Filtering Operator

Builds the Local Polynomial Lifting Trend Filtering (LPL-TF) analysis operator from local polynomial prediction residuals. For each observed target point $i$, the operator predicts $f_i$ from nearby values $f_j$ using a local polynomial model and stores the residual row $$r_i(f) = f_i - \sum_{j \in S_i} h_{ij} f_j.$$

Usage

lpl.tf.operator(
  X,
  adj.list = NULL,
  weight.list = NULL,
  graph = NULL,
  graph.stage = "final",
  anchor.index = NULL,
  anchor.coordinates = NULL,
  degree = 2L,
  support.type = c("adaptive.radius", "knn", "fixed.radius"),
  support.size = NULL,
  radius = NULL,
  min.support = NULL,
  support.buffer = 3L,
  kernel = c("epanechnikov", "triangular", "gaussian", "tricube"),
  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"),
  exclude.self = TRUE,
  row.normalize = c("l2", "none", "l1"),
  local.solver = c("auto", "normal.equations", "qr", "svd"),
  normal.equations.max.condition = 1e+08,
  duplicate.action = c("keep", "error"),
  drop.rank.deficient = TRUE,
  verbose = FALSE,
  ...
)

Arguments

X: Numeric coordinate matrix with one row per observation.
adj.list, weight.list: Optional supplied undirected graph adjacency and positive edge-length lists using 1-based vertex indices.
graph: Optional graph object returned by dgraphs::create.rknn.graph() or a list containing adj.list/weight.list or adj_list/weight_list.
graph.stage: Graph stage to extract from graph: "final", "raw", or "pruned".
anchor.index: Optional integer vector of observed anchor/target indices. The current implementation supports observed anchors only.
anchor.coordinates: Reserved for later off-observation anchors; this implementation requires NULL.
degree: Polynomial degree. The current implementation supports 0L, 1L, and 2L.
support.type: Coordinate support rule. "knn" uses the nearest support.size candidates including the target before self exclusion. "adaptive.radius" uses the nearest min.support positive predictors after self exclusion. "fixed.radius" uses all points within radius.
support.size: Positive integer for support.type = "knn".
radius: Positive coordinate radius for support.type = "fixed.radius".
min.support: Minimum number of positive-weight predictors after self exclusion. If NULL, uses choose(ncol(X) + degree, degree) + support.buffer.
support.buffer: Nonnegative integer added to the local polynomial design size when choosing default supports.
kernel: Kernel used to weight local predictors by distance.
coordinate.method: Coordinate chart used for the local polynomial design. "coordinates" uses centered ambient coordinates; "local.pca" uses a deterministic local PCA chart on the selected support.
chart.dim: Chart dimension. For "coordinates", this must be NULL or ncol(X). For "local.pca", NULL defaults to ncol(X). The special value "auto" estimates a single chart dimension from observed-coordinate local PCA spectra only, without using responses, truth values, latent coordinates, or labels.
support.metric: Support-distance rule. "coordinates" uses Euclidean coordinate distances; "graph.geodesic" uses shortest-path distances in the supplied graph. "auto" uses graph geodesics when a graph 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 operator support metric, and "both" computes both diagnostics side by side.
auto.chart.selection.metric: Which auto chart-dimension diagnostic to use for the fitted operator when auto.chart.support.metric = "both". The default "coordinates" preserves historical behavior.
exclude.self: Logical. LPL-TF residual rows require TRUE.
row.normalize: Complete-row normalization rule applied after setting target coefficient +1 and predictor coefficients -h_ij.
local.solver: Local linear algebra rule.
normal.equations.max.condition: Maximum condition number for local.solver = "auto" to use normal equations.
duplicate.action: Duplicate coordinate policy.
drop.rank.deficient: Logical. The current implementation requires TRUE.
verbose: Logical. Reserved for diagnostic messages.
...: Reserved.

Value

A list of class "lpl_tf_operator" containing the sparse operator matrix A, row metadata, supports, local design summaries, diagnostics, settings, and the matched call.

Details

The operator uses observed anchors, excludes the target point from every predictor support, and drops requested-degree rank-deficient rows with explicit metadata. There is no silent degree downgrade. Graph support distances affect support selection and kernel bandwidths only; local polynomial coordinates are controlled separately by coordinate.method. Graph construction is supplied by dgraphs or by explicit adj.list/weight.list payloads. Coordinate support paths and graph-geodesic payload validation are package-local; shortest-path distances are computed through dgraphs.

If $a_i$ is the complete assembled residual row, then row.normalize = "l2" uses $a_i / \|a_i\|_2$, and row.normalize = "l1" uses $a_i / \|a_i\|_1$. Normalization is applied to the whole row, not only to predictor coefficients.

Examples

X <- matrix(seq(0, 1, length.out = 18), ncol = 1)
lpl.tf.operator(X, degree = 1L, support.type = "knn",
                support.size = 7L, kernel = "gaussian")
#> Local Polynomial Lifting Trend-Filtering operator
#>   observations: 18 
#>   valid rows: 18 
#>   degree: 1 
#>   support type: knn 
#>   row normalization: l2 
#>   operator rank: 16 
#>   operator nullity: 2