R/control_parameters.R

Defines functions trex_tikhonov_control trex_dummy_distribution trex_biobank_control trex_screen_control trex_gvs_control trex_da_control .check_group_numbers trex_control

Documented in trex_biobank_control trex_control trex_da_control trex_dummy_distribution trex_gvs_control trex_screen_control trex_tikhonov_control

# =============================================================================
# Control parameter constructor functions for the T-Rex selector variants.
#
# These mirror the Cpp struct hierarchy:
#   trex_control()        -> TRexControlParameter
#   trex_da_control()     -> TRexDAControlParameter
#   trex_gvs_control()    -> GVS control struct
#   trex_screen_control() -> ScreenTRexControlParameter
#   trex_biobank_control()-> BiobankScreenTRex FDR bounds
# =============================================================================

#' @name trex_control
#'
#' @title T-Rex Control Parameters
#'
#' @description Build a control list for the T-Rex selectors.
#'
#' @note **Seeds.** The seed is an argument of the selector constructors, for
#'   example \code{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.
#'
#' @param 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 \code{lambda2 >= 0}) and is accepted wherever TENET
#'   runs; it solves with the standard LASSO inner path unless the optional
#'   \code{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
#'   \code{TRexGVSSelector} with \code{gvs_type = "IEN"}; "TIKNET" needs a
#'   penalty matrix and is dispatchable only inside
#'   \code{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.
#' @param K Number of random experiments (default: 20, at least 2).
#' @param 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).
#' @param 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 \code{tFDR}.
#' @param parallel_rnd_experiments Run the K random experiments in parallel
#'   (default: \code{FALSE}, the experiments run in sequence). Inside a
#'   parallel run every solver runs serially; the lean L-loop strategies
#'   (\code{"SEEDED"}, \code{"PERMUTATION"}, \code{"PERMUTATION_SEEDED"})
#'   always run their experiments in sequence. Was \code{use_openmp}.
#' @param use_memory_mapping Keep the dummy matrices in memory-mapped files
#'   instead of in memory (default: FALSE).
#' @param max_outer_threads Threads of the parallel K-loop (default: 1; a
#'   whole number of at least 1), capped at \code{K}. Ignored while
#'   \code{parallel_rnd_experiments} is \code{FALSE}.
#' @param 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.
#' @param max_dummy_multiplier Cap of the dummy multiplier: the L-loop adds dummies up to
#'   this many times the number of variables (default: 10).
#' @param use_max_T_stop Whether the T-loop ends at \code{ceiling(n / 2)} at the latest
#'   (default: TRUE). Without the bound it can run up to the number of dummies.
#' @param opt_threshold Reference voting level of the L-loop (default: 0.75, in
#'   \code{[0, 1]}). The L-loop raises L until the FDP estimate at the largest
#'   voting level that does not exceed \code{opt_threshold} is at or below
#'   \code{tFDR}.
#' @param 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 \code{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".
#' @param 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 (\code{\link{tsolver_options}}).
#'   The two tolerances serve different purposes and differ on purpose.
#' @param lambda2 Elastic-net L2 penalty (TENET hyperparameter, default: 0.1).
#' @param rho_afs Shrinkage step of TAFS in (0, 1] (default: 0.3); 1 is forward stepwise.
#' @param ncgmp_variant NCGMP variant: 0 = line_search, 1 = fully_corrective (default: 0).
#' @param 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.
#'   \code{-1} (default): the selector decides. \code{TRexDASelector} runs
#'   with 0.25, every other selector without the band. \code{0} turns the
#'   band off, also under T-Rex+DA. The path solvers ignore the option.
#' @param exch_tie_floor Minimum absolute correlation for exchangeable-tie
#'   candidates, in (0, 1) (default: 0.5). Ignored unless
#'   \code{exch_tie_alpha > 0}.
#' @param tenet_aug_use_lars Logical, for \code{solver = "TENET_AUG"} in the
#'   plain/DA/screening selectors. The default \code{FALSE} runs the
#'   STANDARD LASSO inner path (variables can be dropped); \code{TRUE}
#'   opts into the pure-LARS inner path that never drops variables. Inside
#'   \code{TRexGVSSelector} use the \code{gvs_control} knob of the same
#'   name instead. Ignored by every other solver.
#' @param 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.
#' @param cd_tol_certify KKT certification tolerance of the CCD family. Must
#'   be set together with \code{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.
#' @param cd_tol_probe Probing tolerance of the CCD family's coordinate
#'   sweeps. Must be set together with \code{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.
#' @param 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.
#' @param 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.
#' @param cd_certified_localization Logical (default \code{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.
#'   \code{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.
#' @param dummy_distribution Dummy variable distribution, created with
#'   \code{\link{trex_dummy_distribution}} (default: standard Normal).
#' @param scaling_mode Working-design convention, one of \code{"L2"}
#'   (default), \code{"ZSCORE"} or \code{"NONE"}. \code{"L2"} centers
#'   \code{X} and \code{y} inside the selector and divides each column of
#'   \code{X} by its L2 norm; \code{"ZSCORE"} centers and divides by the
#'   sample SD (glmnet \code{standardize = TRUE} convention); the dummies
#'   follow the same convention. \code{"NONE"} takes \code{X} and \code{y}
#'   exactly as supplied (no centering, no scaling): pre-center and
#'   pre-scale as the model demands (\code{\link{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 \code{"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
#'   \code{"L2"} / \code{"ZSCORE"}, all-zero under \code{"NONE"}) are
#'   rejected in every mode with the column named. \code{"L2"} and
#'   \code{"ZSCORE"} standardize the design in place and restore it, so a
#'   memory-mapped design must be open in \code{"readwrite"} mode; under
#'   \code{"NONE"} nothing is written and \code{"readonly"} mode suffices.
#'
#' @return A named list for the constructors of the T-Rex selectors.
#'
#' @examples
#' trex_control()
#' trex_control(solver = "TLASSO", K = 10)
#' trex_control(scaling_mode = "NONE")  # user-managed centering and scaling
#'
#' @family T-Rex selectors and controls
#' @export
trex_control <- function(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-6,
                         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-6,
                         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")) {

  if (max_dummy_multiplier < 1) {
    stop("max_dummy_multiplier must be >= 1. Got: ", max_dummy_multiplier)
  }
  if (!is.character(scaling_mode) || length(scaling_mode) < 1 ||
      !(scaling_mode[1] %in% c("L2", "ZSCORE", "NONE"))) {
    stop("scaling_mode must be one of \"L2\", \"ZSCORE\", \"NONE\". Got: ",
         paste(scaling_mode, collapse = ", "))
  }
  scaling_mode <- scaling_mode[1]
  if (tloop_max_stagnant_steps < 1) {
    stop("tloop_max_stagnant_steps must be >= 1. Got: ", tloop_max_stagnant_steps)
  }
  if (max_outer_threads < 1) {
    stop("max_outer_threads must be >= 1. Got: ", max_outer_threads)
  }
  if (max_inner_threads < 1) {
    stop("max_inner_threads must be >= 1. Got: ", max_inner_threads)
  }
  # The C++ side applies the certify/probe pair only when BOTH are > 0;
  # fail loudly here instead of silently ignoring a half-set pair.
  if (xor(cd_tol_certify > 0, cd_tol_probe > 0)) {
    stop("cd_tol_certify and cd_tol_probe must be set together (both > 0), ",
         "or both left at their defaults. Got: cd_tol_certify = ",
         cd_tol_certify, ", cd_tol_probe = ", cd_tol_probe)
  }
  if (cd_gram_cap < 0) {
    stop("cd_gram_cap must be >= 0. Got: ", cd_gram_cap)
  }
  if (cd_max_sweeps < 0) {
    stop("cd_max_sweeps must be >= 0. Got: ", cd_max_sweeps)
  }

  # NULL stays NULL: the C++ core resolves it by its own solver rule, the one
  # source of the default for the three surfaces
  if (!is.null(tloop_stagnation_stop)) {
    tloop_stagnation_stop <- as.logical(tloop_stagnation_stop)
  }

  list(
    solver                  = solver,
    K                       = K,
    max_dummy_multiplier    = max_dummy_multiplier,
    use_max_T_stop          = use_max_T_stop,
    opt_threshold           = opt_threshold,
    lloop_strategy          = lloop_strategy,
    tloop_stagnation_stop   = tloop_stagnation_stop,
    tloop_max_stagnant_steps = tloop_max_stagnant_steps,
    parallel_rnd_experiments = as.logical(parallel_rnd_experiments),
    use_memory_mapping      = use_memory_mapping,
    max_outer_threads       = max_outer_threads,
    max_inner_threads       = max_inner_threads,
    tol                     = tol,
    lambda2                 = lambda2,
    rho_afs                 = rho_afs,
    ncgmp_variant           = ncgmp_variant,
    exch_tie_alpha          = exch_tie_alpha,
    exch_tie_floor          = exch_tie_floor,
    tenet_aug_use_lars      = tenet_aug_use_lars,
    cd_lambda_rel_tol       = cd_lambda_rel_tol,
    cd_tol_certify          = cd_tol_certify,
    cd_tol_probe            = cd_tol_probe,
    cd_gram_cap             = cd_gram_cap,
    cd_max_sweeps           = cd_max_sweeps,
    cd_certified_localization = as.logical(cd_certified_localization),
    dummy_distribution      = dummy_distribution,
    scaling_mode            = scaling_mode
  )
}


