---
title: "Get started with jugglr"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Get started with jugglr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r setup}
library(jugglr)
```

Juggling sequences can be written in a notation called siteswap. A 3-ball cascade — the first sequence most jugglers learn — is written as "3", where each ball is thrown the same height and caught in the opposite hand three beats later. "531", "423" and "441" are also valid 3-ball juggling patterns, though with balls thrown to different heights, or caught in the same hand that throws them. Each number in a siteswap sequence encodes how many beats until that prop needs to be thrown again. However, not everything that can be written in siteswap is a valid, juggleable pattern. For example, in the sequence "432", the first two props thrown would need to be caught in the same hand at the same time.

**jugglr** lets you create, validate, and visualise siteswap patterns in R.

There are several different types of siteswap, distinguished by their notation: vanilla, synchronous, multiplex, synchronous multiplex, and passing. Each is introduced in the sections below.

In **jugglr**, you define a sequence with the function `siteswap()`, which creates an [S7](https://rconsortium.github.io/S7/) object with class `Siteswap` as well as a child class corresponding to its type: `vanillaSiteswap`, `synchronousSiteswap`, `multiplexSiteswap`, `synchronousMultiplexSiteswap`, or `passingSiteswap`.

Each child class has a `print` method that shows the sequence and whether it is valid.
For valid sequences, it also reports the number of props the pattern requires, its period (how many beats before it repeats), and whether it is symmetrical (i.e. whether both hands do the same thing, just offset in time).
For patterns that aren't valid, it reports why not: either the sequence does not satisfy the average theorem, or it has collisions.

Two visualisation methods work for every class: `timeline()`, which shows the beats on which each prop is thrown and caught, and `ladder()`, which conveys that same information along with which hands the props are thrown from and caught in.
These visualisations are useful both for seeing how valid sequences fit together and for diagnosing why invalid sequences do not work.

## Vanilla siteswap

The simplest form is *vanilla* siteswap: one prop thrown per beat, hands alternating. Create a pattern with `siteswap()`:

```{r vanilla-cascade}
siteswap("3")
```

The print method tells you four things: whether the pattern is valid, how many props it requires, its period (how many beats before it repeats), and whether it's symmetrical — meaning both hands do the same thing, just offset in time.

Here's a trickier pattern:

```{r vanilla-423}
ss_423 <- siteswap("423")
ss_423
```

Still three props, period 3. The 4 is a high self-throw that buys you a moment, the 2 is a low hold, and the 3 is a standard cascade throw. The pattern starts to take shape even from the numbers. And for the jugglers working towards five balls:

```{r vanilla-5}
siteswap("5")
```

### Invalid patterns

Not every sequence of numbers makes a jugglable pattern. jugglr checks validity at construction:

```{r vanilla-invalid}
ss_21 <- siteswap("21")
ss_21
```

Two problems, both reported separately. The average of 2 and 1 is 1.5, which would require 1.5 props — impossible. And even setting that aside, two throws would land on the same beat: a collision. The diagrams in the [visualising patterns](#visualising-patterns) section below make this concrete.

This is genuinely useful when you're inventing patterns. Check the sequence before picking up the clubs.

## Other notation types

Vanilla siteswap is one prop per beat from alternating hands. jugglr handles four more notation types for more complex juggling styles.

### Synchronous siteswap

Both hands throw at the same time, written as pairs in parentheses:

```{r sync}
siteswap("(4,4)")
```

An `x` suffix on a throw value marks it as crossing to the other side. The `*` shorthand indicates the pattern alternates between two states — jugglr expands it into the full sequence:

```{r sync-alt}
siteswap("(4,2x)*")
```

### Multiplex siteswap

Multiple props thrown from one hand simultaneously, with square brackets grouping them:

```{r multiplex}
siteswap("[43]1")
```

### Synchronous multiplex siteswap

Both hands throwing at the same time, with multiplex groups:

```{r sync-multiplex}
siteswap("(4,[42x])*")
```

### Passing siteswap

Patterns for multiple jugglers. The `<A|B>` notation separates each juggler's sequence; `p` on a throw value marks a pass to the other juggler:

```{r passing-p}
siteswap("<3p 3|3p 3>")
```

Six props between two jugglers, each passing on every other throw. Experienced passers often prefer fractional notation, where a `.5` on a throw indicates it's a pass:

```{r passing-frac}
siteswap("<4.5 3 3 | 3 4 3.5>")
```

## Visualising patterns {#visualising-patterns}

A sequence of numbers only tells you so much about a pattern. jugglr provides two diagrams, each revealing different aspects of the same sequence.

Both diagrams colour throws by prop using the colour-blind-friendly [Okabe-Ito palette](https://clauswilke.com/dataviz/color-pitfalls.html#not-designing-for-color-vision-deficiency) (up to seven props, after which ggplot2's default scale takes over). The same colours can be passed to `animate()` for consistency across static and animated views — see the [animation article](animate.html).

Both `timeline()` and `ladder()` return ggplot2 objects, so you can customise them with any standard ggplot2 function:

```{r ggplot-customise, fig.alt="Timeline diagram for the 423 pattern with a custom title added via ggplot2::labs()"}
timeline(ss_423) +
  ggplot2::labs(title = "My favourite three-ball pattern")
