GitHub

Distributions

SomeGraphs.Distributions.distribution_graph — Function 
distribution_graph(;
    [figure_title::Maybe{AbstractString} = nothing,
    value_axis_title::Maybe{AbstractString} = nothing,
    distribution_values::AbstractVector{<:Real} = Float32[],
    distribution_name::Maybe{AbstractString} = nothing,
    configuration::DistributionGraphConfiguration = DistributionGraphConfiguration()]
)::DistributionGraph

Create a DistributionGraph by initializing only the DistributionGraphData fields (with an optional DistributionGraphConfiguration ).

SomeGraphs.Distributions.DistributionGraphData — Type 
@kwdef mutable struct DistributionGraphData <: AbstractGraphData
    figure_title::Maybe{AbstractString} = nothing
    value_axis_title::Maybe{AbstractString} = nothing
    distribution_values::AbstractVector{<:Real} = Float32[]
    distribution_name::Maybe{AbstractString} = nothing
    distribution_color::Maybe{AbstractString} = nothing
    value_bands::BandsData = BandsData()
    cumulative_bands::BandsData = BandsData()
end

The data for a single distribution graph. By default, all the titles are empty. You can specify the overall figure_title as well as the value_axis_title . The optional distribution_name is used as the name of the density axis. You can also specify the distribution_color and/or value_bands offsets here, if they are more of a data than a configuration parameter in the specific graph. This will override whatever is specified in the configuration.

The cumulative_bands should only be specified if the distribution.style is CumulativeDistribution .

Examples:

Default (serves as a baseline to compare with when modifying options): 

using SomeGraphs
graph = distribution_graph(; distribution_values = [0, 0, 1, 1, 1, 3])
using PlotlyDocumenter
to_documenter(graph.figure)

Titles: 

using SomeGraphs
graph = distribution_graph(; distribution_values = [0, 0, 1, 1, 1, 3])
graph.data.figure_title = "Figure title"
graph.data.value_axis_title = "Values axis"
graph.data.distribution_name = "Distribution name"
using PlotlyDocumenter
to_documenter(graph.figure)

Color (if it is more of a data than a configuration parameter): 

using SomeGraphs
graph = distribution_graph(; distribution_values = [0, 0, 1, 1, 1, 3])
graph.data.distribution_color = "red"
using PlotlyDocumenter
to_documenter(graph.figure)
SomeGraphs.Distributions.DistributionGraphConfiguration — Type 
@kwdef mutable struct DistributionGraphConfiguration <: AbstractGraphConfiguration
    figure::FigureConfiguration = FigureConfiguration()
    distribution::DistributionConfiguration = DistributionConfiguration()
    value_axis::AxisConfiguration = AxisConfiguration(; expand_fraction = 0.01)
    value_bands::BandsConfiguration = BandsConfiguration()
    density_axis::AxisConfiguration = AxisConfiguration()
    cumulative_bands::BandsConfiguration = BandsConfiguration()
end

Configure a graph for showing a single distribution. The density_axis configures the inner density axis (the bin counts for a HistogramDistribution , the cumulative scale for a CumulativeDistribution ); it must be left at its default for the other styles, which have no meaningful density scale. The cumulative_bands are only used if the distribution.style is CumulativeDistribution ; their offsets are always in fractions (between 0 and 1) regardless of the distribution.normalize and density_axis.percent settings.

SomeGraphs.Distributions.DistributionConfiguration — Type 
@kwdef mutable struct DistributionConfiguration <: Validated
    values_orientation::ValuesOrientation = HorizontalValues
    style::DistributionStyle = CurveDistribution
    line::LineConfiguration = LineConfiguration(; is_filled = true)
    normalize::Bool = false
    cumulative_descending::Bool = false
end

Configure the style of the distribution(s) in a graph.

The values_orientation will determine the overall orientation of the graph.

The line.color is chosen automatically by default. When showing multiple distributions, you can override it per each one in the DistributionsGraphData . By default, the distribution is filled. Plotly only allows for solid lines for distributions, and always fills histogram plots without any line.

If normalize is set, the density axis shows the fraction of the entries instead of their count; this is only allowed for HistogramDistribution and CumulativeDistribution . For a CumulativeDistribution , if cumulative_descending is set, we count the entries down to some value (so the graph is descending) instead of up to some value (so the graph is ascending).

Examples:

Change orientation: 

using SomeGraphs
graph = distribution_graph(; distribution_values = [0, 0, 1, 1, 1, 3])
graph.configuration.distribution.values_orientation = VerticalValues
using PlotlyDocumenter
to_documenter(graph.figure)
SomeGraphs.Distributions.DistributionStyle — Type

Possible styles for visualizing a distribution:

CurveDistribution - a density curve (the default).

ViolinDistribution - same as a density curve but mirrored below the values axis.

BoxDistribution - a box with whiskers to show important distribution values.

BoxOutliersDistribution - a box with outlier points and whiskers to show important distribution values.

CurveBoxDistribution - combine a curve and a box.

ViolinBoxDistribution - combine a violin and a box.