# Group numbers of an R argument: 1 to M without gaps, one whole number per
# variable. The core counts from 0, so its own messages would not fit R.
.check_group_numbers <- function(groups, name) {
  whole <- is.numeric(groups) && length(groups) > 0 && !anyNA(groups) &&
    all(groups == round(groups))
  if (!whole || min(groups) < 1 || length(unique(groups)) != max(groups)) {
    stop(name, " must number the groups 1 to M without gaps, with one whole ",
         "number per variable.")
  }
  invisible(NULL)
}


#' @name trex_da_control
#'
#' @title T-Rex+DA Control Parameters
#'
#' @description Build a control list for the dependency-aware correction of TRexDASelector.
#'
#' @param da_method Dependency model (default: "BT"). "BT", the binary tree, is made
#'   for disjoint groups of highly correlated variables. "NN", nearest neighbours, is
#'   made for overlapping groups of highly correlated variables and sweeps the
#'   correlation thresholds of a rho grid of length \code{hc_grid_length}. "AR1" is
#'   made for a first-order autoregressive dependency across the columns. "EQUI" is
#'   made for variables that all share one correlation.
#' @param cor_coef Correlation coefficient for AR1/EQUI. -2.0 triggers auto-estimation
#'   (default: -2.0). The estimate is the mean lag-1 autocorrelation of the rows for AR1
#'   and the mean pairwise correlation of the variables for EQUI. Both methods use the
#'   magnitude of a supplied coefficient. Any other value outside \code{[-1, 1]} gives a
#'   warning and is replaced by the estimate.
#' @param rho_thr_DA Correlation threshold of the AR1 and EQUI methods (default: 0.02).
#'   AR1: the window around a variable reaches
#'   \code{ceiling(log(rho_thr_DA) / log(abs(cor_coef)))} columns to each side, up to the
#'   first lag whose correlation \code{abs(cor_coef)^lag} has fallen to the threshold,
#'   range \code{[0, 1)}. EQUI: the correction is skipped when \code{abs(cor_coef)} does
#'   not exceed the threshold, range \code{[0, 1]}.
#' @param hc_linkage Hierarchical clustering linkage: "single", "complete", "average",
#'   "wpgma" (default: "single"). Used by BT and by prior groups. "ward" is rejected,
#'   because its update is valid for squared Euclidean distances only and the correlation
#'   distance \code{1 - abs(cor)} is not Euclidean. The capitalized names of
#'   TRexSelector 2.0.1 ("Single") are accepted as well.
#' @param hc_grid_length Number of correlation thresholds on the calibration grid of BT,
#'   NN and prior groups. \code{0} (default) takes \code{min(20, p)}.
#' @param prior_groups Optional prior grouping constraints: a list of integer
#'   vectors, each of length \code{p}, giving non-negative group labels per
#'   variable. When supplied (non-\code{NULL}, non-empty), the prior-groups
#'   dependency-aware path is used and \code{da_method} is ignored: the finest
#'   common refinement of all supplied levels acts as a hard merge constraint,
#'   hierarchical clustering (\code{hc_linkage}, correlation distance) runs
#'   within each constraint group, and the calibration rho grid (length
#'   \code{hc_grid_length}) is built from the pooled within-group dendrogram
#'   heights plus the conservative rho = 1 singleton anchor. The deflation
#'   therefore acts on tight data-driven neighbourhoods inside the known
#'   groups, never on the raw groups themselves. (default: \code{NULL}).
#' @param bt_selection_mode Which cells of the calibration grid may win the selection
#'   of the methods BT, NN and prior groups. \code{"FeasibleOnly"} (default) admits
#'   only cells whose FDP estimate is at or below the target, which controls the
#'   realized FDR. \code{"RFaithful"} admits every cell with the largest selection
#'   count, as the 1.x versions of the package do, and can exceed the target at
#'   high within-group correlation. Ignored by AR1 and EQUI.
#'
#' @return A named list for use in TRexDASelector.
#'
#' @examples
#' trex_da_control()
#' trex_da_control(da_method = "BT", hc_linkage = "average")
#' # Prior-groups path (constraints over p = 4 variables):
#' trex_da_control(prior_groups = list(c(1, 1, 2, 2)))
#'
#' @family T-Rex selectors and controls
#' @export
trex_da_control <- function(da_method = "BT",
                            cor_coef = -2.0,
                            rho_thr_DA = 0.02,
                            hc_linkage = "single",
                            hc_grid_length = 0,
                            prior_groups = NULL,
                            bt_selection_mode = "FeasibleOnly") {
  bt_selection_mode <- match.arg(bt_selection_mode, c("FeasibleOnly", "RFaithful"))
  list(
    da_method         = da_method,
    cor_coef          = cor_coef,
    rho_thr_DA        = rho_thr_DA,
    hc_linkage        = tolower(hc_linkage),
    hc_grid_length    = hc_grid_length,
    prior_groups      = prior_groups,
    bt_selection_mode = bt_selection_mode
  )
}


