Package {geosmooth}

geosmooth package

Description

Geometric smoothing and conditional expectation methods for coordinate data, point clouds, and weighted graphs. The package provides local polynomial, model-averaged, trend-filtering, graph low-pass, occupation-density, and Hessian-energy methods.

Author(s)

Maintainer: Pawel Gajer pgajer@gmail.com

Authors:

• Pawel Gajer pgajer@gmail.com

Other contributors:

• Gael Guennebaud (Eigen) [contributor]

• Benoit Jacob (Eigen) [contributor]

• Authors of Eigen (Authorship and copyright in the included Eigen library) [copyright holder]

• Yixuan Qiu (Spectra) [contributor, copyright holder]

• Contributors to Spectra (Copyright in the included Spectra library) [copyright holder]

• Sunil Arya (ANN) [contributor, copyright holder]

• David M. Mount (ANN) [contributor, copyright holder]

• University of Maryland (ANN) [copyright holder]

See Also

Useful links:

• https://github.com/pgajer/geosmooth

• Report bugs at https://github.com/pgajer/geosmooth/issues

Apply a Metric Graph Low-Pass Filter Path

Description

Applies every requested low-pass parameter to one response or a matrix of responses using a reusable spectral basis.

Usage

apply.metric.graph.lowpass.path(
  basis,
  y,
  eta.grid,
  filter.type = c("heat_kernel", "tikhonov", "cubic_spline", "gaussian", "exponential",
    "butterworth"),
  block.size = NULL,
  truncation.tol = 1e-04,
  unresolved.action = c("warn", "error", "allow"),
  exact.zero = TRUE
)

Arguments

Value

A list of class "metric.graph.lowpass.path". For one response, fitted.values is an N by J matrix. For multiple responses it is an N by J by S array.

Examples

adj <- list(2L, c(1L, 3L), c(2L, 4L), 3L)
lengths <- list(1, c(1, 1), c(1, 1), 1)
basis <- metric.graph.lowpass.basis(adj, lengths, n.eigenpairs = 4L,
                                    eigen.solver = "dense")
apply.metric.graph.lowpass.path(basis, 1:4, eta.grid = c(0, 0.1, 1))

Summarize a synthetic dataset as one metadata row

Description

Summarize a synthetic dataset as one metadata row

Usage

## S3 method for class 'synthetic_dataset'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A one-row data frame.

Bootstrap Uncertainty For A Fixed-Selection MALPS Fit

Description

Reuses the supports, local charts, prediction supports, averaging weights, selected degree, and local-solver controls from an existing fit.malps object, then repeatedly calls refit.malps with bootstrap-style case weights. This is a fixed-selection uncertainty diagnostic: it measures refit variability conditional on the fitted MALPS support profile and does not rerun cross-validation or rebuild supports in each replicate.

Usage

bootstrap.malps(
  object,
  B = 200L,
  weight.type = c("bayesian", "multinomial"),
  y = NULL,
  probs = NULL,
  conf.level = 0.95,
  seed = NULL,
  max.failures = max(10L, B),
  keep.weights = FALSE,
  verbose = FALSE,
  ...
)

Arguments

Details

Two weight generators are available. "bayesian" draws positive exponential weights and rescales them to have mean one. This is the default because it preserves positive local support weights and therefore avoids many local-support degeneracies. "multinomial" draws ordinary nonparametric bootstrap counts with total count nrow(object$X); this can fail when a replicate assigns zero weight to all observations in a local support, and such failures are recorded.

Value

A list of class "malps_bootstrap" containing:

• replicate.fitted.values: an n \times B matrix of successful replicate fitted values;

• replicate.weights: an optional n \times B matrix of bootstrap weights when keep.weights = TRUE;

• failures: a data frame with columns attempt, failure, and message;

• summary: pointwise fitted values, bootstrap summaries, and empirical lower/upper intervals;

• bootstrap metadata such as B.completed, n.failures, conf.level, and weight.type.

Examples

X <- matrix(seq(0, 1, length.out = 20), ncol = 1)
fit <- fit.malps(X, X[, 1]^2, degree = 1L,
                 support.type = "knn", support.size = 8L)
bootstrap.malps(fit, B = 5L, seed = 1L)

Compare two synthetic datasets scientifically

Description

Compare two synthetic datasets scientifically

Usage

compare.synthetic.dataset(x, y, tolerance = c(1e-12, 1e-10))

Arguments

Value

A list with equality and mismatch details.

Examples

spec <- synthetic.registry.spec("G1")
x <- materialize.synthetic(spec, n = 20L, seed = 1L)
y <- materialize.synthetic(spec, n = 20L, seed = 1L)
compare.synthetic.dataset(x, y)

Exact latent-segment lengths under a synthetic geometry

Description

For quadforms this integrates the induced metric along each straight latent segment. Flat quadforms reduce exactly to Euclidean distance.

Usage

edge.lengths.synthetic.geometry(geometry, from, to, tolerance = 1e-10)

Arguments

Value

A numeric vector of segment lengths.

Examples

geometry <- synthetic.quadform(1L, 1L)
edge.lengths.synthetic.geometry(geometry, matrix(0), matrix(2))

Embed latent coordinates through a synthetic geometry

Description

This deterministic operator performs no random draws. A realized frame.matrix is required for random-frame geometries.

Usage

embed.synthetic.geometry(geometry, latent, frame.matrix = NULL)

Arguments

Value

A numeric matrix of observed coordinates.

Examples

geometry <- synthetic.circle()
embed.synthetic.geometry(geometry, matrix(c(0, pi / 2), ncol = 1))

Fit a Chart-Kernel Smoother

Description

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

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.

Value

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

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")

Fit a Density Estimator

Description

Dispatches to a dedicated density estimator. Subject-occupation density estimation is one application: construct a sparse mass vector over a fixed support set and call this generic density layer.

Usage

fit.density(
  X,
  weights = NULL,
  method = c("empirical", "graph_random_walk"),
  graph = NULL,
  graph.control = list(),
  density.control = list(),
  return.details = TRUE,
  ...
)

Arguments

Value

A list of class "density_fit" with fields method.id, status, rho, empirical.rho, fitted.raw, theta, accounting, smoothness, timing, diagnostics, and warnings.

Examples

X <- matrix(seq(0, 1, length.out = 6), ncol = 1)
fit.density(X, weights = c(1, 0, 2, 0, 0, 1), method = "empirical")

Fit Graph Trend Filtering

Description

Fits graph trend filtering on a supplied undirected graph. Supported phase-2 orders are 0L, 1L, and 2L:

\widehat\beta_\lambda = \arg\min_{\beta\in\mathbb R^n} \left\{ \frac{1}{2}\|y-\beta\|_2^2 + \lambda\|\Delta_w^{(k+1)}\beta\|_1 \right\}.

Usage

fit.graph.trend.filtering(
  adj.list,
  weight.list = NULL,
  y,
  order = 0L,
  lambda.grid = NULL,
  lambda.selection = c("cv", "fixed"),
  weight.rule = c("conductance", "sqrt.conductance", "unit"),
  operator.family = c("graph.laplacian.recursive", "path.divided.difference"),
  path.family = c("branch.continuation", "all.simple"),
  path.weighting = c("unit", "anchor.mean"),
  n.lambda = 40L,
  nfolds = 5L,
  foldid = NULL,
  maxsteps = 2000L,
  minlam = 0,
  approx = FALSE,
  rtol = 1e-07,
  btol = 1e-07,
  eps = 1e-04,
  verbose = FALSE
)

Arguments

Details

Graph trend filtering is intended as an \ell_1-adaptive comparator to the \ell_2 graph smoothers now housed in geosmooth and the legacy rdgraph comparator. The low-pass smoother penalizes broad quadratic graph roughness through a term like

\eta f^\top L f,

which shrinks high-frequency variation everywhere. Graph trend filtering instead penalizes absolute graph differences. For order = 0L, this is

\lambda \sum_e \omega_e |\beta_j-\beta_i|,

so many edge differences can become exactly zero while selected edges carry jumps. In this sense order = 0L is locally adaptive: fitted values can be piecewise constant over graph regions. Higher orders use

\Delta_w^{(1)} = D_w,\qquad \Delta_w^{(2)} = L_w,\qquad \Delta_w^{(3)} = D_w L_w,

with L_w = D_w^\top D_w.

The supplied weight.list, when used, is interpreted as a graph trend-filtering edge weight or conductance for operator.family = "graph.laplacian.recursive". For operator.family = "path.divided.difference", weight.list is interpreted as metric edge length and is used to form local path coordinates. Use weight.rule = "sqrt.conductance" when the recursive graph square-root convention is desired, and weight.rule = "unit" for an unweighted recursive graph fused-lasso penalty.

The solver backend is currently genlasso. Cross-validation refits the generalized-lasso problem on vertex-held-out training sets using a selection matrix X; this is useful for small and moderate diagnostic problems but is not yet a scalable production graph-trend-filtering solver.

Value

A list of class "graph.trend.filtering.fit" containing fitted values, residuals, selected lambda, the operator, path metadata, and CV diagnostics when requested.

References

Wang, Y.-X., Sharpnack, J., Smola, A., and Tibshirani, R. J. (2016). Trend filtering on graphs. Journal of Machine Learning Research, 17(105), 1–41. https://www.jmlr.org/papers/v17/15-147.html

Examples

if (requireNamespace("genlasso", quietly = TRUE)) {
  adj <- list(2L, c(1L, 3L), c(2L, 4L), 3L)
  fit.graph.trend.filtering(
    adj, y = c(0, 0.2, 1.8, 2), lambda.grid = 0.3,
    lambda.selection = "fixed", weight.rule = "unit"
  )
}

Fit a Local-Likelihood Density or Bernoulli Smoother

Description

Fits a local likelihood model at each evaluation point and reads off one raw fitted value at that evaluation anchor. Density and Bernoulli workflows should convert the returned fitted field with normalize.density when the target is a subject-occupation density.

Usage

fit.local.likelihood(
  X,
  y,
  X.eval = NULL,
  likelihood.family = c("density", "bernoulli"),
  support.size = min(15L, nrow(X)),
  degree = 1L,
  kernel = c("gaussian", "tricube", "epanechnikov", "triangular"),
  bandwidth.multiplier = 1,
  support.grid = NULL,
  degree.grid = NULL,
  kernel.grid = NULL,
  bandwidth.multiplier.grid = NULL,
  lambda.ridge.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,
  design.margin = 2L,
  auto.chart.support.metric = c("coordinates", "operator", "both"),
  auto.chart.selection.metric = c("coordinates", "operator"),
  quadrature.weights = NULL,
  lambda.ridge = 1e-08,
  min.local.mass = sqrt(.Machine$double.eps),
  min.nonzero.mass = 1L,
  fallback = c("degree0", "zero", "chart_kernel", "na"),
  optimizer = c("newton", "optim"),
  max.iter = 50L,
  tol = 1e-08,
  return.details = TRUE
)

Arguments

Details

The likelihood.family = "density" branch uses a local exponential tilt of the chart reference measure. The "bernoulli" branch uses a weighted local logistic likelihood and returns fitted probabilities at the evaluation anchors.

Value

A list with class "local_likelihood" containing fitted.values, selected controls, and local solver diagnostics.

Examples

X <- matrix(seq(0, 1, length.out = 21), ncol = 1)
y <- exp(-20 * (X[, 1] - 0.5)^2)
y <- y / sum(y)
fit.local.likelihood(X, y, likelihood.family = "density",
                     support.size = 7L, degree = 0L)

Fit A Local Polynomial Lifting Trend Filter

Description

Fits the Phase-2 LPL-TF estimator with a fixed operator:

\hat f = \arg\min_f \frac12\|y-f\|_2^2 + \lambda\|A_{\mathrm{LPL}}f\|_1.

Usage

