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(),
    names::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()
    names::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 names values (if any) are strings, one per bar, shown as the bar axis ticks; their title is the bar axis title. The bars hold the hovers and mask of the bars; masked bars are left out of the graph. The colors are optional (typically all bars have the same color); their title is the legend title. 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)
    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). The annotations are the sizes of the annotations shown next to the bars.

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.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,
    names::VectorValuesData = VectorValuesData(),
    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
    names::VectorValuesData = VectorValuesData()
    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 names values (if any) are strings, one per bar, shown as the bar axis ticks; their title is the bar axis title. The bars hold the hovers and mask shared by the bars of all the series; masked bars are left out of every series. 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 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)
    values_orientation::ValuesOrientation = VerticalValues
    bars::BarsConfiguration = BarsConfiguration()
    annotations::AnnotationSize = AnnotationSize()
    series_gap::Maybe{Real} = nothing
    stacking::Maybe{Stacking} = nothing
    mirrored::Bool = false
end

Configure a graph for showing multiple series of bars.

This expands on BarsGraphConfiguration by adding 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. The series_gap is specified as a fraction of the used graph size. If zero the graphs will be adjacent, if 1 then the gaps will be the same size as the graphs. If neither is specified, then the bars will be shown in groups (adjacent to each other) with the bars.gap between the groups. The colors of the bars are those of their series.

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.minimum (or maximum ) overrides this. A log scale never reaches zero, so there a bar is measured from the smallest value shown.

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.