HistogramDistribution - a histogram of the distribution.

'CumulativeDistribution' - a cumulative distribution (aka "CDF"). This one allows for additional configuration options.

Examples:

Violin: 

using SomeGraphs
graph = distribution_graph(; distribution_values = [0, 0, 1, 1, 1, 3])
graph.configuration.distribution.style = ViolinDistribution
using PlotlyDocumenter
to_documenter(graph.figure)

Box: 

using SomeGraphs
graph = distribution_graph(; distribution_values = [0, 0, 1, 1, 1, 3])
graph.configuration.distribution.style = BoxDistribution
using PlotlyDocumenter
to_documenter(graph.figure)

Box with outliers: 

using SomeGraphs
graph = distribution_graph(; distribution_values = [0, 0, 1, 1, 1, 3])
graph.configuration.distribution.style = BoxOutliersDistribution
using PlotlyDocumenter
to_documenter(graph.figure)

Curve and Box: 

using SomeGraphs
graph = distribution_graph(; distribution_values = [0, 0, 1, 1, 1, 3])
graph.configuration.distribution.style = CurveBoxDistribution
using PlotlyDocumenter
to_documenter(graph.figure)

Violin and Box: 

using SomeGraphs
graph = distribution_graph(; distribution_values = [0, 0, 1, 1, 1, 3])
graph.configuration.distribution.style = ViolinBoxDistribution
using PlotlyDocumenter
to_documenter(graph.figure)

Histogram: 

using SomeGraphs
graph = distribution_graph(; distribution_values = [0, 0, 1, 1, 1, 3])
graph.configuration.distribution.style = HistogramDistribution
using PlotlyDocumenter
to_documenter(graph.figure)

Color (if it is more of a configuration parameter than data): 

using SomeGraphs
graph = distribution_graph(; distribution_values = [0, 0, 1, 1, 1, 3])
graph.configuration.distribution.line.color = "red"
using PlotlyDocumenter
to_documenter(graph.figure)

Line width and disable fill: 

using SomeGraphs
graph = distribution_graph(; distribution_values = [0, 0, 1, 1, 1, 3])
graph.configuration.distribution.line.width = 4
graph.configuration.distribution.line.is_filled = false
using PlotlyDocumenter
to_documenter(graph.figure)

Bands (if the offset is more of a configuration parameter than data): 

using SomeGraphs
graph = distribution_graph(; distribution_values = [0, 0, 1, 1, 1, 3])
graph.configuration.value_bands.middle.offset = 2
using PlotlyDocumenter
to_documenter(graph.figure)

Examples:

Cumulative distribution functions are an undervalued tool for showing distributions. They have the advantage that the second axis is in actual units (by default, counts). This opens up additional configuration options. 

using SomeGraphs
graph = distribution_graph(; distribution_values = [0, 0, 1, 1, 1, 3])
graph.configuration.distribution.style = CumulativeDistribution
graph.configuration.distribution.line.is_filled = true
using PlotlyDocumenter
to_documenter(graph.figure)

Fractions: 

using SomeGraphs
graph = distribution_graph(; distribution_values = [0, 0, 1, 1, 1, 3])
graph.configuration.distribution.style = CumulativeDistribution
graph.configuration.distribution.line.is_filled = true
graph.configuration.distribution.normalize = true
using PlotlyDocumenter
to_documenter(graph.figure)

Percents: 

using SomeGraphs
graph = distribution_graph(; distribution_values = [0, 0, 1, 1, 1, 3])
graph.configuration.distribution.style = CumulativeDistribution
graph.configuration.distribution.line.is_filled = true
graph.configuration.distribution.normalize = true
graph.configuration.density_axis.percent = true
using PlotlyDocumenter
to_documenter(graph.figure)

Descending: 

using SomeGraphs
graph = distribution_graph(; distribution_values = [0, 0, 1, 1, 1, 3])
graph.configuration.distribution.style = CumulativeDistribution
graph.configuration.distribution.line.is_filled = true
graph.configuration.distribution.cumulative_descending = true
using PlotlyDocumenter
to_documenter(graph.figure)
SomeGraphs.Distributions.distributions_graph — Function 
distributions_graph(;
    [figure_title::Maybe{AbstractString} = nothing,
    value_axis_title::Maybe{AbstractString} = nothing,
    density_axis_title::Maybe{AbstractString} = nothing,
    series_axis_title::Maybe{AbstractString} = nothing,
    distributions_values::AbstractVector{<:AbstractVector{<:Real}} = Vector{Float32}[],
    distributions_names::Maybe{AbstractVector{<:AbstractString}} = nothing,
    distributions_colors::Maybe{AbstractVector{<:AbstractString}} = nothing,
    distributions_order::Maybe{AbstractVector{<:Integer}} = nothing,
    value_bands::BandsData = BandsData(),
    configuration::DistributionsGraphConfiguration = DistributionsGraphConfiguration()]
)::DistributionsGraph

Create a DistributionsGraph by initializing only the DistributionsGraphData fields (with an optional DistributionsGraphConfiguration ).

