Help for package TRexSelector

Type:

Package

Title:

T-Rex Selector: High-Dimensional Variable Selection & FDR Control

Version:

2.0.0

Description:

Variable selection for regression and classification in high-dimensional settings with control of the false discovery rate (FDR) at a user-specified target level. The implementations are primarily based on the T-Rex selector of Machkour, Muma and Palomar (2025) <doi:10.1016/j.sigpro.2025.109894> and its dependency-aware extension for correlated variables by Machkour, Muma and Palomar (2025) <doi:10.1016/j.sigpro.2025.109990>. Since version 2.0.0 the package comes as R bindings to the 'TRexSelector' C++ library, which replaces the pure-R implementation of the 1.x releases.

URL:

https://github.com/trexselector/TRexSelector

BugReports:

https://github.com/trexselector/TRexSelector/issues

License:

GPL (≥ 3)

Encoding:

UTF-8

LazyData:

true

LinkingTo:

Rcpp, RcppEigen, BH, Rcereal

Depends:

R (≥ 4.3)

Imports:

Rcpp, R6, methods

Suggests:

Matrix, testthat (≥ 3.0.0), knitr, rmarkdown

VignetteBuilder:

knitr

SystemRequirements:

C++20

Config/roxygen2/version:

8.1.0

NeedsCompilation:

yes

Packaged:

2026-11-06 17:11:25 UTC; fabianscheidt

Author:

Jasin Machkour [aut, cre], Fabian Scheidt [aut], Simon Tien [ctb], Daniel P. Palomar [aut], Michael Muma [aut]

Maintainer:

Jasin Machkour <jasin.machkour@tu-darmstadt.de>

Repository:

CRAN

Date/Publication:

2026-11-06 18:10:02 UTC

TRexSelector: the T-Rex selector, its T-solvers and ML utilities

Description

FDR-controlled variable selection with the Terminating-Random Experiments (T-Rex) selector, the terminating solvers it runs on, and the machine learning utilities around them. The exported symbols form four groups, recognizable by their prefix (functions and constant lists) or their leading group word (R6 classes):

T-Rex selectors and controls (`TRexSelector`, `⁠trex_⁠`)

The R6 selectors TRexSelector, TRexDASelector, TRexGVSSelector, TRexScreeningSelector, TRexBiobankScreeningSelector, TRexSPCASelector and TRexTikhonovSelector; their control lists trex_control, trex_da_control, trex_gvs_control, trex_screen_control, trex_biobank_control, trex_spca_control, trex_tikhonov_control and trex_dummy_distribution; the helpers trex_normalize_design and trex_gamma_to_k; the evaluation metrics trex_fdp, trex_tpp, trex_precision, trex_recall, trex_fdp_dense and trex_tpp_dense.

T-solvers (`⁠T_Solver⁠`, `⁠tsolver_⁠`)

The terminating solvers as R6 classes, constructed as ⁠$new(X, D, y, [groups | tikhonov_K,] options)⁠ with tsolver_options: the LARS family (TLARS_Solver, TLASSO_Solver, TSTEPWISE_Solver, TSTAGEWISE_Solver, TENET_Solver, TENETAug_Solver, TIENET_Solver, TIENETAug_Solver, TIKNET_Solver), the OMP family (TOMP_Solver, TGP_Solver, TACGP_Solver, TMP_Solver, TOOLS_Solver, TNCGMP_Solver), the AFS solver TAFS_Solver, and the coordinate-descent family (TCDLASSO_Solver, TCDENET_Solver, TCDIENET_Solver, TCDTIKNET_Solver). The solvers work on the caller's matrices without copying and may preprocess them in place; the writer/reader contract and ⁠$restore()⁠ are described in tsolver_options and TSolver_Base.

ML methods (`⁠ML⁠`, `⁠ml_⁠`)

Scalers MLZScoreScaler and MLLpNormScaler; regressions MLRidge, MLRidgeCV, MLElasticNet and MLElasticNetCV; decompositions MLSVD and MLPCA; hierarchical clustering ml_agglomerative_cluster and ml_cut_tree with the constants ml_linkage_method and ml_distance_metric.

Memory-mapped matrices (`⁠mem_*⁠`)

mem_matrix opens or creates a disk-backed matrix and mem_matrix_from writes an in-memory matrix to one; every selector, solver and ML method accepts the result in place of a matrix.

Author(s)

Maintainer: Jasin Machkour jasin.machkour@tu-darmstadt.de

Authors:

Jasin Machkour jasin.machkour@tu-darmstadt.de
Fabian Scheidt fabian.scheidt@tu-darmstadt.de
Daniel P. Palomar daniel.p.palomar@gmail.com
Michael Muma michael.muma@tu-darmstadt.de

Other contributors:

Simon Tien simon.tien@stud.tu-darmstadt.de [contributor]

Toy data generated from a Gaussian linear model

Description

A data set containing a predictor matrix X with n = 50 observations and p = 100 variables (predictors), and a sparse parameter vector beta with associated support vector.

Usage

Gauss_data

Format

A list containing a matrix X and vectors y, beta, and support:

X: Predictor matrix, n = 50, p = 100.
y: Response vector.
beta: Parameter vector.
support: Support vector.

Examples

# Generated as follows:
set.seed(789)
n <- 50
p <- 100
X <- matrix(stats::rnorm(n * p), nrow = n, ncol = p)
beta <- c(rep(5, times = 3), rep(0, times = 97))
support <- beta > 0
y <- X %*% beta + stats::rnorm(n)
Gauss_data <- list(
  X = X,
  y = y,
  beta = beta,
  support = support
)

Elastic Net (coordinate-descent path)

Description

Fits the elastic-net coefficient path via coordinate descent over a glmnet-style lambda grid (or an explicit grid). Reports coefficients in the original predictor scale, intercepts, the deviance-ratio path, and predictions for new data. The mixing parameter alpha interpolates between lasso (alpha = 1) and ridge (alpha = 0).

Methods

`MLElasticNet$new()`

Initialize the MLElasticNet object.

Usage

MLElasticNet$new(low_memory = FALSE, n_threads = NULL)

Arguments

low_memory: Logical (default FALSE). FALSE: the coordinate descent runs on a centered and standardized working copy of X (one n x p matrix while fitting). TRUE: it runs on X itself (an mmap_matrix is read in place, "readonly" suffices) with no allocation of the size of X; same estimator and grid, the two engines agree to rounding (about 1e-12 in the coefficients).
n_threads: Integer, the thread budget of the fit's matrix products (NULL, the default: the library's default budget, trex_get_num_threads(), initially 1).

`MLElasticNet$fit()`

Fit the EN path over an auto-generated glmnet-style grid.

Usage

MLElasticNet$fit(
  X,
  y,
  alpha = 1,
  n_lambda = 100,
  lambda_min_ratio = -1,
  standardize = TRUE,
  intercept = TRUE,
  use_strong_rule = FALSE,
  max_iter = 1e+05,
  tol = 1e-07
)

Arguments

X: Predictor matrix (n x p), or an mmap_matrix (bound zero-copy; "readonly" suffices, the fit does not modify X).
y: Response vector (n).
alpha: Mixing in [0, 1]: 1 = lasso, 0 = ridge (default 1).
n_lambda: Grid size (default 100).
lambda_min_ratio: Ratio lambda_min/lambda_max; negative (default) auto-selects glmnet's rule.
standardize: Standardize columns to unit SD (default TRUE).
intercept: Fit an unpenalized intercept (default TRUE).
use_strong_rule: Enable the sequential strong rule (default FALSE).
max_iter: Max CD sweeps per lambda (default 100000).
tol: Convergence tolerance (default 1e-7).

Returns

Invisibly returns self.

`MLElasticNet$fit_grid()`

Fit the EN path at an explicit lambda grid (sorted descending internally); use to evaluate at exactly glmnet's sequence.

Usage

MLElasticNet$fit_grid(
  X,
  y,
  lambda_grid,
  alpha = 1,
  standardize = TRUE,
  intercept = TRUE,
  use_strong_rule = FALSE,
  max_iter = 1e+05,
  tol = 1e-07
)

Arguments

X: Predictor matrix (n x p), or an mmap_matrix (zero-copy).
y: Response vector (n).
lambda_grid: Explicit lambda values (any order, > 0).
alpha: Mixing in [0, 1] (default 1).
standardize: Standardize columns to unit SD (default TRUE).
intercept: Fit an unpenalized intercept (default TRUE).
use_strong_rule: Enable the sequential strong rule (default FALSE).
max_iter: Max CD sweeps per lambda (default 100000).
tol: Convergence tolerance (default 1e-7).

Returns

Invisibly returns self.

`MLElasticNet$get_coef()`

Coefficient path in original predictor scale (p x n_lambda).

Usage

MLElasticNet$get_coef()

Returns

Numeric matrix.

`MLElasticNet$get_intercepts()`

Intercept per lambda (zero if intercept = FALSE).

Usage

MLElasticNet$get_intercepts()

Returns

Numeric vector.

`MLElasticNet$get_lambdas()`

Lambda grid actually used (descending).

Usage

MLElasticNet$get_lambdas()

Returns

Numeric vector.

`MLElasticNet$get_dev_ratio()`

Fraction of null deviance explained per lambda (glmnet %Dev).

Usage

MLElasticNet$get_dev_ratio()

Returns

Numeric vector.

`MLElasticNet$converged()`

Whether every lambda reached the convergence tolerance.

Usage

MLElasticNet$converged()

Returns

Logical scalar.

`MLElasticNet$n_nonconverged()`

Number of lambdas whose coordinate descent hit max_iter.

Usage

MLElasticNet$n_nonconverged()

Returns

Integer.

`MLElasticNet$predict()`

Predictions per lambda for new data.

Usage

MLElasticNet$predict(X_new)

Arguments

X_new: Predictor matrix with the same number of columns as the fit, or an mmap_matrix (zero-copy).

Returns

Numeric matrix (nrow(X_new) x n_lambda).

`MLElasticNet$clone()`

The objects of this class are cloneable with this method.

Usage

MLElasticNet$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

H. Zou and T. Hastie, "Regularization and Variable Selection via the Elastic Net," J. R. Stat. Soc. Ser. B Stat. Methodol., vol. 67, no. 2, pp. 301-320, 2005.

J. Friedman, T. Hastie, and R. Tibshirani, "Regularization Paths for Generalized Linear Models via Coordinate Descent," J. Stat. Softw., vol. 33, no. 1, pp. 1-22, 2010, doi: 10.18637/jss.v033.i01.

Examples

set.seed(1)
n <- 50; p <- 8
X <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + X[, 3] - X[, 5] + rnorm(n)
en <- MLElasticNet$new()
en$fit(X, y, alpha = 1.0)
dim(en$get_coef())        # p x n_lambda
en$predict(X[1:5, ])

Elastic Net with Cross-Validation

Description

Selects the elastic-net penalty by K-fold cross-validation over a shared glmnet-style lambda grid (coordinate descent per fold), returning lambda.min and lambda.1se. The mixing parameter alpha interpolates between lasso (alpha = 1) and ridge (alpha = 0).

Methods

Public methods

MLElasticNetCV$new()
MLElasticNetCV$fit()
MLElasticNetCV$cv_min()
MLElasticNetCV$cv_1se()
MLElasticNetCV$index_min()
MLElasticNetCV$index_1se()
MLElasticNetCV$get_lambdas()
MLElasticNetCV$get_cv_errors()
MLElasticNetCV$get_cv_std()
MLElasticNetCV$clone()

`MLElasticNetCV$new()`

Initialize the MLElasticNetCV object.

Usage

MLElasticNetCV$new(low_memory = FALSE, n_threads = NULL)

Arguments

