Circos > Software > Readme
Loading
Circos at the EMBO NGS workshop in Tunis, Sept 15–25.

The terrifying dinosaur corn genome

Amblin Entertainment and Legendary Pictures, the studios that produced Jurrasic World, try to inject genome science into the movie. Unfortunately, since we don't quite know how to construct viable genomes of extinct species, much less grow the creatures themselves, we don't know whether the depiction of the science is right. Perhaps theirs is exactly what a genome lab would look like in a dino-building facility.

But, we can get fewer things wrong. In the Creation Lab companion website, a Circos image is used to illustrate a triceratops genome.

Unfortunately, this is an image of the B73 Maize reference genome (B73 RefGen_v1), as published in Nature's The B73 Maize Genome: Complexity, Diversity, and Dynamics.

Schnable PS Ware D Fulton RS et al. 2009 The B73 maize genome: complexity, diversity, and dynamics Science 326 (5956) 1112-1115

Using News Reports to Track Wildlife Black Markets

http://www.wired.com/2015/06/using-news-reports-track-wildlife-black-markets/

THE INTERNATIONAL BLACK market in wildlife—alive or dead—is notoriously difficult to track. Hunters and smugglers don’t report their take for the same reasons that drug dealers don’t report profits to the IRS. But if you could actually track those networks, maybe you could do something about them. That’s what sent Nikkita Patel, a veterinary epidemiologist at the University of Pennsylvania, to an unusual source of data on the illegal wildlife trade: the news.

Wired

The image shows the illegal global rhinoceros trade network before (top) and after (bottom) a hypothetical targeted disruption. Created with Circos online table viewer.

Circos Maps America’s Restless Interstate Migration Without a Map

Wired has a writeup about migration patterns within the US that shows the data using d3.js chord diagrams, modeled after how Circos shows tabular data.

Circos reaches 500 literature citations

In October 2013 Circos reached a milestone - 500 citations in peer-reviewed literature.

To celebrate, I've made a commemorative poster that features over 400 Circos images from the literature.

citation list | image gallery | press highlights

Circos for R

Zhang et al. implement Circos in R.

Same round shape you expect. And now, in everyone's favourite open source statistics and data analysis environment.

CRAN RCircos package

Zhang H, Meltzer P, Davis S 2013 RCircos: an R package for Circos 2D track plots BMC Bioinformatics 14:244.

Circos Interchange Diagrams — Networks and Flow

Zeng et al. introduce a new type of visualization based on Circos, the interchange diagram, in their paper Visualizing Interchange Patterns in Massive Movement Data.

The design is applied to displaying movement data, such as daily trips made by passengers in a city. By incorporating interactivity, this visualization method is helpful to understand interchange patterns at different spatial (between trains, between cities) and time scales (different times of day).

Circos has been used for urban planning before. The town of Caceres in Spain has used Circos to communicate their urban planning strategy.

project website

Zeng W, Fu C-W, Arisona SM et al. 2013 Visualizing Interchange Patterns in Massive Movement Data Computer Graphics Forum 32:271-280

Circos connects to the connectome

Methods to visualize the connectome are reviewed in Craddock et al — Circos is one of them.

Craddock RC, Jbabdi S, Yan C-G et al. 2013 Imaging human connectomes at the macroscale Nat Meth 10:524-539.

The use of Circos for showing the connectome was introduced by Irimia et al. in Circular representation of human cortical networks for subject and population-level connectomic visualization.

A good layman description of the work can be found at the neurosceptic blog.

Irimia A, Chambers MC, Torgerson CM et al. 2012 Circular representation of human cortical networks for subject and population-level connectomic visualization NeuroImage, Irimia A, Chambers MC, Torgerson CM et al. 2012 Patient-tailored connectomics visualization for the assessment of white matter atrophy in traumatic brain injury Frontiers in Neurology 3

Circos is the Method for Visualizing Translocations

Genomic rearrangements can cause disease and are implicated in many cancers. Being able to see the patterns in these changes across samples and patients is important.

In the review article End-joining, Translocations and Cancer, Bunting and Nussenzweig demonstrate how compositing the genome circularly adds value and clarity to the presentation.

Bunting SF, Nussenzweig A 2013 End-joining, translocations and cancer Nat Rev Cancer

From Degree to Job — Circos Visualizes Workforce Transitions

Finding the relationship between a student's major and career field is the topic of "Measuring Transitions Into The Workforce As A Form Of Accountability". The diagrams connect the flow of students from one of 17 fields of study (left) to job sectors (right).

Schenk TL, Jr. 2011 Measuring Transitions into the Workforce as a Form of Accountability SSRN eLibrary ID 1831967

