Bar Plots

Graphs for showing bars.

A graph showing a single series of bars. See BarsGraphData and BarsGraphConfiguration .

function bars_graph(;
    [figure_title::Maybe{AbstractString} = nothing,
    values::VectorValuesData = VectorValuesData(),
    bars::VectorEntitiesData = VectorEntitiesData(),
    colors::VectorValuesData = VectorValuesData(),
    annotations::AbstractVector{AnnotationData} = AnnotationData[],
    annotations_order::Maybe{AbstractVector{<:Integer}} = nothing,
    value_bands::BandsData = BandsData(),
    configuration::BarsGraphConfiguration = BarsGraphConfiguration()]
)::BarsGraph

Create a BarsGraph by initializing only the BarsGraphData fields (with an optional BarsGraphConfiguration ).

@kwdef mutable struct BarsGraphData <: AbstractGraphData
    figure_title::Maybe{AbstractString} = nothing
    values::VectorValuesData = VectorValuesData()
    bars::VectorEntitiesData = VectorEntitiesData()
    colors::VectorValuesData = VectorValuesData()
    annotations::AbstractVector{AnnotationData} = AnnotationData[]
    annotations_order::Maybe{AbstractVector{<:Integer}} = nothing
    value_bands::BandsData = BandsData()
end

The data for a graph of a single series of bars.

The values are required and numeric, one per bar; their title is the value axis title. The bars hold the names, hovers, mask and order of the bars; their names are shown as the bar axis ticks, masked bars are left out of the graph, and the order (if any) is the order of the bars along the bar axis. The colors are optional (typically all bars have the same color); their title is the title of the color scale. You can even add annotations to the bars.

If annotations_order is specified, the annotations are shown in that order. It describes all the annotations, including the ones that are not is_shown .

@kwdef mutable struct BarsGraphConfiguration <: AbstractGraphConfiguration
    figure::FigureConfiguration = FigureConfiguration()
    value_axis::AxisConfiguration = AxisConfiguration(; expand_fraction = 0.01)
    bar_axis::AxisConfiguration = AxisConfiguration()
    value_bands::BandsConfiguration = BandsConfiguration()
    values_orientation::ValuesOrientation = VerticalValues
    colors::ColorsConfiguration = ColorsConfiguration()
    bars::BarsConfiguration = BarsConfiguration()
    annotations::AnnotationSize = AnnotationSize()
end

Configure a graph for showing a single series of bars.

By default the values are the y axis ( VerticalValues ). You can flip the axes using the values_orientation . You can specify bands for this axis using value_bands . The bars configure the bars themselves (see BarsConfiguration ). The colors is used to control the color of the bars (if not specified, chosen automatically by Plotly), in combination with the data bar colors (if any). A bars graph has no legend, so the colors' legend can only be shown for continuous colors (in a color scale). The annotations are the sizes of the annotations shown next to the bars.

The bar_axis shows the names of the bars. Only its show_ticks , ticks_angle and title apply, as the rest have no meaning for an axis of names.

The value_axis always shows zero, which is where a bar is measured from, however far from it the values are - so the bars show their sizes rather than their differences. Setting an explicit value_axis.scale.minimum (or maximum ) overrides this. A log scale never reaches zero, so there a bar is measured from the smallest value shown.

@kwdef mutable struct BarsConfiguration <: Validated
    gap::Real = 0.02
end

Configure the bars of a bars graph. The gap is added between the bars, and is in the usual inconvenient units of fractions of the total graph size.

A graph showing multiple series of bars. See SeriesBarsGraphData and SeriesBarsGraphConfiguration .

function series_bars_graph(;
    [figure_title::Maybe{AbstractString} = nothing,
    series::AbstractVector{SeriesData} = SeriesData[],
    order::Maybe{AbstractVector{<:Integer}} = nothing,
    bars::VectorEntitiesData = VectorEntitiesData(),
    annotations::AbstractVector{AnnotationData} = AnnotationData[],
    annotations_order::Maybe{AbstractVector{<:Integer}} = nothing,
    configuration::SeriesBarsGraphConfiguration = SeriesBarsGraphConfiguration()]
)::SeriesBarsGraph

