Plot

Colors

This document shows you how to change the colors of your novem plot, including themes and types.

The novem api has two primary options to help you change the colors that you want.

  • The type - what kind of colors are you defining (think categorical vs gradient or table vs barchart)
  • The colors - the actual colors that you want to use

In addition novem supports theming, where you can select from several pre-made ones or define your own (for professional or above subscribers).

The last thing to keep in mind is that novem also supports dark-mode, so all themes and colors can have a corresponding dark-mode variant.

As can be seen from the config overview, the color configuration consists of three endpoints to interact with: type, colors and theme.

en_letter_frequency      => Name
...
├── config               => Configuration options
...
│   └── colors           => Folder for the color options
│       ├── colors       => The actual color values
│       ├── theme [TODO] => Color theme to use
│       └── type         => The type of colors
├── data                 => data to chart
...

Like most novem api end-points the above values can be modified with a POST request containing the desired values.

The type endpoint control how to interpret the colors endpoint and can have one of three values.

  • clr parses the content of the colors file to color your visualisation, this is the most common way to set your novem colors
  • ix enables the index colors — a custom novem format for coloring tables and other matrix style structures
  • pack the content of colors now refers to a predefined color pack, useful if you have certain colors styles you want to reuse across your visuals

The theme endpoint allows you to refer to a global, organisational or personal theme. Custom theme support is available for professional and above subscriptions.

Everyone has access to the default theme novem along with novem-light and novem-dark.

The content of colors controls the actual colors of the plot. How the content of colors is interpreted depends on the value specified in type.

The simplest is pack, here the value of colors is used to look up a color pack with the given name, if no color pack exists, the default colors are used.

Then comes ix which is used to color tables and other matrix like structures. Unlike pack and clr, ix is tightly coupled to the data and not usually found in pack definition.

Finally we have clr which is used for everything else. Clr is intended to offer both flexibility and to be easy to edit by hand, the price of this is a bit more complexity, but we believe the tradeoff is worth it.

Due to the complexity of ix and clr instructions we've added separate sections for each of them below.

Novem is currently in closed alpha, CLR Color documentation will be added soon.

If you want to add colors to any of your novem tables then you'll be using index colors. You enable index colors by setting the /config/colors/type endpoint to ix.

Index colors use the novem slicing notation to describe an area of the table and then the color instructions to color the selected segment.

Index colors consists of three core components

  1. Selectors - the row and column selectors
  2. Plane - foreground or background
  3. Color Instruction - the colors and associated information
: :
Selector

A novem selector which denotes which rows and columns the color should be applied to.

bg
Plane instruction

There are two dimensions or planes you can color in a table, foreground and background.

blue-200
Novem Color Instruction

Color plane of the slice given by the row and column selectors.

See below for an example of a complex color instruction.

Novem supports setting fixed foreground or background colors using the sta instruction. The color is applied to the part of the table defined by the given selector.

Both light and darkmode colors can be supplied explicitly or else is inferred by the theme.

Static colors are defined with the sta instruction and offers only a single color per row (with optional darkmode variant).

: : sta fg|bg color-light color-dark

This example shows a static background color pattern reminiscent of a picnic blanket using three shades of blue.

Here we use four selectors and take particular advantage of the step instructor. First we color alternating rows starting at different offsets. Then we add alternating columns, overwriting select colors.

-- Create a "picnic blanket" using 4 shades of blue
 ::2  :     bg blue-100 -- color every other row starting at 0
1::2  :     bg blue-200 -- color every other row starting at 1
1::2 1::2   bg blue-300 -- color every other col starting at row 1 col 1
 ::2 1::2   bg blue-200 -- color every other row starting at row 0 col 1

Here we emulate a hierarchical structure in our table by coloring rows in descending shades of gray, a common strategy when wanting to preserve space.

Unlike in the picnic example above, here we use a comma separated list of rows to shade, this is because there is no geometric pattern to the hierarchy, rather it depends on the data itself.

-- Color rows by "hierarchy"
1           : bg gray-500 -- world
2,5,8       : bg gray-400 -- region 1
3,6,9,12,19 : bg gray-300 -- region 2

Later instructions will override the colors of the previous instructions, below is an example drawing several "squares" in different colors.

As you can see the purple square is drawn on top of the blue and red squares, this is because colors are applied in the order they are defined.

-- Create some colorful "squares"
  2:4    1:3   bg blue-200
  6:8    1:3   bg red-200
 10:12   1:3   bg green-200
  4:6    3:5   bg purple-200
  2:5    7:9   bg pink-200
  8:11   5:7   bg yellow-200

-- Creating our "gradient"
  3    11:-1   bg orange-100
  4    11:-1   bg orange-200
  5    11:-1   bg orange-300
  6    11:-1   bg orange-400
  7    11:-1   bg orange-500
  8    11:-1   bg orange-600
  9    11:-1   bg orange-700
 10    11:-1   bg orange-800
 11    11:-1   bg orange-900

Changing the the instructions above from bg to fg will color the text located in the cells instead of the background as can be seen below (with 400 instead of 200 colors along with a global gray-300).

So far we've only shown static colors, but novem also supports colors based on the value contained in the cells, we call this dynamic colors. Dynamic colors are created by providing a novem color instruction consisting of a color range along with optional domain and scale.

A color range is a comma separated list of novem colors which by default is linearly interpolated over the corresponding cell values. Novem also supports logarithmic and exponential interpolations using the scale function.

To supply a scale simply add a caret ^ followed by the scale to the end of the color instruction .e.g. ^lin, ^log or ^exp.

Finally you can also control the the domain of the underlying values, by default the values in the cells selected by the row and column selectors are used, but this can be overridden by supplying a domain function.

The domain function consists of sequence of comma separated numbers contained in a bracket. The numbers will be matched to the corresponding color in the order supplied.

If you want to mix and match values from the underlying dataset along with specific domain values, such as forcing 0 for a neutral color in a diverging dataset, you can use the _ (underscore) operator. The _ gets replaced with the corresponding value from the dataset based on its position in the domain.

Below you can see an example of a Novem Color Instruction that creates a linear heatmap from red -> gray -> green with red for numbers below zero and green for numbers above. Numbers in the zero range are colored gray.

N.B. Please be aware that Novem Color Instructions should contain no space!

bad,neutral,good
range

Create a color range of three novem theme colors. Here we use the subjective bad, neutral and good colors which are mapped to red, gray and green.

(,0,)
domain

If we didn't specify a domain, the linear midpoint in our data could be located below or above zero. Here we use the domain function to force neutral to be zero whilst using the underlying value for the lowest (bad) and highest (good) colors.

^lin
scale

Finally we state that this should be a linear color interpretation. This is the default behavior, so technically this instruction could be skipped.

Here we use the above information to create a heatmap over a given dataset.

As you can see we get a nice linear spread across our predefined color range. In addition we've included a separate selection in the center showing that those colors are interpolated within the designated value selection.

  :     :    bg bad,neutral,good(_,0,_)^lin
 4:9   4:9   bg bad,neutral,good(_,0,_)^lin

Whilst the above example can look a bit stylized, below is a table using real world data from our Novem Example Index dataset. If you're curious about how we made this visual check out our blog.

Next
Table