R: Adjust 1-d data to separate coincident points

swarmx {beeswarm} | R Documentation

## Adjust 1-d data to separate coincident points

### 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

    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.

### See Also

`beeswarm`, `jitter`

### Examples

    ## 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)

[Package beeswarm version 0.4.0 Index]