TSolver_Base: Base T-Solver Class

TSolver_BaseR Documentation

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, which either of the two may be. 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, so it accepts an mmap_matrix open in "readonly" mode for X and for D, which a writer refuses. 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 in memory, or an mmap_matrix (the handle of a memory-mapped file).

D

Numeric matrix of dummies in memory, or an mmap_matrix (the handle of a memory-mapped file).

y

Numeric response vector.

ptr

External pointer to the underlying Cpp TSolver_Base object.

Methods

Public methods


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 or memory-mapped files the C++ solver binds (no copy for double storage).

Usage
TSolver_Base$new(X, D, y)
Arguments
X

Numeric matrix of predictors in memory, or mmap_matrix (the handle of a memory-mapped file).

D

Numeric matrix of dummies in memory, or mmap_matrix (the handle of a memory-mapped file).

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 of the greedy solvers (TOMP, TOOLS, TGP, TACGP, TMP, TNCGMP and TAFS); alpha <= 0 turns it off. The path solvers ignore it.

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)

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