# swarmx: Adjust 1-d data to separate coincident points In beeswarm: The Bee Swarm Plot, an Alternative to Stripchart

## Description

Take a series of points lying in a horizontal or vertical line, and jitter them in the other dimension such that no points are overlapping.

## Usage

 ``` 1 2 3 4 5 6 7 8 9 10 11 12``` ```swarmx(x, y, xsize = xinch(0.08, warn.log = FALSE), ysize = yinch(0.08, warn.log = FALSE), log = NULL, cex = par("cex"), side = 0L, priority = c("ascending", "descending", "density", "random", "none"), fast = TRUE, compact = FALSE) swarmy(x, y, xsize = xinch(0.08, warn.log = FALSE), ysize = yinch(0.08, warn.log = FALSE), log = NULL, cex = par("cex"), side = 0L, priority = c("ascending", "descending", "density", "random", "none"), fast = TRUE, compact = FALSE) ```

## Arguments

 `x, y` Coordinate vectors in any format supported by `xy.coords`. `xsize, ysize` Width and height of the plotting character in user coordinates. `log` Character string indicating which axes are logarithmic, as in `plot.default`, or `NULL` to figure it out automatically. `cex` Relative plotting character size. `side` Direction to perform jittering: 0: both directions; 1: to the right or upwards; -1: to the left or downwards. `priority` Method used to perform point layout (see below). `fast` Use compiled version of algorithm? This option is ignored for all methods except `"swarm"` and `"compactswarm"`. `compact` Use compact layout? (see below)

## Details

For `swarmx`, the input coordinates must lie in a vertical line. For `swarmy`, the input coordinates must lie in a horizontal line.

`swarmx` adjusts coordinates to the left or right; `swarmy` adjusts coordinates up or down.

`priority` controls the order in which the points are placed; this has generally has a noticeable effect on the resulting appearance. `"ascending"` gives the "traditional" beeswarm plot in which the points are placed in an ascending order. `"descending"` is the opposite. `"density"` prioritizes points with higher local density. `"random"` places points in a random order. `"none"` places points in the order provided.

When `compact` is FALSE, points are placed in a predetermined order. When `compact` is TRUE, a greedy strategy is used to determine which point will be placed next. This often leads to a more tightly-packed layout. The strategy is very simple: on each iteration, a point that can be placed as close as possible to the non-data axis is chosen and placed. If there are two or more equally good points, `priority` is used to break ties.

Usually it makes sense to call this function after a plotting device has already been set up (e.g. when adding points to an existing plot), so that the default values for `xsize`, `ysize`, and `log` will be appropriate.

## Value

A data frame with columns `x` and `y` with the new coordinates.

`beeswarm`, `jitter`
 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21``` ``` ## Plot points in one dimension index <- rep(0, 100) values <- rnorm(100) plot(index, values, xlim = c(-0.5, 2.5)) points(swarmx(index + 1, values), col = 2) points(swarmx(index + 2, values, cex = 1.5), col = 3, cex = 1.5) ## Try the horizontal direction, with a log scale plot(values, index, log = "x", ylim = c(-1, 2)) points(swarmy(values, index + 1), col = 2) ## Newer examples using "side", "priority", and "compact" plot(c(-0.5, 3.5), range(values), type = 'n') points(swarmx(index + 0, values), col = 1) points(swarmx(index + 0.9, values, side = -1), col = 2) points(swarmx(index + 1.1, values, side = 1, priority = "descending"), col = 3) points(swarmx(index + 2 , values, priority = 'density'), col = 4) points(swarmx(index + 3 , values, priority = 'random'), col = 5) points(swarmx(index + 3 , values, priority = 'random', compact = TRUE), col = 5) ```