Sparklines

Sparkline view functions. There are two basic chart types:

Line charts
Columns charts

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). 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:

Faceted line charts
Faceted columns charts

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:

Multiple-lines charts

Highlighting

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.

Brushing

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.

Access to highlighted and selected data

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.

Examples

See the examples directory for all features in action.

Reference

Single charts

line : Config msg -> Maybe (Brush OneDimensional) -> Series -> 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 ( Paint, Paint ) -> Config msg -> List Series -> 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 OneDimensional) -> Series -> 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 :

Scaling2d

-> Config msg

-> Maybe (Brush OneDimensional)

-> List Series

-> List (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 :

Scaling2d

-> Config msg

-> Maybe (Brush OneDimensional)

-> List Series

-> List (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, ... ]

Charts together with selected/highlighted data

type alias ChartData msg =

{ chart : Svg msg

, selected : Series

, highlighted : Series

}

Data type for chart and selected and highlighted data returned by lineData, lineFacetsData, columnsData, and columnsFacetsData.

lineData : Config msg -> Maybe (Brush OneDimensional) -> Series -> ChartData msg

Same as line, but returning ChartData with highlighted and selected (brushed) data, in addition to the chart.

lineFacetsData :

Scaling2d

-> Config msg

-> Maybe (Brush OneDimensional)

-> List 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 OneDimensional) -> Series -> ChartData msg

Same as columns, but returning ChartData with highlighted and selected (brushed) data, in addition to the chart.

columnsFacetsData :

Scaling2d

-> Config msg

-> Maybe (Brush OneDimensional)

-> List Series

-> List (ChartData msg)

Same as columnsFacets, but returning ChartData with highlighted and selected (brushed) data, in addition to the chart.

Highlighting

type Highlight

= NoHighlight

| HighlightLast

| HighlightNegative

| HighlightMin

| HighlightMax

| HighlightMinMax

| HighlightPeaks

{ lookaround : Int

, sensitivity : Float

, coallesce : Int

}

Options for chart highlighting.

NoHighlight: Don't highlight anything
HighlightLast: Highlight the last observation
HighlightNegative: Highlight all values less than 0
HighlightMin: Highlight the minimum value in the series
HighlightMax: Highlight the maximum value in the series
HighlightMinMax: Highlight the minimum and maximum values in the series
HighlightPeaks: 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.Day Time.utc 100 50
        |> withHighlight HighlightMax

Basic configuration

lineConfig : Zone -> Float -> Float -> Config msg

Basic line chart configuration, given a Time.Zone, width, and height of chart.

columnsConfig : (List Float -> Float) -> Interval -> Zone -> Float -> 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 : 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 : BandConfig -> Config msg -> Config msg

Configure the band-scale used for columns charts. Refer to elm-visualization Scale.BandConfig for details.

defaultColorPairs : List ( Paint, 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.

type Config msg

Chart configuration. See above for usage examples.

Brushing configuration

withBrush :

(OnBrush -> msg)

-> BrushingAppearanceConfig

-> 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 :

(OnBrush -> msg)

-> BrushingAppearanceConfig

-> 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 :

(OnBrush -> msg)

-> BrushingAppearanceConfig

-> Config msg

Configure brushing in chart with only X labels

withBrushLabelsY :

(OnBrush -> msg)

-> BrushingAppearanceConfig

-> Config msg

Configure brushing in chart with only Y labels

type alias BrushingAppearanceConfig =

{ area : Paint

, bounds : Paint

, boundsDashed : Bool

, highlight : 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 chart
bounds: the stroke color of the bounds lines of the brush
boundsDashed: True if you want dashed bounds lines
highlight: the color of bounds lines and labels when the observations are highlighted

type alias BrushingLabelsConfig =

{ color : Paint

, size : Length

, labelX : Zone -> Posix -> String

, labelY : 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 labels
size: the size of label text
labelX: how to display X (time) values
labelY: how to display Y (float) values

Note 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 : (Zone -> 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 : (Float -> String) -> Config msg -> Config msg

Format labels for the y axis with custom function

coloringLabels : Paint -> Config msg -> Config msg

Set label (background) color (in TypedSvg.Types.Paint).

sizingLabels : Length -> Config msg -> Config msg

Set label size (in TypedSvg.Types.Length).

ericgj/elm-sparklines/1.0.0

Sparklines

Highlighting

Brushing

Access to highlighted and selected data

Examples

Reference

Single charts

Facet charts

Charts together with selected/highlighted data

Highlighting

Basic configuration

Brushing configuration

Modules