#' @name trex_gvs_control
#'
#' @title T-Rex+GVS Control Parameters
#'
#' @description Build a control list for the grouped variable selection of
#'   \code{\link{TRexGVSSelector}}. The solver follows \code{gvs_type}. For
#'   "EN" \code{en_solver} chooses it: TENET (default), TENET_AUG or the
#'   deprecated TCDENET. For "IEN" the \code{solver} of
#'   \code{\link{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 \code{lambda_2} and on saturating designs, and a solve
#'   that does not converge within \code{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.
#'
#' @param gvs_type Penalty of the grouped selection: "EN" (elastic net) or "IEN" (informed
#'   elastic net) (default: "EN").
#' @param corr_max Correlation threshold of the automatic clustering (default: 0.5). The
#'   dendrogram is cut at the height \code{1 - corr_max}. With "single" linkage (default)
#'   no two variables of different clusters correlate above \code{corr_max}. With
#'   "complete" linkage every two variables of one cluster correlate at least at
#'   \code{corr_max}, and variables of different clusters can exceed it.
#' @param hc_linkage Hierarchical clustering linkage: "single", "complete", "average",
#'   "wpgma" (default: "single"). Used when no \code{groups} are supplied. "ward" is
#'   rejected, because its update is valid for squared Euclidean distances only and the
#'   correlation distance \code{1 - abs(cor)} is not Euclidean. The capitalized names of
#'   TRexSelector 2.0.1 ("Single") are accepted as well.
#' @param lambda_2 L2 penalty weight for group structure.
#'   A negative value (default \code{-1}) triggers automatic determination via
#'   the method selected by \code{lambda2_method}; \code{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
#'   \code{scaling_mode = "ZSCORE"} the columns have the squared norm \code{n - 1}, so the
#'   same shrinkage needs the value times \code{n - 1}.
#' @param lambda2_method Auto-determination strategy for \code{lambda_2} when
#'   \code{lambda_2 < 0}. \code{NULL} (default) resolves by track:
#'   \code{"CV_1SE_CCD"} for \code{gvs_type = "EN"} and
#'   \code{"CV_1SE_IEN_CCD"} for \code{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
#'   \code{"CV_1SE_CCD"} on the IEN track also runs the IEN tuner. Explicit choices:
#'   EN-shaped ridge CV \code{"CV_1SE_CCD"}, \code{"CV_MIN_CCD"},
#'   \code{"CV_1SE_SVD"}, \code{"CV_MIN_SVD"} (allowed on both tracks);
#'   IEN-geometry \code{"CV_1SE_IEN_CCD"}, \code{"CV_MIN_IEN_CCD"},
#'   \code{"CV_1SE_TIK_SVD"}, \code{"CV_MIN_TIK_SVD"} (require
#'   \code{gvs_type = "IEN"} — they consume the group structure).
#' @param en_solver Elastic Net solver variant for \code{gvs_type = "EN"}:
#'   \code{"TENET"} (default, Gram-based), \code{"TENET_AUG"}
#'   (row-augmented LASSO), or \code{"TCDENET"} (coordinate descent; exact
#'   fixed-lambda1 elastic-net minimizers per dummy crossing; deprecated,
#'   it will be removed in TRexSelector 2.1.0, use \code{"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,
#'   \strong{not} to choose a LARS vs LASSO path (for that, see
#'   \code{tenet_aug_use_lars}).
#' @param tenet_aug_use_lars Logical. For the augmented solvers, \code{en_solver =
#'   "TENET_AUG"} or \code{gvs_type = "IEN"} with the solver \code{"TIENET_AUG"}: run
#'   the augmented system with a pure-LARS inner path that never drops variables
#'   (\code{TRUE}) instead of the default LASSO inner path that can
#'   (\code{FALSE}, default). This is the LARS-vs-LASSO distinction. Ignored for
#'   \code{"TENET"} and \code{"TIENET"}.
#' @param groups Integer vector of manually specified group assignments, one entry per
#'   variable, numbered 1 to M without gaps (default: NULL).
#' @param group_labels Optional character vector with a name per group of \code{groups}, in
#'   the order of the group numbers. Its length must equal the number of groups. The names
#'   are returned in the field \code{group_labels} of the selector (default: NULL).
#' @param cv_n_folds Number of folds for the k-fold cross-validation used by the
#'   CV \code{lambda2_method} paths (default: 10, matching \code{cv.glmnet}).
#'   Ignored when \code{lambda_2 >= 0}.
#' @param cv_n_lambda Number of points on the \code{lambda_2} grid of the rules
#'   \code{"CV_1SE_SVD"}, \code{"CV_MIN_SVD"}, \code{"CV_1SE_CCD"}, \code{"CV_MIN_CCD"},
#'   \code{"CV_1SE_TIK_SVD"} and \code{"CV_MIN_TIK_SVD"} (default: 1000). The rules
#'   \code{"CV_1SE_IEN_CCD"} and \code{"CV_MIN_IEN_CCD"} use \code{cv_n_lambda2}.
#'   Ignored when \code{lambda_2 >= 0}.
#' @param cv_n_lambda1 IEN-geometry coordinate-descent tuners
#'   (\code{"CV_1SE_IEN_CCD"}, \code{"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
#'   \code{lambda_2 >= 0}.
#' @param cv_n_lambda2 IEN-geometry coordinate-descent tuners only: points
#'   on the lambda_2 grid (default: 100). Ignored by the other rules and
#'   when \code{lambda_2 >= 0}.
#' @param 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 \code{floor(cv_dfmax_ratio * n_train)}
#'   coefficients are nonzero (default: 0.8). A value \code{<= 0} disables
#'   the cap. Larger values allow larger supports at a higher tuner cost.
#'   Must be finite. Ignored by the other rules and when
#'   \code{lambda_2 >= 0}.
#' @param cv_seed Seed for the deterministic fold-permutation RNG used by the CV
#'   \code{lambda2_method} paths. \code{-1} (default) derives it from the T-Rex
#'   \code{seed} (deterministic when \code{seed >= 0}, hardware entropy when
#'   \code{seed < 0}); a value \code{>= 0} overrides \code{seed} for CV folds
#'   only, giving per-trial fold reproducibility.
#'
#' @return A named list for use in TRexGVSSelector.
#'
#' @examples
#' trex_gvs_control()
#' trex_gvs_control(gvs_type = "IEN", corr_max = 0.3)
#'
#' @family T-Rex selectors and controls
#' @export
trex_gvs_control <- function(gvs_type = "EN",
                             corr_max = 0.5,
                             hc_linkage = "single",
                             lambda_2 = -1.0,
                             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) {
  # NULL resolves by track: the EN-shaped ridge CV for EN, the IEN-geometry
  # tuner (group-consuming, no p/2 conversion) for IEN. 1SE in both cases —
  # the MIN rule tends to pin to the grid floor.
  if (is.null(lambda2_method)) {
    lambda2_method <- if (gvs_type == "IEN") "CV_1SE_IEN_CCD" else "CV_1SE_CCD"
  }
  lambda2_method <- match.arg(lambda2_method,
                              c("CV_1SE_CCD", "CV_MIN_CCD",
                                "CV_1SE_SVD", "CV_MIN_SVD",
                                "CV_1SE_IEN_CCD", "CV_MIN_IEN_CCD",
                                "CV_1SE_TIK_SVD", "CV_MIN_TIK_SVD"))
  ien_methods <- c("CV_1SE_IEN_CCD", "CV_MIN_IEN_CCD",
                   "CV_1SE_TIK_SVD", "CV_MIN_TIK_SVD")
  if (gvs_type == "EN" && lambda2_method %in% ien_methods) {
    stop("lambda2_method = \"", lambda2_method, "\" is an IEN-geometry ",
         "tuner (it consumes the group structure) and requires ",
         "gvs_type = \"IEN\".")
  }
  en_solver <- match.arg(en_solver, c("TENET", "TENET_AUG", "TCDENET"))
  if (!is.null(groups)) {
    .check_group_numbers(groups, "groups")
  }
  dfmax_ok <- is.numeric(cv_dfmax_ratio) && length(cv_dfmax_ratio) == 1 &&
    is.finite(cv_dfmax_ratio)
  if (!dfmax_ok) {
    stop("cv_dfmax_ratio must be a single finite number (<= 0 disables the ",
         "support cap). Got: ", format(cv_dfmax_ratio))
  }
  list(
    gvs_type           = gvs_type,
    corr_max           = corr_max,
    hc_linkage         = tolower(hc_linkage),
    lambda_2           = lambda_2,
    lambda2_method     = lambda2_method,
    en_solver          = en_solver,
    tenet_aug_use_lars = as.logical(tenet_aug_use_lars),
    groups             = groups,
    group_labels       = if (is.null(group_labels)) NULL else as.character(group_labels),
    cv_n_folds         = as.integer(cv_n_folds),
    cv_n_lambda        = as.integer(cv_n_lambda),
    cv_n_lambda1       = as.integer(cv_n_lambda1),
    cv_n_lambda2       = as.integer(cv_n_lambda2),
    cv_dfmax_ratio     = as.numeric(cv_dfmax_ratio),
    cv_seed            = as.integer(cv_seed)
  )
}