```

### Timeline

`timeline()` draws arcs: each arc represents one throw, with height proportional to the throw value, colour-coded by prop. It's roughly what the pattern looks like from the side.

```{r timeline-valid, fig.alt="Timeline arc diagram for the 423 pattern, showing three arcs per cycle colour-coded by prop"}
timeline(ss_423)
```

Follow any single colour to track one prop through the pattern. Each arc shows when it was thrown, how high, and when it lands.

### Ladder diagram

`ladder()` shows the schedule: beats across the axis, with lines connecting throws to catches. Straight lines are self-throws; crossing lines go to the other hand.

```{r ladder-valid, fig.alt="Ladder diagram for the 423 pattern showing throws and catches connected by lines"}
ladder(ss_423)
```

Where the timeline shows the shape of the pattern in the air, the ladder shows the mechanics hand-to-hand.

### Invalid patterns

Both diagrams become most instructive when something goes wrong:

```{r timeline-invalid, fig.alt="Timeline diagram for the invalid 21 pattern, showing a collision where two arcs land on the same beat"}
timeline(ss_21)
```

```{r ladder-invalid, fig.alt="Ladder diagram for the invalid 21 pattern, showing two lines converging at the same beat"}
ladder(ss_21)
```

The collision is visible: two arcs land on the same beat, two lines converge at the same point. The colours show where props appear out of nowhere or need to be in two places at once. This is a useful debugging tool when an invented pattern doesn't feel right — the diagram tells you exactly where it breaks.

### Synchronous patterns

Both diagrams adapt to each notation type. Because synchronous patterns throw from both hands at once, the timeline is drawn two-sided: one hand's arcs sit above a faint centre line and the other's mirror below it, each with its own throw labels.

```{r timeline-sync, fig.alt="Two-sided timeline for the synchronous (4,2x)* pattern, with one hand's arcs above the centre line and the other's mirrored below"}
ss_sync <- siteswap("(4,2x)*")
timeline(ss_sync)
```

The ladder follows suit, numbering only the even beats, since both hands throw together:

```{r ladder-sync, fig.alt="Ladder diagram for the synchronous (4,2x)* pattern, numbered on even beats only"}
ladder(ss_sync)
```

### Multiplex patterns

When a hand throws two identical props at once, their arcs would otherwise land on top of each other. Both diagrams fan such throws apart — to slightly different heights in the timeline, and into separate curves in the ladder — so each prop stays visible:

```{r timeline-multiplex, fig.alt="Timeline for the multiplex [22]2 pattern, with the two simultaneous throws fanned to slightly different heights"}
ss_mult <- siteswap("[22]2")
timeline(ss_mult)
```

```{r ladder-multiplex, fig.alt="Ladder diagram for the multiplex [22]2 pattern, with the two simultaneous throws fanned into separate curves"}
ladder(ss_mult)
```

### Passing patterns

Both diagrams extend naturally to passing patterns, with one lane per juggler:

```{r timeline-passing, fig.alt="Timeline arc diagram for the <3p 3|3p 3> passing pattern, with two juggler lanes and passes arcing between them"}
ss_pass <- siteswap("<3p 3|3p 3>")
timeline(ss_pass)
```

```{r ladder-passing, fig.alt="Ladder diagram for the <3p 3|3p 3> passing pattern, with two juggler rows and passes shown as diagonal lines"}
ladder(ss_pass)
```

Passes appear as arcs (or lines) that cross between the juggler lanes.

### A few options

The `n_cycles` argument controls how many repetitions to show — the default of 3 is usually enough to see the full structure, but increase it to trace individual props further. `ladder()` also accepts `direction = "vertical"` if you prefer that orientation.

## The raw data

If you want to build your own visualisation or work directly with the numbers, `throw_data()` returns the underlying data frame:

```{r throw-data}
throw_data(ss_423)
```

One row per throw: when it was thrown, which hand, the throw value, when and where it lands, and which prop it belongs to. This is the same data that drives the diagrams.

## Animation

jugglr can also produce animated GIFs of patterns via the [JugglingLab](https://jugglinglab.org) server. Here's `423` animated with three colours:

```{r animate-teaser, eval=FALSE}
animate("423", colors = c("#E69F00", "#56B4E9", "#009E73"))
```

```{r animate-gif, echo=FALSE, out.width="40%", fig.alt="Animated GIF of the 423 juggling pattern with three coloured balls"}
knitr::include_graphics("figures/423-animation.gif")
```

The [animation article](https://ellakaye.github.io/jugglr/articles/animate.html) covers the full range of options: colour modes, prop types, speed controls, and how to save animations to disk for use in documents.