low_memory: Logical (default FALSE); TRUE runs the full-data fit and every fold on X itself with a 0/1 training mask (no allocation of the size of X; an mmap_matrix is read in place). See MLElasticNet.
n_threads: Integer, the thread budget of the matrix products of the fit and its folds (NULL, the default: the library's default budget, trex_get_num_threads(), initially 1).

`MLElasticNetCV$fit()`

Fit K-fold CV over a glmnet-style grid.

Usage

MLElasticNetCV$fit(
  X,
  y,
  alpha = 0,
  n_folds = 10,
  n_lambda = 100,
  lambda_min_ratio = -1,
  seed = 0,
  standardize = TRUE,
  intercept = TRUE,
  max_iter = 1e+05,
  tol = 1e-07
)

Arguments

X: Predictor matrix (n x p), or an mmap_matrix (bound zero-copy; "readonly" suffices, the fit does not modify X).
y: Response vector (n).
alpha: Mixing in [0, 1]: 1 = lasso, 0 = ridge (default 0).
n_folds: Number of folds (default 10).
n_lambda: Grid size (default 100).
lambda_min_ratio: Ratio lambda_min/lambda_max; negative (default) auto-selects glmnet's rule.
seed: Fold-permutation RNG seed (default 0).
standardize: Standardize columns to unit SD (default TRUE).
intercept: Fit an unpenalized intercept (default TRUE).
max_iter: Max CD sweeps per lambda (default 100000).
tol: Convergence tolerance (default 1e-7).

Returns

Invisibly returns self.

`MLElasticNetCV$cv_min()`

Lambda that minimizes the mean CV error.

Usage

MLElasticNetCV$cv_min()

Returns

Scalar numeric.

`MLElasticNetCV$cv_1se()`

Largest lambda within one SE of the minimum (1SE rule).

Usage

MLElasticNetCV$cv_1se()

Returns

Scalar numeric.

`MLElasticNetCV$index_min()`

Index (1-based) of lambda.min.

Usage

MLElasticNetCV$index_min()

Returns

Integer.

`MLElasticNetCV$index_1se()`

Index (1-based) of lambda.1se.

Usage

MLElasticNetCV$index_1se()

Returns

Integer.

`MLElasticNetCV$get_lambdas()`

Lambda grid used (descending).

Usage

MLElasticNetCV$get_lambdas()

Returns

Numeric vector.

`MLElasticNetCV$get_cv_errors()`

Mean CV MSE per lambda.

Usage

MLElasticNetCV$get_cv_errors()

Returns

Numeric vector.

`MLElasticNetCV$get_cv_std()`

Standard error of the CV MSE per lambda.

Usage

MLElasticNetCV$get_cv_std()

Returns

Numeric vector.

`MLElasticNetCV$clone()`

The objects of this class are cloneable with this method.

Usage

MLElasticNetCV$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

H. Zou and T. Hastie, "Regularization and Variable Selection via the Elastic Net," J. R. Stat. Soc. Ser. B Stat. Methodol., vol. 67, no. 2, pp. 301-320, 2005.

J. Friedman, T. Hastie, and R. Tibshirani, "Regularization Paths for Generalized Linear Models via Coordinate Descent," J. Stat. Softw., vol. 33, no. 1, pp. 1-22, 2010, doi: 10.18637/jss.v033.i01.

R. Tibshirani, J. Bien, J. Friedman, T. Hastie, N. Simon, J. Taylor, and R. J. Tibshirani, "Strong Rules for Discarding Predictors in Lasso-Type Problems," J. R. Stat. Soc. Ser. B Stat. Methodol., vol. 74, no. 2, pp. 245-266, 2012, doi: 10.1111/j.1467-9868.2011.01004.x.

L. Breiman, J. H. Friedman, R. A. Olshen, and C. J. Stone, Classification and Regression Trees. Wadsworth, Belmont, CA, 1984.

Examples

set.seed(1)
n <- 60; p <- 10
X <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 - X[, 4] + rnorm(n)
cv <- MLElasticNetCV$new()
cv$fit(X, y, alpha = 0.5)
cv$cv_min()

Lp-Norm Scaler

Description

Scales input features to unit norm based on the chosen L1 or L2 formulation. The center/scale arguments follow R's scale(): the norm is computed around the applied center (around 0 when center = FALSE).

Details

The *_inplace methods mutate X directly (zero-copy) when it is a double-storage matrix; other inputs are coerced to a double matrix first, in which case the coerced copy is modified. The (modified) matrix is returned in both cases. X may also be an mmap_matrix created by mem_matrix / mem_matrix_from: the disk-backed buffer is then bound zero-copy through the same Eigen map interface and modified in place on disk. All scaler methods — including fit() — require the handle to be open in "readwrite" mode, because the scaler core binds a mutable map.

Methods

Public methods

MLLpNormScaler$new()
MLLpNormScaler$fit()
MLLpNormScaler$transform_inplace()
MLLpNormScaler$inverse_transform_inplace()
MLLpNormScaler$fit_transform_inplace()
MLLpNormScaler$is_fitted()
MLLpNormScaler$get_dropped_indices()
MLLpNormScaler$get_centers()
MLLpNormScaler$get_scales()
MLLpNormScaler$get_center()
MLLpNormScaler$get_scale()
MLLpNormScaler$get_norm_type()
MLLpNormScaler$save()
MLLpNormScaler$load()
MLLpNormScaler$clone()

`MLLpNormScaler$new()`

Initialize the MLLpNormScaler

Usage

MLLpNormScaler$new(
  norm_type = 2,
  center = TRUE,
  scale = TRUE,
  n_threads = NULL
)

Arguments

norm_type: Integer, 1 for L1 norm, 2 for L2 norm (default: 2)
center: Logical, whether to center columns to mean 0 (default: TRUE)
scale: Logical, whether to scale columns to unit Lp norm (default: TRUE)
n_threads: Integer, the thread budget of the column passes (NULL, the default: the library's default budget, trex_get_num_threads(), initially 1).

`MLLpNormScaler$fit()`

Compute the norm parameters.

Usage

MLLpNormScaler$fit(X, threshold = 1e-12)

Arguments

X: A numeric matrix (n x p) or an mmap_matrix in "readwrite" mode (the scaler core binds a mutable map).
threshold: Double, lower bound for the scale statistic (default: 1e-12).

Returns

Value.

`MLLpNormScaler$transform_inplace()`

Perform standardization in-place.

Usage

MLLpNormScaler$transform_inplace(X)

Arguments

X: A numeric matrix (n x p) or an mmap_matrix in "readwrite" mode.

Returns

The modified matrix X (the same handle for an mmap_matrix).

`MLLpNormScaler$inverse_transform_inplace()`

Inverse transform to original scale.

Usage

MLLpNormScaler$inverse_transform_inplace(X)

Arguments

X: A numeric matrix (n x p) or an mmap_matrix in "readwrite" mode.

Returns

The modified matrix X (the same handle for an mmap_matrix).

`MLLpNormScaler$fit_transform_inplace()`

Fit and transform in one call, like R's scale().

Usage

MLLpNormScaler$fit_transform_inplace(X, threshold = 1e-12)

Arguments

X: A numeric matrix (n x p) or an mmap_matrix in "readwrite" mode.
threshold: Double, lower bound for the scale statistic (default: 1e-12).

Returns

The modified matrix X (the same handle for an mmap_matrix).

`MLLpNormScaler$is_fitted()`

Check if scaler is fitted.

Usage

MLLpNormScaler$is_fitted()

Returns

Value.

`MLLpNormScaler$get_dropped_indices()`

Get dropped (degenerate) column indices. These columns get scale factor 1 and are still centered (sklearn semantics).

Usage

MLLpNormScaler$get_dropped_indices()

Returns

Value.

`MLLpNormScaler$get_centers()`

Get the learned centers (column means).

Usage

MLLpNormScaler$get_centers()

Returns

Value.

`MLLpNormScaler$get_scales()`

Get the learned scales.

Usage

MLLpNormScaler$get_scales()

Returns

Value.

`MLLpNormScaler$get_center()`

Check if scaler centers data.

Usage

MLLpNormScaler$get_center()

Returns

Value.

`MLLpNormScaler$get_scale()`

Check if scaler scales data to unit norm.

Usage

MLLpNormScaler$get_scale()

Returns

Value.

`MLLpNormScaler$get_norm_type()`

Get norm type (1 for L1, 2 for L2).

Usage

MLLpNormScaler$get_norm_type()

Returns

Value.

`MLLpNormScaler$save()`

Save model state to file.

Usage

MLLpNormScaler$save(filename)

Arguments

filename: String path to save output.

Returns

Value.

`MLLpNormScaler$load()`

Load model state from file.

Usage

MLLpNormScaler$load(filename)

Arguments

filename: String path to load input from.

Returns

Value.

`MLLpNormScaler$clone()`

The objects of this class are cloneable with this method.

Usage

MLLpNormScaler$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples

set.seed(1)
X <- matrix(rnorm(50 * 5), 50, 5)
scaler <- MLLpNormScaler$new(norm_type = 2)
scaler$fit(X)
X_norm <- scaler$transform_inplace(X)

Principal Component Analysis

Description

Fits PCA to a data matrix, retaining the top-M principal components. Centering/normalization is applied to X in-place at construction time (the R matrix or the memory-mapped file itself, no copy) and undone by restore(), which may be called before or after fit() and is idempotent; an object that is garbage-collected without restore() writes X back in its finalizer (the same rule as the T-solvers).

Details

Wraps the C++ PCA class. The instance is bound to X at creation (mirroring the C++ constructor); fit() is single-use. The fit result is cached internally; use the get_*() accessors or pass X_new to transform() for out-of-sample scoring.

Methods

Public methods

MLPCA$new()
MLPCA$fit()
MLPCA$transform()
MLPCA$restore()
MLPCA$get_scores()
MLPCA$get_loadings()
MLPCA$get_explained_variance()
MLPCA$get_means()
MLPCA$get_norms()
MLPCA$clone()

`MLPCA$new()`

Initialize PCA bound to X. Centering/normalization is applied to X in-place immediately.

Usage

MLPCA$new(X, M, center = TRUE, normalize = TRUE, n_threads = NULL)

Arguments

X: A numeric matrix (n x p), or an mmap_matrix ("readwrite": the file is modified). Modified in place when centering/normalizing; call restore() to undo.
M: Integer, number of principal components.
center: Logical, whether to center X in-place (default: TRUE).
normalize: Logical, whether to scale the columns of X in-place (default: TRUE).
n_threads: Integer, the thread budget of the matrix products of fit() and transform() (NULL, the default: the library's default budget, trex_get_num_threads(), initially 1).

`MLPCA$fit()`

Fit the PCA bound at construction time (single-use).

Usage

MLPCA$fit()

Returns

Invisible self for method chaining.

`MLPCA$transform()`

Project new data onto the fitted principal subspace.

Usage

MLPCA$transform(X_new)

Arguments

X_new: A numeric matrix (n_new x p), or an mmap_matrix (zero-copy). The stored training means/norms are applied before projection.

Returns

Score matrix (n_new x M).

`MLPCA$restore()`

Restore X to its original values (un-center/un-scale).

Usage

MLPCA$restore()

Returns

Invisible self.

`MLPCA$get_scores()`

Get the PC score matrix from the fit() call.

Usage

MLPCA$get_scores()

Returns

Score matrix (n x M), or NULL if fit() not yet called.

`MLPCA$get_loadings()`

Get loading matrix from the fit() call.

Usage

MLPCA$get_loadings()

Returns

Loading matrix (p x M), or NULL if fit() not yet called.

`MLPCA$get_explained_variance()`

Get explained variance per component from the fit() call.

Usage

MLPCA$get_explained_variance()

Returns

Numeric vector of length M, or NULL if fit() not yet called.

`MLPCA$get_means()`

Get the column means used for centering.

Usage

MLPCA$get_means()

Returns

Numeric vector of length p. Zero-vector when center = FALSE.

`MLPCA$get_norms()`

Get the column scaling factors used for normalization.

Usage

MLPCA$get_norms()

Returns

Numeric vector of length p. Ones when normalize = FALSE.

`MLPCA$clone()`

The objects of this class are cloneable with this method.

Usage

MLPCA$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

G. Guennebaud, B. Jacob et al., Eigen v3, https://libeigen.gitlab.io/, 2010.

Examples

set.seed(42)
X <- matrix(rnorm(50 * 8), 50, 8)
pca <- MLPCA$new(X, M = 3, center = TRUE)
pca$fit()
pca$get_explained_variance()
X_new <- matrix(rnorm(10 * 8), 10, 8)
pca$transform(X_new)
pca$restore()

Ridge Regression Solver

Description

Solves the ridge regression problem \min_\beta \|y - X\beta\|^2 + \lambda \|\beta\|^2 for a single regularization value. Dispatches internally between primal (n \ge p) and dual (n < p) Cholesky paths.

Details

Wraps the C++ MLRidge::solve(X, y, lambda) static method.

Methods

Public methods

MLRidge$solve()
MLRidge$clone()

`MLRidge$solve()`

Solve ridge regression for a single lambda.

Usage

MLRidge$solve(X, y, lambda, n_threads = NULL)

Arguments

X: A numeric matrix (n x p), or an mmap_matrix (bound zero-copy; "readonly" suffices).
y: Numeric response vector of length n.
lambda: Non-negative regularization parameter.
n_threads: Integer, the thread budget of the matrix products (NULL, the default: the library's default budget, trex_get_num_threads(), initially 1).

Returns

Coefficient vector of length p.

`MLRidge$clone()`

The objects of this class are cloneable with this method.

Usage

MLRidge$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

A. E. Hoerl and R. W. Kennard, "Ridge Regression: Biased Estimation for Nonorthogonal Problems," Technometrics, vol. 42, no. 1, pp. 80-86, 2000 (Reprint of the 1970 article in the Special 40th Anniversary Issue).

Examples

set.seed(42)
n <- 40; p <- 5
X <- matrix(rnorm(n * p), n, p)
beta_true <- c(1, -2, 0, 0.5, 0)
y <- X %*% beta_true + rnorm(n, sd = 0.1)
solver <- MLRidge$new()
beta_hat <- solver$solve(X, y, lambda = 0.01)

Ridge Regression with Cross-Validation

Description

Performs explicit K-Fold cross-validation for Ridge Regression model selection.

Methods

Public methods

MLRidgeCV$new()
MLRidgeCV$fit()
MLRidgeCV$cv_min()
MLRidgeCV$cv_1se()
MLRidgeCV$index_min()
MLRidgeCV$index_1se()
MLRidgeCV$get_lambdas()
MLRidgeCV$get_cv_errors()
MLRidgeCV$get_cv_std()
MLRidgeCV$interpolates()
MLRidgeCV$selection_at_grid_edge()
MLRidgeCV$clone()

`MLRidgeCV$new()`

Initialize the MLRidgeCV object.

Usage

MLRidgeCV$new(low_memory = FALSE, n_threads = NULL)

Arguments

low_memory: Logical (default FALSE). FALSE: each fold gathers and standardizes its training rows and takes a thin SVD (about three to four copies of X in flight). TRUE: the dual (kernel) form — n x n kernels accumulated from column blocks of X read in place (an mmap_matrix included, "readonly" suffices), no p-dimensional coefficients; same estimator, grid and rank rule, agreement to numerical precision; memory O(n^2) instead of O(n p), the route for p >> n.
n_threads: Integer, the thread budget of the fit's matrix products (NULL, the default: the library's default budget, trex_get_num_threads(), initially 1).

`MLRidgeCV$fit()`

Fit the CV model.

Usage

MLRidgeCV$fit(
  X,
  y,
  n_folds = 10,
  n_lambda = 100,
  lambda_ratio = 1000,
  seed = 0
)

Arguments

X: Predictor matrix, or an mmap_matrix created by mem_matrix / mem_matrix_from (bound zero-copy; "readonly" mode suffices since the fit does not modify X).
y: Response vector.
n_folds: Number of folds (default 10).
n_lambda: Number of lambdas in the path (default 100).
lambda_ratio: Ratio of max to min lambda (default 1000).
seed: Random seed for CV splits (default 0).

Returns

Value.

`MLRidgeCV$cv_min()`

Get lambda that minimizes CV error.

Usage

MLRidgeCV$cv_min()

Returns

Value.

`MLRidgeCV$cv_1se()`

Get 1SE rule lambda.

Usage

MLRidgeCV$cv_1se()

Returns

Value.

`MLRidgeCV$index_min()`

Get index of minimum CV error.

Usage

MLRidgeCV$index_min()

Returns

Value.

`MLRidgeCV$index_1se()`

Get index of 1SE rule lambda.

Usage

MLRidgeCV$index_1se()

Returns

Value.

`MLRidgeCV$get_lambdas()`

Get the sequence of lambdas used.

Usage

MLRidgeCV$get_lambdas()

Returns

Value.

`MLRidgeCV$get_cv_errors()`

Get the CV mean squared errors for each lambda.

Usage

MLRidgeCV$get_cv_errors()

Returns

Value.

`MLRidgeCV$get_cv_std()`

Get the standard error of the CV errors.

Usage

MLRidgeCV$get_cv_std()

Returns

Value.

`MLRidgeCV$interpolates()`

Whether the smallest training fold has p >= n_train, so the lambda -> 0 end of the grid tends to the minimum-norm interpolator instead of an ordinary least-squares fit. The curve still has a genuine interior minimum in that regime; together with selection_at_grid_edge() it tells whether cv_min() is a real minimum or the grid running out.

Usage

MLRidgeCV$interpolates()

Returns

Logical.

`MLRidgeCV$selection_at_grid_edge()`

Whether cv_min() or cv_1se() landed on the first or the last grid point. The pick is then the grid boundary, not an optimum, and lambda_ratio or n_lambda need widening.

Usage

MLRidgeCV$selection_at_grid_edge()

Returns

Logical.

`MLRidgeCV$clone()`

The objects of this class are cloneable with this method.

Usage

MLRidgeCV$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

G. Guennebaud, B. Jacob et al., Eigen v3, https://libeigen.gitlab.io/, 2010.

Examples

set.seed(1)
X <- matrix(rnorm(50 * 5), 50, 5)
y <- X[, 1] * 2 + rnorm(50)
cv <- MLRidgeCV$new()
cv$fit(X, y, n_folds = 5)
cv$cv_min()
cv$selection_at_grid_edge()   # FALSE: the picks are interior grid points

SVD Solver

Description

Computes the top-M truncated SVD of a matrix. Dispatches internally between a direct (tall matrices), Gram (wide matrices), and randomized path based on the shape of X.

Details

Wraps the C++ MLSVD::compute(X, M) static method.

Methods

Public methods

MLSVD$new()
MLSVD$compute()
MLSVD$clone()

`MLSVD$new()`

Initialize the solver with its dispatch thresholds.

Usage

MLSVD$new(min_dim_thresh = 10000, block_size = 1024, n_threads = NULL)

Arguments

min_dim_thresh: Integer (default 10000). The direct path (a Jacobi SVD that copies X and computes every singular triplet) is taken while min(n, p) is below it; above it, and when M < min(n, p) / 10, the randomized path runs two block-wise passes over X without a copy (the route for a large mmap_matrix). p > 2 n always takes the Gram path.
block_size: Integer (default 1024): the column block of the block-wise passes.
n_threads: Integer, the thread budget of the matrix products (NULL, the default: the library's default budget, trex_get_num_threads(), initially 1).

`MLSVD$compute()`

Compute top-M singular value decomposition of X.

Usage

MLSVD$compute(X, M)

Arguments

X: A numeric matrix (n x p), or an mmap_matrix (bound zero-copy; "readonly" suffices).
M: Integer, number of singular components to retain.

Returns

Named list with:

U Left singular vectors (n x M).
S Singular values (M).
V Right singular vectors (p x M).

`MLSVD$clone()`

The objects of this class are cloneable with this method.

Usage

MLSVD$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

G. Guennebaud, B. Jacob et al., Eigen v3, https://libeigen.gitlab.io/, 2010.

Examples

set.seed(42)
X <- matrix(rnorm(50 * 10), 50, 10)
solver <- MLSVD$new()
res <- solver$compute(X, M = 3)
dim(res$U)  # 50 x 3

Z-Score Scaler

Description

Standardizes features by removing the mean and scaling to unit variance (Bessel-corrected, n - 1). The center/scale arguments follow R's scale(): with center = FALSE, scale = TRUE columns are divided by the root-mean-square around 0.

Details

Methods

Public methods

MLZScoreScaler$new()
MLZScoreScaler$fit()
MLZScoreScaler$transform_inplace()
MLZScoreScaler$inverse_transform_inplace()
MLZScoreScaler$fit_transform_inplace()
MLZScoreScaler$is_fitted()
MLZScoreScaler$get_dropped_indices()
MLZScoreScaler$get_center()
MLZScoreScaler$get_scale()
MLZScoreScaler$get_centers()
MLZScoreScaler$get_scales()
MLZScoreScaler$save()
MLZScoreScaler$load()
MLZScoreScaler$clone()

`MLZScoreScaler$new()`

Initialize the MLZScoreScaler

Usage

MLZScoreScaler$new(center = TRUE, scale = TRUE, n_threads = NULL)

Arguments

center: Logical, whether to center columns to mean 0 (default: TRUE)
scale: Logical, whether to scale columns to unit SD (default: TRUE); around 0 instead of the mean when center = FALSE, as in R's scale().
n_threads: Integer, the thread budget of the column passes (NULL, the default: the library's default budget, trex_get_num_threads(), initially 1).

`MLZScoreScaler$fit()`

Compute the centers and scales to be used for later scaling.

Usage

MLZScoreScaler$fit(X, threshold = 1e-12)

Arguments

X: A numeric matrix (n x p) or an mmap_matrix in "readwrite" mode (the scaler core binds a mutable map).
threshold: Double, lower bound for the scale statistic (default: 1e-12).

Returns

Value.

`MLZScoreScaler$transform_inplace()`

Perform standardization by centering and scaling in-place.

Usage

MLZScoreScaler$transform_inplace(X)

Arguments

X: A numeric matrix (n x p) or an mmap_matrix in "readwrite" mode.

Returns

The modified matrix X (the same handle for an mmap_matrix).

`MLZScoreScaler$inverse_transform_inplace()`

Inverse transform to original scale.

Usage

MLZScoreScaler$inverse_transform_inplace(X)

Arguments

X: A numeric matrix (n x p) or an mmap_matrix in "readwrite" mode.

Returns

The modified matrix X (the same handle for an mmap_matrix).

`MLZScoreScaler$fit_transform_inplace()`

Fit and transform in one call, like R's scale().

Usage

MLZScoreScaler$fit_transform_inplace(X, threshold = 1e-12)

Arguments

X: A numeric matrix (n x p) or an mmap_matrix in "readwrite" mode.
threshold: Double, lower bound for the scale statistic (default: 1e-12).

Returns

The modified matrix X (the same handle for an mmap_matrix).

`MLZScoreScaler$is_fitted()`

Check if scaler is fitted.

Usage

MLZScoreScaler$is_fitted()

Returns

Value.

`MLZScoreScaler$get_dropped_indices()`

Get dropped (degenerate) column indices. These columns get scale factor 1 and are still centered (sklearn semantics).

Usage

MLZScoreScaler$get_dropped_indices()

Returns

Value.

`MLZScoreScaler$get_center()`

Check if scaler centers data.

Usage

MLZScoreScaler$get_center()

Returns

Value.

`MLZScoreScaler$get_scale()`

Check if scaler scales data to unit variance.

Usage

MLZScoreScaler$get_scale()

Returns

Value.

`MLZScoreScaler$get_centers()`

Get the learned centers (column means).

Usage

MLZScoreScaler$get_centers()

Returns

Value.

`MLZScoreScaler$get_scales()`

Get the learned scales (standard deviations).

Usage

MLZScoreScaler$get_scales()

Returns

Value.

`MLZScoreScaler$save()`

Save model state to file.

Usage

MLZScoreScaler$save(filename)

Arguments

filename: String path to save output.

Returns

Value.

`MLZScoreScaler$load()`

Load model state from file.

Usage

MLZScoreScaler$load(filename)

Arguments

filename: String path to load input from.

Returns

Value.

`MLZScoreScaler$clone()`

The objects of this class are cloneable with this method.

Usage

MLZScoreScaler$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples

set.seed(1)
X <- matrix(rnorm(50 * 5), 50, 5)
scaler <- MLZScoreScaler$new()
scaler$fit(X)
X_std <- scaler$transform_inplace(X)
scaler$get_centers()

T-ACGP Solver

Description

Terminating Approximate Conjugate Gradient Pursuit (T-ACGP) solver. Inherits all common methods from TSolver_Base.

Super class

TSolver_Base -> TACGP_Solver

Methods

Public methods

TACGP_Solver$new()
TACGP_Solver$clone()

Inherited methods

`TACGP_Solver$new()`

Create a new TACGP_Solver.

Usage

TACGP_Solver$new(X, D, y, options = tsolver_options())

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies.
y: Numeric response vector.
options: Solver options from tsolver_options (default: tsolver_options()).

`TACGP_Solver$clone()`

The objects of this class are cloneable with this method.

Usage

TACGP_Solver$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

T. Blumensath and M. E. Davies, "Gradient Pursuits," IEEE Trans. Signal Process., vol. 56, no. 6, pp. 2370-2382, 2008.

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.

Examples

set.seed(1)
n <- 20; p <- 5
X <- matrix(rnorm(n * p), n, p)
D <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + rnorm(n)
solver <- TACGP_Solver$new(X, D, y)
solver$execute_step(T_stop = 3)
solver$get_beta()

T-AFS Solver

Description

Terminating Adaptive Forward Stepwise (T-AFS) solver. The shrinkage parameter rho interpolates between Forward Stepwise (rho = 1) and LAR/LASSO (rho -> 0). Inherits all common methods from TSolver_Base.

Super class

TSolver_Base -> TAFS_Solver

Methods

Public methods

TAFS_Solver$new()
TAFS_Solver$clone()

Inherited methods

`TAFS_Solver$new()`

Create a new TAFS_Solver.

Usage

TAFS_Solver$new(X, D, y, options = tsolver_options())

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies.
y: Numeric response vector.
options: Solver options from tsolver_options; this solver reads rho_afs, the shrinkage parameter in (0, 1] (default 1: forward stepwise).

`TAFS_Solver$clone()`

The objects of this class are cloneable with this method.

Usage

TAFS_Solver$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

I. Zhang and R. Tibshirani, "Adaptive Forward Stepwise: A Method for High Sparsity Regression," J. Mach. Learn. Res., vol. 27, pp. 1-24, 2026.

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.

Examples

set.seed(1)
n <- 20; p <- 5
X <- matrix(rnorm(n * p), n, p)
D <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + rnorm(n)
solver <- TAFS_Solver$new(X, D, y, options = tsolver_options(rho_afs = 0.5))
solver$execute_step(T_stop = 3)
solver$get_beta()

T-CDENET Solver

Description

Terminating coordinate-descent Elastic Net (diagonal ridge lambda2, the dummies get kappa_dummy * lambda2). The solver used internally by TRexGVSSelector for en_solver = "TCDENET". Inherits the CD getters from TCDSolver_Base and all common methods from TSolver_Base.

Super classes

TSolver_Base -> TCDSolver_Base -> TCDENET_Solver

Methods

Public methods

TCDENET_Solver$new()
TCDENET_Solver$clone()

Inherited methods

`TCDENET_Solver$new()`

Create a new TCDENET_Solver.

Usage

TCDENET_Solver$new(X, D, y, options = tsolver_options())

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies.
y: Numeric response vector.
options: Solver options from tsolver_options; this solver reads lambda2, kappa_dummy and the cd_* knobs.

`TCDENET_Solver$clone()`

The objects of this class are cloneable with this method.

Usage

TCDENET_Solver$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

H. Zou and T. Hastie, "Regularization and Variable Selection via the Elastic Net," J. R. Stat. Soc. Ser. B Stat. Methodol., vol. 67, no. 2, pp. 301-320, 2005.

J. Friedman, T. Hastie, H. Höfling, and R. Tibshirani, "Pathwise Coordinate Optimization," Ann. Appl. Stat., vol. 1, no. 2, pp. 302-332, 2007, doi: 10.1214/07-AOAS131.

J. Friedman, T. Hastie, and R. Tibshirani, "Regularization Paths for Generalized Linear Models via Coordinate Descent," J. Stat. Softw., vol. 33, no. 1, pp. 1-22, 2010, doi: 10.18637/jss.v033.i01.

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.

Examples

set.seed(1)
n <- 20; p <- 5
X <- matrix(rnorm(n * p), n, p)
D <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + rnorm(n)
solver <- TCDENET_Solver$new(X, D, y, options = tsolver_options(lambda2 = 0.1))
solver$execute_step(T_stop = 3)
solver$get_beta()

T-CDIENET Solver

Description

Terminating coordinate-descent Informed Elastic Net: exact fixed-lambda1 IEN minimizers per dummy crossing with O(1) group-penalty hooks (group_penalty = "MEAN", the canonical group-sum penalty, or "CENTERING"). The solver used internally by TRexGVSSelector for solver = "TCDIENET". Inherits the CD getters from TCDSolver_Base and all common methods from TSolver_Base.

Super classes

TSolver_Base -> TCDSolver_Base -> TCDIENET_Solver

Methods

Public methods

TCDIENET_Solver$new()
TCDIENET_Solver$get_groups()
TCDIENET_Solver$get_num_groups()
TCDIENET_Solver$clone()

Inherited methods

`TCDIENET_Solver$new()`

Create a new TCDIENET_Solver.

Usage

TCDIENET_Solver$new(X, D, y, groups, options = tsolver_options())

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies (a multiple of ncol(X) columns: one group-aligned layer per p).
y: Numeric response vector.
groups: Integer vector of 1-based group ids, one per predictor column of X (contiguous ids starting at 1).
options: Solver options from tsolver_options; this solver reads lambda2, group_penalty and the cd_* knobs.

`TCDIENET_Solver$get_groups()`

Get the group ids (1-based, one per predictor).

Usage

TCDIENET_Solver$get_groups()

Returns

Integer vector of group ids.

`TCDIENET_Solver$get_num_groups()`

Get the number of disjoint groups.

Usage

TCDIENET_Solver$get_num_groups()

Returns

Integer count of groups.

`TCDIENET_Solver$clone()`

The objects of this class are cloneable with this method.

Usage

TCDIENET_Solver$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

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.

H. Zou and T. Hastie, "Regularization and Variable Selection via the Elastic Net," J. R. Stat. Soc. Ser. B Stat. Methodol., vol. 67, no. 2, pp. 301-320, 2005.

J. Friedman, T. Hastie, H. Höfling, and R. Tibshirani, "Pathwise Coordinate Optimization," Ann. Appl. Stat., vol. 1, no. 2, pp. 302-332, 2007, doi: 10.1214/07-AOAS131.

J. Friedman, T. Hastie, and R. Tibshirani, "Regularization Paths for Generalized Linear Models via Coordinate Descent," J. Stat. Softw., vol. 33, no. 1, pp. 1-22, 2010, doi: 10.18637/jss.v033.i01.

Examples

set.seed(1)
n <- 20; p <- 4
X <- matrix(rnorm(n * p), n, p)
D <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + rnorm(n)
solver <- TCDIENET_Solver$new(X, D, y, groups = c(1, 1, 2, 2),
                              options = tsolver_options(lambda2 = 0.1))
solver$execute_step(T_stop = 3)
solver$get_beta()

T-CDLASSO Solver

Description

Terminating coordinate-descent LASSO: exact penalized-lasso minimizers at every dummy crossing, localized with certificates (duality gap and coordinate statuses; cd_certified_localization = FALSE in the options selects the LEGACY probe bisection). The base of the CD family (TCDENET_Solver, TCDIENET_Solver, TCDTIKNET_Solver inherit its getters). Inherits all common methods from TSolver_Base.

Super classes

TSolver_Base -> TCDSolver_Base -> TCDLASSO_Solver

Methods

Public methods

TCDLASSO_Solver$new()
TCDLASSO_Solver$clone()

Inherited methods

`TCDLASSO_Solver$new()`

Create a new TCDLASSO_Solver.

Usage

TCDLASSO_Solver$new(X, D, y, options = tsolver_options())

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies.
y: Numeric response vector.
options: Solver options from tsolver_options; this solver reads the cd_* knobs.

`TCDLASSO_Solver$clone()`

The objects of this class are cloneable with this method.

Usage

TCDLASSO_Solver$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

R. Tibshirani, "Regression Shrinkage and Selection via the Lasso," J. R. Stat. Soc. Ser. B Stat. Methodol., vol. 58, no. 1, pp. 267-288, 1996.

J. Friedman, T. Hastie, H. Höfling, and R. Tibshirani, "Pathwise Coordinate Optimization," Ann. Appl. Stat., vol. 1, no. 2, pp. 302-332, 2007, doi: 10.1214/07-AOAS131.

J. Friedman, T. Hastie, and R. Tibshirani, "Regularization Paths for Generalized Linear Models via Coordinate Descent," J. Stat. Softw., vol. 33, no. 1, pp. 1-22, 2010, doi: 10.18637/jss.v033.i01.

W. J. Fu, "Penalized Regression: The Bridge Versus the Lasso," J. Comput. Graph. Statist., vol. 7, pp. 397-416, 1998.

Examples

set.seed(1)
n <- 20; p <- 5
X <- matrix(rnorm(n * p), n, p)
D <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + rnorm(n)
solver <- TCDLASSO_Solver$new(X, D, y)
solver$execute_step(T_stop = 3)
solver$get_beta()
solver$is_certified_localization()

CD-family base class

Description

Shared getters of the coordinate-descent solver family (TCDLASSO_Solver, TCDENET_Solver, TCDIENET_Solver, TCDTIKNET_Solver): the recorded lambda_1 path, the quadratic penalty weight, and the certified-localization diagnostics. Not intended for direct instantiation.

Super class

TSolver_Base -> TCDSolver_Base

Methods

Public methods

TCDSolver_Base$get_lambda()
TCDSolver_Base$get_lambda2()
TCDSolver_Base$is_certified_localization()
TCDSolver_Base$is_certified_degraded()
TCDSolver_Base$get_record_gaps()
TCDSolver_Base$get_record_kkt_violations()
TCDSolver_Base$get_kkt_violation()
TCDSolver_Base$clone()

Inherited methods

`TCDSolver_Base$get_lambda()`

Get lambda_1 at every recorded step.

Usage

TCDSolver_Base$get_lambda()

Returns

Numeric vector, one per step.

`TCDSolver_Base$get_lambda2()`

Get the quadratic penalty weight lambda2 (0 for T-CDLASSO).

Usage

TCDSolver_Base$get_lambda2()

Returns

Scalar numeric lambda2.

`TCDSolver_Base$is_certified_localization()`

Is the certified crossing localization active?

Usage

TCDSolver_Base$is_certified_localization()

Returns

Logical.

`TCDSolver_Base$is_certified_degraded()`

Did certification become unavailable along the path (A0-w boundary), so the solver fell back to LEGACY localization?

Usage

TCDSolver_Base$is_certified_degraded()

Returns

Logical.

`TCDSolver_Base$get_record_gaps()`

Get the duality gap at every recorded step.

Usage

TCDSolver_Base$get_record_gaps()

Returns

Numeric vector, one per step.

`TCDSolver_Base$get_record_kkt_violations()`

Get the KKT violation at every recorded step.

Usage

TCDSolver_Base$get_record_kkt_violations()

Returns

Numeric vector, one per step.

`TCDSolver_Base$get_kkt_violation()`

KKT violation of the current state (a certificate of the coordinate-descent minimizer).

Usage

TCDSolver_Base$get_kkt_violation(lambda1 = -1)

Arguments

lambda1: The lambda_1 to certify at; negative (default) uses the solver's current one.

Returns

Numeric scalar.

`TCDSolver_Base$clone()`

The objects of this class are cloneable with this method.

Usage

TCDSolver_Base$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

T-CDTIKNET Solver

Description

Terminating coordinate-descent Tikhonov Net: exact fixed-lambda1 minimizers per dummy crossing under the general quadratic penalty lambda2 * t(beta) K beta with a sparse PSD K. Dummy coupling per fold_dummies in the options (FALSE: independent kappa_dummy ridge; TRUE: FOLDED layered convention). The solver used internally by TRexTikhonovSelector for solver = "TCDTIKNET". Inherits the CD getters from TCDSolver_Base and all common methods from TSolver_Base.

Super classes

TSolver_Base -> TCDSolver_Base -> TCDTIKNET_Solver

Methods

Public methods

TCDTIKNET_Solver$new()
TCDTIKNET_Solver$is_folded_dummy_coupling()
TCDTIKNET_Solver$clone()

Inherited methods

`TCDTIKNET_Solver$new()`

Create a new TCDTIKNET_Solver.

Usage

TCDTIKNET_Solver$new(X, D, y, tikhonov_K, options = tsolver_options())

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies (a multiple of ncol(X) columns when fold_dummies = TRUE).
y: Numeric response vector.
tikhonov_K: p x p PSD Tikhonov matrix: a Matrix::dgCMatrix or a dense matrix.
options: Solver options from tsolver_options; this solver reads lambda2, kappa_dummy, fold_dummies and the cd_* knobs.

`TCDTIKNET_Solver$is_folded_dummy_coupling()`

Is the FOLDED dummy coupling active?

Usage

TCDTIKNET_Solver$is_folded_dummy_coupling()

Returns

Logical.

`TCDTIKNET_Solver$clone()`

The objects of this class are cloneable with this method.

Usage

TCDTIKNET_Solver$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

A. N. Tikhonov, "Solution of Incorrectly Formulated Problems and the Regularization Method," Soviet Math. Dokl., vol. 4, pp. 1035-1038, 1963 (English translation of Dokl. Akad. Nauk SSSR 151 (1963), no. 3, 501-504).

Y. Park, L. Reichel, G. Rodriguez, and X. Yu, "Parameter Determination for Tikhonov Regularization Problems in General Form," J. Comput. Appl. Math., vol. 343, pp. 12-25, 2018, doi: 10.1016/j.cam.2018.04.049.

J. Friedman, T. Hastie, H. Höfling, and R. Tibshirani, "Pathwise Coordinate Optimization," Ann. Appl. Stat., vol. 1, no. 2, pp. 302-332, 2007, doi: 10.1214/07-AOAS131.

J. Friedman, T. Hastie, and R. Tibshirani, "Regularization Paths for Generalized Linear Models via Coordinate Descent," J. Stat. Softw., vol. 33, no. 1, pp. 1-22, 2010, doi: 10.18637/jss.v033.i01.

Examples

set.seed(1)
n <- 20; p <- 4
X <- matrix(rnorm(n * p), n, p)
D <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + rnorm(n)
solver <- TCDTIKNET_Solver$new(X, D, y, tikhonov_K = diag(p),
                               options = tsolver_options(lambda2 = 0.1))
solver$execute_step(T_stop = 3)
solver$get_beta()

T-ENET-Aug Solver

Description

Terminating Elastic Net solver via row augmentation (TENETAug). The ridge penalty is encoded in an augmented data system solved by an inner T-LASSO (or pure T-LARS) path, matching the R reference implementation of trex_GVS(). Inherits all common methods from TSolver_Base.

Super class

TSolver_Base -> TENETAug_Solver

Methods

Public methods

TENETAug_Solver$new()
TENETAug_Solver$clone()

Inherited methods

`TENETAug_Solver$new()`

Create a new TENETAug_Solver.

Usage

TENETAug_Solver$new(X, D, y, options = tsolver_options())

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies.
y: Numeric response vector.
options: Solver options from tsolver_options; this solver reads lambda2 (the ridge penalty, >= 0) and tenet_aug_use_lars (run the inner path with a pure-LARS solver that never drops variables).

`TENETAug_Solver$clone()`

The objects of this class are cloneable with this method.

Usage

TENETAug_Solver$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

H. Zou and T. Hastie, "Regularization and Variable Selection via the Elastic Net," J. R. Stat. Soc. Ser. B Stat. Methodol., vol. 67, no. 2, pp. 301-320, 2005.

B. Efron, T. Hastie, I. Johnstone, and R. Tibshirani, "Least Angle Regression," Ann. Statist., vol. 32, no. 2, pp. 407-499, 2004.

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.

Examples

set.seed(1)
n <- 20; p <- 5
X <- matrix(rnorm(n * p), n, p)
D <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + rnorm(n)
solver <- TENETAug_Solver$new(X, D, y, options = tsolver_options(lambda2 = 0.1))
solver$execute_step(T_stop = 3)
solver$get_beta()

T-ENET Solver

Description

Terminating Elastic Net solver (L1 + L2 regularization). Inherits all common methods from TSolver_Base.

Super class

TSolver_Base -> TENET_Solver

Methods

Public methods

TENET_Solver$new()
TENET_Solver$get_num_removals()
TENET_Solver$get_cycling_ratio()
TENET_Solver$get_lambda()
TENET_Solver$get_alpha()
TENET_Solver$clone()

Inherited methods

`TENET_Solver$new()`

Create a new TENET_Solver.

Usage

TENET_Solver$new(X, D, y, options = tsolver_options())

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies.
y: Numeric response vector.
options: Solver options from tsolver_options; this solver reads lambda2, the L2 (ridge) penalty (>= 0; the default 0 is the plain lasso path).

`TENET_Solver$get_num_removals()`

Get the number of coefficient removals.

Usage

TENET_Solver$get_num_removals()

Returns

Integer count of removals.

`TENET_Solver$get_cycling_ratio()`

Get the cycling ratio (removals / total steps).

Usage

TENET_Solver$get_cycling_ratio()

Returns

Scalar numeric cycling ratio.

`TENET_Solver$get_lambda()`

Get the regularization (lambda) path.

Usage

TENET_Solver$get_lambda()

Returns

Numeric vector of lambda values, one per step.

`TENET_Solver$get_alpha()`

The elastic-net mixing alpha implied by lambda2.

Usage

TENET_Solver$get_alpha()

Returns

Numeric scalar.

`TENET_Solver$clone()`

The objects of this class are cloneable with this method.

Usage

TENET_Solver$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

H. Zou and T. Hastie, "Regularization and Variable Selection via the Elastic Net," J. R. Stat. Soc. Ser. B Stat. Methodol., vol. 67, no. 2, pp. 301-320, 2005.

B. Efron, T. Hastie, I. Johnstone, and R. Tibshirani, "Least Angle Regression," Ann. Statist., vol. 32, no. 2, pp. 407-499, 2004.

Examples

set.seed(1)
n <- 20; p <- 5
X <- matrix(rnorm(n * p), n, p)
D <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + rnorm(n)
solver <- TENET_Solver$new(X, D, y, options = tsolver_options(lambda2 = 0.1))
solver$execute_step(T_stop = 3)
solver$get_beta()

T-GP Solver

Description

Terminating Gradient Pursuit (T-GP) solver. Inherits all common methods from TSolver_Base.

Super class

TSolver_Base -> TGP_Solver

Methods

Public methods

TGP_Solver$new()
TGP_Solver$clone()

Inherited methods

`TGP_Solver$new()`

Create a new TGP_Solver.

Usage

TGP_Solver$new(X, D, y, options = tsolver_options())

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies.
y: Numeric response vector.
options: Solver options from tsolver_options (default: tsolver_options()).

`TGP_Solver$clone()`

The objects of this class are cloneable with this method.

Usage

TGP_Solver$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

T. Blumensath and M. E. Davies, "Gradient Pursuits," IEEE Trans. Signal Process., vol. 56, no. 6, pp. 2370-2382, 2008.

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.

Examples

set.seed(1)
n <- 20; p <- 5
X <- matrix(rnorm(n * p), n, p)
D <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + rnorm(n)
solver <- TGP_Solver$new(X, D, y)
solver$execute_step(T_stop = 3)
solver$get_beta()

T-IENET-Aug Solver

Description

Terminating Informed Elastic Net solver via row augmentation (TIENETAug). The group-ridge penalty (one augmented row per group, scaled by sqrt(lambda2)) is encoded in an augmented data system solved by an inner T-LASSO (or pure T-LARS) path. This is the solver used internally by TRexGVSSelector for gvs_type = "IEN". Inherits all common methods from TSolver_Base.

Super class

TSolver_Base -> TIENETAug_Solver

Methods

Public methods

TIENETAug_Solver$new()
TIENETAug_Solver$get_lambda2()
TIENETAug_Solver$get_groups()
TIENETAug_Solver$get_num_groups()
TIENETAug_Solver$clone()

Inherited methods

`TIENETAug_Solver$new()`

Create a new TIENETAug_Solver.

Usage

TIENETAug_Solver$new(X, D, y, groups, options = tsolver_options())

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies.
y: Numeric response vector.
groups: Integer vector of 1-based group ids, one per predictor column of X (contiguous ids starting at 1).
options: Solver options from tsolver_options; this solver reads lambda2 (the group-ridge penalty, >= 0) and tenet_aug_use_lars (run the inner path with a pure-LARS solver that never drops variables).

`TIENETAug_Solver$get_lambda2()`

Get the group-ridge penalty lambda2 used.

Usage

TIENETAug_Solver$get_lambda2()

Returns

Scalar numeric lambda2.

`TIENETAug_Solver$get_groups()`

Get the group ids (1-based, one per predictor).

Usage

TIENETAug_Solver$get_groups()

Returns

Integer vector of group ids.

`TIENETAug_Solver$get_num_groups()`

Get the number of disjoint groups.

Usage

TIENETAug_Solver$get_num_groups()

Returns

Integer group count.

`TIENETAug_Solver$clone()`

The objects of this class are cloneable with this method.

Usage

TIENETAug_Solver$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

H. Zou and T. Hastie, "Regularization and Variable Selection via the Elastic Net," J. R. Stat. Soc. Ser. B Stat. Methodol., vol. 67, no. 2, pp. 301-320, 2005.

B. Efron, T. Hastie, I. Johnstone, and R. Tibshirani, "Least Angle Regression," Ann. Statist., vol. 32, no. 2, pp. 407-499, 2004.

Examples

set.seed(1)
n <- 20; p <- 4
X <- matrix(rnorm(n * p), n, p)
D <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + rnorm(n)
groups <- c(1, 1, 2, 2)  # 1-based group id per predictor
solver <- TIENETAug_Solver$new(X, D, y, groups = groups,
                               options = tsolver_options(lambda2 = 0.1))
solver$execute_step(T_stop = 3)
solver$get_beta()

T-IENET Solver (native pathwise)

Description

Terminating Informed Elastic Net solver, native LARS homotopy on the group-ridge penalty (no augmented copies). The solver used internally by TRexGVSSelector for gvs_type = "IEN" with solver = "TIENET". Inherits all common methods from TSolver_Base.

Super class

TSolver_Base -> TIENET_Solver

Methods

Public methods

TIENET_Solver$new()
TIENET_Solver$get_lambda()
TIENET_Solver$get_lambda2()
TIENET_Solver$get_groups()
TIENET_Solver$get_num_groups()
TIENET_Solver$clone()

Inherited methods

`TIENET_Solver$new()`

Create a new TIENET_Solver.

Usage

TIENET_Solver$new(X, D, y, groups, options = tsolver_options())

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies (a multiple of ncol(X) columns when lambda2 > 0: one group-aligned layer per p).
y: Numeric response vector.
groups: Integer vector of 1-based group ids, one per predictor column of X (contiguous ids starting at 1).
options: Solver options from tsolver_options; this solver reads lambda2 (the group-ridge penalty, >= 0).

`TIENET_Solver$get_lambda()`

Get the regularization (lambda) path.

Usage

TIENET_Solver$get_lambda()

Returns

Numeric vector of lambda values, one per step.

`TIENET_Solver$get_lambda2()`

Get the group-ridge penalty lambda2 used.

Usage

TIENET_Solver$get_lambda2()

Returns

Scalar numeric lambda2.

`TIENET_Solver$get_groups()`

Get the group ids (1-based, one per predictor).

Usage

TIENET_Solver$get_groups()

Returns

Integer vector of group ids.

`TIENET_Solver$get_num_groups()`

Get the number of disjoint groups.

Usage

TIENET_Solver$get_num_groups()

Returns

Integer count of groups.

`TIENET_Solver$clone()`

The objects of this class are cloneable with this method.

Usage

TIENET_Solver$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

H. Zou and T. Hastie, "Regularization and Variable Selection via the Elastic Net," J. R. Stat. Soc. Ser. B Stat. Methodol., vol. 67, no. 2, pp. 301-320, 2005.

B. Efron, T. Hastie, I. Johnstone, and R. Tibshirani, "Least Angle Regression," Ann. Statist., vol. 32, no. 2, pp. 407-499, 2004.

Examples

set.seed(1)
n <- 20; p <- 4
X <- matrix(rnorm(n * p), n, p)
D <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + rnorm(n)
groups <- c(1, 1, 2, 2)  # 1-based group id per predictor
solver <- TIENET_Solver$new(X, D, y, groups = groups,
                            options = tsolver_options(lambda2 = 0.1))
solver$execute_step(T_stop = 3)
solver$get_beta()

T-TIKNET Solver

Description

Terminating Tikhonov Net solver: native LARS homotopy with a general quadratic penalty lambda2 * t(beta) K beta on the folded sums (a sparse PSD K = t(Gamma) Gamma, see trex_gamma_to_k). FOLDED dummy coupling only. The solver used internally by TRexTikhonovSelector for solver = "TIKNET". Inherits all common methods from TSolver_Base.

Super class

TSolver_Base -> TIKNET_Solver

Methods

Public methods

TIKNET_Solver$new()
TIKNET_Solver$get_lambda()
TIKNET_Solver$get_lambda2()
TIKNET_Solver$get_tikhonov_k()
TIKNET_Solver$clone()

Inherited methods

`TIKNET_Solver$new()`

Create a new TIKNET_Solver.

Usage

TIKNET_Solver$new(X, D, y, tikhonov_K, options = tsolver_options())

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies (a multiple of ncol(X) columns when lambda2 > 0: FOLDED layered convention).
y: Numeric response vector.
tikhonov_K: p x p PSD Tikhonov matrix: a Matrix::dgCMatrix or a dense matrix.
options: Solver options from tsolver_options; this solver reads lambda2 (the quadratic penalty weight, >= 0).

`TIKNET_Solver$get_lambda()`

Get the regularization (lambda) path.

Usage

TIKNET_Solver$get_lambda()

Returns

Numeric vector of lambda values, one per step.

`TIKNET_Solver$get_lambda2()`

Get the quadratic penalty weight lambda2 used.

Usage

TIKNET_Solver$get_lambda2()

Returns

Scalar numeric lambda2.

`TIKNET_Solver$get_tikhonov_k()`

The Tikhonov matrix K used (sparse dgCMatrix).

Usage

TIKNET_Solver$get_tikhonov_k()

Returns

A Matrix::dgCMatrix (p x p).

`TIKNET_Solver$clone()`

The objects of this class are cloneable with this method.

Usage

TIKNET_Solver$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

Y. Miche, M. van Heeswijk, P. Bas, O. Simula, and A. Lendasse, "TROP-ELM: A Double-Regularized ELM Using LARS and Tikhonov Regularization," Neurocomputing, vol. 74, pp. 2413-2421, 2011, doi: 10.1016/j.neucom.2010.12.042.

B. Efron, T. Hastie, I. Johnstone, and R. Tibshirani, "Least Angle Regression," Ann. Statist., vol. 32, no. 2, pp. 407-499, 2004.

Examples

set.seed(1)
n <- 20; p <- 4
X <- matrix(rnorm(n * p), n, p)
D <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + rnorm(n)
K <- diag(p)
solver <- TIKNET_Solver$new(X, D, y, tikhonov_K = K,
                            options = tsolver_options(lambda2 = 0.1))
solver$execute_step(T_stop = 3)
solver$get_beta()

T-LARS Solver

Description

Terminating Least Angle Regression (T-LARS) solver. Inherits all common methods from TSolver_Base.

Super class

TSolver_Base -> TLARS_Solver

Methods

Public methods

TLARS_Solver$new()
TLARS_Solver$get_lambda()
TLARS_Solver$get_kahan_refresh_interval()
TLARS_Solver$set_kahan_refresh_interval()
TLARS_Solver$clone()

Inherited methods

`TLARS_Solver$new()`

Create a new TLARS_Solver.

Usage

TLARS_Solver$new(X, D, y, options = tsolver_options())

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies.
y: Numeric response vector.
options: Solver options from tsolver_options (default: tsolver_options()).

`TLARS_Solver$get_lambda()`

Get the regularization (lambda) path.

Usage

TLARS_Solver$get_lambda()

Returns

Numeric vector of lambda values, one per step.

`TLARS_Solver$get_kahan_refresh_interval()`

Kahan refresh interval of the LARS-family solver (steps between exact refreshes of the compensated sums).

Usage

TLARS_Solver$get_kahan_refresh_interval()

Returns

Integer.

`TLARS_Solver$set_kahan_refresh_interval()`

Set the Kahan refresh interval.

Usage

TLARS_Solver$set_kahan_refresh_interval(interval)

Arguments

interval: Positive integer.

Returns

Invisibly returns self.

`TLARS_Solver$clone()`

The objects of this class are cloneable with this method.

Usage

TLARS_Solver$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

B. Efron, T. Hastie, I. Johnstone, and R. Tibshirani, "Least Angle Regression," Ann. Statist., vol. 32, no. 2, pp. 407-499, 2004.

Examples

set.seed(1)
n <- 20; p <- 5
X <- matrix(rnorm(n * p), n, p)
D <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + rnorm(n)
solver <- TLARS_Solver$new(X, D, y)
solver$execute_step(T_stop = 3)
solver$get_beta()
solver$get_actives()

T-LASSO Solver

Description

Terminating LASSO solver (T-LARS with variable removal). Inherits all common methods from TSolver_Base.

Super class

TSolver_Base -> TLASSO_Solver

Methods

Public methods

TLASSO_Solver$new()
TLASSO_Solver$get_num_removals()
TLASSO_Solver$get_cycling_ratio()
TLASSO_Solver$get_lambda()
TLASSO_Solver$clone()

Inherited methods

`TLASSO_Solver$new()`

Create a new TLASSO_Solver.

Usage

TLASSO_Solver$new(X, D, y, options = tsolver_options())

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies.
y: Numeric response vector.
options: Solver options from tsolver_options (default: tsolver_options()).

`TLASSO_Solver$get_num_removals()`

Get the number of coefficient removals.

Usage

TLASSO_Solver$get_num_removals()

Returns

Integer count of removals.

`TLASSO_Solver$get_cycling_ratio()`

Get the cycling ratio (removals / total steps).

Usage

TLASSO_Solver$get_cycling_ratio()

Returns

Scalar numeric cycling ratio.

`TLASSO_Solver$get_lambda()`

Get the regularization (lambda) path.

Usage

TLASSO_Solver$get_lambda()

Returns

Numeric vector of lambda values, one per step.

`TLASSO_Solver$clone()`

The objects of this class are cloneable with this method.

Usage

TLASSO_Solver$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

R. Tibshirani, "Regression Shrinkage and Selection via the Lasso," J. R. Stat. Soc. Ser. B Stat. Methodol., vol. 58, no. 1, pp. 267-288, 1996.

B. Efron, T. Hastie, I. Johnstone, and R. Tibshirani, "Least Angle Regression," Ann. Statist., vol. 32, no. 2, pp. 407-499, 2004.

M. R. Osborne, B. Presnell, and B. A. Turlach, "On the LASSO and Its Dual," J. Comput. Graph. Statist., vol. 9, no. 2, pp. 319-337, 2000.

Examples

set.seed(1)
n <- 20; p <- 5
X <- matrix(rnorm(n * p), n, p)
D <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + rnorm(n)
solver <- TLASSO_Solver$new(X, D, y)
solver$execute_step(T_stop = 3)
solver$get_beta()

T-MP Solver

Description

Terminating Matching Pursuit (T-MP) solver. Inherits all common methods from TSolver_Base.

Super class

TSolver_Base -> TMP_Solver

Methods

Public methods

TMP_Solver$new()
TMP_Solver$clone()

Inherited methods

`TMP_Solver$new()`

Create a new TMP_Solver.

Usage

TMP_Solver$new(X, D, y, options = tsolver_options())

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies.
y: Numeric response vector.
options: Solver options from tsolver_options (default: tsolver_options()).

`TMP_Solver$clone()`

The objects of this class are cloneable with this method.

Usage

TMP_Solver$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

S. G. Mallat and Z. Zhang, "Matching Pursuits with Time-Frequency Dictionaries," IEEE Trans. Signal Process., vol. 41, no. 12, pp. 3397-3415, 1993, doi: 10.1109/78.258082.

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.

Examples

set.seed(1)
n <- 20; p <- 5
X <- matrix(rnorm(n * p), n, p)
D <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + rnorm(n)
solver <- TMP_Solver$new(X, D, y)
solver$execute_step(T_stop = 3)
solver$get_beta()

T-NCGMP Solver

Description

Terminating Norm-Corrected Gradient Matching Pursuit (T-NCGMP) solver. Two variants are available: "line_search" (standard, 1-D projection) and "fully_corrective" (OMP-style least squares over the active set). Inherits all common methods from TSolver_Base.

Super class

TSolver_Base -> TNCGMP_Solver

Methods

Public methods

TNCGMP_Solver$new()
TNCGMP_Solver$clone()

Inherited methods

`TNCGMP_Solver$new()`

Create a new TNCGMP_Solver.

Usage

TNCGMP_Solver$new(X, D, y, options = tsolver_options())

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies.
y: Numeric response vector.
options: Solver options from tsolver_options; this solver reads ncgmp_variant: "line_search" (default) or "fully_corrective".

`TNCGMP_Solver$clone()`

The objects of this class are cloneable with this method.

Usage

TNCGMP_Solver$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

F. Locatello, R. Khanna, M. Tschannen, and M. Jaggi, "A Unified Optimization View on Generalized Matching Pursuit and Frank-Wolfe," in Proc. 20th Int. Conf. Artif. Intell. Statist. (AISTATS), JMLR: W&CP vol. 54, 2017.

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.

Examples

set.seed(1)
n <- 20; p <- 5
X <- matrix(rnorm(n * p), n, p)
D <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + rnorm(n)
solver <- TNCGMP_Solver$new(X, D, y,
                            options = tsolver_options(ncgmp_variant = "line_search"))
solver$execute_step(T_stop = 3)
solver$get_beta()

T-OMP Solver

Description

Terminating Orthogonal Matching Pursuit (T-OMP) solver. Inherits all common methods from TSolver_Base.

Super class

TSolver_Base -> TOMP_Solver

Methods

Public methods

TOMP_Solver$new()
TOMP_Solver$clone()

Inherited methods

`TOMP_Solver$new()`

Create a new TOMP_Solver.

Usage

TOMP_Solver$new(X, D, y, options = tsolver_options())

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies.
y: Numeric response vector.
options: Solver options from tsolver_options (default: tsolver_options()).

`TOMP_Solver$clone()`

The objects of this class are cloneable with this method.

Usage

TOMP_Solver$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

Y. C. Pati, R. Rezaiifar, and P. S. Krishnaprasad, "Orthogonal Matching Pursuit: Recursive Function Approximation with Applications to Wavelet Decomposition," in Proc. 27th Asilomar Conf. Signals, Syst., Comput., 1993, pp. 40-44.

J. A. Tropp, "Greed is Good: Algorithmic Results for Sparse Approximation," IEEE Trans. Inf. Theory, vol. 50, no. 10, pp. 2231-2242, 2004, doi: 10.1109/TIT.2004.834793.

T. Blumensath and M. E. Davies, "On the Difference Between Orthogonal Matching Pursuit and Orthogonal Least Squares," unpublished note, draft of March 29, 2007.

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.

Examples

set.seed(1)
n <- 20; p <- 5
X <- matrix(rnorm(n * p), n, p)
D <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + rnorm(n)
solver <- TOMP_Solver$new(X, D, y)
solver$execute_step(T_stop = 3)
solver$get_beta()

T-OLS Solver

Description

Terminating Orthogonal Least Squares (T-OLS) solver. Inherits all common methods from TSolver_Base.

Super class

TSolver_Base -> TOOLS_Solver

Methods

Public methods

TOOLS_Solver$new()
TOOLS_Solver$clone()

Inherited methods

`TOOLS_Solver$new()`

Create a new TOOLS_Solver.

Usage

TOOLS_Solver$new(X, D, y, options = tsolver_options())

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies.
y: Numeric response vector.
options: Solver options from tsolver_options (default: tsolver_options()).

`TOOLS_Solver$clone()`

The objects of this class are cloneable with this method.

Usage

TOOLS_Solver$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

S. Chen, S. A. Billings, and W. Luo, "Orthogonal Least Squares Methods and Their Application to Non-Linear System Identification," Int. J. Control, vol. 50, no. 5, pp. 1873-1896, 1989, doi: 10.1080/00207178908953472.

T. Blumensath and M. E. Davies, "On the Difference Between Orthogonal Matching Pursuit and Orthogonal Least Squares," unpublished note, draft of March 29, 2007.

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.

Examples

set.seed(1)
n <- 20; p <- 5
X <- matrix(rnorm(n * p), n, p)
D <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + rnorm(n)
solver <- TOOLS_Solver$new(X, D, y)
solver$execute_step(T_stop = 3)
solver$get_beta()

Biobank Screen T-Rex Selector

Description

Genomic biobank phenotype screening algorithm based on TRex architecture.

Methods

Public methods

TRexBiobankScreeningSelector$new()
TRexBiobankScreeningSelector$select()
TRexBiobankScreeningSelector$clone()

`TRexBiobankScreeningSelector$new()`

Create a new TRexBiobankScreeningSelector object.

Usage

TRexBiobankScreeningSelector$new(
  X,
  Y,
  tFDR = 0.1,
  seed = -1,
  verbose = TRUE,
  biobank_control = trex_biobank_control(),
  screen_control = trex_screen_control(),
  control = trex_control()
)

Arguments

X: Feature matrix (n x p), or an mmap_matrix opened "readwrite" (mapped directly, no copy; the screening's inner selectors normalize it in place per call and restore it).
Y: Response vector (1D) or matrix (2D).
tFDR: Target FDR level (default: 0.1).
seed: Random seed (default: -1).
verbose: Whether to print progress (default: TRUE).
biobank_control: A biobank control list from trex_biobank_control() (default: trex_biobank_control()).
screen_control: A screen control list from trex_screen_control() (default: trex_screen_control()).
control: A control list from trex_control() (default: trex_control()). The lloop_strategy field is forced to "STANDARD".

`TRexBiobankScreeningSelector$select()`

Run the Biobank Screening algorithm.

Usage

TRexBiobankScreeningSelector$select()

Returns

For a vector Y, a single per-phenotype record: a named list with phenotype_index, selected_indices, estimated_FDR, method_used, estimated_FDR_screen_ordinary, estimated_FDR_screen_bootstrap, selected_indices_screen_ordinary, selected_indices_screen_bootstrap, and used_fallback_trex (indices are 1-based). For a matrix Y, a plain list of such records, one per column, so res[[i]] has the same shape as the vector case. This mirrors the Python binding, which returns one result object (vector) or a list of them (matrix). A tidy summary table is one line away, e.g. do.call(rbind, lapply(res, function(r) as.data.frame(r[c("phenotype_index", "estimated_FDR", "method_used", "used_fallback_trex")]))).

`TRexBiobankScreeningSelector$clone()`

The objects of this class are cloneable with this method.

Usage

TRexBiobankScreeningSelector$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

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.

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.

Examples


data(Gauss_data)
X <- Gauss_data$X
y <- Gauss_data$y
sel <- TRexBiobankScreeningSelector$new(X, y, tFDR = 0.1, verbose = FALSE)
res <- sel$select()
res$selected_indices

Dependency-Aware T-Rex Selector (TRexDA)

Description

FDR-controlled variable selection algorithm for dependency scenarios.

Super class

TRexSelector -> TRexDASelector

Active bindings

rho_thresh: Optimal correlation threshold selected by the DA process.
rho_grid: The grid of correlation thresholds evaluated.
da_method_used: The integer code (or name mapped later) of the DA method used.
FDP_hat_array_BT: A 3D array of FDP estimates for BT method: (Variables x Thresholds x K).
Phi_array_BT: A 3D array of variables selected for BT method.
R_array_BT: A 3D array mapping original to clustered features for BT method.
cor_coef: The correlation coefficient of the dependency-aware dummy generation (AR1 / EQUI methods).

Methods

Public methods

TRexDASelector$new()
TRexDASelector$select()
TRexDASelector$clone()

Inherited methods

TRexSelector$restore()

`TRexDASelector$new()`

Create a new TRexDASelector object.

Usage

TRexDASelector$new(
  X,
  y,
  tFDR = 0.1,
  seed = -1,
  verbose = TRUE,
  da_control = trex_da_control(),
  control = trex_control()
)

Arguments

X: Feature matrix or MemoryMappedMatrix.
y: Response vector.
tFDR: Target FDR level (default: 0.1).
seed: Random seed (default: -1).
verbose: Whether to print progress (default: TRUE).
da_control: A DA control list from trex_da_control() (default: trex_da_control()).
control: A control list from trex_control() (default: trex_control()).

`TRexDASelector$select()`

Run the Dependency-Aware TRexSelector algorithm.

Usage

TRexDASelector$select()

`TRexDASelector$clone()`

The objects of this class are cloneable with this method.

Usage

TRexDASelector$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

J. Machkour, M. Muma, and D. P. Palomar, "High-Dimensional False Discovery Rate Control for Dependent Variables," Signal Process., vol. 234, Art. no. 109990, 2025, doi: 10.1016/j.sigpro.2025.109990.

J. Machkour, D. P. Palomar, and M. Muma, "FDR-Controlled Portfolio Optimization for Sparse Financial Index Tracking," in Proc. IEEE Int. Conf. Acoust., Speech, Signal Process. (ICASSP), 2025, doi: 10.1109/ICASSP49660.2025.10890629.

J. Machkour, M. Muma, and D. P. Palomar, "FDR-Controlled Sparse Index Tracking with Autoregressive Stock Dependency Models," in Proc. Eur. Signal Process. Conf. (EUSIPCO), 2024, pp. 2662-2666.

Examples


data(Gauss_data)
X <- Gauss_data$X
y <- Gauss_data$y
sel <- TRexDASelector$new(X, y, tFDR = 0.1, verbose = FALSE,
                          da_control = trex_da_control(da_method = "BT"))
sel$select()
sel$selected_indices

T-Rex Selector with Group Variable Selection (TRex GVS)

Description

FDR-controlled variable selection algorithm utilizing group-based structural augmentation.

Super class

TRexSelector -> TRexGVSSelector

Active bindings

lambda2_used: Lambda2 regularization term selected/applied.
lambda2_cv_diagnostics: Health record of the lambda_2 tuner of the last select(): a list with ran, seconds, n_profile_at_edge (lambda_2 values whose profiled lambda_1 optimum sat on a truncation edge; 0 is healthy), support_cap (-1 = disabled), dfmax_ratio (IEN tuner: the cv_dfmax_ratio it was called with; 0 when no IEN-geometry tuner ran), low_dimensional, and the boundary-pick guard fields: grid_index / grid_size (0-based position of the returned lambda_2 on the tuner's grid), at_grid_edge (the pick is the first or last grid point, so the grid boundary rather than a CV optimum), profile_at_edge (IEN tuner: the profiled lambda_1 optimum of the chosen lambda_2 sat on the truncation edge), profile_at_support_cap (that edge is the support cap; raise cv_dfmax_ratio to move it) and boundary_pick (at_grid_edge or profile_at_edge; the selector warned once and returned the pick unchanged).
gvs_type: The augmentation policy name used (e.g., "EN", "IEN").
max_clusters: The number of unique clusters dynamically formulated.
groups: Integer vector of length p giving the 1-based cluster label assigned to each variable (prior groups for Route 1, or the hierarchical-clustering assignment for Route 2). Enables computing cluster diagnostics (e.g. purity) on the R side.
group_labels: Optional human-readable cluster names (length max_clusters), or an empty character vector when none were supplied.
hc_method_used: The hierarchical-clustering linkage the GVS augmentation actually used.

Methods

Public methods

TRexGVSSelector$new()
TRexGVSSelector$select()
TRexGVSSelector$clone()

Inherited methods

TRexSelector$restore()

`TRexGVSSelector$new()`

Create a new TRexGVSSelector object.

Usage

TRexGVSSelector$new(
  X,
  y,
  tFDR = 0.1,
  seed = -1,
  verbose = TRUE,
  gvs_control = trex_gvs_control(),
  control = trex_control()
)

Arguments

X: Feature matrix or MemoryMappedMatrix.
y: Response vector.
tFDR: Target FDR level (default: 0.1).
seed: Random seed (default: -1).
verbose: Whether to print progress (default: TRUE).
gvs_control: A GVS control list from trex_gvs_control() (default: trex_gvs_control()). For gvs_type = "EN" the solver is derived from en_solver (TENET, TENET_AUG, or TCDENET) and the solver field in control is ignored (a warning is issued if it is set to a non-matching solver). For gvs_type = "IEN" the solver field selects the IEN solver: "TIENET" (default, native pathwise), "TIENET_AUG", or "TCDIENET".
control: A control list from trex_control() (default: trex_control()). For gvs_type = "EN" the solver field is overridden; for "IEN" it selects the IEN-family solver.

`TRexGVSSelector$select()`

Run the GVS algorithm.

Usage

TRexGVSSelector$select()

`TRexGVSSelector$clone()`

The objects of this class are cloneable with this method.

Usage

TRexGVSSelector$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

H. Zou and T. Hastie, "Regularization and Variable Selection via the Elastic Net," J. R. Stat. Soc. Ser. B Stat. Methodol., vol. 67, no. 2, pp. 301-320, 2005.

Examples


data(Gauss_data)
X <- Gauss_data$X
y <- Gauss_data$y
sel <- TRexGVSSelector$new(X, y, tFDR = 0.1, verbose = FALSE,
                           gvs_control = trex_gvs_control(gvs_type = "EN"))
sel$select()
sel$selected_indices

T-Rex Sparse PCA Selector

Description

Extracts sparse principal components under FDR control via T-Rex variable selection. For each of the M components, ordinary PCA identifies a PC-response direction, T-Rex selects a sparse active set at the target FDR, and a sparse loading vector is assembled (ActiveSet or Thresholded mode). Explained variance is adjusted for non-orthogonality via QR decomposition.

Active bindings

Z: Score matrix (n x M) from last select() call.
V: Loading matrix (p x M) from last select() call.
active_sets: List of M integer vectors (1-based) from last select() call.
adjusted_ev: Marginal adjusted explained variance per component (M-vector).
cumulative_ev: Cumulative explained variance percentage (M-vector).

Methods

Public methods

TRexSPCASelector$new()
TRexSPCASelector$select()
TRexSPCASelector$clone()

`TRexSPCASelector$new()`

Create a new TRexSPCASelector.

Usage

TRexSPCASelector$new(
  X,
  M,
  tFDR,
  control = trex_spca_control(),
  seed = -1L,
  verbose = FALSE
)

Arguments

X: Numeric matrix (n x p), or an mmap_matrix opened "readwrite". Stored by reference (no copy); centered in place during select() and restored on return.
M: Integer, number of sparse principal components to extract.
tFDR: Numeric, target false discovery rate in (0, 1).
control: A control list from trex_spca_control() (default: trex_spca_control()).
seed: Integer random seed. Use -1L (default) for non-deterministic (hardware entropy) behaviour.
verbose: Logical, whether to print progress (default: FALSE).

`TRexSPCASelector$select()`

Run T-Rex Sparse PCA selection.

Usage

TRexSPCASelector$select()

Returns

Invisible self for method chaining. Results accessible via active fields Z, V, active_sets, adjusted_ev, cumulative_ev.

`TRexSPCASelector$clone()`

The objects of this class are cloneable with this method.

Usage

TRexSPCASelector$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

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.

Examples


set.seed(1)
n <- 100; p <- 30
X <- matrix(rnorm(n * p), n, p)
sel <- TRexSPCASelector$new(X, M = 2, tFDR = 0.2,
                             control = trex_spca_control(K = 5))
sel$select()
sel$adjusted_ev
sel$active_sets

Screen T-Rex Selector

Description

Fast variable screening algorithm based on TRex architecture.

Super class

TRexSelector -> TRexScreeningSelector

Active bindings

estimated_FDR: Empirical FDR expectation bounds.
used_bootstrap: Employs bootstrapping.
confidence_level: Bounds the bootstrap estimates.
estimated_correlation: Covariance max value.
beta_mat: Complete variables parameter space.
dummy_betas: Dummy variables parameter space.

Methods

Public methods

TRexScreeningSelector$new()
TRexScreeningSelector$select()
TRexScreeningSelector$clone()

Inherited methods

TRexSelector$restore()

`TRexScreeningSelector$new()`

Create a new TRexScreeningSelector object.

Usage

TRexScreeningSelector$new(
  X,
  y,
  seed = -1,
  verbose = TRUE,
  screen_control = trex_screen_control(),
  control = trex_control()
)

Arguments

X: Feature matrix or MemoryMappedMatrix.
y: Response vector.
seed: Random seed (default: -1).
verbose: Whether to print progress (default: TRUE).
screen_control: A screen control list from trex_screen_control() (default: trex_screen_control()).
control: A control list from trex_control() (default: trex_control()). The lloop_strategy field is forced to "STANDARD".

`TRexScreeningSelector$select()`

Run the Screening algorithm.

Usage

TRexScreeningSelector$select()

`TRexScreeningSelector$clone()`

The objects of this class are cloneable with this method.

Usage

TRexScreeningSelector$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

Examples


data(Gauss_data)
X <- Gauss_data$X
y <- Gauss_data$y
sel <- TRexScreeningSelector$new(X, y, verbose = FALSE)
sel$select()
sel$selected_indices

T-Rex Selector

Description

FDR-controlled variable selection algorithm.

Active bindings

.ptr: Get internal pointer.
.ptr_X: internal proxy for data size
selected_var: Logical vector indicating which variables were selected.
selected_indices: Integer vector of selected 1-based indices.
v_thresh: The chosen voting threshold.
T_stop: Stopping time: the number of included dummies at which the T-loop stopped.
L: Calibrated dummy multiplier L (the selector uses L * p dummies).
voting_grid: Voting levels 0.5, 0.5 + 1/K, ..., 1 - eps that the selection searches.
fdp_hat_mat: Estimated false discovery proportion per T step (rows) and voting level (columns).
phi_mat: Relative occurrences of the original variables over the K random experiments after each T step (rows).
r_mat: Number of selected variables per T step (rows) and voting level (columns).
phi_prime: Calibrated relative occurrences used by the FDP estimate (length p), at most 1 and possibly negative.
x_means: computed means of the predictor variables
x_l2_norms: computed L2 norms of the scaled predictors
y_mean: computed mean of the response sequence
tFDR: The target FDR level.
K: The number of random experiments.
max_num_dummies: The maximum dummy multiplier of the L-loop.
max_T_stop: Whether the maximum T_stop rule is active.
stagnation_check: Whether the stagnation check is active.
num_selected: The number of selected variables.
num_dummies: The number of dummies used by the last select() (the L-loop's calibration).

Methods

Public methods

TRexSelector$new()
TRexSelector$restore()
TRexSelector$select()
TRexSelector$clone()

`TRexSelector$new()`

Create a new TRexSelector object.

Usage

TRexSelector$new(
  X,
  y,
  tFDR = 0.1,
  seed = -1,
  verbose = TRUE,
  control = trex_control()
)

Arguments

X: Feature matrix or MemoryMappedMatrix.
y: Response vector.
tFDR: Target FDR level (default: 0.1).
seed: Random seed (default: -1).
verbose: Whether to print progress (default: TRUE).
control: A control list from trex_control() (default: trex_control()).

`TRexSelector$restore()`

Give X back before select(): undo the in-place normalization applied at construction and release the buffer claim (idempotent; a no-op after select(), which restores X itself). A restored selector cannot run: select() then errors, construct a new one. Without it, an unselected selector gives X back only when it is garbage-collected.

Usage

TRexSelector$restore()

Returns

Invisibly returns self.

`TRexSelector$select()`

Run the TRexSelector algorithm.

Usage

TRexSelector$select()

Returns

invisible(self)

`TRexSelector$clone()`

The objects of this class are cloneable with this method.

Usage

TRexSelector$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

Examples


data(Gauss_data)
X <- Gauss_data$X
y <- Gauss_data$y
sel <- TRexSelector$new(X, y, tFDR = 0.1, verbose = FALSE)
sel$select()
sel$selected_indices

T-Rex Selector with a general Tikhonov penalty

Description

FDR-controlled variable selection with a Tikhonov penalty matrix K = t(Gamma) %*% Gamma driving the Tikhonov-net solvers (TCDTIKNET by default, or TIKNET). K = I collapses to the plain elastic net; a group-mean K reproduces the GVS-IEN penalty; banded / Laplacian K encode smoothness-informed selection; penalty_structure = "GROUP_CENTERING" builds the centering penalty from the dummy clustering. lambda_2 comes from the caller, a CV tuner, or the pilot rule (see trex_tikhonov_control). Dummies are cluster-aware and FOLDED-coupled by default.

Super class

TRexSelector -> TRexTikhonovSelector

Active bindings

lambda2_used: The lambda_2 actually used by the last select() run (user-supplied or CV-resolved; solver scale). -1 before select().
lambda2_cv_diagnostics: Health record of the lambda_2 tuner of the last select(): a list with ran (a tuner or the pilot ran), seconds, n_profile_at_edge (lambda_2 values whose profiled lambda_1 optimum sat on a truncation edge; 0 is healthy), support_cap (-1 = disabled), dfmax_ratio (IEN tuner: the cv_dfmax_ratio it was called with; 0 otherwise), low_dimensional, and the boundary-pick guard fields grid_index / grid_size, at_grid_edge, profile_at_edge, profile_at_support_cap and boundary_pick (see TRexGVSSelector; the CV methods warn once on a boundary pick and return it unchanged; the pilot rule leaves them at their defaults).
lambda2_pilot: Record of the lambda_2 pilot rule of the last select() (ran == FALSE when no pilot ran): the grid, the counts the pick was read off, the per-grid-point curves over the pilot stopping times (curve_majority, curve_soft; G x T matrices), the calibrated and group_majority counts, the 1-based index of the pick, the picked lambda2, max_selected, n_ties, the boundary flags at_lower_end / at_upper_end (widen the grid before trusting a boundary pick), the budget actually used (K_pilot, T_pilot, L_0) and the timings.

Methods

Public methods

TRexTikhonovSelector$new()
TRexTikhonovSelector$select()
TRexTikhonovSelector$clone()

Inherited methods

TRexSelector$restore()

`TRexTikhonovSelector$new()`

Create a new TRexTikhonovSelector object.

Usage

TRexTikhonovSelector$new(
  X,
  y,
  tFDR = 0.1,
  seed = -1,
  verbose = TRUE,
  tik_control,
  control = trex_control()
)

Arguments

X: Feature matrix or MemoryMappedMatrix.
y: Response vector.
tFDR: Target FDR level (default: 0.1).
seed: Random seed (default: -1).
verbose: Whether to print progress (default: TRUE).
tik_control: A Tikhonov control list from trex_tikhonov_control() (required — it carries the penalty matrix K).
control: A control list from trex_control() (default: trex_control()). The solver field selects the Tikhonov-family solver: "TCDTIKNET" (default; the neutral trex_control() default "TLARS" maps to it), or "TIKNET" (native pathwise); any other value warns and falls back to "TCDTIKNET".

`TRexTikhonovSelector$select()`

Run the Tikhonov T-Rex algorithm.

Usage

TRexTikhonovSelector$select()

`TRexTikhonovSelector$clone()`

The objects of this class are cloneable with this method.

Usage

TRexTikhonovSelector$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

A. J. Smola and R. Kondor, "Kernels and Regularization on Graphs," in Learning Theory and Kernel Machines (COLT/Kernel 2003), Lecture Notes in Artificial Intelligence vol. 2777, 2003, pp. 144-158.

F. R. K. Chung, Spectral Graph Theory. CBMS Regional Conference Series in Mathematics, no. 92. American Mathematical Society, 1997.

Examples


data(Gauss_data)
X <- Gauss_data$X
y <- Gauss_data$y
ctrl <- trex_tikhonov_control(tikhonov_K = diag(ncol(X)), lambda_2 = 0.5,
                              cluster_dummies = FALSE,
                              fold_dummy_coupling = FALSE)
sel <- TRexTikhonovSelector$new(X, y, tFDR = 0.1, verbose = FALSE,
                                tik_control = ctrl)
sel$select()
sel$selected_indices

T-Stagewise Solver

Description

Terminating Stagewise Regression solver. Inherits all common methods from TSolver_Base.

Super class

TSolver_Base -> TSTAGEWISE_Solver

Methods

Public methods

TSTAGEWISE_Solver$new()
TSTAGEWISE_Solver$get_num_removals()
TSTAGEWISE_Solver$get_cycling_ratio()
TSTAGEWISE_Solver$get_lambda()
TSTAGEWISE_Solver$clone()

Inherited methods

`TSTAGEWISE_Solver$new()`

Create a new TSTAGEWISE_Solver.

Usage

TSTAGEWISE_Solver$new(X, D, y, options = tsolver_options())

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies.
y: Numeric response vector.
options: Solver options from tsolver_options (default: tsolver_options()).

`TSTAGEWISE_Solver$get_num_removals()`

Get the number of coefficient removals.

Usage

TSTAGEWISE_Solver$get_num_removals()

Returns

Integer count of removals.

`TSTAGEWISE_Solver$get_cycling_ratio()`

Get the cycling ratio (removals / total steps).

Usage

TSTAGEWISE_Solver$get_cycling_ratio()

Returns

Scalar numeric cycling ratio.

`TSTAGEWISE_Solver$get_lambda()`

Get the regularization (lambda) path.

Usage

TSTAGEWISE_Solver$get_lambda()

Returns

Numeric vector of lambda values, one per step.

`TSTAGEWISE_Solver$clone()`

The objects of this class are cloneable with this method.

Usage

TSTAGEWISE_Solver$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

B. Efron, T. Hastie, I. Johnstone, and R. Tibshirani, "Least Angle Regression," Ann. Statist., vol. 32, no. 2, pp. 407-499, 2004.

T. Hastie, J. Taylor, R. Tibshirani, and G. Walther, "Forward Stagewise Regression and the Monotone Lasso," Electron. J. Stat., vol. 1, pp. 1-29, 2007, doi: 10.1214/07-EJS004.

R. J. Tibshirani, "A General Framework for Fast Stagewise Algorithms," J. Mach. Learn. Res., vol. 16, pp. 2543-2588, 2015.

Examples

set.seed(1)
n <- 20; p <- 5
X <- matrix(rnorm(n * p), n, p)
D <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + rnorm(n)
solver <- TSTAGEWISE_Solver$new(X, D, y)
solver$execute_step(T_stop = 3)
solver$get_beta()

T-Stepwise Solver

Description

Terminating Forward Stepwise Regression solver. Inherits all common methods from TSolver_Base.

Super class

TSolver_Base -> TSTEPWISE_Solver

Methods

Public methods

TSTEPWISE_Solver$new()
TSTEPWISE_Solver$get_lambda()
TSTEPWISE_Solver$clone()

Inherited methods

`TSTEPWISE_Solver$new()`

Create a new TSTEPWISE_Solver.

Usage

TSTEPWISE_Solver$new(X, D, y, options = tsolver_options())

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies.
y: Numeric response vector.
options: Solver options from tsolver_options (default: tsolver_options()).

`TSTEPWISE_Solver$get_lambda()`

Get the regularization (lambda) path.

Usage

TSTEPWISE_Solver$get_lambda()

Returns

Numeric vector of lambda values, one per step.

`TSTEPWISE_Solver$clone()`

The objects of this class are cloneable with this method.

Usage

TSTEPWISE_Solver$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

References

B. Efron, T. Hastie, I. Johnstone, and R. Tibshirani, "Least Angle Regression," Ann. Statist., vol. 32, no. 2, pp. 407-499, 2004.

Examples

set.seed(1)
n <- 20; p <- 5
X <- matrix(rnorm(n * p), n, p)
D <- matrix(rnorm(n * p), n, p)
y <- X[, 1] * 2 + rnorm(n)
solver <- TSTEPWISE_Solver$new(X, D, y)
solver$execute_step(T_stop = 3)
solver$get_beta()

Base T-Solver Class

Description

Abstract base class for all T-Solver R6 wrappers. Provides the common solver API backed by a Cpp TSolver_Base instance. Users should instantiate one of the concrete subclasses (TLARS_Solver, TLASSO_Solver, etc.) rather than this class directly.

In-place preprocessing (the writer/reader contract)

The solver works on the caller's memory without copying: the R matrices X and D (double storage; an integer matrix is coerced first, which is a copy) or the memory-mapped file behind an mmap_matrix. With normalize = TRUE or intercept = TRUE in tsolver_options the solver is a writer: it centers / scales the columns of X and D in place (the change is visible on the caller's matrix), keeps the statistics itself, and holds a claim on both until $restore() or garbage collection, both of which write X and D back ($restore() is idempotent and the fitted path stays available); constructing a second writer (T-solver or T-Rex selector) on a claimed matrix is an error, because a second in-place transformation moves the data by rounding. With both FALSE the solver is a reader: it runs as constructed and never writes. A pipeline with several solvers on one matrix pre-scales once in front (MLLpNormScaler) and constructs readers. $load() expects X and D in the state they were saved in: load into a reader on pre-scaled data, or into a writer constructed with the same options on the same data (it keeps the duty to write back). y is never written (the solver centers an internal copy).

Public fields

X: Numeric matrix of predictors, or an mmap_matrix.
D: Numeric matrix of dummies.
y: Numeric response vector.
ptr: External pointer to the underlying Cpp TSolver_Base object.

Methods

Public methods

TSolver_Base$new()
TSolver_Base$execute_step()
TSolver_Base$get_num_steps()
TSolver_Base$get_memory_bytes()
TSolver_Base$get_actions()
TSolver_Base$get_beta()
TSolver_Base$get_cp()
TSolver_Base$get_rss()
TSolver_Base$get_r2()
TSolver_Base$get_dof()
TSolver_Base$get_actives()
TSolver_Base$get_inactives()
TSolver_Base$get_intercept()
TSolver_Base$save()
TSolver_Base$load()
TSolver_Base$get_residuals()
TSolver_Base$get_beta_path()
TSolver_Base$get_cp_with_sigma()
TSolver_Base$solver_type_to_string()
TSolver_Base$get_dropped_indices()
TSolver_Base$get_active_predictor_indices()
TSolver_Base$get_active_dummy_indices()
TSolver_Base$get_num_actives()
TSolver_Base$get_dummy_start_index()
TSolver_Base$is_connected()
TSolver_Base$set_tolerance()
TSolver_Base$set_tie_seed()
TSolver_Base$set_num_threads()
TSolver_Base$get_num_threads()
TSolver_Base$set_exchangeable_tie()
TSolver_Base$get_warnings()
TSolver_Base$clear_warnings()
TSolver_Base$restore()
TSolver_Base$clone()

`TSolver_Base$new()`

Validate and store data fields. Called by every subclass initialize. Not intended for direct instantiation. The stored X and D are the matrices the C++ solver maps (no copy for double storage).

Usage

TSolver_Base$new(X, D, y)

Arguments

X: Numeric matrix of predictors, or mmap_matrix.
D: Numeric matrix of dummies.
y: Numeric response vector.

`TSolver_Base$execute_step()`

Execute solver step.

Usage

TSolver_Base$execute_step(T_stop = -1, early_stop = TRUE)

Arguments

T_stop: Integer stopping criterion; -1 runs until the early-stop condition is met.
early_stop: Logical; stop early when enough dummies are active.

Returns

Invisibly returns self for method chaining.

`TSolver_Base$get_num_steps()`

Get the number of steps executed so far.

Usage

TSolver_Base$get_num_steps()

Returns

Integer number of completed steps.

`TSolver_Base$get_memory_bytes()`

Heap bytes the solver holds: its copy of y, the residual, correlations, Cholesky factor, coefficient path, diagnostics and reserved capacity (the C++ memoryBytes()). X and D are borrowed and not counted, nor are the temporaries inside a step, so the peak of a step is higher.

Usage

TSolver_Base$get_memory_bytes()

Returns

Numeric (double) byte count.

`TSolver_Base$get_actions()`

Get the action path (variable additions and removals per step). The C++ solver already records the R lars convention: 1-based signed codes, +j for the addition and -j for the removal of variable j (dummies continue after the predictors).

Usage

TSolver_Base$get_actions(r_index = TRUE)

Arguments

r_index: Logical; if TRUE (default) the 1-based signed codes are returned as recorded. If FALSE the 0-based indices of the variables acted on are returned (abs(a) - 1); the sign is dropped there because a 0-based signed code cannot distinguish the addition from the removal of the first variable.

Returns

A list of integer vectors, one per step.

`TSolver_Base$get_beta()`

Get coefficient vector at a given step.

Usage

TSolver_Base$get_beta(step = -1)

Arguments

step: Integer step index; -1 returns the current/final step.

Returns

Numeric vector of coefficients.

`TSolver_Base$get_cp()`

Get Mallows Cp scores along the solution path.

Usage

TSolver_Base$get_cp()

Returns

Numeric vector of Cp scores, one per step.

`TSolver_Base$get_rss()`

Get residual sum of squares along the solution path.

Usage

TSolver_Base$get_rss()

Returns

Numeric vector of RSS values, one per step.

`TSolver_Base$get_r2()`

Get R-squared values along the solution path.

Usage

TSolver_Base$get_r2()

Returns

Numeric vector of R-squared values, one per step.

`TSolver_Base$get_dof()`

Get degrees of freedom along the solution path.

Usage

TSolver_Base$get_dof()

Returns

Numeric vector of degrees of freedom, one per step.

`TSolver_Base$get_actives()`

Get currently active variable indices.

Usage

TSolver_Base$get_actives(r_index = TRUE)

Arguments

r_index: Logical; if TRUE (default) indices are 1-based (R convention); if FALSE they are 0-based (Cpp convention).

Returns

Integer vector of active variable indices.

`TSolver_Base$get_inactives()`

Get currently inactive variable indices.

Usage

TSolver_Base$get_inactives(r_index = TRUE)

Arguments

r_index: Logical; if TRUE (default) indices are 1-based (R convention); if FALSE they are 0-based (Cpp convention).

Returns

Integer vector of inactive variable indices.

`TSolver_Base$get_intercept()`

Get the fitted intercept at a given step.

Usage

TSolver_Base$get_intercept(step = -1)

Arguments

step: Integer step index; -1 returns the current/final step.

Returns

Scalar numeric intercept.

`TSolver_Base$save()`

Serialize the solver state to a binary file.

Usage

TSolver_Base$save(filename)

Arguments

filename: Character; path to the output file.

Returns

Invisibly returns self.

`TSolver_Base$load()`

Restore the solver state from a binary file created by $save(). The loaded solver expects X and D in the state they were saved in and is a reader (it never writes).

Usage

TSolver_Base$load(filename)

Arguments

filename: Character; path to the input file.

Returns

Invisibly returns self.

`TSolver_Base$get_residuals()`

Residual vector at the current step.

Usage

TSolver_Base$get_residuals()

Returns

Numeric vector of length n.

`TSolver_Base$get_beta_path()`

Coefficient path: one column per step including the all-zero start (column 1), predictors first, dummies from get_dummy_start_index() on; the same layout as Python's getBetaPath().

Usage

TSolver_Base$get_beta_path()

Returns

Numeric matrix ((p + num_dummies) x (steps + 1)).

`TSolver_Base$get_cp_with_sigma()`

Mallows' Cp along the path with a supplied noise variance.

Usage

TSolver_Base$get_cp_with_sigma(sigma_hat_sq)

Arguments

sigma_hat_sq: Positive numeric, the noise variance estimate.

Returns

Numeric vector, one per step.

`TSolver_Base$solver_type_to_string()`

Name of the underlying solver type (e.g. "TLARS").

Usage

TSolver_Base$solver_type_to_string()

Returns

Character scalar.

`TSolver_Base$get_dropped_indices()`

Variables dropped during the path (1-based, predictors and dummies alike).

Usage

TSolver_Base$get_dropped_indices()

Returns

Integer vector.

`TSolver_Base$get_active_predictor_indices()`

Active predictor indices (1-based, dummies excluded).

Usage

TSolver_Base$get_active_predictor_indices()

Returns

Integer vector.

`TSolver_Base$get_active_dummy_indices()`

Active dummy indices (1-based within the dummy block).

Usage

TSolver_Base$get_active_dummy_indices()

Returns

Integer vector.

`TSolver_Base$get_num_actives()`

Number of active variables (predictors and dummies).

Usage

TSolver_Base$get_num_actives()

Returns

Integer.

`TSolver_Base$get_dummy_start_index()`

1-based column at which the dummies start in the merged (predictors, dummies) index space, i.e. p + 1.

Usage

TSolver_Base$get_dummy_start_index()

Returns

Integer.

`TSolver_Base$is_connected()`

Whether the solver is connected to its data views.

Usage

TSolver_Base$is_connected()

Returns

Logical.

`TSolver_Base$set_tolerance()`

Set the numerical tolerance of the internal comparisons.

Usage

TSolver_Base$set_tolerance(tol)

Arguments

tol: Positive numeric.

Returns

Invisibly returns self.

`TSolver_Base$set_tie_seed()`

Seed the tie-break engine.

Usage

TSolver_Base$set_tie_seed(seed)

Arguments

seed: Non-negative integer.

Returns

Invisibly returns self.

`TSolver_Base$set_num_threads()`

Set the thread budget of the solver's own passes over the design (tsolver_options(n_threads = )): 1 serial, at least 1.

Usage

TSolver_Base$set_num_threads(n_threads)

Arguments

n_threads: Non-negative integer.

Returns

Invisibly returns self.

`TSolver_Base$get_num_threads()`

The resolved thread budget of the solver's own passes.

Usage

TSolver_Base$get_num_threads()

Returns

Integer, at least 1.

`TSolver_Base$set_exchangeable_tie()`

Exchangeable-tie band for the greedy solvers (TOMP / TAFS families); alpha <= 0 turns it off.

Usage

TSolver_Base$set_exchangeable_tie(alpha, floor = 0.5)

Arguments

alpha: Band width in units of the ranking-noise sd.
floor: Minimum |correlation| of a tie candidate (default 0.5).

Returns

Invisibly returns self.

`TSolver_Base$get_warnings()`

Warnings recorded by the solver (dropped columns, the already-preprocessed input, collinear rejections, ...).

Usage

TSolver_Base$get_warnings()

Returns

Character vector.

`TSolver_Base$clear_warnings()`

Clear the recorded warnings.

Usage

TSolver_Base$clear_warnings()

Returns

Invisibly returns self.

`TSolver_Base$restore()`

Undo the in-place centering / scaling a writer solver applied to X and D at construction and release its claim on them, so that another writer may take the matrices. The solver's fitted path stays available. y is not modified. No-op for a reader (normalize = FALSE, intercept = FALSE).

Usage

TSolver_Base$restore()

Returns

Invisibly returns self.

`TSolver_Base$clone()`

The objects of this class are cloneable with this method.

Usage

TSolver_Base$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples

# TSolver_Base is abstract; use a concrete subclass instead, e.g.:
# solver <- TLARS_Solver$new(X, D, y)

Extract or assign blocks in an mmap_matrix

Description

Extract or assign blocks in an mmap_matrix

Usage

## S3 method for class 'mmap_matrix'
x[i, j, ..., drop = FALSE]

Arguments

x

mmap_matrix object

i

row indices

j

column indices

...

unused arguments

drop

logical. If TRUE the result is coerced to the lowest possible dimension (not supported).

Value

For extraction: a matrix block. For assignment: x invisibly.

Examples


mat <- matrix(as.double(1:20), nrow = 4, ncol = 5)
f <- tempfile(fileext = ".bin")
on.exit(unlink(f), add = TRUE)
mem_matrix_from(mat, f)
mm <- mem_matrix(f, rows = 4, cols = 5)
mm[1:2, 1:3]
mm[2, 3] <- 99.0
mm[1:2, 1:3] <- matrix(as.double(1:6), nrow = 2, ncol = 3)

Get Zero-Copy View as Numeric Vector (Block)

Description

Get Zero-Copy View as Numeric Vector (Block)

Usage

## S3 method for class 'mmap_matrix'
as.matrix(x, ...)

Arguments

x

mmap_matrix object

...

extra arguments including row_range and col_range

Value

Numeric matrix (copied)

Examples


mat <- matrix(as.double(1:20), nrow = 4, ncol = 5)
f <- tempfile(fileext = ".bin")
on.exit(unlink(f), add = TRUE)
mem_matrix_from(mat, f)
mm <- mem_matrix(f, rows = 4, cols = 5)
as.matrix(mm)

Get mmap_matrix dimensions

Description

Get mmap_matrix dimensions

Usage

## S3 method for class 'mmap_matrix'
dim(x)

Arguments

x

mmap_matrix object

Value

an integer vector of length 2

Examples


mat <- matrix(as.double(1:20), nrow = 4, ncol = 5)
f <- tempfile(fileext = ".bin")
on.exit(unlink(f), add = TRUE)
mem_matrix_from(mat, f)
mm <- mem_matrix(f, rows = 4, cols = 5)
dim(mm)

Memory-Mapped Matrix Object

Description

S3 object wrapping an external pointer to a Cpp MemoryMappedMatrix.

Usage

mem_matrix(filename, rows, cols, mode = "readwrite")

Arguments

filename

Path to binary mmap file

rows

Number of rows

cols

Number of columns

mode

Access mode: 'readonly' or 'readwrite' (default)

Value

Object of classes MemoryMappedMatrix and mmap_matrix (S3 XPtr wrapper)

References

Examples


mat <- matrix(as.double(1:20), nrow = 4, ncol = 5)
f <- tempfile(fileext = ".bin")
on.exit(unlink(f), add = TRUE)
mem_matrix_from(mat, f)
mm <- mem_matrix(f, rows = 4, cols = 5)

Convert R Matrix to System Memory Mapped Matrix

Description

Writes a numeric matrix to a binary memory-mapped file on disk and returns a MemoryMappedMatrix handle pointing to it.

Usage

mem_matrix_from(mat, filename)

Arguments

mat

A numeric matrix.

filename

String destination file path.

Value

A MemoryMappedMatrix / mmap_matrix object backed by filename.

References

Examples


mat <- matrix(as.double(1:20), nrow = 4, ncol = 5)
f <- tempfile(fileext = ".bin")
on.exit(unlink(f), add = TRUE)
mm <- mem_matrix_from(mat, f)
print(mm)

Agglomerative Clustering

Description

Performs hierarchical agglomerative clustering on a numeric matrix.

Usage

ml_agglomerative_cluster(
  data,
  method = ml_linkage_method$Ward,
  metric = ml_distance_metric$Euclidean,
  use_mmap = FALSE,
  verbose = FALSE,
  n_threads = NULL
)

Arguments

data

A numeric matrix, or an mmap_matrix created by mem_matrix_from.

method

A value from ml_linkage_method (e.g. ml_linkage_method$Ward).

metric

A value from ml_distance_metric (e.g. ml_distance_metric$Euclidean). Default is Euclidean.

use_mmap

Whether to use memory mapping files for intermediate storage. Default is FALSE. Ignored when data is already an mmap_matrix (always TRUE).

verbose

Whether the backend prints its allocation line (the size of the distance matrix in RAM or in the memory-mapped file). Default is FALSE.

n_threads

Integer, the thread budget of the distance loops (NULL, the default: the library's default budget, trex_get_num_threads(), initially 1).

Value

A numeric matrix representing the computed hierarchical linkage.

References

R. Sibson, "SLINK: An Optimally Efficient Algorithm for the Single-Link Cluster Method," Comput. J., vol. 16, no. 1, pp. 30-34, 1973.

J.-P. Benzécri, "Construction d'une classification ascendante hiérarchique par la recherche en chaîne des voisins réciproques," Les Cahiers de l'Analyse des Données, vol. 7, no. 2, pp. 209-218, 1982.

J. Juan, "Programme de classification hiérarchique par l'algorithme de la recherche en chaîne des voisins réciproques," Les Cahiers de l'Analyse des Données, vol. 7, no. 2, pp. 219-225, 1982.

G. N. Lance and W. T. Williams, "A General Theory of Classificatory Sorting Strategies: I. Hierarchical Systems," Comput. J., vol. 9, pp. 373-380, 1967.

D. Müllner, "Modern Hierarchical, Agglomerative Clustering Algorithms," arXiv:1109.2378, 2011.

F. Murtagh and P. Contreras, "Algorithms for Hierarchical Clustering: An Overview," Wiley Interdiscip. Rev. Data Min. Knowl. Discov., vol. 2, no. 1, pp. 86-97, 2012, doi: 10.1002/widm.53.

F. Murtagh and P. Contreras, "Algorithms for Hierarchical Clustering: An Overview, II," Wiley Interdiscip. Rev. Data Min. Knowl. Discov., vol. 7, no. 6, Art. no. e1219, 2017, doi: 10.1002/widm.1219.

Examples

set.seed(1)
data <- matrix(rnorm(30), nrow = 10)
ml_agglomerative_cluster(data, method = ml_linkage_method$Ward)

Cut Hierarchical Linkage Matrix

Description

Flatten the dendrogram clustering results based on the number of requested groups.

Usage

ml_cut_tree(linkage, num_orig_objs, num_clusters)

Arguments

linkage

A numeric matrix representing linkage, generated by ml_agglomerative_cluster.

num_orig_objs

Original number of observations data rows.

num_clusters

Target flat group capacity.

Value

An integer vector mapping observation indexes to cluster arrays.

Examples

set.seed(1)
data <- matrix(rnorm(30), nrow = 10)
linkage <- ml_agglomerative_cluster(data, method = ml_linkage_method$Ward)
ml_cut_tree(linkage, num_orig_objs = 10, num_clusters = 3)

Distance Metrics

Description

Enumeration of supported distance metrics for hierarchical clustering. Supported metrics include: - Euclidean: Standard Euclidean distance: codes as 0. - Correlation: Correlation distance (1 - correlation): codes as 1. - Manhattan: Manhattan (L1) distance: codes as 2. - Correlation_LSH_Filter: Correlation distance with LSH-based filtering: codes as 3. - Correlation_LSH_Approx: Approximate correlation distance using LSH: codes as 4.

Usage

ml_distance_metric

References

M. S. Charikar, "Similarity Estimation Techniques from Rounding Algorithms," in Proc. ACM Symp. Theory Comput. (STOC), 2002.

P. Indyk and R. Motwani, "Approximate Nearest Neighbors: Towards Removing the Curse of Dimensionality," in Proc. 30th ACM Symp. Theory Comput. (STOC), 1998, pp. 604-613.

P. Li, T. J. Hastie, and K. W. Church, "Very Sparse Random Projections," in Proc. ACM SIGKDD Int. Conf. Knowl. Discovery Data Mining (KDD), 2006.

Examples

ml_distance_metric$Euclidean
ml_distance_metric$Correlation

Linkage Methods

Description

Enumeration of supported hierarchical clustering linkage methods. Supported methods include: - Ward: Ward's minimum variance method: codes as 0. - Average (UPGMA): Average linkage: codes as 1. - Complete: Complete linkage: codes as 2. - Single: Single linkage: codes as 3. - WPGMA: Weighted pair group method with arithmetic mean: codes as 4. - Median: Median linkage: codes as 5. - Centroid: Centroid linkage: codes as 6.

Usage

ml_linkage_method

References

G. N. Lance and W. T. Williams, "A General Theory of Classificatory Sorting Strategies: I. Hierarchical Systems," Comput. J., vol. 9, pp. 373-380, 1967.

D. Müllner, "Modern Hierarchical, Agglomerative Clustering Algorithms," arXiv:1109.2378, 2011.

Examples

ml_linkage_method$Ward
ml_linkage_method$Average

Print mmap_matrix

Description

Print mmap_matrix

Usage

## S3 method for class 'mmap_matrix'
print(x, ...)

Arguments

x

mmap_matrix object

...

arguments passed to other methods

Value

invisibly returns x

Examples


mat <- matrix(as.double(1:20), nrow = 4, ncol = 5)
f <- tempfile(fileext = ".bin")
on.exit(unlink(f), add = TRUE)
mem_matrix_from(mat, f)
mm <- mem_matrix(f, rows = 4, cols = 5)
print(mm)

TRex Biobank Control Parameters

Description

Build a control list for the FDR acceptance bounds in TRexBiobankScreeningSelector. The target FDR level (tFDR) is a separate top-level parameter of the selector constructor.

Usage

trex_biobank_control(lower_bound_FDR = 0.05, upper_bound_FDR = 0.15)

Arguments

lower_bound_FDR

Lower bound of the acceptable estimated FDR range (default: 0.05).

upper_bound_FDR

Upper bound of the acceptable estimated FDR range (default: 0.15).

Value

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 Control Parameters

Description

Build a control list for TRex selector algorithms.

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 = 0,
  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"; the Tikhonov-family names "TCDTIKNET" and "TIKNET" need a penalty matrix and are dispatchable only inside TRexTikhonovSelector. The plain selector rejects both families with an informative error.

K

Number of random experiments (default: 20).

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

Steps before stagnation trigger (default: 5).

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

Use out-of-core memory mapping (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

Maximum dummy features multiplier (default: 10).

use_max_T_stop

Whether to bound max T_stop (default: TRUE).

opt_threshold

Optimization threshold (default: 0.75).

lloop_strategy

L-loop strategy: "SKIPL", "STANDARD", "HCONCAT", "PERMUTATION", "PERMUTATION_SEEDED", or "SEEDED" (default: "STANDARD", as in C++ and Python). The SEEDED variants re-derive dummies from the seed at every step and store nothing: "SEEDED" is the storage-free twin of "STANDARD" (fresh dummies at every L step, bit-identical to "STANDARD" for the same seed) and "PERMUTATION_SEEDED" the storage-free twin of "PERMUTATION".

tol

Tolerance for solver algorithms (default: 1e-6).

lambda2

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

rho_afs

AFS hyperparameter (default: 0.3).

ncgmp_variant

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

exch_tie_alpha

Exchangeable-tie band width for greedy solvers (TOMP/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. Recommended for greedy solvers under trex+DA: 0.25. 0 (default) turns the feature off (exact legacy behavior; ignored by path solvers).

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.

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.

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.

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.

cd_max_sweeps

Maximum coordinate sweeps per CCD subproblem (default: 0 = keep the solver's internal default). Ignored by the non-CCD solvers.

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.

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.

Value

A named list suitable for passing to TRex selector constructors.

Note

Seed recommendation for Monte Carlo FDR simulations: always pass seed = -1 (the default) to TRexSelector$new() or any other selector constructor when running repeated trials. A fixed integer seed causes every trial to draw K per-experiment dummy seeds as mix_seed(fixed, 0), mix_seed(fixed, 1), ... — deterministic but structurally correlated across trials — which can inflate the empirical FDR in a sweep. With seed = -1 each of the K experiments independently draws hardware entropy via std::random_device, matching the behaviour of the standalone C++ demo.

Examples

trex_control()
trex_control(solver = "TLASSO", K = 10)
trex_control(scaling_mode = "NONE")  # user-managed centering and scaling

TRex DA Control Parameters

Description

Build a control list for the dependency-aware dummy generation in TRexDASelector.

Usage

trex_da_control(
  da_method = "BT",
  cor_coef = -2,
  rho_thr_DA = 0.02,
  hc_linkage = "Single",
  hc_grid_length = 0,
  prior_groups = NULL
)

Arguments

da_method

Dependency estimation method: "BT", "AR1", "EQUI", "NN" (default: "BT"). "NN" is a nearest-neighbour correlation-threshold sweep (BT-style) over a rho grid of length hc_grid_length.

cor_coef

Correlation coefficient for AR1/EQUI. -2.0 triggers auto-estimation (default: -2.0).

rho_thr_DA

Threshold below which equi-correlation is skipped (default: 0.02).

hc_linkage

Hierarchical clustering linkage: "Single", "Complete", "Average", "WPGMA", "Ward" (default: "Single").

hc_grid_length

Number of grid points for BT/NN calibration. 0 (default) lets the core auto-select min(20, p).

prior_groups

Optional prior grouping constraints: a list of integer vectors, each of length p, giving non-negative group labels per variable. When supplied (non-NULL, non-empty), the prior-groups dependency-aware path is used and da_method is ignored: the finest common refinement of all supplied levels acts as a hard merge constraint, hierarchical clustering (hc_linkage, correlation distance) runs within each constraint group, and the calibration rho grid (length 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: NULL).

Value

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)))

TRex Dummy Variable Distribution

Description

Build a distribution specification for the dummy variables injected by the T-Rex Selector. Pass the result to the dummy_distribution argument of trex_control.

Usage

trex_dummy_distribution(
  type = "Normal",
  a = NULL,
  df = NULL,
  location = NULL,
  scale = NULL,
  b = NULL,
  c = NULL,
  dim = NULL,
  s = NULL
)

Arguments

type

Character string naming the distribution. One of: "Normal", "Uniform", "Rademacher", "StudentT", "Laplace", "Gumbel", "Triangle", "UniformSphere", "Mammen", "ConstrainedSparseRademacher", "Logistic". Defaults to "Normal".

a

Scale / upper-bound parameter (used by "Uniform").

df

Degrees of freedom (used by "StudentT").

location

Location parameter (used by "Laplace", "Gumbel", "Logistic").

scale

Scale parameter (used by "Laplace", "Gumbel", "Logistic").

b

Upper vertex of the triangle (used by "Triangle").

c

Right boundary of the triangle (used by "Triangle").

dim

Dimension of the sphere (used by "UniformSphere").

s

Sparsity parameter (used by "ConstrainedSparseRademacher").

Value

A named list describing the dummy distribution, for use in trex_control.

References

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)

Compute False Discovery Proportion (FDP) using index sets

Description

Compute False Discovery Proportion (FDP) using index sets

Usage

trex_fdp(selected_indices, true_support)

Arguments

selected_indices

Integer vector of selected indices.

true_support

Integer vector of true active indices.

Value

Numeric FDP value.

Examples

trex_fdp(c(1L, 3L, 5L), c(1L, 2L, 3L))

Compute False Discovery Proportion (FDP) using dense vectors

Description

Compute False Discovery Proportion (FDP) using dense vectors

Usage

trex_fdp_dense(beta_hat, beta, eps = 1e-15)

Arguments

beta_hat

Numeric vector of estimated coefficients.

beta

Numeric vector of true coefficients.

eps

Numeric threshold for counting non-zeros (default: 1e-15).

Value

Numeric FDP value.

Examples

trex_fdp_dense(c(1.5, 0, 0.8, 0, 0), c(2.0, 0, 1.0, 0, 0))

Build a Tikhonov penalty matrix K from an operator Gamma

Description

Computes K = t(Gamma) %*% Gamma (pruned and compressed) for use as tikhonov_K in trex_tikhonov_control. For example, a first-difference Gamma yields the smoothness-encoding graph Laplacian of a chain.

Usage

trex_gamma_to_k(gamma)

Arguments

gamma

Regularization operator (m x p): a base matrix or a sparse Matrix::dgCMatrix.

Value

A sparse Matrix::dgCMatrix (p x p). Requires the Matrix package (Suggests) for the sparse return class.

Examples

# First-difference operator over 5 variables -> chain Laplacian
if (requireNamespace("Matrix", quietly = TRUE)) {
  p <- 5
  gamma <- diff(diag(p))
  K <- trex_gamma_to_k(gamma)
}

The library's thread budget

Description

The library is single-threaded by default. Every parallel region of the C++ backend runs on an explicit budget: a selector's random experiments and its inner kernels on trex_control( max_outer_threads, max_inner_threads), a T-solver on tsolver_options(n_threads), and every method without an option of its own (the scalers, the clustering, the ML regressions, the dummy and data generators, trex_normalize_design) on the library's default budget, which starts at 1. trex_get_num_threads() reads that default budget and trex_set_num_threads() sets it for this session; the n_threads argument of those methods overrides it per object. trex_get_max_threads() reports the threads OpenMP can run on this machine (1 in a build without OpenMP), an upper bound for a budget.

Usage

trex_get_num_threads()

trex_get_max_threads()

trex_set_num_threads(n)

Arguments

n

Positive integer, the default thread budget.

Value

trex_get_num_threads(), trex_get_max_threads(): an integer. trex_set_num_threads(): invisibly, the previous budget.

Examples

trex_get_num_threads()   # 1
old <- trex_set_num_threads(min(2L, trex_get_max_threads()))
trex_get_num_threads()
trex_set_num_threads(old)

TRex GVS Control Parameters

Description

Build a control list for group variable selection augmentation policy in TRexGVSSelector. The solver is determined automatically from gvs_type: "EN" selects the T-Elastic-Net solver via en_solver — TENET (default), with TENET_AUG and TCDENET as optional variants; "IEN" honors an IEN-family solver field in trex_control — TIENET (default, native pathwise), with TIENET_AUG and TCDIENET as optional variants. For gvs_type = "EN" the solver field is ignored.

Usage

trex_gvs_control(
  gvs_type = "EN",
  corr_max = 0.5,
  hc_linkage = "Single",
  lambda_2 = -1,
  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
)

Arguments

gvs_type

Augmentation policy: "EN" (Elastic Net) or "IEN" (Informed Elastic Net) (default: "EN").

corr_max

Maximum pairwise correlation for automatic cluster formation (default: 0.5).

hc_linkage

Hierarchical clustering linkage: "Single", "Complete", "Average", "WPGMA" (default: "Single").

lambda_2

L2 penalty weight for group structure, in LARS units. A negative value (default -1) triggers automatic determination via the method selected by lambda2_method; 0 is the degenerate pure T-LASSO case (no ridge); a positive value is used as-is.

lambda2_method

Auto-determination strategy for lambda_2 when lambda_2 < 0. NULL (default) resolves by track: "CV_1SE_CCD" for gvs_type = "EN" and "CV_1SE_IEN_CCD" for 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 "CV_1SE_CCD" on the IEN track also runs the IEN tuner. Explicit choices: EN-shaped ridge CV "CV_1SE_CCD", "CV_MIN_CCD", "CV_1SE_SVD", "CV_MIN_SVD" (allowed on both tracks); IEN-geometry "CV_1SE_IEN_CCD", "CV_MIN_IEN_CCD", "CV_1SE_TIK_SVD", "CV_MIN_TIK_SVD" (require gvs_type = "IEN" — they consume the group structure).

en_solver

Elastic Net solver variant for gvs_type = "EN": "TENET" (default, Gram-based), "TENET_AUG" (row-augmented LASSO), or "TCDENET" (coordinate descent; exact fixed-lambda1 elastic-net minimizers per dummy crossing). All solve the same EN problem and select the same variables up to path-vs-minimizer differences; the switch exists to validate solver equivalence, not to choose a LARS vs LASSO path (for that, see tenet_aug_use_lars).

tenet_aug_use_lars

Logical. When en_solver = "TENET_AUG", run the augmented system with a pure-LARS inner path that never drops variables (TRUE) instead of the default LASSO inner path that can (FALSE, default). This is the LARS-vs-LASSO distinction. Ignored for en_solver = "TENET".

groups

Integer vector of manually specified group assignments (1-based, default: NULL).

cv_n_folds

Number of folds for the k-fold cross-validation used by the CV lambda2_method paths (default: 10, matching cv.glmnet). Ignored when lambda_2 >= 0.

cv_n_lambda

Number of points on the geometric lambda grid searched by the CV auto-computation of lambda_2 (default: 1000). Ignored when lambda_2 >= 0.

cv_n_lambda1

IEN-geometry coordinate-descent tuners ("CV_1SE_IEN_CCD", "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 lambda_2 >= 0.

cv_n_lambda2

IEN-geometry coordinate-descent tuners only: points on the lambda_2 grid (default: 100). Ignored by the other rules and when lambda_2 >= 0.

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 floor(cv_dfmax_ratio * n_train) coefficients are nonzero (default: 0.8). A value <= 0 disables the cap. Larger values allow larger supports at a higher tuner cost. Must be finite. Ignored by the other rules and when lambda_2 >= 0.

cv_seed

Seed for the deterministic fold-permutation RNG used by the CV lambda2_method paths. -1 (default) derives it from the T-Rex seed (deterministic when seed >= 0, hardware entropy when seed < 0); a value >= 0 overrides seed for CV folds only, giving per-trial fold reproducibility.

Value

A named list for use in TRexGVSSelector.

Examples

trex_gvs_control()
trex_gvs_control(gvs_type = "IEN", corr_max = 0.3)

Apply the T-Rex data normalization to a design

Description

The selectors' own preprocessing as a user-callable helper: the same code path a selector runs at construction for the given scaling_mode. Use it to pre-normalize a design and then run a selector with trex_control(scaling_mode = "NONE") (the selection is identical to running the raw design under "L2"), to inspect the centering and scaling parameters, or to validate a design before a long run. The inputs are copied and left untouched.

Usage

trex_normalize_design(
  X,
  y,
  scaling_mode = c("L2", "ZSCORE", "NONE"),
  eps = 1e-06,
  n_threads = NULL
)

Arguments

X

Numeric design matrix (n x p).

y

Numeric response vector (length n).

scaling_mode

One of "L2" (default; center, divide by the column L2 norm), "ZSCORE" (center, divide by the sample SD) or "NONE" (copies equal the inputs; identity parameters).

eps

Dead-column threshold on the working L2 norm (default 1e-6, the selectors' default solver tolerance).

n_threads

Integer, the thread budget of the column passes (NULL, the default: the library's default budget, trex_get_num_threads(), initially 1).

Details

Errors on a non-finite entry or a dead column (constant under "L2" / "ZSCORE", all-zero under "NONE"), naming the column (0-based, as reported by the C++ core).

Value

A list with X and y (the normalized copies), X_means, X_scales (the per-column divisors: L2 norms for "L2", sample SDs for "ZSCORE", ones for "NONE") and y_mean.

Examples

set.seed(1)
X <- matrix(rnorm(200), 40, 5)
y <- X[, 1] + rnorm(40)
d <- trex_normalize_design(X, y)
colMeans(d$X)            # ~ 0
sqrt(colSums(d$X^2))     # 1

Compute Precision using index sets

Description

Compute Precision using index sets

Usage

trex_precision(selected_indices, true_support)

Arguments

selected_indices

Integer vector of selected indices.

true_support

Integer vector of true active indices.

Value

Numeric precision value.

Examples

trex_precision(c(1L, 3L, 5L), c(1L, 2L, 3L))

Compute Recall using index sets

Description

Compute Recall using index sets

Usage

trex_recall(selected_indices, true_support)

Arguments

selected_indices

Integer vector of selected indices.

true_support

Integer vector of true active indices.

Value

Numeric recall value.

Examples

trex_recall(c(1L, 3L, 5L), c(1L, 2L, 3L))

TRex Screen Control Parameters

Description

Build a control list for the screening step in TRexScreeningSelector and TRexBiobankScreeningSelector.

Usage

trex_screen_control(
  use_bootstrap_CI = FALSE,
  R_boot = 1000,
  ci_grid_step = 0.001,
  trex_method = "TREX"
)

Arguments

use_bootstrap_CI

Whether to use bootstrap confidence intervals for screening (default: FALSE).

R_boot

Number of bootstrap iterations (default: 1000).

ci_grid_step

Grid step size for confidence-interval calculations (default: 0.001).

trex_method

Screening method: "TREX", "TREX_DA_AR1", "TREX_DA_EQUI", "TREX_DA_BLOCK_EQUI" (default: "TREX").

Value

A named list for use in TRexScreeningSelector or TRexBiobankScreeningSelector.

Examples

trex_screen_control()
trex_screen_control(use_bootstrap_CI = TRUE, R_boot = 500)

T-Rex SPCA Control Parameters

Description

Build a control list for the T-Rex Sparse PCA selector.

Usage

trex_spca_control(
  mode = "ActiveSet",
  lambda2_ridge_loadings = 1e-06,
  gvs_type = "EN",
  lambda_2 = -1,
  lambda2_method = "CV_1SE_CCD",
  en_solver = "TENET_AUG",
  tenet_aug_use_lars = FALSE,
  K = 20L,
  max_dummy_multiplier = 10L
)

Arguments

mode

Character, sparse loading strategy: "ActiveSet" (default) assembles loadings via Ridge regression on the T-Rex active set; "Thresholded" keeps and normalizes the top-|A| ordinary PCA loadings.

lambda2_ridge_loadings

Numeric, Ridge penalty for ActiveSet loading assembly (default: 1e-6).

gvs_type

Character, GVS variant used internally for per-PC variable selection. Only "EN" (default, elastic net) is allowed: T-Rex SPCA is defined on the elastic net, and "IEN" is rejected.

lambda_2

Numeric, L2/Elastic Net penalty forwarded to the internal TRexGVSSelector, in LARS units. A negative value (default -1) triggers automatic determination (method selected by lambda2_method); 0 is the degenerate pure T-LASSO case; a positive value is used as-is.

lambda2_method

Character, auto-determination strategy for lambda_2 when lambda_2 < 0: "CV_1SE_CCD" (default), "CV_MIN_CCD", "CV_1SE_SVD", "CV_MIN_SVD".

en_solver

Character, Elastic Net solver variant used internally: "TENET_AUG" (default, row-augmented LASSO) or "TENET" (Gram-based). Both select the same variables; this is a solver-equivalence switch, not a LARS-vs-LASSO choice (see tenet_aug_use_lars).

tenet_aug_use_lars

Logical. When en_solver = "TENET_AUG", run the per-PC augmented sub-selector with a pure-LARS inner path that never drops variables (TRUE) instead of the default LASSO inner path (FALSE, default). This is the LARS-vs-LASSO distinction; ignored for en_solver = "TENET".

K

Integer, number of T-Rex random experiments per PC (default: 20).

max_dummy_multiplier

Integer, maximum dummy feature multiplier for T-Rex sub-selection (default: 10).

Value

A named list for passing to TRexSPCASelector$new().

Examples

trex_spca_control()
trex_spca_control(mode = "Thresholded", K = 10)
trex_spca_control(lambda_2 = 0.01)

TRex Tikhonov Control Parameters

Description

Build a control list for TRexTikhonovSelector, the general-Tikhonov T-Rex: a penalty matrix K = t(Gamma) %*% Gamma drives the Tikhonov-net solvers (TCDTIKNET by default; TIKNET through the solver field of trex_control). K = I collapses to the plain elastic net; a group-mean K reproduces the GVS-IEN penalty; banded/Laplacian K encode smoothness. With penalty_structure = "GROUP_CENTERING" the selector builds K itself from the dummy clustering (block-diagonal I - J / p_m: the members of a group share a coefficient).

Usage

trex_tikhonov_control(
  tikhonov_K = NULL,
  penalty_structure = "SPARSE_GENERAL",
  lambda_2 = -1,
  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 = c(0, 1, 3, 10, 30, 100, 300, 1000, 3000),
  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"
)

Arguments

tikhonov_K

Penalty matrix K (p x p): a base matrix or a sparse Matrix::dgCMatrix. Build it from a regularization operator Gamma with trex_gamma_to_k. Required for penalty_structure = "SPARSE_GENERAL"; ignored under "GROUP_CENTERING".

penalty_structure

"SPARSE_GENERAL" (default): the user-supplied K. "GROUP_CENTERING": K is the block-diagonal centering penalty over the dummy clusters (prior_groups, or the HAC clustering). An all-singleton partition is legitimate there: K vanishes and the path is the plain lasso on per-variable cluster dummies. On this path TCDTIKNET runs through the group-centering hooks of TCDIENET, so its warnings (sweep budget, certification fallback) carry the tag [TCDIENET].

lambda_2

Penalty weight, solver scale. A negative value (default -1) triggers auto-determination via lambda2_method; 0 is the degenerate pure-lasso case; a positive value is used as-is.

lambda2_method

Auto-determination strategy when lambda_2 < 0. "PILOT_KNEE" (default) reads lambda_2 off a few random experiments per candidate of pilot_grid, by the selector's own principle: the smallest lambda_2 whose pilot selection count is within pilot_knee_tolerance of the largest (the knee of the profile). The pilot record is available as lambda2_pilot on the selector. The k-fold CV rules consume K and return lambda_2 on the solver scale (no p/2 conversion): "CV_1SE_IEN_CCD" (well-posed in any p/n regime), "CV_MIN_IEN_CCD", "CV_1SE_TIK_SVD", "CV_MIN_TIK_SVD". The knee of the full selection profile, one selection per grid value, is trex_tikhonov_lambda2_power_rule.

cv_n_folds

Folds for the CV paths (default: 10).

cv_n_lambda

Points on the CV lambda grid of the SVD rules (default: 100).

cv_n_lambda1

IEN-geometry coordinate-descent rules: points on the profiled lambda_1 path per lambda_2 value (default: 40).

cv_n_lambda2

IEN-geometry coordinate-descent rules: points on the lambda_2 grid (default: 100).

cv_dfmax_ratio

IEN-geometry coordinate-descent rules: support cap as a fraction of the smallest fold's training size; each lambda_1 path stops once more than floor(cv_dfmax_ratio * n_train) coefficients are nonzero (default: 0.8). A value <= 0 disables the cap. Larger values allow larger supports at a higher tuner cost. Must be finite.

cv_seed

Seed for the CV fold permutation; -1 (default) derives it from the selector seed, >= 0 overrides it for CV folds only.

pilot_grid

Pilot rule: lambda_2 candidates on the working column scale (default c(0, 1, 3, 10, 30, 100, 300, 1000, 3000)), sorted and de-duplicated internally. Keep 0 on it so that "no penalty" is an admissible answer.

pilot_K

Pilot rule: pilot experiments per grid point (default: 10; at least 2, capped at K of trex_control).

pilot_T

Pilot rule: stopping time of the pilot paths (default: 5; at least 1, capped at min(L_0, ceiling(n / 2))).

pilot_L_multiplier

Pilot rule: pilot dummies L_0 = pilot_L_multiplier * p (default: 1; at most max_dummy_multiplier).

pilot_knee_tolerance

Pilot rule: selections below the largest pilot count that still count as "on the plateau" (default: 1; 0 reads the largest count, ties toward the smallest lambda_2).

pilot_statistic

Pilot rule, the count the pick is read off: "MAJORITY" (default; originals ahead of the T-th dummy in more than half of the pilot experiments), "CALIBRATED" (the T-Rex selection rule applied to the pilot data), or "GROUP_MAJORITY" (the majority count restricted to the groups of prior_groups in which at least pilot_group_fraction of the members are ahead; needs prior_groups).

pilot_group_fraction

"GROUP_MAJORITY": the share of a group's members that must be ahead, in (0, 1] (default: 0.5).

pilot_shared_dummies

Logical (default FALSE): the pilot draws its dummies from a reserved seed stream, independent of the main run's. TRUE reuses the main strategy's first dummy block (not available under the PERMUTATION strategies).

fold_dummy_coupling

Logical (default TRUE): dummy copies join their originating variable's K-coupling (FOLDED — the exact generalization of the GVS layered convention; dummy/null exchangeability holds for arbitrary K). FALSE restores the decoupled unit-ridge dummy block (INDEPENDENT_RIDGE) — a validation escape hatch that preserves the K = I == TCDENET collapse but deforms exchangeability whenever K has off-diagonals. Only the TCDTIKNET solver offers it.

cluster_dummies

Logical (default TRUE): draw dummies as per-cluster colored MVN layers (GVS parity) on the clustering below. FALSE restores canonical i.i.d. dummies — validation runs only; with an informed K, i.i.d. dummies deform the dummy/null exchangeability the FDR calibration relies on.

prior_groups

Integer vector of 1-based cluster IDs per variable (length p) for the dummy clustering. NULL (default): clusters are discovered by correlation-HAC with corr_max / hc_linkage. Ignored when cluster_dummies = FALSE.

corr_max

Maximum cross-cluster |correlation| for the HAC dummy clustering (default: 0.5). Ignored when prior_groups is set or cluster_dummies = FALSE.

hc_linkage

HAC linkage: "Single" (default), "Complete", "Average", "WPGMA". Ignored under prior_groups or cluster_dummies = FALSE.

Value

A named list for use in 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")

The knee of the full lambda_2 profile of the Tikhonov T-Rex

Description

Runs one FDR-controlled Tikhonov T-Rex selection per value of grid with the same seed, so the probes share their dummies and differ by the penalty weight alone, and picks the smallest lambda_2 whose selection is within knee_tolerance selections of the largest (the knee of the profile). This is the reference rule behind the default lambda2_method = "PILOT_KNEE" of trex_tikhonov_control, which reads the same knee off a few random experiments per grid value at a fraction of the cost; the full profile costs one selection per grid value and returns every probe's selection. The pick depends on y and lies outside the fixed-lambda_2 FDR guarantee that each probe carries.

Usage

trex_tikhonov_lambda2_power_rule(
  X,
  y,
  tFDR = 0.1,
  tik_control,
  control = trex_control(),
  seed = 0,
  grid = c(0, 1, 3, 10, 30, 100, 300, 1000, 3000),
  knee_tolerance = 1,
  verbose = FALSE
)

Arguments

X

Feature matrix (n x p). Every probe normalizes it in place and hands it back, so X is unchanged on return and never copied.

y

Response vector (length n).

tFDR

Target FDR level (default: 0.1).

tik_control

A Tikhonov control list from trex_tikhonov_control(); its lambda_2 is overwritten per probe, everything else is shared by every probe.

control

A control list from trex_control() (default: trex_control()); the solver maps as in TRexTikhonovSelector.

seed

Selector seed, the same for every probe (default: 0). A negative seed would draw fresh dummies per probe and is refused.

grid

lambda_2 candidates on the solver scale (default c(0, 1, 3, 10, 30, 100, 300, 1000, 3000)), sorted and de-duplicated. Keep 0 on it so that "no penalty" is an admissible answer.

knee_tolerance

Selections below the largest count that still count as "on the plateau" (default: 1); 0 reads the largest selection, ties toward the smallest lambda_2.

verbose

Whether the probes print their progress (default: FALSE).

Value

A list: lambda2 (the pick), index (1-based, into grid), selected (the 1-based selection at the pick), grid (ascending, de-duplicated), counts (selection sizes per grid value), probes (one list per grid value with lambda2, selected, T_stop and seconds), max_selected, n_ties (grid values within the tolerance of the maximum), the boundary flags at_lower_end / at_upper_end (widen the grid before trusting a boundary pick) and seconds.

Examples


data(Gauss_data)
X <- Gauss_data$X
y <- Gauss_data$y
ctrl <- trex_tikhonov_control(tikhonov_K = diag(ncol(X)))
prof <- trex_tikhonov_lambda2_power_rule(X, y, tFDR = 0.1, tik_control = ctrl,
                                         grid = c(0, 1, 10), seed = 1)
prof$lambda2
prof$counts

Compute True Positive Proportion (TPP) using index sets

Description

Compute True Positive Proportion (TPP) using index sets

Usage

trex_tpp(selected_indices, true_support)

Arguments

selected_indices

Integer vector of selected indices.

true_support

Integer vector of true active indices.

Value

Numeric TPP value.

Examples

trex_tpp(c(1L, 3L, 5L), c(1L, 2L, 3L))

Compute True Positive Proportion (TPP) using dense vectors

Description

Compute True Positive Proportion (TPP) using dense vectors

Usage

trex_tpp_dense(beta_hat, beta, eps = 1e-15)

Arguments

beta_hat

Numeric vector of estimated coefficients.

beta

Numeric vector of true coefficients.

eps

Numeric threshold for counting non-zeros (default: 1e-15).

Value

Numeric TPP value.

Examples

trex_tpp_dense(c(1.5, 0, 0.8, 0, 0), c(2.0, 0, 1.0, 0, 0))

T-Solver Options

Description

Every T-solver input except the data X, D and y, as one list (the C++ SolverOptions). Pass it to a solver's $new(X, D, y, options = ...). Each solver reads the fields it needs and ignores the rest; the defaults are the solver-level defaults.

Usage

tsolver_options(
  normalize = TRUE,
  intercept = TRUE,
  precentered = FALSE,
  scaling_mode = c("L2", "ZSCORE"),
  verbose = FALSE,
  tol = .Machine$double.eps,
  tie_seed = 0,
  n_threads = 1,
  exch_tie_alpha = 0,
  exch_tie_floor = 0.5,
  lambda2 = 0,
  rho_afs = 1,
  ncgmp_variant = c("line_search", "fully_corrective"),
  tenet_aug_use_lars = FALSE,
  kappa_dummy = 1,
  fold_dummies = FALSE,
  group_penalty = c("MEAN", "CENTERING"),
  cd_lambda_rel_tol = 0.001,
  cd_tol_certify = 1e-10,
  cd_tol_probe = 1e-08,
  cd_gram_cap = 400,
  cd_max_sweeps = 2000,
  cd_certified_localization = TRUE
)

Arguments

normalize

Logical; scale each column of X and D to unit L2 norm (or unit SD, see scaling_mode). FALSE when the caller pre-scaled (see the in-place note below). Default TRUE.

intercept

Logical; center X, D and y (an intercept is fitted). FALSE when the caller pre-centered. Default TRUE.

precentered

Logical; the caller centered X, D and y (intercept = FALSE on centered data, as in the T-Rex selectors). The centered columns span at most n - 1 dimensions, so the solver counts the intercept as with intercept = TRUE: the active set is capped at n - 1 and the degrees of freedom and Cp include the intercept. The data are not touched. Redundant when intercept is TRUE. Default FALSE.

scaling_mode

"L2" (default) or "ZSCORE": the column scaling applied when normalize is TRUE.

verbose

Logical; print status and diagnostics. Default FALSE.

tol

Numerical tolerance of the solver's internal comparisons. Default: machine epsilon.

tie_seed

Seed of the solver's tie-break engine. Default 0: a fixed seed, so a solver run is reproducible also where exact ties occur; a negative value seeds from the system entropy source (nondeterministic).

n_threads

Thread budget of the solver's own passes over the design (the correlation refreshes, the step-length search, the standardization). Default 1 (serial); a whole number of at least 1. A pass splits only above about a million entries of the design, and never inside a parallel region of the caller. The T-Rex selectors set it from trex_control(max_inner_threads = ).

exch_tie_alpha

Exchangeable-tie band width for the greedy solvers (TOMP and TAFS families), in units of the pairwise ranking-noise sd; 0 (default) turns it off. Ignored by the path solvers.

exch_tie_floor

Minimum absolute correlation for exchangeable-tie candidates, in [0, 1). Default 0.5.

lambda2

L2 (ridge / group-ridge) penalty weight, >= 0. Read by TENET, TENETAug and TIENETAug. Default 0 (no quadratic penalty: the elastic nets reduce to their lasso).

rho_afs

TAFS shrinkage step in (0, 1]; 1 (default) is forward stepwise.

ncgmp_variant

TNCGMP variant: "line_search" (default) or "fully_corrective".

tenet_aug_use_lars

Logical; TENETAug and TIENETAug run the augmented system with a pure-LARS inner path that never drops variables (default FALSE: LASSO inner path).

kappa_dummy

Ridge weight of the dummy block of the CCD elastic nets (not bound to R yet). Default 1.

fold_dummies

Logical; TCDTIKNET dummy coupling (not bound to R yet). Default FALSE.

group_penalty

TCDIENET structured penalty, "MEAN" (default) or "CENTERING" (not bound to R yet).

cd_lambda_rel_tol, cd_tol_certify, cd_tol_probe, cd_gram_cap, cd_max_sweeps, cd_certified_localization

Knobs of the CD solver family (not bound to R yet); the defaults are the solver defaults (1e-3, 1e-10, 1e-8, 400, 2000, TRUE).

Value

A named list suitable for the options argument of every T-solver constructor.

In-place preprocessing (the writer/reader contract)

The T-solvers work on the caller's matrices without copying, in R as in C++ and Python. With normalize = TRUE or intercept = TRUE a solver is a writer: it centers / scales the columns of X and D in place (visible on the caller's matrix or memory-mapped file), keeps the statistics itself, and holds a claim on both until $restore() or garbage collection, both of which write X and D back; a second writer (T-solver or T-Rex selector) on a claimed matrix is an error, because a second in-place transformation moves the data by rounding. With normalize = FALSE and intercept = FALSE a solver is a reader that runs as constructed and never writes; a pipeline with several solvers on one matrix pre-scales once in front (MLLpNormScaler) and constructs readers. y is never written. See TSolver_Base.

Examples

tsolver_options()
tsolver_options(lambda2 = 0.5, normalize = FALSE)

Package {TRexSelector}

TRexSelector: the T-Rex selector, its T-solvers and ML utilities

Description

T-Rex selectors and controls (TRex*Selector, ⁠trex_*⁠)

T-solvers (⁠T*_Solver⁠, ⁠tsolver_*⁠)

ML methods (⁠ML*⁠, ⁠ml_*⁠)

Memory-mapped matrices (⁠mem_*⁠)

Author(s)

See Also

Toy data generated from a Gaussian linear model

Description

Usage

Format

See Also

Examples

Elastic Net (coordinate-descent path)

Description

Methods

Public methods

MLElasticNet$new()

Usage

Arguments

MLElasticNet$fit()

Usage

Arguments

Returns

MLElasticNet$fit_grid()

Usage

Arguments

Returns

MLElasticNet$get_coef()

Usage

Returns

MLElasticNet$get_intercepts()

Usage

Returns

MLElasticNet$get_lambdas()

Usage

Returns

MLElasticNet$get_dev_ratio()

Usage

Returns

MLElasticNet$converged()

Usage

Returns

MLElasticNet$n_nonconverged()

Usage

Returns

MLElasticNet$predict()

Usage

Arguments

Returns

MLElasticNet$clone()

Usage

Arguments

References

See Also

Examples

Elastic Net with Cross-Validation

Description

Methods

Public methods

MLElasticNetCV$new()

Usage

Arguments

MLElasticNetCV$fit()

Usage

Arguments

Returns

MLElasticNetCV$cv_min()

Usage

Returns

MLElasticNetCV$cv_1se()

Usage

Returns

MLElasticNetCV$index_min()

Usage

Returns

MLElasticNetCV$index_1se()

Usage

T-Rex selectors and controls (`TRexSelector`, `⁠trex_⁠`)

T-solvers (`⁠T_Solver⁠`, `⁠tsolver_⁠`)

ML methods (`⁠ML⁠`, `⁠ml_⁠`)

Memory-mapped matrices (`⁠mem_*⁠`)

`MLElasticNet$new()`

`MLElasticNet$fit()`

`MLElasticNet$fit_grid()`

`MLElasticNet$get_coef()`

`MLElasticNet$get_intercepts()`

`MLElasticNet$get_lambdas()`

`MLElasticNet$get_dev_ratio()`

`MLElasticNet$converged()`

`MLElasticNet$n_nonconverged()`

`MLElasticNet$predict()`

`MLElasticNet$clone()`

`MLElasticNetCV$new()`

`MLElasticNetCV$fit()`

`MLElasticNetCV$cv_min()`

`MLElasticNetCV$cv_1se()`

`MLElasticNetCV$index_min()`

`MLElasticNetCV$index_1se()`

`MLElasticNetCV$get_lambdas()`

`MLElasticNetCV$get_cv_errors()`

`MLElasticNetCV$get_cv_std()`

`MLElasticNetCV$clone()`

`MLLpNormScaler$new()`

`MLLpNormScaler$fit()`

`MLLpNormScaler$transform_inplace()`

`MLLpNormScaler$inverse_transform_inplace()`

`MLLpNormScaler$fit_transform_inplace()`

`MLLpNormScaler$is_fitted()`

`MLLpNormScaler$get_dropped_indices()`

`MLLpNormScaler$get_centers()`

`MLLpNormScaler$get_scales()`

`MLLpNormScaler$get_center()`

`MLLpNormScaler$get_scale()`

`MLLpNormScaler$get_norm_type()`

`MLLpNormScaler$save()`

`MLLpNormScaler$load()`