squat 0.3.0

An implementation of statistical tools for the analysis of 3D rotation-valued time series and functional data. It relies on pre-existing quaternion data structure provided by the ‘Eigen’ ‘C++’ library.

software
rotation-valued functional data
Author
Affiliation

Aymeric Stamm

Department of Mathematics Jean Leray, UMR CNRS 6629

Published

January 10, 2024

Overview

The goal of squat is to provide extensions of common statistical methods for the analysis of rotation-valued time series and functional data. Three-dimensional rotations can be represented in at least five different ways:

  • \(3\times 3\) symmetric definite positive matrices with unit determinant;
  • pair of axis (3D unit vector) and angle (real) of rotation;
  • Euler angles;
  • Tait-Bryan angles;
  • Unit quaternions.

This package mainly focuses on methods in which rotations are represented via unit quaternions. To this end, it exploits the excellent API for quaternions available as part of the Eigen library.

The package is currently structured into 8 sections:

  • New class for QTS. A collection of functions that define the [qts] class for storing quaterion time series (QTS). It provides tools for centering and standardizing a single QTS and for visualizing a single QTS.
  • New class for QTS sample. A collection of functions that define the [qts_sample] class for storing samples of QTS. It provides tools to (i) randomly sample QTS with Gaussian noise on the QTS logarithm, (ii) center and standarize samples, (iii) compute the mean or median and (iv) visualize samples of QTS.
  • QTS Wrangling. A collection of functions to manipulate QTS: differentiation, straightening, logarithm and exponential maps, reorientation, normalization, resampling, smoothing, hemispherization, moving average.
  • Transformations of QTS. A collection of functions to transform QTS into real-valued time series: (i) distance time series (pointwise geodesic distance between two input QTS at each time point), norm time series, angle time series (angle between the first and other attitudes at each time point) and angular velocity time series.
  • Principal Component Analysis. An S3 specialization of the prcomp() method for QTS samples with visualization tools. It performs PCA in the Lie algebra of the 3-sphere.
  • Clustering. A collection of functions to perform clustering of a sample of QTS. It includes (i) an S3 specialization of the kmeans() method for QTS samples, (ii) an S3 specialization of the hclust() method for QTS samples and (iii) an S3 specialization of the dbscan() method for QTS samples. All clustering algorithms return an object of class qtsclust which can be visualized via S3 specializations of the ggplot2::autoplot() and plot() methods.
  • Distance matrix computation. An S3 specialization of the dist() method for computing a pairwise distance matrix from a QTS sample using either the \(L^2\) distance or a Pearson-based distance or the dynamic time warping metric from time series analysis.
  • Data sets. Two datasets for illustrations, examples and case studies.

Installation

You can install the package directly from CRAN:

install.packages("squat")

or you can choose to install the development version from GitHub:

# install.packages("remotes")
remotes::install_github("LMJL-Alea/squat")

The package has its own webpage: https://lmjl-alea.github.io/squat/.

News in v0.3.0

New features

  • Added S3 specialization of the stats::predict() function for prcomp_qts objects.
  • Added function qts2aats() which allows to switch from quaternion to axis-angle representation of rotations.
  • Added usual operations +, -, * and inverse_qts() for quaternion time series using the Eigen library.

Small improvements

  • Make sure quaternion geodesic mean is not flipped.
  • Fix issues in PCA:
    • avoid numerical overflows due to bad choice of k in gam();
    • improved documentation;
    • Use same number of basis functions in uni- and multivariate decompositions.
  • Updated GHA scripts and README.
  • Fix bug related to Rcpp following RcppCore/Rcpp#1287.