<!-- README.md is generated from README.Rmd. Please edit that file -->

# moveEZ <img src="man/figures/logo.png" align="right" width="150"/>

`moveEZ` (pronounced *move easy*) extends the
[biplotEZ](https://CRAN.R-project.org/package=biplotEZ) package to
animate PCA biplots across the ordered levels of a categorical variable.
Rather than producing a separate static biplot per level, which
fragments sequential information and makes gradual structural change
difficult to perceive, `moveEZ` renders transitions between levels as a
continuous animation.

## Installation

Install the released version from CRAN:

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

Or install the development version from GitHub:

```r
# install.packages("devtools")
devtools::install_github("MuViSU/moveEZ")
```

## Overview

`moveEZ` animates PCA biplots across the ordered levels of a categorical
variable — referred to as the **time variable**. This variable need not
represent chronological time; it may be any ordered index such as
experimental stages, algorithmic iterations, or measurement occasions.
Each distinct level of the time variable defines a **time slice**: the
subset of observations corresponding to that level.

The package provides three animation functions of increasing
methodological complexity:

| Function | PCA computed | Variable vectors | Alignment |
|---|---|---|---|
| `moveplot()` | Once, on full dataset | Fixed | Not required |
| `moveplot2()` | Per time slice | Dynamic | Manual (`align.time`, `reflect`) |
| `moveplot3()` | Per time slice | Dynamic | Automated (GPA) |

All three functions support animated output (`move = TRUE`) and static
faceted output (`move = FALSE`).

## Basic usage

```r
library(moveEZ)
library(biplotEZ)

data("Africa_climate")

bp <- biplot(Africa_climate, scaled = TRUE) |>
  PCA(group.aes = Africa_climate$Region) |>
  samples(opacity = 0.8) |>
  plot()

# Static faceted display
bp |> moveplot(time.var = "Year", group.var = "Region",
               hulls = TRUE, move = FALSE)

# Animated display
bp |> moveplot(time.var = "Year", group.var = "Region",
               hulls = TRUE, move = TRUE)
```

## Learn more

- **Vignette**: a full applied demonstration of all three functions,
  including animated outputs, evaluation measures, and aesthetic
  customisation - `vignette("moveEZ")`. Also consult the package [website](https://muvisu.github.io/moveEZ/).
- **Paper**: the [preprint](https://arxiv.org/abs/2605.22284) provides the complete
  methodology, including the theoretical motivation for
  each framework.

## Report bugs and get support

If you encounter any issues or have questions, please open an issue on
the [GitHub repository](https://github.com/MuViSU/moveEZ/issues).

## About the logo

Logo concept developed with assistance from OpenAI's ChatGPT
(<https://openai.com/chatgpt>); final design by Raeesa and Johané.
