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

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

The "woylier" package provides alternative method for generating a tour path by interpolating between d-D frames in p-D space rather than d-D planes. A tour path is a sequence of projection and we use interpolation method to produce the path. The \CRANpkg{tourr} package uses geodesic interpolation between planes. Geodesic interpolation path is the locally shortest path between planes with no within-plane spin. As a result of this method, the rendered target plane could be the rotated version of the target plane we wanted. This is not a problem when the structure we are looking can be identified without turning the axis around. 

The "woylier" package implements the Givens interpolation paths method proposed by [Buja et al. (2005)](https://doi.org/10.1016/S0169-7161(04)24014-7) in R. This algorithm adapts Given’s matrix decomposition technique which allows the interpolation to be between frames rather than planes.

# Installation

You can install the development version of woylier from GitHub with:

```{r eval=FALSE}
# install.packages("remotes")
remotes::install_github("numbats/woylier")
```

```{r setup}
library(woylier)
library(geozoo)
library(ggplot2)
library(dplyr)
library(purrr)
```

# Path 1

In this example, we have 2 random 1D basis in 6D data space and the `givens_full_path()` function returns the intermediate interpolation step projections in given number of steps. The code chunk below demonstrates the interpolation between 2 random basis in 5 steps.

```{r}
# Generate 1D example

set.seed(2022)
p <- 6
base1 <- tourr::basis_random(p, d=1)
base2 <- tourr::basis_random(p, d=1)

base1

base2

givens_full_path(base1, base2, nsteps = 5)
```

# Path 2

In this example, we have 2 random 2D basis in 6D data space and the `givens_full_path()` function returns the intermediate interpolation step projections in given number of steps. The code chunk below demonstrates the interpolation between 2 random basis in 5 steps.

```{r}
# Generate 2D example

set.seed(2022)
p <- 6
base3 <- tourr::basis_random(p, d=2)
base4 <- tourr::basis_random(p, d=2)

base3

base4

givens_full_path(base3, base4, nsteps = 5)
```
 
# Examples

To see how to use this for examining projections of multivariate data, see [Batsaikhan, Cook, Laa (2024)](https://doi.org/10.48550/arXiv.2311.08181).