---
title: "Getting started with TRexSelector"
output:
  rmarkdown::html_vignette:
    toc: true
    css: vignette_styles.css
    includes:
      before_body: vignette_nav.html
bibliography: references.bib
csl: ieee.csl
link-citations: true
vignette: >
  %\VignetteIndexEntry{Getting started with TRexSelector}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.align = "center",
                      fig.width = 6, fig.height = 4, fig.retina = 2)
options(width = 80)
library(TRexSelector)
# Vignettes build on at most two threads (the CRAN rule)
old_threads <- trex_set_num_threads(min(2L, trex_get_max_threads()))
```

# 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) [@machkour2025trex]. 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](https://CRAN.R-project.org/src/contrib/Archive/TRexSelector/TRexSelector_1.0.0.tar.gz)].

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](https://CRAN.R-project.org/package=TRexSelector)]. Install it from an R session.

```{r, eval = FALSE}
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.

```{r, eval = FALSE}
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 [@eddelbuettel2011rcpp] and RcppEigen [@bates2013rcppeigen] for the bindings,
on the Boost headers of BH [@eddelbuettel2025bh] for the memory mapping, on the cereal headers of Rcereal
[@wu2024rcereal] for the serialization, and on R6 [@chang2025r6] 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.

```{r first-run}
data(Gauss_data)
X <- Gauss_data$X
y <- Gauss_data$y
true_support <- which(Gauss_data$support)
true_support
```

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.

```{r first-select}
sel <- TRexSelector$new(X, y, tFDR = 0.1, seed = 1234, verbose = FALSE)
sel$select()
sel$selected_indices
```

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.

```{r metrics}
trex_fdp(sel$selected_indices, true_support)
trex_tpp(sel$selected_indices, true_support)
```

# The result fields

Every selector exposes the calibration it arrived at.

```{r fields}
sel$num_selected   # number of selected variables
sel$T_stop         # stopping time: dummies included when the T-loop stopped
sel$L              # calibrated dummy multiplier, the selector used L * p dummies
sel$v_thresh       # voting level the selection was read at
sel$K              # random experiments
```

`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.

```{r matrices}
dim(sel$fdp_hat_mat)
head(sel$voting_grid)
round(sel$fdp_hat_mat[sel$T_stop, ], 3)
```

# T-Rex variants of the library

| Situation | Selector | Page |
| --- | --- | --- |
| Independent or modestly 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` | Screen-T-Rex |
| Many phenotypes against one genotype matrix | `TRexBiobankScreeningSelector` | Screen-T-Rex |
| 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.

```{r solver-choice}
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
```

# Citing the package

```{r, eval = FALSE}
citation("TRexSelector")
```

The methods are published in [@machkour2025trex] (T-Rex), [@machkour2025datrex] (T-Rex+DA),
[@machkour2022gvs; @machkour2023ien] (T-Rex GVS), [@machkour2023screen] (Screen-T-Rex),
[@machkour2024spca] (T-Rex SPCA), [@scheidt2023bigtrex] (memory mapping) and [@scheidt2026greedy]
(the terminating greedy pursuits).

```{r teardown, include = FALSE}
trex_set_num_threads(old_threads)
```

# Bibliography