Scatter Plots

Graphs for showing scatter points and/or lines.

A graph visualizing scattered points (possibly with edges between them). See PointsGraphData and PointsGraphConfiguration .

function points_graph(;
    [figure_title::Maybe{AbstractString} = nothing,
    x::VectorValuesData = VectorValuesData(),
    y::VectorValuesData = VectorValuesData(),
    points::PointsData = PointsData(),
    borders::BordersData = BordersData(),
    edges::EdgesData = EdgesData(),
    vertical_bands::BandsData = BandsData(),
    horizontal_bands::BandsData = BandsData(),
    diagonal_bands::BandsData = BandsData(),
    configuration::PointsGraphConfiguration = PointsGraphConfiguration()]
)::PointsGraph

Create a PointsGraph by initializing only the PointsGraphData fields (with an optional PointsGraphConfiguration ).

@kwdef mutable struct PointsGraphData <: AbstractGraphData
    figure_title::Maybe{AbstractString} = nothing
    x::VectorValuesData = VectorValuesData()
    y::VectorValuesData = VectorValuesData()
    points::PointsData = PointsData()
    borders::BordersData = BordersData()
    edges::EdgesData = EdgesData()
    vertical_bands::BandsData = BandsData()
    horizontal_bands::BandsData = BandsData()
    diagonal_bands::BandsData = BandsData()
end

The data for a scatter graph of points.

