Version 4.1.1 (47.9 KB) by Adam Danz
Automatically label points in your plot given x and y values & an array of labels.
Updated 26 Jan 2020

View License

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

[Major update with additional features coming soon; don't forget to follow this file.]

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 (2024). labelpoints (, MATLAB Central File Exchange. Retrieved .

MATLAB Release Compatibility
Created with R2016a
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!
Version Published Release Notes

'Major update coming' announcement added to the description; no changes made the file.


Replaced use of isdatetime() with isa() so older versions of matlab won't cause error.

fixed typos.
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.
Move definition of 'pairIDX' within the outliers conditional.

All changes listed within labelpoints.m under 'change history' starting after 11/15/14.
Two additional outlier methods were added; Added a 'stacked' option to stack text in a list. Outliers were being calculated based on medians - not we use means.
Provided clearer examples and corrected a small problem when stacking text with only 1 element.

Improved the 'outliers_N' optional parameter and added the automatic removal of points that have 'inf' value.
Replaced example picture.

There was an error within the optional text rotation parameter.
curr_extent is not always a cell (ie, when only 2 label is entered).

This function has added several features onto the first version but has not affected functionality of earlier versions.

Added an additional example in the help file. No changes to code.