---
title: "Getting Started with risdr"
output: rmarkdown::html_vignette
bibliography: references.bib
vignette: >
  %\VignetteIndexEntry{Getting Started with risdr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5
)
```

## Purpose

Sufficient dimension reduction seeks a low-dimensional projection
`\mathbf{B}^{\mathsf{T}}\mathbf{X}` that retains the information in the
predictors `\mathbf{X}` about a response `Y`. The working condition is

\[
Y \perp\!\!\!\perp \mathbf{X}\mid \mathbf{B}^{\mathsf{T}}\mathbf{X}.
\]

`risdr` combines classical inverse-regression estimators with covariance
regularisation, structural dimension criteria, prediction, and resampling.
The implemented SDR methods are SIR [@li1991sir], SAVE [@cook1998regression],
DR [@liwang2007dr], and pHd [@li1992phd].

## A reproducible example

```{r}
library(risdr)

sim <- simulate_risdr_data(
  n = 160,
  p = 20,
  d = 2,
  rho = 0.6,
  sigma = 0.7,
  model = "linear_quadratic",
  seed = 2026
)
```

The simulation object contains the predictor matrix, response, true central
subspace basis, sufficient predictors, population covariance matrix, signal,
noise, and generation settings.

```{r}
str(sim[c("X", "y", "beta", "Sigma", "n", "p", "d")], max.level = 1)
```

## Fit an SDR model

```{r}
fit <- fit_risdr(
  X = sim$X,
  y = sim$y,
  sdr_method = "dr",
  cov_method = "oas",
  nslices = 6,
  d_max = 6,
  selector = "cicomp",
  standardize = TRUE,
  stabilize = TRUE
)

fit
summary(fit)
```

The fitted object stores the training transformations, covariance estimate,
kernel, eigenvalues, directions, scores, dimension-selection table, and
downstream linear model.

## Inspect the structural dimension

```{r}
fit$d_table
criterion_weights(fit$d_table, criterion = "CICOMP")
```

Information criteria answer a model-selection question, while predictive
cross-validation estimates out-of-fold error. Both should be considered when
the selected dimension is consequential.

```{r}
cv <- select_dimension_cv(
  X = sim$X,
  y = sim$y,
  sdr_method = "dr",
  cov_method = "oas",
  d_max = 5,
  v = 5,
  nslices = 6,
  metric = "RMSE",
  seed = 2026
)

cv$selected_d
cv$cv_table
```

## Prediction

Prediction applies the training centre, scale, SDR centre, and estimated
directions to new observations before invoking the downstream model.

```{r}
predicted <- predict(fit, sim$X[1:12, , drop = FALSE])
evaluate_prediction(
  y_true = sim$y[1:12],
  y_pred = predicted,
  d = fit$d
)
```

Named columns may be supplied in a different order. They are checked and
reordered to the training layout. A single new observation is also valid.

## Component-specific controls

Arguments for covariance estimation, covariance stabilisation, and SDR kernels
are supplied separately. This prevents a control intended for one component
from being passed to another component.

```{r}
fit_ridge <- fit_risdr(
  X = sim$X,
  y = sim$y,
  sdr_method = "sir",
  cov_method = "ridge",
  d = 2,
  d_max = 5,
  cov_args = list(lambda = 0.15),
  stabilization_args = list(eps = 1e-7),
  sdr_args = list(slice_type = "quantile")
)
```

## Diagnostics

```{r, fig.show="hold"}
plot_scree(fit, n_eigen = 10)
plot_sufficient(fit, direction = 1)
plot_dimension_selection(fit)
```

Loadings and sufficient summary plots are descriptive. Signs of eigenvectors
are not identified, so sign reversals across numerically equivalent fits do not
change the estimated subspace.

## Current scope

The verified modelling interface is for continuous responses. The standalone
MEC covariance helper accepts additional working response forms, but binary,
multiclass, and censored survival modelling are not yet claimed as complete
`risdr` workflows.

## References