fit.lpl.tf(
  X = NULL,
  y,
  operator = NULL,
  adj.list = NULL,
  weight.list = NULL,
  graph = NULL,
  degree = 2L,
  lambda.grid = NULL,
  lambda = NULL,
  lambda.selection = c("cv", "fixed"),
  operator.grid = NULL,
  foldid = NULL,
  cv.folds = 5L,
  cv.loss = c("mse", "rmse", "mae"),
  cv.seed = NULL,
  cv.repeats = 1L,
  solver = c("genlasso"),
  selection = c("min", "one.se"),
  n.lambda = 80L,
  maxsteps = 2000L,
  minlam = 0,
  approx = FALSE,
  rtol = 1e-07,
  btol = 1e-07,
  eps = 1e-04,
  verbose = FALSE,
  ...
)

Arguments

Value

A list of class "lpl_tf".

Examples

if (requireNamespace("genlasso", quietly = TRUE)) {
  X <- matrix(seq(0, 1, length.out = 18), ncol = 1)
  fit.lpl.tf(X, sin(2 * pi * X[, 1]), degree = 1L,
             support.type = "knn", support.size = 7L,
             lambda = 0.1, lambda.selection = "fixed")
}

Fit a Local Polynomial Smoother

Description

Fits a local polynomial smoother (LPS) and selects its support size, polynomial degree, and kernel by cross-validation. By default, the smoother works in the observed ambient coordinates: each prediction point uses its nearest training points in Euclidean distance, centers the support at the prediction point, fits a weighted local polynomial, and uses the fitted intercept as the prediction.

Usage

fit.lps(
  X,
  y,
  foldid = NULL,
  support.grid = c(10L, 15L, 20L),
  degree.grid = 0:2,
  kernel.grid = c("gaussian", "tricube"),
  cv.folds = 5L,
  cv.seed = 1L,
  X.eval = NULL,
  coordinate.method = c("coordinates", "local.pca"),
  chart.dim = NULL,
  chart.dim.grid = NULL,
  local.chart.method = c("pca", "second.order.svd"),
  auto.chart.support.metric = c("coordinates", "operator", "both"),
  auto.chart.selection.metric = c("coordinates", "operator"),
  backend = c("auto", "R", "cpp", "cpp.local.pca"),
  design.basis = c("orthogonal.polynomial.drop", "monomial", "weighted.qr",
    "weighted.qr.drop"),
  design.drop.tol = 1e-08,
  ridge.multiplier.grid = c(0, 1e-10, 1e-08),
  ridge.condition.max = 1e+12,
  unstable.action = c("na", "mean"),
  outcome.family = c("gaussian", "bernoulli", "binomial"),
  bandwidth.multiplier.grid = 1,
  keep.cv.predictions = FALSE,
  ridge.shrinkage.target = c("zero", "local.mean"),
  selection.strategy = c("grid", "sparse_kd", "plateau_kd"),
  chart.activation = c("none", "subject.od"),
  chart.activation.response = NULL,
  chart.activation.control = list(),
  chart.dim.max = NULL,
  design.margin = 2L
)

Arguments

Details

The optional coordinate.method = "local.pca" mode keeps the same support and kernel weighting rule, but builds the local polynomial in a local PCA chart centered at each prediction point. With chart.dim = "auto", the chart dimension is estimated as one global scalar from observed X only, using the same shared local-PCA dimension helper used by LPL-TF and S-LPL-TF. The experimental chart.dim = "local.auto" mode estimates an input-only local chart dimension separately for each prediction anchor.

Value

A list of class "lps" with response-scale fitted.values, unmodified local least-squares fitted.values.raw, selected parameters, a candidate CV table, the requested local.chart.method, and the effective chart method used for reporting. In outcome.family = "bernoulli" or "binomial" mode, fitted.values are response-scale probabilities in [0,1], fitted.values.raw are the un-clipped conditional-expectation estimates for "bernoulli" and the fitted probabilities for "binomial", cv.table$cv.brier.observed is the observed CV Brier score of the response-scale (clipped) predictions with Inf for candidates having any non-finite prediction, and probability.diagnostics records raw/clipped probability ranges, out-of-range fractions, and Brier/log-loss diagnostics. The Brier and log-loss diagnostics are defined only when the fitted predictions have the same length as the training response, which is the default X.eval = X path. In "binomial" mode, logistic.diagnostics records local logistic solve attempts, convergence statuses, fallback-path counts, event-rate fallback counts, and NA failure counts separately for CV and final fitting.

References

Fan, J. and Gijbels, I. (1996). Local Polynomial Modelling and Its Applications. Chapman and Hall/CRC. ISBN 9780412983214.

Examples

X <- matrix(seq(0, 1, length.out = 20), ncol = 1)
y <- sin(2 * pi * X[, 1])
fit <- fit.lps(
  X, y, support.grid = 8L, degree.grid = 1L,
  kernel.grid = "tricube", cv.folds = 2L, backend = "R"
)
head(fit$fitted.values)

Fit Model-Averaged Local Polynomial Smoothing

Description

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

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.

Value

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

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)

Fit Metric-Conductance Graph Low-Pass Regression

Description

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

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"
)

Fit Prediction-Synchronized Local Polynomial Smoothing

Description

Experimental R reference implementation of prediction-synchronized local polynomial smoothing (PS-LPS). For fixed local polynomial parameters, PS-LPS fits one local polynomial chart per anchor and adds a quadratic penalty that synchronizes chart predictions on overlap points.

Usage

fit.ps.lps(
  X,
  y,
  foldid = NULL,
  support.size = NULL,
  degree = 2L,
  kernel = "gaussian",
  chart.dim = NULL,
  support.grid = NULL,
  degree.grid = NULL,
  kernel.grid = NULL,
  auto.chart.support.metric = c("coordinates", "operator", "both"),
  auto.chart.selection.metric = c("coordinates", "operator"),
  chart.dim.grid = NULL,
  selection.strategy = c("grid", "sparse_kd", "plateau_kd"),
  chart.dim.max = NULL,
  design.margin = 2L,
  lambda.sync.grid = c(0, 0.001, 0.01, 0.1, 1, 10),
  lambda.sync.search = c("grid", "guarded"),
  lambda.sync.selection = c("cv", "fixed"),
  local.candidate.search = c("screened", "full", "subgrid"),
  local.candidate.search.control = list(),
  lambda.sync.search.control = list(),
  lambda.diagnostics = c("all", "selected"),
  lambda.ridge = 1e-08,
  design.basis = c("monomial", "weighted.qr", "weighted.qr.drop",
    "orthogonal.polynomial.drop"),
  design.drop.tol = sqrt(.Machine$double.eps),
  ridge.multiplier.grid = NULL,
  ridge.condition.max = Inf,
  sync.neighbor.size = NULL,
  overlap.weight = c("normalized.product", "product"),
  chart.activation = c("none", "subject.od"),
  chart.activation.response = NULL,
  chart.activation.control = list(),
  ps.lps.geometry.cache = NULL,
  ps.lps.local.pca.supports = NULL,
  cv.folds = 5L,
  cv.seed = 1L
)

Arguments

Value

A list with fitted values, selected lambda, CV table, diagnostics, and fitted chart coefficients.

Examples

X <- matrix(seq(0, 1, length.out = 20), ncol = 1)
fit.ps.lps(
  X, sin(2 * pi * X[, 1]), support.size = 7L, degree = 1L,
  chart.dim = 1L, lambda.sync.grid = 0,
  lambda.sync.selection = "fixed", cv.folds = 2L
)

Fit A Parallel-Transport Trend Filter From A PTTF Operator

Description

Fits the first experimental PTTF regression models from a transported difference operator produced by pttf.operator. Phase 3 focuses on one response vector and explicit operator-row policies, especially the 1-D boundary policy used to separate interior transported rows from endpoint rows.

Usage

fit.pttf.trend.filtering(
  geometry = NULL,
  operator = NULL,
  X = NULL,
  y,
  derivative.order = 3L,
  penalty = c("l1", "l2"),
  lambda.grid = NULL,
  lambda.selection = c("cv", "fixed"),
  n.lambda = 80L,
  nfolds = 5L,
  foldid = NULL,
  cv.loss = c("mse", "mae"),
  selection = c("min", "one.se"),
  lambda.extension = c("none", "auto"),
  solver = c("genlasso", "admm", "auto"),
  operator.row.policy = c("all", "drop.line.boundary", "diagnostic.only"),
  line.order = NULL,
  boundary.trim = NULL,
  row.mass.rule = c("none", "node.mass"),
  row.normalize = c("none", "l2"),
  weights = NULL,
  maxsteps = 2000L,
  minlam = 0,
  approx = FALSE,
  rtol = 1e-07,
  btol = 1e-07,
  eps = 1e-04,
  admm.rho = 1,
  admm.maxiter = 2000L,
  admm.abstol = 1e-04,
  admm.reltol = 0.001,
  verbose = FALSE,
  ...
)

Arguments

Value

A list of class "pttf.trend.filtering.fit".

Examples

n <- 10L
X <- matrix(seq(0, 1, length.out = n), ncol = 1)
adj <- lapply(seq_len(n), function(i) intersect(c(i - 1L, i + 1L), 1:n))
lengths <- Map(function(i, j) abs(X[j, 1] - X[i, 1]), seq_len(n), adj)
geometry <- pttf.geometry(
  X, adj, lengths, graph = "supplied", tangent.dim = 1L
)
operator <- pttf.operator(geometry, derivative.order = 2L)
fit.pttf.trend.filtering(
  operator = operator, y = sin(2 * pi * X[, 1]), penalty = "l2",
  lambda.grid = 0.1, lambda.selection = "fixed"
)

Fit A Fixed-Operator Synchronized LPL-TF Model

Description

Fits the fixed-operator S-LPL-TF estimator

\hat f = \arg\min_f \frac12\|y-f\|_2^2 + \lambda_1\|A_{\mathrm{LPL}}f\|_1 + \frac{\lambda_2}{2}\|C_{\mathrm{sync}}f\|_2^2.

Usage

fit.slpl.tf(
  X = NULL,
  y,
  operator = NULL,
  lambda1 = NULL,
  lambda2 = 0,
  lambda1.grid = NULL,
  lambda2.grid = NULL,
  lambda.selection = c("fixed", "cv"),
  operator.grid = NULL,
  foldid = NULL,
  cv.folds = 5L,
  cv.loss = c("mse", "rmse", "mae"),
  cv.seed = NULL,
  cv.repeats = 1L,
  solver = c("genlasso"),
  selection = c("min", "one.se"),
  maxsteps = 2000L,
  minlam = 0,
  approx = FALSE,
  rtol = 1e-07,
  btol = 1e-07,
  eps = 1e-04,
  verbose = FALSE,
  ...
)

Arguments

Value

A list of class "slpl_tf".

Examples

if (requireNamespace("genlasso", quietly = TRUE)) {
  X <- matrix(seq(0, 1, length.out = 18), ncol = 1)
  fit.slpl.tf(X, sin(2 * pi * X[, 1]), degree = 1L,
              support.type = "knn", support.size = 7L,
              lambda1 = 0.1, lambda2 = 0, lambda.selection = "fixed")
}

Fit SSRHE-Style Hessian L1 Regression

Description

Fits an \ell_1-adaptive SSRHE Hessian comparator using the row operator A from ssrhe.hessian.operator:

\widehat f_\lambda = \arg\min_f \left\{ \frac{1}{2}\sum_i w_i(y_i-f_i)^2 + \lambda \|Af\|_1 \right\}.

Usage

