Title: Alternative Tour Frame Interpolation Method
Version: 0.0.9
Description: This method generates a tour path by interpolating between d-D frames in p-D using Givens rotations. The algorithm arises from the problem of zeroing elements of a matrix. This interpolation method is useful for showing specific d-D frames in the tour, as opposed to d-D planes, as done by the geodesic interpolation. It is useful for projection pursuit indexes which are not s invariant. See more details in Buj, Cook, Asimov and Hurley (2005) <doi:10.1016/S0169-7161(04)24014-7> and Batsaikhan, Cook and Laa (2023) <doi:10.48550/arXiv.2311.08181>.
Depends: R (≥ 4.1)
Imports: tourr, geozoo, dplyr, tibble
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.3.2
Suggests: knitr, rmarkdown, purrr, ggplot2, ash, testthat (≥ 3.0.0)
Config/testthat/edition: 3
URL: https://numbats.github.io/woylier/, https://github.com/numbats/woylier
BugReports: https://github.com/numbats/woylier/issues
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2024-09-29 05:29:18 UTC; cookd
Author: Zola Batsaikan ORCID iD [aut], Dianne Cook ORCID iD [aut, cre], Ursula Laa ORCID iD [aut]
Maintainer: Dianne Cook <dicook@monash.edu>
Repository: CRAN
Date/Publication: 2024-10-01 09:40:02 UTC

woylier: Alternative Tour Frame Interpolation Method

Description

logo

This method generates a tour path by interpolating between d-D frames in p-D using Givens rotations. The algorithm arises from the problem of zeroing elements of a matrix. This interpolation method is useful for showing specific d-D frames in the tour, as opposed to d-D planes, as done by the geodesic interpolation. It is useful for projection pursuit indexes which are not s invariant. See more details in Buj, Cook, Asimov and Hurley (2005) doi:10.1016/S0169-7161(04)24014-7 and Batsaikhan, Cook and Laa (2023) doi:10.48550/arXiv.2311.08181.

Author(s)

Maintainer: Dianne Cook dicook@monash.edu (ORCID)

Authors:

See Also

Useful links:

Overlay paths of interpolation on the sphere

Description

Overlay paths of interpolation on the sphere

Usage

add_path(proj_space, path)

Arguments

proj_space

n number of points on the surface of sphere

path

interpolated path

Value

data frame with interpolated path and points on sphere surface

Examples

p <- 4
base1 <- tourr::basis_random(p, d=1)
base2 <- tourr::basis_random(p, d=1)
path <- woylier::givens_full_path(base1, base2, nsteps=10)
sp <- woylier::generate_space_view(p=p)
sp_path <- woylier::add_path(sp, path)
tourr::animate_xy(sp_path[,1:4], col=sp_path$type)

Compute the angle between 2d vectors 360 degrees

Description

Compute the angle between 2d vectors 360 degrees

Usage

angle2(x, y)

Arguments

x

vector with length 2

y

vector with length 2

Value

angle in radians

Calculate angles of required rotations to map Wz to Wa

Description

Calculate angles of required rotations to map Wz to Wa

Usage

calculate_angles(Wa, Wz)

Arguments

Wa

starting preprojected frame

Wz

target preprojected frame

Value

named list of angles

Reconstruct interpolated frames using pre-projection

Description

Reconstruct interpolated frames using pre-projection

Usage

construct_moving_frame(Wt, B)

Arguments

Wt

A givens path by stepfraction

B

pre-projection px2d matrix

Value

A frame of on the step of interpolation

Construct preprojected frames

Description

Construct preprojected frames

Usage

construct_preframe(Fr, B)

Arguments

Fr

Orthonormal frame

B

pre-projection px2d matrix

Value

Preprojected 2dxd frame on preprojection space (first dxd entry of this matrix is identity matrix by construction)

Generate the background sphere or torus

Description

Generate the background sphere or torus

Usage

generate_space_view(n = 1000, p = 3, d = 1)

Arguments

n

number of points on the sphere

p

dimension of data

d

dimension of projection

Value

n number of points on the surface of sphere

Examples

p <- 4
sp <- generate_space_view(p=p)

Construct full interpolated frames

Description

Construct full interpolated frames

Usage

givens_full_path(Fa, Fz, nsteps)

Arguments

Fa

starting pxd frame

Fz

target pxd frame

nsteps

number of steps of interpolation

Value

array with nsteps+1 matrices. Each matrix is interpolated frame in between starting and target frames.

Examples

p <- 4
base1 <- tourr::orthonormalise(tourr::basis_random(p, d=1))
base2 <- tourr::orthonormalise(tourr::basis_random(p, d=1))
path <- woylier::givens_full_path(base1, base2, nsteps=10)

Calculate information needed for Givens interpolation The methodology is outlined in http://www-stat.wharton.upenn.edu/~buja/PAPERS/paper-dyn-proj-algs.pdf

Description

Calculate information needed for Givens interpolation The methodology is outlined in http://www-stat.wharton.upenn.edu/~buja/PAPERS/paper-dyn-proj-algs.pdf

Usage

givens_info(Fa, Fz)

Arguments

Fa

starting frame, will be orthonormalized if necessary

Fz

target frame, will be orthonormalized if necessary

