data-viz-lab / elm-chart-builder / Chart.Line

This is the line chart module from elm-chart-builder.

It expects the X axis to plot time or continuous data and the Y axis to plot continuous data.

Chart Data Format


type alias Accessor data =
Chart.Internal.Type.AccessorContinuousOrTime data

The data accessors

A line chart can have the X axis as continuous or time data.

type Accessor data
    = AccessorContinuous (accessorContinuous data)
    | AccessorTime (accessorTime data)


type alias AccessorCont data =
{ xGroup : data -> Maybe String
, xValue : data -> Basics.Float
, yValue : data -> Basics.Float 
}

An alias for AccessorContinuous


type alias AccessorContinuous data =
{ xGroup : data -> Maybe String
, xValue : data -> Basics.Float
, yValue : data -> Basics.Float 
}

The accessor structure for x continuous lines.


type alias AccessorTime data =
{ xGroup : data -> Maybe String
, xValue : data -> Time.Posix
, yValue : data -> Basics.Float 
}

The accessor structure for x time lines.

continuous : Chart.Internal.Type.AccessorContinuousStruct data -> Accessor data

The accessor constructor for x continuous lines.

Line.continuous (Line.AccessorContinuous .groupLabel .x .y)

cont : Chart.Internal.Type.AccessorContinuousStruct data -> Accessor data

An alias for Line.continuous

Line.cont (Line.AccessorCont .groupLabel .x .y)

time : Chart.Internal.Type.AccessorTimeStruct data -> Accessor data

The accessor constructor for x time lines.

Line.time (Line.AccessorTime .groupLabel .x .y)

Chart Initialization

init : RequiredConfig -> Config msg validation

Initializes the line chart with a default config

data : List Data
data =
    [ { groupLabel = "A"
      , x = Time.millisToPosix 1579275175634
      , y = 10
      }
    , { groupLabel = "A"
      , x = Time.millisToPosix 1579285175634
      , y = 16
      }
    , { groupLabel = "B"
      , x = Time.millisToPosix 1579275175634
      , y = 13
      }
    , { groupLabel = "B"
      , x = Time.millisToPosix 1579285175634
      , y = 23
      }
    ]

accessor : Line.Accessor data
accessor =
    Line.time (Line.accessorTime .groupLabel .x .y)

Line.init
    { margin =
        { top = 10
        , right = 10
        , bottom = 30
        , left = 30
        }
    , width = 500
    , height = 200
    }
    |> Line.render (data, accessor)

Chart Rendering

render : ( List data, Accessor data ) -> Config msg validation -> Html msg

Renders the line chart, after initialisation and optional customisations.

Line.init requiredConfig
    |> Line.render ( data, accessor )

Configuration


type alias Config msg validation =
Chart.Internal.Type.Config msg validation

The Config opaque type


type alias RequiredConfig =
Chart.Internal.Type.RequiredConfig

The required config, passed as an argument to the init function

{ margin =
    { top = Float
    , right = Float
    , bottom = Float
    , left = Float
    }
, width = Float
, height = Float
}

Optional Configuration setters

asArea : Config msg validation -> Config msg validation

Draw the line chart as an area

Line.init requiredConfig
    |> Line.asArea
    |> Line.render ( data, accessor )

withBottomPadding : Basics.Float -> Config msg validation -> Config msg validation

Sets the bottom padding for the chart component. The higher the padding, the bigger the gap between the chart and the axis.

Line.init requiredConfig
    |> Line.withBottomPadding 4
    |> Line.render ( data, accessor )

withColorPalette : List Color -> Config msg validation -> Config msg validation

Sets the color palette for the chart.

palette =
    -- From elm-visualization
    Scale.Color.tableau10

Line.init requiredConfig
    |> Line.withColorPalette palette
    |> Line.render (data, accessor)

withCurve : (List ( Basics.Float, Basics.Float ) -> SubPath) -> Config msg validation -> Config msg validation

Sets the line curve shape

Defaults to Shape.continuousCurve

See elm-visualization/latest/Shape Curves section for more info.

Line.init requiredConfig
    |> Line.withCurve Shape.monotoneInXCurve
    |> Line.render ( data, accessor )

withDesc : String -> Config msg validation -> Config msg validation

Sets an accessible, long-text description for the svg chart.

It defaults to an empty string. This shuld be set if no title nor description exists for the chart, for example in a sparkline.

Line.init requiredConfig
    |> Line.withDesc "This is an accessible chart"
    |> Line.render ( data, accessor )

withEvent : Chart.Internal.Event.Event msg -> Config msg validation -> Config msg validation

Add an event with a msg to handle the returned Hint data. One of:

