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

barchart

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

The Bar module expects the X axis to plot ordinal data and the Y axis to plot continuous data. The data can be grouped by passing an xGroup accessor, or it can be flat by making the accessor always Nothing.

The X and Y axis are determined by the default vertical orientation. If the orientatin changes, X and Y also change.

Data Format


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

The data accessors

Initialization

init : RequiredConfig -> Config msg { canHaveSymbols : (), canHaveStackedLayout : () }

Initializes the bar chart with the required config.

data :
    List
        { groupLabel : String
        , x : String
        , y : Float
        }
data =
    [ { groupLabel = "A"
      , x = "a"
      , y = 10
      }
    , { groupLabel = "B"
      , x = "a"
      , y = 11
      }
    ]

accessor =
    Bar.Accessor (.groupLabel >> Just) .x .y

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

Rendering

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

Renders the bar chart, after initialisation and optional customisations.

Bar.init requiredConfig
    |> Bar.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

Optional Configuration Setters

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

Sets the style for the bars The styles set here have precedence over withColorPalette, withColorInterpolator and css.

Bar.init requiredConfig
    |> Bar.withBarStyle [ ( "fill", "none" ), ( "stroke-width", "2" ) ]
    |> Bar.render ( data, accessor )

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

Sets the style for the bars depending on the x value The styles set here have precedence over withBarStyle, withColorPalette, withColorInterpolator and css rules.

Bar.init requiredConfig
    |> Bar.withBarStyleFrom
        (\xValue ->
            if xValue == "X" then
                [ ( "fill", "none" ), ( "stroke-width", "2" ) ]

            else
                []
        )
    |> Bar.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.

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

withColorInterpolator : (Basics.Float -> Color) -> Config msg validation -> Config msg validation

Sets the color interpolator for the chart.

This option is not supported for stacked bar charts and will have no effect on them.

Bar.init requiredConfig
    |> Bar.withColorInterpolator Scale.Color.plasmaInterpolator
    |> Bar.render ( data, accessor )

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

Sets the color palette for the chart. If a palette with a single color is passed all bars will have the same colour. If the bars in a group are more then the colours in the palette, the colours will be repeted.

palette =
    Scale.Color.tableau10

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

withColumnTitle : Chart.Internal.Type.ColumnTitle -> Config msg validation -> Config msg validation

Set the chart columns title value

It takes one of: stackedColumnTitle, xOrdinalColumnTitle, yColumnTitle

defaultLayoutConfig
    |> Bar.withColumnTitle (Bar.yColumnTitle String.fromFloat)

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.

Bar.init requiredConfig
    |> Bar.withDesc "This is an accessible chart, with a desc element"
    |> Bar.render ( data, accessor )

withGroupedLayout : Config msg { validation | canHaveSymbols : () } -> Config msg { validation | canHaveSymbols : () }

Creates a grouped bar chart.

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

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

Show a label at the end of the bars.

It takes one of: yLabel, xLabel, xGroupLabel

If used together with symbols, the label will be drawn after the symbol.

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

defaultLayoutConfig
    |> Bar.withLabels (Bar.yLabel String.fromFloat)

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.

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

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

Set the Y scale to logaritmic, passing a base

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

withOrientation : Chart.Internal.Type.Orientation -> Config msg validation -> Config msg validation

Sets the orientation value.

Accepts: horizontal or vertical. Default value: vertical.

Bar.init requiredConfig
    |> Bar.withOrientation Bar.horizontal
    |> Bar.render ( data, accessor )

withStackedLayout : Chart.Internal.Type.Direction -> Config msg { validation | canHaveSymbols : (), canHaveStackedLayout : () } -> Config msg validation

Creates a stacked bar chart. Stacked Charts do not support symbols.

It takes a direction: diverging or noDirection.

Bar.init requiredConfig
    |> Bar.withStackedLayout Bar.diverging
    |> Bar.render ( data, accessor )

withSymbols : List Chart.Internal.Symbol.Symbol -> Config msg { validation | canHaveSymbols : () } -> Config msg validation

Pass a list of symbols to be rendered at the end of the bars.

