ribbon

Ribbon plot

collapse all in page

Syntax

ribbon(Z)

ribbon(Y,Z)

ribbon(Y,Z,width)

ribbon(___,Name=Value)

ribbon(ax,___)

s = ribbon(___)

Description

ribbon(Z) plots the columns of Z as three-dimensional ribbons of uniform width, where y-coordinates range from 1 to the number of rows in Z. Ribbons advance along the x-axis centered at unit intervals.

example

ribbon(Y,Z) plots three-dimensional ribbons at the locations specified by Y.

example

ribbon(Y,Z,width) specifies the width of the ribbons.

example

ribbon(___,Name=Value) sets properties of the ribbon plot using one or more name-value arguments. For example you can specify the color and transparency of the ribbons. For a list of properties, see Surface Properties. (since R2024b)

ribbon(ax,___) plots into the axes specified by ax instead of the current axes (gca). The ax option can precede any of the input argument combinations in the previous syntaxes.

s = ribbon(___) returns a vector of Surface objects with one object per ribbon. Use s to modify properties of the plot after creating it. For a list of properties, see Surface Properties.

example

Examples

collapse all

Create Ribbon Plot

Open Live Script

Create a plot with five ribbons at increasing heights. First, create a 5-by-5 matrix with elements corresponding to ribbon heights.

Z = repmat(1:5,4,1)

Z = 4×5

     1     2     3     4     5
     1     2     3     4     5
     1     2     3     4     5
     1     2     3     4     5

Each column of Z represents one ribbon, plotted at a constant x-coordinate corresponding to the column number and with y-coordinates corresponding to the row numbers of Z.

ribbon(Z)

Figure contains an axes object. The axes object contains 5 objects of type surface.

Specify Ribbon Locations

Open Live Script

Create a 5-by-5 matrix with the magic function.

Z = magic(5)

Z = 5×5

    17    24     1     8    15
    23     5     7    14    16
     4     6    13    20    22
    10    12    19    21     3
    11    18    25     2     9

Create a ribbon plot of the matrix and specify the y-coordinates so each ribbon is centered at 0.

Y = [-2 -1 0 1 2];
ribbon(Y,Z);

Figure contains an axes object. The axes object contains 5 objects of type surface.

Create Ribbons with Different y-Coordinates

Open Live Script

Plot three ribbons at different locations along the y-axis. Specify the y-coordinates of the ribbons as a matrix Y that is the same size as Z, the matrix of ribbon heights. Each column of Y corresponds to one ribbon.

Y = [1 2 3;
     2 3 4;
     3 4 5;
     4 5 6];
Z = Y;
ribbon(Y,Z)

Figure contains an axes object. The axes object contains 3 objects of type surface.

Specify Ribbon Width

Open Live Script

Create a ribbon plot and set the width of each ribbon to 30% of the total space available.

Z = magic(5);
Y = [-2 -1 0 1 2];
ribbon(Y,Z,0.3)

Figure contains an axes object. The axes object contains 5 objects of type surface.

Modify Ribbon Plot Appearance

Open Live Script

Create a ribbon plot and specify an output argument. The output is a vector of five Surface objects, where each object corresponds to one ribbon.

Z = magic(5);
Y = [-2 -1 0 1 2];
s = ribbon(Y,Z)

Figure contains an axes object. The axes object contains 5 objects of type surface.

s = 
  5x1 Surface array:

  Surface
  Surface
  Surface
  Surface
  Surface

Highlight the first ribbon by changing the EdgeColor and LineWidth properties of the corresponding Surface object.

s(1).EdgeColor = "yellow";
s(1).LineWidth = 3;

Figure contains an axes object. The axes object contains 5 objects of type surface.

Specify Ribbon Plot Colormap

Open Live Script

Create a ribbon plot with 30 ribbons and a colorbar.

t = linspace(0,2*pi,30);
x = sin(t)';
y = cos(t);
ribbon(x*y)
cbar = colorbar;
cbar.Label.String= "Ribbon Number";

Figure contains an axes object. The axes object contains 30 objects of type surface.

Change the ribbon colors using the colormap function. ribbon maps the x-coordinates of the ribbons to colors in the colormap linearly.

colormap(turbo)

Figure contains an axes object. The axes object contains 30 objects of type surface.

Input Arguments

collapse all

`Z` — z-coordinates
numeric vector | numeric matrix

z-coordinates that represent ribbon heights, specified as a numeric vector or numeric matrix.

If Z is a vector, ribbon creates a single ribbon regardless of whether Z is a row or column vector.
If Z is a matrix, ribbon creates one ribbon for each column. Ribbons advance along the x-axis centered at unit intervals, where x-coordinates range from 1 to the number of columns in Z.

`Y` — y-coordinates
numeric vector | numeric matrix

y-coordinates, specified as a numeric vector or numeric matrix. The size of Z determines the possible sizes of Y:

