---
title: "An introduction to the spinebil package"
vignette: >
  %\VignetteIndexEntry{An introduction to the spinebil package}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
---

## About

The `spinebil` package provides tools to explore and evaluate the behavior of *Projection Pursuit Index (PPI)* functions using *tour methods*, specifically focusing on interpolated paths and line graphs. It offers a structured approach to assessing how different PPI functions behave when applied to data with known structure and noise, by tracing their values along controlled transitions between projection planes.

Projection pursuit is a powerful technique in multivariate statistics that seeks "interesting" low-dimensional projections of high-dimensional data. These projections are identified by optimizing an index function designed to highlight structure such as clustering, outliers, or non-Gaussianity.

The methods implemented in `spinebil` are described in detail in [this paper](https://doi.org/10.1007/s00180-020-00954-8), and the package builds on prior work such as the tourr package.

## Installation
The package can be installed from CRAN using: 

```r
install.packages("spinebil")
```

You can install the development version from [GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("uschiLaa/spinebil")
```

## Purpose

The main goal of `spinebil` is to:

- Provide a framework for systematically comparing PPI functions.
- Facilitate visual diagnostics of index behavior.
- Enable reproducible experiments with simulated data to understand how well indices detect meaningful structure versus random noise.

## Example

To evaluate the index behaviour on a known input distribution we can trace its value when interpolating a tour path, for example moving from nuisance and structured projection.

```{r example}
library(spinebil)
## sample from the spiral distribution
d <- spiral_data(100, 4)
## the first two parameters are noise
## parameters 3 and 4 contain a spiral
## we write a list with the nuisance and structured plane
m <- list(basis_matrix(1,2,4), basis_matrix(3,4,4))
## the index functions to be evaluated should also be passed in a list
index_list <- list(tourr::holes(), tourr::cmass())
index_labels <- c("holes", "cmass")
## we can now compute the index traces and plot them
trace <- get_trace(d, m, index_list, index_labels)
plot_trace(trace)
```

## Usage

`spinebil` is particularly useful for researchers and developers designing new projection pursuit indices or wanting to better understand the strengths and weaknesses of existing ones. By using tour-based visual diagnostics, it helps bridge the gap between statistical rigor and exploratory data analysis.