Package {risdr}

risdr: Regularised and Information-Theoretic Sufficient Dimension Reduction

Description

The package implements SIR, SAVE, DR, and pHd for continuous responses, together with covariance regularisation, information-theoretic structural dimension selection, prediction, resampling, simulation, and diagnostic utilities.

Main interface

Use fit_risdr() to estimate an SDR model and predict.risdr() to obtain predictions for new observations. Use select_dimension_cv(), select_dimension_cv_icomp(), or select_dimension_ladle() for complementary structural-dimension diagnostics.

Scope

fit_risdr() retains its continuous-response scope. Use fit_risdr_sparse() for joint dimension and sparsity selection with continuous, categorical, and right-censored survival responses, or fit_risdr_dual() for sample-space PCA reduction when predictors outnumber observations. fit_risdr_sparse_realdata() adds variance screening. See the sparse-survival vignette for the frozen thesis conventions.

Author(s)

Maintainer: Kabir Olorede kabirolorede@gmail.com

See Also

Useful links:

• https://github.com/ilovemaths/risdr

• https://ilovemaths.github.io/risdr/

• Report bugs at https://github.com/ilovemaths/risdr/issues

C1F complexity and induced adaptive weights

Description

Computes cumulative scale-invariant covariance complexity from leading eigenvalues and converts the complexity profile to relative weights.

Usage

C1F(evals, positive_only = TRUE, cumulative = TRUE, tol = 1e-10)

Arguments

Value

A list with C1F values, induced weights, and processed eigenvalues.

Adjusted coefficient of determination

Description

Adjusted coefficient of determination

Usage

adjusted_r_squared(y_true, y_pred, d)

Arguments

Value

Numeric adjusted R-squared.

Examples

adjusted_r_squared(
  c(2, 4, 6, 8, 10),
  c(2.2, 3.8, 5.7, 8.1, 9.8),
  d = 1
)

AR(1) covariance matrix

Description

AR(1) covariance matrix

Usage

ar1_covariance(p, rho)

Arguments

Value

Covariance matrix.

Examples

ar1_covariance(p = 4, rho = 0.5)

Check predictor matrix

Description

Internal function for validating predictor input.

Usage

check_X(X, min_rows = 5L, min_cols = 2L)

Arguments

Value

A numeric matrix.

Check covariance matrix

Description

Internal function for validating covariance matrix input.

Usage

check_cov_matrix(Sigma)

Arguments

Value

A numeric square symmetric matrix.

Check covariance method

Description

Check covariance method

Usage

check_cov_method(method)

Arguments

Value

Matched covariance method.

Validate a cross-validation design

Description

Validate a cross-validation design

Usage

check_cv_design(n, v, minimum_required = 5L)

Arguments

Value

Checked fold count and minimum training-set size.

Check dimension arguments

Description

Check dimension arguments

Usage

check_dimensions(d = NULL, d_max = 10, p, n = NULL)

Arguments

Value

A list containing checked d and d_max.

Validate a logical flag

Description

Validate a logical flag

Usage

check_flag(x, name)

Arguments

Value

The validated logical value.

Check missing values

Description

Internal function for detecting missing values.

Usage

check_missing(X, y)

Arguments

Value

Invisibly returns TRUE if no missing values are found.

Validate a named argument list

Description

Validate a named argument list

Usage

check_named_list(x, name)

Arguments

Value

The validated list.

Check new predictor observations

Description

Validates predictor input used only for projection or prediction. Unlike check_X(), this helper permits a single observation.

Usage

check_new_X(X, min_cols = 1L)

Arguments

Value

A numeric matrix.

Check number of slices

Description

Check number of slices

Usage

check_nslices(nslices, n)

Arguments

Value

Integer number of slices.

Check prediction vectors

Description

Check prediction vectors

Usage

check_prediction_vectors(y_true, y_pred)

Arguments

Value

Invisibly TRUE.

Check SDR method

Description

Check SDR method

Usage

check_sdr_method(method)

Arguments

Value

Matched SDR method.

Check selector

Description

Check selector

Usage

check_selector(selector)

Arguments

Value

Matched selector.

Validate slice labels

Description

Validate slice labels

Usage

check_slice_labels(slices, n)

Arguments

Value

Positive integer slice labels.

Check stabilisation method

Description

Check stabilisation method

Usage

check_stabilization_method(method)

Arguments

Value

Matched stabilisation method.

Check continuous response vector

Description

Internal function for validating continuous response input.

Usage

check_y_continuous(y, n)

Arguments

Value

Numeric response vector.

Choose dimension from criteria table

Description

Choose dimension from criteria table

Usage

choose_dimension(
  d_table,
  selector = c("cicomp", "icomp", "bic", "caic", "aic")
)

Arguments

Value

Selected structural dimension.

Examples

scores <- as.matrix(mtcars[, c("wt", "hp", "disp")])
dimension_table <- select_dimension(scores, mtcars$mpg, d_max = 2)
choose_dimension(dimension_table, selector = "bic")

Compute Directional Regression

Description

Computes Directional Regression using the canonical pairwise-slice formulation.

Usage

compute_dr(
  X,
  y,
  Sigma = NULL,
  nslices = 6,
  slice_type = c("quantile", "equal_width"),
  stabilize_slices = TRUE,
  stabilization = c("eigenfloor", "ridge", "nearest_pd"),
  eps = 1e-08
)

Arguments

Details

Directional Regression is computed using the pairwise-slice formulation.

M_{DR} = \sum_h \sum_k p_h p_k (2I_p - A_{hk}) (2I_p - A_{hk})^\top