#' @name trex_screen_control
#'
#' @title T-Rex+Screening Control Parameters
#'
#' @description Build a control list for the screening step in TRexScreeningSelector and
#'   TRexBiobankScreeningSelector.
#'
#' @param use_bootstrap_CI Whether the confidence-based screening (bootstrap) makes the
#'   selection (default: FALSE). The FDR estimate stays one over the number of selected
#'   variables. With a dependency-aware variant it mostly selects nothing: the filter lowers
#'   the ordinary count that the confidence level has to reach, and in simulations no level
#'   reached it in 90 % to 100 % of the runs.
#' @param R_boot Number of bootstrap resamples, at least 2 (default: 1000).
#' @param ci_grid_step Step of the grid over the confidence level, in \code{(0, 1]}
#'   (default: 0.001).
#' @param trex_method Variant of the screening (default: "TREX"). "TREX" screens without a
#'   dependency-aware filter. The other variants apply a dependency-aware filter to the
#'   relative occurrences. "TREX_DA_AR1", for a first-order autoregressive dependency,
#'   compares a variable with the neighbors inside the AR(1) window. "TREX_DA_EQUI", for
#'   equi-correlated variables, compares a variable with all other variables.
#'   "TREX_DA_BLOCK_EQUI", for block equi-correlated variables, makes the same comparison
#'   inside contiguous blocks. "TREX_DA_NN" compares a variable with the neighbors inside the
#'   AR(1) window whose sample correlation reaches \code{rho_thr_DA}, and a variable without
#'   such a neighbor keeps its relative occurrence. With a threshold at or above the
#'   correlation of the data no neighbor is left, and the variant selects as "TREX".
#' @param cor_coef Correlation coefficient of the dependency-aware variants. -2.0 triggers
#'   auto-estimation (default: -2.0). The variants use the magnitude of a supplied coefficient.
#'   Any other value outside \code{[-1, 1]} gives a warning and is replaced by the estimate.
#' @param rho_thr_DA Correlation threshold of the dependency-aware variants (default: 0.02).
#'   "TREX_DA_AR1": the window around a variable reaches
#'   \code{ceiling(log(rho_thr_DA) / log(abs(cor_coef)))} columns to each side, up to the
#'   first lag whose correlation \code{abs(cor_coef)^lag} has fallen to the threshold, range
#'   \code{[0, 1)}. "TREX_DA_NN": the same window, of which the variables stay whose sample
#'   correlation with the variable reaches the threshold, range \code{[0, 1)}. A threshold at
#'   or above the correlation of the data leaves no neighbor, the variant then selects as
#'   "TREX" and the filter protects no longer, so the threshold stays below the correlation
#'   that the filter is meant to guard against. At the default the variant selected as
#'   "TREX_DA_AR1" in simulations.
#'   "TREX_DA_EQUI" and "TREX_DA_BLOCK_EQUI": the filter is skipped when
#'   \code{abs(cor_coef)} does not exceed the threshold, range \code{[0, 1]}.
#' @param n_blocks Number of blocks of "TREX_DA_BLOCK_EQUI", between 1 and the number of
#'   variables (default: 5).
#'
#' @return A named list for use in TRexScreeningSelector or TRexBiobankScreeningSelector.
#'
#' @examples
#' trex_screen_control()
#' trex_screen_control(use_bootstrap_CI = TRUE, R_boot = 500)
#'
#' @family T-Rex selectors and controls
#' @export
trex_screen_control <- function(use_bootstrap_CI = FALSE,
                                R_boot = 1000,
                                ci_grid_step = 0.001,
                                trex_method = "TREX",
                                cor_coef = -2.0,
                                rho_thr_DA = 0.02,
                                n_blocks = 5) {
  list(
    use_bootstrap_CI = use_bootstrap_CI,
    R_boot           = R_boot,
    ci_grid_step     = ci_grid_step,
    trex_method      = trex_method,
    cor_coef         = cor_coef,
    rho_thr_DA       = rho_thr_DA,
    n_blocks         = n_blocks
  )
}


