Main Content

yregion

1-D filled region between y-coordinates

Since R2023a

    Description

    yregion(y1,y2) creates one or more filled regions between y-coordinates. To create one filled region, specify y1 and y2 as scalars. To create multiple filled regions, specify y1 and y2 as vectors of the same length.

    example

    yregion(Y) specifies multiple regions as a matrix. To create n regions, specify Y as a 2-by-n or n-by-2 matrix containing the lower and upper bounds for each region. (since R2023b)

    example

    yregion(ax,___) specifies the target axes for the filled region. Specify ax as the first argument in any of the previous syntaxes.

    yregion(___,Name=Value) specifies properties for the region using one or more name-value arguments. If you create multiple regions, the property values apply to all of the regions. For example, you can set the color of a region to yellow by using yregion(5,10,FaceColor="yellow"). For a list of properties, see ConstantRegion Properties.

    yr = yregion(___) returns one or more ConstantRegion objects. Use yr to set properties of the filled regions after creating them. For a list of properties, see ConstantRegion Properties.

    Examples

    collapse all

    Create a line plot and a filled region between y=0 and y=106.

    x = 0:0.1:50;
    y = 2*x .* (sin(x) + cos(2*x));
    plot(x,y)
    yregion(0,106)

    Figure contains an axes object. The axes object contains 2 objects of type line, constantregion.

    You can modify aspects of a region by setting properties. You can set properties by specifying name-value arguments when you call yregion, or you can set properties later using dot notation.

    For example, create a plot with a filled region, and customize the fill and boundary line colors by specifying the FaceColor and EdgeColor name-value arguments. Also, specify an output argument to store the ConstantRegion object.

    x = 0:0.1:50;
    y = 2*x .* (sin(x) + cos(2*x));
    plot(x,y)
    yr = yregion(0,106,FaceColor="b",EdgeColor=[0.4 0 0.7]);

    Figure contains an axes object. The axes object contains 2 objects of type line, constantregion.

    Modify the appearance further by setting properties of the ConstantRegion object yr. Change the opacity of the fill color and boundary line color by setting the FaceAlpha and EdgeAlpha properties to numbers from 0 to 1, where 1 is fully opaque. Then, set the boundary line thickness by setting the LineWidth property.

    yr.FaceAlpha = 0.1;
    yr.EdgeAlpha = 0.5;
    yr.LineWidth = 3;

    Figure contains an axes object. The axes object contains 2 objects of type line, constantregion.

    Move the lower boundary to -25.

    yr.Value = [-25 106];

    Figure contains an axes object. The axes object contains 2 objects of type line, constantregion.

    You can create multiple filled regions by specifying the starting and ending coordinates as vectors of the same size. You can also display entries for these regions in a legend.

    For example, create a horizontal bar chart with two filled regions. Specify an output argument to store both ConstantRegion objects so you can modify them later.

    x = [1 2 3 4 13 11 2.5];
    barh(x,DisplayName="Results")
    yr = yregion([0.5 4.5],[2.5 6.5]);

    Figure contains an axes object. The axes object contains 3 objects of type bar, constantregion. This object represents Results.

    Specify a color for each region by setting the FaceColor property. Specify a legend entry name for each region by setting the DisplayName property. To access the individual ConstantRegion objects for setting the properties, index into the output argument yr. After setting the properties, display a legend.

    yr(1).FaceColor = "r";
    yr(1).DisplayName = "Low";
    yr(2).FaceColor = "#88FE45";
    yr(2).DisplayName = "High";
    legend

    Figure contains an axes object. The axes object contains 3 objects of type bar, constantregion. These objects represent Results, Low, High.

    Create a horizontal bar chart with five bars positioned at specific numbers of minutes. Then display a filled region from the second bar to the fourth bar. To contain the three bars within the region, calculate the boundaries by subtracting 30 seconds from the second bar's location and adding 30 seconds to the fourth bar's location.

    dur = minutes(1:5)';
    y = [1 5 11 4 3];
    barh(dur,y)
    yregion(dur(2)-seconds(30), dur(4)+seconds(30))

    Figure contains an axes object. The axes object contains 2 objects of type bar, constantregion.

    Create a horizontal bar chart of categorical data, and create a filled region that spans the second and third bars. The reordercats function specifies the order of the categories for the bar chart.

    cats = categorical(["Pumpkin" "Apple" "Pecan" "Cherry"]);
    cats = reordercats(cats,["Pumpkin" "Apple" "Pecan" "Cherry"]);
    barlengths = [15 21 33 12];
    barh(cats,barlengths)
    yregion(cats(2),cats(3))
    title("Favorite Pies")

    Figure contains an axes object. The axes object with title Favorite Pies contains 2 objects of type bar, constantregion.

    Since R2023b

    Create a plot, and add three filled regions. Specify a 2-by-3 matrix with the lower bounds in the first row and the upper bounds in the second row. The first region has a lower bound of -Inf, and the last region has an upper bound of Inf, so the first and last regions are unbounded.

    x = 0:0.1:50;
    y = 2*x .* (sin(x) + cos(2*x));
    plot(x,y)
    Y = [-Inf -50 50; -100 0 Inf];
    yregion(Y)

    Figure contains an axes object. The axes object contains 4 objects of type line, constantregion.

    Input Arguments

    collapse all

    Starting and ending y-coordinates of the filled region, specified as a pair of scalars or a pair of vectors. To create one filled region, specify y1 and y2 as scalars. To create multiple filled regions, specify vectors of equal length. The minimum and maximum region values can be defined in either y1 or y2. Thus, yregion(1,5) and yregion(5,1) produce the same result.

    To create an unbounded region, specify one of the coordinates as Inf or -Inf. (since R2023b)

    If any coordinates are NaN values, no region appears for those coordinates.

    Example: yregion(5,10) creates a filled region from y=5 to y=10.

    Example: yregion([1 20],[10 30]) creates two filled regions: one from y=1 to y=10, and the other from y=20 to y=30.

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | categorical | datetime | duration

    Since R2023b

    Starting and ending coordinates for multiple regions, specified as a 2-by-n or n-by-2 matrix, where n is the number of regions.

    To create an unbounded region, specify one of the coordinates as Inf or -Inf.

    If any coordinates are NaN values, no region appears for those coordinates.

    Example: yregion([1 3; 2 4]) creates a filled region from y=1 to y=2, and another filled region from y=3 to y=4.

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | categorical | datetime | duration

    Target axes for the filled region, specified as an Axes object. Use this argument if you want yregion to plot into a specific Axes object instead of the current axes.

    Name-Value Arguments

    Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

    Example: yregion(5,10,FaceColor="yellow") creates a yellow filled region.

    Note

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

    Fill color, specified as an RGB triplet, a hexadecimal color code, or a color 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 string scalar or character vector 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. Therefore, 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"

    Sample of the color red

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

    Sample of the color green

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

    Sample of the color blue

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

    Sample of the color cyan

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

    Sample of the color magenta

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

    Sample of the color yellow

    "black""k"[0 0 0]"#000000"

    Sample of the color black

    "white""w"[1 1 1]"#FFFFFF"

    Sample of the color white

    "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"

    Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

    [0.8500 0.3250 0.0980]"#D95319"

    Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

    [0.9290 0.6940 0.1250]"#EDB120"

    Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

    [0.4940 0.1840 0.5560]"#7E2F8E"

    Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

    [0.4660 0.6740 0.1880]"#77AC30"

    Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

    [0.3010 0.7450 0.9330]"#4DBEEE"

    Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

    [0.6350 0.0780 0.1840]"#A2142F"

    Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

    Boundary line color, specified as an RGB triplet, a hexadecimal color code, or a color 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 string scalar or character vector 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. Therefore, 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"

    Sample of the color red

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

    Sample of the color green

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

    Sample of the color blue

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

    Sample of the color cyan

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

    Sample of the color magenta

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

    Sample of the color yellow

    "black""k"[0 0 0]"#000000"

    Sample of the color black

    "white""w"[1 1 1]"#FFFFFF"

    Sample of the color white

    "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"

    Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

    [0.8500 0.3250 0.0980]"#D95319"

    Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

    [0.9290 0.6940 0.1250]"#EDB120"

    Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

    [0.4940 0.1840 0.5560]"#7E2F8E"

    Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

    [0.4660 0.6740 0.1880]"#77AC30"

    Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

    [0.3010 0.7450 0.9330]"#4DBEEE"

    Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

    [0.6350 0.0780 0.1840]"#A2142F"

    Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

    Fill color transparency, specified as a scalar in the range [0,1]. A value of 1 is opaque and 0 is completely transparent. Values between 0 and 1 are partially transparent.

    Boundary line transparency, specified as a scalar in the range [0,1]. A value of 1 is opaque and 0 is completely transparent. Values between 0 and 1 are partially transparent.

    Boundary line style, specified as one of the options listed in this table.

    Line StyleDescriptionResulting Line
    "-"Solid line

    Sample of solid line

    "--"Dashed line

    Sample of dashed line

    ":"Dotted line

    Sample of dotted line

    "-."Dash-dotted line

    Sample of dash-dotted line, with alternating dashes and dots

    "none"No lineNo line

    Version History

    Introduced in R2023a

    expand all