Construct a Metric-Conductance Graph Low-Pass Operator — metric.graph.lowpass.operator • geosmooth

Builds a weighted graph Laplacian by transforming metric edge lengths into conductances. This operator is a direct metric-conductance comparator to the legacy rdgraph regression smoother, not a replacement for the Riemannian-complex/overlap-density smoother.

Usage

metric.graph.lowpass.operator(
  adj.list,
  weight.list,
  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"),
  return.sparse = TRUE,
  verbose = FALSE
)

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.
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}$.
return.sparse: Logical. If TRUE, attach a Matrix sparse Laplacian when Matrix is available.
verbose: Logical. Reserved for future diagnostic messages.

Value

A list of class "metric.graph.lowpass.operator" containing the edge table, conductances, degree vector, Laplacian triplets, summaries, and optionally a sparse Laplacian matrix.

Details

The legacy rdgraph regression precomputed-graph path uses supplied weight.list values as edge lengths for neighborhood ordering. The spectral conductance in that smoother is overlap-density based: $$c_e^\rho = 1 / \max(\rho_1(e), 10^{-10}),$$ where $\rho_1(e)$ is computed by the Riemannian-complex density machinery.

This function instead constructs conductances directly from metric lengths: $$c_{ij} = \phi(\ell_{ij}).$$ Supported transforms are $$c_{ij}=(\ell_{ij}+\epsilon)^{-\alpha},$$ $$c_{ij}=\exp(-\ell_{ij}/\sigma),$$ $$c_{ij}=\exp(-\ell_{ij}^{2}/\sigma^{2}),$$ and $$c_{ij}=\exp(-\ell_{ij}^{2}/(\sigma_i\sigma_j)).$$

For laplacian.type = "symmetric.normalized", smoothing is performed in the Euclidean eigenbasis of $L_{\mathrm{sym}}$. The null vector is proportional to $\sqrt{d}$, not the constant vector, so this mode does not preserve constant responses in the same way as the unnormalized Laplacian.

Examples

adj <- list(2L, c(1L, 3L), c(2L, 4L), 3L)
lengths <- list(1, c(1, 1), c(1, 1), 1)
metric.graph.lowpass.operator(adj, lengths)
#> $graph
#> $graph$n.vertices
#> [1] 4
#> 
#> $graph$n.edges
#> [1] 3
#> 
#> $graph$adj.list
#> $graph$adj.list[[1]]
#> [1] 2
#> 
#> $graph$adj.list[[2]]
#> [1] 1 3
#> 
#> $graph$adj.list[[3]]
#> [1] 2 4
#> 
#> $graph$adj.list[[4]]
#> [1] 3
#> 
#> 
#> $graph$weight.list
#> $graph$weight.list[[1]]
#> [1] 1
#> 
#> $graph$weight.list[[2]]
#> [1] 1 1
#> 
#> $graph$weight.list[[3]]
#> [1] 1 1
#> 
#> $graph$weight.list[[4]]
#> [1] 1
#> 
#> 
#> 
#> $edge.table
#>   u v length conductance
#> 1 1 2      1           1
#> 2 2 3      1           1
#> 3 3 4      1           1
#> 
#> $conductance
#> $conductance$rule
#> [1] "inverse.length.power"
#> 
#> $conductance$values
#> [1] 1 1 1
#> 
#> $conductance$local.scales
#> [1] NA NA NA NA
#> 
#> $conductance$summary
#> $conductance$summary$min
#> [1] 1
#> 
#> $conductance$summary$q10
#> [1] 1
#> 
#> $conductance$summary$median
#> [1] 1
#> 
#> $conductance$summary$q90
#> [1] 1
#> 
#> $conductance$summary$max
#> [1] 1
#> 
#> $conductance$summary$mean
#> [1] 1
#> 
#> $conductance$summary$n.nonfinite
#> [1] 0
#> 
#> $conductance$summary$n.clipped
#> [1] 0
#> 
#> 
#> 
#> $degree
#> [1] 1 2 2 1
#> 
#> $laplacian
#> $laplacian$dim
#> [1] 4 4
#> 
#> $laplacian$i
#>  [1] 0 1 0 1 2 1 2 3 2 3
#> 
#> $laplacian$j
#>  [1] 0 0 1 1 1 2 2 2 3 3
#> 
#> $laplacian$x
#>  [1]  1 -1 -1  2 -1 -1  2 -1 -1  1
#> 
#> $laplacian$matrix
#> 4 x 4 sparse Matrix of class "dgCMatrix"
#>                 
#> [1,]  1 -1  .  .
#> [2,] -1  2 -1  .
#> [3,]  . -1  2 -1
#> [4,]  .  . -1  1
#> 
#> 
#> $laplacian.type
#> [1] "unnormalized"
#> 
#> $parameters
#> $parameters$conductance.epsilon
#> [1] 1e-08
#> 
#> $parameters$conductance.alpha
#> [1] 1
#> 
#> $parameters$conductance.sigma
#> [1] NA
#> 
#> $parameters$conductance.sigma.rule
#> [1] "edge.quantile"
#> 
#> $parameters$conductance.sigma.quantile
#> [1] 0.75
#> 
#> $parameters$conductance.local.k
#> [1] 5
#> 
#> $parameters$laplacian.type
#> [1] "unnormalized"
#> 
#> 
#> $diagnostics
#> $diagnostics$degree.summary
#> $diagnostics$degree.summary$min
#> [1] 1
#> 
#> $diagnostics$degree.summary$q10
#> [1] 1
#> 
#> $diagnostics$degree.summary$median
#> [1] 1.5
#> 
#> $diagnostics$degree.summary$q90
#> [1] 2
#> 
#> $diagnostics$degree.summary$max
#> [1] 2
#> 
#> $diagnostics$degree.summary$mean
#> [1] 1.5
#> 
#> $diagnostics$degree.summary$n.nonfinite
#> [1] 0
#> 
#> $diagnostics$degree.summary$n.clipped
#> [1] 0
#> 
#> 
#> $diagnostics$length.summary
#> $diagnostics$length.summary$min
#> [1] 1
#> 
#> $diagnostics$length.summary$q10
#> [1] 1
#> 
#> $diagnostics$length.summary$median
#> [1] 1
#> 
#> $diagnostics$length.summary$q90
#> [1] 1
#> 
#> $diagnostics$length.summary$max
#> [1] 1
#> 
#> $diagnostics$length.summary$mean
#> [1] 1
#> 
#> $diagnostics$length.summary$n.nonfinite
#> [1] 0
#> 
#> $diagnostics$length.summary$n.clipped
#> [1] 0
#> 
#> 
#> 
#> attr(,"class")
#> [1] "metric.graph.lowpass.operator" "list"