Common

Common data types and utilities for defining specific graph types.

The type of a figure we can display. This is a combination of some AbstractGraphData and AbstractGraphConfiguration . Accessing the .fig property of the graph will return it as a PlotlyFigure , which can be displayed in interactive environments (such as Jupyter notebooks or a Plotly-aware IDE). Accessing the .json property will return the same figure as a JSON string, for handing the graph over to another programming language (e.g., to display it in a Python or R Jupyter notebook). Accessing the .html property will return it as an HTML page, which loads plotly.js from the internet, and the .standalone_html property as a page which includes it, so it works offline (see graph_to_html ). Accessing the .svg or .png property will return the graph as a static image (see graph_to_image ).

A configuration of a Graph specifies how to display the data while being (as much as possible) independent of the data itself. That is, it should be possible to apply the same configuration to multiple sets of data to generate multiple similar graphs. In some cases (e.g., colors) you can specify a default in the configuration and override it for specific entities in the data.

Some data of a Graph specifies what to display the data while being (as much as possible) independent of how to display it. That is, it should be possible to apply multiple sets of data to the same configuration to to generate multiple similar graphs. In some cases (e.g., colors) you can specify a default in the configuration and override it for specific entities in the data.

One of the several parts a graph can be built from: a series of bars, a line, a distribution. Every part has its own name (shown in the legend), a hover prefixed to the hover of each of its entries, an is_shown which leaves it out of the graph, and a color . It also holds the entities of its entries (the bars of a series of bars, the points of a line). In addition it holds whatever other data is needed forthe part - values or x and y coordinates, width , etc.

The type of a rendered graph which Julia knows how to display.

A plotly figure contains everything needed to display an interactive graph (or generate a static one on disk). It can also be converted to a JSON string for handing it over to a different programming language (e.g., to be used to display the interactive graph in a Python Jupyter notebook, given an appropriate wrapper code).

save_graph(graph::Graph, output_file::AbstractString; standalone::Bool = false)::Nothing

Save the graph to a file. Unlike the Plotly savefig function, this function will actually obey the width and height parameters specified in the graph's configuration. The format is deduced from the suffix of the file name. An .html file is the page graph_to_html gives, which includes plotly.js if standalone .

flip_axes(graph::Graph)::Graph

Return a new graph with the axes flipped (X <-> Y for scatter/line graphs, rows <-> columns for heatmap graphs). The returned graph shares storage of arrays and configuration objects from the original graph where possible. Matrices are transposed using zero-copy views ( transpose for numeric, PermutedDimsArray for non-numeric).

flip_axes!(graph::Graph)::Graph

Flip the axes of the given graph in-place (X <-> Y for scatter/line graphs, rows <-> columns for heatmap graphs) and return it. Matrices are transposed using zero-copy views ( transpose for numeric, PermutedDimsArray for non-numeric).

@kwdef mutable struct FigureConfiguration <: Validated
    margins::MarginsConfiguration = MarginsConfiguration()
    width::Maybe{Int} = nothing
    height::Maybe{Int} = nothing
    background_color::AbstractString = "white"
    paper_color::AbstractString = "white"
    legends_gap::Int = 10
end

Generic configuration that applies to the whole figure. Each complete AbstractGraphConfiguration contains a figure field of this type.

The optional width and height are in pixels, that is, 1/96 of an inch. The margins are specified in the same units.

You can also manually change the background_color (inside the graph's area) and paper_color (outside the graph's area, that is, the margins).

The legends and color scales of a graph (see LegendConfiguration ) are in a side panel to the right of the plot. The panel is placed in columns, each as wide as its widest legend, and the right margin is the panel's width plus the margins.right . The legends_gap (in pixels) separates the plot from the panel, the columns from each other, and the legends of a column from each other. Widths are in pixels, but heights are fractions of the plot's height, so the legends follow the plot's height when an interactive graph is resized. When the height isn't specified, the fractions are computed for Plotly's default height (450 pixels).

