Circos > Documentation > Tutorials > Configuration > Colors
Loading
Circos at the EMBO NGS workshop in Tunis, Sept 15–25.

Use the latest version of Circos and read Circos best practices—these list recent important changes and identify sources of common problems.
If you are having trouble, post your issue to the Circos Google Group and include all files and detailed error logs. Please do not email me directly unless it is urgent—you are much more likely to receive a timely reply from the group.
Don't know what question to ask? Read Points of View: Visualizing Biological Data by Bang Wong, myself and invited authors from the Points of View series.

0 — Configuration and Installation

4. Colors

If you are having trouble with installation of Perl or modules, use online resources that explain the details of how to download Perl, get it working (Linux, Mac OS X, Windows [win32.perl.org wiki, ActiveState, Strawberry]), and how to install modules (UNIX, Windows). If you're still stuck, post your questions to the Circos group.

Need to install modules? See A Guide to Installing Modules and its corresponding tutorial for Windows users.

Having trouble with libgd and GD? See the Perl Monks libgd/GD Tutorial, Shaun Jackman's Homebrew formula, Paulo Nuin's Installing Circos on Mac OS X, Wang's install zlib/libpng/jpeg/freetype/libgd/GD on Mavericks as well as my own guide for installation of libpng, freetype, libgd and GD on Mac OS X Mavericks. There are some useful threads in the Google Group about this.

Need to run Bash shell batch files in Windows? You'll need to install a UNIX command line shell, like Cygwin.

Stumped by an error? A good strategy is to Google the error message (e.g. mkdir /usr/local/share/man: permission denied) to find the solution.

Want to learn more about Perl? Try learn.perl.org.

color definitions

RGB and HSV

Colors are defined using RGB or HSV values.

red = 255,0,0    # RGB definition
red = hsv(0,1,1) # HSV definition

The range of RGB components is [0..255]. HSV values range is H=[0,360] (integer), S=[0,1] (float) and V=[0,1] (float).

transparent RGB values

RGB values can have an optional 4th field to indicate transparency. The transparency can be specified in the range [0,1] or [0,127]. Both map onto the same result. The minimum value (0) indicates full opacity while the maximum (1 or 127) indicates full transparency.

# 0 < alpha < 1 
# 0 opaque
# 1 transparent
red_faint = 255,0,0,0.8

# or 
#
# 0 < alpha < 127
# 0   opaque
# 127 transparent
red_also_faint = 255,0,0,102

Please see Transparent Link tutorial for discussion about automating definition of these colors.

full transparency

To create a fully transparent color (e.g. for an image with transparent background), you'll need to define a color named transparent. A transparent color still requires an RGB value (a strange artefact in gd implementation). Choose an RGB value that you aren't using elsewhere. Typically something like 1,0,0 will be suitable.

# in color.conf
transparent = 1,0,0

The transparent color will be available using the name transparent. A synonym clear is also provided. To use the transparent color (e.g. for background),

<image>
...
background = transparent # 'clear' also works here 
...
</image>

The names transparent and clear are reserved. Do not use these two color names for other colors.

synonyms

You can include synonyms for colors, by defining one color using the name of another color, instead of RGB or RGBA values.

green  = 51,204,94
orange = 255,136,0
...
favourite        = green
almost_favourite = orange

Be careful not to create infinite lookup loops — these produce an error.

# don't do this
favourite = green
green     = favourite

<color> block

The <colors> block contains all the color definitions.

Circos comes with a large number of default color definitions (pure colors and hues, Brewer palettes, UCSC chromosome color schemes, luminance-normalized colors, etc). You should always include these in your configuration, unless you have a good reason not to.

The best way to do this is to import the etc/colors_fonts_patterns.conf in your circos.conf. Importing this file will define colors, fonts and patterns, using the appropriate block structure.

# circos.conf
<<include etc/colors_fonts_patterns.conf>>

For example, etc/colors_fonts_patterns.conf contains the following

<colors>
<<include etc/colors.conf>>
</colors>

In turn, etc/colors.conf has the following definitions

# primary RGB colors
...

# Brewer palettes
# see etc/colors.brewer.conf
<<include colors.brewer.conf>>

# UCSC genome browser human chromosome colors
# see etc/colors.ucsc.conf
<<include colors.ucsc.conf>>

# HSV pure colors
# see etc/colors.hsv.conf
<<include colors.hsv.conf>>

using colors

Colors are referenced using their RGB values or their names (see below).

# using RGB values
color = 107,174,241

# using name
color = blue

When passing a color as an option in data files, the RGB values need to be delimited by (...). For example, if you want to add a color to a link

# using a color name
chr1 100 200 chr2 200 250 color=blue,thickness=2

# using RGB value
chr1 100 200 chr2 200 250 color=(107,174,241),thickness=2

predefined colors

named colors with tone prefix