Interpolation format for tourr

Description

Generates the interpolation in the form needed for tourr, modelled on geodesic_path()

Usage

givens_path(current, target, frozen = NULL, ...)

Arguments

current

starting frame

target

target frame

frozen

indicator whether some dimensions fixed

...

arguments sent to later functions

Value

interpolate

A function with single parameter in [0, 1] that returns an interpolated frame between the current and future frames. 0 gives the current plane, 1 gives the new target frame in plane of current frame.

dist

The distance, in radians, between the current and target frames.

Fa

The current frame.

Fz

The new target frame.

tau

The principle angles between the current and target frames.

Ga

The current plane.

Gz

The target plane.

It implements series of Givens rotations that maps Wa to Wz

Description

It implements series of Givens rotations that maps Wa to Wz

Usage

givens_rotation(Wa, angles, stepfraction)

Arguments

Wa

starting preprojected frame

angles

angles of required rotations to map Wz to Wa

stepfraction

for the interpolation of rotations

Value

Givens path by stepfraction in pre-projected space

Step along a Givens interpolated path by fraction of path length.

Description

Step along a Givens interpolated path by fraction of path length.

Usage

givens_step_fraction(interp, fraction)

Arguments

interp

interpolated path

fraction

fraction of distance between start and end frames

Create a grand tour with Givens interpolation

Description

Create a grand tour with Givens interpolation

Usage

grand_tour_givens(d = 2, ...)

Arguments

d

dimension of projection

...

additional parameters to pass through

Value

creates grand tour

Examples

data(sine_curve)
tourr::animate(sine_curve, woylier::grand_tour_givens(), tourr::display_xy())

Create a guided tour with Givens interpolation

Description

Create a guided tour with Givens interpolation

Usage

guided_tour_givens(
  index_f,
  d = 2,
  alpha = 0.5,
  cooling = 0.99,
  max.tries = 25,
  max.i = Inf,
  optim = "search_geodesic",
  n_sample = 100,
  ...
)

Arguments

index_f

the index function to optimize.

d

target dimensionality

alpha

the initial size of the search window, in radians

cooling

the amount the size of the search window should be adjusted by after each step

max.tries

the maximum number of unsuccessful attempts to find a better projection before giving up

max.i

the maximum index value, stop search if a larger value is found

optim

character indicating the search strategy to use: search_geodesic, search_better, search_better_random, search_polish. Default is search_geodesic.

n_sample

number of samples to generate if search_f is search_polish

...

arguments sent to the search_f

Value

creates guided tour

Examples

data(sine_curve)
tourr::animate_xy(sine_curve, guided_tour_givens(tourr::splines2d()), sphere=FALSE)

Path needed for tour with Givens interpolation

Description

Path needed for tour with Givens interpolation

Usage

new_givens_path(name, generator, frozen = NULL, ...)

Arguments

name

name to give tour path

generator

basis generator function

frozen

matrix giving frozen variables, as described in freeze

Value

creates path for Givens interpolation

A planned tour path using frame-to-frame interpolation.

Description

The planned tour takes you from one basis to the next in a set order. Once you have visited all the planned bases, you either stop or start from the beginning once more (if cycle = TRUE).

Usage

planned_tour_givens(basis_set, cycle = FALSE)

Arguments

basis_set

the set of bases as a list of projection matrices or a 3d array

cycle

cycle through continuously (TRUE) or stop after first pass (FALSE)

Details

Usually, you will not call this function directly, but will pass it to a method that works with tour paths like tour::animate(), tourr::save_history() or tourr::render().

Value

creates planned tour path

See Also

The tourr::little_tour(), a special type of planned tour which cycles between all axis parallel projections.

Examples

library(tourr)
twod <- save_history(flea[, 1:3], max = 5)
str(twod)
tourr::animate_xy(flea[, 1:3], woylier::planned_tour_givens(twod))
tourr::animate_xy(flea[, 1:3], woylier::planned_tour_givens(twod, TRUE))
oned <- tourr::save_history(flea[, 1:6], tourr::grand_tour(1), max = 3)
tourr::animate_dist(flea[, 1:6], woylier::planned_tour_givens(oned))

Build a d-dimensional pre-projection space by orthonormalizing Fz with regard to Fa

Description

Build a d-dimensional pre-projection space by orthonormalizing Fz with regard to Fa

Usage

preprojection(Fa, Fz)

Arguments

Fa

starting pxd frame

Fz

ending pxd frame

Value

B pre-projection px2d matrix

Takes i and k-th row of a matrix and rotate matrix by theta angle (requires matrix a to be 2*q matrix)

Description

Takes i and k-th row of a matrix and rotate matrix by theta angle (requires matrix a to be 2*q matrix)

Usage

row_rot(a, i, k, theta)

Arguments

a

matrix

i

row

k

row that we want to zero the element

theta

angle between them

Value

rotated matrix a refer to Algorithm 5.1.6 of Matrix computation (Golub, Van)

Simulated 6D data with a sine curve

Description

The data has 6 columns, labelled V1-V6, where the sine curve is in V5, V6. The other columns are normal samples.

Format

A 500x6 data frame

Examples

library(woylier)
data(sine_curve)
plot(sine_curve$V5, sine_curve$V6)