where

A_{hk} = \Sigma_h + \Sigma_k + (\mu_h - \mu_k) (\mu_h - \mu_k)^\top

Value

A list containing DR kernel, eigenvalues, directions, scores, and slices.

Examples

X <- as.matrix(mtcars[, c("disp", "hp", "wt")])
fit <- compute_dr(X, y = mtcars$mpg, nslices = 4)
head(fit$eigenvalues)

Compute one reduced-model information criterion

Description

Compute one reduced-model information criterion

Usage

compute_ic(
  y,
  Z,
  criterion = c("cicomp", "icomp", "aic", "caic", "bic"),
  response_type = c("continuous", "categorical", "survival"),
  delta = NULL,
  n_active = NULL,
  support_penalty = FALSE,
  tol = 1e-10
)

Arguments

Value

Scalar criterion value.

Compute all reduced-model information criteria

Description

Compute all reduced-model information criteria

Usage

compute_ic_values(
  y,
  Z,
  response_type = c("continuous", "categorical", "survival"),
  delta = NULL,
  n_active = NULL,
  support_penalty = FALSE,
  tol = 1e-10
)

Arguments

Value

Named numeric vector containing AIC, BIC, CAIC, ICOMP, CICOMP, log-likelihood, effective df, and C1F.

Compute model selection criteria

Description

Computes AIC, BIC, CAIC, ICOMP, and CICOMP for a fitted linear model.

Usage

compute_information_criteria(fit, complexity = c("C1", "C1F"), eps = 1e-10)

Arguments

Value

Named numeric vector of criteria.

Examples

fit <- stats::lm(mpg ~ wt + hp, data = mtcars)
compute_information_criteria(fit)

Compute adaptive penalty weights from C1F variable contributions

Description

For mode = "c1f", the regularised covariance matrix is decomposed into original-coordinate C1F contributions. Variables with larger contribution receive smaller soft-threshold weights, matching the direction of the historical C1F weighting rule while avoiding the invalid mapping of eigenvalue indices directly to predictor indices. inverse_c1f reverses that weighting. uniform returns equal weights.

Usage

compute_penalty_weights(
  Sigma,
  mode = c("c1f", "inverse_c1f", "uniform"),
  tol = 1e-10
)

Arguments

Value

Numeric vector of variable-level penalty weights with mean one.

Compute Principal Hessian Directions

Description

Compute Principal Hessian Directions

Usage

compute_phd(X, y, Sigma = NULL, eps = 1e-08)

Arguments

Value

A list containing pHd kernel, eigenvalues, directions, scores.

Examples

X <- as.matrix(mtcars[, c("disp", "hp", "wt")])
fit <- compute_phd(X, y = mtcars$mpg)
head(fit$eigenvalues)

Compute Sliced Average Variance Estimation

Description

Compute Sliced Average Variance Estimation

Usage

compute_save(
  X,
  y,
  Sigma = NULL,
  nslices = 6,
  slice_type = c("quantile", "equal_width"),
  stabilize_slices = TRUE,
  stabilization = c("eigenfloor", "ridge", "nearest_pd"),
  eps = 1e-08
)

Arguments

Value

A list containing SAVE kernel, eigenvalues, directions, scores, and slices.

Examples

X <- as.matrix(mtcars[, c("disp", "hp", "wt")])
fit <- compute_save(X, y = mtcars$mpg, nslices = 4)
head(fit$eigenvalues)

Compute SDR scores for new data

Description

Projects new predictor observations onto estimated SDR directions.

Usage

compute_scores(newX, directions)

Arguments

Value

Matrix of SDR scores.

Examples

X <- as.matrix(mtcars[1:5, c("wt", "hp", "disp")])
directions <- diag(3)[, 1:2, drop = FALSE]
compute_scores(X, directions)

General SDR kernel dispatcher

Description

General SDR kernel dispatcher

Usage

compute_sdr(
  X,
  y,
  method = c("dr", "sir", "save", "phd"),
  Sigma = NULL,
  nslices = 6,
  ...
)

Arguments

Value

SDR fit components.

Examples

X <- as.matrix(mtcars[, c("disp", "hp", "wt")])
Sigma <- cov_oas(X)
fit <- compute_sdr(
  X,
  y = mtcars$mpg,
  method = "sir",
  Sigma = Sigma,
  nslices = 4
)
dim(fit$scores)

Compute Sliced Inverse Regression

Description

Compute Sliced Inverse Regression

Usage

compute_sir(
  X,
  y,
  Sigma = NULL,
  nslices = 6,
  slice_type = c("quantile", "equal_width"),
  eps = 1e-08
)

Arguments

Value

A list containing SIR kernel, eigenvalues, directions, scores, and slices.

Examples

X <- as.matrix(mtcars[, c("disp", "hp", "wt")])
fit <- compute_sir(X, y = mtcars$mpg, nslices = 4)
head(fit$eigenvalues)

Covariance complexity C1

Description

Computes Bozdogan-type maximal covariance complexity.

Usage

cov_complexity_C1(Sigma, eps = 1e-10)

Arguments

Value

Numeric complexity value.

Scale-invariant covariance complexity C1F

Description

Computes the scale-invariant C1F covariance complexity measure.

Usage

cov_complexity_C1F(Sigma, eps = 1e-10)

Arguments

Value

Numeric complexity value.

Covariance condition number

Description

Computes the spectral condition number of a covariance matrix.

Usage

cov_condition_number(Sigma, eps = 1e-12)

Arguments

Value

Numeric condition number.

Examples