The x and y values are required, numeric, and of the same size (the number of points); their titles are the axis titles. If specified, the points and borders colors and sizes values must also be of the same size, as must the hovers and masks. Colors can be explicit color names if no palette is specified in the configuration; otherwise, they are either numeric values or category names depending on the type of palette specified. Sizes are the diameter in pixels (1/96th of an inch); border sizes are added to the point sizes. The colors titles are used for the legends, if show_legend is set for the relevant colors configuration (you can't specify show_legend if the colors data contains explicit color names).

The edges draw straight lines between pairs of points; see EdgesData .

The masks of the points, borders and edges allow disabling an arbitrary subset of them. This is often more convenient than excluding the data from the arrays. This is also useful for defining points which are only used to draw edges between them and aren't drawn as actual points. The properties of excluded entities, other than their coordinates, are ignored (e.g., the colors of masked points need not be valid color names). Numeric values are the exception: they must be finite whether the entity is drawn or not.

If the points and/or edges order is specified, we reorder the points and/or edges accordingly. This allows controlling which points and/or edges will appear on top of the others. Due to Plotly limitations, when using categorical colors, all the points (or edges) of one category must all be either above or below all the points of each other category. We therefore compute an overall priority for each category as the mean reordered index of all the points (or edges) of that category, and reorder the categories based on that.

@kwdef mutable struct PointsData
    colors::VectorValuesData = VectorValuesData()
    sizes::VectorValuesData = VectorValuesData()
    entities::VectorEntitiesData = VectorEntitiesData()
    order::Maybe{AbstractVector{<:Integer}} = nothing
end

The per-point data of a PointsGraphData , other than the coordinates: the colors and sizes values, the hovers and mask of the points ( entities ), and the order the points are drawn in. It mirrors the points of the PointsGraphConfiguration .

@kwdef mutable struct BordersData
    colors::VectorValuesData = VectorValuesData()
    sizes::VectorValuesData = VectorValuesData()
    mask::Maybe{Union{AbstractVector{Bool}, BitVector}} = nothing
end

The per-point data of the borders of a PointsGraphData : the colors and sizes values, and the mask of the borders. Borders share the hovers and order of the points. It mirrors the borders of the PointsGraphConfiguration .

@kwdef mutable struct EdgesData
    points::Maybe{AbstractVector{<:Tuple{Integer, Integer}}} = nothing
    colors::VectorValuesData = VectorValuesData()
    sizes::VectorValuesData = VectorValuesData()
    styles::Maybe{AbstractVector{LineStyle}} = nothing
    entities::VectorEntitiesData = VectorEntitiesData()
    order::Maybe{AbstractVector{<:Integer}} = nothing
end

The edges of a PointsGraphData : straight lines between pairs of points (given by their indices). The colors , sizes (widths) and styles override the edges of the PointsGraphConfiguration per edge. The entities hold the hovers and mask of the edges. If order is specified, the edges are drawn in that order.

@kwdef mutable struct PointsGraphConfiguration <: AbstractGraphConfiguration
    figure::FigureConfiguration = FigureConfiguration()
    x_axis::AxisConfiguration = AxisConfiguration(; expand_fraction = 0.01)
    y_axis::AxisConfiguration = AxisConfiguration(; expand_fraction = 0.01)
    points::ScattersConfiguration = ScattersConfiguration()
    borders::ScattersConfiguration = ScattersConfiguration()
    edges::ScattersConfiguration = ScattersConfiguration(sizes = SizesConfiguration(smallest = 2))
    edges_over_points::Bool = true
    vertical_bands::BandsConfiguration = BandsConfiguration()
    horizontal_bands::BandsConfiguration = BandsConfiguration()
    diagonal_bands::BandsConfiguration = BandsConfiguration()
end

Configure a graph for showing a scatter of points and/or edges.

If edges_over_points is set, the edges will be plotted above the points; otherwise, the points will be plotted above the edges. Edges are plotted using the edges_style unless the styles are specified in the data.

The borders is used if the PointsGraphData contains either the borders_colors and/or borders_sizes . This allows displaying some additional data per point.

Using the vertical_bands , horizontal_bands and/or diagonal_bands you can partition the graph into regions. The diagonal_bands can only be used if both axes are linear or both axes are in (the same) log scale. They are parallel to the X = Y line. For linear axes, the offset is additive, (Y = X + offset). For log scale axes, the offset is multiplicative (Y = X * offset), and the offset must be positive. This is a rare case where we must break orthogonality between flags, as switching between linear and log scales must be accompanied by patching the diagonal band offsets to match.

@kwdef mutable struct ScattersConfiguration <: Validated
    colors::ColorsConfiguration = ColorsConfiguration()
    sizes::SizesConfiguration() = SizesConfiguration()
end

Configure points (or borders, which are just larger points drawn under the actual points) or edges in a scatter graph. Point sizes are the diameter of the points. Border sizes are added to the point sizes. Edge sizes are the width of the lines.

points_density(
    points_xs::AbstractVector{<:Real},
    points_ys::AbstractVector{<:Real},
)::AbstractVector{<:AbstractFloat}

Given a set of point coordinates, compute for each one the density of its environment. This can be used to color the points by density.

A graph showing a single line. See LineGraphData and LineGraphConfiguration .

function line_graph(;
    [figure_title::Maybe{AbstractString} = nothing,
    x::VectorValuesData = VectorValuesData(),
    y::VectorValuesData = VectorValuesData(),
    points::VectorEntitiesData = VectorEntitiesData(),
    vertical_bands::BandsData = BandsData(),
    horizontal_bands::BandsData = BandsData(),
    diagonal_bands::BandsData = BandsData(),
    configuration::LineGraphConfiguration = LineGraphConfiguration()]
)::LineGraph

Create a LineGraph by initializing only the LineGraphData fields (with an optional LineGraphConfiguration ).

@kwdef mutable struct LineGraphData <: AbstractGraphData
    figure_title::Maybe{AbstractString} = nothing
    x::VectorValuesData = VectorValuesData()
    y::VectorValuesData = VectorValuesData()
    points::VectorEntitiesData = VectorEntitiesData()
    vertical_bands::BandsData = BandsData()
    horizontal_bands::BandsData = BandsData()
    diagonal_bands::BandsData = BandsData()
end

The data for a single line graph.

The x and y values are required, numeric, and of the same size (the number of points); their titles are the axis titles. The points hold the hovers and mask of the points, which must be of the same size if specified. Masked points are left out of the line.

@kwdef mutable struct LineGraphConfiguration <: AbstractGraphConfiguration
    figure::FigureConfiguration = FigureConfiguration()
    x_axis::AxisConfiguration = AxisConfiguration(; expand_fraction = 0.01)
    y_axis::AxisConfiguration = AxisConfiguration(; expand_fraction = 0.01)
    line::LineConfiguration = LineConfiguration()
    show_points::Bool = false
    points_size::Maybe{Real} = nothing
    points_color::Maybe{AbstractString} = nothing
    vertical_bands::BandsConfiguration = BandsConfiguration()
    horizontal_bands::BandsConfiguration = BandsConfiguration()
    diagonal_bands::BandsConfiguration = BandsConfiguration()
end

Configure a graph for showing a single line.

If show_points is set, each point is drawn, using the points_size and/or points_color if specified. The bands are similar to PointsGraphConfiguration .

A graph showing multiple lines. See LinesGraphData and LinesGraphConfiguration .

function lines_graph(;
    [figure_title::Maybe{AbstractString} = nothing,
    lines::AbstractVector{LineData} = LineData[],
    order::Maybe{AbstractVector{<:Integer}} = nothing,
    vertical_bands::BandsData = BandsData(),
    horizontal_bands::BandsData = BandsData(),
    diagonal_bands::BandsData = BandsData(),
    configuration::LinesGraphConfiguration = LinesGraphConfiguration()]
)::LinesGraph

Create a LinesGraph by initializing only the LinesGraphData fields (with an optional LinesGraphConfiguration ).

@kwdef mutable struct LinesGraphData <: AbstractGraphData
    figure_title::Maybe{AbstractString} = nothing
    lines::AbstractVector{LineData} = LineData[]
    order::Maybe{AbstractVector{<:Integer}} = nothing
    vertical_bands::BandsData = BandsData()
    horizontal_bands::BandsData = BandsData()
    diagonal_bands::BandsData = BandsData()
end

The data for a multi-line graph, a LineData per line.

The axes titles are the titles of the x (and y ) values of the lines: all the lines that give one must give the same. The name of every shown line is required if show_legend is specified in the LinesGraphConfiguration .

If order is specified, we draw the lines in that order, so later lines appear on top of (or, when stacking, above) earlier ones.

@kwdef mutable struct LineData <: AbstractPartData
    x::VectorValuesData = VectorValuesData()
    y::VectorValuesData = VectorValuesData()
    points::VectorEntitiesData = VectorEntitiesData()
    name::Maybe{AbstractString} = nothing
    hover::Maybe{AbstractString} = nothing
    is_shown::Bool = true
    color::Maybe{AbstractString} = nothing
    width::Maybe{Real} = nothing
    style::Maybe{LineStyle} = nothing
    points_size::Maybe{Real} = nothing
    points_color::Maybe{AbstractString} = nothing
end

One line of a LinesGraphData . The x and y values are required, numeric, and of the same size (the number of points of this line). The points hold the hovers and mask of these points; masked points are left out of the line. The name is shown in the legend. The hover (if any) is prefixed to the hover of each point. A line which is not is_shown is left out of the graph. The color , width , style , points_size and points_color override the LinesGraphConfiguration for this line; a nothing means the configuration default is used.

@kwdef mutable struct LinesGraphConfiguration <: AbstractGraphConfiguration
    figure::FigureConfiguration = FigureConfiguration()
    x_axis::AxisConfiguration = AxisConfiguration(; expand_fraction = 0.01)
    y_axis::AxisConfiguration = AxisConfiguration(; expand_fraction = 0.01)
    line::LineConfiguration = LineConfiguration()
    show_points::Bool = false
    points_size::Maybe{Real} = nothing
    points_color::Maybe{AbstractString} = nothing
    vertical_bands::BandsConfiguration = BandsConfiguration()
    horizontal_bands::BandsConfiguration = BandsConfiguration()
    diagonal_bands::BandsConfiguration = BandsConfiguration()
    show_legend::Bool = false
end

Configure a graph for showing multiple lines.

This is similar to LineGraphConfiguration , with the addition of show_legend . If this is set, then the data must specify the title to use for each line.

If stacking is specified, we stack the values on top of each other.