Editor's Note: This file was selected as MATLAB Central Pick of the Week
Given vectors of x-values, y-values, and a vector of label names, lablepoints.m will automatically place all labels appropriately in the plot and output their handles. This function streamlines matlab's builtin text() function and greatly increases its flexibility.
.
xpos = [1,2,3,4]; ypos = [1,4,1,5]; labels = {'Lancaster', 'Cincinnati', 'Sofia', 'Rochester'}
h = labelpoints (xpos, ypos, labels)
.
(optional) Choose where you want your label relative to the data point using initials of compass directions (N, S, E, W, NE, NW, SE, SW, Center).
h = labelpoints (xpos, ypos, labels, 'N')
.
(optional) Add (or subtract) extra space between data points and labels by using a buffer between 0:1
h = labelpoints (xpos, ypos, labels, 'N', 0.15)
.
(optional) Decide whether or not the axis limits should automatically adjust if a label falls out of the axis limits (0/1)
h = labelpoints (xpos, ypos, labels, 'N', 0.15, 1)
.
(optional) Let labelpoints.m identify and label only the outliers in your data. Several outlier methods are available (see help labelpoints)
- Identify and label outliers that are N standard deviations from the mean
- Identify and label outliers that are greater than N times the interquartile range
- Identify and label outliers that are inside or outside of a given bound
- Identify and label outliers that are high residuals from a linear fit of the data.
.
(optional) Easily place texts in a list stacked downward, upward, to the left or right.
h = labelpoints (xpos, ypos, labels, 'N, 'stacked', 'down')
.
(optional) Rotate all labels
h = labelpoints (xpos, ypos, labels, 'rotation', 45)
.
(optional) Specify the font size and color of all labels
h = labelpoints (xpos, ypos, labels, 'FontSize', 12, 'Color', 'r')
.
The help section includes many versatile examples demonstrating labeling with numbers, strings, and symbols. This function is quite flexible as the examples show. There are only three required inputs, 3 optional inputs, and several optional parameters to increase flexibility. The outlier options may require stats toolbox.
Cite As
Adam Danz (2020). labelpoints (https://www.mathworks.com/matlabcentral/fileexchange/46891-labelpoints), MATLAB Central File Exchange. Retrieved .
Comments and Ratings (60)
Updates
| 4.1 | Replaced use of isdatetime() with isa() so older versions of matlab won't cause error. |
|
| 4.0.0.0 | fixed typos. |
|
| 4.0.0.0 | Move definition of 'pairIDX' within the outliers conditional. |
|
| 4.0.0.0 | Added several new optional parameters including interpreter, axHand, fontweight, backgroundColor. Added a new outlier method, "outlier_rand". Allow to specify label colors individually. Adapted sections of code to work with datetime axes. |
|
| 3.0.0.0 | Provided clearer examples and corrected a small problem when stacking text with only 1 element. |
|
| 3.0.0.0 | All changes listed within labelpoints.m under 'change history' starting after 11/15/14.
|
|
| 1.4.0.0 | Improved the 'outliers_N' optional parameter and added the automatic removal of points that have 'inf' value.
|
|
| 1.3.0.0 | There was an error within the optional text rotation parameter.
|
|
| 1.2.0.0 | This function has added several features onto the first version but has not affected functionality of earlier versions. |
|
| 1.1.0.0 | Added an additional example in the help file. No changes to code. |
MATLAB Release Compatibility
Platform Compatibility
Windows macOS LinuxCategories
Tags
Acknowledgements
Inspired by: vdpdemo
Inspired: hist3d(x,y,w,varargin), Getting Started with Portfolio Optimization (Files for Video Demo)
Discover Live Editor
Create scripts with code, output, and formatted text in a single executable document.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
Select web siteYou can also select a web site from the following list:
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)
SHIVANAND Samshette (view profile)
Jeff Severino (view profile)
Great documentation! It could even be used as an example for writing good comments and help sections!
Alisa Finkbeiner (view profile)
Easy to use, thank you!
Trevor McSwain (view profile)
Jacob Williams (view profile)
Dan Hallatt (view profile)
Angelos Kalitzeos (view profile)
Adam Danz (view profile)
@Eko Leksono, it works with pzmap(). Here's a demo (I'm using matlab 2018a).
H = tf([2 5 1],[1 3 5]);
pzmap(H)
grid on
hold on
plot(-1, 1, 'rx')
labelpoints(-1, 1, 'Here', 'NE', 'color', 'r')
Eko Leksono (view profile)
I cannot use it in s-plane plot (pzmap) :(
Adam Danz (view profile)
@ed, thanks! Subscripts and superscripts are possible with labelpoints(); just follow the example below. I've been meaning to update the code so users can specify the interpreter property but here's a way to do it in the meantime.
figure; axes
h(1) = labelpoints(.2, .2, 'H_{2}O', 'center'); %subscript
h(2) = labelpoints(.4, .4, 'H^{2}O', 'center'); %superscript
set(h, 'Interpreter', 'tex')
ed (view profile)
Hi, great toolbox! For later versions it would be great to be able to use subscripts (and superscripts), for instance if points should be labeled by chemical elements.
minibela (view profile)
very useful! thank you!
Karl Behrendt (view profile)
Brilliant, great time saver!
Udo Schröder (view profile)
It would be great if you could extend the function to scatter3 plots.
Carrie Sun (view profile)
Dunno why this is rated anything less than 4 or 5. This is very straightforward and intuitive. Maybe this Eva needs to practice on basic Matlab before using this. Anyway, thank you for this!
Eva Skvor (view profile)
Mithun (view profile)
Thank you!
Gabriel Nobert (view profile)
Works very well. However, it would be interesting to make the extra space parameter work for logarithmic plots.
YANAN ZHU (view profile)
Fabio Gomez (view profile)
Adam Danz (view profile)
Shane S, as for the outliers, you can get those from the boxplot output which outputs a bunch of handles used in the boxplot. Follow this example below (you may need to run it more than once in case no outliers are produced)
fakedata = normrnd(20, 50, 1, 400);
bh = boxplot(fakedata);
% find the handle that stores the outliers
hOutliers = findobj(bh,'Tag','Outliers');
% Use the handle to pull the (x,y) coordinates of the outliers
labelpoints(hOutliers.XData,hOutliers.YData, hOutliers.YData, 'E', 1,1, 'outliers_N', 10)
% give labelpoints 5 stars :D
ShaneS (view profile)
How can label outliers on boxplot with this , please?
Andreas B (view profile)
Thank you very much Adam, I very much appreciate it!
Adam Danz (view profile)
@Andreas, it's possible to do this by making the labels have multiple lines. Here's an example:
figure; plot([1 2 3],[1 2,3], 'o')
label = sprintf('Row 1\nRow 2'); %here, the \n means new row.
labelpoints(2,2, label, 'NE', 0.1)
Try is again with
label = sprintf('Row 1\nRow 2\nRow 3');
Andreas B (view profile)
This gave me almost everything I needed in one function - thank you very mucht!
Just one more question for me: is it possible to stack multiple values on multiple markers? E.g., I got a marker (x,y), on which I want to show the numerical y-value and, say, the date when it was recorded in a second line. My workaround would be to call the function twice, first with the numerical value, say, to the north and then with the date to the south.
Ofir Shein Lumbroso (view profile)
Really great function, thanks!
Is there also a version compatible with the "App Designer"?
Kylie Hansen (view profile)
Does exactly what I needed. Thanks a lot!!!
Adam Danz (view profile)
Thanks, Simon. Unfortunately the function only considers the x and y axes for now and plots everything on the z axis at z=0. Below is a snippet of code to show an example with a 3D plot. If you manually rotate the 3D plot you'll see that the labels are in the correct (x,y) coordinates and are at z=0. It wouldn't take a lot to add a z-axis functionality but I don't have time this week to dig into that.
figure('units','normalized','outerposition',[0 0 1 1])
[X,Y,Z] = sphere(16);
x = [0.5*X(:); 0.75*X(:); X(:)];
y = [0.5*Y(:); 0.75*Y(:); Y(:)];
z = [0.5*Z(:); 0.75*Z(:); Z(:)];
scatter3(x,y,z)
select = [200, 400, 600];
hold on;
scatter3(x(select),y(select),z(select), 'markerfacecolor', 'r')
labels = strsplit(sprintf('(%.2f, %.2f)|', reshape([x(select), y(select)]', [1,6])), '|');
labelpoints(x(select), y(select), labels(1:end-1), 'N', 'fontsize', 12)
xlabel('x axis')
ylabel('y axis')
Simon Bouvot (view profile)
Cool function, works fine with scatter function : thanks.
A question : How to have labels in 3D with scatter 3 ? Labels are in 2D I think.
Thanks €.
Chang hsiung (view profile)
perfect works, thanks a lot
Adam Danz (view profile)
Hi Brad, the function has been updated to accept datetime label positions. Let me know if there are any problems since I haven't use this func much with datetime data. However, I did test it with the following code.
t = datetime(2014,6,28) + calweeks(0:9);
y = rand(1,10);
plot(t,y);
labelpoints([datetime(2014,7,12), datetime(2014,8,24)], [0.4, 0.6], 'here->', 'W')
Brad Stiritz (view profile)
Hi Adam, thanks for your great work on this. I would like to use your function to annotate time series plots, where the X-values are datetime (introduced in R2014b). Your function doesn't seem to support this directly:
>> labelpoints(my_datetimes,Y_values,char(my_datetimes),'S')
Error using labelpoints (line 258)
Comparison is not defined between datetime and double arrays.
I tried a few different hacks, with no success. For example:
>> labelpoints(datenum(my_datetimes),Y_values,char(my_datetimes),'S')
Error using axis (line 80)
x-axis and y-axis limits have different data types. Use xlim and ylim functions
instead.
Error in labelpoints (line 296)
a = axis/10;% I've somewhat arbitrarily divided by 10 to make 'buffer' more
sensitive
Changqing Lu (view profile)
Thanks so much!
Gizem Okyay (view profile)
Seunghak Lee (view profile)
This is great!! Thank you!
pradeep kumar (view profile)
Thank You Very much! It perfectly works for me.
Chenfei Ye (view profile)
Thank you for your contribution. It works well
Ivan Abraham (view profile)
Chatarin Wangsanuwat (view profile)
Adam Danz (view profile)
Easy. Here's a demo:
%Fake Data
x = rand(1,10);
y = rand(1,10);
labels = rand(1,10)*10;
% add string to values
strLabels = sprintf('w=%.1f|', labels);
strLabels(end) = []; %remove final separater
%split long string into cell array
cellLabels = strsplit(strLabels, '|');
%plot and labelpoints
plot(x,y, 'o')
labelpoints(x,y,cellLabels,'NE')
Issa Asrawi (view profile)
I need to add w = ... at each point in my graph. Any help please?
Hyeyun Yang (view profile)
Liutong (view profile)
excellent!
Craig Cole (view profile)
Gordon (view profile)
Works for my problem. Thank you!
Baris (view profile)
A N (view profile)
Marcelo Birche Ferri (view profile)
Very nice and helpfull tool, thx!
Ryan Richardson (view profile)
Very good tool. Would like to be able to select only certain strings to add as labels
Warwick (view profile)
very good, easy to use.
Brad Stiritz (view profile)
Very helpful, thank you!
I appreciate being able to select single labels after rendering, and reposition manually. Scatter points can be very close sometimes, leading to overlapping.
Highly recommended.
Zhan Yang Lim (view profile)
found it
luca de vivo (view profile)
jvc (view profile)
Fabulous! Thanks very much for this very useful tool.
William Persampieri (view profile)
Very easy to drop into my code - took me 60sec to add data labels to my figure! Thanks Adam!
cmo (view profile)
Annick (view profile)
Amazing!! Thanks for this.
Adam Danz (view profile)
Soon I will update this file with a new version that has the option of labeling only the outliers which will be calculated within the function. Check back in a couple of weeks if interested. (3-Nov-2014)
Adam Danz (view profile)
Just to follow up, the subplot issue mentioned previously has been resolved and was not a problem with labelpoint.m
This function works well with subplots, too.
Leyon (view profile)
Very useful. Thanks.
Have a problem using with subplot. Even with the use of the extra option its placement of labels is crazy.
Was using it with a (4,2,s) subplot of bar graphs to plot frequencies and label with probabilities.
Any help to fix the issue would be nice