Sigma <- cov(mtcars[, c("disp", "hp", "wt")])
cov_condition_number(Sigma)

Covariance eigenvalue summary

Description

Provides diagnostic eigenvalue summaries for a covariance matrix.

Usage

cov_diagnostics(Sigma, tol = 1e-06)

Arguments

Value

A list of covariance diagnostics.

Examples

Sigma <- cov(mtcars[, c("disp", "hp", "wt")])
cov_diagnostics(Sigma)

Effective covariance rank

Description

Computes the number of eigenvalues exceeding a threshold.

Usage

cov_effective_rank(Sigma, tol = 1e-06)

Arguments

Value

Effective rank.

Examples

Sigma <- cov(mtcars[, c("disp", "hp", "wt")])
cov_effective_rank(Sigma)

Ledoit-Wolf type covariance estimator

Description

Computes a practical Ledoit-Wolf type shrinkage estimator toward a scaled identity target.

Usage

cov_lw(X)

Arguments

Value

A covariance matrix.

Examples

X <- as.matrix(mtcars[, c("disp", "hp", "wt")])
Sigma <- cov_lw(X)
attr(Sigma, "shrinkage")

Maximum Entropy Covariance estimator

Description

Computes a maximum-entropy motivated covariance estimator for SDR.

Usage

cov_mec(
  X,
  y,
  nslices = 6,
  response_type = c("continuous", "categorical", "survival"),
  delta = NULL,
  alpha = NULL,
  eps = 1e-06,
  ...
)

Arguments

Details

The estimator uses response slicing to obtain slice-specific covariance matrices, selects the covariance matrix with maximum log-determinant entropy, and combines it with the pooled covariance matrix through convex shrinkage.

For censored survival responses, the function accepts delta and applies a survival-aware response construction before slicing.

Value

A covariance matrix with attributes containing the shrinkage weight and entropy diagnostics.

Examples

X <- as.matrix(mtcars[, c("disp", "hp", "wt")])
Sigma <- cov_mec(X, y = mtcars$mpg, nslices = 4)
attr(Sigma, "alpha")
attr(Sigma, "entropy_slice")

Oracle Approximating Shrinkage covariance estimator

Description

Computes a simplified Oracle Approximating Shrinkage (OAS) covariance estimator for stabilising the sample covariance matrix.

Usage

cov_oas(X)

Arguments

Value

A covariance matrix.

Examples

X <- as.matrix(mtcars[, c("disp", "hp", "wt")])
Sigma <- cov_oas(X)
attr(Sigma, "shrinkage")

Ridge-type covariance estimator

Description

Computes a convex shrinkage covariance estimator of the form

\Sigma_{\lambda} = (1 - \lambda)S + \lambda T,

where S is the sample covariance matrix and T is a scaled identity target.

Usage

cov_ridge(X, lambda = 0.1)

Arguments

Value

A covariance matrix.

Examples

X <- as.matrix(mtcars[, c("disp", "hp", "wt")])
cov_ridge(X, lambda = 0.2)

Sample covariance matrix

Description

Computes the usual unbiased sample covariance matrix.

Usage

cov_sample(X)

Arguments

Value

A covariance matrix.

Examples

X <- as.matrix(mtcars[, c("disp", "hp", "wt")])
cov_sample(X)

Information criterion weights

Description

Computes relative weights from any information criterion column.

Usage

criterion_weights(
  d_table,
  criterion = c("AIC", "BIC", "CAIC", "ICOMP", "CICOMP")
)

Arguments

Value

Data frame with criterion differences and weights.

Examples

scores <- as.matrix(mtcars[, c("wt", "hp", "disp")])
dimension_table <- select_dimension(scores, mtcars$mpg, d_max = 2)
criterion_weights(dimension_table, criterion = "BIC")

Eigen-decompose SDR kernel

Description

Eigen-decompose SDR kernel

Usage

decompose_kernel(M, sort_by_abs = FALSE)

Arguments

Value

A list with kernel, eigenvalues, directions.

Dual PCA score construction for p much larger than n

Description

Constructs low-rank sample-space scores without forming a p by p covariance matrix. This is useful when the number of predictors is very large.

Usage

dual_pca_scores(
  X,
  dual_rank = NULL,
  variance_explained = NULL,
  center = TRUE,
  scale_X = TRUE,
  eps = 1e-10
)

Arguments

Value

A list containing scores, loadings, singular values, centre, scale, and retained rank.

General covariance estimator dispatcher

Description

Dispatches to the requested covariance estimator. For MEC, the function supports continuous, categorical, and censored survival responses by passing response_type and delta to cov_mec().

Usage

estimate_cov(
  X,
  y = NULL,
  method = c("sample", "ridge", "oas", "lw", "mec"),
  nslices = 6,
  response_type = c("continuous", "categorical", "survival"),
  delta = NULL,
  ...
)

Arguments

Value

A covariance matrix.

Examples

X <- as.matrix(mtcars[, c("disp", "hp", "wt")])

estimate_cov(X, method = "oas")
estimate_cov(
  X,
  y = mtcars$mpg,
  method = "mec",
  nslices = 4
)

Evaluate predictions

Description

Computes common prediction metrics.

Usage

evaluate_prediction(y_true, y_pred, d = NULL)

Arguments

Value

A data frame of prediction metrics.

Examples

evaluate_prediction(
  y_true = c(2, 4, 6, 8, 10),
  y_pred = c(2.2, 3.8, 5.7, 8.1, 9.8),
  d = 1
)

Repeated cross-validation for predictive assessment

Description

