Sparkline view functions. There are two basic chart types:
These are conceptually very similar, except columns charts aggregate observations under a specified time interval, whereas line charts do not do any aggregation, but plot the observations according to a continuous time scale, and draw a line between them.
The data to be charted must be a List (Time.Posix, Float)
, alias
Timeseries.Series
. For line charts, in most cases the X values should be
unique, i.e. there should one Y for every X, but this is not enforced. For
columns charts, this constraint is enforced by aggregating Y values over
each given time interval, using a provided aggregation function (by default,
List.sum
). (If you want the same behavior for line charts, i.e. aggregating
over time intervals, use the functions in the Timeseries
module on your data first.)
There are also functions for scaling multiple data series together, i.e. for creating 'facet' charts from small multiples:
Please note that these functions do not themselves group your data into small multiples, nor do they position or label the series each chart represents. That is all up to you. The purpose of these chart functions is to render the charts scaling the X and Y dimensions of the series according to the parameters you specify.
Finally, a function to create a single line chart with multiple series (with both X and Y dimensions scaled together) is provided:
For any chart type you can define which observations are highlighted. Often this is the last observation, or the min and/or the max, but there are some more options as well (see Highlight). Highlighted observations are rendered as circles (points) with a configurable color.
For any chart type except multiple-lines charts, you can provide and configure a an elm-visualization Brush to allow interactive selection of observations. This can also be configured to display X and Y values at the start and end of the selection -- interactive axis labels.
In addition, functions are available that return charts together with the data that is currently highlighted and selected (brushed), to make it easy to build a separate view based on the current highlights/selections.
See the examples directory for all features in action.
line : Config msg -> Maybe (Brush Brush.OneDimensional) -> Timeseries.Series -> TypedSvg.Core.Svg msg
Produce a line chart, passing in an optional brush for interactive selection. (See Example/Brush for a full example of how to set up brushes).
Example:
chart : Svg msg
chart =
line config (Just brush) series
lines : List ( TypedSvg.Types.Paint, TypedSvg.Types.Paint ) -> Config msg -> List Timeseries.Series -> TypedSvg.Core.Svg msg
Produce a multi-line chart, with all given series scaled together on both
X and Y dimensions, using the given list of color pairs for the line and
highlight colors respectively of each series. (Note that colors are specified
as TypedSvg.Types.Paint
.)
Example:
chart : Svg msg
chart =
lines defaultColorPairs config [series1, series2, series3, ... ]
Note that neither brushing nor returning highlighted data is implemented currently for multi-line charts.
columns : Config msg -> Maybe (Brush Brush.OneDimensional) -> Timeseries.Series -> TypedSvg.Core.Svg msg
Produce a columns chart, passing in an optional brush for interactive selection. (See Example/Brush for a full example of how to set up brushes).
Example:
chart : Svg msg
chart =
columns config (Just brush) series
lineFacets : Facet.Scaling2d -> Config msg -> Maybe (Brush Brush.OneDimensional) -> List Timeseries.Series -> List (TypedSvg.Core.Svg msg)
Produce a list of line charts, scaling the given timeseries data together as specified by a Facet.Scaling2d, and passing in an optional brush for synchronized brushing across all charts. (See Example/Brush for an example of this).
Example (fixed X and free Y scales):
charts : List (Svg msg)
charts =
lineFacets
{ x = Facet.Fixed, y = Facet.Free }
config
(Just brush)
[ series1, series2, series3, ... ]
columnsFacets : Facet.Scaling2d -> Config msg -> Maybe (Brush Brush.OneDimensional) -> List Timeseries.Series -> List (TypedSvg.Core.Svg msg)
Produce a list of columns charts, scaling the given timeseries data together as specified by a Facet.Scaling2d, and passing in an optional brush for synchronized brushing across all charts. (See Example/Brush for an example of this).
Example (fixed X and free Y scales):
charts : List (Svg msg)
charts =
columnsFacets
{ x = Facet.Fixed, y = Facet.Free }
config
(Just brush)
[ series1, series2, series3, ... ]
{ chart : TypedSvg.Core.Svg msg
, selected : Timeseries.Series
, highlighted : Timeseries.Series
}
Data type for chart and selected and highlighted data returned by lineData, lineFacetsData, columnsData, and columnsFacetsData.
lineData : Config msg -> Maybe (Brush Brush.OneDimensional) -> Timeseries.Series -> ChartData msg
Same as line, but returning ChartData with highlighted and selected (brushed) data, in addition to the chart.
lineFacetsData : Facet.Scaling2d -> Config msg -> Maybe (Brush Brush.OneDimensional) -> List Timeseries.Series -> List (ChartData msg)
Same as lineFacets, but returning ChartData with highlighted and selected (brushed) data, in addition to the chart.
columnsData : Config msg -> Maybe (Brush Brush.OneDimensional) -> Timeseries.Series -> ChartData msg
Same as columns, but returning ChartData with highlighted and selected (brushed) data, in addition to the chart.
columnsFacetsData : Facet.Scaling2d -> Config msg -> Maybe (Brush Brush.OneDimensional) -> List Timeseries.Series -> List (ChartData msg)
Same as columnsFacets, but returning ChartData with highlighted and selected (brushed) data, in addition to the chart.
Options for chart highlighting.
NoHighlight
: Don't highlight anythingHighlightLast
: Highlight the last observationHighlightNegative
: Highlight all values less than 0HighlightMin
: Highlight the minimum value in the seriesHighlightMax
: Highlight the maximum value in the seriesHighlightMinMax
: Highlight the minimum and maximum values in the seriesHighlightPeaks
: Highlight positive peaks detected in the series, with
specified parameters.See elm-visualization's peaks function for details on that calculation and the parameters needed.
Example:
config : Config msg
config =
lineConfig Time.utc 100 50
|> withHighlight HighlightMax
lineConfig : Time.Zone -> Basics.Float -> Basics.Float -> Config msg
Basic line chart configuration, given a Time.Zone, width, and height of chart.
columnsConfig : (List Basics.Float -> Basics.Float) -> Time.Extra.Interval -> Time.Zone -> Basics.Float -> Basics.Float -> Config msg
Basic columns chart configuration, given an aggregation function, a Time.Interval, a Time.Zone, the width, and the height of chart.
Example for a columns chart aggregating by the mean of observations over month intervals:
config : Config msg
config =
columnsConfig
(\ys -> List.sum ys / (List.length ys |> toFloat))
Time.Month
Time.utc
100
50
withPadding : Basics.Float -> Config msg -> Config msg
Set padding (in pixels) around chart
withCssBlock : String -> Config msg -> Config msg
Set CSS block name (default is "sparklines")
withHighlight : Highlight -> Config msg -> Config msg
Set highlight to include in chart
withBandConfig : Scale.BandConfig -> Config msg -> Config msg
Configure the band-scale used for columns charts. Refer to elm-visualization Scale.BandConfig for details.
defaultColorPairs : List ( TypedSvg.Types.Paint, TypedSvg.Types.Paint )
A default set of color-pairs for multi-lines charts. Uses
elm-visualization category10
color scale, with line color at 70% alpha of
the highlight color. Need a better default.
Chart configuration. See above for usage examples.
withBrush : (Brush.OnBrush -> msg) -> BrushingAppearanceConfig -> Config msg -> Config msg
Configure brushing in chart (with no labels)
Example:
type Msg
= UpdateBrush Brush.OnBrush
| ...
config : Config Msg
config =
lineConfig Time.utc 100 50
|> withBrush UpdateBrush defaultBrushingAppearance
withBrushLabels : (Brush.OnBrush -> msg) -> BrushingAppearanceConfig -> Config msg -> Config msg
Configure brushing in chart with both X and Y labels
Example:
type Msg
= UpdateBrush Brush.OnBrush
| ...
config : Config Msg
config =
lineConfig Time.utc 100 50
|> withBrushLabels UpdateBrush defaultBrushingAppearance
withBrushLabelsX : (Brush.OnBrush -> msg) -> BrushingAppearanceConfig -> Config msg -> Config msg
Configure brushing in chart with only X labels
withBrushLabelsY : (Brush.OnBrush -> msg) -> BrushingAppearanceConfig -> Config msg -> Config msg
Configure brushing in chart with only Y labels
{ area : TypedSvg.Types.Paint
, bounds : TypedSvg.Types.Paint
, boundsDashed : Basics.Bool
, highlight : TypedSvg.Types.Paint
}
Configuration for the appearance of the brush overlay. Note that
colors are specified using TypedSvg.Type.Paint
.
area
: the fill color of the brushed area (or bars) of the chartbounds
: the stroke color of the bounds lines of the brushboundsDashed
: True if you want dashed bounds lineshighlight
: the color of bounds lines and labels when the observations are
highlighted{ color : TypedSvg.Types.Paint
, size : TypedSvg.Types.Length
, labelX : Time.Zone -> Time.Posix -> String
, labelY : Basics.Float -> String
}
Configuration for the appearance of the brush overlay labels. Note that
color is specified using TypedSvg.Type.Paint
, and size is specified using
TypedSvg.Type.Length
.
color
: the text color of labelssize
: the size of label textlabelX
: how to display X (time) valueslabelY
: how to display Y (float) valuesNote labelX
uses the time zone specified in top-level Config.
defaultBrushingAppearance : BrushingAppearanceConfig
Default brushing appearance options. Yellow selection area, 70% black solid (non-dashed) bounds lines, red when highlighted.
formattingLabelsX : (Time.Zone -> Time.Posix -> String) -> Config msg -> Config msg
Format time interval labels (x axis) with custom function.
Note: The time zone in top-level Config is used to render labels.
Most date/time formatting libraries should compose with this. Internally, ryannhg/date-format is used for default formats based on the given interval.
Example:
yyyymmdd : Time.Zone -> Time.Posix -> String
yyyymmdd =
DateFormat.format
[ DateFormat.yearNumber
, DateFormat.monthFixed
, DateFormat.dayOfMonthFixed
]
config : Config Msg
config =
lineConfig Time.utc 100 50
|> withBrushLabels UpdateBrush defaultBrushingAppearance
|> formattingLabelsX yyyymmdd
formattingLabelsY : (Basics.Float -> String) -> Config msg -> Config msg
Format labels for the y axis with custom function
coloringLabels : TypedSvg.Types.Paint -> Config msg -> Config msg
Set label (background) color (in TypedSvg.Types.Paint
).
sizingLabels : TypedSvg.Types.Length -> Config msg -> Config msg
Set label size (in TypedSvg.Types.Length
).