trex_gvs_control: T-Rex+GVS Control Parameters

View source: R/control_parameters.R

trex_gvs_controlR Documentation

T-Rex+GVS Control Parameters

Description

Build a control list for the grouped variable selection of TRexGVSSelector. The solver follows gvs_type. For "EN" en_solver chooses it: TENET (default), TENET_AUG or the deprecated TCDENET. For "IEN" the solver of trex_control names it, TIENET (native pathwise), TIENET_AUG or the deprecated TCDIENET, so the IEN track needs a base control with one of them. The selector refuses a base control whose solver does not fit the track. TCDIENET is not finally developed: its sweeps grow with lambda_2 and on saturating designs, and a solve that does not converge within cd_max_sweeps raises an error. TCDENET and TCDIENET are deprecated and will be removed with the coordinate-descent family in TRexSelector 2.1.0: the selector raises a deprecation warning for them. Use TENET and TIENET.

Usage

trex_gvs_control(
  gvs_type = "EN",
  corr_max = 0.5,
  hc_linkage = "single",
  lambda_2 = -1,
  lambda2_method = NULL,
  en_solver = "TENET",
  tenet_aug_use_lars = FALSE,
  groups = NULL,
  cv_n_folds = 10,
  cv_n_lambda = 1000,
  cv_n_lambda1 = 40,
  cv_n_lambda2 = 100,
  cv_dfmax_ratio = 0.8,
  cv_seed = -1,
  group_labels = NULL
)

Arguments

gvs_type

Penalty of the grouped selection: "EN" (elastic net) or "IEN" (informed elastic net) (default: "EN").

corr_max

Correlation threshold of the automatic clustering (default: 0.5). The dendrogram is cut at the height 1 - corr_max. With "single" linkage (default) no two variables of different clusters correlate above corr_max. With "complete" linkage every two variables of one cluster correlate at least at corr_max, and variables of different clusters can exceed it.

hc_linkage

Hierarchical clustering linkage: "single", "complete", "average", "wpgma" (default: "single"). Used when no groups are supplied. "ward" is rejected, because its update is valid for squared Euclidean distances only and the correlation distance 1 - abs(cor) is not Euclidean. The capitalized names of TRexSelector 2.0.1 ("Single") are accepted as well.

lambda_2

L2 penalty weight for group structure. A negative value (default -1) triggers automatic determination via the method selected by lambda2_method; 0 is the degenerate pure T-LASSO case (no ridge); a positive value is used as-is. A supplied value refers to the scale of the standardized columns. Under scaling_mode = "ZSCORE" the columns have the squared norm n - 1, so the same shrinkage needs the value times n - 1.

lambda2_method

Auto-determination strategy for lambda_2 when lambda_2 < 0. NULL (default) resolves by track: "CV_1SE_CCD" for gvs_type = "EN" and "CV_1SE_IEN_CCD" for gvs_type = "IEN" (the IEN-geometry tuner consumes the group structure; the 1SE rule is preferred because the MIN rule tends to pin to the grid floor). The C++ core applies the same rule at construction on every surface, so an explicit "CV_1SE_CCD" on the IEN track also runs the IEN tuner. Explicit choices: EN-shaped ridge CV "CV_1SE_CCD", "CV_MIN_CCD", "CV_1SE_SVD", "CV_MIN_SVD" (allowed on both tracks); IEN-geometry "CV_1SE_IEN_CCD", "CV_MIN_IEN_CCD", "CV_1SE_TIK_SVD", "CV_MIN_TIK_SVD" (require gvs_type = "IEN" — they consume the group structure).

en_solver

Elastic Net solver variant for gvs_type = "EN": "TENET" (default, Gram-based), "TENET_AUG" (row-augmented LASSO), or "TCDENET" (coordinate descent; exact fixed-lambda1 elastic-net minimizers per dummy crossing; deprecated, it will be removed in TRexSelector 2.1.0, use "TENET"). All solve the same EN problem and select the same variables up to path-vs-minimizer differences; the switch exists to validate solver equivalence, not to choose a LARS vs LASSO path (for that, see tenet_aug_use_lars).

tenet_aug_use_lars

Logical. For the augmented solvers, en_solver = "TENET_AUG" or gvs_type = "IEN" with the solver "TIENET_AUG": run the augmented system with a pure-LARS inner path that never drops variables (TRUE) instead of the default LASSO inner path that can (FALSE, default). This is the LARS-vs-LASSO distinction. Ignored for "TENET" and "TIENET".

groups

Integer vector of manually specified group assignments, one entry per variable, numbered 1 to M without gaps (default: NULL).

cv_n_folds

Number of folds for the k-fold cross-validation used by the CV lambda2_method paths (default: 10, matching cv.glmnet). Ignored when lambda_2 >= 0.

cv_n_lambda

Number of points on the lambda_2 grid of the rules "CV_1SE_SVD", "CV_MIN_SVD", "CV_1SE_CCD", "CV_MIN_CCD", "CV_1SE_TIK_SVD" and "CV_MIN_TIK_SVD" (default: 1000). The rules "CV_1SE_IEN_CCD" and "CV_MIN_IEN_CCD" use cv_n_lambda2. Ignored when lambda_2 >= 0.

cv_n_lambda1

IEN-geometry coordinate-descent tuners ("CV_1SE_IEN_CCD", "CV_MIN_IEN_CCD") only: points on the profiled lambda_1 path per lambda_2 value (default: 40, the shortest path that still reproduces the 100-point picks; the cost is U-shaped in this number). Ignored by the other rules and when lambda_2 >= 0.

cv_n_lambda2

IEN-geometry coordinate-descent tuners only: points on the lambda_2 grid (default: 100). Ignored by the other rules and when lambda_2 >= 0.

cv_dfmax_ratio

IEN-geometry coordinate-descent tuners only: support cap as a fraction of the smallest fold's training size; each lambda_1 path stops once more than floor(cv_dfmax_ratio * n_train) coefficients are nonzero (default: 0.8). A value <= 0 disables the cap. Larger values allow larger supports at a higher tuner cost. Must be finite. Ignored by the other rules and when lambda_2 >= 0.

cv_seed

Seed for the deterministic fold-permutation RNG used by the CV lambda2_method paths. -1 (default) derives it from the T-Rex seed (deterministic when seed >= 0, hardware entropy when seed < 0); a value >= 0 overrides seed for CV folds only, giving per-trial fold reproducibility.

group_labels

Optional character vector with a name per group of groups, in the order of the group numbers. Its length must equal the number of groups. The names are returned in the field group_labels of the selector (default: NULL).

Value

A named list for use in TRexGVSSelector.

See Also

Other T-Rex selectors and controls: Gauss_data, TRexBiobankScreeningSelector, TRexDASelector, TRexGVSSelector, TRexSPCASelector, TRexScreeningSelector, TRexSelector, TRexTikhonovSelector, trex_biobank_control(), trex_build_group_centering_k(), trex_control(), trex_da_control(), trex_default_lambda2_grid(), trex_dummy_distribution(), trex_fdp(), trex_fdp_dense(), trex_gamma_to_k(), trex_get_num_threads(), trex_gvs_lambda2_power_rule(), trex_normalize_design(), trex_precision(), trex_recall(), trex_screen_control(), trex_spca_control(), trex_tikhonov_control(), trex_tikhonov_lambda2_power_rule(), trex_tpp(), trex_tpp_dense()

Examples

trex_gvs_control()
trex_gvs_control(gvs_type = "IEN", corr_max = 0.3)


TRexSelector documentation built on Nov. 20, 2026, 5:09 p.m.