Repeats V-fold cross-validation for a fixed SDR and covariance-estimator combination. Failed folds are retained with diagnostic messages.

Usage

evaluate_prediction_cv(
  X,
  y,
  sdr_method = c("dr", "sir", "save", "phd"),
  cov_method = c("sample", "ridge", "oas", "lw", "mec"),
  d,
  v = 5,
  repeats = 10,
  nslices = 6,
  standardize = TRUE,
  stabilize = TRUE,
  stabilization = c("eigenfloor", "ridge", "nearest_pd"),
  seed = NULL,
  cov_args = list(),
  stabilization_args = list(),
  sdr_args = list(),
  ...
)

Arguments

Value

A list containing a one-row summary and fold-level results.

Extract SDR loadings

Description

Extract SDR loadings

Usage

extract_loadings(directions, variables = NULL)

Arguments

Value

A data frame of loadings.

Filter low-variance predictors

Description

Removes predictors with variance below a specified quantile.

Usage

filter_low_variance(X, variance_quantile = 0.25)

Arguments

Value

Filtered matrix.

Fit downstream regression model on SDR scores

Description

Fits a linear regression model using the first d SDR scores.

Usage

fit_downstream_lm(scores, y, d)

Arguments

Value

A fitted lm object.

Examples

scores <- as.matrix(mtcars[, c("wt", "hp")])
fit_downstream_lm(scores, y = mtcars$mpg, d = 2)

Fit regularised and information-theoretic SDR model

Description

Fits sufficient dimension reduction models with optional covariance regularisation and information-theoretic structural dimension selection.

Usage

fit_risdr(
  X,
  y,
  sdr_method = c("dr", "sir", "save", "phd"),
  cov_method = c("sample", "ridge", "oas", "lw", "mec"),
  stabilize = TRUE,
  stabilization = c("eigenfloor", "ridge", "nearest_pd"),
  nslices = 6,
  d = NULL,
  d_max = 10,
  selector = c("cicomp", "icomp", "bic", "caic", "aic"),
  standardize = TRUE,
  complexity = c("C1", "C1F"),
  cov_args = list(),
  stabilization_args = list(),
  sdr_args = list(),
  ...
)

Arguments

Value

An object of class "risdr".

Examples

simulated <- simulate_risdr_data(
  n = 60,
  p = 6,
  d = 2,
  seed = 2026
)

fit <- fit_risdr(
  X = simulated$X,
  y = simulated$y,
  sdr_method = "sir",
  cov_method = "oas",
  nslices = 4,
  d = 1,
  d_max = 3
)

fit

Fit dual high-dimensional RISDR

Description

Constructs a low-rank PCA score representation, fits the unified RISDR core in that score space, maps the dense and selected sparse SDR directions back to the original predictor coordinates, and ranks variables using the Euclidean loading norm across only the selected sparse directions.

Usage

fit_risdr_dual(
  X,
  y,
  delta = NULL,
  response_type = c("continuous", "categorical", "survival"),
  dual_rank = 100L,
  variance_explained = NULL,
  d = NULL,
  d_max = 10L,
  nslices = 4L,
  sdr_method = c("dr", "sir", "save", "phd"),
  cov_method = c("mec", "oas", "lw", "sample", "ridge"),
  selector = c("cicomp", "icomp", "aic", "caic", "bic"),
  lambda_grid = seq(0, 0.3, length.out = 10L),
  adapt_weights = TRUE,
  weight_mode = c("c1f", "inverse_c1f", "uniform"),
  support_penalty = FALSE,
  standardize_dual = TRUE,
  gene_select_top = NULL,
  gene_select_quantile = 0.99,
  center = TRUE,
  scale_X = TRUE,
  verbose = TRUE,
  ...
)

Arguments

Details

The inner RISDR standardisation scale is explicitly undone before mapping directions through the PCA loadings. The returned reduced predictors are taken directly from the fitted core and are therefore exactly aligned with the model used for information-criterion selection.

This entry point uses the frozen sparse thesis engine. The existing fit_risdr() and fit_risdr_realdata() interfaces retain their continuous-response behaviour from version 0.3.1. Survival fits use Efron Cox partial likelihood. Apparent fit statistics and loading ranks are exploratory and do not establish external predictive validity.

Value

An object of class risdr_dual.

Examples

set.seed(2026)
X <- matrix(rnorm(80 * 6), 80)
colnames(X) <- paste0("G", 1:6)
time <- rexp(80, rate = exp(0.5 * X[, 1]))
delta <- rep(c(0L, 1L), 40)
fit <- fit_risdr_dual(
  X, time, delta = delta, response_type = "survival",
  sdr_method = "sir", cov_method = "oas", nslices = 4,
  dual_rank = 4, verbose = FALSE, d_max = 2, lambda_grid = c(0, 0.05)
)
fit$d
predict(fit, X[1:2, , drop = FALSE], type = "risk")

Fit RISDR to real high-dimensional data

Description

Fit RISDR to real high-dimensional data

Usage

fit_risdr_realdata(
  X,
  y,
  delta = NULL,
  response_type = c("continuous", "binary", "multiclass", "survival"),
  variance_quantile = 0.25,
  d = NULL,
  ...
)

Arguments

Value

Fitted RISDR workflow object.

Fit regularised and information-theoretic sufficient dimension reduction

Description

Fits an SDR model using a regularised covariance estimator, a selected inverse-regression kernel, adaptive sparse direction estimation, and information-criterion profiling jointly over structural dimension and sparsity tuning parameter.

Usage