If stacking elements, how to do so:

StackValues just adds the raw values on top of each other.

StackFractions normalizes the values so their sum is 1. This can be combined with setting the percent of the scale of the relevant AxisConfiguration to display percents.

@kwdef mutable struct MarginsConfiguration <: Validated
    left::Int = 10
    bottom::Int = 10
    right::Int = 10
    top::Int = 10
end

Configure the margins of the graph. Sizes are in pixels (1/96th of an inch). Each margin is the space beyond what lies on its side of the plot's area: the tick labels and titles of the axes, the titles of the annotations, the figure's title (above) and the side panel (to the right). The space these take is estimated from their texts, for the widest labels Plotly may draw. If an estimate falls short and something is clipped, increase that side's margin.

@kwdef mutable struct AxisConfiguration <: Validated
    scale::ScaleConfiguration = ScaleConfiguration()
    expand_fraction::Real = 0
    show_ticks::Bool = true
    ticks_angle::Maybe{Real} = nothing
    show_grid::Bool = true
    grid_color::AbstractString = "lightgrey"
    title::Maybe{AbstractString} = nothing
end

Generic configuration for a drawn graph axis. The scale says how the values are mapped to the range they are shown in (see ScaleConfiguration ); the rest says how the axis is drawn.

The expand_fraction grows the visible range by this fraction of its size on each side (e.g. 0.01 adds 1% at both ends). This keeps round markers at the extreme values from being clipped by the plot border. It is applied in the scaled (e.g. log) space, after the minimum and maximum are determined.

The show_ticks and/or show_grid can be disabled for a cleaner (though less informative) graph appearance. By default the grid lines are shown in lightgrey . The ticks_angle rotates the tick labels and is measured relative to the axis (between -90 and 90): 0 keeps the text parallel to the axis and ±90 stands it perpendicular, positive being clockwise. By default ( nothing ) the labels are horizontal, which is the readable orientation for numbers regardless of the axis direction. The titles of the annotations next to the tick labels (in a bars graph) follow a set ticks_angle . By default, a title below an annotation stands up, so the titles of neighbouring annotations don't overlap.

If title is specified, it will be shown next to the axis. However, in some cases the correct title depends on the data set, so you can override this in the data.

@kwdef mutable struct ScaleConfiguration <: Validated
    minimum::Maybe{Real} = nothing
    maximum::Maybe{Real} = nothing
    include_hidden::Bool = true
    log_base::Maybe{LogBase} = nothing
    log_regularization::Real = 0
    percent::Bool = false
end

How to map data values to the range they are shown in. This is the numeric half of an AxisConfiguration , and is also what colors and sizes are mapped through, since neither of these is a drawn axis.

Everything is optional; by default, the minimum and maximum are computed automatically from the data. Entities hidden by a mask (see VectorEntitiesData ) still take part in this computation, so hiding some of them does not move the range. Set include_hidden to false to compute the range from the shown entities only.

If log_base is specified, then the log_regularization is added to the value to avoid zero values, and the values are shown according to the LogBase . Otherwise, log_regularization must be 0.

If percent is set, then the values are multiplied by 100 and a % suffix is added to the tick labels.

The minimum/maximum, data values, color palette values etc. are all in the original scale. That is, you should be able to control log scale and/or percent scaling without changing anything else.

Supported bases for taking the log of values (when log scaling is enabled):

• Log10Base converts values to their log (base 10). The ticks show the real values (such as 1, 10, 100 or 1, 2, 5, 10), using SI suffixes (such as 10k or 1M). Plotly picks the ticks, so they adapt to the size of the graph and to zooming.

• Log2Base converts values to their log (base 2). The ticks show the log values, with a subscript 2 prefix.

Stacking can't be combined with a log scale.

