What the package does

The Terminating-Random Experiments (T-Rex) selector selects variables 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 applies to low- and high-dimensional designs and is tailored to the high-dimensional problem. It takes a design matrix \(\boldsymbol{X}\) with \(n\) observations of \(p\) variables, a response vector \(\boldsymbol{y}\) and the target FDR, and runs \(K\) random experiments in which the real variables compete with computer-generated dummy variables, random columns with finite mean and variance that act as flagged null variables. In every experiment the dummies are appended to the design, a forward selection solver walks its path and stops as soon as \(T\) dummies have entered, and the share of experiments in which a variable was selected is its vote. Because a dummy enters as easily as a null variable, the included dummies give an estimate of the false discoveries, and a calibration over the number of dummies, the stopping time and the voting level selects as many variables as the FDR target allows, with a finite-sample guarantee that holds for a broad class of forward selection solvers. The scheme is not tied to the linear model and scales to millions of variables. The library currently covers the supervised linear model with a response vector and a design matrix.

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. Since version 2.0.0 it replaces the pure-R implementation of the 1.x releases under the same package name [version 1.0.0].

The package currently has five groups of tools.

• T-Rex selectors. The core TRexSelector and its variants for dependent variables (TRexDASelector), grouped variables (TRexGVSSelector), fast screening (TRexScreeningSelector, TRexBiobankScreeningSelector), sparse principal component analysis (PCA) (TRexSPCASelector) and a general Tikhonov penalty (TRexTikhonovSelector).
• T-solvers. The twenty terminating forward selection solvers the selectors run inside their random experiments, available as classes of their own.
• Machine learning (ML) methods. Scalers, ridge and elastic-net regression with cross-validation, singular value decomposition (SVD), PCA and hierarchical clustering.
• Memory-mapped matrices. Disk-backed designs are accepted everywhere a matrix is accepted. The algorithms are agnostic to the data representation, so the library processes designs larger than the random-access memory (RAM) of the machine out of core.
• Utilities. The selection metrics (false discovery proportion, true positive proportion, precision and recall), the normalizers, the dummy distributions, and the threading functions.

Installation

The released package is on the Comprehensive R Archive Network (CRAN) [package page]. Install it from an R session.

install.packages("TRexSelector")

CRAN provides binaries for Windows and macOS. On Linux, and for every install from source, the package compiles its C++ backend, so a C++20 compiler is required (GCC 10, Clang 12, Apple Clang 14, Rtools on Windows, or newer) together with R (>= 4.3).

The main branch of the repository carries the released sources, the version that is on CRAN, in the R/TRexSelector/ subdirectory, and the development happens on the dev_beyond branch. Install the R-side prerequisites once, then the package from GitHub.

install.packages(c("Rcpp", "RcppEigen", "BH", "Rcereal", "R6", "remotes"))
remotes::install_github("trexselector/TRexSelector", subdir = "R/TRexSelector")

OpenMP is optional. The CRAN binary for Windows is built with it, and on Linux the package compiles with the OpenMP flags of R. CRAN’s R for macOS has none, so the macOS binary runs on one thread, while a build from source (install.packages("TRexSelector", type = "source")) 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.

The package builds on Rcpp [2] and RcppEigen [3] for the bindings, on the Boost headers of BH [4] for the memory mapping, on the cereal headers of Rcereal [5] for the serialization, and on R6 [6] for its classes.

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

T-Rex variants of the library

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

Citing the package

citation("TRexSelector")

The methods are published in [1] (T-Rex), [7] (T-Rex+DA), [8], [9] (T-Rex GVS), [10] (Screen-T-Rex), [11] (T-Rex SPCA), [12] (memory mapping) and [13] (the terminating greedy pursuits).