fit_risdr_sparse(
  X,
  y,
  delta = NULL,
  response_type = c("continuous", "categorical", "survival"),
  sdr_method = c("dr", "sir", "save", "phd"),
  cov_method = c("mec", "oas", "lw", "sample", "ridge", "user"),
  stabilize = TRUE,
  stabilization = c("eigenfloor", "ridge", "nearest_pd"),
  nslices = 6L,
  d = NULL,
  d_max = 10L,
  selector = c("cicomp", "icomp", "bic", "caic", "aic"),
  standardize = TRUE,
  complexity = "C1F",
  lambda_grid = seq(0, 0.3, length.out = 10L),
  adapt_weights = TRUE,
  weight_mode = c("c1f", "inverse_c1f", "uniform"),
  penalty_weights = NULL,
  support_penalty = FALSE,
  cov_fun = NULL,
  shrinkage = 1e-04,
  tol = 1e-10,
  ...
)

Arguments

Details

For d = NULL, every candidate dimension from 1 through d_max is evaluated over the complete lambda_grid. The requested selector then chooses the final ⁠(d, lambda)⁠ pair. For explicit d, the same audit grid is retained but the final dimension is fixed and only lambda is selected within that dimension.

This entry point uses the frozen sparse thesis engine. The existing fit_risdr() and fit_risdr_realdata() interfaces retain their continuous-response behaviour from version 0.3.1. Survival fits use Efron Cox partial likelihood. Apparent fit statistics and loading ranks are exploratory and do not establish external predictive validity.

Value

An object of class risdr containing the complete ⁠(d, lambda)⁠ selection grid, profiled dimension table, selected sparse directions, reduced predictors, covariance diagnostics, and compatibility fields.

Examples

set.seed(2026)
X <- matrix(rnorm(80 * 6), 80)
colnames(X) <- paste0("G", 1:6)
time <- rexp(80, rate = exp(0.5 * X[, 1]))
delta <- rep(c(0L, 1L), 40)
fit <- fit_risdr_sparse(
  X, time, delta = delta, response_type = "survival",
  sdr_method = "sir", cov_method = "oas", nslices = 4,
  d_max = 2, lambda_grid = c(0, 0.05)
)
fit$d
predict(fit, X[1:2, , drop = FALSE], type = "risk")

Fit RISDR to real high-dimensional data

Description

Fit RISDR to real high-dimensional data

Usage

fit_risdr_sparse_realdata(
  X,
  y,
  delta = NULL,
  response_type = c("continuous", "binary", "multiclass", "categorical", "survival"),
  variance_quantile = 0.25,
  ...
)

Arguments

Details

This entry point uses the frozen sparse thesis engine. The existing fit_risdr() and fit_risdr_realdata() interfaces retain their continuous-response behaviour from version 0.3.1. Survival fits use Efron Cox partial likelihood. Apparent fit statistics and loading ranks are exploratory and do not establish external predictive validity.

Value

Fitted RISDR workflow object. Fit RISDR to a real-data predictor matrix

Applies outcome cleaning, low-variance screening, the unified RISDR core, and descriptive loading-based variable ranking. The wrapper returns the reduced predictors computed by the core itself so that centring and standardisation are not silently bypassed.

"multiclass", "categorical", or "survival". low-variance screen.

An object of class risdr_realdata.

Fit sparse SDR directions over a lambda grid

Description

Accepts either an explicit dense direction matrix or a historical kernel object containing directions or vectors.

Usage

fit_sparse_grid(
  kernel_obj = NULL,
  directions = NULL,
  d = 2L,
  lambda_grid = seq(0, 0.5, length.out = 25L),
  penalty_weights = NULL,
  adapt_weights = FALSE,
  Sigma = NULL,
  weight_mode = c("c1f", "inverse_c1f", "uniform"),
  tol = 1e-10
)

Arguments

Value

Sparse-grid object.

Generate SDR signal

Description

Generate SDR signal

Usage

generate_signal(
  U,
  model = c("linear_quadratic", "symmetric", "interaction", "linear")
)

Arguments

Value

Numeric signal vector.

Mean absolute error

Description

Mean absolute error

Usage

mae(y_true, y_pred)

Arguments

Value

Numeric MAE.

Examples

mae(c(2, 4, 6, 8), c(2.2, 3.8, 5.7, 8.1))

Create cross-validation folds

Description

Create cross-validation folds

Usage

make_cv_folds(n, v = 5, seed = NULL)

Arguments

Value

Integer vector of fold memberships.

Create response slices

Description

Constructs response slices for inverse regression-based sufficient dimension reduction methods.

Usage

make_slices(y, nslices = 6, type = c("quantile", "equal_width"))

Arguments

Value

Integer vector of slice memberships.

Examples

slices <- make_slices(mtcars$mpg, nslices = 4)
table(slices)

Construct true central subspace basis

Description

Construct true central subspace basis

Usage

make_true_beta(
  p,
  d,
  beta_type = c("coordinate", "random_sparse", "random_dense")
)

Arguments

Value

A p x d orthonormal basis matrix.

Mean absolute percentage error

Description

Mean absolute percentage error

Usage

mape(y_true, y_pred)

Arguments

Value

Numeric MAPE.

Examples

mape(c(2, 4, 6, 8), c(2.2, 3.8, 5.7, 8.1))

Matrix inverse square root

Description

Computes the inverse square root of a symmetric positive definite matrix.

Usage

matrix_inv_sqrt(Sigma, eps = 1e-08)

Arguments

Value

Matrix inverse square root.

Plot cross-validation dimension selection result

Description

Plot cross-validation dimension selection result

Usage

