yline

Horizontal line with constant y-value

Description

example

yline(yvalue) creates a constant horizontal line at the specified y-value in the current axes. For example, yline(6) creates a line at y = 6.

example

yline(yvalue,LineSpec) specifies either the line style, the line color, or both. For example, ':' creates a dotted line, 'm' creates a magenta line, and ':m' creates a magenta dotted line.

example

yline(yvalue,LineSpec,label) adds the specified label to the line.

example

yline(___,Name,Value) specifies constant line properties using one or more name-value pair arguments. For a list of properties, see ConstantLine Properties. Specify name-value pairs after all other input arguments.

example

yline(ax,___) creates the line in the specified axes instead of the current axes. To determine the current axes use gca.

example

yl = yline(___) returns the ConstantLine object created. Use yl to modify or query properties of the line after it is created.

Examples

collapse all

Create a horizontal line at y = 2.5.

yline(2.5);

Create a blue dash-dot line at y = 4.

yline(4,'-.b');

To create a line with a label, you must also specify the line style. The default line style is a solid line, '-'.

fplot(@(x) log(x));
xlim([0 15]);
ylim([0 4]);
yline(3,'-','Threshold');

Create a horizontal dashed line with a label and a specified line width.

x = -2:0.25:2;
[X,Y] = meshgrid(x);
Z = X.*exp(-X.^2-Y.^2);
contour(X,Y,Z,30)

yl = yline(0,'--','y = 0','LineWidth',3);

Adjust the horizontal alignment and color of the line.

yl.LabelHorizontalAlignment = 'center';
yl.Color = [.80 0 .40];

Create subplots in a 1-by-2 grid and plot data in each. Then, add a horizontal line to the first subplot.

ax1 = subplot(1,2,1);
x = -pi/2:pi/60:pi/2;
y1 = tan(sin(x)) + cos(sin(x)); 
plot(ax1,x,y1)

ax2 = subplot(1,2,2);
x = -pi/2:pi/60:pi/2;
y2 = tan(cos(x)) + exp(x);
plot(ax2,x,y2)

yline(ax1,1.0);

Input Arguments

collapse all

Location of the horizontal line on the y-axis, specified as a scalar. You can specify yvalue as a numeric, categorical, datetime, or duration value. However, the type of value you specify must match the data type for the values along the y-axis.

Example: yline(8.45) plots the line at y = 8.45.

Example: yline(C(2)) plots the line at the value of the second element in the array.

Example: yline(datetime('today')) plots the line at the current date and time.

Line style and color, specified as a character vector or string scalar containing symbols. The characters and symbols can appear in any order. You can specify line style, line color, or both. You cannot specify a marker symbol.

Example: '--' is a dashed line.

Example: '--g' is a green dashed line.

Line StyleDescription
'-'Solid line (default)
'-–'Dashed line
':'Dotted line
'-.'Dash-dot line
ColorDescription
'y'Yellow
'm'Magenta
'c'Cyan
'r'Red
'g'Green
'b'Blue
'w'White
'k'Black

Target axes, specified as an Axes object. Use this argument if you want yline to plot in axes other than the current axes.

Line label, specified as a character vector, cell array of character vectors, string array, or numeric array. To create a multiline label, use a string array or a cell array of character vectors.

Example: yline(55,'-.','Target Sales')

Example: yline(75,'-',["Average","Student Score"])

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: yline(3,':','Median Price','LabelHorizontalAlignment','center') specifies the horizontal alignment of the label as 'center'.

Note

The properties listed here are only a subset. For a complete list, see ConstantLine Properties.

Line color, specified as an RGB triplet, a hexadecimal color code, a color name, or a short name.

For a custom color, specify an RGB triplet or a hexadecimal color code.

  • An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7].

  • A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Thus, the color codes '#FF8800', '#ff8800', '#F80', and '#f80' are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

Color NameShort NameRGB TripletHexadecimal Color CodeAppearance
'red''r'[1 0 0]'#FF0000'

'green''g'[0 1 0]'#00FF00'

'blue''b'[0 0 1]'#0000FF'

'cyan' 'c'[0 1 1]'#00FFFF'

'magenta''m'[1 0 1]'#FF00FF'

'yellow''y'[1 1 0]'#FFFF00'

'black''k'[0 0 0]'#000000'

'white''w'[1 1 1]'#FFFFFF'

'none'Not applicableNot applicableNot applicableNo color

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB® uses in many types of plots.

RGB TripletHexadecimal Color CodeAppearance
[0 0.4470 0.7410]'#0072BD'

[0.8500 0.3250 0.0980]'#D95319'

[0.9290 0.6940 0.1250]'#EDB120'

[0.4940 0.1840 0.5560]'#7E2F8E'

[0.4660 0.6740 0.1880]'#77AC30'

[0.3010 0.7450 0.9330]'#4DBEEE'

[0.6350 0.0780 0.1840]'#A2142F'

Example: 'g'

Example: [0.6 0.2 0.5]

Example: '#D2F9A7'

Line width, specified as a positive value in points.

Legend label, specified as a character vector or string scalar. The legend does not display until you call the legend command. If you do not specify the text, then legend sets the label using the form 'dataN'.

Horizontal alignment of the label with respect to the line, specified as one of the options in the table.

OptionDescriptionExample
'right'Right side of the line

'left'Left side of the line

'center'Center of the line

Vertical alignment of the label with respect to the line, specified as one of the options in the table.

OptionDescriptionExample
'top'Top of the line.

'middle'Middle of the line. The label segments the line.

'bottom'Bottom of the line.

Label orientation, specified as 'aligned' or 'horizontal'. Examples are shown in the table.

OrientationDescriptionExample
'aligned'Label has the same orientation as the specified line.

'horizontal'Label is horizontal, regardless of the line orientation.

Algorithms

In a 3-D view of the axes, the constant line appears in the x-y plane at the midpoint of the z-axis limits. If the axes are rotated, then the constant line rotates accordingly.

See Also

Functions

Properties

Introduced in R2018b