Default value: []

Usefull for facilitating accessibility.

Bar.init requiredConfig
    |> withSymbols [ Circle, Corner, Triangle ]
    |> Bar.render ( data, accessor )

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

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

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

Sets an accessible title for the whole 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.

Bar.init requiredConfig
    |> Bar.withTitle "This is a chart"
    |> Bar.render ( data, accessor )

withXDomain : List String -> Config msg validation -> Config msg validation

Sets the band domain explicitly. The data relates to the xValue accessor.

Bar.init requiredConfig
    |> Bar.withXDomain [ "a", "b" ]
    |> Bar.render ( data, accessor )

withXGroupDomain : List String -> Config msg validation -> Config msg validation

Sets the group band domain explicitly. The group data relates to the xGoup accessor.

Bar.init requiredConfig
    |> Bar.withXGroupDomain [ "0" ]
    |> Bar.render ( data, accessor )

withXLabels : Config msg validation -> Config msg validation

Show the X ordinal values at the end of the bars.

If used together with symbols, the label will be drawn on top of the symbol.

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

Bar.init requiredConfig
    |> Bar.withXLabels
    |> Bar.render ( data, accessor )

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

Sets the continuous domain explicitly. The data relates to the yValue accessor.

Bar.init requiredConfig
    |> Bar.withYDomain ( 0, 0.55 )
    |> Bar.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.

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

Axis

⚠ axisLeft & axisRight apply to a vertical chart context. If you change the chart orientation to horizontal, the axis positioning will always change to bottom.


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

The XAxis type


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

The YAxis type

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

It returns an XAxis Bottom type

Bar.axisBottom [ Axis.tickCount 5 ]

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

It returns an YAxis Grid type

Bar.axisGrid [ Axis.tickCount 5 ]

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

It returns an YAxis Left type

Only relevant if the chart orientation is vertical.

Bar.axisLeft [ Axis.tickCount 5 ]

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

It returns an YAxis Right type

Only relevant if the chart orientation is vertical.

Bar.axisRight [ Axis.tickCount 5 ]

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

It returns an XAxis Top type

Bar.axisTop [ Axis.tickCount 5 ]

hideAxis : Config msg validation -> Config msg validation

Hide all axis.

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

hideXAxis : Config msg validation -> Config msg validation

Hide the X aixs.

The X axis depends from the layout:

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

hideYAxis : Config msg validation -> Config msg validation

Hide the Y aixs.

The Y axis depends from the layout:

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

withXAxis : Chart.Internal.Axis.XAxis String -> Config msg validation -> Config msg validation

Customise the xAxis

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

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

Customise the yAxis

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

Configuration arguments

diverging : Chart.Internal.Type.Direction

Diverging layout for stacked bar charts.

An example can be a population pyramid chart.

Bar.init requiredConfig
    |> Bar.withStackedLayout Bar.diverging
    |> Bar.render ( data, accessor )

horizontal : Chart.Internal.Type.Orientation

Horizontal layout type.

Used as argument to Bar.withOrientation.

Bar.init requiredConfig
    |> Bar.withOrientation horizontal
    |> Bar.render ( data, accessor )

noDirection : Chart.Internal.Type.Direction

Default layout for stacked bar charts, where the bars are sequentially stacked one upon another.

Bar.init requiredConfig
    |> Bar.withStackedLayout Bar.noDirection
    |> Bar.render ( data, accessor )

stackedColumnTitle : (Basics.Float -> String) -> Chart.Internal.Type.ColumnTitle

vertical : Chart.Internal.Type.Orientation

Vertical layout type.

Used as argument to Bar.withOrientation. This is the default layout.

Bar.init requiredConfig
    |> Bar.withOrientation vertical
    |> Bar.render ( data, accessor )

xGroupLabel : Chart.Internal.Type.Label

xLabel : Chart.Internal.Type.Label

xOrdinalColumnTitle : Chart.Internal.Type.ColumnTitle

yColumnTitle : (Basics.Float -> String) -> Chart.Internal.Type.ColumnTitle

yLabel : (Basics.Float -> String) -> Chart.Internal.Type.Label