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()
    value_bands::BandsConfiguration = BandsConfiguration()
    cumulative_axis::CumulativeAxisConfiguration = CumulativeAxisConfiguration()
    cumulative_bands::BandsConfiguration = BandsConfiguration()
end

Configure a graph for showing a single distribution. The cumulative_axis and cumulative_bands are only used if the distribution.style is CumulativeDistribution . The offsets of the cumulative_bands are always in fractions (between 0 and 1) regardless of the cumulative_axis.units .

SomeGraphs.Distributions.DistributionConfiguration — Type 
@kwdef mutable struct DistributionConfiguration <: Validated
    values_orientation::ValuesOrientation = HorizontalValues
    style::DistributionStyle = CurveDistribution
    line::LineConfiguration = LineConfiguration(; is_filled = true)
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.

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)
SomeGraphs.Distributions.CumulativeUnits — Type

Possible units for the distribution axis of a cumulative distribution:

CumulativeFractions - the axis is the fraction of entries.

CumulativePercents - the axis is the percent of entries.

CumulativeCounts - the axis is the number of entries.

SomeGraphs.Distributions.CumulativeAxisConfiguration — Type 
@kwdef mutable struct CumulativeAxisConfiguration
    units::CumulativeUnits = CumulativeFractions
    descending::Bool = false
    show_ticks::Bool = true
    show_grid::Bool = true
    grid_color::AbstractString = "lightgrey"
    title::Maybe{AbstractString} = nothing
end

Possible configurations for the distribution axis of a cumulative distribution, using the specified units . Normally we count the entries up to some value, so the graph is ascending; if descending , we count the entries down to some value, so the graph is descending.

This intentionally offers only a subset of the fields of AxisConfiguration .

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, fractions). 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)

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.cumulative_axis.units = CumulativePercents
using PlotlyDocumenter
to_documenter(graph.figure)

Counts: 

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.cumulative_axis.units = CumulativeCounts
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.cumulative_axis.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,
    distributions_values::AbstractVector{<:AbstractVector{<:Real}} = Vector{Float32}[],
    distributions_names::Maybe{AbstractVector{<:AbstractString}} = nothing,
    distributions_colors::Maybe{AbstractVector{<:AbstractString}} = nothing,
    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
    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
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.

You can only specify the density_axis_title if the distributions_gap is nothing (that is, if there is a single density axis). Otherwise, the distributions_names are used for each graph's 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()
    cumulative_axis::CumulativeAxisConfiguration = CumulativeAxisConfiguration()
    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.

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. The cumulative_axis is only used if the distribution.style is CumulativeDistribution .

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