fit.ssrhe.hessian.l1.regression(
  X,
  y,
  k = NULL,
  tangent.dim,
  lambda.grid = NULL,
  lambda.selection = c("cv", "fixed"),
  weights = NULL,
  n.lambda = 40L,
  nfolds = 5L,
  fold.id = NULL,
  loss = c("mse", "mae"),
  selection = c("min", "one.se"),
  nn.index = NULL,
  neighborhood.type = c("knn", "adaptive.radius", "supplied"),
  support.index = NULL,
  adaptive.k.scale = NULL,
  radius.rule = c("geomean", "max", "min"),
  radius.factor = 1.25,
  min.support = NULL,
  max.support = NULL,
  support.buffer = 2L,
  support.topup = c("nearest", "none"),
  tangent.dim.rule = c("fixed", "eigen.cumulative"),
  eigen.tolerance = 0.95,
  derivative.order = 2L,
  pinv.tol = sqrt(.Machine$double.eps),
  local.solver = c("auto", "normal.equations", "svd", "qr"),
  normal.equations.max.condition = 10000,
  solver = c("genlasso", "admm", "auto"),
  row.scaling = c("none", "l2"),
  admm.rho = 1,
  admm.maxiter = 2000L,
  admm.abstol = 1e-04,
  admm.reltol = 0.001,
  maxsteps = 2000L,
  minlam = 0,
  approx = FALSE,
  rtol = 1e-07,
  btol = 1e-07,
  eps = 1e-04,
  support.selection = c("rule", "cv"),
  support.grid = NULL,
  support.cv.max.candidates = 8L,
  return.local.diagnostics = FALSE,
  return.timing = FALSE,
  verbose = FALSE
)

Arguments

Details

This function exposes the SSRHE local polynomial derivative estimator as an \ell_1 penalty, rather than as the original SSRHE \ell_2 Hessian-energy penalty used by fit.ssrhe.hessian.regression. With derivative.order = 2L, A contains local quadratic/Hessian rows. With derivative.order = 3L, A contains local cubic third-derivative tensor rows with the same symmetric component scaling used by ssrhe.hessian.operator. The existing \ell_2 fit solves a linear system involving B=A^\top A. This function instead keeps the rows of A and penalizes their absolute values. It is therefore closer in spirit to graph trend filtering, while retaining SSRHE's local-PCA derivative construction.

The default solver backend is genlasso. For larger or numerically fragile third-order operators, solver = "admm" fits the requested lambda values directly without computing a generalized-lasso path, and solver = "auto" falls back to ADMM when the path backend fails or returns non-finite fitted values. Cross-validation removes held-out labels from the data-fit term by setting their weights to zero, then scores predictions on those held-out labels.

With support.selection = "cv", each adaptive-radius support candidate builds a fresh SSRHE operator and runs the usual lambda CV with shared fold assignments. The selected fit is the candidate with the smallest selected CV error. This is useful when the default support-size rule is too rigid, but it can be much slower than tuning lambda for one fixed operator.

Value

A list of class "ssrhe.hessian.l1.fit" containing fitted values, residuals, selected lambda, the SSRHE operator, generalized-lasso path metadata, lambda-grid fitted values, and CV diagnostics when requested.

References

Kim, K. I., Steinke, F., and Hein, M. (2009). Semi-supervised regression using Hessian energy with an application to semi-supervised dimensionality reduction. Advances in Neural Information Processing Systems 22. https://papers.nips.cc/paper_files/paper/2009/hash/f4552671f8909587cf485ea990207f3b-Abstract.html

Examples

X <- matrix(seq(0, 1, length.out = 12), ncol = 1)
fit.ssrhe.hessian.l1.regression(
  X, sin(2 * pi * X[, 1]), k = 6L, tangent.dim = 1L,
  lambda.grid = 0.05, lambda.selection = "fixed", solver = "admm"
)

Fit SSRHE-Style Hessian-Energy Regression

Description

Fits the \ell_2 Hessian-energy regularized estimator associated with ssrhe.hessian.operator. This is a direct SSRHE-style comparator for Hessian smoothing on point clouds; it is not a replacement for graph trend-filtering regression and is distinct from \ell_1-adaptive graph trend filtering.

Usage

fit.ssrhe.hessian.regression(
  X,
  y,
  k = NULL,
  tangent.dim,
  lambda1,
  lambda2 = 0,
  weights = NULL,
  nn.index = NULL,
  neighborhood.type = c("knn", "adaptive.radius", "supplied"),
  support.index = NULL,
  adaptive.k.scale = NULL,
  radius.rule = c("geomean", "max", "min"),
  radius.factor = 1.25,
  min.support = NULL,
  max.support = NULL,
  support.buffer = 2L,
  support.topup = c("nearest", "none"),
  tangent.dim.rule = c("fixed", "eigen.cumulative"),
  eigen.tolerance = 0.95,
  derivative.order = 2L,
  stabilizer = lambda2 > 0,
  pinv.tol = sqrt(.Machine$double.eps),
  local.solver = c("auto", "normal.equations", "svd", "qr"),
  normal.equations.max.condition = 10000,
  ridge = 0,
  return.A = TRUE,
  return.local.diagnostics = FALSE,
  return.timing = FALSE,
  verbose = FALSE
)

Arguments

Details

For each response column, this function solves

(W + \lambda_1 B + \lambda_2 B_S + \epsilon I)\hat f = Wy,

where W is the diagonal matrix of observation weights and \epsilon is ridge. Fully observed data with lambda1 = lambda2 = ridge = 0 therefore reproduce the observed response exactly. Missing responses are excluded from the data-fit term by setting their weights to zero. The Matlab SSRHE semi-supervised convention is represented by a 0/1 labeled-indicator weights vector, or equivalently by setting unlabeled responses to NA: labeled vertices contribute unit diagonal data-fit terms and unlabeled vertices contribute no data-fit term.

The lower-level operator is matched to the Kim–Steinke–Hein SSRHE Matlab construction: self-including kNN neighborhoods, local PCA charts, a fixed-intercept local quadratic fit, doubled diagonal Hessian components, and optional supplemental stabilizer. The package exposes both A and B=A^\top A; the fitted \ell_2 estimator uses B.

Value

A list of class "ssrhe.hessian.fit" containing fitted values, residuals, input response, weights, lambda parameters, objective/energy diagnostics, the reused operator, solver metadata, and the call.

References

Kim, K. I., Steinke, F., and Hein, M. (2009). Semi-supervised regression using Hessian energy with an application to semi-supervised dimensionality reduction. Advances in Neural Information Processing Systems 22. https://papers.nips.cc/paper_files/paper/2009/hash/f4552671f8909587cf485ea990207f3b-Abstract.html

Examples

X <- matrix(seq(0, 1, length.out = 12), ncol = 1)
fit.ssrhe.hessian.regression(
  X, sin(2 * pi * X[, 1]), k = 6L, tangent.dim = 1L, lambda1 = 0.1
)

Select SSRHE Hessian Regression Penalties by Label Cross-Validation

Description

Fits fit.ssrhe.hessian.regression over a grid of fixed lambda1/lambda2 values using cross-validation on observed labels. This is intended for semi-supervised SSRHE use: validation folds are formed only from entries that are observed and have positive data-fit weight.

Usage

fit.ssrhe.hessian.regression.cv(
  X,
  y,
  k = NULL,
  tangent.dim,
  lambda1.grid,
  lambda2.grid = 0,
  weights = NULL,
  nfolds = 5L,
  fold.id = NULL,
  loss = c("mse", "mae"),
  selection = c("min", "one.se"),
  nn.index = NULL,
  neighborhood.type = c("knn", "adaptive.radius", "supplied"),
  support.index = NULL,
  adaptive.k.scale = NULL,
  radius.rule = c("geomean", "max", "min"),
  radius.factor = 1.25,
  min.support = NULL,
  max.support = NULL,
  support.buffer = 2L,
  support.topup = c("nearest", "none"),
  tangent.dim.rule = c("fixed", "eigen.cumulative"),
  eigen.tolerance = 0.95,
  derivative.order = 2L,
  stabilizer = any(lambda2.grid > 0),
  pinv.tol = sqrt(.Machine$double.eps),
  local.solver = c("auto", "normal.equations", "svd", "qr"),
  normal.equations.max.condition = 10000,
  ridge = 0,
  return.A = TRUE,
  return.local.diagnostics = FALSE,
  return.timing = FALSE,
  support.selection = c("rule", "cv"),
  support.grid = NULL,
  support.cv.max.candidates = 8L,
  verbose = FALSE
)

Arguments

Details

For each validation fold, the held-out labels are removed from the data-fit term by setting their weights to zero. The fitted values are then scored only on those held-out labels. The final returned fit is refit with the selected penalties using all observed positive-weight labels.

With support.selection = "cv", this function performs an outer support-profile selection loop. For each candidate adaptive-radius support profile, it constructs a fresh SSRHE operator, runs the usual lambda1.grid/lambda2.grid cross-validation with the same fold assignments, and selects the support profile with the smallest selected CV error. This can substantially increase runtime because local operator construction and lambda CV are nested.

The current implementation supports a single response vector. Matrix-response penalty selection should be performed column-by-column.

Value

A list of class "ssrhe.hessian.cv.fit" and "ssrhe.hessian.fit" containing the final fit plus cv.table, fold.id, and selection diagnostics.

Examples

X <- matrix(seq(0, 1, length.out = 12), ncol = 1)
fit.ssrhe.hessian.regression.cv(
  X, sin(2 * pi * X[, 1]), k = 6L, tangent.dim = 1L,
  lambda1.grid = c(0.01, 0.1), nfolds = 2L
)

Select SSRHE Hessian Regression Penalties by GCV

Description

Fits fit.ssrhe.hessian.regression over a grid of lambda1/lambda2 values and selects penalties by generalized cross-validation (GCV). This is a faster, deterministic alternative to label-fold CV for fully observed SSRHE \ell_2 smoothing problems. The smoother trace can be computed exactly, or estimated by a Hutchinson randomized trace estimator for larger grids.

Usage

fit.ssrhe.hessian.regression.gcv(
  X,
  y,
  k = NULL,
  tangent.dim,
  lambda1.grid,
  lambda2.grid = 0,
  weights = NULL,
  nn.index = NULL,
  neighborhood.type = c("knn", "adaptive.radius", "supplied"),
  support.index = NULL,
  adaptive.k.scale = NULL,
  radius.rule = c("geomean", "max", "min"),
  radius.factor = 1.25,
  min.support = NULL,
  max.support = NULL,
  support.buffer = 2L,
  support.topup = c("nearest", "none"),
  tangent.dim.rule = c("fixed", "eigen.cumulative"),
  eigen.tolerance = 0.95,
  derivative.order = 2L,
  stabilizer = any(lambda2.grid > 0),
  pinv.tol = sqrt(.Machine$double.eps),
  local.solver = c("auto", "normal.equations", "svd", "qr"),
  normal.equations.max.condition = 10000,
  ridge = 0,
  return.A = TRUE,
  return.local.diagnostics = FALSE,
  return.timing = FALSE,
  support.selection = c("rule", "gcv"),
  support.grid = NULL,
  support.gcv.max.candidates = 8L,
  gcv.trace.method = c("exact", "hutchinson"),
  gcv.trace.n.probes = 50L,
  gcv.trace.seed = NULL,
  verbose = FALSE
)

Arguments

Details

For a fixed SSRHE operator, the \ell_2 fit is a linear smoother

\hat f_\lambda = S_\lambda y,\qquad S_\lambda = (W + \lambda_1 B + \lambda_2 B_S + \epsilon I)^{-1} W,

where W is the diagonal observation-weight matrix and \epsilon is ridge. By default this function computes the exact smoother trace \mathrm{tr}(S_\lambda) and scores each grid point by

\mathrm{GCV}(\lambda) = \frac{n^{-1}\sum_i w_i(y_i-\hat f_i)^2} {(1-\mathrm{tr}(S_\lambda)/n)^2}.

With gcv.trace.method = "hutchinson", the trace is estimated by

\mathrm{tr}(S_\lambda) = \mathbb E\{z^\top S_\lambda z\},