Satyan L Devadoss from Williams College performed a similar analysis of Impact of Major on Career Path for 15600 Williams College Alums.

Circos tackles the connectome

Irimia et al. introduce circular representation of cortical networks in Circular representation of human cortical networks for subject and population-level connectomic visualization. The scalability of this circular visualization approach is demonstrated by lucid aggregate visualizations using cortical networks of 50 individuals.

The UCLA group also used the circular connectome visualization to assess differences in brain injury in patients Patient-tailored connectomics visualization for the assessment of white matter atrophy in traumatic brain injury in Frontiers in Neurotrauma.

A good layman description of the work can be found at the neurosceptic blog.

Irimia A, Chambers MC, Torgerson CM et al. 2012 Circular representation of human cortical networks for subject and population-level connectomic visualization NeuroImage, Irimia A, Chambers MC, Torgerson CM et al. 2012 Patient-tailored connectomics visualization for the assessment of white matter atrophy in traumatic brain injury Frontiers in Neurology 3

Hemolytic–Uremic Syndrome Outbreak

Rasko et al. use Circos to show how the E. coli strain implicated in the German outbreak of hemolytic-uremic syndrome varies from other strains in their New England Journal of Medicine paper, where they find that "the genome of the German outbreak strain can be distinguished from those of other O104:H4 strains because it contains a prophage encoding Shiga toxin 2 and a distinct set of additional virulence and antibiotic-resistance factors."

NEJM created an animation that explains the visualizations. The paper was blogged by Pacific Biosciences.

Rasko DA, Webster DR, Sahl JW et al. 2011 Origins of the E. coli Strain Causing an Outbreak of Hemolytic-Uremic Syndrome in Germany The New England journal of medicine published ahead of print:-.

Circos Maps Cancer Landscapes

Nature features an article by Heidi Ledford, The Cancer Genome Challenge, which discusses the progress and challenges of identifying structural variation signatures in cancer genomes.

Circos images are used throughout the piece, taken from the COSMIC project (Catalogue of Somatic Mutations in Cancer).

Ledford H 2010 Big science: The cancer genome challenge Nature 464 (7291) 972-974.

Linux kernel exploration

Răzvan Musăloiu-E. explored the Linux file system and used Circos to relate the systems (disk-based, optical mediums, flash-based, network-based, cluster-based, memory-based, ancient) to kernel symbols.

Circular Worle

Jonathan Feinberg (IBM) created this perfectly circular wordle for me, using content from the Circos site.

As far as I know, this is the only circular wordle.

Circos Citation Themes

A wordle created from the words of the over 100 scientific articles that cite Circos.

All Your Genes Are Belong To Us

Remembering one of the most viral internet memes.

Circos is catching on, too.

Circos at VIZBI 2011

Circos was one of the community visualization tool tutorials at VIZBI 2011, at the Broad Institute in Boston.

Circos Helps with Urban Planning

The town of Caceres, Spain, a UNESCO World Heritage Site, used Circos to illustrate the relationships between businesses in their urban planning strategy.

Hive Plots - Linear Layout for Network Visualization

Visualizing large networks is hard. Nobody wants to see another hairball, but you want to show your data.

What do you do?

Try our new linear layout for network visualization, introducing the hive plot. This plot takes a fresh approach to drawing networks. It scales well, shows topology, and makes the network layout based on meaningful properties.

Power of Round

Circular data tracks naturally support display of information at various resolutions.

Compared to a track at a radius r, a pixel in a track at r/4 will span a region 4x larger. Tracks in the interior of the figure are therefore useful to display low-resolution or summary information.

Circos Introduced in the New York Times

My first Circos infographic to be published in the New York Times introduces the idea of sequence similarity curves linking circularly composed ideograms.

Working with David Constantine, I illustrated the similarity between chromosome 1 of mouse, rhesus, chimp, and chicken to that of human.

One of the smaller panels in the infographic was subsequently used by the Alliance of Lupus Research in their Faces of Lupus II video.

NYT Article - Mapping the Epigenome

In collaboration with Jonathan Corum from the NYT, Martin Krzywinski created an illustration of data showing methylation on chromosome 22 in a variety of tissues.

The illustration accompanies the article Now: The Rest of the Genome, by Carl Zimmer.

Circos README


################################################################

Circos - flexible and automatable circular data visualization

Martin Krzywinski
Canada's Michael Smith Genome Sciences Center
British Columbia Cancer Agency

martink@bcgsc.ca
www.circos.ca

################################################################

0. INTRODUCTION
   0.a   what is circos?
   0.b   requirements

1. GETTING STARTED
   1.a   installation 
   1.b   executing scripts
   1.c   testing GD
   1.d   tools
   1.e   batch files
   1.f   configuration files