Line.init requiredConfig
    |> Line.withEvent (Line.hoverOne OnHover)
    |> Line.render ( data, accessor )

withGroupedLayout : Config msg validation -> Config msg validation

Creates a grouped line chart. This option is already set by default.

Line.init requiredConfig
    |> Line.withGroupedLayout
    |> Line.render ( data, accessor )

withLabels : Chart.Internal.Type.Label -> Config msg validation -> Config msg validation

Show a label at the end of the lines.

Currently only takes an xGroupLabel

⚠ Use with caution, there is no knowledge of text wrapping!

defaultLayoutConfig
    |> Line.withLabels Line.xGroupLabel

withLeftPadding : Basics.Float -> Config msg validation -> Config msg validation

Sets the left padding for the chart component. The higher the padding, the bigger the gap between the chart and the axis.

Line.init requiredConfig
    |> Line.withLeftPadding 4
    |> Line.render ( data, accessor )

withLineStyle : List ( String, String ) -> Config msg validation -> Config msg validation

Sets the style for the lines The styles set here have precedence over withColorPalette and css rules.

Line.init requiredConfig
    |> Line.withLineStyle [ ( "stroke-width", "2" ) ]
    |> Line.render ( data, accessor )

withLogYScale : Basics.Float -> Config msg validation -> Config msg validation

Set the Y scale to logaritmic, passing a base

Line.init requiredConfig
    |> Line.withLogYScale 10
    |> Line.render ( data, accessor )

withPointAnnotation : Maybe Chart.Annotation.Hint -> Config msg validation -> Config msg validation

A predefined point annotation, in the format of Chart.Annotation.Point Typically used to draw points on hover.

Line.init requiredConfig
    |> Line.withEvent (Line.hoverOne OnHover)
    |> Line.withPointAnnotation annotations
    |> Line.render ( data, accessor )

withStackedLayout : Chart.Internal.Type.StackOffset -> Config msg validation -> Config msg validation

Creates a stacked line chart.

It takes an option to draw stacked lines or stacked areas

Line.init requiredConfig
    |> Line.withStackedLayout Shape.stackOffsetSilhouette
    |> Line.render ( data, accessor )

withSymbols : List Chart.Internal.Symbol.Symbol -> Config msg validation -> Config msg validation

Pass a list of symbols to the line chart, one per data group. If the list is empty, no symbols are rendered. It defaults to empty List.

defaultLayoutConfig
    |> withSymbols [ Circle, Corner, Triangle ]

withTableFloatFormat : (Basics.Float -> String) -> Config msg validation -> Config msg validation

An optional formatter for all float values in the alternative table content for accessibility.

Defaults to String.fromFloat

Line.init requiredConfig
    |> Line.withTableFloatFormat String.fromFloat
    |> Line.render ( data, accessor )

withTablePosixFormat : (Time.Posix -> String) -> Config msg validation -> Config msg validation

An optional formatter for all posix values in the alternative table content for accessibility.

Defaults to Time.posixToMillis >> String.fromInt

Line.init requiredConfig
    |> Line.withTablePosixFormat (Time.posixToMillis >> String.fromInt)
    |> Line.render ( data, accessor )

withTitle : String -> Config msg validation -> Config msg validation

Sets an accessible title for the svg chart.

It defaults to an empty string. This shuld be set if no title nor description exists for the chart, for example in a sparkline.

Line.init required
    |> Line.withTitle "Line chart"
    |> Line.render ( data, accessor )

withVLineAnnotation : Maybe Chart.Annotation.Hint -> Config msg validation -> Config msg validation

A predefined x-bar annotation, in the format of Chart.Annotation.Point Typically used to draw a vertical bar on hover.

Line.init requiredConfig
    |> Line.withEvent (Line.hoverOne OnHover)
    |> Line.VerticalLine annotations
    |> Line.render ( data, accessor )

withXContDomain : ( Basics.Float, Basics.Float ) -> Config msg validation -> Config msg validation

An alias for withXContinuousDomain

If not set, the domain is calculated from the data. If set on a continuous line chart this setting will have no effect.

Line.init requiredConfig
    |> Line.withXContDomain ( 0, 10 )
    |> Line.render ( data, accessor )

withXContinuousDomain : ( Basics.Float, Basics.Float ) -> Config msg validation -> Config msg validation

Sets the Y domain of a continuous line chart

If not set, the domain is calculated from the data. If set on a continuous line chart this setting will have no effect.

Line.init requiredConfig
    |> Line.withXContinuousDomain ( 0, 10 )
    |> Line.render ( data, accessor )

withXTimeDomain : ( Time.Posix, Time.Posix ) -> Config msg validation -> Config msg validation

Sets the Y domain of a time line chart