@kwdef mutable struct LegendConfiguration <: Validated
    show::Bool = false
    width::Maybe{Integer} = nothing
    height::Maybe{Real} = nothing
    column::Maybe{Integer} = nothing
    order::Maybe{Real} = nothing
end

Configure the legend (or color scale) of something shown in a graph. It is shown only if show is set. The other fields control its place in the side panel to the right of the graph, and can only be specified if show is set.

The width is in pixels. By default it is computed from the legend's content. The height is a fraction of the plot's height. The column is the index of the side panel's column the legend is placed in, where 1 is the column next to the plot. By default the legends are packed into columns automatically.

The legends of a column are placed from the top by their order . By default this is 1 for a categorical legend, 2 for a color scale and 3 for a legend of sizes, and legends of the same order keep the order of the graph's parts. For example, an order of 0 places a legend at the top of its column, and 1.5 between the categorical legends and the color scales.

@kwdef mutable struct SizesConfiguration <: Validated
    fixed::Maybe{Real} = nothing
    scale::ScaleConfiguration = ScaleConfiguration()
    smallest::Real = 6
    span::Real = 12
    legend::LegendConfiguration = LegendConfiguration()
    title::Maybe{AbstractString} = nothing
end

Configure how to map sizes data to a size in pixels (1/96th of an inch). If fixed is specified, it is the size to be used, the scale and legend must be left at their defaults, the smallest and span are not used, and no sizes data may be specified. Otherwise, sizes data must be specified. The scale maps the sizes data: values at most its minimum (or the minimal value) are mapped to the smallest size in pixels, values at least its maximum (or the maximal value) are mapped to a size with an additional span in pixels, and if log_base is set the log of the values (plus the log_regularization ) is used instead. The percent of the scale does not apply to sizes and must be left unset.

