An element that draws a bar chart, a line chart, a pie chart, a treemap, a sunburst, a sankey, an alluvial chart, a parallel sets chart, a chord chart, a scatter plot or a waterfall chart
The chart entity takes the kind as its first argument: :bar, :line,
:pie, :treemap, :sunburst, :sankey, :alluvial, :parallel_sets or
:chord. A slash in a category of a treemap or a
sunburst names a part of a group, and Expresso.Element.Chart.Hierarchy
draws them. The categories option gives the names of the categories, and each
series entity gives a name and one value for each category. The src
option gives a CSV file in place of the two: the first row holds the names
of the series, and each other row holds a category and its values.
The render function draws the chart as SVG in the document, so the chart
needs no script and no file, and it prints. The colors of the series are
--chart-1 to --chart-8 of the theme, in a fixed order. A chart with two
or more series has a legend, a bar shows its value, the end of a line shows
its name and its last value, and the legend of a pie shows each part in
percent. A table with the values goes into the document for a screen
reader.
A series is a child of the chart, so reveal true shows each series at its
own step, and dim true dims each series when a later series shows. The
highlight option shows each series at each step, and it puts one group of
series or of categories in focus at each step: the rest of the chart dims.
check/1 makes an Expresso.Element.Focus for each group, and rules/1
writes the rules that dim the series and the marks.
A frame entity holds the series at one point in time, and each frame
after the first takes one step. A chart with frames, or with the effect
:grow, moves its marks: Expresso.Element.Chart.Motion draws them.
docs/reference/chart-element.md gives the rules.
A category of a sankey is a path of nodes. The flow entities give the
same data in a shorter form. Expresso.Element.Chart.Sankey draws a
sankey. With reveal true, the check makes one series for each step: a
source column of the links in a sankey or an alluvial chart, a node of the
first column in a parallel sets chart, and a source in a chord chart. An
alluvial chart is a sankey with one node for each name in each column. The
place of a name in its path sets its column. A parallel sets chart has the
nodes of an alluvial chart. Expresso.Element.Chart.ParallelSets draws
each of its categories as one ribbon through the columns. A chord chart
takes the flows of a sankey. Expresso.Element.Chart.Chord draws its
nodes as arcs of a ring.
A scatter plot holds point entities in place of categories and series.
Expresso.Element.Chart.Scatter checks it and draws it, and
docs/scatter-plots.md gives its design.
A waterfall chart has one series. Its first value is the start, each other
number is a change, and the atom :total marks a total column.
Expresso.Element.Chart.Waterfall checks it and draws it, and
docs/waterfall-charts.md gives its design.
Summary
Functions
Read the CSV file of a chart with src, and make its categories and series
Check the options of a chart
Make the assigns of the render function from the struct
Return the data-keys attribute of a mark of a category
Return the number of steps that a chart takes before the groups of its
highlight option
Tell whether the marks of a chart move
Make the HTML of a chart: a figure with the SVG and a table of the values
Return the CSS rules of the frames and of the highlight option of a chart
Return the style attribute of the width option of a chart, as a list of
attributes
Types
@type t() :: %Expresso.Element.Chart{ __spark_metadata__: term(), at: term(), categories: term(), category_label: term(), class: term(), color: term(), color_label: term(), color_mid: term(), color_scale: term(), count: term(), delimiter: term(), dim: term(), direction: term(), easing: term(), effect: term(), el: term(), elements: term(), flows: term(), focus: term(), frame_label: term(), frames: term(), highlight: term(), jitter: term(), kind: term(), label: term(), labels: term(), levels: term(), morph: term(), on: term(), opacity: term(), reveal: term(), separator: term(), shape: term(), signature: term(), size: term(), size_label: term(), sort: term(), spans: term(), speed: term(), src: term(), steps: term(), symbol: term(), symbol_label: term(), thumbnail: term(), timeline: term(), title: term(), totals: term(), trend: term(), value_label: term(), value_range: term(), values: term(), whole_first: term(), width: term(), x: term(), x_label: term(), x_range: term(), x_scale: term(), y: term(), y_label: term(), y_range: term(), y_scale: term() }
The struct of a chart
Functions
Read the CSV file of a chart with src, and make its categories and series
The first row holds a heading for the categories, then the name of each
series. Each other row holds a category, then one number for each series.
A comma divides the cells, or a tab in a file that ends in .tsv, or the
delimiter option. Expresso.Element.Chart.Csv tells the rules. The
function reads the file through Expresso.DeckFile, so the watch mode
renders the deck again after a change to the file.
Check the options of a chart
The transform of the chart entity calls this function. A chart with src
keeps its file until Expresso.PathTransformer runs, because the root
option of the deck can change the path, and build/1 then reads it.
Make the assigns of the render function from the struct
The key overlay holds the attributes of the overlay contract, and the
style attribute of the width option. The key series holds each series
with its color number and its overlay attributes. A series of a chart with
the highlight option also gets data-series with its color number, and
the rules of rules/1 select it by that number. The key keys is true
for a chart with a group of categories, and key/2 then gives each mark
of a category its data-keys attribute.
@spec key(map(), non_neg_integer() | nil) :: String.t() | nil
Return the data-keys attribute of a mark of a category
index is the index of the category, from 0. A mark that dims at each step
of a group of categories, such as a line, takes nil, and it gets an empty
attribute. A chart without a group of categories gives no attribute.
iex> Expresso.Element.Chart.key(%{keys: true}, 1)
"c2"
iex> Expresso.Element.Chart.key(%{keys: true}, nil)
""
iex> Expresso.Element.Chart.key(%{keys: false}, 1)
nil@spec lead(t()) :: 0 | 1
Return the number of steps that a chart takes before the groups of its
highlight option
The whole_first option gives the chart one step with no group in focus,
as a pause in front of the chart does. A waterfall chart with reveal
takes one step for its start and its totals before its first change.
Expresso.Overlay.Expand reads this number.
Tell whether the marks of a chart move
The marks move in a chart with two or more frames, and in a chart with the
effect :grow on the chart or on a series, or on a point of a scatter
plot. Expresso.Element.Chart.Motion
then draws them.
@spec render(map()) :: Phoenix.HTML.safe()
Make the HTML of a chart: a figure with the SVG and a table of the values
The SVG has role="img" and the title as its name. The table has the class
chart-table, and the style sheet hides it from the eye and not from a
screen reader.
Return the CSS rules of the frames and of the highlight option of a chart
Expresso.Overlay.Render.style/1 calls this function for each chart, after
Expresso.Overlay.Render.identify/1. A chart without frames and without
the highlight option has no rules.
A group of the highlight option gives one rule at its step. The rule sets
--chart-dim: 1 on each series that is not in the group, or on each mark
with a data-keys attribute that does not hold a key of the group. The
theme dims a series or a mark with that property.
Return the style attribute of the width option of a chart, as a list of
attributes
A chart without the option returns an empty list.