Getting started with TRexSelector

What the package does

The T-Rex selector (terminating-random experiments) selects variables in high-dimensional linear models while controlling the false discovery rate (FDR) at a target level chosen by the user, and it does so with a high true positive rate (TPR) [1]. It runs \(K\) random experiments. In each experiment the design matrix \(\boldsymbol{X}\) is enlarged by random dummy variables, a forward selection solver walks its path and stops as soon as \(T\) dummies have entered the model, and the active sets of the \(K\) experiments are fused by a vote. A calibration over the number of dummies and the stopping time guarantees the FDR level.

The R package is the R interface to the TRexSelector C++ library. The same library drives the Python package and the C++ software development kit, so the three surfaces select the same variables on the same data. Version 2.0.0 replaces the pure-R implementation of the 1.x releases under the same package name.

The package has four groups of tools.

Installation

The package compiles its C++ backend on installation, so a C++20 compiler is required (GCC 10, Clang 12, Apple Clang 14, Rtools on Windows, or newer) together with R 4.3 or newer. First install the R-side prerequisites once.

install.packages(c("Rcpp", "RcppEigen", "BH", "Rcereal", "R6"))

CRAN still carries the pure-R 1.x release, so until version 2.0.0 is accepted there, install it from GitHub. It lives in the R/TRexSelector/ subdirectory of the repository.

install.packages("remotes")
remotes::install_github("trexselector/TRexSelector", subdir = "R/TRexSelector")

OpenMP is optional. On Linux and Windows R supplies the OpenMP flags. CRAN’s R for macOS has none, so the configure script uses the omp.h header of Homebrew’s libomp (brew install libomp) together with the OpenMP runtime that R itself ships. Without a header the package compiles single-threaded and trex_get_max_threads() returns 1. The parallelism page explains what the threads are used for.

A first run

The package ships a small Gaussian data set with \(n = 50\) observations, \(p = 100\) variables and three active variables.

data(Gauss_data)
X <- Gauss_data$X
y <- Gauss_data$y
true_support <- which(Gauss_data$support)
true_support
#> [1] 1 2 3

The selectors are R6 classes. Construct one with $new(), run it with $select() and read the results from its fields. A fixed seed makes the dummy draws reproducible. The default seed = -1 draws them from the hardware entropy source, which is the right choice for Monte Carlo studies, see the T-Rex selector page.

sel <- TRexSelector$new(X, y, tFDR = 0.1, seed = 1234, verbose = FALSE)
sel$select()
sel$selected_indices
#> [1] 1 2 3

The two metrics of variable selection compare the selection with the true support. The false discovery proportion (FDP) is the share of false positives among the selected variables and the true positive proportion (TPP) is the share of the true support that was found. Their expectations are the FDR and the TPR.

trex_fdp(sel$selected_indices, true_support)
#> [1] 0
trex_tpp(sel$selected_indices, true_support)
#> [1] 1

The result fields

Every selector exposes the calibration it arrived at.

sel$num_selected   # number of selected variables
#> [1] 3
sel$T_stop         # stopping time: dummies included when the T-loop stopped
#> [1] 6
sel$L              # calibrated dummy multiplier, the selector used L * p dummies
#> [1] 4
sel$v_thresh       # voting level the selection was read at
#> [1] 1
sel$K              # random experiments
#> [1] 20

fdp_hat_mat holds the FDP estimate per stopping time (rows) and voting level (columns), phi_mat the relative occurrence of every variable over the \(K\) experiments after each stopping time, and voting_grid the voting levels. The T-Rex selector page walks through them.

dim(sel$fdp_hat_mat)
#> [1]  6 11
head(sel$voting_grid)
#> [1] 0.50 0.55 0.60 0.65 0.70 0.75
round(sel$fdp_hat_mat[sel$T_stop, ], 3)
#>  [1] 0.38 0.20 0.20 0.20 0.20 0.20 0.20 0.20 0.20 0.20 0.20

Choosing a selector and a solver

