CIRCOS(1)

📦
version 0.69.9 · 2 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

✨ circos(1) ✨

okay bestie, sit down, hydrate, and let's talk about the most iconic circle-drawing situation on the planet 💖

                                       ____ _
                                      / ___(_)_ __ ___ ___  ___
                                     | |   | | '__/ __/ _ \/ __|
                                     | |___| | | | (_| (_) \__ \
                                      \____|_|_|  \___\___/|___/

                                                   round is good

💫 NAME 💫

circos — generate circular data visualizations 🌈🎀

Like. It makes circles. Gorgeous ones. And it's literally called circos. Periodt. 💅

🌸 SYNOPSIS 🌸

here's the whole vibe, verbatim, no edits, i would never:

# without -conf Circos will search for configuration
circos

# use specific configuration file
circos -conf circos.conf

# diagnose required modules
circos -modules

# detailed debugging for code components
# see http://www.circos.ca/documentation/tutorials/configuration/debugging
circos -debug_group GROUP1,[GROUP2,...]

# full debugging
circos -debug_group _all

# absolutely no reporting
circos ... [-silent]

# configuration dump of a block (or block tree) of
# any parameters that match REGEXP (optional)
circos -cdump [BLOCK1/[BLOCK2/...]]{:REGEXP}
circos -cdump ideogram
circos -cdump ideogram:label
circos -cdump ideogram/spacing

# override configuration parameters
circos -param image/radius=2000p -param ideogram/show=no

# for fun - randomize all colors in the image except for
# COLOR1, COLOR2,...
circos -randomcolor COLOR1,[COLOR2,...]
circos -randomcolor white,black

# brief help
circos -h

# man page
circos -man

# version
circos -v

run it with no args and it goes hunting for config all by itself, main character energy tbh 🫶

🦋 SUPPORT 🦋

need a hand? a shoulder to cry on? a human who knows things? 😭 the Google Group is where the people are:

https://groups.google.com/forum/#!forum/circos-data-visualization

that's the whole support section, yes, one link, and honestly? respect. no fluff. 👑

🌈 DESCRIPTION 🌈

Circos generates circular data visualizations. It is ideal for exploring relationships between objects or positions. 🎯

And now the part that makes some people nervous and makes me feral: Circos does not have an interface. no buttons. no drag-and-drop. no wizard. It is driven by plain-text configuration files (see below). And the way that this is actually a feature and not a crime — it makes Circos scriptable and easily incorporated into automatic data analysis and reporting pipelines. slay. 💅

💖 Uses 💖

lore time, bestie. Circos was initially designed to visualize genomic information, specifically genomic rearrangements in tumor genomes. 🧬

And yes — some important parameters in configuration files are named to be intuitve to biologists (e.g. "chromosomes"). (that spelling is theirs, i'm not touching it, i'm not that brave 🫶)

But listen: Circos is not limited to the kind of data it can display. Not even a little. Circular heatmaps, histograms, scatter plots and other types of data displays can be easily made from data collected in other fields, such as meteorology, social science, and computer security. 🌦️📊🔐

so like… it's giving universal. it's giving "circles for every fandom." 💀

✨ Salience and Relevance ✨

okay this part is genuinely the philosophy of the whole thing and i'm obsessed. 😭💖

One of the challenges in creating data visualizations is to aptly map what is important (relevance) onto graphical elements that stand out from others (salience). 🎯

Being able to emphasize (e.g. change color) or attenuate (e.g. add transparency or even hide) salience of information without changing the original data input files is a key feature of Circos. 🫶

How data is displayed can be easily changed by writing rules, which are evaluated at run-time. Rules can be designed to apply to all data points or only to those that pass certain conditions. Conditions can be based on any property of the data (value, position, format). And rules can be chained into a decision tree making it possible to progressively change the format of data based on the output of other rules. 🌳✨

rules on rules on rules. it's giving decision tree couture. 💅

🎀 Data Input Format 🎀

Data input formats are plain-text and made to be as simple as possible. 🍓

that's it. that's the whole section. simple, like it promised. iconic. 💜

🧚 Is it right for you? 🧚

real talk, no cap:

Circos is not a solution. It's a tool to solve visualization problems. For a given problem, you are not guaranteed that Circos is appropriate. 💀

it's not gonna fix your life bestie, it's gonna draw you a circle. know the difference. 🫶

🎀 CONFIGURATION 🎀

Okay bestie, this is the moment. The configuration file is a plain-text file that defines a hierarchy of parameters, and it controls how images get made. Like, it's the blueprint. These files decide which files Circos pulls in for input data, how that data shows up, the layout and formatting of everything in the image, plus the system-level parameters that run the low-level machinery underneath. 👑

✨ Syntax ✨

Configuration is plain-text and it's built out of hierarchical blocks. Some blocks are literally mandatory (hi, <ideogram">), and some are optional (heyyy <backgrounds">).

To get started, go read the quick guide tutorial, no cap:

<http://www.circos.ca/documentation/tutorials/quick_guide>

A typical configuration file might look, like, exactly like this:

 # chromosome name and length definitions
 karyotype = myfile.txt

 # image size and format
 <image>
  ...
 </image>

 # position and size of ideograms
 <ideogram>
  ...
 </ideogram>

 # frequency, position and labeling of tick marks
 <ticks>
  ...
 </ticks>

 # position, type and format of data tracks
 <plots>
  <plot>
    ...
   # run-time rules to change data format and visibility
    <rules>
      <rule>
       ...
      </rule>
      ...
     </rules>
  </plot>
  ...
 </plots>

 # colors, fonts and fill patterns
 <<include colors_fonts_patterns.conf>>

 # system parameters
 <<include housekeeping.conf>>

🦋 Modularity 🦋

You can include the configuration from one file inside another, which makes for a truly modular setup. Like if a single project makes a bunch of different kinds of images, you can have project-wide config definitions that then get complemented — and possibly overwritten — by image-specific config. Chef's kiss. 💅

The <<include FILE>> directive imports one configuration file into another.

 # circos.conf
 <<include ideogram.conf>>

 # ideogram.conf
 <<include ideogram.label.conf>>
 <<include ideogram.size.conf>>
 ...

So in the tutorials you'll notice the <ideogram"> and <ticks"> blocks get imported into the main configuration file. Because those blocks can get huge, the main config file stays way more legible if you relegate them to their own separate files.

Parameter definitions that don't change much — color definitions, font definitions, the classics — are conventionally imported from files living in etc/ in the distribution. Every Circos image should have:

 # image size, output file name
 <image>
 <<include image.conf>>
 </image>
 # color names and lists, location of fonts, fill patterns
 <<include colors_fonts_patterns.conf>>
 # low-level system parameters
 <<include housekeeping.conf>>

💖 Overriding with * 💖

So if you want to override a parameter that got pulled in from a file, you use the * suffix. And yes the suffix is required, because multiple definitions of a parameter are not allowed — except in the cases where a parameter can have more than one value. Rules are rules.

 <image>
 # included file defines 'radius'
 <<include image.conf>>
 # this will override the radius value
 radius* = 2500p
 </image>

And the * suffix can be repeated to specify which value takes precedence in a block:

 radius   = 1500p
 radius*  = 2500p
 radius** = 3000p # this instance of radius will be used

🌸 Overriding with Command Line 🌸

Any configuration parameter in a unique block name can be specified right on the command line, like this:

 -param PATH/PARAM=value

For example:

 <ideogram>
   show = no
   ...
 </ideogram>

 -param ideogram/show=no

and:

 <ideogram>
   <spacing>
     default = 0.01r
   </spacing>
   ...
 </ideogram>

 -param ideogram/spacing/default=0.01r

⭐ Accessing Parameters ⭐

The conf() function gets used in the configuration file to retrieve the value of a parameter. And it can retrieve any parameter, not just the ones you set with -param. So it's a super flexible system for changing your configuration straight from the command line.

For example, here the karyotype file name will change as the species parameter changes — either in the config file or via the -param flag. And same vibe for the color palette size and name.

 # circos.conf
 species    = human
 palette    = blues
 num_colors = 9
 karytotype = data/karyotype/karyotype.conf(species).txt
 ...
 <plots>
  color     = conf(palette)-seq-conf(num_colors)
  ...

 > circos ... -param species=rat -param palette=reds -param num_colors=5

Multiple parameters can be redefined, each with its own -param flag:

 -param show_ticks=no -param image/radius=2000p

🌈 Merging Blocks 🌈

Multiple instances of these blocks get automatically merged: <ideogram">, <colors">, <fonts">, <paterns">, <image">, <links">, <plots"> and <highlights">.

The whole point of this is so you can add to canonical definitions. Big fan.

 # this file defines default <colors>, <fonts> and <patterns>
 <<include colors_fonts_patterns.conf>>

 # add to the colors block
 <colors>
 mycolor = 150,25,25
 </colors>

🧚 Absolute and Relative Paths 🧚

Using absolute paths in a configuration file? Discouraged. Like, strongly. Doing that makes your configuration less modular and literally unuseable on another system. 💀

For example, if Joe's files are organized like this:

 /user/joe/project/
                   data/genes.txt
                   etc/circos.conf

he could use:

 file = /user/joe/project/data/genes.txt

and run Circos from his home directory:

 > cd ~
 > circos -conf project/etc/circos.conf

But it would be much better for him to define:

 file = data/genes.txt

and run Circos from the project/ directory:

 > cd ~/project
 > circos

Now, if he makes a tarball of all the project files (like project.tgz), anyone could use those files by executing exactly the same commands. That's the dream, fr fr.

When you define a file with a relative path, such as:

 file = data/genes.txt

Circos will look for that file relative to several reasonable start points — like the location of the configuration file you're using, one level up from the config location, your current directory, and so on.

To see where Circos is searching for files, use:

 > circos -debug_group io

This is the same mechanism used to find the initial configuration file. So if you run Circos without the -conf flag:

 > cd ~/project
 > circos

then Circos will look for:

 ~/project/circos.conf
 ~/project/etc/circos.conf
 ~/project/data/circos.conf
 ~/project/../circos.conf
 ~/project/../etc/circos.conf
 ...

If the configuration file cannot be found, Circos will default to looking into its distribution directory.

Users who are unaware of this feature often manage to get away with unorganized project files because of this automatic file search. The purpose of this feature is to make your life easier when you know what you're doing — not necessarily to make it possible when you don't know what you're doing. 😭

If you want to redefine the search paths, see the data_path parameter in etc/housekeeping.conf in the distribution directory, or override it in your configuration file:

 <<include housekeeping.conf>>
 data_path* = ...

🔥 OPTIONS 🔥

Configuration

  • -configfile FILE — Name of configuration file. This one is required, bestie. Circos will attempt to guess the location of this file, searching for circos.conf in ., .., and ../... Described above, iykyk.

Output Format

  • -png, -nopng — Toggles output of PNG files.
  • -svg, -nosvg — Toggles output of SVG files.

Image Elements

  • -show_ticks, -noshow_ticks — Override the display of ticks.
  • -show_tick_labels, -noshow_tick_labels — Override the display of tick labels. Both of these are usually defined in the <ticks> block.

These flags are shortcuts to:

 -param show_ticks=no
 -param show_tick_labels=no

Output Paths

  • -outputdir DIR, -dir DIR — Change the output directory.
  • -outputfile FILE, -file FILE — Change the output filename. The FILE can contain a path.

Debugging

  • -debug — Turn on basic debugging output. Reports information from these debug groups (see below):
 image, io, layer, summary, timer
  • -debug_group {+-}GROUP1,[{+-}GROUP2,...] — Turn on debugging output for specific groups. For a list of groups, see:

<http://www.circos.ca/documentation/tutorials/configuration/debugging>

To add a group to the output, prefix it with +. To remove it, use -.

 # use default debugging groups but exclude layer and io
 -debug -debug_group -layer,-io

 # use default debugging groups and add spacing
 -debug -debug_group +spacing

 # explicitly specify the groups
 -debug_group png,io,timer

To list the groups that are supported, use the flag without an argument:

 -debug_group

Those listed with a * are turned on by default. To change that, adjust debug_group in etc/housekeeping.conf in the distribution directory.

  • -time — Report timing information. Same as -debug_group +timer.
  • -silent — Generate no reporting.
  • -paranoid, -noparanoid — Run in paranoid mode (default), or not. The default for this setting is defined by paranoid in etc/housekeeping.conf.
  • -warnings, -nowarnings — Display warnings, or not (default). The default for this setting is defined by warnings in etc/housekeeping.conf.
  • -fakeerror, -fakeerror CAT, -fakeerror ,ID, -fakeerror CAT,ID — Fake an error by displaying the error message for category CAT and error name ID. If one or neither are specified, lists which errors are available.
Unless you truly enjoy seeing error messages, there should be little reason for you to want to use this. 🙈

Usage

  • -version — Show the version.
  • -help — Show brief usage synopsis.
  • -man — Show man page.

Goofing Around

  • -randomcolor [color1,color2,...] — Randomize the color of every element in the image, except for an optional list of colors.

For example, to keep the background white and anything that is black:

 -randomcolor white,black

📚 DOCUMENTATION 📚

For full documentation, see:

<http://www.circos.ca/documentation/tutorials>

👑 AUTHOR 👑

Martin Krzywinski martink@bcgsc.ca <http://mkweb.bcgsc.ca> @MKrzywinski

Canada's Michael Smith Genome Sciences Centre 100-570 W 7th Ave Vancouver BC V5Z 4S6 Canada

<http://www.bcgsc.ca>

💜 RESOURCES 💜

<http://www.circos.ca>

<https://groups.google.com/forum/#!forum/circos-data-visualization>

🎀 CITING 🎀

okay bestie, real talk — if you use Circos in a publication, you gotta cite it. That's just the rules of the game, no cap. Cite it like this:

Krzywinski, M., J. Schein, I. Birol, J. Connors, R. Gascoyne, D.
Horsman, S. Jones, and M. Marra. 2009. Circos: an Information Aesthetic
for Comparative Genomics. Genome Res 19:1639-1645.

Give the people their credit, it's the least you can do 💖

👑 CONTRIBUTORS 👑

shoutout to the people who helped make this happen:

  • Ken Youens-Clark kyclark@gmail.com — icon behavior, honestly 🫶

🌈 SEE ALSO 🌈

Other stuff you might be obsessed with:

okay so legal stuff, but it's important so don't skip it:

Copyright 2004-2017 Martin Krzywinski, all rights reserved.

This script is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. Slay, freedom of software ✨

This script is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. (Translation: it's free, but if it breaks, that's on you bestie 😭)

You should have received a copy of the GNU General Public License along with this script; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 📬

ngl the way this page is dated 2020-06-08 and running on perl v5.30.3? it's giving vintage but make it iconic 💅 and the whole thing is literally the CIRCOS(1) page, section 1, like it always was 🦋✨ bye bestie, go make some gorgeous circles 🌸
📦 where this page comes from