Nothing
#' @title 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 \code{\link[base]{scale}()}: with \code{center = FALSE, scale = TRUE}
#' columns are divided by the root-mean-square around 0.
#'
#' @details The \code{*_inplace} methods mutate \code{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. \code{X} may also be an
#' \code{mmap_matrix} created by \code{\link{mem_matrix}} /
#' \code{\link{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 \code{fit()} — require the
#' handle to be open in \code{"readwrite"} mode, because the scaler core
#' binds a mutable map.
#'
#' @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()
#'
#' @family ML methods
#' @export
MLZScoreScaler <- R6::R6Class("MLZScoreScaler",
private = list(
cpp_ptr = NULL
),
public = list(
#' @description Initialize the MLZScoreScaler
#'
#' @param center Logical, whether to center columns to mean 0 (default: TRUE)
#' @param scale Logical, whether to scale columns to unit SD (default: TRUE);
#' around 0 instead of the mean when \code{center = FALSE}, as in R's scale().
#' @param n_threads Integer, the thread budget of the column passes
#' (\code{NULL}, the default: the library's default budget,
#' \code{\link{trex_get_num_threads}()}, initially 1).
initialize = function(center = TRUE, scale = TRUE, n_threads = NULL) {
private$cpp_ptr <- zscore_scaler_create(center, scale, resolve_n_threads(n_threads))
},
#' @description Compute the centers and scales to be used for later scaling.
#'
#' @param X A numeric matrix (n x p) or an \code{mmap_matrix} in
#' \code{"readwrite"} mode (the scaler core binds a mutable map).
#' @param threshold Double, lower bound for the scale statistic (default: 1e-12).
#'
#' @return Value.
fit = function(X, threshold = 1e-12) {
if (inherits(X, "mmap_matrix")) {
zscore_scaler_fit_mmap(private$cpp_ptr, X, threshold)
} else {
X <- .as_double_matrix(X)
zscore_scaler_fit(private$cpp_ptr, X, threshold)
}
invisible(self)
},
#' @description Perform standardization by centering and scaling in-place.
#'
#' @param X A numeric matrix (n x p) or an \code{mmap_matrix} in
#' \code{"readwrite"} mode.
#'
#' @return The modified matrix `X` (the same handle for an \code{mmap_matrix}).
transform_inplace = function(X) {
if (inherits(X, "mmap_matrix")) {
zscore_scaler_transform_inplace_mmap(private$cpp_ptr, X)
return(invisible(X))
}
X <- .as_double_matrix(X)
zscore_scaler_transform_inplace(private$cpp_ptr, X)
return(X)
},
#' @description Inverse transform to original scale.
#'
#' @param X A numeric matrix (n x p) or an \code{mmap_matrix} in
#' \code{"readwrite"} mode.
#'
#' @return The modified matrix `X` (the same handle for an \code{mmap_matrix}).
inverse_transform_inplace = function(X) {
if (inherits(X, "mmap_matrix")) {
zscore_scaler_inverse_transform_inplace_mmap(private$cpp_ptr, X)
return(invisible(X))
}
X <- .as_double_matrix(X)
zscore_scaler_inverse_transform_inplace(private$cpp_ptr, X)
return(X)
},
#' @description Fit and transform in one call, like R's scale().
#'
#' @param X A numeric matrix (n x p) or an \code{mmap_matrix} in
#' \code{"readwrite"} mode.
#' @param threshold Double, lower bound for the scale statistic (default: 1e-12).
#'
#' @return The modified matrix `X` (the same handle for an \code{mmap_matrix}).
fit_transform_inplace = function(X, threshold = 1e-12) {
if (inherits(X, "mmap_matrix")) {
zscore_scaler_fit_transform_inplace_mmap(private$cpp_ptr, X, threshold)
return(invisible(X))
}
X <- .as_double_matrix(X)
zscore_scaler_fit_transform_inplace(private$cpp_ptr, X, threshold)
return(X)
},
#' @description Check if scaler is fitted.
#'
#' @return Value.
is_fitted = function() {
zscore_scaler_is_fitted(private$cpp_ptr)
},
#' @description Get dropped (degenerate) column indices. These columns get
#' scale factor 1 and are still centered (sklearn semantics).
#'
#' @return Value.
get_dropped_indices = function() {
# Convert 0-based Cpp column indices to 1-based R convention
zscore_scaler_get_dropped_indices(private$cpp_ptr) + 1L
},
#' @description Check if scaler centers data.
#'
#' @return Value.
get_center = function() {
zscore_scaler_get_center(private$cpp_ptr)
},
#' @description Check if scaler scales data to unit variance.
#'
#' @return Value.
get_scale = function() {
zscore_scaler_get_scale(private$cpp_ptr)
},
#' @description Get the learned centers (column means).
#'
#' @return Value.
get_centers = function() {
zscore_scaler_get_centers(private$cpp_ptr)
},
#' @description Get the learned scales (standard deviations).
#'
#' @return Value.
get_scales = function() {
zscore_scaler_get_scales(private$cpp_ptr)
},
#' @description Save model state to file.
#'
#' @param filename String path to save output.
#'
#' @return Value.
save = function(filename) {
if (!is.character(filename) || length(filename) != 1) {
stop("filename must be a single string.")
}
zscore_scaler_save(private$cpp_ptr, filename)
invisible(self)
},
#' @description Load model state from file.
#'
#' @param filename String path to load input from.
#'
#' @return Value.
load = function(filename) {
if (!is.character(filename) || length(filename) != 1) {
stop("filename must be a single string.")
}
zscore_scaler_load(private$cpp_ptr, filename)
invisible(self)
}
)
)
#' @title 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
#' \code{\link[base]{scale}()}: the norm is computed around the applied
#' center (around 0 when \code{center = FALSE}).
#'
#' @details The \code{*_inplace} methods mutate \code{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. \code{X} may also be an
#' \code{mmap_matrix} created by \code{\link{mem_matrix}} /
#' \code{\link{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 \code{fit()} — require the
#' handle to be open in \code{"readwrite"} mode, because the scaler core
#' binds a mutable map.
#'
#' @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)
#'
#' @family ML methods
#' @export
MLLpNormScaler <- R6::R6Class("MLLpNormScaler",
private = list(
cpp_ptr = NULL
),
public = list(
#' @description Initialize the MLLpNormScaler
#'
#' @param norm_type Integer, 1 for L1 norm, 2 for L2 norm (default: 2)
#' @param center Logical, whether to center columns to mean 0 (default: TRUE)
#' @param scale Logical, whether to scale columns to unit Lp norm (default: TRUE)
#' @param n_threads Integer, the thread budget of the column passes
#' (\code{NULL}, the default: the library's default budget,
#' \code{\link{trex_get_num_threads}()}, initially 1).
initialize = function(norm_type = 2, center = TRUE, scale = TRUE, n_threads = NULL) {
if (!(norm_type %in% c(1, 2))) {
stop("norm_type must be 1 (L1) or 2 (L2)")
}
private$cpp_ptr <- lpnorm_scaler_create(norm_type, center, scale,
resolve_n_threads(n_threads))
},
#' @description Compute the norm parameters.
#'
#' @param X A numeric matrix (n x p) or an \code{mmap_matrix} in
#' \code{"readwrite"} mode (the scaler core binds a mutable map).
#' @param threshold Double, lower bound for the scale statistic (default: 1e-12).
#'
#' @return Value.
fit = function(X, threshold = 1e-12) {
if (inherits(X, "mmap_matrix")) {
lpnorm_scaler_fit_mmap(private$cpp_ptr, X, threshold)
} else {
X <- .as_double_matrix(X)
lpnorm_scaler_fit(private$cpp_ptr, X, threshold)
}
invisible(self)
},
#' @description Perform standardization in-place.
#'
#' @param X A numeric matrix (n x p) or an \code{mmap_matrix} in
#' \code{"readwrite"} mode.
#'
#' @return The modified matrix `X` (the same handle for an \code{mmap_matrix}).
transform_inplace = function(X) {
if (inherits(X, "mmap_matrix")) {
lpnorm_scaler_transform_inplace_mmap(private$cpp_ptr, X)
return(invisible(X))
}
X <- .as_double_matrix(X)
lpnorm_scaler_transform_inplace(private$cpp_ptr, X)
return(X)
},
#' @description Inverse transform to original scale.
#'
#' @param X A numeric matrix (n x p) or an \code{mmap_matrix} in
#' \code{"readwrite"} mode.
#'
#' @return The modified matrix `X` (the same handle for an \code{mmap_matrix}).
inverse_transform_inplace = function(X) {
if (inherits(X, "mmap_matrix")) {
lpnorm_scaler_inverse_transform_inplace_mmap(private$cpp_ptr, X)
return(invisible(X))
}
X <- .as_double_matrix(X)
lpnorm_scaler_inverse_transform_inplace(private$cpp_ptr, X)
return(X)
},
#' @description Fit and transform in one call, like R's scale().
#'
#' @param X A numeric matrix (n x p) or an \code{mmap_matrix} in
#' \code{"readwrite"} mode.
#' @param threshold Double, lower bound for the scale statistic (default: 1e-12).
#'
#' @return The modified matrix `X` (the same handle for an \code{mmap_matrix}).
fit_transform_inplace = function(X, threshold = 1e-12) {
if (inherits(X, "mmap_matrix")) {
lpnorm_scaler_fit_transform_inplace_mmap(private$cpp_ptr, X, threshold)
return(invisible(X))
}
X <- .as_double_matrix(X)
lpnorm_scaler_fit_transform_inplace(private$cpp_ptr, X, threshold)
return(X)
},
#' @description Check if scaler is fitted.
#'
#' @return Value.
is_fitted = function() {
lpnorm_scaler_is_fitted(private$cpp_ptr)
},
#' @description Get dropped (degenerate) column indices. These columns get
#' scale factor 1 and are still centered (sklearn semantics).
#'
#' @return Value.
get_dropped_indices = function() {
# Convert 0-based Cpp column indices to 1-based R convention
lpnorm_scaler_get_dropped_indices(private$cpp_ptr) + 1L
},
#' @description Get the learned centers (column means).
#'
#' @return Value.
get_centers = function() {
lpnorm_scaler_get_centers(private$cpp_ptr)
},
#' @description Get the learned scales.
#'
#' @return Value.
get_scales = function() {
lpnorm_scaler_get_scales(private$cpp_ptr)
},
#' @description Check if scaler centers data.
#'
#' @return Value.
get_center = function() {
lpnorm_scaler_get_center(private$cpp_ptr)
},
#' @description Check if scaler scales data to unit norm.
#'
#' @return Value.
get_scale = function() {
lpnorm_scaler_get_scale(private$cpp_ptr)
},
#' @description Get norm type (1 for L1, 2 for L2).
#'
#' @return Value.
get_norm_type = function() {
lpnorm_scaler_get_norm_type(private$cpp_ptr)
},
#' @description Save model state to file.
#'
#' @param filename String path to save output.
#'
#' @return Value.
save = function(filename) {
if (!is.character(filename) || length(filename) != 1) {
stop("filename must be a single string.")
}
lpnorm_scaler_save(private$cpp_ptr, filename)
invisible(self)
},
#' @description Load model state from file.
#'
#' @param filename String path to load input from.
#'
#' @return Value.
load = function(filename) {
if (!is.character(filename) || length(filename) != 1) {
stop("filename must be a single string.")
}
lpnorm_scaler_load(private$cpp_ptr, filename)
invisible(self)
}
)
)
#' @title Ridge Regression with Cross-Validation
#'
#' @description Performs explicit K-Fold cross-validation for Ridge Regression model selection.
#'
#' @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).
#'
#' 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
#'
#' @family ML methods
#' @export
MLRidgeCV <- R6::R6Class("MLRidgeCV",
private = list(
cpp_ptr = NULL
),
public = list(
#' @description Initialize the MLRidgeCV object.
#' @param low_memory Logical (default \code{FALSE}). \code{FALSE}: each
#' fold gathers and standardizes its training rows and takes a thin SVD
#' (about three to four copies of X in flight). \code{TRUE}: the dual
#' (kernel) form — n x n kernels accumulated from column blocks of X read
#' in place (an \code{mmap_matrix} included, \code{"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.
#' @param n_threads Integer, the thread budget of the fit's matrix products
#' (\code{NULL}, the default: the library's default budget,
#' \code{\link{trex_get_num_threads}()}, initially 1).
initialize = function(low_memory = FALSE, n_threads = NULL) {
private$cpp_ptr <- ridge_cv_create(as.logical(low_memory), resolve_n_threads(n_threads))
},
#' @description Fit the CV model.
#'
#' @param X Predictor matrix, or an \code{mmap_matrix} created by
#' \code{\link{mem_matrix}} / \code{\link{mem_matrix_from}}
#' (bound zero-copy; \code{"readonly"} mode suffices since the fit does
#' not modify \code{X}).
#' @param y Response vector.
#' @param n_folds Number of folds (default 10).
#' @param n_lambda Number of lambdas in the path (default 100).
#' @param lambda_ratio Ratio of max to min lambda (default 1000).
#' @param seed Random seed for CV splits (default 0).
#'
#' @return Value.
fit = function(X, y, n_folds = 10, n_lambda = 100, lambda_ratio = 1000.0, seed = 0) {
if (inherits(X, "mmap_matrix")) {
stopifnot(is.numeric(y), dim(X)[1] == length(y))
ridge_cv_fit_mmap(private$cpp_ptr, X, as.numeric(y), as.integer(n_folds),
as.integer(n_lambda), as.numeric(lambda_ratio), as.integer(seed))
return(invisible(self))
}
X <- .as_double_matrix(X)
stopifnot(is.numeric(y), nrow(X) == length(y))
ridge_cv_fit(private$cpp_ptr, X, as.numeric(y), as.integer(n_folds), as.integer(n_lambda),
as.numeric(lambda_ratio), as.integer(seed))
invisible(self)
},
#' @description Get lambda that minimizes CV error.
#'
#' @return Value.
cv_min = function() {
ridge_cv_min(private$cpp_ptr)
},
#' @description Get 1SE rule lambda.
#'
#' @return Value.
cv_1se = function() {
ridge_cv_1se(private$cpp_ptr)
},
#' @description Get index of minimum CV error.
#'
#' @return Value.
index_min = function() {
# Add 1 since R is 1-indexed
ridge_cv_index_min(private$cpp_ptr) + 1L
},
#' @description Get index of 1SE rule lambda.
#'
#' @return Value.
index_1se = function() {
# Add 1 since R is 1-indexed
ridge_cv_index_1se(private$cpp_ptr) + 1L
},
#' @description Get the sequence of lambdas used.
#'
#' @return Value.
get_lambdas = function() {
ridge_cv_get_lambdas(private$cpp_ptr)
},
#' @description Get the CV mean squared errors for each lambda.
#'
#' @return Value.
get_cv_errors = function() {
ridge_cv_get_cv_errors(private$cpp_ptr)
},
#' @description Get the standard error of the CV errors.
#'
#' @return Value.
get_cv_std = function() {
ridge_cv_get_cv_std(private$cpp_ptr)
},
#' @description 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
#' \code{selection_at_grid_edge()} it tells whether \code{cv_min()} is
#' a real minimum or the grid running out.
#'
#' @return Logical.
interpolates = function() {
ridge_cv_interpolates(private$cpp_ptr)
},
#' @description Whether \code{cv_min()} or \code{cv_1se()} landed on the
#' first or the last grid point. The pick is then the grid boundary,
#' not an optimum, and \code{lambda_ratio} or \code{n_lambda} need
#' widening.
#'
#' @return Logical.
selection_at_grid_edge = function() {
ridge_cv_selection_at_grid_edge(private$cpp_ptr)
}
)
)
# ==============================================================================
# MLElasticNet
# ==============================================================================
#' @title 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 \code{alpha} interpolates
#' between lasso (\code{alpha = 1}) and ridge (\code{alpha = 0}).
#'
#' @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, ])
#'
#' @family ML methods
#' @export
MLElasticNet <- R6::R6Class("MLElasticNet",
private = list(
cpp_ptr = NULL
),
public = list(
#' @description Initialize the MLElasticNet object.
#' @param low_memory Logical (default \code{FALSE}). \code{FALSE}: the
#' coordinate descent runs on a centered and standardized working copy of
#' X (one n x p matrix while fitting). \code{TRUE}: it runs on X itself
#' (an \code{mmap_matrix} is read in place, \code{"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).
#' @param n_threads Integer, the thread budget of the fit's matrix products
#' (\code{NULL}, the default: the library's default budget,
#' \code{\link{trex_get_num_threads}()}, initially 1).
initialize = function(low_memory = FALSE, n_threads = NULL) {
private$cpp_ptr <- enet_create(as.logical(low_memory), resolve_n_threads(n_threads))
},
#' @description Fit the EN path over an auto-generated glmnet-style grid.
#'
#' @param X Predictor matrix (n x p), or an \code{mmap_matrix} (bound
#' zero-copy; \code{"readonly"} suffices, the fit does not modify X).
#' @param y Response vector (n).
#' @param alpha Mixing in \code{[0, 1]}: 1 = lasso, 0 = ridge (default 1).
#' @param n_lambda Grid size (default 100).
#' @param lambda_min_ratio Ratio lambda_min/lambda_max; negative (default)
#' auto-selects glmnet's rule.
#' @param standardize Standardize columns to unit SD (default TRUE).
#' @param intercept Fit an unpenalized intercept (default TRUE).
#' @param use_strong_rule Enable the sequential strong rule (default FALSE).
#' @param max_iter Max CD sweeps per lambda (default 100000).
#' @param tol Convergence tolerance (default 1e-7).
#' @return Invisibly returns \code{self}.
fit = function(X, y, alpha = 1.0, n_lambda = 100, lambda_min_ratio = -1.0,
standardize = TRUE, intercept = TRUE, use_strong_rule = FALSE,
max_iter = 100000, tol = 1e-7) {
if (inherits(X, "mmap_matrix")) {
stopifnot(is.numeric(y), dim(X)[1] == length(y))
enet_fit_mmap(private$cpp_ptr, X, as.numeric(y), as.numeric(alpha),
as.integer(n_lambda), as.numeric(lambda_min_ratio),
as.logical(standardize), as.logical(intercept),
as.logical(use_strong_rule), as.integer(max_iter), as.numeric(tol))
return(invisible(self))
}
X <- .as_double_matrix(X)
stopifnot(is.numeric(y), nrow(X) == length(y))
enet_fit(private$cpp_ptr, X, as.numeric(y), as.numeric(alpha),
as.integer(n_lambda), as.numeric(lambda_min_ratio),
as.logical(standardize), as.logical(intercept),
as.logical(use_strong_rule), as.integer(max_iter), as.numeric(tol))
invisible(self)
},
#' @description Fit the EN path at an explicit lambda grid (sorted
#' descending internally); use to evaluate at exactly glmnet's sequence.
#'
#' @param X Predictor matrix (n x p), or an \code{mmap_matrix} (zero-copy).
#' @param y Response vector (n).
#' @param lambda_grid Explicit lambda values (any order, > 0).
#' @param alpha Mixing in \code{[0, 1]} (default 1).
#' @param standardize Standardize columns to unit SD (default TRUE).
#' @param intercept Fit an unpenalized intercept (default TRUE).
#' @param use_strong_rule Enable the sequential strong rule (default FALSE).
#' @param max_iter Max CD sweeps per lambda (default 100000).
#' @param tol Convergence tolerance (default 1e-7).
#' @return Invisibly returns \code{self}.
fit_grid = function(X, y, lambda_grid, alpha = 1.0, standardize = TRUE,
intercept = TRUE, use_strong_rule = FALSE,
max_iter = 100000, tol = 1e-7) {
if (inherits(X, "mmap_matrix")) {
stopifnot(is.numeric(y), dim(X)[1] == length(y), is.numeric(lambda_grid))
enet_fit_grid_mmap(private$cpp_ptr, X, as.numeric(y), as.numeric(lambda_grid),
as.numeric(alpha), as.logical(standardize),
as.logical(intercept), as.logical(use_strong_rule),
as.integer(max_iter), as.numeric(tol))
return(invisible(self))
}
X <- .as_double_matrix(X)
stopifnot(is.numeric(y), nrow(X) == length(y), is.numeric(lambda_grid))
enet_fit_grid(private$cpp_ptr, X, as.numeric(y), as.numeric(lambda_grid),
as.numeric(alpha), as.logical(standardize),
as.logical(intercept), as.logical(use_strong_rule),
as.integer(max_iter), as.numeric(tol))
invisible(self)
},
#' @description Coefficient path in original predictor scale (p x n_lambda).
#' @return Numeric matrix.
get_coef = function() {
enet_get_coef(private$cpp_ptr)
},
#' @description Intercept per lambda (zero if \code{intercept = FALSE}).
#' @return Numeric vector.
get_intercepts = function() {
enet_get_intercepts(private$cpp_ptr)
},
#' @description Lambda grid actually used (descending).
#' @return Numeric vector.
get_lambdas = function() {
enet_get_lambdas(private$cpp_ptr)
},
#' @description Fraction of null deviance explained per lambda (glmnet %Dev).
#' @return Numeric vector.
get_dev_ratio = function() {
enet_get_dev_ratio(private$cpp_ptr)
},
#' @description Whether every lambda reached the convergence tolerance.
#' @return Logical scalar.
converged = function() {
enet_converged(private$cpp_ptr)
},
#' @description Number of lambdas whose coordinate descent hit \code{max_iter}.
#' @return Integer.
n_nonconverged = function() {
enet_n_nonconverged(private$cpp_ptr)
},
#' @description Predictions per lambda for new data.
#' @param X_new Predictor matrix with the same number of columns as the
#' fit, or an \code{mmap_matrix} (zero-copy).
#' @return Numeric matrix (nrow(X_new) x n_lambda).
predict = function(X_new) {
if (inherits(X_new, "mmap_matrix")) return(enet_predict_mmap(private$cpp_ptr, X_new))
enet_predict(private$cpp_ptr, .as_double_matrix(X_new, arg = "X_new"))
}
)
)
# ==============================================================================
# MLElasticNetCV
# ==============================================================================
#' @title 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
#' \code{lambda.min} and \code{lambda.1se}. The mixing parameter \code{alpha}
#' interpolates between lasso (\code{alpha = 1}) and ridge (\code{alpha = 0}).
#'
#' @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()
#'
#' @family ML methods
#' @export
MLElasticNetCV <- R6::R6Class("MLElasticNetCV",
private = list(
cpp_ptr = NULL
),
public = list(
#' @description Initialize the MLElasticNetCV object.
#' @param low_memory Logical (default \code{FALSE}); \code{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 \code{mmap_matrix} is read in
#' place). See \code{\link{MLElasticNet}}.
#' @param n_threads Integer, the thread budget of the matrix products of the
#' fit and its folds (\code{NULL}, the default: the library's default
#' budget, \code{\link{trex_get_num_threads}()}, initially 1).
initialize = function(low_memory = FALSE, n_threads = NULL) {
private$cpp_ptr <- enet_cv_create(as.logical(low_memory), resolve_n_threads(n_threads))
},
#' @description Fit K-fold CV over a glmnet-style grid.
#'
#' @param X Predictor matrix (n x p), or an \code{mmap_matrix} (bound
#' zero-copy; \code{"readonly"} suffices, the fit does not modify X).
#' @param y Response vector (n).
#' @param alpha Mixing in \code{[0, 1]}: 1 = lasso, 0 = ridge (default 0).
#' @param n_folds Number of folds (default 10).
#' @param n_lambda Grid size (default 100).
#' @param lambda_min_ratio Ratio lambda_min/lambda_max; negative (default)
#' auto-selects glmnet's rule.
#' @param seed Fold-permutation RNG seed (default 0).
#' @param standardize Standardize columns to unit SD (default TRUE).
#' @param intercept Fit an unpenalized intercept (default TRUE).
#' @param max_iter Max CD sweeps per lambda (default 100000).
#' @param tol Convergence tolerance (default 1e-7).
#' @return Invisibly returns \code{self}.
fit = function(X, y, alpha = 0.0, n_folds = 10, n_lambda = 100,
lambda_min_ratio = -1.0, seed = 0, standardize = TRUE,
intercept = TRUE, max_iter = 100000, tol = 1e-7) {
if (inherits(X, "mmap_matrix")) {
stopifnot(is.numeric(y), dim(X)[1] == length(y))
enet_cv_fit_mmap(private$cpp_ptr, X, as.numeric(y), as.numeric(alpha),
as.integer(n_folds), as.integer(n_lambda),
as.numeric(lambda_min_ratio), as.integer(seed),
as.logical(standardize), as.logical(intercept),
as.integer(max_iter), as.numeric(tol))
return(invisible(self))
}
X <- .as_double_matrix(X)
stopifnot(is.numeric(y), nrow(X) == length(y))
enet_cv_fit(private$cpp_ptr, X, as.numeric(y), as.numeric(alpha),
as.integer(n_folds), as.integer(n_lambda),
as.numeric(lambda_min_ratio), as.integer(seed),
as.logical(standardize), as.logical(intercept),
as.integer(max_iter), as.numeric(tol))
invisible(self)
},
#' @description Lambda that minimizes the mean CV error.
#' @return Scalar numeric.
cv_min = function() {
enet_cv_min(private$cpp_ptr)
},
#' @description Largest lambda within one SE of the minimum (1SE rule).
#' @return Scalar numeric.
cv_1se = function() {
enet_cv_1se(private$cpp_ptr)
},
#' @description Index (1-based) of \code{lambda.min}.
#' @return Integer.
index_min = function() {
enet_cv_index_min(private$cpp_ptr) + 1L
},
#' @description Index (1-based) of \code{lambda.1se}.
#' @return Integer.
index_1se = function() {
enet_cv_index_1se(private$cpp_ptr) + 1L
},
#' @description Lambda grid used (descending).
#' @return Numeric vector.
get_lambdas = function() {
enet_cv_get_lambdas(private$cpp_ptr)
},
#' @description Mean CV MSE per lambda.
#' @return Numeric vector.
get_cv_errors = function() {
enet_cv_get_cv_errors(private$cpp_ptr)
},
#' @description Standard error of the CV MSE per lambda.
#' @return Numeric vector.
get_cv_std = function() {
enet_cv_get_cv_std(private$cpp_ptr)
}
)
)
# ==============================================================================
# MLSVD
# ==============================================================================
#' @title 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 \code{X}.
#'
#' @details Wraps the C++ \code{MLSVD::compute(X, M)} static method.
#'
#' @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
#'
#' @family ML methods
#' @export
MLSVD <- R6::R6Class("MLSVD",
private = list(
n_threads_ = 1L,
min_dim_thresh_ = 10000,
block_size_ = 1024
),
public = list(
#' @description Initialize the solver with its dispatch thresholds.
#' @param min_dim_thresh Integer (default 10000). The direct path (a
#' Jacobi SVD that copies X and computes every singular triplet) is
#' taken while \code{min(n, p)} is below it; above it, and when
#' \code{M < min(n, p) / 10}, the randomized path runs two block-wise
#' passes over X without a copy (the route for a large
#' \code{mmap_matrix}). \code{p > 2 n} always takes the Gram path.
#' @param block_size Integer (default 1024): the column block of the
#' block-wise passes.
#' @param n_threads Integer, the thread budget of the matrix products
#' (\code{NULL}, the default: the library's default budget,
#' \code{\link{trex_get_num_threads}()}, initially 1).
initialize = function(min_dim_thresh = 10000, block_size = 1024, n_threads = NULL) {
stopifnot(is.numeric(min_dim_thresh), min_dim_thresh >= 1,
is.numeric(block_size), block_size >= 1)
private$min_dim_thresh_ <- as.numeric(min_dim_thresh)
private$block_size_ <- as.numeric(block_size)
private$n_threads_ <- resolve_n_threads(n_threads)
},
#' @description Compute top-M singular value decomposition of \code{X}.
#'
#' @param X A numeric matrix (n x p), or an \code{mmap_matrix} (bound
#' zero-copy; \code{"readonly"} suffices).
#' @param M Integer, number of singular components to retain.
#'
#' @return Named list with:
#' \itemize{
#' \item \code{U} Left singular vectors (n x M).
#' \item \code{S} Singular values (M).
#' \item \code{V} Right singular vectors (p x M).
#' }
compute = function(X, M) {
if (inherits(X, "mmap_matrix")) {
stopifnot(is.numeric(M), M >= 1L, M <= min(dim(X)))
return(svd_compute_mmap(X, as.integer(M), private$min_dim_thresh_, private$block_size_,
private$n_threads_))
}
X <- .as_double_matrix(X)
stopifnot(is.numeric(M), M >= 1L, M <= min(nrow(X), ncol(X)))
svd_compute(X, as.integer(M), private$min_dim_thresh_, private$block_size_,
private$n_threads_)
}
)
)
# ==============================================================================
# PCA
# ==============================================================================
#' @title Principal Component Analysis
#'
#' @description Fits PCA to a data matrix, retaining the top-M principal
#' components. Centering/normalization is applied to \code{X} in-place at
#' construction time (the R matrix or the memory-mapped file itself, no
#' copy) and undone by \code{restore()}, which may be called before or
#' after \code{fit()} and is idempotent; an object that is garbage-collected
#' without \code{restore()} writes \code{X} back in its finalizer (the
#' same rule as the T-solvers).
#'
#' @details Wraps the C++ \code{PCA} class. The instance is bound to \code{X}
#' at creation (mirroring the C++ constructor); \code{fit()} is single-use.
#' The fit result is cached internally; use the \code{get_*()} accessors or
#' pass \code{X_new} to \code{transform()} for out-of-sample scoring.
#'
#' @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()
#'
#' @family ML methods
#' @export
MLPCA <- R6::R6Class("MLPCA",
private = list(
cpp_ptr = NULL,
X_ = NULL,
result_ = NULL
),
public = list(
#' @description Initialize PCA bound to \code{X}. Centering/normalization
#' is applied to \code{X} in-place immediately.
#'
#' @param X A numeric matrix (n x p), or an \code{mmap_matrix}
#' (\code{"readwrite"}: the file is modified). Modified in place when
#' centering/normalizing; call \code{restore()} to undo.
#' @param M Integer, number of principal components.
#' @param center Logical, whether to center \code{X} in-place
#' (default: \code{TRUE}).
#' @param normalize Logical, whether to scale the columns of \code{X}
#' in-place (default: \code{TRUE}).
#' @param n_threads Integer, the thread budget of the matrix products of
#' \code{fit()} and \code{transform()} (\code{NULL}, the default: the
#' library's default budget, \code{\link{trex_get_num_threads}()},
#' initially 1).
initialize = function(X, M, center = TRUE, normalize = TRUE, n_threads = NULL) {
n_threads <- resolve_n_threads(n_threads)
if (inherits(X, "mmap_matrix")) {
stopifnot(is.numeric(M), M >= 1L, M <= min(dim(X)))
private$X_ <- X
private$cpp_ptr <- pca_create_mmap(X, as.integer(M),
as.logical(center), as.logical(normalize),
n_threads)
return(invisible(self))
}
# Double storage so pca_create's zero-copy view aliases this buffer; the
# same buffer is centered in place here and un-centered by restore().
private$X_ <- .as_double_matrix(X)
stopifnot(is.numeric(M), M >= 1L, M <= min(nrow(private$X_), ncol(private$X_)))
private$cpp_ptr <- pca_create(private$X_, as.integer(M),
as.logical(center), as.logical(normalize),
n_threads)
},
#' @description Fit the PCA bound at construction time (single-use).
#'
#' @return Invisible \code{self} for method chaining.
fit = function() {
private$result_ <- pca_fit(private$cpp_ptr)
invisible(self)
},
#' @description Project new data onto the fitted principal subspace.
#'
#' @param X_new A numeric matrix (n_new x p), or an \code{mmap_matrix}
#' (zero-copy). The stored training means/norms are applied before
#' projection.
#'
#' @return Score matrix (n_new x M).
transform = function(X_new) {
stopifnot(!is.null(private$result_))
if (inherits(X_new, "mmap_matrix")) return(pca_transform_mmap(private$cpp_ptr, X_new))
pca_transform(private$cpp_ptr, .as_double_matrix(X_new, arg = "X_new"))
},
#' @description Restore \code{X} to its original values (un-center/un-scale).
#'
#' @return Invisible \code{self}.
restore = function() {
if (inherits(private$X_, "mmap_matrix")) {
pca_restore_mmap(private$cpp_ptr, private$X_)
} else {
pca_restore(private$cpp_ptr, private$X_)
}
invisible(self)
},
#' @description Get the PC score matrix from the \code{fit()} call.
#'
#' @return Score matrix (n x M), or \code{NULL} if \code{fit()} not yet called.
get_scores = function() {
private$result_$Z
},
#' @description Get loading matrix from the \code{fit()} call.
#'
#' @return Loading matrix (p x M), or \code{NULL} if \code{fit()} not yet called.
get_loadings = function() {
private$result_$V
},
#' @description Get explained variance per component from the \code{fit()} call.
#'
#' @return Numeric vector of length M, or \code{NULL} if \code{fit()} not yet called.
get_explained_variance = function() {
private$result_$explained_variance
},
#' @description Get the column means used for centering.
#'
#' @return Numeric vector of length p. Zero-vector when \code{center = FALSE}.
get_means = function() {
pca_get_means(private$cpp_ptr)
},
#' @description Get the column scaling factors used for normalization.
#'
#' @return Numeric vector of length p. Ones when \code{normalize = FALSE}.
get_norms = function() {
pca_get_norms(private$cpp_ptr)
}
)
)
# ==============================================================================
# MLRidge
# ==============================================================================
#' @title Ridge Regression Solver
#'
#' @description Solves the ridge regression problem
#' \eqn{\min_\beta \|y - X\beta\|^2 + \lambda \|\beta\|^2}
#' for a single regularization value. Dispatches internally between primal
#' (\eqn{n \ge p}) and dual (\eqn{n < p}) Cholesky paths.
#'
#' @details Wraps the C++ \code{MLRidge::solve(X, y, lambda)} static method.
#'
#' @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)
#'
#' @family ML methods
#' @export
MLRidge <- R6::R6Class("MLRidge",
public = list(
#' @description Solve ridge regression for a single \code{lambda}.
#'
#' @param X A numeric matrix (n x p), or an \code{mmap_matrix} (bound
#' zero-copy; \code{"readonly"} suffices).
#' @param y Numeric response vector of length n.
#' @param lambda Non-negative regularization parameter.
#' @param n_threads Integer, the thread budget of the matrix products
#' (\code{NULL}, the default: the library's default budget,
#' \code{\link{trex_get_num_threads}()}, initially 1).
#'
#' @return Coefficient vector of length p.
solve = function(X, y, lambda, n_threads = NULL) {
stopifnot(is.numeric(y), is.numeric(lambda), lambda >= 0)
n_threads <- resolve_n_threads(n_threads)
if (inherits(X, "mmap_matrix")) {
stopifnot(dim(X)[1] == length(y))
return(ridge_solve_mmap(X, as.numeric(y), as.numeric(lambda), n_threads))
}
X <- .as_double_matrix(X)
stopifnot(nrow(X) == length(y))
ridge_solve(X, as.numeric(y), as.numeric(lambda), n_threads)
}
)
)
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.