using independent Rademacher vectors z. Each probe requires one solve with right-hand side Wz. The estimate is stochastic but can be made reproducible with gcv.trace.seed; the returned GCV table reports the trace standard error.

The current implementation requires a single fully observed response vector and strictly positive observation weights. Semi-supervised or missing-label SSRHE tuning should continue to use fit.ssrhe.hessian.regression.cv.

With support.selection = "gcv", this function performs an outer adaptive-radius support-profile loop. Each support candidate constructs a fresh SSRHE operator, runs the same exact GCV grid search, and the candidate with the smallest selected GCV is refit and returned.

Value

A list of class "ssrhe.hessian.gcv.fit" and "ssrhe.hessian.fit" containing the final fit plus gcv.table, selection, and optional support.gcv.table diagnostics.

Examples

X <- matrix(seq(0, 1, length.out = 12), ncol = 1)
fit.ssrhe.hessian.regression.gcv(
  X, sin(2 * pi * X[, 1]), k = 6L, tangent.dim = 1L,
  lambda1.grid = c(0.01, 0.1)
)

Fit Subject-Occupation Density

Description

Convenience wrapper that converts subject visit indices into a density input. Density-native methods dispatch to fit.density. LPS/PS-LPS methods fit ordinary smoother objects first and then call normalize.density; they are subject-occupation workflows, not standalone density-native methods.

Usage

fit.subject.od(
  X,
  subject.index,
  method = c("empirical", "graph_random_walk", "lps_count", "ps_lps_count",
    "lps_logistic_binary", "chart_kernel", "local_likelihood_density",
    "local_likelihood_bernoulli"),
  graph = NULL,
  graph.control = list(),
  od.control = list(),
  return.details = TRUE,
  od.cv = c("none", "visit"),
  visit.foldid = NULL,
  visit.cv.folds = 5L,
  visit.cv.seed = 1L,
  visit.cv.epsilon = 1e-15,
  ...
)

Arguments

Details

The "lps_logistic_binary" method name is historical. In the current OD workflow it calls fit.lps(..., outcome.family = "bernoulli"), which fits a clipped probability field with the LPS least-squares core and then converts that field to a density with normalize.density. It is not the outcome.family = "binomial" local-logistic IRLS path.

When od.cv = "visit", graph random-walk candidates may pass OD-level grids inside graph.control: walk.step.grid, affinity.method.grid, affinity.scale.grid, affinity.epsilon.grid, and normalize.grid. Missing affinity.scale values mean the usual data-derived affinity scale.

When od.cv = "visit", chart-based and LPS-family methods may pass chart.dim.grid through .... For "chart_kernel", "local_likelihood_density", "local_likelihood_bernoulli", "lps_count", "lps_logistic_binary", and "ps_lps_count", this grid compares fixed integer chart dimensions with optional "auto" and "local.auto" chart-dimension policies under the same held-out-visit negative-log-occupation score. For LPS-family OD visit CV, each outer candidate is passed to the source smoother as a scalar local model configuration; this avoids nested row-level multi-candidate selection inside each held-out-visit fold.

Value

A list of class "density_fit". Its rho component is the estimated probability mass over the rows of X, and empirical.rho is the normalized visit-count mass. The subject component summarizes the number of visits, the number of distinct visited support points, the largest visit multiplicity, and the fraction of repeatedly visited support points. Other components describe the fitted method, normalization accounting, smoothing diagnostics, and warnings as documented in fit.density. With od.cv = "visit" and return.details = TRUE, the result also contains the visit-level cross-validation table, fold assignments, and held-out predicted masses.

Examples

X <- matrix(seq(0, 1, length.out = 6), ncol = 1)
fit.subject.od(X, subject.index = c(1L, 3L, 3L, 6L),
               method = "empirical")

Get Boundary Vertices of a Region in a Graph

Description

Identifies the boundary vertices of a specified region in a graph, defined as vertices in the region that have at least one neighbor outside the region.

Usage

get.region.boundary(adj.list, region)

Arguments

Details

This function determines which vertices in a specified region are positioned at the boundary - meaning they have at least one neighbor that is not part of the region. These boundary vertices are often treated differently in graph-based algorithms, such as harmonic smoothing, where their values are typically fixed as constraints.

The boundary definition used matches the one implemented in the C++ harmonic smoothing functions, focusing on vertices that have connections to the outside of the region.

Value

An integer vector containing the indices of the boundary vertices, which is a subset of the input region vector. Returns an empty integer vector if no boundary vertices exist.

See Also

perform.harmonic.smoothing, harmonic.smoother

Examples

# Create a simple grid graph adjacency list (5x5 grid)
create_grid_adj_list <- function(n_rows, n_cols) {
  n <- n_rows * n_cols
  adj_list <- vector("list", n)
  for (i in 1:n_rows) {
    for (j in 1:n_cols) {
      v <- (i-1) * n_cols + j
      neighbors <- numeric(0)

      # Add neighbors (up, down, left, right)
      if (i > 1) neighbors <- c(neighbors, (i-2) * n_cols + j)  # up
      if (i < n_rows) neighbors <- c(neighbors, i * n_cols + j)  # down
      if (j > 1) neighbors <- c(neighbors, (i-1) * n_cols + (j-1))  # left
      if (j < n_cols) neighbors <- c(neighbors, (i-1) * n_cols + (j+1))  # right

      adj_list[[v]] <- neighbors
    }
  }
  return(adj_list)
}

# Create a 5x5 grid graph
grid_adj_list <- create_grid_adj_list(5, 5)

# Define a region (central 3x3 subgrid)
central_region <- c(7:9, 12:14, 17:19)

# Find boundary vertices of the central region
boundary <- get.region.boundary(grid_adj_list, central_region)
print(boundary)
# Expected output: c(7, 8, 9, 12, 14, 17, 18, 19)
# (all except the center vertex 13)

Construct a Graph Trend-Filtering Operator

Description

Builds the weighted graph difference operators used by graph trend filtering. The default operator.family = "graph.laplacian.recursive" uses the phase-2 recursive graph operators

k=0:\quad \Delta_w^{(1)} = D_w,

k=1:\quad \Delta_w^{(2)} = L_w = D_w^\top D_w,

and

k=2:\quad \Delta_w^{(3)} = D_w L_w.

The experimental operator.family = "path.divided.difference" builds canonical path rows and computes position-aware finite differences along graph paths using weight.list as metric edge lengths.

Usage

graph.trend.filtering.operator(
  adj.list,
  weight.list = NULL,
  order = 0L,
  weight.rule = c("conductance", "sqrt.conductance", "unit"),
  operator.family = c("graph.laplacian.recursive", "path.divided.difference"),
  path.family = c("branch.continuation", "all.simple"),
  path.weighting = c("unit", "anchor.mean"),
  return.sparse = TRUE
)

Arguments

Value

A list of class "graph.trend.filtering.operator" containing the canonical graph, edge table, trend-filtering weights, incidence, weighted Laplacian, selected penalty operator, and nullity estimate.

Examples

adj <- list(2L, c(1L, 3L), c(2L, 4L), 3L)
graph.trend.filtering.operator(adj, order = 1L, weight.rule = "unit")

Perform Harmonic Smoothing with Topology Tracking

Description

Applies harmonic smoothing to function values defined on vertices of a graph while tracking how the topological structure (local extrema and their basins) evolves during the smoothing process. This helps identify the optimal level of smoothing that reduces noise while preserving significant features.

Usage

harmonic.smoother(
  adj.list,
  weight.list,
  values,
  region.vertices,
  max.iterations = 100,
  tolerance = 1e-06,
  record.frequency = 1,
  stability.window = 3,
  stability.threshold = 0.05
)

Arguments

Details

This function extends standard harmonic smoothing by monitoring the evolution of local extrema during the iterative process. It identifies a "sweet spot" where the topological structure stabilizes, indicating that noise has been removed without over-flattening important features.

The algorithm:

1. Iteratively performs harmonic smoothing on interior vertices

2. Periodically identifies local extrema and their basins

3. Monitors the stability of the topological structure

4. Identifies when the topological structure stabilizes

The function returns comprehensive information about the smoothing process, including all intermediate states and the detected stability point.

Value

A list of class "harmonic_smoother" containing:

See Also

perform.harmonic.smoothing for basic smoothing, plot.harmonic_smoother for visualization methods, summary.harmonic_smoother for summary statistics

Examples

adj.list <- list(2L, c(1L, 3L), c(2L, 4L), 3L)
weight.list <- list(1, c(1, 1), c(1, 1), 1)
values <- c(0, 2, -1, 1)
result <- harmonic.smoother(
  adj.list, weight.list, values, region.vertices = seq_along(values),
  max.iterations = 20, record.frequency = 2
)
smoothed.values <- result$harmonic_predictions
smoothed.values

Construct a Local Polynomial Lifting Trend-Filtering Operator

Description

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

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.

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.

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")

Report LPS Backend and Chart-Dimension Diagnostics

Description

Builds a compact one-row diagnostic table for a fitted local polynomial smoother. The table records the requested backend, the backend actually used, the requested chart-dimension rule, the resolved chart dimension, selected tuning parameters, and whether the fit follows the current deployable local-PCA auto-dimension contract.

Usage

lps.backend.diagnostics(object)

Arguments

Details

The current backend policy is conservative: backend = "auto" uses the C++ backend for ambient-coordinate LPS, but uses the R reference backend for coordinate.method = "local.pca". The native local-PCA backend "cpp.local.pca" remains an explicit opt-in backend. This helper makes that policy visible in reports and downstream experiment manifests without changing the default.

For real-data local-PCA runs, the deployable chart-dimension contract is the ordinary local.chart.method = "pca" path with chart.dim = "auto" or "local.auto" and observed-covariate auto-dimension diagnostics. In P7-style experiments this is paired with auto.chart.support.metric = "both" and auto.chart.selection.metric = "operator". The experimental "second.order.svd" chart path is reported explicitly but is not certified by this deployable local-PCA contract. For LPS itself, which uses coordinate supports, the operator-support diagnostic is currently equivalent to the coordinate-support diagnostic; the fields are still recorded so the same manifest schema can be shared with LPL-TF and S-LPL-TF experiments.

Value

A one-row data.frame with backend, chart-dimension, selection, candidate-count, and policy fields.

Examples

X <- matrix(seq(0, 1, length.out = 16), ncol = 1)
fit <- fit.lps(X, X[, 1]^2, support.grid = 6L, degree.grid = 1L,
               kernel.grid = "gaussian", cv.folds = 2L, backend = "R")
lps.backend.diagnostics(fit)

Build a Cluster-Respecting Fold Assignment

Description

Assigns whole clusters to cross-validation folds so that no cluster is split across folds: every observation of a cluster receives the same fold id, and therefore no training set ever shares a cluster with the fold held out against it. Folds are built by a deterministic size-balanced greedy rule: clusters are taken largest first (ties by first appearance in cluster.id) and each is placed into the currently smallest fold (ties by lowest fold index). With v equal to the number of clusters this reduces to leave-cluster-out.

Usage

lps.grouped.foldid(cluster.id, v = 5L, shuffle.seed = NULL)

Arguments

Details

The assignment is fully deterministic when shuffle.seed is NULL. Supplying shuffle.seed applies one seeded permutation to the cluster order before the greedy pass (the seed is consumed immediately via set.seed), giving a reproducible randomized variant; callers following the LPS evidence conventions should record the seed they pass.

Value

An integer fold-id vector of length length(cluster.id) with values in 1:v; every fold is nonempty and every cluster maps to exactly one fold.

See Also

lps.nested.cv() for nested cross-validation that can consume grouped folds at both the outer and inner level.

Examples

cluster <- rep(letters[1:6], each = 2)
lps.grouped.foldid(cluster, v = 3L)

Nested Cross-Validation for LPS with Explicit, Recorded Folds

Description

