trex_control: T-Rex Control Parameters

View source: R/control_parameters.R

trex_controlR Documentation

T-Rex Control Parameters

Description

Build a control list for the T-Rex selectors.

Usage

trex_control(
  solver = "TLARS",
  K = 20,
  tloop_stagnation_stop = NULL,
  tloop_max_stagnant_steps = 5,
  parallel_rnd_experiments = FALSE,
  use_memory_mapping = FALSE,
  max_outer_threads = 1,
  max_inner_threads = 1,
  max_dummy_multiplier = 10,
  use_max_T_stop = TRUE,
  opt_threshold = 0.75,
  lloop_strategy = "STANDARD",
  tol = 1e-06,
  lambda2 = 0.1,
  rho_afs = 0.3,
  ncgmp_variant = 0,
  exch_tie_alpha = -1,
  exch_tie_floor = 0.5,
  tenet_aug_use_lars = FALSE,
  cd_lambda_rel_tol = 1e-06,
  cd_tol_certify = -1,
  cd_tol_probe = -1,
  cd_gram_cap = 0,
  cd_max_sweeps = 0,
  cd_certified_localization = TRUE,
  dummy_distribution = trex_dummy_distribution(),
  scaling_mode = c("L2", "ZSCORE", "NONE")
)

Arguments

solver

Solver algorithm: "TLARS", "TLASSO", "TENET", "TENET_AUG", "TSTAGEWISE", "TSTEPWISE", "TOMP", "TGP", "TACGP", "TMP", "TNCGMP", "TOOLS", "TAFS", "TCDLASSO", "TCDENET" (default: "TLARS"). "TENET_AUG" is the row-augmented formulation of the TENET elastic net (proved equivalent for lambda2 >= 0) and is accepted wherever TENET runs; it solves with the standard LASSO inner path unless the optional tenet_aug_use_lars is set. The coordinate-descent (CD) family (TCDLASSO/TCDENET) records exact penalized-lasso minimizers per dummy crossing. The IEN-family names "TIENET", "TIENET_AUG", and "TCDIENET" are accepted by the parser but only dispatchable inside TRexGVSSelector with gvs_type = "IEN"; "TIKNET" needs a penalty matrix and is dispatchable only inside TRexTikhonovSelector. The plain selector rejects both families with an informative error. The coordinate-descent names "TCDLASSO", "TCDENET" and "TCDIENET" are deprecated and will be removed in TRexSelector 2.1.0: a selector that receives one of them raises a deprecation warning. "TCDTIKNET" is deprecated as well, and no selector accepts it any more. Use "TLASSO", "TENET", "TIENET" and "TIKNET", the homotopy solvers of the same problems.

K

Number of random experiments (default: 20, at least 2).

tloop_stagnation_stop

Whether to stop the T-loop on stagnation. NULL (default) leaves the choice to the C++ core, the same rule on every surface: FALSE for the path solvers (TLARS, TLASSO, TENET, TENET_AUG, TIENET, TIENET_AUG, TIKNET and the CD family TCDLASSO, TCDENET, TCDIENET, TCDTIKNET), TRUE for the greedy ones (the OMP family, TSTEPWISE, TSTAGEWISE, TAFS, TNCGMP, TOOLS).

tloop_max_stagnant_steps

Number of T steps in a row without a growing selection that ends the T-loop under the stagnation stop (default: 5, at least 1). The selection is counted at the highest voting level whose FDP estimate does not exceed tFDR.

parallel_rnd_experiments

Run the K random experiments in parallel (default: FALSE, the experiments run in sequence). Inside a parallel run every solver runs serially; the lean L-loop strategies ("SEEDED", "PERMUTATION", "PERMUTATION_SEEDED") always run their experiments in sequence. Was use_openmp.

use_memory_mapping

Keep the dummy matrices in memory-mapped files instead of in memory (default: FALSE).

max_outer_threads

Threads of the parallel K-loop (default: 1; a whole number of at least 1), capped at K. Ignored while parallel_rnd_experiments is FALSE.

max_inner_threads

Thread budget of the solvers' own passes over the design (default: 1, serial; a whole number of at least 1). Live when the experiments run in sequence; inside a parallel run the solvers stay serial. A pass splits only above about a million entries of the design, so small problems run serially whatever the budget.

max_dummy_multiplier

Cap of the dummy multiplier: the L-loop adds dummies up to this many times the number of variables (default: 10).

use_max_T_stop

Whether the T-loop ends at ceiling(n / 2) at the latest (default: TRUE). Without the bound it can run up to the number of dummies.

opt_threshold

Reference voting level of the L-loop (default: 0.75, in [0, 1]). The L-loop raises L until the FDP estimate at the largest voting level that does not exceed opt_threshold is at or below tFDR.

lloop_strategy

L-loop strategy (default: "STANDARD", as in C++ and Python). "STANDARD" draws fresh dummies at every L step, as the 1.x versions do. "HCONCAT" keeps the dummies of the earlier steps and appends p columns per step, which is faster. The two gave the same FDR in simulations and can select differently. "PERMUTATION" stores one base dummy matrix and permutes its rows per experiment. "SKIPL" skips the L-loop and runs with max_dummy_multiplier times p dummies at once. The seeded variants re-derive the dummies from the seed at every step and store nothing: "SEEDED" is the storage-free twin of "STANDARD" (bit-identical to "STANDARD" for the same seed) and "PERMUTATION_SEEDED" the storage-free twin of "PERMUTATION".

tol

