Creating 2D and 3D Bar Plots
Bar plots (also known as bar charts or bar graphs) display grouped data as rectangular bars and associate the heights of the bars with the values of the data. Bar plots can be configured in various ways to orient the bars vertically or horizontally, to create 3D bricks (box or cuboids) instead of plain rectangular bars, and to group series of corresponding bars together by placing them next to or above each other (grouped and stacked bar plots).
Bar coloring brings in an additional dimension and can help improve the readablility for complex scenarios. Flexible labeling options are of great importance for bar plots. Therefore, bar plots are expected to be used inside a plot cube to leverage its axis labeling capabilities.
In the ILNumerics Visualization Engine Regular bar plots are created by the class ILNumerics.Drawing.Plotting.BarPlot from the ILNumerics.Toolboxes.Drawing2 module. This page describes its features:
- Simple Bar Plots
- 2D Bar Plot Styles
- 3D Bar Plots
- Bar Plot Syles Configuration
- Axis Configuration
- Legend
- Update and Configure Methods
Simple Bar Plots
Most parameters of BarPlot are configured with common default values and can be omitted in many situations. A simple way of creating a bar plot is shown in the following example.
Example: A simple bar plot.
Here, the vector sized array Y with the data to be visualized is given to the constructor of BarPlot. Each element of Y defines the height of an individual bar. Note how the heights, positions and colors of the bars as well as the labels are adopted automatically.
Multiple Bar Groups
BarPlot allows the data parameter Y to be a matrix with more than one column. Each column causes the creation of an individual series of values. Values from the same row appear grouped together. Several options exist for the visual style of the groups. See below for details.
Example: Create a grouped bar plot from 4 series of data, 3 elements each.
Positioning Bars
By default, bars are positioned according to the index of corresponding value elements in Y. A optional parameter X can be used to explicitly define positions of each bar along the X axis. Commonly, the size of X matches the size of Y. If Y is a vector of length $N$ then X must also be a vector of length $N$. Each bar will be placed at a position defined by X.
Example: Y and X are vectors of the same length. X defines the bar position for each value in Y.
For grouped bar plots, where Y is a matrix of size [$M$ x $N$] , X can be specified as a vector of length $M$. Each bar group will be placed at positions corresponding to the values in X at corresponding indices.
Example: Create a grouped bar plot of 4 series with 3 elements each. Position the 3 group centers to represent individual years.
Alternatively, for grouped bar plots, X can be used to define individual positions for each bar by providing a matrix of the same size as Y. Elements in X will define the position of the bars for corresponding elements in Y.
Example: Y and X are matrices of the same size. Each bar (instead of each group) is positioned individually.
Note how the definition of individual bar positions in a grouped bar plot quickly makes things more complicated: labels are commonly auto-created for each group. However, the manual bar positioning potentially causes conflicts with the grouping of the bars. Hence, one may also want to take control of the way labels for the bars are displayed.
2D Bar Plot Styles
BarPlot, creates rectangle bars in the $X-Y$ plane by default. Since the bars do not have any depth ($Z$ axis) such plots are considered as 'two-dimensional'. In the following, several different drawing styles for 2D plots are demonstrated. They differ in the general look, feel of the plot and in the way bars of individual data series are arranged to groups. (Therefore, 'single grouped' plots resulting from vector data may not differ for some styles.)
The drawing style is set by the property Style or by using the style constructor parameter. The following values from the BarPlotStyle enumeration are supported:
BarPlotStyle.grouped is the default style. It displays $M$ groups of $N$ bars if Y is a matrix of size [M x N]. $N$ bars are displayed if Y is a vector of $N$ elements.
Example: A simple grouped 2D bar plot in default style (grouped).
BarPlotStyle.stacked for a matrix Y of size [$M$ x $N$] $M$ stacked bars of $N$ elements each are displayed, where the height of the i-th bar corresponds to the sum of all $N$ elements on row i.
Example: A simple stacked 2D bar plot.
BarPlotStyle.hist and BarPlotStyle.histc - displays bar plot in histogram format, i.e.: adjacent bars touch each other. BarPlotStyle.hist positions bars aligned with axis ticks rounded to nearest integer values, while BarPlotStyle.histc positions the bars/ groups centered on rounded integer positions.
Example : A simple grouped 2D bar plot, utilizing bar style histc.
3D Bar Plot Styles
Users of BarPlot may decide to give the bars a volume to turn the plot into a full featured three dimensional plot. The value of the Draw3D property or, alternatively, the constructor parameter draw3DBars is used to switch between 2D and 3D mode. In 3D mode (Draw3D = true) all drawing styles for 2D mode are supported similarly.
Example: A simple 3D bar plot with grouped style.
BarPlotStyle.detached is a drawing style only suitable for grouped bar plots in 3D mode, i.e. when Y was provided as matrix and Draw3D is set to true. It displays individual 3D bars for each element of Y and positions the bars of each group behind each other along the Y axis.
Example: A simple detached 3D bar plot
Detached 3D bar plots as the one shown above are sometimes refered to as '3D Bar Surface', possibly due to their capability to visualize the values of a two dimensional data series by associating them with a height at corresponding points. However, besides this common property such bar plots differ from surface plots in many aspects.
Another, more advanced option to create such 'surface-like' bar plots is to use the BarPlotEx class, which allows to apply colormaps to the bars in various ways.
Configuring Bar Plot Styles
BarPlot provides additional option for configuring the styling of bars. The following options exist to control the colors of the fill area and of the border, and the width of- as well as the padding between individual bars and between groups of bars. These configurations will be valid for all bars of the plot. Read below about further configuration options which affect selected bars only.
- Initial Colors. By default, the color of the bars for individual series are varied automatically. If the constructor parameters borderColor and/or fillColor are set, then all bars in all series will be colored with this same color.
- Line Width. The constructor parameter lineWidth sets the line width of bar borders. Default value is 1 px.
- Bar Width. The constructor parameter barWidth or property BarWidth controls the width of all bars. The width is specified as a scalar value in the range 0.0f ... 1.0f. 0 corresponds to a width of 0. A value of 1.0f corresponds to adjacent bars within a group touching each other. Default is 0.8f.
- Padding. The Padding property sets the padding between groups for grouped, hist or histc styles. The values must lay in range 0f...1f. 0 corresponds to no padding between groups. 1 corresponds to maximum space between groups. Note how the Padding parameter also indirectly influences the width of the bars. Default: 0.2f.
Example: using initial color in constructor, all groups are colored the same color, setting border line width, setting border dash style, setting bar width to 0.5f, setting padding to 0.6f
Custom Fill and Border Colors Configuration
BarPlot provides methods and properties to set up custom colors to each bar or to each bar group, if needed.
- Group Color. The BarPlot.SetGroupColor(ID, borderColor, fillColor) - method sets a user defined border and fill color to a group of bars specified by ID. ID is a scalar value in the range [0,1,..,N], where $N = {bars count} - 1$.
- Single Bar Color. BarPlot.SetBarColor(ID, borderColor, fillColor) - sets a user defined border and fill color to the single bar specified by ID. ID is a scalar value [0,1,..,N], where $N = {bars count} - 1$.
Note, in these functions ID refers to the index of individual bars/ groups. Like always, the first bar/ group corresponds to the index 0. Refering to a negative index or to an index outside of the existing range will cause an ArgumentException to be thrown.
Example: Creating a grouped bar with automatically generated colors, change the color of an individual group and of an individual bar.
BarPlot allows to visualize bars in horizontal orientation. All described properties and features on this page are fully supported for horizontal bar plots. The BarPlot object constructor provides the optional parameter drawHorizontal to control the orientation setting. Alternatively, the property Horizontal can be utilized to modify an existing BarPlot object. By default bars are drawn in vertical orientation, i.e. Horizontal is set to false.
Example: Create a bar plot in horizontal mode.
By default, individual bars in BarPlot span the range from 0 to the corresponding value specified. '0' corresponds to the value of the property BaseValue. It controls the second range (upper or lower range respectively) and can be used to arbitrarily move the base level of the bars. The base value is specified as a numeric scalar value, hence the value is applied to all bars in the bar plot object.
Example: Draw a horizontally grouped bar plot. Configure a custom base value.
The boolean property UseLighting controls whether any lights in the scene get reflected by the bars. By default UseLighting is set to null (i.e. 'auto'), that means, that 2D bar plots will be rendered with lighting enabled and 3D bar plots - without lighting. If UseLighting is false, bar plot in both modes, 2D and 3D, will be rendered without lighting. Otherwise, if UseLighting is set to true, bar plot in both modes, 2D and 3D, will be rendered with lighting enabled.
Note that for lighting the regular default lights are used. Feel free to add new lights or re-configure the default lighting in order to control the way the bars are lit.Example: Create a simple bar plot using lighting and reposition the shiny effect on the bar.
Lighting can be used to control the colors of the bars. Often, the effect of color gradients created due to lighting can give the bars a more professional look and feel. However, such effects are rather for eye-catching purposes. In order to associate a meaning to the color gradients consider using the advanced options of another bar plot object, found in the same toolbox: BarPlotEx.
Axis Configuration
In order to create a great user experience, further options are needed for controlling the way axis labels are created and displayed. BarPlot automatically configures the axis in most common situations. For special cases, the user can take full control of the axis configurations. Two properties are provided for BarPlots for such custom configurations: BarPlot.Axis and BarPlot.Ticks.
The property Axis returns a reference to the working axis of the bar plot. Note that each bar plot creates its own axis object and adds it to the Axes collection of the hosting plot cube. The corresponding default axis on the plot cube is deactivated and replaced by the working axis of the bar plot at the time the bar plot is added to the plot cube.
The object returned from BarPlot.Axis is a regular Axis object. All common configuration options are applicable, including TickMode.Manual, DefaultLabel, Label, and Ticks. (Read about all Axis Configuration options)
While a custom axis configuration via the Axis property offers the greatest flexibility, a custom axis configuration can be cumbersome. Therefore, the property Ticks offers a compromise: it allows to define custom working axis ticks only. Once a set of ticks was defined those ticks will be applied to the working axis.
The working axis for vertical bar plots is always X, for horizontal bar plots in 2D mode the working axis is the Y axis, in 3D mode it is the Z axis. For bar plots configured for 3D horizontal detached style, the working axis is Y.
Example: A bar plot with custom axis ticks configuration.
Let's add another, more complex example with vertical bar plots and custom naming of the bars:
Legend Configuration
Adding a legend object to a scene is described on this page. BarPlot creates individual legend items for each group of bars. If the source values Y for the bar plot were provided as a vector (defining a single group only) then a single legend item will result.
While using legends with BarPlot, keep in mind that all legend items in the plot cube are combined in a legend and displayed in the order of their construction.
Example: Combine inePlot and BarPlot items into a single legend.
Update and Configure Method
BarPlot is a dynamic plot object. It is perfectly suited to be used in setups with frequently changing values. Use the BarPlot.Update() method on an existing bar plot object in order to update values of the bars. Note, that the ability to change an existing bar plot at runtime is valid for all properties of BarPlot, including the ability to change the size and number of the bars. More information can be found in the corresponding ApiDoc for ILNumerics.Drawing.Plotting.BarPlot.
Keep in mind: after having finished all configurations on a plot object the Configure() method needs to be called on the object (or any parent object on the path to the root of the scene graph). This is necessary in order to commit the changes to the rendering pipeline. Not calling Configure() may lead to partial updates or may even prevent any changes from appearing in the rendering result.
Example: Using Configure() method
Further reading:
Advanced, colormapped bar plots by BarPlotEx