GitHub

Sources

SomeGraphs.Sources — Module

Provide convenient API for setting up graph's data. The core concept is that we can break the graph definition to parts w/ uniform structure, so that writing a data source to fill this structure allows using it to fill whatever data we want

  • X coordinates, Y coordinates, colors, bar sizes, etc.

We have a few kinds of these uniform structures. Each is built from two parts - one for all the data fields and one for all the configuration fields. All these fields are direct references to the graph fields, so they can be set via this view into the graph.

Some fields are shared between several views. For example, hovers for points in scatter graphs can be given by the X data, the Y data, or the color data. To support this we provide functions for adding hovers into the common (shared) field instead of simply overwriting it.

Some views are of one entry of a vector of structures (a series of bars, a line, a distribution, an annotation). Such an entry is appended by add_series! and its siblings, which return the index the view accessors take.

A data source view bundles the parts of a graph that one source of data fills: the values of one role, the entities they belong to, and the configuration they are shown by. A function written against a view works on any graph and any role that offers the same kind of view.

SomeGraphs.Sources.VectorFields — Type 
struct VectorFields{Configuration}
    data::VectorDataFields
    configuration::Configuration
end

AxisVectorFields = VectorFields{AxisConfigurationFields}
ColorsVectorFields = VectorFields{ColorsConfigurationFields}
SizesVectorFields = VectorFields{SizesConfigurationFields}

A data source view of one role of a graph whose entities are a vector: the data (a VectorDataFields ) and the configuration (whose axis is an AxisConfiguration , whatever else it holds). A function writing into such a view fills the role from some source of data, and works the same on the X coordinates of points, the values of bars, the colors of either, and so on. The views are AxisVectorFields for values shown along an axis, ColorsVectorFields for values shown as colors (see ColorsConfigurationFields ) and SizesVectorFields for values shown as sizes (see SizesConfigurationFields ). They are obtained from a graph by the accessor functions ( x_axis_vector_fields , colors_vector_fields , ...), whose names follow the path of the values in the data of the graph.

SomeGraphs.Sources.VectorDataFields — Type 
struct VectorDataFields
    values::VectorValuesData
    entities::VectorEntitiesData
end

The data half of a data source view (see VectorFields ): the VectorValuesData of one role of a graph (the X coordinates of its points, their colors, ...) and the VectorEntitiesData of the entities these values belong to. Both are the graph's own objects, so writing into them changes the graph. Several roles of the same entities (say, the X, Y, colors and sizes of points) share one entities , so hovers added through any of them are seen by all.

A source which only writes values, a title and hovers takes a VectorDataFields . The data half of every VectorFields is one, and so is a view of a role that has no configuration to speak of (the names of the bars, the groups of the rows of a heatmap), so such a source applies to all of them alike.

SomeGraphs.Sources.MatrixFields — Type 
struct MatrixFields
    data::MatrixDataFields
    configuration::MatrixConfigurationFields
end

The data source view of the entries of a graph whose entities are arranged in rows and columns (the entries of a heatmap), shown as colors.

SomeGraphs.Sources.MatrixDataFields — Type 
struct MatrixDataFields
    values::MatrixValuesData
    entities::MatrixEntitiesData
    rows_entities::VectorEntitiesData
    columns_entities::VectorEntitiesData
end

The data half of a MatrixFields data source view: the MatrixValuesData of the entries of a graph (a heatmap), the MatrixEntitiesData of its cells, and the VectorEntitiesData of each of its two axes. All are the graph's own objects, so writing into them changes the graph.

A matrix source knows the two axes its data is indexed by, so it can add hovers to all three: one per cell, one per row and one per column. The axis entities are the same ones the row and column views hand out ( rows_names_vector_data_fields , rows_annotations_colors_vector_fields , ...), so hovers added through either path are seen by both.

SomeGraphs.Sources.PartFields — Type 
struct PartFields{GraphType, PartType <: AbstractPartData}
    graph::GraphType
    data::PartType
    index::Int
end

The data source view of one part of a graph built from several (a series of bars, a line, a distribution). Everything is reached through a property of the view, and writing one writes the part itself, so part.name = "Foo" names the part in the graph.

The point of the view is that a source need not know which kind of part it fills. The scalars every part has ( name , hover , is_shown , color ) are always spelled the same, and the entities of the part are always entities , whatever the part calls them. A property no part of this kind has is an error, so width reaches a line but not a distribution.

The values of a part are shown in roles: values for a series of bars or a distribution, x and y for a line. Each role is a VectorFields , which is what a source filling a role expects. Writing a role is an error.

The view therefore offers three ways in, each for a different job:

  • data is the part itself, for writing its values directly ( part.data.values.vector = ... ) and for asking which part this is ( part.data === graph.data.distributions[2] ).
  • entities is the part's VectorEntitiesData , for adding hovers, under one name whatever the part calls it.
  • A role is the part's values and entities paired with the configuration of the axis they are shown along, for handing the whole role to a source which fills both.

These overlap, and deliberately so. A role has to carry the values and the entities, because that is what a VectorFields is, so part.values.data.values and part.data.values are the same object by two paths, as are part.values.data.entities and part.entities . Reach for the short paths when writing values or hovers yourself, and for the role when passing it on; going through a role to reach a value works but is the long way round.