If not set, the domain is calculated from the data. If set on a continuous line chart this setting will have no effect.

Line.init requiredConfig
    |> Line.withXTimeDomain ( Time.millisToPosix 1579275175634, 10 )
    |> Line.render ( data, accessor )

withYDomain : ( Basics.Float, Basics.Float ) -> Config msg validation -> Config msg validation

Sets the Y domain of a line chart

This is always a continuous domain, not a time domain. If not set, the domain is calculated from the data. If set on a continuous line chart this setting will have no effect.

Line.init required
    |> Line.withYDomain ( Time.millisToPosix 1579275175634, Time.millisToPosix 1579375175634 )
    |> Line.render ( data, accessor )

withoutTable : Config msg validation -> Config msg validation

Do not build an alternative table content for accessibility

⚠ By default an alternative table is always being rendered. Use this option to not build the table.

Line.init requiredConfig
    |> Line.withoutTable
    |> Line.render ( data, accessor )

Configuration arguments

axisBottom : List (Axis.Attribute value) -> Chart.Internal.Axis.XAxis value

It returns an XAxis bottom type

Line.axisBottom [ Axis.tickCount 5 ]

axisGrid : List (Axis.Attribute value) -> Chart.Internal.Axis.YAxis value

It returns an YAxis Grid type

Line.axisGrid [ Axis.tickCount 5 ]

axisLeft : List (Axis.Attribute value) -> Chart.Internal.Axis.YAxis value

It returns an YAxis Left type

Line.axisLeft [ Axis.tickCount 5 ]

axisRight : List (Axis.Attribute value) -> Chart.Internal.Axis.YAxis value

It returns an YAxis right type

Line.axisRight [ Axis.tickCount 5 ]

xGroupLabel : Chart.Internal.Type.Label

The xGroup label type.

Axis


type alias XAxis value =
Chart.Internal.Axis.XAxis value

The XAxis type


type alias YAxis value =
Chart.Internal.Axis.YAxis value

The YAxis type

hideAxis : Config msg validation -> Config msg validation

Hide all axis. Useful, for example, when drawing a sparkline.

Line.init requiredConfig
    |> Line.hideAxis
    |> Line.render ( data, accessor )

hideXAxis : Config msg validation -> Config msg validation

Hide the X axis

The X axis depends from the layout:

Line.init requiredConfig
    |> Line.hideXAxis
    |> Line.render ( data, accessor )

hideYAxis : Config msg validation -> Config msg validation

Hide the Y aixs

The Y axis depends from the layout:

Line.init requiredConfig
    |> Line.hideYAxis
    |> Line.render ( data, accessor )

withXAxisCont : Chart.Internal.Axis.XAxis Basics.Float -> Config msg validation -> Config msg validation

An alias for withXAxisContinuous

Line.init requiredConfig
    |> Line.withXAxisCont (Line.axisBottom [ Axis.tickCount 5 ])
    |> Line.render ( data, accessor )

withXAxisContinuous : Chart.Internal.Axis.XAxis Basics.Float -> Config msg validation -> Config msg validation

Customise the continuous xAxis

Line.init requiredConfig
    |> Line.withXAxisContinuous (Line.axisBottom [ Axis.tickCount 5 ])
    |> Line.render ( data, accessor )

withXAxisTime : Chart.Internal.Axis.XAxis Time.Posix -> Config msg validation -> Config msg validation

Customise the time xAxis

Line.init requiredConfig
    |> Line.withXAxisTime (Line.axisBottom [ Axis.tickCount 5 ])
    |> Line.render ( data, accessor )

withYAxis : Chart.Internal.Axis.YAxis Basics.Float -> Config msg validation -> Config msg validation

Customise the yAxis

Line.init requiredConfig
    |> Line.withYAxis (Line.axisRight [ Axis.tickCount 5 ])
    |> Line.render ( data, accessor )

Events


type alias Hint =
Chart.Internal.Event.Hint

The data format returned by an event. Internaly defined as:

type alias Hint =
    { groupLabel : Maybe String
    , xChart : Float
    , yChart : List Float
    , xData : Float
    , yData : List Float
    }

hoverAll : (Maybe Chart.Internal.Event.Hint -> msg) -> Chart.Internal.Event.Event msg

An event listener for all elements along the same x-value.

Line.init requiredConfig
    |> Line.withEvent (Line.hoverAll OnHover)
    |> Line.render ( data, accessor )

hoverOne : (Maybe Chart.Internal.Event.Hint -> msg) -> Chart.Internal.Event.Event msg

An event listener for a single element at a time.

Line.init requiredConfig
    |> Line.withEvent (Line.hoverOne OnHover)
    |> Line.render ( data, accessor )