If Z is a vector, Y must be a vector of the same size as Z. ribbon plots a single ribbon at X = 1 using the data in Y and Z.
If Z is a matrix, Y can be a row or column vector with a length equal to the number of rows in Z, or a matrix of the same size as Z. ribbon plots a ribbon for each column of Z using the data in Y and Z. If Y is a vector, each ribbon has the same y-coordinate.

`width` — Ribbon width
0.75 (default) | numeric scalar

Ribbon width, specified as a numeric scalar representing a percentage of the total space available for each ribbon.

If width < 1, the ribbon width occupies that fraction of the allocated space.
If width = 1, the ribbons touch one another, leaving no space between them when viewed down the z-axis.
If width > 1, the ribbons overlap and can intersect.

For example, the default value of 0.75 means the ribbon width is 75% of the total space available for the ribbon, with 12.5% of empty space on each side.

`ax` — Target axes
`Axes` object

Target axes, specified as an Axes object. If you do not specify the axes, MATLAB^® plots into the current axes or it creates an Axes object if one does not exist.

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: ribbon([1 2 3; 1 2 3],FaceColor="red") creates a red ribbon plot.

Note

The properties listed here are only a subset. For a full list, see Surface Properties.

`FaceColor` — Face color
`'flat'` (default) | `'interp'` | `'none'` | `'texturemap'` | RGB triplet | hexadecimal color code | `'r'` | `'g'` | `'b'` | ...

Face color, specified as one of the values in this table.

Value	Description
`'flat'`	Use a different color for each face based on the values in the `CData` property. First you must specify the `CData` property as a matrix the same size as `ZData`. The color value at the first vertex of each face (in the positive x and y directions) determines the color for the entire face. You cannot use this value when the `FaceAlpha` property is set to `'interp'`.
`'interp'`	Use interpolated coloring for each face based on the values in the `CData` property. First you must specify the `CData` property as a matrix the same size as `ZData`. The color varies across each face by interpolating the color values at the vertices. You cannot use this value when the `FaceAlpha` property is set to `'flat'`.
RGB triplet, hexadecimal color code, or color name	Use the specified color for all the faces. This option does not use the color values in the `CData` property.
`'texturemap'`	Transform the color data in `CData` so that it conforms to the surface.
`'none'`	Do not draw the faces.

RGB triplets and hexadecimal color codes are useful for specifying custom colors.

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 Name	Short Name	RGB Triplet	Hexadecimal Color Code
`"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"`

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

RGB Triplet	Hexadecimal Color Code	Appearance
`[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"`

`FaceAlpha` — Face transparency
1 (default) | scalar in range `[0,1]` | `'flat'` | `'interp'` | `'texturemap'`

Face transparency, specified as one of these values:

Scalar in range [0,1] — Use uniform transparency across all the faces. A value of 1 is fully opaque and 0 is completely transparent. Values between 0 and 1 are semitransparent. This option does not use the transparency values in the AlphaData property.
'flat' — Use a different transparency for each face based on the values in the AlphaData property. The transparency value at the first vertex determines the transparency for the entire face. First you must specify the AlphaData property as a matrix the same size as the ZData property. The FaceColor property also must be set to 'flat'.
'interp' — Use interpolated transparency for each face based on the values in AlphaData property. The transparency varies across each face by interpolating the values at the vertices. First you must specify the AlphaData property as a matrix the same size as the ZData property. The FaceColor property also must be set to 'interp'.
'texturemap' — Transform the data in AlphaData so that it conforms to the surface.

`EdgeColor` — Edge line color
`[0 0 0]` (default) | `'none'` | `'flat'` | `'interp'` | RGB triplet | hexadecimal color code | `'r'` | `'g'` | `'b'` | ...

Edge line color, specified as one of the values listed here. The default color of [0 0 0] corresponds to black edges.

Value	Description
`'none'`	Do not draw the edges.
`'flat'`	Use a different color for each edge based on the values in the `CData` property. First you must specify the `CData` property as a matrix the same size as `ZData`. The color value at the first vertex of each face (in the positive x and y directions) determines the color for the adjacent edges. You cannot use this value when the `EdgeAlpha` property is set to `'interp'`.
`'interp'`	Use interpolated coloring for each edge based on the values in the `CData` property. First you must specify the `CData` property as a matrix the same size as `ZData`. The color varies across each edge by linearly interpolating the color values at the vertices. You cannot use this value when the `EdgeAlpha` property is set to `'flat'`.
RGB triplet, hexadecimal color code, or color name	Use the specified color for all the edges. This option does not use the color values in the `CData` property.

RGB triplets and hexadecimal color codes are useful for specifying custom colors.

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 Name	Short Name	RGB Triplet	Hexadecimal Color Code
`"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"`

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

RGB Triplet	Hexadecimal Color Code	Appearance
`[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"`

`EdgeAlpha` — Edge transparency
1 (default) | scalar value in range`[0,1]` | `'flat'` | `'interp'`