#' @name trex_biobank_control
#'
#' @title T-Rex Biobank Screening Control Parameters
#'
#' @description Build a control list for TRexBiobankScreeningSelector: the accepted range of
#'   the FDR estimate of the screening and the target FDR level of the fallback T-Rex
#'   selector.
#'
#' @param lower_bound_FDR Lower bound of the accepted range of the FDR estimate of the
#'   screening (default: 0.05). An estimate below it suggests too little power.
#' @param upper_bound_FDR Upper bound of the accepted range of the FDR estimate of the
#'   screening (default: 0.15). An estimate above it suggests too many false discoveries.
#' @param target_FDR_trex Target FDR level of the fallback T-Rex selector (default: 0.1).
#'
#' @return A named list for use in TRexBiobankScreeningSelector.
#'
#' @examples
#' trex_biobank_control()
#' trex_biobank_control(lower_bound_FDR = 0.02, upper_bound_FDR = 0.10)
#' trex_biobank_control(target_FDR_trex = 0.2)
#'
#' @family T-Rex selectors and controls
#' @export
trex_biobank_control <- function(lower_bound_FDR = 0.05,
                                 upper_bound_FDR = 0.15,
                                 target_FDR_trex = 0.1) {
  list(
    lower_bound_FDR = lower_bound_FDR,
    upper_bound_FDR = upper_bound_FDR,
    target_FDR_trex = target_FDR_trex
  )
}


