plot::Bars3d

3D bar chart of matrix data

MuPAD® notebooks will be removed in a future release. Use MATLAB® live scripts instead.

MATLAB live scripts support most MuPAD functionality, though there are some differences. For more information, see Convert MuPAD Notebooks to MATLAB Live Scripts.

Syntax

plot::Bars3d(A, <x = xmin .. xmax, y = ymin .. ymax>, <a = amin .. amax>, options)
plot::Bars3d(L, <x = xmin .. xmax, y = ymin .. ymax>, <a = amin .. amax>, options)

Description

plot::Bars3d(A) generates a 3D bar chart with bar heights given by the entries of the matrix A.

The rows of the matrix are plotted along the x coordinate, the columns along the y coordinate.

Different rows may be regarded as different classes of data. Each row has a different color determined by the the attribute Colors = [ c1, c2, ...] with RGB or RGBa colors c1, c2 etc.

The simplest way to obtain a uniform coloring of all rows with the color c is to specify the attribute Color = c.

Arrays/matrices do not need to be indexed from 1. E.g.,

A = array( `i_{min}` .. `i_{max}` , `j_{min}` .. `j_{max}` , [..data..])

yields a bar chart with imax - imin + 1 rows and jmax - jmin + 1 columns, stretching from xmin to xmax in x direction and from ymin to ymax in y direction.

If no plot range `x_{min}` .. `x_{max}`, `y_{min}` .. `y_{max}` is specified, xmin = jmin - 1, xmax = jmax, ymin = imin - 1, ymax = imax is used.

When the values are specified by a list of lists L and no plot range `x_{min}` .. `x_{max}`, `y_{min}` .. `y_{max}` is specified, xmin = 0, xmax = m, ymin = 0, ymax = n is used, where n is the length of L and m is the (common) length of the sublists in L. All sublists (“rows”) must have the same length.

The attribute BarStyle allows to switch the style of the bars between Boxes (bars), Lines (vertical lines), LinesPoints (vertical lines and points), and Points(points only). See Example 1.

The attribute Gap = [gx, gy] or, equivalently, XGap = gx, YGap = gy allows to introduce gaps between adjacent bars. The values gx, gy may be real numerical values between 0 and 1 or expressions of the animation parameter a. These values set the fraction of the space reserved for a bar that is not filled by the bar.

With gx = 0, gy = 0, there are no gaps. With gx = 0.5, gy = 0.5, the gaps between adjacent bars are of the same size as the bars. With gx = 1, gy = 1, there bars become lines.

Values of gx, gy larger than 1 are treated like 1, negative values like 0.

The Gap attribute has an effect only for BarStyle = Boxes.

The attribute Ground = z0 determines the z value of the lower or upper face of the bars. Matrix values m > z0 are displayed as bars stretching in z direction from the lower face z0 to the upper face m. Matrix values m < z0 are displayed as bars stretching in z direction from the upper face z0 down to the lower face m.

The parameter z0 has to be a numerical real value or an expression of the animation parameter a.

If the attribute Ground = z0 is not specified, the default value z0 = 0 is used.

Attributes

AttributePurposeDefault Value
AffectViewingBoxinfluence of objects on the ViewingBox of a sceneTRUE
BarStyledisplay style of bar plotsBoxes
Colorthe main color 
Colorslist of colors to use[RGB::Blue, RGB::Red, RGB::Green, RGB::MuPADGold, RGB::Orange, RGB::Cyan, RGB::Magenta, RGB::LimeGreen, RGB::CadmiumYellowLight, RGB::AlizarinCrimson, RGB::Aqua, RGB::Lavender, RGB::SeaGreen, RGB::AureolineYellow, RGB::Banana, RGB::Beige, RGB::YellowGreen, RGB::Wheat, RGB::IndianRed, RGB::Black]
Datathe (statistical) data to plot 
Filledfilled or transparent areas and surfacesTRUE
Framesthe number of frames in an animation50
Gapgaps between the bars of a bar chart[0, 0]
Groundbase value0
Legendmakes a legend entry 
LegendTextshort explanatory text for legend 
LegendEntryadd this object to the legend?FALSE
LineColorcolor of linesRGB::Black.[0.25]
LineWidthwidth of lines0.35
LineStylesolid, dashed or dotted lines?Solid
LinesVisiblevisibility of linesTRUE
Namethe name of a plot object (for browser and legend) 
ParameterEndend value of the animation parameter 
ParameterNamename of the animation parameter 
ParameterBegininitial value of the animation parameter 
ParameterRangerange of the animation parameter 
PointSizethe size of points1.5
PointStylethe presentation style of pointsFilledCircles
TimeEndend time of the animation10.0
TimeBeginstart time of the animation0.0
TimeRangethe real time span of an animation0.0 .. 10.0
Titleobject title 
TitleFontfont of object titles[" sans-serif ", 11]
TitlePositionposition of object titles 
TitleAlignmenthorizontal alignment of titles w.r.t. their coordinatesCenter
TitlePositionXposition of object titles, x component 
TitlePositionYposition of object titles, y component 
TitlePositionZposition of object titles, z component 
VisiblevisibilityTRUE
VisibleAfterobject visible after this time value 
VisibleBeforeobject visible until this time value 
VisibleFromToobject visible during this time range 
VisibleAfterEndobject visible after its animation time ended?TRUE
VisibleBeforeBeginobject visible before its animation time starts?TRUE
XGapgaps in x direction between the bars of a bar chart0
XMaxfinal value of parameter “x” 
XMininitial value of parameter “x” 
XNamename of parameter “x” 
XRangerange of parameter “x” 
YGapgaps in y direction between the bars of a bar chart0
YMaxfinal value of parameter “y” 
YMininitial value of parameter “y” 
YNamename of parameter “y” 
YRangerange of parameter “y” 