Runs outer-fold nested cross-validation around fit.lps(): for each outer fold, candidate selection is one ordinary fit.lps call on the inner-training rows only, with an explicit inner fold id and X.eval set to the held-out outer-test rows, so the held-out fold never participates in inner selection. The pooled outer-test error is the nested generalization estimate. The same call also computes the selected-min arm — an ordinary fit.lps on all rows using the same outer.foldid — so optimism comparisons are paired on one fold assignment by construction.

Usage

lps.nested.cv(
  X,
  y,
  outer.foldid,
  fit.args = list(),
  inner.folds = 5L,
  cluster.id = NULL,
  inner.foldid.method = c("round.robin", "grouped"),
  inner.shuffle.seed = NULL
)

Arguments

Details

The existing fit.lps behavior is untouched: this utility consumes the public API with explicit foldid only. It currently supports outcome.family = "gaussian" (the default) and scores with RMSE.

Inner folds are built per outer fold and fully recorded in the return value: "round.robin" assigns rep_len(1:inner.folds, n) over the inner-training rows in row order (deterministic; if inner.shuffle.seed is supplied, fold k — by position — uses set.seed(inner.shuffle.seed + k) and permutes the balanced assignment, giving a reproducible randomized variant); "grouped" builds cluster-respecting inner folds with lps.grouped.foldid() on the inner-training rows of cluster.id (passing the same per-fold offset seed when inner.shuffle.seed is supplied).

Value

A list of class "lps_nested_cv":

nested.rmse

pooled RMSE of the outer-test predictions over all rows with finite predictions.

n.missing.predictions

count of non-finite outer-test predictions (e.g. unstable.action = "na" fallbacks).

folds

one row per outer fold: fold label, test size, selected support.size / degree / kernel / bandwidth.multiplier, the inner selected-min CV score, and the fold's outer-test RMSE.

predictions

length-nrow(X) vector of outer-test predictions (each row predicted by the fold that held it out).

selected.min

the paired selected-min arm on the same outer.foldid: selected (the fit.lps selected row), cv.score (its observed CV RMSE), foldid, and fit (the full-data fit.lps object, usable for deployment on an external test set).

outer.foldid, test.index, train.index, inner.foldid, inner.foldid.used, inner.cv.table

complete fold/index telemetry: the realized inner fold ids as constructed and as recorded by each inner fit.lps ($foldid), per-fold index sets, and each fold's full inner CV candidate table.

outer.cluster.whole

TRUE/FALSE whether every cluster lies wholly inside one outer fold (NA when cluster.id is absent).

inner.folds, inner.foldid.method, inner.shuffle.seed, fit.args, call

the recorded configuration.

See Also

lps.grouped.foldid() for the grouped fold constructor.

Examples

X <- matrix(seq(0, 1, length.out = 18), ncol = 1)
y <- sin(2 * pi * X[, 1])
nested <- lps.nested.cv(
  X, y, outer.foldid = rep(1:3, length.out = 18), inner.folds = 2L,
  fit.args = list(support.grid = 6L, degree.grid = 1L,
                  kernel.grid = "gaussian", backend = "R")
)
nested$rmse

Pointwise Variance and Confidence Band for a Fixed-Configuration LPS Fit

Description

Computes, from the analytically extracted linear-smoother matrix S of a fixed-configuration LPS fit (see lps.smoother.matrix()), the pointwise variance ⁠Var(fitted_i) = sigma^2 * sum_j S_ij^2⁠, the effective degrees of freedom df = tr(S), the plug-in noise estimate sigma.hat^2 = RSS / (n - tr(S)), and the pointwise confidence band ⁠fitted_i +/- z * sigma * ||S_i.||_2⁠ with z = qnorm(1 - (1 - level) / 2).

Usage

lps.pointwise.band(object, sigma = NULL, level = 0.95, check.tol = 1e-10)

Arguments

Details

With sigma supplied (known noise standard deviation), the band uses it directly (sigma.source = "known"); with sigma = NULL the plug-in sigma.hat is used (sigma.source = "plug.in"). sigma.hat is reported in both modes. The variance is purely the linear-smoother sampling variance: the band makes no bias correction, so where bias dominates (boundary, high curvature) undercoverage is expected and must be reported, not masked.

Requires X.eval identical to X (the square training-fit smoother, on which tr(S) and RSS are defined), in addition to all restrictions of lps.smoother.matrix(). If any evaluation point's local fit returned NA, its variance/band entries are NA, and df, rss, and sigma.hat are NA as well; supplying a known sigma still yields bands at the unaffected points.

Value

A list of class "lps.pointwise.band" with named fields: fitted (the fit's raw fitted values), se, variance, lower, upper, level, z, sigma (the supplied known sigma, or NA in plug-in mode), sigma.hat, sigma.source ("known" or "plug.in"), df (tr(S)), rss, n.train, smoother.row.norm (⁠||S_i.||_2⁠), and configuration (the pinned fit configuration).

See Also

lps.smoother.matrix()

Examples

set.seed(1)
n <- 30
X <- matrix(runif(2 * n, -1, 1), ncol = 2)
y <- sin(pi * X[, 1]) + 0.1 * rnorm(n)
fit <- fit.lps(X, y, foldid = rep(1:2, length.out = n),
               support.grid = 12L, degree.grid = 1L,
               kernel.grid = "tricube", backend = "R",
               design.basis = "orthogonal.polynomial.drop",
               ridge.multiplier.grid = 0, ridge.condition.max = Inf,
               unstable.action = "na")
band.known <- lps.pointwise.band(fit, sigma = 0.1)
band.plugin <- lps.pointwise.band(fit)
band.known$df
band.plugin$sigma.hat

Extract the Linear-Smoother Matrix of a Fixed-Configuration LPS Fit

Description

For a fixed configuration (singleton support.grid, degree.grid, and kernel.grid, with an explicit numeric chart dimension) the LPS fitted vector is linear in the response: fitted = S %*% y with S depending on X, the kernel weights, and the configuration, but not on y. This function reconstructs S analytically, one evaluation row at a time, by rebuilding each local fit's support, kernel weights, local chart, and design through the same internal routines fit.lps() used, and reading off the influence row of the local weighted least-squares solve.

Usage

lps.smoother.matrix(object, check.tol = 1e-10)

Arguments

Details

The extraction refuses configurations where the linearity premise fails or is unsupported: it requires outcome.family = "gaussian", the R backend, design.basis = "orthogonal.polynomial.drop", singleton grids (no data-driven selection: the CV-selected pipeline is not a linear smoother), and coordinate.method = "coordinates" or "local.pca" with an explicit numeric chart.dim (never "auto" or "local.auto").

Self-guard: before returning, the function verifies max(abs(S %*% y - fitted.values.raw)) <= check.tol against the fit it was given (and that the NA patterns agree), so any divergence between the reconstruction and the estimator is a hard error, never a silent drift.

Local fits that fell back are represented honestly: a weighted-mean fallback (unstable.action = "mean") contributes its exact linear row w / sum(w); an unstable.action = "na" non-fit contributes an all-NA row.

Value

A numeric matrix S with nrow(object$X.eval) rows and nrow(object$X) columns: row i holds the weights through which the training responses enter the prediction at evaluation point i.

See Also

lps.pointwise.band() for pointwise variances and confidence bands derived from S.

Examples

set.seed(1)
n <- 30
X <- matrix(runif(2 * n, -1, 1), ncol = 2)
y <- sin(pi * X[, 1]) + 0.1 * rnorm(n)
fit <- fit.lps(X, y, foldid = rep(1:2, length.out = n),
               support.grid = 12L, degree.grid = 1L,
               kernel.grid = "tricube", backend = "R",
               design.basis = "orthogonal.polynomial.drop",
               ridge.multiplier.grid = 0, ridge.condition.max = Inf,
               unstable.action = "na")
S <- lps.smoother.matrix(fit)
max(abs(S %*% y - fit$fitted.values))   # ~1e-15: the linear identity
sum(diag(S))                            # effective degrees of freedom

Compute MALPS Linear-Smoother Diagnostics

Description

Computes effective degrees of freedom, generalized cross-validation (GCV), and analytic leave-one-out residual diagnostics from a MALPS smoother matrix. These diagnostics are exact for fixed-support, fixed-weight linear MALPS fits. For cross-validated fits they are conditional on the selected support profile. Robust fits are rejected by default for the same reason described in malps.smoother.matrix.

Usage

malps.gcv(
  object,
  y = NULL,
  smoother.matrix = NULL,
  include.loocv = TRUE,
  max.n = 1000L,
  allow.robust = FALSE,
  ...
)

Arguments

Details

The GCV score is computed as

\mathrm{GCV} = \frac{n^{-1}\|y - S y\|_2^2} {(1 - \operatorname{tr}(S)/n)^2}.

The analytic leave-one-out residuals are computed as

e_i^{\mathrm{loo}} = \frac{y_i - \hat y_i}{1 - S_{ii}}.

Value

A list with residual, fitted-value, EDF, GCV, and optional LOOCV diagnostics.

Examples

X <- matrix(seq(0, 1, length.out = 20), ncol = 1)
fit <- fit.malps(X, X[, 1]^2, degree = 1L,
                 support.type = "knn", support.size = 8L)
malps.gcv(fit)$gcv

Construct The Conditional MALPS Smoother Matrix

Description

Constructs the exact training-point smoother matrix for a fitted fit.malps object, conditional on the stored supports, local charts, fitting weights, and averaging weights. For a non-robust MALPS fit or weighted refit with fixed supports, the returned matrix S satisfies \hat y = S y. If the original fit used cross-validation, this matrix is conditional on the selected support profile; it does not account for the response-dependence of the model-selection step.

Usage

malps.smoother.matrix(object, max.n = 1000L, allow.robust = FALSE, ...)

Arguments

Details

Robust residual reweighting makes the effective fitting weights depend on the response. By default this function therefore rejects robust MALPS fits. Setting allow.robust = TRUE constructs the fixed-final-weight linearization, which reproduces the stored fit but should not be interpreted as the exact response-to-fit map.

Value

A dense numeric n \times n matrix with attributes describing whether the matrix is conditional on support selection and whether it used a robust fixed-weight linearization.

Examples

X <- matrix(seq(0, 1, length.out = 20), ncol = 1)
fit <- fit.malps(X, X[, 1]^2, degree = 1L,
                 support.type = "knn", support.size = 8L)
S <- malps.smoother.matrix(fit)
max(abs(S %*% fit$y - fit$fitted.values))

Materialize a synthetic-data specification

Description

Materialize a synthetic-data specification

Usage

materialize.synthetic(
  spec,
  n = NULL,
  seed,
  rng.policy = c("named.stream.v1", "legacy"),
  validate = TRUE
)

Arguments

Value

A synthetic_dataset.

Examples

spec <- synthetic.registry.spec("G1")
materialize.synthetic(spec, n = 20L, seed = 1L)

Materialize a frozen synthetic instance

Description

Materialize a frozen synthetic instance

Usage

materialize.synthetic.instance(instance.id, validate = TRUE)

Arguments

Value

A synthetic_dataset whose dataset.id is instance.id.

Examples

materialize.synthetic.instance("geosmooth.g1.default.v1")

Construct a Graph Heat-Time Grid

Description

Creates a positive heat-time grid from a "metric.graph.lowpass.basis" object.

Usage

metric.graph.heat.eta.grid(
  basis,
  rule = c("spectral_guarded", "w1_inverse_spectrum"),
  n.initial = 40L,
  include.zero = FALSE,
  truncation.tol = 1e-04,
  equilibrium.tol = 1e-04
)

Arguments

Value

A numeric vector with grid-construction metadata stored as attributes.

Examples

adj <- list(2L, c(1L, 3L), c(2L, 4L), 3L)
lengths <- list(1, c(1, 1), c(1, 1), 1)
basis <- metric.graph.lowpass.basis(adj, lengths, n.eigenpairs = 4L,
                                    eigen.solver = "dense")
metric.graph.heat.eta.grid(basis, n.initial = 6L)

Propose a Guarded Lower Graph Heat Time

Description

Proposes one lower positive heat time after an external search controller has classified the current lower endpoint. The helper enforces a geometric expansion step, an identity-departure floor, a maximum number of expansion rounds, and the truncated-basis resolution certificate. It does not decide whether an endpoint is competitive; fold-level or cohort-level search logic remains the caller's responsibility.

Usage

metric.graph.heat.extend.lower(
  basis,
  eta.grid,
  endpoint.status = c("active", "inactive", "unresolved"),
  expansion.factor = 3,
  max.expansions = 3L,
  expansions.completed = 0L,
  identity.departure = 0.01,
  truncation.tol = 1e-04,
  unresolved.action = c("error", "mark")
)

Arguments

Value

A list of class "metric.graph.heat.lower.extension" with the augmented or unchanged grid and proposal telemetry. A proposal is added only when admitted is TRUE.

Examples

adj <- list(2L, c(1L, 3L), c(2L, 4L), 3L)
lengths <- list(1, c(1, 1), c(1, 1), 1)
basis <- metric.graph.lowpass.basis(adj, lengths, n.eigenpairs = 4L,
                                    eigen.solver = "dense")
eta <- metric.graph.heat.eta.grid(basis, n.initial = 6L)
metric.graph.heat.extend.lower(basis, eta, endpoint.status = "active")

Construct a Reusable Metric Graph Low-Pass Spectral Basis

Description

Builds a metric-conductance graph Laplacian and computes the low-frequency eigensystem used by graph low-pass filters. The resulting object is response-independent and can be reused for many responses and filter parameters.

Usage

metric.graph.lowpass.basis(
  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"),
  n.eigenpairs = 50L,
  eigen.solver = c("auto", "sparse", "dense"),
  dense.eigen.threshold = 200L,
  dense.fallback.threshold = 5000L,
  dense.fallback = c("auto", "never", "always"),
  verbose = FALSE
)

Arguments

Details

The basis is complete only when it contains one eigenvector per graph vertex. A truncated basis represents only the retained low-frequency subspace. The largest retained eigenvalue supplies a conservative proxy for bounding the contribution of omitted modes because all omitted eigenvalues are at least as large.

Value

A list of class "metric.graph.lowpass.basis" containing the graph operator, eigenvalues, eigenvectors, solver metadata, and spectral completeness diagnostics.

Examples

adj <- list(2L, c(1L, 3L), c(2L, 4L), 3L)
lengths <- list(1, c(1, 1), c(1, 1), 1)
metric.graph.lowpass.basis(adj, lengths, n.eigenpairs = 4L,
                           eigen.solver = "dense")

Construct a Metric-Conductance Graph Low-Pass Operator

Description

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

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 phase-1 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.

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.

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)