If the legend is shown, it is to the side of the graph and shows some sizes and the values they stand for (it requires sizes data, so it can't be combined with fixed ). The entries are chosen as described in sizes_legend_entries . The legend takes its place in the side panel (see FigureConfiguration ). It is a Plotly legend, which can only draw a point up to 21 pixels, a border up to 10 pixels, and an edge up to 10 pixels; larger sizes are drawn at these limits (with the right labels).

If title is specified, it will be used when showing the legend. However, in some cases the correct title depends on the data set, so you can override this in the data.

@kwdef mutable struct LineConfiguration <: Validated
    width::Maybe{Real} = nothing
    style::Maybe{LineStyle} = SolidLine
    is_filled::Bool = false
    color::Maybe{AbstractString} = nothing
end

Configure a line in a graph.

If style is nothing no line is drawn. If is_filled then the region defined by the line (below it in a lines graph) is filled. A line with no style and no filled is not drawn but can still be used to define a region (e.g., for a BandsConfiguration ).

By default, the color is chosen automatically.

Styles of drawing a line

• SolidLine draws a solid line (the default).

• DashLine draws a dashed line.

• DotLine draws a dotted line.

• DashDotLine draws a dash-dotted line.

The orientation of the values axis in a distribution(s) or bars graph:

HorizontalValues - The values are the X axis

VerticalValues - The values are the Y axis.

The default depends on the graph (see its configuration).

@kwdef mutable struct BandsConfiguration <: Validated
    low::BandConfiguration = BandConfiguration(; line = LineConfiguration(; style = DotLine))
    middle::BandConfiguration = BandConfiguration()
    high::BandConfiguration = BandConfiguration(; line = LineConfiguration(; style = DashLine))
end

Configure the partition of the graph up to three band regions. The low and high bands are for the "outer" regions (so their lines are at their border, dotted and dashed by default) and the middle band is for the "inner" region between them (so its line is inside it, solid by default).

@kwdef mutable struct BandConfiguration <: Validated
    offset::Maybe{Real} = nothing
    line::LineConfiguration = LineConfiguration()
end

Configure a region of the graph defined by some band of values.

The offset specifies the band's defining line position. We allow up to three bands in a complete BandsConfiguration . A band exists only if its offset is specified, in which case the line specifies how to render its defining line. The low and high bands are defined the region below and above their defining line's offset . If both are defined, the middle band offset defines the center line of the band; the band can still be filled even if this offset is not specified.

@kwdef mutable struct BandsData
    low_offset::Maybe{Real} = nothing
    middle_offset::Maybe{Real} = nothing
    high_offset::Maybe{Real} = nothing
end

Specify data for bands.

@kwdef mutable struct ColorsConfiguration <: Validated
    palette::Maybe{Union{AbstractString, ContinuousColors, CategoricalColors, AutomaticColors}} = nothing
    fixed::Maybe{AbstractString} = nothing
    scale::ScaleConfiguration = ScaleConfiguration()
    legend::LegendConfiguration = LegendConfiguration()
    title::Maybe{AbstractString} = nothing
end

Configure how to color some data. Supported combinations of configuration and data are:

fixed	palette	colors data	scale	legend.show	Behavior
color name	nothing	nothing	Restricted(S)	false	Named fixed (1)
nothing	nothing	nothing	Restricted(S)	false	Auto fixed (2)
nothing	nothing	str[]	Restricted(S)	false	Named data (3)
nothing	nothing	num[]	Any	Any	Auto scale (4)
nothing	palette name	num[]	Any	Any	Named scale (5)
nothing	(value::num, color::str)[]	num[]	Any	Any	Manual scale (6)
nothing	Dict{value::str => color::str}	str[]	Restricted(S)	Any	Categorical (7)
nothing	AutomaticColors()	str[]	Restricted(S)	Any	Automatic (8)

Any other combination of configuration is not allowed.

Restricted Scale: The scale can't specify log_base , percent , minimum , maximum as they make no sense in this case.

Named fixed (1): All the data entities will be given the same fixed color.

Auto fixed (2): All the data entities will be given the same color, chosen automatically by Plotly.

Named data (3): The colors data contains explicit color names. An empty color name will prevent the matching data from being plotted.

Auto scale (4): The colors data (transformed by the scale ) will be shown in a color scale chosen by Plotly.

Named scale (5): The colors data (transformed by the scale ) will be shown using the named standard Plotly color scale (see NAMED_COLOR_SCALES ).

Manual scale (6): The colors data (transformed by the scale ) will be shown using the specified palette (whose values will also be transformed by the scale ). The values must be in non-decreasing order, and the overall range of values must not be empty.

Categorical (7): The colors data contains valid value keys of the categorical colors dictionary. An empty color name in the data or the dictionary will prevent the matching data from being plotted.

Automatic (8): The colors data contains categorical keys, whose colors are picked automatically (see AutomaticColors ).

If the legend is shown, categorical colors (cases 7 and 8 above) will be shown in a legend; numerical colors will be shown in a color scale. Either takes its place in the side panel (see FigureConfiguration ). A color scale is half the plot's height by default.

If title is specified, it will be used when showing the legend (whatever it is). However, in some cases the correct title depends on the data set, so you can override this in the data.

A continuous colors palette, mapping numeric values to colors. We also allow specifying tuples instead of pairs to make it easy to invoke the API from other languages such as Python which do not have the concept of a Pair .

A categorical colors palette, mapping string values to colors. An empty string color means the entity will not be shown (as if it was masked or never included in the data). As a convenience, a named vector of strings can be specified instead of a dictionary.

The legend lists the values in the order of the palette. A Dict has no order of its own, so use an OrderedDict (or a named vector) to control it.

struct AutomaticColors end

A marker for the palette of a ColorsConfiguration specifying that string color values are categorical keys (rather than explicit color names), to be shown as separate series whose colors are picked automatically (the same way colors are picked for any other series). This is the only way to have separate auto-colored series without specifying the colors at all.

categorical_palette(
    values::Union{AbstractSet{<:AbstractString}, AbstractVector{<:AbstractString}},
    palette::Union{AbstractString, ContinuousColors} = "HSV",
)::CategoricalColors

Given some string values , generate a categorical palette for them based on some continuous palette . This is done by giving each unique value an index from 1 to N and then mapping the range 0 to N into the continuous palette (adding 0 allows for safely using cyclical palettes). This palette should have as many distinct colors in it as possible, to maximize legibility of the result; HSV is a good default choice.

Builtin color scales from Plotly , both linear: Blackbody , Bluered , Blues , Cividis , Earth , Electric , Greens , Greys , Hot , Jet , Picnic , Portland , Rainbow , RdBu , Reds , Viridis , YlGnBu , YlOrRd and cyclical: Twilight , IceFire , Edge , Phase , HSV , mrybm , mygbm . In addition, BuWtRd which is useful for showing +/- diff values and WtYlOrRdDm is useful for showing absolute values.

A _r suffix specifies reversing the order of the scale.

You can also append a final _z:<value_fraction>:<color_fraction> suffix to the name. This will map values in the bottom 0.. value_fraction of the range to white, and map the rest of the values to the top color_fraction ..1 range of the scale. For example, Blues_z:0.3:0.2 will color the bottom 30% of the values in white, and color the top 70% of the values to the top 80% of the Blues scale.

A _c:<value_fraction>:<color_fraction> works similarly to the _z suffix, except that the fractions are centered on 0.5 (the middle) of the values and color ranges. This is meant to be applied when the values range is +/-Diff, and the scale has white in the middle. For example RdBu_c:0.3:0.2 will color the 30% of the values near the 0 middle in white, and color the rest of the values using the top and bottom 40% of the RdBu scale.

An _o:<value_fraction>:<color> suffix maps the scale to the range 0.. 1-value_fraction , and all the values above this to the color , to denote overflow (too high) values. For example, Blues_o:0.01:magenta will color all the values in the bottom 99% of the values range to Blues , and the top 1% of the range to magenta. A _u suffix works similarly but applies to the bottom range of the values.

You can combine multiple suffixes together, for example Reds_z:0.2:0.2_o:0.01:magenta or RdBu_r_c:0.2:0.2_o:0.01:magenta_u:0.01:darkgreen .

Palettes with suffixes (including _r ) are computed on the fly and cached for future use.

A global lock to use when accessing the NAMED_COLOR_SCALES . Always hold the COLOR_SCALES_LOCK when manually accessing the NAMED_COLOR_SCALES , otherwise you will regret it at some point.

@kwdef mutable struct AnnotationData <: Validated
    values::VectorValuesData = VectorValuesData()
    colors::ColorsConfiguration = ColorsConfiguration()
    is_shown::Bool = true
end

An annotation to attach to an axis. This applies to discrete axes (bars axis for a BarsGraph or the rows and/or columns of a HeatmapGraph ). The values are required, one per entry of the axis. Hovering an annotation shows the hovers of the axis entries. An annotation which is not is_shown is left out of the graph, and gives up its place in the row of annotations.

The title of the annotation is the title of the values , falling back to the title of the colors . It names the annotation next to the axis, and titles its legend or color scale.

The colors configuration is part of the data, because the color of annotations (in particular, categorical ones) is tightly coupled with the data.

@kwdef mutable struct AnnotationSize <: Validated
    size::Integer = 16
    gap::Integer = 2
end

Specify the sizes of annotations shown to the side of an axis, with a gap between each other and the graph itself, in pixels. By default, an annotation is as tall as its title (a 12 pixels font with 2 pixels of padding on each side), and the gap is a hairline, so the annotations read as one block.

@kwdef mutable struct VectorValuesData
    vector::Maybe{Union{AbstractVector{<:Real}, AbstractVector{<:AbstractString}}} = nothing
    title::Maybe{AbstractString} = nothing
end

A value per entity for one role of a graph (the X coordinates of points, their colors, the names of bars, ...), and the title of these values (which becomes the axis title, the colors title, ...). A role that is not in use has no vector . Whether string values are allowed depends on the role.

@kwdef mutable struct VectorEntitiesData
    names::Maybe{AbstractVector{<:AbstractString}} = nothing
    hovers::Maybe{AbstractVector{<:AbstractString}} = nothing
    mask::Maybe{Union{AbstractVector{Bool}, BitVector}} = nothing
    order::Maybe{AbstractVector{<:Integer}} = nothing
end

The names, hovers, mask and order of one set of entities of a graph (the points of a points graph, the bars of a bars graph, ...), shared by all the roles of these entities.

The names identify the entities. Where the graph has room to label them, they are shown as the tick labels of their axis. They are also the first line of the hover of each entity, so the hovers are whatever you wish to say about an entity in addition to its name. Hovers are only shown in interactive graphs (or when saving an HTML file).

The mask hides an arbitrary subset of the entities. Hidden entities are still part of the data: they take part in whatever is computed from it (axis ranges, clustering), unless the relevant configuration says otherwise (see include_hidden in ScaleConfiguration ). They are just not drawn.

The order is a permutation of the entities. What it means depends on the graph: the order the points of a scatter graph are drawn in, the order of the bars of a bars graph along the bar axis, or the layout of an axis of a heatmap. It describes all the entities, hidden ones included. A graph which has no use for an order of some entities rejects it rather than ignoring it.

@kwdef mutable struct ArrangementData
    hclust::Maybe{Hclust} = nothing
    groups::VectorValuesData = VectorValuesData()
    subgroups::VectorValuesData = VectorValuesData()
    arrange_by::Maybe{AbstractMatrix{<:Real}} = nothing
end

The inputs to arranging the entries of one axis of a heatmap, other than the order of its entities: a clustering tree, the groups of the entries, and the matrix to cluster them by.

By default, if reordering the entries, this is based on the entries.matrix of the graph. You can override this by specifying an arrange_by matrix. Only the reordered dimension needs to match the entries.matrix (the rows arrange_by must have the same number of rows, and the columns arrange_by the same number of columns); the other dimension holds whatever features you want to cluster by, and need not match. For efficiency the rows arrange_by matrix should be in row-major layout, but that's not critical.

Alternatively you can give the tree of the entries as an hclust , and/or the order of the entities; see HeatmapSideConfiguration for how they take part in the layout.

If groups values (numbers or strings, one per entry) are specified, then a gap can be added between entries of different groups. Groups can also be used to constrain the computed clustering. The subgroups are a second, finer level of grouping nested in the groups. Neither has a title.

struct SidePlacement
    order::AbstractVector{<:Integer}
    hclust::Maybe{Hclust}
end

Where the entries of one side of a heatmap were put: their final order , and the tree they were put by, if one was needed.

• order is the order of the entries of the data, that is, the index of the original entry shown at each position. This is always a permutation of 1:n_entries , which for a side that isn't reordered at all is the identity.
• hclust is the tree of the entries, or nothing if no tree was needed (see TreeSource ).

These describe the order of the data, not the order it is displayed in; applying the origin is up to whoever shows the graph, as is skipping the hidden entries (the order and the tree include them).

@kwdef mutable struct MatrixValuesData
    matrix::Maybe{AbstractMatrix{<:Real}} = nothing
    title::Maybe{AbstractString} = nothing
end

A value per row per column of a graph (the entries of a heatmap), and the title of these values (which becomes the colors title).

@kwdef mutable struct MatrixEntitiesData
    hovers::Maybe{AbstractMatrix{<:AbstractString}} = nothing
end

The hovers of the entities of a graph which are arranged in rows and columns (the cells of a heatmap). Hovers are only shown in interactive graphs (or when saving an HTML file).

There's no mask here, unlike VectorEntitiesData . A cell always occupies the slot of its row and its column, so there's nothing to hide; to drop a cell, hide its whole row or column.