---
title: "Basis and FPCA Workflows"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Basis and FPCA Workflows}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
has_glmnet <- requireNamespace("glmnet", quietly = TRUE)
```

`SelectBoost.FDA` can fit spline-basis and FPCA preprocessing directly from raw
curves, store the fitted transforms, and then reuse the same design/selection
machinery as before.

## Fit preprocessing from raw curves

```{r}
library(SelectBoost.FDA)
data("motion_example", package = "SelectBoost.FDA")

predictors <- list(
  signal = fda_grid(
    motion_example$predictors$signal,
    argvals = motion_example$grid,
    name = "signal",
    unit = "time"
  ),
  nuisance = fda_grid(
    motion_example$predictors$nuisance,
    argvals = motion_example$grid,
    name = "nuisance",
    unit = "time"
  )
)

prep <- fit_fda_preprocessor(
  predictors = predictors,
  scalar_covariates = motion_example$scalar_covariates,
  transforms = list(
    signal = fda_fpca(n_components = 3),
    nuisance = fda_bspline(df = 5, center = TRUE)
  ),
  scalar_transform = fda_standardize()
)

prep
summary(prep)
```

## Build a design with the fitted preprocessor

```{r}
design <- fda_design(
  response = motion_example$response,
  predictors = predictors,
  scalar_covariates = motion_example$scalar_covariates,
  preprocessor = prep,
  family = "gaussian"
)

head(selection_map(design))
selection_map(design, level = "basis")
```

## Fit grouped stability selection

```{r, eval = has_glmnet}
fit <- fit_stability(
  design,
  selector = "glmnet",
  B = 30,
  sample_fraction = 0.5,
  cutoff = 0.6,
  seed = 7
)

fit
summary(fit)
selection_map(fit)
selection_map(fit, level = "basis")
selected(fit, level = "basis")
plot(fit, type = "basis", value = "mean")
```

The basis-level summary is often the most convenient table for reporting:

- `n_components` counts the basis coefficients or FPCA scores in each predictor.
- `selected_components` reports how many exceed the stability threshold.
- `mean_feature_frequency` and `max_feature_frequency` summarize component-wise
  stability within each basis-expanded predictor.

## Interpretation note

For FPCA in particular, scores are often much less correlated than dense raw
grid points. In that setting, grouped stability selection is usually the more
natural default, while `SelectBoost` remains most useful for dense
discretizations or strongly correlated basis systems.