For each of the named colors red, orange, yellow, green, blue, and purple, the following are defined

vvl{name} - very very light version of color
vl{name}  - very light
l{name}   - light
{name}    - default tone
d{name}   - dark
vd{name}  - very dark
vvd{name} - very very dark

The tone ladder is based on Brewer palette colors (see below).

# points to Brewer color...
orange = oranges-7-seq-4

# ...which is defined in colors.brewer.conf as
oranges-7-seq-4 = 253,141,60

For example, for red we have vvlred, vlred, lred, red, dred, vdred and vvdred.

vvlred = reds-7-seq-1
vlred  = reds-7-seq-2
lred   = reds-7-seq-3
red    = reds-7-seq-4
dred   = reds-7-seq-5
vdred  = reds-7-seq-6
vvdred = reds-7-seq-7

In the case of grey, additional vvvlgrey and vvvdgrey are available.

Also defined are white and black.

named pure colors with tone prefix

For pure color versions of the above definitions (i.e. not based on Brewer palettes), use the p (pure) prefix to the color name.

vvlp{name} - very very light version of color
vlp{name}  - very light
lp{name}   - light
p{name}    - default tone
dp{name}   - dark
vdp{name}  - very dark
vvdp{name} - very very dark

For example, for red we have vvlpred, vlpred, lpred, pred, dpred, vdpred and vvdpred.

# pure orange
porange  = 255,127,0

# dark pure orange
dporange = 234,110,0

Brewer colors

Brewer colors compose Brewer palettes which have been manually defined by Cynthia Brewer for their perceptual properties.

Brewer colors are categorized into one of three palette types: sequential, diverging and qualitative. For a given palette type (e.g. sequential), there are a variety of palettes (e.g. reds, greens, blues). Each palette is available for various number of colors (e.g. 3, 4, 5, ...).

The syntax for a Brewer color name is palettename-ncolors-palettetype-index. The palette names, for each type, are

# sequential (-seq-) (3-9 colors)
blues
bugn
bupu
gnbu
greens
greys
oranges
orrd
pubu
pubugn
purd
purples
rdpu
reds
ylgn
ylgnbu
ylorbr
ylorrd

# diverging (-div-) (3-11 colors)
brbg
piyg
prgn
puor
rdbu
rdgy
rdylbu
rdylgn
spectral

# qualitative (-qual-) (3-8 colors, some up to 12 colors)
accent (3-8 colors)
dark2 (3-8 colors)
paired (3-12 colors)
pastel1 (3-9 colors)
pastel2 (3-8 colors)
set1 (3-9 colors)
set2 (3-8 colors)
set3 (3-12 colors)

For example, purple-orange diverging 9-color palette colors are puor-9-div-1, puor-9-div-2, ..., puor-9-div-9.

I suggest that you try using the Brewer colors (e.g. orange vs porange), because they are perceptually uniform. However, they will appear less punchy and saturated than their pure equivalents. In particular, the Brewer reds may appear pinkish and light when used on their own.

Experiment, but be aware of the perceptual aspects of color, which will influence how your figure is perceived (see my Color Palettes Matter presentation).

HSV colors

You can use the HSV color space to define colors. To do so, specify the HSV values as hsv(h,s,v). For example,

red = hsv(0,1,1)

All pure HSV colors (s = 1, v = 1) are defined in colors.hsv.conf.

hue000 = hsv(0,1,1)
hue001 = hsv(1,1,1)
...
hue359 = hsv(359,1,1)
hue360 = hsv(360,1,1) # same as hue000

chromosome color scheme

A set of colors named after chromosomes is also defined and corresponds to the chromosome color scheme used by UCSC Genome Browser and other online resources. This is a standardized palette.

chr1 = 153,102,0
chr2 = 102,102,0
chr3 = 153,153,30
...
chrX = 153,153,153
chrY = 204,204,204

Another set of colors is named after cytogenetic band colors, typically reported in karyotype files. These colors define the G-staining shades seen in ideograms.

gpos100 = 0,0,0
gpos    = 0,0,0
gpos75  = 130,130,130
gpos66  = 160,160,160
gpos50  = 200,200,200
gpos33  = 210,210,210
gpos25  = 200,200,200
gvar    = 220,220,220
gneg    = 255,255,255
acen    = 217,47,39
stalk   = 100,127,164

Because the original UCSC color palette is not uniform in brightness (e.g. chr10 is a very bright yellow, whereas chr1 is a dark brown), I make luminance-normalized (70, 80 and 90%) versions of these colors available.

# 70% luminance
lum70chr1
...
lum70chrY

# 80% luminance
lum80chr1
...
lum80chrY

# 90% luminance
lum90chr1
...
lum90chrY

