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
request containing the desired values.
type endpoint control how to interpret the
colors endpoint and can have
one of three values.
clrparses the content of the colors file to color your visualisation, this is the most common way to set your novem colors
indexcolors — a custom novem format for coloring tables and other matrix style structures
packthe content of colors now refers to a predefined color pack, useful if you have certain colors styles you want to reuse across your visuals
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
The content of
colors controls the actual colors of the plot. How the content of
colors is interpreted depends on the value specified in
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.
ix which is used to color tables and other matrix like structures.
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
clr instructions we’ve added separate sections
for each of them below.
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
Index colors use the novem slicing notiation to describe an area of the table and then the color instructions to color the selected segment.
Index colors consists of three core components
- Selectors - the row and column selectors
- Plane - foreground or background
- Color Instruction - the colors and associated information
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
Creating a pattern
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
Adding a hierarchy
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 geomteric 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
Playing with squares
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 sqaure 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
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
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
To supply a scale simply add a caret
^ followed by the scale to the end
of the color instruction .e.g.
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 overriden by supplying a
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 corrsponding value from the dataset based on it’s position in the
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.
Creating a heatmap
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
A real world example
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.