Normalize Fitted Values Into a Density

Description

Converts a numeric field or fitted smoother/regression object into a probability mass vector over the evaluation support. This is the explicit adapter between ordinary smoothers such as fit.lps, fit.ps.lps, and fit.metric.graph.lowpass and density or occupation-density workflows.

Usage

normalize.density(x, ...)

## S3 method for class 'numeric'
normalize.density(
  x,
  X = NULL,
  density.control = list(),
  method.id = "normalized_numeric",
  keep.source.fit = FALSE,
  adj.list = NULL,
  empirical.rho = NULL,
  return.details = TRUE,
  ...
)

## Default S3 method:
normalize.density(
  x,
  X = NULL,
  density.control = list(),
  method.id = NULL,
  keep.source.fit = TRUE,
  adj.list = NULL,
  empirical.rho = NULL,
  return.details = TRUE,
  ...
)

## S3 method for class 'lps'
normalize.density(
  x,
  X = NULL,
  density.control = list(),
  method.id = NULL,
  keep.source.fit = TRUE,
  adj.list = NULL,
  empirical.rho = NULL,
  return.details = TRUE,
  ...
)

## S3 method for class 'ps_lps'
normalize.density(
  x,
  X = NULL,
  density.control = list(),
  method.id = NULL,
  keep.source.fit = TRUE,
  adj.list = NULL,
  empirical.rho = NULL,
  return.details = TRUE,
  ...
)

## S3 method for class 'metric.graph.lowpass.fit'
normalize.density(
  x,
  X = NULL,
  density.control = list(),
  method.id = NULL,
  keep.source.fit = TRUE,
  adj.list = NULL,
  empirical.rho = NULL,
  return.details = TRUE,
  ...
)

## S3 method for class 'metric.graph.lowpass.refit'
normalize.density(
  x,
  X = NULL,
  density.control = list(),
  method.id = NULL,
  keep.source.fit = TRUE,
  adj.list = NULL,
  empirical.rho = NULL,
  return.details = TRUE,
  ...
)

Arguments

Value

A list of class "density_fit".

Examples

normalize.density(c(0.5, -0.1, 0.6, 0), X = matrix(1:4, ncol = 1))

Perform Harmonic Smoothing on Graph Function Values

Description

Applies harmonic smoothing to function values defined on vertices of a graph, preserving values at the boundary of a specified region while smoothly interpolating interior values. This function implements a discrete Laplace equation solution using weighted averaging.

Usage

perform.harmonic.smoothing(
  adj.list,
  weight.list,
  values,
  region.vertices,
  max.iterations = 100,
  tolerance = 1e-06
)

Arguments

Details

Harmonic smoothing preserves the overall shape of a function defined on a graph while removing local fluctuations. It works by iteratively updating interior vertex values as weighted averages of their neighbors until convergence, while keeping boundary values fixed.

The algorithm:

1. Identifies boundary vertices (vertices with neighbors outside the region or degree 1 vertices)

2. Iteratively updates interior vertex values using edge-weighted averaging

3. Continues until convergence or maximum iterations reached

Edge weights are incorporated by using their inverse as weighting factors, respecting the geometric structure of the graph.

Value

A list containing:

• harmonic_predictions: the numeric vector of smoothed values;

• converged: whether both the maximum update and discrete harmonic residual fell below tolerance;

• num_region, num_boundary, and num_interior: vertex counts for the requested region and its boundary/interior split;

• num_iterations: the number of relaxation iterations run;

• max_change and max_residual: per-iteration convergence diagnostics.

See Also

harmonic.smoother for smoothing with topology tracking, get.region.boundary for boundary vertex identification

Examples

adj.list <- list(2L, c(1L, 3L), c(2L, 4L), 3L)
weight.list <- list(1, c(1, 1), c(1, 1), 1)
values <- c(0, 2, -1, 1)
result <- perform.harmonic.smoothing(
  adj.list, weight.list, values, region.vertices = 1:3
)
result$harmonic_predictions

Plot Method for Harmonic Smoother Results

Description

Creates various plots to visualize the results of harmonic smoothing with topology tracking.

Usage

## S3 method for class 'harmonic_smoother'
plot(x, y = NULL, ..., type = c("topology", "extrema", "values"))

Arguments

Value

Invisibly returns the input object.

See Also

harmonic.smoother

Examples

adj.list <- list(2L, c(1L, 3L), c(2L, 4L), 3L)
weight.list <- list(1, c(1, 1), c(1, 1), 1)
values <- c(0, 2, -1, 1)
result <- harmonic.smoother(
  adj.list, weight.list, values, region.vertices = seq_along(values),
  max.iterations = 20, record.frequency = 2
)
plot(result, type = "values")

Plot a canonical synthetic dataset

Description

One-dimensional datasets show response and truth against the first latent coordinate. Higher-dimensional datasets show the first two predictor coordinates, colored by response or region.

Usage

## S3 method for class 'synthetic_dataset'
plot(x, color = c("response", "truth", "region"), ...)

Arguments

Value

x, invisibly.

Predict From A Local Polynomial Lifting Trend Filter

Description

Predict From A Local Polynomial Lifting Trend Filter

Usage

## S3 method for class 'lpl_tf'
predict(
  object,
  newdata = NULL,
  type = c("response"),
  allow.incomplete = FALSE,
  ...
)

Arguments

Value

Fitted values at the training points.

Predict from an LPS Fit

Description

Predict from an LPS Fit

Usage

## S3 method for class 'lps'
predict(object, newdata = NULL, type = c("response", "raw"), ...)

Arguments

Value

A numeric vector of predictions.

Predict From A MALPS Fit

Description

Predict From A MALPS Fit

Usage

## S3 method for class 'malps'
predict(
  object,
  newdata = NULL,
  type = c("response"),
  allow.incomplete = FALSE,
  ...
)

Arguments

Value

Numeric vector of fitted values.

Predict From A Fixed-Operator Synchronized LPL-TF Model

Description

Predict From A Fixed-Operator Synchronized LPL-TF Model

Usage

## S3 method for class 'slpl_tf'
predict(object, newdata = NULL, type = c("response"), ...)

Arguments

Value

Fitted values at the training points.

Print Method for Harmonic Smoother Results

Description

Prints a concise summary of harmonic smoother results.

Usage

## S3 method for class 'harmonic_smoother'
print(x, ...)

Arguments

Value

Invisibly returns the input object.

See Also

harmonic.smoother, summary.harmonic_smoother

Print Method for Summary of Harmonic Smoother Results

Description

Prints the summary of harmonic smoother results in a formatted manner.

Usage

## S3 method for class 'summary.harmonic_smoother'
print(x, ...)

Arguments

Value

Invisibly returns the input object.

See Also

summary.harmonic_smoother

Print a canonical synthetic dataset

Description

Print a canonical synthetic dataset

Usage

## S3 method for class 'synthetic_dataset'
print(x, ...)

Arguments

Value

x, invisibly.

Construct PTTF Local Geometry

Description

Builds the geometry layer for the experimental parallel-transport trend filtering (PTTF) route. The returned object contains graph supports, local PCA tangent frames, edge directions, orthogonal edge transports, sampling density metadata, and diagnostics. It does not assemble transported difference operators and it does not fit a response.

Usage

pttf.geometry(
  X,
  adj.list = NULL,
  weight.list = NULL,
  graph = c("rknn", "supplied"),
  tangent.dim,
  local.support = c("graph.disk", "neighbors"),
  min.support = NULL,
  max.hops = 3L,
  support.k = NULL,
  graph.k.scale = 1L,
  graph.radius.factor = 1,
  graph.radius.rule = "geomean",
  transport.rule = c("procrustes"),
  synchronize.orientation = TRUE,
  density.method = c("support.radius"),
  alpha = 1,
  diagnostics = TRUE
)

Arguments

Details

The stored transport convention is column-vector based. For an oriented edge i \leftarrow j, Oij maps tangent coordinates from frame j into frame i:

v_j \mapsto O_{ij} v_j.

For shared-support Procrustes, row-coordinate matrices Z_i and Z_j are formed on the same vertex set. The row problem \min_Q \|Z_j Q - Z_i\|_F^2 gives Q = U V^\top when Z_j^\top Z_i = U\Sigma V^\top. The stored column map is O_{ij}=Q^\top=VU^\top; the reported residual is \|Z_j O_{ij}^\top - Z_i\|_F / \max(\|Z_i\|_F,\epsilon).

Value

A list of class "pttf_geometry".

Examples

n <- 10L
X <- matrix(seq(0, 1, length.out = n), ncol = 1)
adj <- lapply(seq_len(n), function(i) intersect(c(i - 1L, i + 1L), 1:n))
lengths <- Map(function(i, j) abs(X[j, 1] - X[i, 1]), seq_len(n), adj)
pttf.geometry(X, adj, lengths, graph = "supplied", tangent.dim = 1L)

Construct PTTF Transported-Difference Operators

Description

Assembles experimental parallel-transport trend-filtering (PTTF) transported-difference operators from a pttf.geometry object. This is an operator-construction function only: it does not fit a response, tune a penalty parameter, or run an \ell_1/\ell_2 smoother.