plot_cv_dimension(cv, metric = NULL, ...)

Arguments

Value

Invisibly returns the CV table.

Plot dimension selection criteria

Description

Plot dimension selection criteria

Usage

plot_dimension_selection(
  fit,
  criteria = c("AIC", "BIC", "CAIC", "ICOMP", "CICOMP"),
  ...
)

Arguments

Value

Invisibly returns dimension table.

Plot ladle dimension diagnostic

Description

Plot ladle dimension diagnostic

Usage

plot_ladle(ladle, ...)

Arguments

Value

Invisibly returns ladle table.

Plot SDR loadings

Description

Displays the largest absolute loadings for a selected SDR direction.

Usage

plot_loadings(fit, direction = 1, top = 15, ...)

Arguments

Value

Invisibly returns loading table.

Prediction plot

Description

Plots observed versus predicted values.

Usage

plot_prediction(y_true, y_pred, ...)

Arguments

Value

Invisibly returns plotted data.

Residual plot

Description

Plots residuals against predicted values.

Usage

plot_residuals(y_true, y_pred, ...)

Arguments

Value

Invisibly returns plotted data.

Scree plot of SDR eigenvalues

Description

Scree plot of SDR eigenvalues

Usage

plot_scree(fit, n_eigen = 20, type = "b", ...)

Arguments

Value

Invisibly returns eigenvalues plotted.

Sufficient summary plot

Description

Plots the response against a selected SDR direction.

Usage

plot_sufficient(fit, direction = 1, ...)

Arguments

Value

Invisibly returns plotted data.

Two-direction sufficient summary plot

Description

Plots the first two selected SDR scores, optionally coloured by response.

Usage

plot_sufficient2d(
  fit,
  directions = c(1, 2),
  colour_by_y = TRUE,
  groups = 4,
  ...
)

Arguments

Value

Invisibly returns plotted data.

Predict method for risdr objects

Description

Predict method for risdr objects

Usage

## S3 method for class 'risdr'
predict(object, newX, d = NULL, ...)

Arguments

Value

Numeric vector of predictions.

Examples

simulated <- simulate_risdr_data(
  n = 60,
  p = 6,
  d = 2,
  seed = 2026
)

fit <- fit_risdr(
  X = simulated$X,
  y = simulated$y,
  sdr_method = "sir",
  cov_method = "oas",
  nslices = 4,
  d = 1,
  d_max = 3
)

predict(fit, newX = simulated$X[1:5, , drop = FALSE])

Predict from the sparse or dual SDR engine

Description

Projects new observations using the training centring, scaling, and selected directions. Survival predictions are Cox linear predictors or relative risks; they are not predicted survival times.

Usage

## S3 method for class 'risdr_sparse'
predict(
  object,
  newX,
  type = c("response", "scores", "link", "risk", "class", "probs"),
  ...
)

## S3 method for class 'risdr_dual'
predict(
  object,
  newX,
  type = c("response", "scores", "link", "risk", "class", "probs"),
  ...
)

Arguments

Value

Predictions or a score matrix, according to type.

Predict from downstream SDR regression model

Description

Predict from downstream SDR regression model

Usage

predict_downstream_lm(fit_lm, scores_new, d)

Arguments

Value

Numeric vector of predictions.

Prediction correlation

Description

Prediction correlation

Usage

prediction_correlation(y_true, y_pred)

Arguments

Value

Pearson correlation.

Examples

prediction_correlation(
  c(2, 4, 6, 8),
  c(2.2, 3.8, 5.7, 8.1)
)

Prepare survival response

Description

Prepare survival response

Usage

prepare_survival_response(time, delta)

Arguments

Value

Cleaned survival response list.

Print risdr object

Description

Print risdr object

Usage

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

Arguments

Value

Invisibly returns x.

Print method for dual RISDR objects

Description

Print method for dual RISDR objects

Usage

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

Arguments

Print real-data RISDR workflow

Description

Print real-data RISDR workflow

Usage

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

Arguments

Value

Invisibly returns x.

Print risdr object

Description

Print risdr object

Usage

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

Arguments

Value

Invisibly returns x.

Print real-data RISDR workflow

Description

Print real-data RISDR workflow

Usage

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

Arguments

Print summary of risdr object

Description

Print summary of risdr object

Usage

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

Arguments

Value

Invisibly returns x.

Print summary of risdr object

Description

Print summary of risdr object

Usage

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

Arguments

Value

Invisibly returns x.

Projection matrix

Description

Projection matrix

Usage

projection_matrix(B)

Arguments

Value

Projection matrix.

Examples

B <- matrix(c(1, 0, 0, 0, 1, 0), nrow = 3)
projection_matrix(B)

Coefficient of determination

Description

Coefficient of determination

Usage

r_squared(y_true, y_pred)

Arguments

Value

Numeric R-squared.

Examples

r_squared(c(2, 4, 6, 8), c(2.2, 3.8, 5.7, 8.1))

Package imports

Description

Package imports

Root mean squared error

Description

Root mean squared error

Usage

rmse(y_true, y_pred)

Arguments

Value

Numeric RMSE.

Examples

rmse(c(2, 4, 6, 8), c(2.2, 3.8, 5.7, 8.1))

Route component-specific arguments

Description

Separates legacy arguments supplied through ... from explicit covariance, stabilisation, and SDR argument lists. Explicit component lists take precedence over matching legacy arguments.

Usage

route_risdr_args(
  dots,
  cov_method,
  stabilization,
  sdr_method,
  cov_args = list(),
  stabilization_args = list(),
  sdr_args = list()
)

Arguments

