View Source Contex.CategoryColourScale (ContEx v0.5.0)

Maps categories to colours.

The Contex.CategoryColourScale maps categories to a colour palette. It is used, for example, to calculate the fill colours for Contex.BarChart, or to calculate the colours for series in Contex.PointPlot.

Internally it is a very simple map with some convenience methods to handle duplicated data inputs, cycle through colours etc.

The mapping is done on a first identified, first matched basis from the provided dataset. So, for example, if you have a colour palette of ["ff0000", "00ff00", "0000ff"] (aka red, green, blue), the mapping for a dataset would be as follows:

XYCategoryMapped Colour
00Turtlered
11Turtlered
01Camelgreen
21Brontosaurusblue
34Turtlered
55Brontosaurusblue
67Hippopotamusred ← NOTE - if you run out of colours, they will cycle

Tn use, the CategoryColourScale is created with a list of values to map to colours and optionally a colour palette. If using with a Contex.Dataset, it would be initialised like this:

dataset = Dataset.new(data, ["X", "Y", "Category"])
colour_scale
  = dataset
  |> Dataset.unique_values("Category")
  |> CategoryColourScale(["ff0000", "00ff00", "0000ff"])

Then it can be used to look up colours for values as needed:

fill_colour = CategoryColourScale.colour_for_value(colour_scale, "Brontosaurus") // returns "0000ff"

There are a number of built-in colour palettes - see colour_palette(), but you can supply your own by providing a list of strings representing hex code of the colour as per CSS colour hex codes, but without the #. For example:

  scale = CategoryColourScale.set_palette(scale, ["fbb4ae", "b3cde3", "ccebc5"])

Link to this section Summary

Functions

Look up a colour for a value from the palette.

Create a function to lookup a value from the palette.

Get the default colour. Surprise.

Inverts the order of values. Note, the palette is generated from the existing colour map so reapplying a palette will result in reversed colours

Create a new CategoryColourScale from a list of values.

Sets the default colour for the scale when it isn't possible to look one up for a value

Update the colour palette used for the scale

Link to this section Types

@type colour_palette() :: nil | :default | :pastel1 | :warm | list()
@type t() :: %Contex.CategoryColourScale{
  colour_map: term(),
  colour_palette: term(),
  default_colour: term(),
  values: term()
}

Link to this section Functions

Link to this function

colour_for_value(colour_scale, value)

View Source
@spec colour_for_value(t() | nil, any()) :: String.t()

Look up a colour for a value from the palette.

Link to this function

domain_to_range_fn(scale)

View Source

Create a function to lookup a value from the palette.

Link to this function

get_default_colour(colour_scale)

View Source
@spec get_default_colour(t() | nil) :: String.t()

Get the default colour. Surprise.

Inverts the order of values. Note, the palette is generated from the existing colour map so reapplying a palette will result in reversed colours

Link to this function

new(raw_values, palette \\ :default)

View Source
@spec new(list(), colour_palette()) :: t()

Create a new CategoryColourScale from a list of values.

Optionally attach a colour palette. Pretty well any value list can be used so long as it can be a key in a map.

Link to this function

set_default_colour(colour_scale, colour)

View Source

Sets the default colour for the scale when it isn't possible to look one up for a value

Link to this function

set_palette(colour_scale, palette)

View Source
@spec set_palette(t(), colour_palette()) :: t()

Update the colour palette used for the scale