Usage

pttf.operator(
  geometry,
  derivative.order = 3L,
  edge.status.policy = c("ok.only", "frame.fallback"),
  regression.weight.rule = c("inverse.length.squared", "inverse.length", "unit"),
  edge.length.epsilon = 1e-08,
  tensor.scaling = c("hs", "raw"),
  row.mass.rule = c("node.mass", "none"),
  row.normalize = c("none", "l2"),
  min.operator.rank.tol = 1e-10,
  max.operator.condition = 1e+08,
  return.intermediate = TRUE,
  return.A = TRUE,
  return.B = TRUE,
  diagnostics = TRUE
)

Arguments

Details

Phase 2 keeps a full logical vertex/component layout internally. For order r, the logical field has one block of q_r=\binom{m+r-1}{r} components at each vertex. The returned A is compact: it includes rows only for accepted final-order vertex/component blocks, and row.table$full.row records the original full logical row.

For derivative level r, the local regression uses blocks \Phi_r(u_{ij})\in\mathbb R^{q_{r-1}\times q_r}, lifted weights W_i^{(r)}=\operatorname{diag}(w_{ij})\otimes I_{q_{r-1}}, and transported predecessor differences K_{r-1}(O_{ij})z_j-z_i. Unavailable predecessor blocks are never filled with zero; affected neighbors are dropped and recorded.

Value

A list of class "pttf_operator" containing sparse operators, row/vertex provenance, tensor-basis metadata, and diagnostics.

Examples

n <- 10L
X <- matrix(seq(0, 1, length.out = n), ncol = 1)
adj <- lapply(seq_len(n), function(i) intersect(c(i - 1L, i + 1L), 1:n))
lengths <- Map(function(i, j) abs(X[j, 1] - X[i, 1]), seq_len(n), adj)
geometry <- pttf.geometry(
  X, adj, lengths, graph = "supplied", tangent.dim = 1L
)
pttf.operator(geometry, derivative.order = 2L)

Filter Rows Of A PTTF Operator

Description

Creates a new "pttf_operator" object with a subset of compact operator rows. The sparse triplet payload is rebuilt from the filtered matrix so triplet row indices always refer to the filtered fit rows, while original compact and full logical row identities remain in row.table.

Usage

pttf.operator.filter.rows(
  operator,
  rows,
  reason = NULL,
  preserve.original = TRUE
)

Arguments

Value

A filtered "pttf_operator" object.

Examples

n <- 10L
X <- matrix(seq(0, 1, length.out = n), ncol = 1)
adj <- lapply(seq_len(n), function(i) intersect(c(i - 1L, i + 1L), 1:n))
lengths <- Map(function(i, j) abs(X[j, 1] - X[i, 1]), seq_len(n), adj)
geometry <- pttf.geometry(
  X, adj, lengths, graph = "supplied", tangent.dim = 1L
)
operator <- pttf.operator(geometry, derivative.order = 2L)
pttf.operator.filter.rows(operator, seq_len(max(1L, nrow(operator$A) - 2L)))

Evaluate gradients of all quadforms

Description

Evaluate gradients of all quadforms

Usage

quadform.gradient(geometry, latent)

Arguments

Value

For one form, an n by d matrix. For multiple forms, an n by r by d array. With no forms, an n by zero by d array.

Examples

geometry <- synthetic.quadform(1L, 2L, forms = list(matrix(1)))
quadform.gradient(geometry, matrix(c(-1, 0, 1), ncol = 1))

Evaluate the induced metric of a quadform geometry

Description

Evaluate the induced metric of a quadform geometry

Usage

quadform.metric(geometry, latent)

Arguments

Value

For one row, a d by d matrix; otherwise an n by d by d array.

Examples

geometry <- synthetic.quadform(1L, 2L, forms = list(matrix(1)))
quadform.metric(geometry, matrix(c(0, 1), ncol = 1))

Refit A Local Polynomial Lifting Trend Filter

Description

Reuses the fixed operator and selected lambda from an existing LPL-TF fit.

Usage

refit.lpl.tf(
  object,
  y,
  lambda = NULL,
  reuse.lambda = TRUE,
  verbose = FALSE,
  ...
)

Arguments

Value

A refitted "lpl_tf" object.

Examples

if (requireNamespace("genlasso", quietly = TRUE)) {
  X <- matrix(seq(0, 1, length.out = 18), ncol = 1)
  fit <- fit.lpl.tf(X, X[, 1]^2, degree = 1L,
                    support.type = "knn", support.size = 7L,
                    lambda = 0.1, lambda.selection = "fixed")
  refit.lpl.tf(fit, y = X[, 1]^3)
}

Refit A MALPS Smoother With A New Response

Description

Reuses the anchors, selected support profile, local supports, prediction supports, coordinate method, kernel, degree, and local-solver controls from a previous fit.malps result, then recomputes local polynomial coefficients for a new response vector. Observation weights, when supplied, multiply the stored geometric fitting weights for local coefficient estimation. Supports and model-averaging weights remain fixed. A weighted refit requires every stored local support to retain at least one positive effective fitting weight; sparse bootstrap-style weights can therefore fail even when the global weight vector is not all zero. If the original fit used robust local residual reweighting, robust weights are recomputed for the new response because they are response-dependent.

Usage

refit.malps(
  object,
  y = NULL,
  weights = NULL,
  reuse.selection = TRUE,
  refit.local.coefficients = TRUE,
  verbose = FALSE,
  ...
)

Arguments

Value

A "malps" object with the same support profile and new fitted values.

Examples

X <- matrix(seq(0, 1, length.out = 20), ncol = 1)
fit <- fit.malps(X, X[, 1]^2, degree = 1L,
                 support.type = "knn", support.size = 8L)
refit.malps(fit, y = X[, 1]^3)

Refit Metric-Conductance Graph Low-Pass Regression

Description

Reuses a fitted metric graph low-pass eigensystem to smooth new responses.

Usage

refit.metric.graph.lowpass(
  fitted.model,
  y.new,
  per.column.gcv = FALSE,
  eta.grid = NULL,
  n.candidates = 40L,
  n.cores = 1L,
  block.size = NULL,
  verbose = FALSE
)

Arguments

Value

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

Examples

adj <- list(2L, c(1L, 3L), c(2L, 4L), 3L)
lengths <- list(1, c(1, 1), c(1, 1), 1)
fit <- fit.metric.graph.lowpass(
  adj, lengths, y = 1:4, n.eigenpairs = 4L,
  eta.grid = c(0.1, 1), eigen.solver = "dense"
)
refit.metric.graph.lowpass(fit, y.new = 4:1)

Refit A Fixed-Operator Synchronized LPL-TF Model

Description

Refit A Fixed-Operator Synchronized LPL-TF Model

Usage

refit.slpl.tf(
  object,
  y,
  lambda1 = NULL,
  lambda2 = NULL,
  reuse.lambda = TRUE,
  verbose = FALSE,
  ...
)

Arguments

Value

A refitted "slpl_tf" object.

Examples

if (requireNamespace("genlasso", quietly = TRUE)) {
  X <- matrix(seq(0, 1, length.out = 18), ncol = 1)
  fit <- fit.slpl.tf(X, X[, 1]^2, degree = 1L,
                     support.type = "knn", support.size = 7L,
                     lambda1 = 0.1, lambda2 = 0,
                     lambda.selection = "fixed")
  refit.slpl.tf(fit, y = X[, 1]^3)
}

Refit SSRHE-Style Hessian L1 Regression

Description

Reuses the A operator from fit.ssrhe.hessian.l1.regression to fit a new response or a new lambda grid without rebuilding local neighborhoods or local PCA Hessian rows.

Usage

refit.ssrhe.hessian.l1.regression(
  fitted.model,
  y.new = NULL,
  lambda.grid = fitted.model$lambda,
  lambda.selection = c("fixed", "cv"),
  weights = NULL,
  n.lambda = 40L,
  nfolds = 5L,
  fold.id = NULL,
  loss = c("mse", "mae"),
  selection = c("min", "one.se"),
  solver = c("genlasso", "admm", "auto"),
  row.scaling = c("none", "l2"),
  admm.rho = 1,
  admm.maxiter = 2000L,
  admm.abstol = 1e-04,
  admm.reltol = 0.001,
  maxsteps = 2000L,
  minlam = 0,
  approx = FALSE,
  rtol = 1e-07,
  btol = 1e-07,
  eps = 1e-04,
  verbose = FALSE
)

Arguments

Value

A list of class "ssrhe.hessian.l1.refit".

Examples

X <- matrix(seq(0, 1, length.out = 12), ncol = 1)
fit <- fit.ssrhe.hessian.l1.regression(
  X, X[, 1]^2, k = 6L, tangent.dim = 1L,
  lambda.grid = 0.05, lambda.selection = "fixed", solver = "admm"
)
refit.ssrhe.hessian.l1.regression(
  fit, y.new = X[, 1]^3, solver = "admm"
)

Refit SSRHE-Style Hessian-Energy Regression

Description

Reuses the operator from fit.ssrhe.hessian.regression to fit new responses or new fixed penalty weights without rebuilding local PCA neighborhoods or Hessian-energy matrices.

Usage

refit.ssrhe.hessian.regression(
  fitted.model,
  y.new = NULL,
  lambda1 = fitted.model$lambda$lambda1,
  lambda2 = fitted.model$lambda$lambda2,
  weights = NULL,
  ridge = fitted.model$lambda$ridge,
  verbose = FALSE
)

Arguments

Value

A list of class "ssrhe.hessian.refit".

Examples

X <- matrix(seq(0, 1, length.out = 12), ncol = 1)
fit <- fit.ssrhe.hessian.regression(
  X, X[, 1]^2, k = 6L, tangent.dim = 1L, lambda1 = 0.1
)
refit.ssrhe.hessian.regression(fit, y.new = X[, 1]^3)

Construct A Synchronized LPL-TF Fixed Operator

Description

Builds the fixed S-LPL-TF operator pair. The LPL component A_{\mathrm{LPL}} is the accepted self-excluded LPL-TF residual operator from lpl.tf.operator. The synchronization component C_{\mathrm{sync}} compares inclusive local polynomial prediction maps over overlapping supports.

Usage

slpl.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"),
  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,
  sync.row.normalize = c("l2"),
  sync.min.norm = 1e-12,
  verbose = FALSE,
  ...
)

Arguments

Value

A list of class "slpl_tf_operator" containing A_LPL, C_sync, row metadata, diagnostics, settings, and the embedded "lpl_tf_operator".

Examples

X <- matrix(seq(0, 1, length.out = 18), ncol = 1)
slpl.tf.operator(X, degree = 1L, support.type = "knn",
                 support.size = 7L, kernel = "gaussian")

Construct an SSRHE-Style Local Hessian Energy Operator

Description

Constructs the discrete local Hessian operator used by the semi-supervised regularization framework of Kim, Steinke, and Hein (2009). The constructor is intended as a package-facing, auditable R/C++ port of the reference behavior: it returns the sparse row operator A, the quadratic energy matrix B=A^\top A, and optionally the supplemental stabilizer B_S.

Usage

ssrhe.hessian.operator(
  X,
  k = NULL,
  tangent.dim,
  nn.index = NULL,
  neighborhood.type = c("knn", "adaptive.radius", "supplied"),
  support.index = NULL,
  adaptive.k.scale = NULL,
  radius.rule = c("geomean", "max", "min"),
  radius.factor = 1.25,
  min.support = NULL,
  max.support = NULL,
  support.buffer = 2L,
  support.topup = c("nearest", "none"),
  tangent.dim.rule = c("fixed", "eigen.cumulative"),
  eigen.tolerance = 0.95,
  derivative.order = 2L,
  stabilizer = FALSE,
  pinv.tol = sqrt(.Machine$double.eps),
  local.solver = c("auto", "normal.equations", "svd", "qr"),
  normal.equations.max.condition = 10000,
  return.A = TRUE,
  return.B = TRUE,
  return.BS = stabilizer,
  return.sparse = TRUE,
  return.local.diagnostics = TRUE,
  return.timing = FALSE,
  verbose = FALSE
)

