Main Content

Swarm scatter chart

`swarmchart(`

displays
a swarm chart, which is a scatter plot with the points offset (jittered) in the
`x`

,`y`

)`x`

-dimension. The points form distinct shapes, and the outline of each
shape is similar to a violin plot. Swarm charts help you to visualize discrete
`x`

data with the distribution of the `y`

data. At each
location in `x`

, the points are jittered based on the kernel density
estimate of `y`

.

To plot one set of points, specify

`x`

and`y`

as vectors of equal length.To plot multiple sets of points on the same set of axes, specify at least one of

`x`

or`y`

as a matrix.

`swarmchart(___,`

specifies a
different marker than the default marker, which is a circle. Specify `mkr`

)`mkr`

after all the arguments in any of the previous syntaxes.

`swarmchart(___,`

fills in
the markers. Specify the `'filled'`

)`'filled'`

option after all the arguments in any
of the previous syntaxes.

`swarmchart(___,`

specifies additional properties for the swarm chart using one or more
`Name,Value`

)`Name,Value`

pair arguments. Specify the properties after all other input
arguments. For a list of properties, see Scatter Properties.

`swarmchart(`

displays the
swarm chart in the target axes. Specify the axes before all the arguments in any of the
previous syntaxes.`ax`

,___)

`s = swarmchart(___)`

returns the
`Scatter`

object or an array of `Scatter`

objects. Use
`s`

to modify properties of the chart after creating it. For a list of
properties, see Scatter Properties.

The points in a swarm chart are jittered using uniform random values that are weighted by
the Gaussian kernel density estimate of `y`

and the relative number of points
at each `x`

location. This behavior corresponds to the default
`'density'`

setting of the `XJitter`

property on the
`Scatter`

object when you call the `swarmchart`

function.

The maximum spread of points at each `x`

location is 90% of the smallest distance between adjacent `x`

values by
default:

spread = 0.9 * min(diff(unique(x)));

You can control the spread by setting the `XJitterWidth`

property on
the `Scatter`

object.