Edge transparency, specified as one of these values:

Scalar in range [0,1] — Use uniform transparency across all of the edges. A value of 1 is fully opaque and 0 is completely transparent. Values between 0 and 1 are semitransparent. This option does not use the transparency values in the AlphaData property.
'flat' — Use a different transparency for each edge based on the values in the AlphaData property. First you must specify the AlphaData property as a matrix the same size as the ZData property. The transparency value at the first vertex determines the transparency for the entire edge. The EdgeColor property also must be set to 'flat'.
'interp' — Use interpolated transparency for each edge based on the values in AlphaData property. First you must specify the AlphaData property as a matrix the same size as the ZData property. The transparency varies across each edge by interpolating the values at the vertices. The EdgeColor property also must be set to 'interp'.

Extended Capabilities

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The ribbon function supports GPU array input with these usage notes and limitations:

This function accepts GPU arrays, but does not run on a GPU.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays
Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

Usage notes and limitations:

This function operates on distributed arrays, but executes in the client MATLAB.

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a

expand all

R2024b: Control appearance and behavior with name-value arguments

Control the appearance and behavior of ribbon plots by specifying name-value arguments. Previously, ribbon did not support name-value arguments.

ribbon

Syntax

Description

Examples

Create Ribbon Plot

Specify Ribbon Locations

Create Ribbons with Different y-Coordinates

Specify Ribbon Width

Modify Ribbon Plot Appearance

Specify Ribbon Plot Colormap

Input Arguments

`Z` — z-coordinates
numeric vector | numeric matrix

`Y` — y-coordinates
numeric vector | numeric matrix

`width` — Ribbon width
0.75 (default) | numeric scalar

`ax` — Target axes
`Axes` object

Name-Value Arguments

`FaceColor` — Face color
`'flat'` (default) | `'interp'` | `'none'` | `'texturemap'` | RGB triplet | hexadecimal color code | `'r'` | `'g'` | `'b'` | ...

`FaceAlpha` — Face transparency
1 (default) | scalar in range `[0,1]` | `'flat'` | `'interp'` | `'texturemap'`

`EdgeColor` — Edge line color
`[0 0 0]` (default) | `'none'` | `'flat'` | `'interp'` | RGB triplet | hexadecimal color code | `'r'` | `'g'` | `'b'` | ...

`EdgeAlpha` — Edge transparency
1 (default) | scalar value in range`[0,1]` | `'flat'` | `'interp'`

Extended Capabilities

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Distributed Arrays
Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

Version History

R2024b: Control appearance and behavior with name-value arguments

See Also

Functions

Properties

Topics

ribbon

Syntax

Description

Examples

Create Ribbon Plot

Specify Ribbon Locations

Create Ribbons with Different y-Coordinates

Specify Ribbon Width

Modify Ribbon Plot Appearance

Specify Ribbon Plot Colormap

Input Arguments

Z — z-coordinates numeric vector | numeric matrix

Y — y-coordinates numeric vector | numeric matrix

width — Ribbon width 0.75 (default) | numeric scalar

ax — Target axes Axes object

Name-Value Arguments

FaceColor — Face color 'flat' (default) | 'interp' | 'none' | 'texturemap' | RGB triplet | hexadecimal color code | 'r' | 'g' | 'b' | ...

FaceAlpha — Face transparency 1 (default) | scalar in range [0,1] | 'flat' | 'interp' | 'texturemap'

EdgeColor — Edge line color [0 0 0] (default) | 'none' | 'flat' | 'interp' | RGB triplet | hexadecimal color code | 'r' | 'g' | 'b' | ...

EdgeAlpha — Edge transparency 1 (default) | scalar value in range[0,1] | 'flat' | 'interp'

Extended Capabilities

GPU Arrays Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Distributed Arrays Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

Version History

R2024b: Control appearance and behavior with name-value arguments

See Also

Functions

Properties

Topics

`Z` — z-coordinates
numeric vector | numeric matrix

`Y` — y-coordinates
numeric vector | numeric matrix

`width` — Ribbon width
0.75 (default) | numeric scalar

`ax` — Target axes
`Axes` object

`FaceColor` — Face color
`'flat'` (default) | `'interp'` | `'none'` | `'texturemap'` | RGB triplet | hexadecimal color code | `'r'` | `'g'` | `'b'` | ...

`FaceAlpha` — Face transparency
1 (default) | scalar in range `[0,1]` | `'flat'` | `'interp'` | `'texturemap'`

`EdgeColor` — Edge line color
`[0 0 0]` (default) | `'none'` | `'flat'` | `'interp'` | RGB triplet | hexadecimal color code | `'r'` | `'g'` | `'b'` | ...

`EdgeAlpha` — Edge transparency
1 (default) | scalar value in range`[0,1]` | `'flat'` | `'interp'`

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Distributed Arrays
Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.