SomeGraphs.Distributions.DistributionsGraphData — Type 
@kwdef mutable struct DistributionsGraphData <: AbstractGraphData
    figure_title::Maybe{AbstractString} = nothing
    value_axis_title::Maybe{AbstractString} = nothing
    density_axis_title::Maybe{AbstractString} = nothing
    series_axis_title::Maybe{AbstractString} = nothing
    distributions_values::AbstractVector{<:AbstractVector{<:Real}} = Vector{Float32}[]
    distributions_names::Maybe{AbstractVector{<:AbstractString}} = nothing
    distributions_colors::Maybe{AbstractVector{<:AbstractString}} = nothing
    distributions_order::Maybe{AbstractVector{<:Integer}} = nothing
    value_bands::BandsData = BandsData()
end

The data for a multiple distributions graph. By default, all the titles are empty. You can specify the overall figure_title as well as the value_axis_title . If specified, the distributions_names and/or the distributions_colors vectors must contain the same number of elements as the number of vectors in the distributions_values .

If distributions_order are specified, we reorder the distributions accordingly. This allows controlling which distributions will appear on top of the others.

The density_axis_title titles the inner density axis. The series_axis_title titles the cross-series names axis and may only be specified when there is a gap ( distributions_gap is not nothing ). At most one of the two may be specified; when there is a gap, whichever is given is used to title the series axis.

Examples:

Default (serves as a baseline to compare with when modifying options): 

using SomeGraphs
graph = distributions_graph(; distributions_values = [[0, 0, 1, 1, 1, 3], [4, 4, 3, 3, 3, 1]])
using PlotlyDocumenter
to_documenter(graph.figure)
SomeGraphs.Distributions.DistributionsGraphConfiguration — Type 
@kwdef mutable struct DistributionsGraphConfiguration <: AbstractGraphConfiguration
    figure::FigureConfiguration = FigureConfiguration()
    distribution::DistributionConfiguration = DistributionConfiguration()
    value_axis::AxisConfiguration = AxisConfiguration(; expand_fraction = 0.01)
    value_bands::BandsConfiguration = BandsConfiguration()
    density_axis::AxisConfiguration = AxisConfiguration()
    series_axis::AxisConfiguration = AxisConfiguration()
    distributions_gap::Maybe{Real} = 0.05
end

Configure a graph for showing multiple distributions.

This is similar to DistributionGraphConfiguration , with additions to deal with having multiple distributions. The density_axis configures the inner density axis exactly as in the single-distribution graph.

If distributions_gap is set to nothing , overlay the distributions on top of each other. Otherwise, the distributions are plotted next to each other, with the distributions_gap 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.

When there is a gap, the series_axis configures the cross-series names axis (the per-series names shown next to the sub-graphs). Only its show_ticks (whether to show the names), ticks_angle (by default the names are shown parallel to the axis, as if they were its title) and title are used; the numeric and grid fields are not applicable.

Titles: 

using SomeGraphs
graph = distributions_graph(;
    distributions_values = [[0, 0, 1, 1, 1, 3], [4, 4, 3, 3, 3, 1]],
    distributions_names = ["Foo", "Bar"],
    figure_title = "Figure title",
    value_axis_title = "Values title",
)
using PlotlyDocumenter
to_documenter(graph.figure)

Size of gap between distributions: 

using SomeGraphs
graph = distributions_graph(; distributions_values = [[0, 0, 1, 1, 1, 3], [4, 4, 3, 3, 3, 1]])
graph.configuration.distributions_gap = 0.05
using PlotlyDocumenter
to_documenter(graph.figure)

Overlay the distributions: 

using SomeGraphs
graph = distributions_graph(; distributions_values = [[0, 0, 1, 1, 1, 3], [4, 4, 3, 3, 3, 1]])
graph.configuration.distributions_gap = nothing
using PlotlyDocumenter
to_documenter(graph.figure)

Overlay the distributions with a legend: 

using SomeGraphs
graph = distributions_graph(;
    distributions_values = [[0, 0, 1, 1, 1, 3], [4, 4, 3, 3, 3, 1]],
    distributions_names = ["Foo", "Bar"],
)
graph.configuration.distributions_gap = nothing
using PlotlyDocumenter
to_documenter(graph.figure)

Colors (if they are part of the data): 

using SomeGraphs
graph = distributions_graph(;
    distributions_values = [[0, 0, 1, 1, 1, 3], [4, 4, 3, 3, 3, 1]],
    distributions_colors = ["red", "green"],
)
using PlotlyDocumenter
to_documenter(graph.figure)

You can also apply any of the distribution and/or value axis configuration options; these will apply to all the distributions: 

using SomeGraphs
graph = distributions_graph(; distributions_values = [[0, 0, 1, 1, 1, 3], [4, 4, 3, 3, 3, 1]])
graph.configuration.distribution.values_orientation = VerticalValues
graph.configuration.distribution.line.color = "red"
graph.configuration.distribution.style = BoxOutliersDistribution
using PlotlyDocumenter
to_documenter(graph.figure)

Index