2. BUGS
   2.a 	 report bugs and comments
   2.b   known issues

3. INSTALLATION PROBLEMS
   3.a   missing modules

4. OTHER ISSUES
   4.a   configuration paths
   4.b   typical errors and how to fix them
   4.b.1 numerical parameter units

################################################################

0. INTRODUCTION

0.a  What is circos?

Circos is a program for the generation of publication-quality,
circularly composited renditions of genomic data and related
annotations.

Circos is particularly suited for visualizing alignments, conservation
and intra and inter-chromosomal relationships.

But wait. Also, Circos is useful to visualize any type of information
that benefits from a circular layout. Thus, although it has been
designed for the field of genomics, it is sufficiently flexible to be
used in other data domains.

0.b  Requirements

Perl 5.8.x, or newer, is highly recommended. In addition to the core
modules that come with your Perl distribution, some CPAN modules are required.

On UNIX systems, for a list of modules required by Circos, run

> cd bin
> ./list.modules

On UNIX systems, to test whether you have these modules, run

> cd bin
> ./test.modules

Circos supports TTF fonts. A few fonts are included in fonts/.

UNIX users likely do not need to install perl on their systems, since it is commonly included by default. Windows users on the other hand usually do not have Perl and need to install it - Strawberry Perl or ActiveState Perl.

  http://strawberryperl.com
  http://www.activestate.com/activeperl

Both Windows Perl distributions have their own module manager that make it easy to install, update and remove modules.
1. GETTING STARTED

Refer to online tutorials for installation, configuration and troubleshooting

  http://www.circos.ca/documentation/tutorials/configuration/

1.a  Installation

On UNIX systems, use 'tar' to extract the files.

> tar xvfz circos-x.xx.tgz
> cd circos-x.xx

On Windows, use an archiver like WinZip or WinRAR or Window's built-in
support for Zip files.

You don't need to move or edit any files in the main distribution.

1.b  Executing Scripts

Circos is written in Perl, which is an interpreted language. This
means that the program files are plain-text and are passed through the
Perl interpreter in order to run.

On UNIX systems, to run the scripts you simply need to make sure that
the files are executable (they should be already)

> chmod +x bin/circos

after which you can execute them directly

> bin/circos 

The association between the bin/circos script and perl is created by
the first line in the script]

#!/bin/env perl

which instructs the shell to run the perl binary and provide the
script as input. See notes on /bin/env below.

On Windows, you'll also want to work from the command line (DOS
window), but you'll need to call perl explicitly. Once you've
installed a Perl distribution, like Strawberry Perl or ActiveState
Perl, you should be able to run the interpreter which has been placed
in your PATH by the installation process.

C:>perl -V
...information about version of perl

To run Circos, 

C:>perl C:\path\to\circos\bin\circos [any command-line parameters]

Anytime you see instruction to run a script, such as

> tools/bin/binlinks ...

substitute instead

C:>perl tools\bin\binlinks ...

Also note that on UNIX file paths use "/" as a separation
(e.g. /bin/env) and on Windows "\" is used (e.g. C:\perl\bin\perl).

1.c  Testing GD

To test your GD installation to make sure your Perl distribution can
create graphics and handle True Type fonts.

> bin/gddiag

Look at the created gddiag.png. It should look like this

  http://www.circos.ca/documentation/tutorials/configuration/png_output/images

If you don't see any text, see 4.b.2 below.

If you get an error like

-bash: /bin/env: No such file or directory

then your 'env' binary is likely in /usr/bin (e.g. on Mac OS X) Check this by 

> which env
/usr/bin/env

To fix this, either change the first line in scripts in bin/* and tools/*/bin to 

#!/usr/bin/env perl

or make a symlink from /usr/bin/env to /bin/env

> sudo su
> cd /bin
> ln -s /usr/bin/env env

Now try creating the example image

> cd circos-x.xx
> cd example
> ../bin/circos -conf etc/circos.conf

To get some verbose reporting about file I/O , use 

> ../bin/circos -conf etc/circos.conf -debug_group io,summary

Please see L<http://www.circos.ca> for documentation. There are a
large number of tutorials that described how the configuration files
are formatted. Tutorials need to be downloaded separately.

1.d  Tools

There are several helper scripts, available separately, that are designed
to aid you in processing your data.

Many of these involve manipulating link files. These tools independent
scripts and are covered in Tutorial 9.

  http://www.circos.ca/documentation/tutorials/utilities

The tools can be downloaded independently. Note that the stand-alone
tools distribution may contain scripts that are newer than those
bundled with Circos. To check this, look at the release date for the
archives at L<http://www.circos.ca/software/download>.

1.e Batch Files

