ContEx v0.3.0 Contex.BarChart View Source

Draws a barchart from a Contex.Dataset.

Contex.BarChart will attempt to create reasonable output with minimal input. The defaults are as follows:

  • Bars will be drawn vertically (use orientation/2 to override - options are :horizontal and :vertical)
  • The first column of the dataset is used as the category column (i.e. the bar), and the second column is used as the value column (i.e. the bar height). These can be overridden with set_cat_col_name/2 and set_val_col_names/2
  • The barchart type defaults to :stacked. This doesn't really matter when you only have one series (one value column) but if you accept the defaults and then add another value column you will see stacked bars rather than grouped. You can override this with type/2
  • By default the chart will be annotated with data labels (i.e. the value of a bar will be printed on a bar). This can be overriden with data_labels/2. This override has no effect when there are 4 or more value columns specified.
  • By default, the padding between the data series is 2 (how this translates into pixels depends on the plot size you specify when adding the barchart to a Contex.Plot)

By default the BarChart figures out reasonable value axes. In the case of a :stacked bar chart it find the maximum of the sum of the values for each category and the value axis is set to {0, that_max}. For a :grouped bar chart the value axis minimum is set to the minimum value for any category and series, and likewise, the maximum is set to the maximum value for any category and series. This may not work. For example, in the situation where you want zero to be shown. You can force the range using force_value_range/2

Link to this section Summary

Functions

Specifies the label rotation value that will be applied to the bottom axis. Accepts integer values for degrees of rotation or :auto. Note that manually set rotation values other than 45 or 90 will be treated as zero. The default value is :auto, which sets the rotation to zero degrees if the number of items on the axis is greater than eight, 45 degrees otherwise.

Overrides the default colours.

Allows the axis tick labels to be overridden. For example, if you have a numeric representation of money and you want to have the value axis show it as millions of dollars you might do something like

Specifies whether data labels are shown on the bars

Optionally specify a LiveView event handler. This attaches a phx-click attribute to each bar element. Note that it may not work with some browsers (e.g. Safari on iOS).

Forces the value scale to the given data range

Creates a new barchart from a dataset and sets defaults.

Specifies whether the bars are drawn horizontally or vertically.

Specifies the padding between the category groups. Defaults to 2. Specified relative to the plot size.

Highlights a selected value based on matching category and series.

Sets the category column name. This must exist in the dataset.

Sets the default scales for the plot based on its column mapping.

Sets the value column names. Each must exist in the dataset.

Specifies whether the bars are drawn stacked or grouped.

Link to this section Types

Link to this type

orientation()

View Source
orientation() :: :vertical | :horizontal
Link to this type

plot_type()

View Source
plot_type() :: :stacked | :grouped
Link to this type

selected_item()

View Source
selected_item() :: %{category: any(), series: any()}
Link to this type

t()

View Source
t() :: %Contex.BarChart{
  axis_label_rotation: term(),
  category_scale: term(),
  colour_palette: term(),
  custom_value_formatter: term(),
  data_labels: term(),
  dataset: term(),
  height: term(),
  mapping: term(),
  options: term(),
  orientation: term(),
  padding: term(),
  phx_event_handler: term(),
  select_item: term(),
  series_fill_colours: term(),
  type: term(),
  value_range: term(),
  value_scale: term(),
  width: term()
}

Link to this section Functions

Link to this function

axis_label_rotation(plot, rotation)

View Source
axis_label_rotation(t(), integer() | :auto) :: t()

Specifies the label rotation value that will be applied to the bottom axis. Accepts integer values for degrees of rotation or :auto. Note that manually set rotation values other than 45 or 90 will be treated as zero. The default value is :auto, which sets the rotation to zero degrees if the number of items on the axis is greater than eight, 45 degrees otherwise.

Overrides the default colours.

Colours can either be a named palette defined in Contex.CategoryColourScale or a list of strings representing hex code of the colour as per CSS colour hex codes, but without the #. For example:

  barchart = BarChart.colours(barchart, ["fbb4ae", "b3cde3", "ccebc5"])

The colours will be applied to the data series in the same order as the columns are specified in set_val_col_names/2

Link to this function

custom_value_formatter(plot, custom_value_formatter)

View Source
custom_value_formatter(t(), nil | (... -> any())) :: t()

Allows the axis tick labels to be overridden. For example, if you have a numeric representation of money and you want to have the value axis show it as millions of dollars you might do something like:

  # Turns 1_234_567.67 into $1.23M
  defp money_formatter_millions(value) when is_number(value) do
    "$#{:erlang.float_to_binary(value/1_000_000.0, [decimals: 2])}M"
  end

  defp show_chart(data) do
    BarChart.new(data)
    |> BarChart.custom_value_formatter(&money_formatter_millions/1)
  end
Link to this function

data_labels(plot, data_labels)

View Source
data_labels(t(), boolean()) :: t()

Specifies whether data labels are shown on the bars

Link to this function

event_handler(plot, event_handler)

View Source

Optionally specify a LiveView event handler. This attaches a phx-click attribute to each bar element. Note that it may not work with some browsers (e.g. Safari on iOS).

Link to this function

force_value_range(plot, value_range)

View Source
force_value_range(t(), {number(), number()}) :: t()

Forces the value scale to the given data range

Link to this function

new(dataset, options \\ [orientation: :vertical])

View Source
new(Contex.Dataset.t(), keyword()) :: t()

Creates a new barchart from a dataset and sets defaults.

If the data in the dataset is stored as a map, the :mapping option is required. This value must be a map of the plot's :category_col and :value_cols to keys in the map, such as %{category_col: :column_a, value_cols: [:column_b, column_c]. The value for the :value_cols key must be a list.

Link to this function

orientation(plot, orientation)

View Source
orientation(t(), orientation()) :: t()

Specifies whether the bars are drawn horizontally or vertically.

Link to this function

padding(plot, padding)

View Source
padding(t(), number()) :: t()

Specifies the padding between the category groups. Defaults to 2. Specified relative to the plot size.

Link to this function

select_item(plot, select_item)

View Source
select_item(t(), selected_item()) :: t()

Highlights a selected value based on matching category and series.

Link to this function

set_cat_col_name(plot, cat_col_name)

View Source

Sets the category column name. This must exist in the dataset.

This provides the labels for each bar or group of bars

Link to this function

set_default_scales(plot)

View Source
set_default_scales(t()) :: t()

Sets the default scales for the plot based on its column mapping.

Link to this function

set_val_col_names(plot, val_col_names)

View Source

Sets the value column names. Each must exist in the dataset.

This provides the value for each bar.

Link to this function

type(plot, type)

View Source
type(t(), plot_type()) :: t()

Specifies whether the bars are drawn stacked or grouped.