---
title: "Getting Started"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Overview

`SelectBoost.quantile` adapts the SelectBoost idea to sparse quantile
regression. A typical workflow is:

1. fit a quantile model with `selectboost_quantile()`,
2. inspect the selection-frequency path,
3. extract a stable support with `summary()` or
   `support_selectboost_quantile()`,
4. optionally tune the penalty explicitly with `tune_lambda_quantile()`.

The current package defaults are designed to be reasonably conservative:
screening is activated automatically in `p > n` settings, tuning can use a
1-SE rule with penalty inflation, and stable support extraction defaults to a
hybrid score that combines path stability and fitted effect size.

## Simulate a correlated design

```{r}
load_selectboost_quantile <- function() {
  if (requireNamespace("SelectBoost.quantile", quietly = TRUE)) {
    library(SelectBoost.quantile)
    return(invisible(TRUE))
  }

  if (!requireNamespace("pkgload", quietly = TRUE)) {
    stop(
      "SelectBoost.quantile is not installed and pkgload is unavailable.",
      call. = FALSE
    )
  }

  roots <- c(".", "..")
  roots <- roots[file.exists(file.path(roots, "DESCRIPTION"))]
  if (!length(roots)) {
    stop("Could not locate the package root for SelectBoost.quantile.", call. = FALSE)
  }

  pkgload::load_all(roots[[1]], export_all = FALSE, helpers = FALSE, quiet = TRUE)
  invisible(TRUE)
}

load_selectboost_quantile()

sim <- simulate_quantile_data(
  n = 100,
  p = 20,
  active = 1:4,
  rho = 0.7,
  correlation = "toeplitz",
  tau = 0.5,
  seed = 1
)
```

## Fit a first model

```{r}
fit <- selectboost_quantile(
  sim$x,
  sim$y,
  tau = 0.5,
  B = 6,
  step_num = 0.5,
  screen = "auto",
  tune_lambda = "cv",
  lambda_rule = "one_se",
  lambda_inflation = 1.25,
  subsamples = 4,
  sample_fraction = 0.5,
  complementary_pairs = TRUE,
  max_group_size = 10,
  seed = 1,
  verbose = FALSE
)

print(fit)
```

The printed object summarizes the perturbation path, tuning choice, screening
rule, and the highest mean selection frequencies.

## Summarize and extract stable support

```{r}
smry <- summary(fit)
smry

support_selectboost_quantile(fit)
coef(fit, threshold = 0.55)
```

By default, `summary()` and `support_selectboost_quantile()` use the hybrid
support score. If you want the older frequency-only rule, use
`selection_metric = "frequency"`.

```{r}
support_selectboost_quantile(
  fit,
  threshold = 0.55,
  selection_metric = "frequency"
)
```

## Plot the frequency path

```{r}
plot(fit)
```

The path can help distinguish variables that remain stable under stronger
perturbations from variables that are selected only when the perturbation is
weak.

## Formula interface and multiple quantiles

```{r}
dat <- data.frame(y = sim$y, sim$x)

fit_formula <- selectboost_quantile(
  y ~ .,
  data = dat,
  tau = c(0.25, 0.5, 0.75),
  B = 4,
  step_num = 0.5,
  tune_lambda = "bic",
  seed = 2,
  verbose = FALSE
)

print(fit_formula)
summary(fit_formula, tau = 0.5)
```

Predictions can be extracted from either matrix- or formula-based fits.

```{r}
predict(
  fit_formula,
  newdata = dat[1:3, -1, drop = FALSE],
  tau = 0.5
)
```

## Inspect penalty tuning directly

```{r}
tuned <- tune_lambda_quantile(
  sim$x,
  sim$y,
  tau = 0.5,
  method = "cv",
  rule = "one_se",
  lambda_inflation = 1.25,
  nlambda = 6,
  folds = 3,
  repeats = 2,
  seed = 3,
  verbose = FALSE
)

print(tuned)
summary(tuned)
```

## Next steps

- Use `vignette("validation-study", package = "SelectBoost.quantile")` to see
  how the current selector compares with the lasso baselines on the shipped
  benchmark study.
- Use `benchmark_quantile_selection()` if you want to evaluate the method on a
  different simulation grid.