Value

A list with cov_args, stabilization_args, and sdr_args.

Helper for row names or fallback names

Description

Helper for row names or fallback names

Usage

rownames_or_names(x, fallback = NULL)

Arguments

Value

Character vector.

Run one SDR simulation replication

Description

Run one SDR simulation replication

Usage

run_one_simulation(
  n = 200,
  p = 50,
  d = 2,
  rho = 0.6,
  sigma = 1,
  model = "linear_quadratic",
  beta_type = "coordinate",
  sdr_method = "dr",
  cov_method = "oas",
  nslices = 6,
  selector = "cicomp",
  d_max = 10,
  seed = NULL
)

Arguments

Value

A data frame with simulation results.

Run SDR simulation study

Description

Run SDR simulation study

Usage

run_risdr_simulation(
  R = 200,
  rho_values = c(0.3, 0.6, 0.9),
  methods = c("sir", "save", "dr", "phd"),
  cov_methods = c("sample", "oas", "mec"),
  seed = NULL,
  ...
)

Arguments

Value

Data frame of simulation results.

Select structural dimension

Description

Fits linear models on SDR scores for candidate dimensions and computes information criteria.

Usage

select_dimension(
  scores,
  y,
  d_max = 10,
  complexity = c("C1", "C1F"),
  eps = 1e-10
)

Arguments

Value

A data frame of criteria by candidate dimension.

Examples

scores <- as.matrix(mtcars[, c("wt", "hp", "disp")])
dimension_table <- select_dimension(
  scores = scores,
  y = mtcars$mpg,
  d_max = 2
)
dimension_table

Cross-validation dimension selection for SDR

Description

Selects structural dimension by V-fold cross-validation. For each candidate dimension, SDR is fitted on the training folds, a downstream linear regression is fitted using the reduced predictors, and prediction error is evaluated on the validation fold.

Usage

select_dimension_cv(
  X,
  y,
  sdr_method = c("dr", "sir", "save", "phd"),
  cov_method = c("sample", "ridge", "oas", "lw", "mec"),
  d_max = 10,
  v = 5,
  nslices = 6,
  standardize = TRUE,
  stabilize = TRUE,
  stabilization = c("eigenfloor", "ridge", "nearest_pd"),
  metric = c("RMSE", "MAE"),
  seed = NULL,
  cov_args = list(),
  stabilization_args = list(),
  sdr_args = list(),
  ...
)

Arguments

Value

A list containing the CV table, selected dimension, and fold-level results.

Complexity-aware cross-validation for structural dimension selection

Description

Combines out-of-fold prediction error with rescaled BIC, CAIC, or CICOMP penalties. The tuning constant lambda controls the contribution of the information-criterion component.

Usage

select_dimension_cv_icomp(
  X,
  y,
  sdr_method = c("dr", "sir", "save", "phd"),
  cov_method = c("sample", "ridge", "oas", "lw", "mec"),
  d_max = 10,
  v = 5,
  nslices = 6,
  standardize = TRUE,
  stabilize = TRUE,
  stabilization = c("eigenfloor", "ridge", "nearest_pd"),
  complexity = c("C1", "C1F"),
  lambda = 1,
  seed = NULL,
  cov_args = list(),
  stabilization_args = list(),
  sdr_args = list(),
  ...
)

Arguments

Value

A list containing selected dimensions, the aggregated cross-validation table, and fold-level results.

Ladle-type structural dimension diagnostic

Description

Computes a simple ladle-type diagnostic by combining normalised eigenvalue information with a bootstrap-based subspace instability measure.

Usage

select_dimension_ladle(
  X,
  y,
  sdr_method = c("dr", "sir", "save", "phd"),
  cov_method = c("sample", "ridge", "oas", "lw", "mec"),
  d_max = 10,
  B = 100,
  nslices = 6,
  standardize = TRUE,
  stabilize = TRUE,
  stabilization = c("eigenfloor", "ridge", "nearest_pd"),
  seed = NULL,
  cov_args = list(),
  stabilization_args = list(),
  sdr_args = list(),
  ...
)

Arguments

Value

A list containing ladle table, selected dimension, and bootstrap distances.

Simulate multivariate normal data

Description

Simulate multivariate normal data

Usage

simulate_mvn(n, Sigma)

Arguments

Value

Numeric matrix.

Simulate SDR data

Description

Simulates data from a sufficient dimension reduction model with an autoregressive covariance structure. The function returns the true orthonormal central subspace basis, which allows simulation studies to evaluate both prediction accuracy and subspace recovery.

Usage

simulate_risdr_data(
  n = 200,
  p = 50,
  d = 2,
  rho = 0.6,
  sigma = 1,
  signal_strength = 1,
  model = c("linear_quadratic", "symmetric", "interaction", "linear"),
  beta_type = c("coordinate", "random_sparse", "random_dense"),
  beta = NULL,
  seed = NULL
)

Arguments

Value

A list containing the simulated predictors, response, true basis, latent sufficient predictors, population covariance matrix, signal, error, and simulation settings.

Examples

simulated <- simulate_risdr_data(
  n = 60,
  p = 6,
  d = 2,
  rho = 0.4,
  seed = 2026
)

dim(simulated$X)
head(simulated$y)
crossprod(simulated$beta)

Compute slice covariance matrices

Description

Computes slice-specific covariance matrices.

Usage

slice_covariances(
  X,
  slices,
  stabilize = TRUE,
  stabilization = c("eigenfloor", "ridge", "nearest_pd"),
  eps = 1e-06
)

Arguments

Value

A list of covariance matrices.