This is also the only reason the view holds the graph . A role needs the axis configuration, which lives on the graph and is shared by every part, unlike the part's own fields. Whatever else you reach through graph is shared the same way.

The index is the position of the part in the graph, for filling the graph's order .

SomeGraphs.Sources.add_hovers! — Function 
add_hovers!(
    entities::Union{VectorEntitiesData, MatrixEntitiesData},
    hovers::AbstractArray{<:AbstractString};
    [title::Maybe{AbstractString} = nothing]
)::Nothing

Add a line to the hover of each of the entities : the hovers entry of the entity (a vector for VectorEntitiesData , a matrix for MatrixEntitiesData ), prefixed by the title (if any) as title: hover . The lines of several calls are joined by <br> , in the order of the calls. All the hovers given to the same entities must be of the same size.

The views are obtained from a graph by accessor functions, named by the path of the values in the data of the graph:

SomeGraphs.Sources.x_axis_vector_fields — Function 
x_axis_vector_fields(graph)::AxisVectorFields
x_axis_vector_fields(graph, index::Integer)::AxisVectorFields

The data source view of the X coordinates of a graph (of its points; of the points of one of its lines, given the index of the line).

SomeGraphs.Sources.y_axis_vector_fields — Function 
y_axis_vector_fields(graph)::AxisVectorFields
y_axis_vector_fields(graph, index::Integer)::AxisVectorFields

The data source view of the Y coordinates of a graph (of its points; of the points of one of its lines, given the index of the line).

SomeGraphs.Sources.annotations_colors_vector_fields — Function 
annotations_colors_vector_fields(graph, index::Integer)::ColorsVectorFields

The data source view of one annotation of a graph, given the index of the annotation. The annotation shares the entities of the axis it annotates (the bars).

SomeGraphs.Sources.rows_annotations_colors_vector_fields — Function 
rows_annotations_colors_vector_fields(graph, index::Integer)::ColorsVectorFields

The data source view of one annotation of the rows of a graph, given the index of the annotation. The annotation shares the entities of the rows.

SomeGraphs.Sources.columns_annotations_colors_vector_fields — Function 
columns_annotations_colors_vector_fields(graph, index::Integer)::ColorsVectorFields

The data source view of one annotation of the columns of a graph, given the index of the annotation. The annotation shares the entities of the columns.

SomeGraphs.Sources.names_vector_data_fields — Function 
names_vector_data_fields(graph)::VectorDataFields

The data source view of the names of the entities of a graph (of its bars); their title is the title of the axis of the entities.

A view of one entry of a vector of structures (a series, a line, a distribution, an annotation) needs the entry to exist. These append one and return the index the accessors take:

SomeGraphs.Sources.add_series! — Function 
add_series!(graph, [series::SeriesData = SeriesData()])::Int

Append a series to a graph (of series of bars) and return its index (for series_axis_vector_fields ). Whatever the series leaves at its defaults can be set later, through the view or directly.

SomeGraphs.Sources.add_line! — Function 
add_line!(graph, [line::LineData = LineData()])::Int

Append a line to a graph (of lines) and return its index (for x_axis_vector_fields and y_axis_vector_fields ). Whatever the line leaves at its defaults can be set later, through the views or directly.

SomeGraphs.Sources.add_distribution! — Function 
add_distribution!(graph, [distribution::DistributionData = DistributionData()])::Int

Append a distribution to a graph (of distributions) and return its index (for distributions_axis_vector_fields ). Whatever the distribution leaves at its defaults can be set later, through the view or directly.

SomeGraphs.Sources.add_annotation! — Function 
add_annotation!(graph, [annotation::AnnotationData = AnnotationData()])::Int

Append an annotation to the entities of a graph (the bars) and return its index (for annotations_colors_vector_fields ). Whatever the annotation leaves at its defaults can be set later, through the view.

SomeGraphs.Sources.add_rows_annotation! — Function 
add_rows_annotation!(graph, [annotation::AnnotationData = AnnotationData()])::Int

Append an annotation to the rows of a graph and return its index (for rows_annotations_colors_vector_fields ). Whatever the annotation leaves at its defaults can be set later, through the view.

SomeGraphs.Sources.add_columns_annotation! — Function 
add_columns_annotation!(graph, [annotation::AnnotationData = AnnotationData()])::Int

Append an annotation to the columns of a graph and return its index (for columns_annotations_colors_vector_fields ). Whatever the annotation leaves at its defaults can be set later, through the view.

Example:

One source function, filling a role from a vector of values with a title and a hover line, applied to the X and Y coordinates and to the colors of the points of a graph: 

using SomeGraphs
function source!(fields::VectorFields, values::AbstractVector{<:Real}, title::AbstractString)::Nothing
    fields.data.values.vector = values
    fields.data.values.title = title
    add_hovers!(fields.data.entities, string.(values); title)
    return nothing
end
graph = points_graph()
source!(x_axis_vector_fields(graph), collect(0:10) .* 10, "X")
source!(y_axis_vector_fields(graph), collect(0:10) .^ 2, "Y")
source!(points_colors_vector_fields(graph), collect(0:10), "Color")
using PlotlyDocumenter
to_documenter(graph.figure)

Index