Fit Metric-Conductance Graph Low-Pass Regression — fit.metric.graph.lowpass • geosmooth

Fits graph-spectral low-pass regression on a supplied graph by transforming metric edge lengths into conductances and smoothing the response in the eigenbasis of the weighted graph Laplacian.

Usage

fit.metric.graph.lowpass(
  adj.list,
  weight.list,
  y,
  conductance.rule = c("inverse.length.power", "exp.length", "exp.length.squared",
    "self.tuned.gaussian"),
  conductance.epsilon = 1e-08,
  conductance.alpha = 1,
  conductance.sigma = NULL,
  conductance.sigma.rule = c("edge.quantile", "median", "local.k"),
  conductance.sigma.quantile = 0.75,
  conductance.local.k = 5L,
  laplacian.type = c("unnormalized", "symmetric.normalized"),
  n.eigenpairs = 50L,
  filter.type = c("heat_kernel", "tikhonov", "cubic_spline", "gaussian", "exponential",
    "butterworth"),
  eta.grid = NULL,
  n.candidates = 40L,
  eigen.solver = c("auto", "sparse", "dense"),
  dense.eigen.threshold = 200L,
  dense.fallback.threshold = 5000L,
  dense.fallback = c("auto", "never", "always"),
  verbose = FALSE,
  eta.search = c("fixed", "guarded.gcv"),
  eta.expansion.factor = 3,
  eta.max.expansions = 3L,
  eta.identity.departure = 0.01,
  eta.truncation.tol = 1e-04
)

Arguments

adj.list: List of integer neighbor vectors using 1-based vertex indices.
weight.list: List of positive metric edge lengths parallel to adj.list. These are interpreted as edge lengths, not conductances.
y: Numeric response vector of length length(adj.list).
conductance.rule: Character scalar. One of "inverse.length.power", "exp.length", "exp.length.squared", or "self.tuned.gaussian".
conductance.epsilon: Positive numeric regularizer used by inverse-power conductances and as a local-scale floor.
conductance.alpha: Positive numeric exponent for "inverse.length.power".
conductance.sigma: Optional positive global scale for exponential rules. If NULL, it is selected by conductance.sigma.rule.
conductance.sigma.rule: Rule for selecting a global scale when needed.
conductance.sigma.quantile: Quantile used when conductance.sigma.rule = "edge.quantile".
conductance.local.k: Positive integer local incident-edge order statistic for "self.tuned.gaussian".
laplacian.type: Laplacian operator. "unnormalized" uses the weighted graph Laplacian \(L = D - C\). "symmetric.normalized" uses \(L_{\mathrm{sym}} = I - D^{-1/2} C D^{-1/2}\).
n.eigenpairs: Positive integer number of eigenpairs to compute.
filter.type: Spectral low-pass filter family.
eta.grid: Optional numeric eta grid. Values must be positive except for filter.type = "heat_kernel", where eta = 0 is allowed and gives the identity/no-smoothing limit. If NULL, the existing package helper generate.eta.grid() is used.
n.candidates: Number of eta candidates when eta.grid = NULL.
eigen.solver: "auto", "sparse", or "dense". "auto" uses dense decomposition only for n <= dense.eigen.threshold, then sparse-first.
dense.eigen.threshold: Exact dense threshold for auto mode. Default 200L, intended for small reference/testing problems.
dense.fallback.threshold: Maximum graph size for emergency dense fallback when sparse decomposition fails and fallback is allowed.
dense.fallback: "auto", "never", or "always".
verbose: Logical. Reserved for future diagnostic messages.
eta.search: Heat-time search controller. "fixed" evaluates the supplied or generated grid once. "guarded.gcv" is available only for filter.type = "heat_kernel" and proposes one lower positive time whenever GCV selects the current lower endpoint.
eta.expansion.factor: Geometric divisor used by guarded GCV lower-time expansion.
eta.max.expansions: Maximum number of guarded GCV lower-time extensions.
eta.identity.departure: Smallest allowed departure from the identity at the largest retained graph-Laplacian eigenvalue.
eta.truncation.tol: Omitted-mode attenuation tolerance used to certify guarded proposals for a truncated basis.

Value

A list of class "metric.graph.lowpass.fit".

References

Gajer, P. and Ravel, J. (2025). Adaptive geometric regression for high-dimensional structured data. arXiv:2511.03817. doi:10.48550/arXiv.2511.03817

Examples

adj <- list(2L, c(1L, 3L), c(2L, 4L), 3L)
lengths <- list(1, c(1, 1), c(1, 1), 1)
fit.metric.graph.lowpass(
  adj, lengths, y = c(0, 0.2, 1.8, 2), n.eigenpairs = 4L,
  eta.grid = c(0.1, 1), eigen.solver = "dense"
)
#> 
#> Metric-Conductance Graph Low-Pass Fit
#> ====================================
#> 
#> Vertices: 4; edges: 3
#> Conductance rule: inverse.length.power
#> Laplacian: unnormalized
#> Filter: heat_kernel; eta: 1.0000e-01; GCV: 1.1163e-01; effective df: 3.47