File Exchange

image thumbnail

plot spread points (beeswarm plot)

version (12.8 KB) by Jonas
plotSpread plots distributions of data points, adding jitter to the points to avoid overlap.


Updated 11 Feb 2017

View Version History

View License

Editor's Note: This file was selected as MATLAB Central Pick of the Week

plotSpread allows creating "beeswarm plots", i.e. point distributions where jitter has been added to the data points to avoid overlap.
It further allows specifying groups within the data to show the distribution of the groups inside a distribution.
plotSpread is most suited to visualizing distributions with small amounts of data points. If the points become too dense, it becomes difficult to appreciate the relative importance of modes of a distribution, in which case "distributionPlot" should be used.

plotSpread uses the excellent "distinguishable_colors" to choose default colors for different categories.

In addition, the .zip file contains "myErrorbar" (a modification of the built-in errorbar), "repeatEntries" for easy repetition of entries in a list, and "isEven" to test whether a number is even. For both "repeatEntries" and "isEven" there are better alternatives on the File Exchange.

Cite As

Jonas (2021). plot spread points (beeswarm plot) (, MATLAB Central File Exchange. Retrieved .

Comments and Ratings (37)

Jonathan Elliott

To change marker size, I simply edited line 500 in plotSpread to include 'MarkerSze',16

Maite AzcorraSedano

Awesome funcion, but I wish there was an option to change the MarkerSize

wei li

Jose Rego Terol

Does anyone know how to rotate the xlabel and how to colour each label group in the base of the colour marker?
I've changed the font size of the label (line 521):
switch opt.xyOri
case 'normal'
switch opt.xMode
case 'manual'
if ~isempty(opt.xNames)

However, I cannot rotate the labels and colour them in the base of the colour markers.

emiko shishido

Chi Pham

Hi there,
I have 3 groups of data A,B, and C and I want to plot A and B under the same category with different colors/markers. How do I do that?


Love the code and use it often, but I just came across a small problem. binWidth allows you to set the minimum Y-axis distance at which points will be spread, but since it only takes a single input, it is only really useful when plotting linear data. I'm trying to plot data with a log-scale y axis, and setting a single binWidth value will make points below 1 spread very far apart and give points above 1 a narrow spread. Is there an easy fix for converting binWidth as a log function?


Michael Ashby

Thanks for this useful function. I would like to specify colours individually for each marker. I have 1x5 cell array of data input, so tried a matching giving input to 'distributionColors' as either as 1x5 cell array or as a 3 column vector with total length of all points but get error message 'please submit one color per distribution (5 dist, 256 colors)'. Any suggestions on best way to do this/correct colour data format would be greatly appreciated. Thanks.


Andreas Passos

Hello, I run the recommended example:

data = {randn(25,1),randn(100,1),randn(300,1)};
figure,plotSpread(data,[],[],{'25 pts','100 pts','300 pts'})

and the following error appears:

Error using plotSpread (line 170)
please add option categoryLabels to old syntax

Error in Untitled2 (line 4)
figure,plotSpread(data,[],[],{'25 pts','100 pts','300 pts'})

any suggestions please?


Samuel Acuna

Jason Tran

This is a great and helpful code! I chose 'o', 's', 'd', and '^' as my markers. but how do I go about filling them in? currently they're empty shape markers. Also I'd like to adjust the marker size but it seems like the line below isn't working for me. How would I go about changing the marker size and filling in the markers? Thanks.

set(findall(3,'type','line','color','k'),'markerSize',16) %Change marker size


Toru Takumi


Great contribution, very appreciated!

A suggestion: currently it seems that points that are closer to the left/right margins of the distribution are plotted after the ones that are closer to the vertical line around which the distribution is centered. In one of my cases where I plotted lots of points (~ 2000) with the round marker ('o'), this resulted in the graphically not very pleasing effect that the points in the center occluded each other but the ones along the left/right margin were positioned "on top" of the, admittedly, very busy distribution. I am aware that it's probably not ideal to plot that many points, but in case one wants to it might be better to first plot the individual points from outside->in and not inside->out. Hope that was not too confusing...

Brad Stiritz

Thanks for your work, this is a nice start. Dot plot / beeswarm plot is sorely needed in Matlab!

If you are thinking about doing any further work on this function, would you please take a look at Aron Eklund's beeswarm package for R, at the URL below?

In particular, would you please consider implementing his "square" plot option? This does not generate random jitter, which is distracting in many contexts. It is much easier on the eyes and brain to visually process the "square" beeswarm plot.

Also, Matlab now generates perceptually uniform colors out of the box, via function parula (R2014b and later). If possible, appropriate code changes there would be appreciated as well, please.

Ricardo Falcon Perez


Hello, I have a big question: is there a way to connect points between different conditions?

Pierre Mégevand

A very good function that allows a variety of plots and fills a gap in the plotting abilities of MATLAB.



@Rainer, Eric: As plotSpread returns the handles to the points, you can change the marker color like so: handles=plotSpread(yourData); set(handles{1},'color','r'); Use another string, or a [r,g,b] array to choose a different color.


I had the same problem, and I got around it by tricking the function into using two categories, where the second category is empty. I made an addtional row of NaN on the input data, then made a categoryIdx vector of all zeros, except set the end value to one. This makes the plot technically have 2 categories, though the second category is completely empty and not plotted. Then you just use categoryColor to set your color to whatever color you need.


Great submission. I found that there is no way to specify marker colors if there is only ONE group? It always defaults to blue.


@Sneha: plotSpread(data, 'showMM', 5) shows standard deviation, plotSpread(data, 'showMM', 4) shows standard error of the mean.


Is there a way to add errorbars to the plotSpread graphs?


@Yuri: Thank you for the hint. I'll look into fixing this.

Yuri K

I found that distinguishable_colors function requires makecform function from Image Processing Toolbox. Not every installation has it.


To change marker size programmatically, you can use the function "findall" to get the handles for the spots. Say you want to set the marker size to 16 of the black markers, and the figure number is 3, you could write



Thanks for the script!!Is really useful but can you tell me how I change the marker size in your script?




Good script !! Can you implement plotting the mean, median, errorbar, or others with categoryIdx? if yes, how?



It works now !!!
Thanks a lot.


@peter: "ismatrix" only appeared in 2010b. I've tried and failed to install 2009b today, so I wasn't able to make sure that I haven't included another incompatible function call. Have you been able to test the new version?


I am actually running 2010a, but I still do not have it ?


ismatrix is a built-in function from a release later than R2009b - sorry for the mis-labeling of plotSpread. I am replacing ismatrx and I'll upload a fixed version soon


I tested your example and got the following:
I think you forgot to include "ismatrix" function ?
??? Undefined function or method 'ismatrix' for input arguments of type

Error in ==> plotSpread at 196
elseif ismatrix(data)

MATLAB Release Compatibility
Created with R2009b
Compatible with any release
Platform Compatibility
Windows macOS Linux

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!