Situation Selector Page
Independent or weakly dependent variables TRexSelector T-Rex selector
Strongly dependent variables (autoregressive, equi-correlated, clustered) TRexDASelector T-Rex+DA
Groups of correlated variables that should enter together TRexGVSSelector T-Rex GVS
Very large \(p\), a fast first pass before the full selector TRexScreeningSelector Screening
Many phenotypes against one genotype matrix TRexBiobankScreeningSelector Screening
Sparse principal components TRexSPCASelector T-Rex SPCA
A structured penalty (smoothness, graph Laplacian, groups) TRexTikhonovSelector T-Rex Tikhonov

The solver inside the random experiments is set in trex_control(solver = ). T-LARS (terminating least angle regression) is the default and the solver of the T-Rex paper. T-LASSO adds the lasso modification, T-ENET the elastic net, the orthogonal matching pursuit (OMP) family and the adaptive forward stepwise family are greedy and faster per step, and the coordinate descent (CD) family computes exact penalized minimizers at every dummy crossing. The T-solvers page describes the families, and every solver can be run on its own.

ctrl <- trex_control(solver = "TLASSO", K = 10)
sel2 <- TRexSelector$new(X, y, tFDR = 0.1, seed = 1234, verbose = FALSE, control = ctrl)
sel2$select()
sel2$selected_indices
#> [1] 1 2 3

Map of the pages

  1. Getting started (this page).
  2. The T-Rex selector: the framework, the control parameters and the result fields.
  3. T-Rex+DA: dependency-aware dummies.
  4. T-Rex GVS: grouped variable selection with the elastic net and the informed elastic net.
  5. Screening: Screen-T-Rex and the biobank screening.
  6. T-Rex SPCA: sparse PCA under FDR control.
  7. T-Rex Tikhonov: a general penalty matrix.
  8. The T-solvers: the twenty solvers and their options.
  9. The ML methods: scalers, regressions, decompositions and clustering.
  10. Memory mapping: disk-backed designs.
  11. Working without data copies: the in-place contract.
  12. Parallelism: who owns the cores.

Citing the package

citation("TRexSelector")

The methods are published in [1] (T-Rex), [2] (T-Rex+DA), [3], [4] (T-Rex GVS), [5] (Screen-T-Rex), [6] (T-Rex SPCA), [7] (memory mapping) and [8] (the terminating greedy pursuits).

References

[1]
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, 2025, doi: 10.1016/j.sigpro.2025.109894.
[2]
J. Machkour, M. Muma, and D. P. Palomar, “High-dimensional false discovery rate control for dependent variables,” Signal Process., vol. 234, 2025, doi: 10.1016/j.sigpro.2025.109990.
[3]
J. Machkour, M. Muma, and D. P. Palomar, “False discovery rate control for grouped variable selection in high-dimensional linear models using the T-Knock filter,” in Proc. 30th eur. Signal process. Conf. (EUSIPCO), 2022, pp. 892–896.
[4]
J. Machkour, M. Muma, and D. P. Palomar, “The informed elastic net for fast grouped variable selection and FDR control in genomics research,” in Proc. IEEE 9th int. Workshop comput. Adv. Multi-sensor adapt. Process. (CAMSAP), 2023, pp. 466–470.
[5]
J. Machkour, M. Muma, and D. P. Palomar, “False discovery rate control for fast screening of large-scale genomics biobanks,” in Proc. 22nd IEEE statist. Signal process. Workshop (SSP), 2023, pp. 666–670.
[6]
J. Machkour, A. Breloy, M. Muma, D. P. Palomar, and F. Pascal, “Sparse PCA with false discovery rate controlled variable selection,” in Proc. IEEE 49th int. Conf. Acoust., speech, signal process. (ICASSP), 2024, pp. 9716–9720.
[7]
F. Scheidt, J. Machkour, and M. Muma, “Solving FDR-controlled sparse regression problems with five million variables on a laptop,” in Proc. IEEE 9th int. Workshop comput. Adv. Multi-sensor adapt. Process. (CAMSAP), 2023, pp. 116–120.
[8]
F. Scheidt and M. Muma, “Terminating greedy pursuits for high-dimensional false discovery rate control,” in Proc. Eur. Signal process. Conf. (EUSIPCO), 2026, pp. 2511–2515.