# `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
`AffectViewingBox`influence of objects on the `ViewingBox` of a scene`TRUE`
`BarStyle`display style of bar plots`Boxes`
`Color`the main color
`Colors`list 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`]
`Data`the (statistical) data to plot
`Filled`filled or transparent areas and surfaces`TRUE`
`Frames`the number of frames in an animation`50`
`Gap`gaps between the bars of a bar chart[`0`, `0`]
`Ground`base value`0`
`Legend`makes a legend entry
`LegendText`short explanatory text for legend
`LegendEntry`add this object to the legend?`FALSE`
`LineColor`color of lines`RGB::Black.[0.25]`
`LineWidth`width of lines`0.35`
`LineStyle`solid, dashed or dotted lines?`Solid`
`LinesVisible`visibility of lines`TRUE`
`Name`the name of a plot object (for browser and legend)
`ParameterEnd`end value of the animation parameter
`ParameterName`name of the animation parameter
`ParameterBegin`initial value of the animation parameter
`ParameterRange`range of the animation parameter
`PointSize`the size of points`1.5`
`PointStyle`the presentation style of points`FilledCircles`
`TimeEnd`end time of the animation`10.0`
`TimeBegin`start time of the animation`0.0`
`TimeRange`the real time span of an animation`0.0` .. `10.0`
`Title`object title
`TitleFont`font of object titles[`" sans-serif "`, `11`]
`TitlePosition`position of object titles
`TitleAlignment`horizontal alignment of titles w.r.t. their coordinates`Center`
`TitlePositionX`position of object titles, x component
`TitlePositionY`position of object titles, y component
`TitlePositionZ`position of object titles, z component
`Visible`visibility`TRUE`
`VisibleAfter`object visible after this time value
`VisibleBefore`object visible until this time value
`VisibleFromTo`object visible during this time range
`VisibleAfterEnd`object visible after its animation time ended?`TRUE`
`VisibleBeforeBegin`object visible before its animation time starts?`TRUE`
`XGap`gaps in x direction between the bars of a bar chart`0`
`XMax`final value of parameter “x”
`XMin`initial value of parameter “x”
`XName`name of parameter “x”
`XRange`range of parameter “x”
`YGap`gaps in y direction between the bars of a bar chart`0`
`YMax`final value of parameter “y”
`YMin`initial value of parameter “y”
`YName`name of parameter “y”
`YRange`range 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.