Given that Circos uses species prefix for chromosome names (e.g. human chromosomes are named hsN rather than chrN, I also provide synonyms for all the UCSC colors using the chr -> hs name.

hs1 = chr1
hs2 = chr2
...
lum70hs1 = lum70chr1
lum90hs1 = lum80chr1
lum90hs1 = lum90chr1
...

unix colors

The file etc/colors.unixnames.txt defines a large number (700+) of named colors, taken from UNIX's rgb.txt file. This file is not included by default.

Many definitions in this file duplicate definitions in colors.conf (e.g. colors.unixnames.txt defines blue as 0,0,255 but in colors.conf it is blues-7-seq-4, which is 107,174,214). Including colors.unixnames.txt together with (colors.conf) will result in an error.

color lists

A color list can be defined by specifying a comma-delimited list of existing colors

red_list = dred,red,lred,vlred

or, more conveniently, a regular expression. The results will be sorted by the value of any capture buffers. The order will be reasonable (numerically or alphanumerically depending on the value of the capture buffer). If you want to sort the matches in reverse, wrap the regular expression in rev().

For example, to create a list of the 9-color spectral Brewer palette,

spectral9 = spectral-9-div-(\d+)

and to create a reversed list

spectral9r = rev(spectral-9-div-(\d+))

Color lists are used with heat maps.

Brewer palette Lists

Lists for all Brewer palettes are predefined (see etc/brewer.lists.conf). For a given color set name-ncolors-type-index, two lists are available

  • name-ncolors-type Brewer palette color list (e.g. reds-8-seq = reds-8-seq-1,reds-8-seq-2,...)
  • name-ncolors-type-rev corresponding palette, with colors in reverse order (e.g. reds-8-seq-rev = reds-8-seq-8,reds-8-seq-7,...)

For example, the 6-color Brewer palette lists that are defined are

# sequential
blues-6-seq
bugn-6-seq
bupu-6-seq
gnbu-6-seq
greens-6-seq
greys-6-seq
oranges-6-seq
orrd-6-seq
pubu-6-seq
pubugn-6-seq
purd-6-seq
purples-6-seq
rdpu-6-seq
reds-6-seq
ylgn-6-seq
ylgnbu-6-seq
ylorbr-6-seq
ylorrd-6-seq

# diverging
brbg-6-div
piyg-6-div
prgn-6-div
puor-6-div
rdbu-6-div
rdgy-6-div
rdylbu-6-div
rdylgn-6-div
spectral-6-div

# qualitative
accent-6-qual
dark2-6-qual
paired-6-qual
pastel1-6-qual
pastel2-6-qual
set1-6-qual
set2-6-qual
set3-6-qual

Each has a -rev (reversed) counterpart (e.g. spectral-6-div and spectral-6-div-rev).

These lists are automatically imported from etc/colors.brewer.lists.conf via etc/colors.brewer.conf. Thus, if you import the Brewer colors (done by default), you are automatically including all Brewer lists.

HSV color lists

Brewer palettes provide sets of perceptually uniform colors and should be used whenever possible (i.e., always).

Additionally, color sets of pure HSV colors (s = 1, v = 1) are defined in colors.hsv.conf. Two kind of HSVG color lists are defined.

Lists of colors by hue step are named hue-sH, for a set of colors that vary by a change in hue of H. For example, hue-s45 includes the colors hue000, hue045, hue090, hue135, hue180, hue225, hue270, hue315. Lists for steps 2, 3, 4, 5, 6, 8, 9, 10, 12, 15, 18, 20, 24, 30, 36, 40, 45, 60, 72, 90, 120, 180 and 360 are defined.

The other set of lists are named hue-N, for a set of N uniformly spaced colors. For example, hue-7 includes the colors hue000, hue051, hue103, hue154, hue206, hue257, and hue309. Lists for 3 to 30 colors are defined.

color list cache

Generating the color lists can take several seconds. For this reason, Circos employs a caching mechanism to store color lists definitions. By default, the cache file is /tmp/circos.colorlist.dat. If the cache is older than the configuration file, or color definitions, it is recomputed. The length of time required is a function of the total number of colors (color definitions multiplied by automatic transparency levels) and the number of lists. If you are trying to optimize image generation speed, and do not wish to count on caching, remove any list definitions you are not using and reduce the number of automatic transparency levels.

creating your own colors

I strongly suggest that you place new color definitions in a separate file. Modularity will make maintenance easier. And given that you'll likely want access to your custom colors for all images, include them globally rather than on an image-by-image basis.

For example, if you create your own blue

# in mycolors.conf
niceblue = 17,111,227

you can include this file like this

# all default color definitions
<<include colors_fonts_patterns.conf>>

# this will append your definitions to the <colors> block
<colors>
<<include mycolors.conf>>
</colors>

You can quickly add colors directly

# all default color definitions
<<include colors_fonts_patterns.conf>>

# this will append your definitions to the <colors> block
<colors>
<<include mycolors.conf>>
niceblue2 = 37,101,179
</colors>