- Undocumented Matlab - https://undocumentedmatlab.com -
Undocumented scatter plot jitter
Posted By Yair Altman On June 6, 2012 | 4 Comments
Yesterday I started presenting a multi-day Matlab training course [1] for some client. As I was preparing the data visualization segment, I planned to show a programmatic implementation of scatterplot jitter when I came across an undocumented built-in implementation of exactly this mechanism, that I will describe today.
In a scatter plot, we cannot easily minor value differences, when the data points overlap each other. For example:
% Prepare the data
groupX = ones(1,100) * 30;
groupY = ones(1,100) * 24;
singletonsX = [20,40];
singletonsY = [18,32];
dataX = [groupX,singletonsX];
dataY = [groupY,singletonsY];
% Display in a scatterplot
scatter(dataX, dataY);
xlim([0,50]);
ylim([0,40]);
The solution that is generally used in such cases is to either use some other plot type to convey the density information (e.g., histograms, CDF or quantile plots), or to keep using scatter plots but jitter the data just a tiny bit that would enable users to visualize the density more clearly. Jittering the data introduces minor inaccuracies to the data, which some may find anathema, but it does solve the visualization problem:
jitterAmount = 0.5;
jitterValuesX = 2*(rand(size(dataX))-0.5)*jitterAmount; % +/-jitterAmount max
jitterValuesY = 2*(rand(size(dataY))-0.5)*jitterAmount; % +/-jitterAmount max
scatter(dataX+jitterValuesX, dataY+jitterValuesY);
Interestingly, Matlab’s scatterplot has this mechanism built-in, using the undocumented hidden properties Jitter (default=’off’) and JitterAmount (default=0.2). Note that JitterAmount is an absolute (not relative) value, just as in my example above. Also, the built-in jitter only applies to the X data and does not jitter the Y values. Jitter is also applied only to 2D (not 3D) scatter plots:
scatter(dataX, dataY, 'jitter','on', 'jitterAmount',0.5);
The jitter implementation is provided in %matlabroot%/toolbox/matlab/specgraph/@specgraph/@scattergroup/refresh.m lines 16-18 (in R2012a):
if ~is3D && strcmp(this.Jitter,'on')
x = x + (rand(size(x))-0.5)*(2*this.JitterAmount);
end
As you can see, it is trivially easy to modify this code to include Y-data jitter, or to make JitterAmount a relative rather than an absolute value. If you wish to use separate JitterAmounts for X and Y, change the definition of JitterAmount from ‘double’ to ”MATLAB array’ in %matlabroot%/toolbox/matlab/specgraph/@specgraph/@scattergroup/schema.m line 43:
hProp = schema.prop(hClass, 'Jitter', 'on/off');
hProp.Description = 'Enable/disable jittering';
hProp.FactoryValue = 'off';
hProp.Visible = 'off';
markDirtyProp = Lappend(markDirtyProp,hProp);
hProp = schema.prop(hClass, 'JitterAmount', 'double'); % Change this, 'double' => 'MATLAB Array'
hProp.Description = 'Maximum amount of jitter';
hProp.FactoryValue = .2;
hProp.Visible = 'off';
markDirtyProp = Lappend(markDirtyProp,hProp);
For the record, here is a list of the other hidden properties of scatterplot. This list can be retrieved using my getundoc utility [2]:
>> hggroup = scatter(dataX, dataY);
>> getundoc(hggroup)
ans =
ALimInclude: 'on'
ApplicationData: [1x1 struct]
Behavior: [1x1 struct]
CLimInclude: 'on'
Dirty: 'clean'
EraseMode: 'normal'
HelpTopicKey: ''
IncludeRenderer: 'on'
Initialized: 1
Jitter: 'on'
JitterAmount: 0.51
PixelBounds: [0 0 0 0]
RefreshMode: 'auto'
Serializable: 'on'
XLimInclude: 'on'
YLimInclude: 'on'
ZLimInclude: 'on'
Of these properties, the following are unique to scatter plots: Dirty, Initialized, Jitter, JitterAmount, RefreshMode. The rest are common to all Handle Graphic objects.
You may also be interested in the article I posted a few years ago about another undocumented scatterplot behavior [3].
Categories: Handle graphics, Low risk of breaking in future versions, Stock Matlab function, Undocumented feature
Article printed from Undocumented Matlab: https://undocumentedmatlab.com
URL to article: https://undocumentedmatlab.com/articles/undocumented-scatter-plot-jitter
URLs in this post:
[1] Matlab training course: http://undocumentedmatlab.com/training/
[2] getundoc utility: http://www.mathworks.com/matlabcentral/fileexchange/32934-getundoc-get-undocumented-object-properties
[3] undocumented scatterplot behavior: http://undocumentedmatlab.com/blog/undocumented-scatter-plot-behavior/
[4] Undocumented scatter plot behavior : https://undocumentedmatlab.com/articles/undocumented-scatter-plot-behavior
[5] Undocumented plot marker types : https://undocumentedmatlab.com/articles/undocumented-plot-marker-types
[6] Accessing hidden HG2 plot functionality : https://undocumentedmatlab.com/articles/hidden-hg2-plot-functionality
[7] Accessing plot brushed data : https://undocumentedmatlab.com/articles/accessing-plot-brushed-data
[8] Performance: scatter vs. line : https://undocumentedmatlab.com/articles/performance-scatter-vs-line
[9] Plot LimInclude properties : https://undocumentedmatlab.com/articles/plot-liminclude-properties
Click here to print.
Copyright © Yair Altman - Undocumented Matlab. All rights reserved.
4 Comments To "Undocumented scatter plot jitter"
#1 Comment By the cyclist On June 6, 2012 @ 07:28
I suspect that the reason the jitter is only in the X direction is that jitter is a (documented) feature for the boxplot command, where the points beyond the whisker can be jittered side-to-side.
#2 Comment By Felix On November 8, 2012 @ 09:50
Its a pitty, there is no jitter propterty for the “errorbars” plot, becuse I want to create a scatterplot consisting of mean data points.
#3 Comment By Jake On February 23, 2018 @ 04:50
Any ideas of how to use this jitter functionality with gscatter?
#4 Comment By Yair Altman On February 24, 2018 @ 19:55
@Jake – gscatter creates
line
objects, which do not have Jitter properties as inscatter
objects. If you want to use the jitter functionality, use scatter rather than gscatter.