#' @name trex_dummy_distribution
#'
#' @title T-Rex Dummy Variable Distribution
#'
#' @description Build a distribution specification for the dummy variables
#'   injected by the T-Rex Selector. Pass the result to the
#'   \code{dummy_distribution} argument of \code{\link{trex_control}}.
#'
#' @param type Character string naming the distribution.  One of:
#'   \code{"Normal"}, \code{"Uniform"}, \code{"Rademacher"},
#'   \code{"StudentT"}, \code{"Laplace"}, \code{"Gumbel"},
#'   \code{"Triangle"}, \code{"UniformSphere"},
#'   \code{"Mammen"}, \code{"ConstrainedSparseRademacher"}, \code{"Logistic"}.
#'   Defaults to \code{"Normal"}.
#' @param a  Half-range of \code{"Uniform"}, which draws from U(-a, a) (default:
#'   sqrt(3), unit variance), or lower bound of \code{"Triangle"} (default:
#'   -sqrt(6)).
#' @param df  Degrees of freedom of \code{"StudentT"} (default: 5).
#' @param location  Location parameter of \code{"Laplace"}, \code{"Gumbel"}
#'   and \code{"Logistic"} (default: 0).
#' @param scale  Scale parameter of \code{"Laplace"} (default: 1/sqrt(2)),
#'   \code{"Gumbel"} (default: 1) and \code{"Logistic"} (default: sqrt(3)/pi).
#' @param b  Mode of \code{"Triangle"} (default: 0).
#' @param c  Upper bound of \code{"Triangle"} (default: sqrt(6)).
#' @param dim  Dimension of the sphere of \code{"UniformSphere"} (default: 3).
#' @param s  Sparsity parameter of \code{"ConstrainedSparseRademacher"} in
#'   (0, 1] (default: 0.1). An entry is +1 or -1 with probability s/2 each and
#'   0 otherwise, and s = 1 gives the Rademacher distribution.
#' @param p1,p2  Probabilities of the two points of \code{"Mammen"},
#'   -(sqrt(5) - 1)/2 and (sqrt(5) + 1)/2 (defaults: (sqrt(5) + 1)/(2 sqrt(5))
#'   and (sqrt(5) - 1)/(2 sqrt(5))).
#'
#' @return A named list describing the dummy distribution, for use in
#'   \code{\link{trex_control}}.
#'
#' @references
#' J. Machkour, M. Muma, and D. P. Palomar, "The Terminating-Random Experiments Selector: Fast
#'   High-Dimensional Variable Selection with False Discovery Rate Control," Signal Process., vol. 231,
#'   Art. no. 109894, 2025, doi: 10.1016/j.sigpro.2025.109894.
#'
#' E. Mammen, "Bootstrap and Wild Bootstrap for High Dimensional Linear Models," Ann. Statist., vol. 21,
#'   no. 1, pp. 255-285, 1993, doi: 10.1214/aos/1176349025.
#'
#' @examples
#' # Standard Normal (default)
#' trex_dummy_distribution()
#'
#' # Student-t with 3 degrees of freedom
#' trex_dummy_distribution("StudentT", df = 3)
#'
#' @family T-Rex selectors and controls
#' @export
trex_dummy_distribution <- function(type     = "Normal",
                                    a        = NULL,
                                    df       = NULL,
                                    location = NULL,
                                    scale    = NULL,
                                    b        = NULL,
                                    c        = NULL,
                                    dim      = NULL,
                                    s        = NULL,
                                    p1       = NULL,
                                    p2       = NULL) {
  valid_types <- c("Normal", "Uniform", "Rademacher", "StudentT",
                   "Laplace", "Gumbel", "Triangle",
                   "UniformSphere", "Mammen", "ConstrainedSparseRademacher",
                   "Logistic")
  if (!type %in% valid_types) {
    stop("Unknown distribution type: '", type, "'. ",
         "Must be one of: ", paste(valid_types, collapse = ", "), ".")
  }
  dist <- list(type = type)
  if (!is.null(a))        dist$a        <- a
  if (!is.null(df))       dist$df       <- df
  if (!is.null(location)) dist$location <- location
  if (!is.null(scale))    dist$scale    <- scale
  if (!is.null(b))        dist$b        <- b
  if (!is.null(c))        dist$c        <- c
  if (!is.null(dim))      dist$dim      <- dim
  if (!is.null(s))        dist$s        <- s
  if (!is.null(p1))       dist$p1       <- p1
  if (!is.null(p2))       dist$p2       <- p2
  dist
}


