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(`

plots the variables `tbl`

,`xvar`

,`yvar`

)`xvar`

and `yvar`

from the table
`tbl`

. To plot one data set, specify one variable for
`xvar`

and one variable for `yvar`

. To plot multiple
data sets, specify multiple variables for `xvar`

,
`yvar`

, or both. If both arguments specify multiple variables, they must
specify the same number of variables.

`swarmchart(`

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

,___)

`swarmchart(___,`

specifies additional properties for the swarm chart using one or more name-value
arguments. Specify the properties after all other input arguments. For example:`Name,Value`

)

`swarmchart(x,y,'LineWidth',2)`

creates a swarm chart with 2-point marker outlines.`swarmchart(tbl,'MyX','MyY','ColorVariable','MyColors')`

creates a swarm chart from data in a table, and customizes the marker colors using data from the table.

For a list of properties, see Scatter Properties.

`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.