Examples

X <- as.matrix(mtcars[, c("disp", "hp", "wt")])
slices <- make_slices(mtcars$mpg, nslices = 4)
covariances <- slice_covariances(X, slices)
names(covariances)

Compute slice means

Description

Computes slice-specific means of predictors.

Usage

slice_means(X, slices)

Arguments

Value

Matrix of slice means with rows corresponding to slices.

Examples

X <- as.matrix(mtcars[, c("disp", "hp", "wt")])
slices <- make_slices(mtcars$mpg, nslices = 4)
slice_means(X, slices)

Compute slice proportions

Description

Computes empirical slice probabilities.

Usage

slice_proportions(slices)

Arguments

Value

Numeric vector of slice proportions.

Examples

slices <- make_slices(mtcars$mpg, nslices = 4)
slice_proportions(slices)

Slice response for inverse regression

Description

Constructs slice labels for continuous, categorical, or censored survival responses. For censored survival data, double slicing is used by first splitting on censoring status and then slicing observed time within each status group.

Usage

slice_response(
  y,
  nslices = 5L,
  response_type = c("continuous", "categorical", "survival"),
  delta = NULL
)

Arguments

Value

A list containing integer slice labels and metadata.

Summarise response slices

Description

Produces a summary table of slice frequencies and response ranges.

Usage

slice_summary(y, slices)

Arguments

Value

A data frame summarising slices.

Examples

slices <- make_slices(mtcars$mpg, nslices = 4)
slice_summary(mtcars$mpg, slices)

General covariance stabilisation dispatcher

Description

Stabilises a covariance matrix using one of several available methods.

Usage

stabilize_cov(
  Sigma,
  method = c("eigenfloor", "ridge", "nearest_pd"),
  eps = 1e-06,
  lambda = 1e-04,
  keep_diag = TRUE
)

Arguments

Value

A stabilised covariance matrix.

Examples

Sigma <- matrix(c(1, 1, 1, 1), nrow = 2)
stabilize_cov(Sigma, method = "eigenfloor")

Eigenvalue floor stabilisation

Description

Stabilises a symmetric covariance matrix by replacing eigenvalues smaller than a positive threshold with that threshold.

Usage

stabilize_eigenfloor(Sigma, eps = 1e-06)

Arguments

Value

A symmetric positive definite covariance matrix.

Examples

Sigma <- matrix(c(1, 1, 1, 1), nrow = 2)
eigen(stabilize_eigenfloor(Sigma))$values

Nearest positive definite stabilisation

Description

Stabilises a covariance matrix by projecting it to the nearest positive definite matrix using Matrix::nearPD().

Usage

stabilize_nearest_pd(Sigma, keep_diag = TRUE)

Arguments

Value

A symmetric positive definite covariance matrix.

Examples

Sigma <- matrix(c(1, 1, 1, 1), nrow = 2)
eigen(stabilize_nearest_pd(Sigma))$values

Ridge stabilisation of covariance matrix

Description

Stabilises a covariance matrix by adding a positive multiple of the identity matrix.

Usage

stabilize_ridge(Sigma, lambda = 1e-04)

Arguments

Value

A symmetric positive definite covariance matrix.

Examples

Sigma <- matrix(c(1, 1, 1, 1), nrow = 2)
eigen(stabilize_ridge(Sigma))$values

Standardise predictors

Description

Standardise predictors

Usage

standardize_X(X, center = NULL, scale = NULL)

Arguments

Value

A list containing standardised matrix, centre, and scale.

Standardise predictors using covariance matrix

Description

Computes the covariance-standardised predictor matrix.

Usage

standardize_by_cov(X, Sigma, center = NULL, eps = 1e-08)

Arguments

Details

Specifically, this function centres the predictor matrix and multiplies it by the inverse square root of the covariance matrix.

Sigma denotes a positive definite covariance matrix and center denotes the sample mean vector when it is not supplied explicitly.

Value

A list containing standardised predictors and centring vector.

Subspace distance

Description

Computes Frobenius distance between projection matrices.

Usage

subspace_distance(B_hat, B)

Arguments

Value

Numeric subspace distance.

Examples

B <- matrix(c(1, 0, 0, 0, 1, 0), nrow = 3)
transformed <- B %*% diag(c(2, 3))
subspace_distance(transformed, B)

Summarise simulation results

Description

Summarise simulation results

Usage

summarise_simulation(sim_results)

Arguments

Value

Summary data frame.

Summarise sparsity pattern

Description

Summarise sparsity pattern

Usage

summarise_sparsity(V, tol = 1e-08)

Arguments

Value

Sparsity summary.

Summarise risdr object

Description

Summarise risdr object

Usage

## S3 method for class 'risdr'
summary(object, ...)

Arguments

Value

A list summary.

Summary method for dual RISDR objects

Description

Summary method for dual RISDR objects

Usage

## S3 method for class 'risdr_dual'
summary(object, top_n = 20L, ...)

Arguments

Summarise risdr object

Description

Summarise risdr object

Usage

## S3 method for class 'risdr_sparse'
summary(object, ...)

Arguments

Value

A list summary.

Weighted soft-threshold operator

Description

Weighted soft-threshold operator

Usage

weighted_soft_threshold(z, lambda, weights = NULL, tol = 1e-10)

Arguments

Value

Thresholded vector.

Weighted sparse directions from dense SDR directions

Description

Weighted sparse directions from dense SDR directions

Usage

weighted_sparsify_directions(V, lambda, weights = NULL, tol = 1e-10)

Arguments

Value

Sparse direction matrix.