jweir / charter / Charter

This library is for generating inline graphs, called sparklines.

Definition

sparkline : Size -> List (Element a) -> Svg a

Draws a simple chart.

      -- data is tuples with (x,y) values as floats
      data = [(0,0),(5,10),(10,12)]
      data2 = [(0,-5),(7,2),(12,14)]

      sparkline
          (Size 100 10)    -- the width and height
          [ line [] data ] -- type of element to draw with SVG attributes and the data

Multiple elements can be included to have muliple graphs. Each will have its data scaled relatively to one another. The graphs are drawn in the order they are given. So last graph will be drawn on top.

      sparkline
          (100,10)
          [ line [] data
          , line [Svg.stroke "red" ] data2
          ]


type alias Size =
{ width : Basics.Float
, height : Basics.Float 
}

Defines the size of the chart


type Element a

layer : Box -> List (Element a) -> Layer a

Layers group the chart elements. They have a size and x, y offsets

Layers are drawn in the order of the list. If you want something drawn over another layer, place it after that layer.

chart : Size -> List (Layer a) -> Svg a

Use chart to draw graphics with layers. Layers can be positioned and overlayed, allowing for charts with margins and different regions.

chart (Size 620 120)
    [ Layer
        (Box 600 50 10 10)
        [ line [] data0
        , zeroLine []
        ]
    , Layer (Box 600 20 10 60)
        [ area [ Svg.stroke "none", Svg.fill "rgb(150,150,255)" ] data1 ]
    ]


type Layer a

Layer type


type alias Box =
{ width : Basics.Float
, height : Basics.Float
, x : Basics.Float
, y : Basics.Float 
}

Defines the size and position of chart elements

Data


type alias Point =
( Basics.Float, Basics.Float )

Tuple of (x,y) value


type alias DataSet =
List Point

The data to be rendered.


type alias LabelSet a =
List ( Point
, List (Svg.Attribute a)
, String 
}

The data and text to use for labeling

Drawing

line : List (Svg.Attribute a) -> DataSet -> Element a

Line creates a line chart

area : List (Svg.Attribute a) -> DataSet -> Element a

Area creates a graph meant to be filled

dot : List (Svg.Attribute a) -> DataSet -> Element a

Dot draws a dot at each point. Set the radius of the dot by styling it [Svg.r "3"]

bar : List (Svg.Attribute a) -> Basics.Float -> DataSet -> Element a

Bar draws a bar graph of a given width.

label : List (Svg.Attribute a) -> LabelSet a -> Element a

Label plots text on the graph

Options

zeroLine : List (Svg.Attribute a) -> Element a

ZeroLine will draw a line at the 0 y axis

highlight : List (Svg.Attribute a) -> Constraint -> Listener -> Element a

Highlight is used to draw a region that has been selected. See onSelect


type Constraint
    = FreeForm
    | OnlyX

When highlighting a selected region the application can have the selection contrainted to just the X axis or be free.

You would most likely use OnlyX when selecting a timeseries.

extents : List (Element a) -> Maybe ( ( Basics.Float, Basics.Float ), ( Basics.Float, Basics.Float ) )

extents will return a Maybe of two tuples from the passed Elements.

The first tuple is the low range of (x,y) The second tuple is the high range of (x,y)

Deprecated

Domain


type Domain
    = Domain (( Point, Point ))

Domain defines the min (x,u) and max (x,y) points in the data.

getDomain : Layer a -> Domain

Get the Domain from a Layer

include : List ( Maybe Basics.Float, Maybe Basics.Float ) -> Element a

domain will insert points into the Layer's Domain that are not meant to be rendered. This is useful when creating multiple Layers that need to have the same scale or ensure that a min/max value is in the scale.

For example:

    You are graphing the points [(10,5), (20,6)] but you want the graph to start at (0,0)

    call

    include  [(Just 0, Just 0)]

Events

type alias Model =
    { listener : Charter.Listener
    }

type Msg
    = Select Charter.Listener
    | Click Charter.Listener
    | Hover Charter.Listener

chart (Size 620 120)
    [ Layer
        (Box 600 70 10 10)
        [ highlight [ Svg.fill "rgba(255,255,0,0.4)" ]
            OnlyX
            model.listener
        ]
    , Layer
        (Box 600 50 10 10)
        [ Charter.onClick model.listener Click
        , Charter.onSelect model.listener Select
        , Charter.onHover model.listener Hover
        , Charter.line [ Svg.stroke "red" ] data0
        ]
    ]


type Listener

A listener to maintain the state of events (selection, hover and clicks). A listener can be shared across charts with the same scale.

listener : Listener

Create a new event listener.

subscribe : Listener -> (Listener -> a) -> Platform.Sub.Sub a

When tracking onSelect a subscription will be required. The mouse events are tracked outside of the chart's SVG element.

    type alias Model =
        { listener : Listener }

    type Msg
        = Select Listener

    subscriptions =
        Sub.batch [ subscribe model.listener Select ]

onSelect : Listener -> (Listener -> a) -> Element a

onSelect event for when a selection is made.

onClick : Listener -> (Listener -> a) -> Element a

onClick tracks click events.

onHover : Listener -> (Listener -> a) -> Element a

onHover tracks the mouse moving over the chart.

Event Data

Use the below functions to extract the data from events. The Point values returned are scaled to the input data, not the mouse events.

selection : Listener -> Maybe ( Point, Point )

Selection returns a box with the selected boundaries of the data.

Use this selection to filter the applications data into a subset.

filter : DataSet -> Listener -> DataSet
filter data listener =
    case selection listener of
        Nothing ->
            []

        Just ( ( x0, _ ), ( x1, _ ) ) ->
            data
                |> List.filter (\( x, _ ) -> x >= x0 && x <= x1)

clicked : Listener -> Maybe Point

Clicked returns a point from a click event.

hover : Listener -> Maybe Point

Hover returns a point from a hover event.

active : Listener -> Basics.Bool

Hover returns a point from a hover event.