Examples

Example 1

We create some random matrix data and plot them as a bar chart:

A := matrix::random(5, 10, frandom) :
plot(plot::Bars3d(A, Gap = [0.4, 0.7]))

We create bar charts of the data with different BarStyle options:

plot(plot::Scene3d(plot::Bars3d(A, BarStyle = Boxes)),
     plot::Scene3d(plot::Bars3d(A, BarStyle = Lines)),
     plot::Scene3d(plot::Bars3d(A, BarStyle = Points)),
     plot::Scene3d(plot::Bars3d(A, BarStyle = LinesPoints)),
     PointSize = 2.0*unit::mm, LineWidth = 0.5*unit::mm
):

delete A:

Example 2

We demonstrate the positioning of bar charts by specifying ranges for the x and the y coordinate. The following two bar charts are plotted in one scene. They are placed side by side via suitable x ranges:

A := matrix::random(5, 5, frandom):
plot(plot::Bars3d(A, x = 0 .. 0.9, y = 0 .. 1, 
                  BarStyle = LinesPoints),
     plot::Bars3d(A, x = 1.1 .. 2, y = 0 .. 1,
                  Gap = [0.3, 0.7])):

delete A:

Example 3

We demonstrate the attributes Ground and Color:

A := matrix::random(5, 10, frandom):
plot(plot::Scene3d(plot::Bars3d(A, Ground = 0,
                                Color = RGB::Grey)),
     plot::Scene3d(plot::Bars3d(A, Ground = 0.5,
                                Color = RGB::Grey)),
     Layout = Horizontal):

In the next call, the ground level is animated. Note that in animations one must specify ranges for the x and y coordinates.We include a transparent plane visualizing the ground level:

plot(plot::Bars3d(A, x = 0 .. 1, y = 0 .. 1, a = 0 .. PI,
                  Color = RGB::Grey, Gap = [0.5, 0.5], 
                  Ground = sin(a)),
     plot::Surface([x, y, sin(a) + 0.001],
                   x = 0 .. 1, y = 0 .. 1, a = 0 .. PI,
                   Mesh = [2, 2], Color = RGB::Blue.[0.5])):

delete A:

Parameters

A

An array of domain type DOM_ARRAY or a matrix of category Cat::Matrix (e.g., of type matrix or densematrix) containing real numerical values or expressions of the animation parameter a. Rows/columns of the array, respectively matrix, correspond to rows/columns of the bar chart.

A is equivalent to the attribute Data.

L

A list of lists of real numerical values or expressions of the animation parameter a. Each sublist of L represents a row of the bar chart.

L is equivalent to the attribute Data.

x

Name of the horizontal variable: an identifier or an indexed identifier. It is used as the title of the coordinate axis in x direction.

x is equivalent to the attribute XName.

xmin .. xmax

The range of the horizontal variable: xmin, xmax must be numerical real value or expressions of the animation parameter a.

xmin .. xmax is equivalent to the attribute XRange.

y

Name of the vertical variable: an identifier or an indexed identifier. It is used as the title of the coordinate axis in y direction.

y is equivalent to the attribute YName.

ymin .. ymax

The range of the vertical variable: ymin, ymax must be numerical real value or expressions of the animation parameter a.

ymin .. ymax is equivalent to the attribute YRange.

a

Animation parameter, specified as a = amin..amax, where amin is the initial parameter value, and amax is the final parameter value.

See Also

MuPAD Functions

MuPAD Graphical Primitives