Create a SeriesBarsGraph by initializing only the SeriesBarsGraphData fields (with an optional SeriesBarsGraphConfiguration ).

@kwdef mutable struct SeriesBarsGraphData <: AbstractGraphData
    figure_title::Maybe{AbstractString} = nothing
    series::AbstractVector{SeriesData} = SeriesData[]
    order::Maybe{AbstractVector{<:Integer}} = nothing
    bars::VectorEntitiesData = VectorEntitiesData()
    annotations::AbstractVector{AnnotationData} = AnnotationData[]
    annotations_order::Maybe{AbstractVector{<:Integer}} = nothing
end

The data for a graph of multiple series of bars, a SeriesData per series.

All the series must have the same number of bars. The value axis title is the title of the series' values: all the series that give one must give the same. The bars hold the names, hovers, mask and order shared by the bars of all the series; their names are shown as the bar axis ticks, masked bars are left out of every series, and the order (if any) is the order of the bars along the bar axis. The bars of each series may add hovers and a mask of their own, but not an order, as they line up with the shared bars. When stacking, a series can't have a mask of its own, and with StackFractions the (scaled) values must not be negative. At least one series must be is_shown . You can even add annotations to the bars.

If order is specified, we draw the series in that order. Stacked, this is the order of the stack from its base; with a series_gap , this is the order of the series' own axes. The order describes all the series, including the ones that are not is_shown ; these are then left out, so hiding a series shifts the rest rather than leaving a gap.

The hover of a bar in a series is the hover of the series, then the shared hover of the bar, then the hover of the bar in the series, skipping whichever is not specified.

@kwdef mutable struct SeriesData <: AbstractPartData
    values::VectorValuesData = VectorValuesData()
    bars::VectorEntitiesData = VectorEntitiesData()
    name::Maybe{AbstractString} = nothing
    hover::Maybe{AbstractString} = nothing
    is_shown::Bool = true
    color::Maybe{AbstractString} = nothing
end

One series of a SeriesBarsGraphData . The values are required and numeric, one per bar; their title is the value axis title shared by all the series. The bars hold the hovers and mask of the bars of this series alone. The name is shown in the legend (or, if using series_gap , as the title of the series' own axis; the names can't then be combined with a title of the values). The hover (if any) is prefixed to the hover of each bar of the series. A series which is not is_shown is left out of the graph. All the bars of a series have the same color ; a nothing means the color is chosen automatically by Plotly.

@kwdef mutable struct SeriesBarsGraphConfiguration <: AbstractGraphConfiguration
    figure::FigureConfiguration = FigureConfiguration()
    value_axis::AxisConfiguration = AxisConfiguration(; expand_fraction = 0.01)
    bar_axis::AxisConfiguration = AxisConfiguration()
    values_orientation::ValuesOrientation = VerticalValues
    bars::BarsConfiguration = BarsConfiguration()
    annotations::AnnotationSize = AnnotationSize()
    series_gap::Maybe{Integer} = nothing
    stacking::Maybe{Stacking} = nothing
    mirrored::Bool = false
end

Configure a graph for showing multiple series of bars.

This is similar to BarsGraphConfiguration , without the colors and value_bands (the colors of the bars are those of their series), and with an optional stacking for stacking the bars of the different series on top of each other. Alternatively, specifying a series_gap will plot each series in its own separate sub-graph; stacking can't be combined with a series_gap . The series_gap is in pixels. If zero the graphs will be adjacent. If neither is specified, then the bars will be shown in groups (adjacent to each other) with the bars.gap between the groups. Stacking can't be combined with a log value_axis .

The value_axis always shows zero, which is where a bar is measured from, however far from it the values are - so the bars show their sizes rather than their differences. Setting an explicit value_axis.scale.minimum (or maximum ) overrides this. A log scale never reaches zero, so there a bar is measured from the bottom of the axis.

If mirrored , the series are read in pairs, so their number must be even. The 1st series of each pair grows to the left (or down) and the 2nd to the right (or up), away from the bar axis they share - a butterfly graph. Each pair therefore needs a value axis per side, and both of them show the same range, so the two sides are drawn to the same scale. Without a series_gap all the pairs share the same two value axes and are shown as groups (or stacked, given stacking ); with one, each pair is given two value axes of its own and the series_gap separates the pairs.