There may be batch files scattered throughout the data/ and tutorial/
directories. These files begin with

#!/bin/bash

and are designed for use in UNIX environments.

1.f Configuration files

Central configuration files with global parameters are found in
etc/. See etc/README for details about the contents of this file and
how the <<include>> directive is used to link them.

For a full explanation of the configuration system, see

  http://www.circos.ca/documentation/tutorials/configuration/configuration_files
2. BUGS

2.a  Report bugs and comments

I appreciate any and all comments you may have about Circos. Please
use the Google Group for questions and bug reports.

  http://groups.google.com/group/circos-data-visualization

2.b  Known issues

GD does not draw rotated text correctly when the font size is small
for certain fonts. For example, using a font size of 6pt, text drawn
an an angle is drawn with letters upright. If you see this, increase
the font size of the text.

Fonts with which this problem occurs are

  CMUBright-Roman
  CMUTypewriter-Regular

For this reason, TTF versions of these fonts are used, rather than OTF.

3. INSTALLATION PROBLEMS

3.a  Missing modules

  http://www.circos.ca/documentation/tutorials/configuration/perl_and_modules/

In order to run Circos you may need to install some modules from CPAN
(www.cpan.org). You will need the modules listed at L<http://www.circos.ca/software/requirements>.

If you run Circos and get a message like

Can't locate Config/General.pm in @INC (@INC contains: /usr/lib/perl5/5.8.0/i386-linux
-thread-multi /usr/lib/perl5/5.8.0 /usr/lib/perl5/site_perl/5.8.0/i386-linux-thread-mu
lti /usr/lib/perl5/site_perl/5.8.0 /usr/lib/perl5/site_perl /usr/lib/perl5/vendor_perl
/5.8.0/i386-linux-thread-multi /usr/lib/perl5/vendor_perl/5.8.0 /usr/lib/perl5/vendor_
perl .) at ./bin/circos line 121.

then you do not have a module installed. It may be that you have the module elsewhere,
but Perl cannot find it. In this case, the error message is barking at the fact that
Config::General is not installed.

You can install the module using CPAN (if CPAN module is installed)

> perl -MCPAN -e shell
% install Config::General

Make sure that you are using the same perl binary to install the module as for Circos.

Alternatively, you can grab the module from CPAN directly. Use search.cpan.org to find
the module.

> wget http://search.cpan.org/~tlinden/Config-General-2.31/General.pm
> tar xvfz Config-General-x.xx.tgz
> cd Config-General-x.xx.tgz
> perl Makefile.PL ; make ; make test
> make install

If you are getting 'permission denied' errors during installation of
the module, then you're likely attempting to write into your system's
default Perl install, and don't have permission to do so. To fix this,
repeat the module installation as root (administrator).

> sudo su
> perl -MCPAN -e shell
...
4. OTHER ISSUES

4.a  Configuration paths

If you look inside one of the configuration files you'll find
that it includes other configuration files using <<include>> and
makes relative mention of data files, such as

  file = data/5/segdup.txt

Circos tries to find the file regardless where you are running the binary from, but 
may still run into trouble finding files specified using a relative path.

To avoid problems, run circos from its distribution directory

> cd circos-x.xxx
> bin/circos -conf ...

Alternative, change all the paths in the .conf file to absolute paths. For example, from

  <<include etc/colors.conf>>

to

  <<include /path/to/your/install/circos-x.xx/etc/colors.conf>>

For details about the configuration files, see etc/README and

  http://www.circos.ca/documentation/tutorials/configuration/configuration_files

4.b  Typical errors and how to fix them

4.b.1 Dealing with errors

  http://www.circos.ca/documentation/tutorials/configuration/errors

4.b.2 No text in figures

If Circos is creating images, but without any text (ideogram labels,
tick labels, etc), it is almost certain that your GD Perl module was
compiled without True Type support.

See the note about gddiag above.

This may be due to the fact that you don't have the True Type library
on your system (freetype), or a configuration error during GD
installation.

You'll need to reinstall GD.

  http://search.cpan.org/dist/GD/

This issue comes up a lot. Circos has this to say about it

circos -fake font,ttf

and many threads about it have been created on the message boards

  http://groups.google.com/group/circos-data-visualization/browse_thread/thread/c893b8b612c2c5cf
README HISTORY

2013 Feb 12 - standardized URLs for /documentation/tutorials

2012 Feb 20 - added link to thread about TTF support and a command to fake TTF font error

2012 Feb 5 - modified note on errors, added reference to external tutorials

2011 Jul 25 - split Circos, tutorials and tools into separate archives

2011 Jun 04 - started keeping track of history

2011 Jul 07 - updated links to ciros.ca