Arguments

Details

For each point x_i, the operator constructs a local PCA chart from a self-including local support, projects the support into \mathbb R^m, and centers the local coordinates at x_i. A local quadratic model is then fitted with the intercept fixed at f_i:

f(x_j) - f(x_i) \approx \sum_{a \le b} h_{ab} z_{ja} z_{jb} + \sum_a g_a z_{ja}.

The local linear map from function values to the quadratic coefficients is the Matlab-compatible

\mathrm{RegMat} = X^+ - X^+ \mathrm{IndMat},

where X is the reduced quadratic-plus-linear design and \mathrm{IndMat} copies the center value into all local rows. Diagonal Hessian components are scaled by \sqrt{2} and off-diagonal components by 1, so that the row energy matches the reference Hessian energy. With derivative.order = 3L, the reduced local design uses cubic monomials first, followed by quadratic and linear monomials. The returned rows estimate unique symmetric third-derivative components \partial_{abc} f with scale

s_{abc}=m_{abc}\sqrt{\mu_{abc}},

where m_{abc} is the factorial monomial-to-derivative multiplier (6 for aaa, 2 for aab, and 1 for three distinct indices) and \mu_{abc} is the ordered-tensor multiplicity (1, 3, or 6). Thus \|Af\|_2^2 approximates the squared Frobenius norm of the full symmetric third-derivative tensor.

The returned A is the stacked sparse matrix of these local derivative coefficient rows. The \ell_2 SSRHE penalty is

f^\top B f = \|Af\|_2^2,\quad B=A^\top A.

Exposing A is useful for auditability and for future \ell_1-style variants based on \|Af\|_1.

Adaptive-radius graph construction uses dgraphs; fixed-k and supplied neighborhoods are package-local geosmooth paths.

Value

A list of class "ssrhe.hessian.operator" containing:

• A: sparse local Hessian row operator, if requested;

• B: sparse quadratic energy matrix A^\top A, if requested;

• BS: optional supplemental stabilizer matrix;

• A.triplet, BS.triplet: raw sparse triplets;

• nn.index: neighbor index matrix for rectangular kNN neighborhoods, if used;

• support.index: list of actual local supports used by the backend;

• neighborhoods: support-construction diagnostics;

• row.table: one row per Hessian component row of A;

• diagnostics: local design rank, condition, and PCA summaries;

• local.diagnostics: if requested, one row per center vertex with support size, design rank/condition, PCA variance, chart-distortion, boundary-asymmetry, and curvature-bias proxy diagnostics;

• timing: if requested, a phase-level elapsed-time table;

• native.timing: if requested, a C++ backend subphase timing table for native operator construction;

• parity: notes documenting reference-behavior conventions.

References

Kim, K. I., Steinke, F., and Hein, M. (2009). Semi-supervised regression using Hessian energy with an application to semi-supervised dimensionality reduction. Advances in Neural Information Processing Systems 22. https://papers.nips.cc/paper_files/paper/2009/hash/f4552671f8909587cf485ea990207f3b-Abstract.html

Examples

X <- matrix(seq(0, 1, length.out = 12), ncol = 1)
ssrhe.hessian.operator(X, k = 6L, tangent.dim = 1L)

Build Candidate Support Profiles for SSRHE Adaptive-Radius Tuning

Description

Constructs a compact grid of adaptive-radius support profiles for use with support.selection = "cv" in SSRHE fitting functions. Each row gives an adaptive.k.scale value and a requested min.support. The grid is intentionally small by default because support selection nests operator construction inside response cross-validation.

Usage

ssrhe.support.grid(
  n,
  tangent.dim,
  derivative.order = 2L,
  support.buffer = 2L,
  max.candidates = 8L
)

Arguments

Value

A data frame with columns adaptive.k.scale, min.support, and max.support. max.support is NA by default, meaning no truncation.

Examples

ssrhe.support.grid(n = 50L, tangent.dim = 2L, max.candidates = 4L)

Summary Method for Harmonic Smoother Results

Description

Provides detailed summary statistics for harmonic smoother results, including the evolution of extrema counts and basin structure differences.

Usage

## S3 method for class 'harmonic_smoother'
summary(object, ...)

Arguments

Value

An object of class "summary.harmonic_smoother" containing:

See Also

harmonic.smoother, print.summary.harmonic_smoother

Specify a circle geometry

Description

Specify a circle geometry

Usage

synthetic.circle(
  radius = 1,
  angle.range = c(0, 2 * pi),
  ambient.dim = 2L,
  frame = c("canonical", "random.orthonormal", "supplied"),
  frame.algorithm = NULL,
  frame.matrix = NULL,
  offset = NULL
)

Arguments

Value

A synthetic geometry component.

Examples

synthetic.circle(radius = 2, angle.range = c(0, pi))

Compute the canonical content checksum of a synthetic dataset

Description

Compute the canonical content checksum of a synthetic dataset

Usage

synthetic.dataset.checksum(x)

Arguments

Value

A lowercase SHA-256 string.

Examples

x <- materialize.synthetic(synthetic.registry.spec("G1"), n = 20L, seed = 1L)
synthetic.dataset.checksum(x)

Specify a helix geometry

Description

Specify a helix geometry

Usage

synthetic.helix(
  pitch = 0.2,
  t.range = c(0, 2 * pi),
  ambient.dim = 3L,
  frame = c("canonical", "random.orthonormal", "supplied"),
  frame.algorithm = NULL,
  frame.matrix = NULL,
  offset = NULL
)

Arguments

Value

A synthetic geometry component.

Examples

synthetic.helix(pitch = 0.25, t.range = c(0, pi))

Specify a point-line junction

Description

Specify a point-line junction

Usage

synthetic.point.line.junction(
  point.location,
  line.origin,
  line.direction,
  line.range
)

Arguments

Value

A two-stratum synthetic_stratified_geometry.

Examples

synthetic.point.line.junction(c(0, 0), c(0, 0), c(1, 0), c(0, 1))

Specify a quadform geometry

Description

Specify a quadform geometry

Usage

synthetic.quadform(
  intrinsic.dim,
  ambient.dim,
  forms = list(),
  frame = c("canonical", "random.orthonormal", "supplied"),
  frame.algorithm = NULL,
  frame.matrix = NULL,
  offset = NULL
)

Arguments

Value

A synthetic geometry component.

Examples

synthetic.quadform(1L, 2L, forms = list(matrix(0.5)))

List maintained synthetic recipe IDs

Description

List maintained synthetic recipe IDs

Usage

synthetic.registry.ids()

Value

Character recipe IDs.

Examples

head(synthetic.registry.ids())

Resolve the legacy seed for an SSRHE registry recipe

Description

Resolve the legacy seed for an SSRHE registry recipe

Usage

synthetic.registry.seed(
  recipe.id,
  replicate = 1L,
  n = NULL,
  base.seed = 273001L
)

Arguments

Value

A validated integer seed.

Examples

synthetic.registry.seed("S16.V1", replicate = 2L)

Resolve a maintained synthetic recipe

Description

Default recipes are reconstructed from normalized component foreign keys. Parameter overrides are accepted only for the legacy G-family compatibility surface and remain content-bound, non-frozen specifications.

Usage

synthetic.registry.spec(recipe.id, parameters = list())

Arguments

Value

A validated synthetic_spec.

Examples

synthetic.registry.spec("G1")

Bernoulli response specification

Description

Bernoulli response specification

Usage

synthetic.response.bernoulli(minimum.positive = 0L, maximum.attempts = 1L)

Arguments

Value

A synthetic response component.

Examples

synthetic.response.bernoulli(minimum.positive = 1L, maximum.attempts = 5L)

Clustered Gaussian response specification

Description

Clustered Gaussian response specification

Usage

synthetic.response.clustered.gaussian(residual.sd, intraclass.correlation)

Arguments

Value

A synthetic response component.

Examples

synthetic.response.clustered.gaussian(0.2, 0.3)

Gaussian response specification

Description

Gaussian response specification

Usage

synthetic.response.gaussian(sd)

Arguments

Value

A synthetic response component.

Examples

synthetic.response.gaussian(sd = 0.2)

Heteroskedastic Gaussian response specification

Description

Heteroskedastic Gaussian response specification

Usage

synthetic.response.heteroskedastic.gaussian(base.sd, truth.multiplier)

Arguments

Value

A synthetic response component.

Examples

synthetic.response.heteroskedastic.gaussian(0.1, 0.2)

Laplace response with Gaussian contamination

Description

Laplace response with Gaussian contamination

Usage

synthetic.response.laplace.outlier(
  laplace.scale,
  outlier.fraction,
  outlier.sd,
  minimum.outliers = 0L,
  count.rounding = "round",
  laplace.algorithm = "uniform.inverse.v1"
)

Arguments

Value

A synthetic response component.

Examples

synthetic.response.laplace.outlier(0.1, 0.05, 1)

Clustered sampling specification

Description

Clustered sampling specification

Usage

synthetic.sampling.clustered(
  cluster.count,
  observations.per.cluster,
  center.lower = -1,
  center.upper = 1,
  within.sd,
  algorithm = "centers.then.gaussian.offsets.v1"
)

Arguments

Value

A fixed-size synthetic sampling component.

Examples

synthetic.sampling.clustered(3L, 5L, within.sd = 0.1)

Dirichlet sampling with structural zeros

Description

Dirichlet sampling with structural zeros

Usage

synthetic.sampling.dirichlet.zeros(
  concentration,
  zero.fraction,
  zero.parts,
  zero.row.policy = c("first", "random"),
  count.rounding = "round",
  algorithm = "normalized.gamma.v1"
)

Arguments

Value

A synthetic sampling component.

Examples

synthetic.sampling.dirichlet.zeros(
  concentration = rep(1, 3), zero.fraction = 0.2, zero.parts = 1L
)

Gapped-uniform sampling specification

Description

Gapped-uniform sampling specification

Usage

synthetic.sampling.gapped.uniform(
  intervals,
  allocation = c("multinomial", "fixed.proportion", "fixed.count"),
  probabilities = NULL,
  counts = NULL,
  rounding = c("largest.remainder", "floor.first.remainder.last"),
  order = c("draw", "ascending"),
  algorithm = "sequential.interval.runif.v1"
)

Arguments

Value

A synthetic sampling component.

Examples

intervals <- rbind(c(-1, -0.25), c(0.25, 1))
synthetic.sampling.gapped.uniform(intervals, probabilities = c(0.5, 0.5))

Deterministic interval-grid sampling specification

Description

Deterministic interval-grid sampling specification

Usage

synthetic.sampling.grid.interval(
  lower,
  upper,
  endpoints = c("exclude.lower", "exclude.upper", "include.both")
)

Arguments

Value

A deterministic synthetic sampling component.

Examples

synthetic.sampling.grid.interval(0, 2 * pi, endpoints = "exclude.lower")

Legacy G4 stratified sampling specification

Description

Legacy G4 stratified sampling specification

Usage

synthetic.sampling.stratified(
  fraction.a = 0.5,
  algorithm = c("stratum.sequential.v1", "legacy.g4.stratum.sequential.v1")
)

Arguments

Value

A synthetic sampling component.

Examples

synthetic.sampling.stratified(fraction.a = 0.6)

Truncated-normal sampling specification

Description

Truncated-normal sampling specification

Usage

synthetic.sampling.truncated.normal(
  mean,
  sd,
  lower,
  upper,
  order = c("draw", "ascending"),
  algorithm = "inverse.cdf.v1"
)

Arguments