#' @name trex_tikhonov_control
#'
#' @title T-Rex+Tikhonov Control Parameters
#'
#' @description Build the control list of \code{\link{TRexTikhonovSelector}}, the
#'   T-Rex selector with a general Tikhonov penalty (T-Rex+Tikhonov). The list
#'   carries the penalty, the rule that chooses its weight \code{lambda_2}, and
#'   how the dummies are drawn. The help of the class describes the method.
#'
#' @param tikhonov_K Penalty matrix K (p x p), symmetric and positive
#'   semi-definite: a base \code{matrix} or a sparse \code{Matrix::dgCMatrix}.
#'   \code{\link{trex_gamma_to_k}} builds it from a regularization operator
#'   Gamma. Required for \code{penalty_structure = "SPARSE_GENERAL"}, where the
#'   selector checks its content once at construction (finite entries,
#'   symmetry, positive semi-definiteness). Optional under
#'   \code{"GROUP_CENTERING"}: left out, the selector builds the centering
#'   matrix from \code{prior_groups}. A supplied matrix is compared with that
#'   centering matrix, and another matrix is an error.
#' @param penalty_structure Structural form of the penalty.
#'   \code{"SPARSE_GENERAL"} (default): the supplied \code{tikhonov_K} is the
#'   penalty. \code{"GROUP_CENTERING"}: K is the block-diagonal centering
#'   matrix \code{I - J / p_m} over the groups of \code{prior_groups}, which
#'   this structure requires, so the members of a group share a coefficient
#'   (\code{\link{trex_build_group_centering_k}} returns the matrix). A
#'   partition into single variables is allowed: K is then zero and the path
#'   is the lasso path.
#' @param lambda_2 Weight of the penalty. A negative value (default: -1) lets
#'   \code{lambda2_method} choose it, \code{0} is no penalty (the lasso path of
#'   the solver), and a positive value is used as it is. The value must be
#'   finite. A supplied value refers to the scale of the standardized columns.
#'   Under \code{scaling_mode = "ZSCORE"} the columns have the squared norm
#'   \code{n - 1}, so the same shrinkage needs the value times \code{n - 1}.
#'   The rules report their pick on this scale.
#' @param lambda2_method Rule that chooses \code{lambda_2} when
#'   \code{lambda_2 < 0}. \code{"PILOT_KNEE"} (default), the pilot rule, reads
#'   it off a few random experiments per value of \code{pilot_grid}: the
#'   smallest lambda_2 whose pilot selection count is within
#'   \code{pilot_knee_tolerance} of the largest, the knee of the profile. The
#'   field \code{lambda2_pilot} of the selector holds its record. The
#'   cross-validation rules tune on the normalized data before the random
#'   experiments. \code{"CV_1SE_IEN_CCD"} and \code{"CV_MIN_IEN_CCD"} profile
#'   the lambda_1 path out per lambda_2 candidate and are well-posed for every
#'   p and n. \code{"CV_1SE_TIK_SVD"} and \code{"CV_MIN_TIK_SVD"} are an
#'   analytic ridge cross-validation (lambda_1 = 0), exact for n > p and
#'   refused when the unpenalized null space interpolates the training folds.
#'   The knee of the full selection profile, one selection per grid value, is
#'   \code{\link{trex_tikhonov_lambda2_power_rule}}.
#' @param cv_n_folds Folds of the cross-validation rules, 2 to n (default: 10).
#' @param cv_n_lambda \code{"CV_1SE_TIK_SVD"} and \code{"CV_MIN_TIK_SVD"}:
#'   points on the lambda_2 grid (default: 100).
#' @param cv_n_lambda1 \code{"CV_1SE_IEN_CCD"} and \code{"CV_MIN_IEN_CCD"}:
#'   points on the profiled lambda_1 path per lambda_2 value (default: 40).
#' @param cv_n_lambda2 \code{"CV_1SE_IEN_CCD"} and \code{"CV_MIN_IEN_CCD"}:
#'   points on the lambda_2 grid (default: 100).
#' @param cv_dfmax_ratio \code{"CV_1SE_IEN_CCD"} and \code{"CV_MIN_IEN_CCD"}:
#'   support cap as a fraction of the smallest fold's training size. Each
#'   lambda_1 path stops once more than
#'   \code{floor(cv_dfmax_ratio * n_train)} coefficients are nonzero (default:
#'   0.8). A value \code{<= 0} disables the cap. Larger values allow larger
#'   supports at a higher cost. Must be finite.
#' @param cv_seed Seed of the fold permutation of the cross-validation rules.
#'   \code{-1} (default) derives it from the seed of the selector, a value
#'   \code{>= 0} replaces it for the folds only.
#' @param pilot_grid Pilot rule: lambda_2 candidates, stated for columns of
#'   unit norm, sorted and de-duplicated internally. The default is the grid
#'   of the C++ core, \code{\link{trex_default_lambda2_grid}()}: 0, 1, 3, 10,
#'   30, 100, 300, 1000, 3000. Under \code{scaling_mode = "ZSCORE"} the pilot
#'   runs at these values times \code{n - 1}, as the cross-validation rules
#'   return their pick, so one grid means the same shrinkage under every
#'   scaling mode. The pick is reported on the working scale and can be
#'   supplied as \code{lambda_2}. Keep 0 on the grid so that "no penalty" is
#'   an admissible answer: a penalty that misfits the truth loses power as
#'   lambda_2 grows, and the rule then switches it off.
#' @param pilot_K Pilot rule: pilot experiments per grid value (default: 10;
#'   at least 2, capped at \code{K} of \code{\link{trex_control}}). The
#'   majority count has the resolution \code{1 / pilot_K}.
#' @param pilot_T Pilot rule: stopping time of the pilot paths (default: 5;
#'   at least 1, capped at \code{min(L_0, ceiling(n / 2))}, as the T-loop caps
#'   its stopping time). The pick reads the count at this stopping time.
#' @param pilot_L_multiplier Pilot rule: pilot dummies
#'   \code{L_0 = pilot_L_multiplier * p} (default: 1; at most
#'   \code{max_dummy_multiplier} of \code{\link{trex_control}}).
#' @param pilot_knee_tolerance Pilot rule: selections below the largest
#'   pilot count that still count as "on the plateau" (default: 1). \code{0}
#'   reads the largest count, ties toward the smallest lambda_2.
#' @param pilot_statistic Pilot rule: the count the pick is read off, per grid
#'   value. \code{"MAJORITY"} (default) is the number of variables ahead of
#'   the last pilot dummy (the \code{pilot_T}-th) in more than half of the
#'   pilot experiments, the count of the T-Rex selector at the voting level
#'   1/2. It is zero under the global null. \code{"CALIBRATED"} is the T-Rex
#'   selection rule applied to the pilot data, the largest selection whose
#'   estimated FDP stays within the target. It is coarser at a small
#'   \code{pilot_K}. \code{"GROUP_MAJORITY"} is the majority count restricted
#'   to the groups of \code{prior_groups} in which at least
#'   \code{pilot_group_fraction} of the members are ahead. A group that enters
#'   as a whole counts with its members, a group that enters as a minority
#'   counts nothing. It needs \code{prior_groups}. The record
#'   \code{lambda2_pilot} holds all three counts.
#' @param pilot_group_fraction \code{"GROUP_MAJORITY"}: the share of a
#'   group's members that must be ahead for the group to count, in (0, 1]
#'   (default: 0.5).
#' @param pilot_shared_dummies Logical (default \code{FALSE}): the pilot
#'   draws its dummies from a seed stream of its own, so the dummies of the
#'   main run do not depend on the pick, and the main run equals a run at the
#'   picked lambda_2 with the same seed. \code{TRUE}: the pilot uses the first
#'   dummy block of the main strategy (not with the PERMUTATION strategies).
#' @param fold_dummy_coupling Logical (default \code{TRUE}): in the penalty
#'   every dummy takes the place of the variable it was drawn for (folded
#'   coupling), so dummies and null variables stay exchangeable for every K.
#'   \code{FALSE}, a ridge block of the dummies decoupled from K, is an
#'   error: it existed with the solver \code{"TCDTIKNET"} only, which the
#'   selector no longer accepts. Deprecated: the argument will be removed
#'   with the coordinate-descent family in TRexSelector 2.1.0.
#' @param cluster_dummies Logical (default \code{TRUE}): draw the dummies per
#'   cluster of correlated variables, as in \code{\link{TRexGVSSelector}}.
#'   \code{FALSE} gives i.i.d. dummies, for validation runs only: with an
#'   informed K they deform the exchangeability of dummies and null variables
#'   that the FDR calibration relies on.
#' @param prior_groups Groups of the variables: an integer vector with the
#'   group of each variable, numbered 1 to M without gaps (length p). They
#'   define the clusters of the dummies (with \code{cluster_dummies}), the
#'   penalty under \code{"GROUP_CENTERING"} and the count
#'   \code{"GROUP_MAJORITY"} of the pilot rule. \code{NULL} (default): the
#'   clusters of the dummies are found by clustering the correlations with
#'   \code{corr_max} and \code{hc_linkage}.
#' @param corr_max Correlation threshold of the automatic clustering, between
#'   0 and 1 (default: 0.5). The dendrogram is cut at the height
#'   \code{1 - corr_max}. With "single" linkage (default) no two variables of
#'   different clusters correlate above \code{corr_max}. With "complete"
#'   linkage every two variables of one cluster correlate at least at
#'   \code{corr_max}, and variables of different clusters can exceed it.
#'   Ignored when \code{prior_groups} is set or \code{cluster_dummies = FALSE}.
#' @param hc_linkage Hierarchical clustering linkage: "single", "complete",
#'   "average", "wpgma" (default: "single"). "ward" is rejected, because its
#'   update is valid for squared Euclidean distances only and the correlation
#'   distance \code{1 - abs(cor)} is not Euclidean. Ignored when
#'   \code{prior_groups} is set or \code{cluster_dummies = FALSE}. The
#'   capitalized names of TRexSelector 2.0.1 ("Single") are accepted as well.
#'
#' @return A named list for use in \code{\link{TRexTikhonovSelector}}.
#'
#' @examples
#' trex_tikhonov_control(tikhonov_K = diag(10))
#' trex_tikhonov_control(penalty_structure = "GROUP_CENTERING",
#'                       prior_groups = rep(1:2, each = 5),
#'                       pilot_grid = c(0, 1, 10, 100))
#' trex_tikhonov_control(tikhonov_K = diag(10),
#'                       lambda2_method = "CV_1SE_IEN_CCD")
#'
#' @family T-Rex selectors and controls
#' @export
trex_tikhonov_control <- function(tikhonov_K = NULL,
                                  penalty_structure = "SPARSE_GENERAL",
                                  lambda_2 = -1.0,
                                  lambda2_method = "PILOT_KNEE",
                                  cv_n_folds = 10,
                                  cv_n_lambda = 100,
                                  cv_n_lambda1 = 40,
                                  cv_n_lambda2 = 100,
                                  cv_dfmax_ratio = 0.8,
                                  cv_seed = -1,
                                  pilot_grid = trex_default_lambda2_grid(),
                                  pilot_K = 10,
                                  pilot_T = 5,
                                  pilot_L_multiplier = 1,
                                  pilot_knee_tolerance = 1,
                                  pilot_statistic = "MAJORITY",
                                  pilot_group_fraction = 0.5,
                                  pilot_shared_dummies = FALSE,
                                  fold_dummy_coupling = TRUE,
                                  cluster_dummies = TRUE,
                                  prior_groups = NULL,
                                  corr_max = 0.5,
                                  hc_linkage = "single") {
  penalty_structure <- match.arg(penalty_structure,
                                 c("SPARSE_GENERAL", "GROUP_CENTERING"))
  lambda2_method <- match.arg(lambda2_method,
                              c("PILOT_KNEE",
                                "CV_1SE_IEN_CCD", "CV_MIN_IEN_CCD",
                                "CV_1SE_TIK_SVD", "CV_MIN_TIK_SVD"))
  pilot_statistic <- match.arg(pilot_statistic,
                               c("MAJORITY", "CALIBRATED", "GROUP_MAJORITY"))
  hc_linkage <- match.arg(tolower(hc_linkage),
                          c("single", "complete", "average", "wpgma"))
  if (!is.null(prior_groups)) {
    .check_group_numbers(prior_groups, "prior_groups")
  }
  if (penalty_structure == "SPARSE_GENERAL" && is.null(tikhonov_K)) {
    stop("tikhonov_K is required (p x p penalty matrix; use trex_gamma_to_k() ",
         "to build K from a regularization operator Gamma) unless ",
         "penalty_structure = \"GROUP_CENTERING\".")
  }
  dfmax_ok <- is.numeric(cv_dfmax_ratio) && length(cv_dfmax_ratio) == 1 &&
    is.finite(cv_dfmax_ratio)
  if (!dfmax_ok) {
    stop("cv_dfmax_ratio must be a single finite number (<= 0 disables the ",
         "support cap). Got: ", format(cv_dfmax_ratio))
  }
  if (!is.numeric(pilot_grid) || length(pilot_grid) == 0 ||
      any(!is.finite(pilot_grid)) || any(pilot_grid < 0)) {
    stop("pilot_grid must be a non-empty vector of finite values >= 0.")
  }
  if (pilot_K < 2) {
    stop("pilot_K must be >= 2. Got: ", pilot_K)
  }
  if (pilot_T < 1) {
    stop("pilot_T must be >= 1. Got: ", pilot_T)
  }
  if (pilot_L_multiplier < 1) {
    stop("pilot_L_multiplier must be >= 1. Got: ", pilot_L_multiplier)
  }
  if (pilot_knee_tolerance < 0) {
    stop("pilot_knee_tolerance must be >= 0. Got: ", pilot_knee_tolerance)
  }
  if (!(pilot_group_fraction > 0 && pilot_group_fraction <= 1)) {
    stop("pilot_group_fraction must be in (0, 1]. Got: ", pilot_group_fraction)
  }
  list(
    tikhonov_K           = tikhonov_K,
    penalty_structure    = penalty_structure,
    lambda_2             = lambda_2,
    lambda2_method       = lambda2_method,
    cv_n_folds           = as.integer(cv_n_folds),
    cv_n_lambda          = as.integer(cv_n_lambda),
    cv_n_lambda1         = as.integer(cv_n_lambda1),
    cv_n_lambda2         = as.integer(cv_n_lambda2),
    cv_dfmax_ratio       = as.numeric(cv_dfmax_ratio),
    cv_seed              = as.integer(cv_seed),
    pilot_grid           = as.numeric(pilot_grid),
    pilot_K              = as.integer(pilot_K),
    pilot_T              = as.integer(pilot_T),
    pilot_L_multiplier   = as.integer(pilot_L_multiplier),
    pilot_knee_tolerance = as.numeric(pilot_knee_tolerance),
    pilot_statistic      = pilot_statistic,
    pilot_group_fraction = as.numeric(pilot_group_fraction),
    pilot_shared_dummies = as.logical(pilot_shared_dummies),
    fold_dummy_coupling  = fold_dummy_coupling,
    cluster_dummies      = cluster_dummies,
    prior_groups         = prior_groups,
    corr_max             = corr_max,
    hc_linkage           = hc_linkage
  )
}

Try the TRexSelector package in your browser

Any scripts or data that you put into this service are public.

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