Fit A Parallel-Transport Trend Filter From A PTTF Operator

Fits experimental PTTF regression models from a transported difference operator produced by pttf.operator. The implementation 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 = NULL,
  admm.maxiter = 2000L,
  admm.abstol = 1e-04,
  admm.reltol = 0.001,
  verbose = FALSE,
  admm.adaptive.rho = TRUE,
  ...
)

Arguments

geometry

Optional "pttf_geometry" object. Used only when operator is NULL.

operator

Optional "pttf_operator" object. Supplying an operator is recommended for validation so geometry/operator construction is separated from fitting.

X

Optional data matrix used to build pttf.geometry when both geometry and operator are NULL.

y

Numeric response vector.

derivative.order

Integer derivative order passed to pttf.operator when an operator must be built.

penalty

"l1" for generalized-lasso style fitting or "l2" for the quadratic energy fit.

lambda.grid

Optional lambda grid. Required for lambda.selection = "fixed".

lambda.selection

"cv" or "fixed".

n.lambda

Number of lambdas in a generated grid.

nfolds

Number of folds used only when foldid = NULL.

foldid

Optional integer fold assignments. Validation lanes should pass a materialized foldid; otherwise folds are generated by R's current RNG state.

cv.loss

Cross-validation loss, "mse" or "mae".

selection

Lambda selection rule, "min" or "one.se".

lambda.extension

Currently recorded as metadata; no extension heuristic is implemented.

solver

L1 solver backend.

operator.row.policy

Which operator rows to use for fitting.

line.order

Vertex order for 1-D boundary-row policies.

boundary.trim

Number of endpoint ranks to drop for operator.row.policy = "drop.line.boundary". Defaults to derivative.order.

row.mass.rule, row.normalize

Passed to pttf.operator when this function builds an operator. row.normalize is also used as the L1 solver row scaling for the supplied fit operator.

weights

Optional nonnegative observation weights.

maxsteps, minlam, approx, rtol, btol, eps

Genlasso controls for L1 fits.

admm.rho, admm.maxiter, admm.abstol, admm.reltol

ADMM controls used when the L1 backend is "admm" or falls back to ADMM. A NULL initial penalty is chosen from the operator scale. The shared solver's convergence checks, failure behavior, and CV eligibility rules are described in fit.ssrhe.hessian.l1.regression.

verbose

Logical.

admm.adaptive.rho

Logical; adapt the ADMM penalty during the initial iterations. Set FALSE to keep its initial value fixed.

...

Additional arguments passed to pttf.geometry or pttf.operator when those objects are built internally.

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"
)
#> PTTF trend-filtering fit
#>   penalty: l2 
#>   lambda.selection: fixed 
#>   lambda: 0.1 
#>   row policy: all