Cross-Validate Projection Trend Filtering

Select explicit mean-loss penalties and component counts using supplied folds. Every candidate in every training split repeats preprocessing, direction selection, refinement and joint fitting.

Usage

cv.projection.trend.filtering(
  X,
  y,
  foldid,
  lambda.grid,
  nterms.grid = c(0L, 1L, 2L),
  curve.ridge.grid = 0.001,
  family = c("gaussian", "binomial"),
  directions = NULL,
  direction.search = c("learned", "fixed", "gn", "pls"),
  weights = NULL,
  offset = NULL,
  groups = NULL,
  preprocessing = c("scale", "isotropic", "none"),
  seed = 1L,
  control = list(),
  backend = c("auto", "dense", "banded"),
  keep.fits = FALSE,
  warn = TRUE
)

Arguments

X

Finite numeric predictor matrix or data frame.

y

Finite numeric response. For family="binomial", values must lie in [0,1]; proportions can be accompanied by trial weights.

foldid

Integer vector, or matrix with one column per CV repeat. Each column must contain at least two folds; labels need not be consecutive.

lambda.grid

Nonnegative finite penalties or Inf.

nterms.grid

Nonnegative integer component counts. In fixed mode the nonzero count must match the supplied direction matrix.

curve.ridge.grid

Nonnegative finite component ridge coefficients.

family

"gaussian" or "binomial".

directions

Matrix with one direction per row and one column per original predictor. Directions refer to the preprocessed coordinates. Entries for dropped constant columns must be zero. In learned mode these are additional candidates; in fixed mode these are the fitted directions.

direction.search

"fixed" fits supplied directions (coordinate directions when omitted); "learned" selects and refines directions with pattern search. "gn" uses multistart damped Gauss–Newton proposals; "pls" uses one covariance start per component with the same Gauss–Newton refinement. The latter two modes construct their own starts and do not accept supplied directions.

weights

Positive finite observation weights, default one.

offset

Known additive predictor, default zero.

groups

Optional participant/group labels. All rows of a group must belong to the same fold in each repeat. Groups validate supplied splits; they do not automatically change observation weights.

preprocessing

"scale" centers and scales each nonconstant column; "isotropic" centers and uses a common scale, preserving rotations and distance ratios; "none" leaves retained columns unchanged. All transformations use training weights only. The default is "isotropic" for "gn" and "pls", and "scale" otherwise.

seed

Integer random seed. Local randomness leaves the caller's RNG state unchanged.

control

Named list. max.sweeps=200, tolerance=1e-7, gap.tolerance=1e-8, and objective.tolerance=1e-10 govern joint fitting. inner=list() passes controls to the univariate solver. joint.solver="backfit" retains alternating component updates; joint.solver="dense" attempts a simultaneous dense solve when there are exactly two components, with guarded fallback to backfitting. joint.max.workspace.bytes=1024^3 bounds the estimated dense workspace. The joint certificate and objective safeguard apply to both solvers. Search controls are starts=2, sparse.directions=8, dense.directions=8, refinement.passes=2, refinement.proposals=16, steps=c(0.25,0.1,0.04,0.01), and improvement.tolerance=1e-9. Zero refinement passes select from a fixed candidate bank. The "gn" and "pls" modes instead use gn.max.steps=8 accepted proposals and gn.max.fits=40 native fits per start, with gn.shared.fits=400 shared fits for previously selected components. stream.key=character() can identify a dataset or representation; local start streams also depend on the seed and component number.

backend

Univariate solver: "auto", "dense", or "banded".

keep.fits

Retain training-split fits for inspection, default FALSE.

warn

Warn when joint fitting or a terminal search failure makes the returned fit ineligible. Failed candidates are retained in search.history.

Value

A projection.trend.filtering.cv containing cv.table, the candidate-by-split fold.results, held-out predictions (logits for binomial data), foldid, optional fold.fits, selected.index, fit, and status. selected.index is NULL if validation or the full refit failed; cv.selected.index retains the validation choice when applicable. For Gauss–Newton modes, fold.results separately records numerical.certified, search.eligible, cv.eligible, search.status, requested/effective component counts and native-fit counts, including when keep.fits=FALSE.

Details

Scores pool weighted held-out losses within each repeat and then average repeats. Gaussian selection uses MSE; binomial selection uses stable log loss from logits. Every required fold must converge and predict every held-out row. Fixed and pattern-search modes select the first grid row on equal scores. Gauss–Newton modes also require explicit search eligibility and resolve equal CV scores by fewer requested components, stronger penalty, then grid order. Their random streams are keyed by repeat and fold. Penalties already use mean loss, so no additional fold-mass multiplier is applied by this wrapper. A final full-data refit is performed only for the selected candidate. Its failure is reported without substituting another candidate. CV scores used for selection are not an independent assessment of the selected procedure; use outer folds or a test set.

Examples

X <- matrix(seq(-1, 1, length.out = 24), ncol = 1)
cv <- cv.projection.trend.filtering(X, sin(2*X[,1]),
    foldid = rep(1:3, 8), nterms.grid = 1,
    lambda.grid = c(Inf, 0.001), direction.search = "fixed")
cv$cv.table
#>   nterms lambda curve.ridge candidate    cv.loss eligible
#> 1      1    Inf       0.001         1 0.02975378     TRUE
#> 2      1  0.001       0.001         2 0.01649731     TRUE