Numerical tolerance of the selector (default: 1e-6): the threshold of its own comparisons and the tolerance of the solvers in its random experiments. A stand-alone solver defaults to machine epsilon (tsolver_options). The two tolerances serve different purposes and differ on purpose.

lambda2

Elastic-net L2 penalty (TENET hyperparameter, default: 0.1).

rho_afs

Shrinkage step of TAFS in (0, 1] (default: 0.3); 1 is forward stepwise.

ncgmp_variant

NCGMP variant: 0 = line_search, 1 = fully_corrective (default: 0).

exch_tie_alpha

Exchangeable-tie band width of the greedy solvers (TOMP, TOOLS, TGP, TACGP, TMP, TNCGMP and TAFS), in units of the pairwise ranking-noise sd. When > 0, statistically indistinguishable top candidates within highly correlated clusters are picked uniformly at random per step, restoring the within-experiment occurrence spread that the dependency-aware (DA) deflation's FDR control relies on. -1 (default): the selector decides. TRexDASelector runs with 0.25, every other selector without the band. 0 turns the band off, also under T-Rex+DA. The path solvers ignore the option.

exch_tie_floor

Minimum absolute correlation for exchangeable-tie candidates, in (0, 1) (default: 0.5). Ignored unless exch_tie_alpha > 0.

tenet_aug_use_lars

Logical, for solver = "TENET_AUG" in the plain/DA/screening selectors. The default FALSE runs the STANDARD LASSO inner path (variables can be dropped); TRUE opts into the pure-LARS inner path that never drops variables. Inside TRexGVSSelector use the gvs_control knob of the same name instead. Ignored by every other solver.

cd_lambda_rel_tol

Relative lambda step tolerance of the CCD family's crossing search (default: 1e-6, as in C++ and Python). Values <= 0 keep the solver's internal default. Ignored by the non-CCD solvers. Deprecated: it will be removed with the coordinate-descent family in TRexSelector 2.1.0.

cd_tol_certify

KKT certification tolerance of the CCD family. Must be set together with cd_tol_probe; the default -1 keeps the solver's own tolerances. Ignored by the non-CCD solvers. Deprecated: it will be removed with the coordinate-descent family in TRexSelector 2.1.0.

cd_tol_probe

Probing tolerance of the CCD family's coordinate sweeps. Must be set together with cd_tol_certify; the default -1 keeps the solver's own tolerances. Ignored by the non-CCD solvers. Deprecated: it will be removed with the coordinate-descent family in TRexSelector 2.1.0.

cd_gram_cap

Column cap for the CCD family's cached Gram matrix; above it the solver falls back to the naive updates (default: 0 = keep the solver's internal default). Ignored by the non-CCD solvers. Deprecated: it will be removed with the coordinate-descent family in TRexSelector 2.1.0.

cd_max_sweeps

Maximum coordinate sweeps per CCD subproblem (default: 0 = keep the solver's internal default of 2000). A solve that stops at this budget far from a solution (KKT violation above 0.001 lambda_1) raises an error instead of continuing on an unconverged path. Ignored by the non-CCD solvers. Deprecated: it will be removed with the coordinate-descent family in TRexSelector 2.1.0.

cd_certified_localization

Logical (default TRUE): the CD family localizes every dummy crossing with certificates — a duality gap and coordinate statuses at every bracket endpoint, closed-form continuation between them, the record placed at the knot. FALSE selects the LEGACY probe bisection with the support-nesting stop (the pre-2026-08 behaviour, kept as the A/B baseline). Ignored by the non-CD solvers. Deprecated: it will be removed with the coordinate-descent family in TRexSelector 2.1.0.

dummy_distribution

Dummy variable distribution, created with trex_dummy_distribution (default: standard Normal).

scaling_mode

Working-design convention, one of "L2" (default), "ZSCORE" or "NONE". "L2" centers X and y inside the selector and divides each column of X by its L2 norm; "ZSCORE" centers and divides by the sample SD (glmnet standardize = TRUE convention); the dummies follow the same convention. "NONE" takes X and y exactly as supplied (no centering, no scaling): pre-center and pre-scale as the model demands (trex_normalize_design reproduces the selector's own preprocessing), or supply an intercept-free dictionary (steering vectors, Vandermonde, Fourier atoms) whose columns must not be centered. The dummies keep the unit-L2 standard, so a "NONE" design should be unit-L2-commensurate (a warning names columns whose L2 norm leaves [0.25, 4]). Non-finite entries and dead columns (constant under "L2" / "ZSCORE", all-zero under "NONE") are rejected in every mode with the column named. "L2" and "ZSCORE" standardize the design in place and restore it, so a memory-mapped design must be open in "readwrite" mode; under "NONE" nothing is written and "readonly" mode suffices.

Value

A named list for the constructors of the T-Rex selectors.

Note

Seeds. The seed is an argument of the selector constructors, for example TRexSelector$new(). A seed of 0 or more makes a run deterministic and reproducible: the same seed draws the same dummies. A negative seed (the default -1) draws them from the hardware entropy source, and the run is not reproducible bit by bit. A Monte Carlo study gives every trial a seed of its own, or uses -1.

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_da_control(), trex_default_lambda2_grid(), trex_dummy_distribution(), trex_fdp(), trex_fdp_dense(), trex_gamma_to_k(), trex_get_num_threads(), trex_gvs_control(), 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_control()
trex_control(solver = "TLASSO", K = 10)
trex_control(scaling_mode = "NONE")  # user-managed centering and scaling


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