---
title: "Getting Started with fastkqr"
author: "An introductory tutorial with examples"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with fastkqr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

The `fastkqr` package fits kernel quantile regression, non-crossing
kernel quantile regression, and regularized linear quantile regression.
Kernel methods currently support `rbfdot` and `laplacedot`. For
parametric linear quantile regression, use `qr()`.

The examples below use a small synthetic data set so that the vignette
can run quickly during package checks.

```{r}
library(fastkqr)

set.seed(1)
x <- matrix(rnorm(80), 40, 2)
y <- sin(x[, 1]) + 0.5 * x[, 2] + rnorm(40, sd = 0.2)
lambda <- 10^seq(0, -2, length.out = 3)
```

## Kernel Quantile Regression

`kqr()` estimates a kernel quantile regression model over a sequence of
penalty values. The default kernel is `rbfdot`.

```{r}
fit <- kqr(x, y, lambda = lambda, tau = 0.5)
coef_fit <- coef(fit)
pred_fit <- predict(fit, x, x[1:5, , drop = FALSE])
dim(coef_fit)
dim(pred_fit)
```

`cv.kqr()` performs cross-validation over the same lambda path.

```{r}
foldid <- rep(1:3, length.out = nrow(x))
cv_fit <- cv.kqr(x, y, lambda = lambda, tau = 0.5, foldid = foldid)
cv_fit$lambda.min
```

## Non-Crossing Kernel Quantile Regression

`nckqr()` estimates non-crossing kernel quantile regression across
multiple quantile levels. The example below keeps the grid small.

```{r}
tau <- c(0.25, 0.5, 0.75)
lambda1 <- 1
lambda2 <- lambda

fit_nc <- nckqr(
  x, y,
  lambda1 = lambda1,
  lambda2 = lambda2,
  tau = tau
)

coef_nc <- coef(fit_nc, s1 = lambda1, s2 = lambda2[1])
pred_nc <- predict(fit_nc, x, x[1:5, , drop = FALSE],
  s1 = lambda1, s2 = lambda2[1])
dim(coef_nc)
dim(pred_nc)
```

`cv.nckqr()` selects `lambda2` for a fixed `lambda1`.

```{r}
cv_fit_nc <- cv.nckqr(
  x, y,
  lambda1 = lambda1,
  lambda2 = lambda2,
  tau = tau,
  foldid = foldid
)
cv_fit_nc$lambda.min
```

## Regularized Linear Quantile Regression

`qr()` fits a parametric linear quantile regression model. This function
masks `base::qr()`; use `base::qr()` when base QR decomposition is needed.

```{r}
fit_lqr <- qr(x, y, lambda = lambda, tau = 0.5)
coef_lqr <- coef(fit_lqr)
pred_lqr <- predict(fit_lqr, x[1:5, , drop = FALSE])
dim(coef_lqr)
dim(pred_lqr)
```

`cv.qr()` performs cross-validation for the linear model.

```{r}
cv_fit_lqr <- cv.qr(x, y, lambda = lambda, tau = 0.5, foldid = foldid)
cv_fit_lqr$lambda.min
```