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.
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.
Having trouble with libgd and GD? See the Perl Monks libgd/GD Tutorial, Shaun Jackman's Homebrew formula, 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.
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.
To run Circos, you need Perl. Perl is an interpreted language, which means that you do not need to compile Circos to run it. The code is read in by the Perl executable, which takes care of interpreting, compiling and running it. To install Circos, nothing other than unpacking the archive is required.
For an overview of the installation process, and how it differs between UNIX and Windows, please also refer to the UNIX vs Windows section.
First, download Circos. The contents of the distribution are described below.
You don't need to move or edit any files in the main distribution.
Assuming that you want to install in
> cd ~ > mkdir software > mkdir software/circos > cd software/circos # download Circos and place the archive in the directory > ls -rw-r--r-- 1 martink users 26725778 Jun 6 11:04 circos-0.67-pre4.tgz # unpack > tar xvfz circos-0.67-pre4.tgz ... circos-0.67-pre4/data/karyotype/karyotype.arabidopsis.txt circos-0.67-pre4/data/karyotype/karyotype.zeamays.txt circos-0.67-pre4/data/karyotype/karyotype.oryzasativa.txt # make a symlink to current > ln -s circos-0.67-pre4 current > ls drwxr-xr-x 10 martink users 4096 Jun 6 11:06 circos-0.67-pre4/ -rw-r--r-- 1 martink users 26725778 Jun 6 11:04 circos-0.67-pre4.tgz lrwxrwxrwx 1 martink users 16 Jun 6 11:07 current -> circos-0.67-pre4/ # delete the tarball, if you want
To install GD and Perl modules on Ubuntu, use
sudo apt-get -y install libgd2-xpm-dev
If you're using Homebrew, you can use Shaun Jackman's formula
brew tap homebrew/science brew remove gd brew install gd --with-freetype brew install cpanminus sudo chown "$USER":admin /Library/Perl/5.16 # on Mac OS cpanm Config::General Font::TTF::Font Math::Bezier Math::VecStat Readonly Set::IntSpan Text::Format cpanm --force GD::Polyline brew install circos brew test circos
Thanks to Paul Nuin for this section. It references an older version of Circos, but the process is the same for newer versions.
This short tutorial gives a step-by-step overview on how to make Circos work on OS X, but it should be similar to other *nix flavours. I just installed on my Mountain Lion box, but, again, it should be identical to previous versions of OS X.
Assume Circos has been installed to
/Applications/circos-0.55/. If you run it and get
$ perl /Applications/circos-0.55/bin/circos Can't locate Config/General.pm in @INC (@INC contains: /Applications/circos-0.55/bin/lib /Applications/circos-0.55/bin/../lib /Applications/circos-0.55/bin /Library/Perl/5.12/darwin-thread-multi-2level /Library/Perl/5.12 /Network/Library/Perl/5.12/darwin-thread-multi-2level /Network/Library/Perl/5.12 /Library/Perl/Updates/5.12.4/darwin-thread-multi-2level /Library/Perl/Updates/5.12.4 /System/Library/Perl/5.12/darwin-thread-multi-2level /System/Library/Perl/5.12 /System/Library/Perl/Extras/5.12/darwin-thread-multi-2level /System/Library/Perl/Extras/5.12 .) at /Applications/circos-0.55/bin/../lib/Circos.pm line 53. BEGIN failed--compilation aborted at /Applications/circos-0.55/bin/../lib/Circos.pm line 53. Compilation failed in require at /Applications/circos-0.55/bin/circos line 184. BEGIN failed--compilation aborted at /Applications/circos-0.55/bin/circos line 184. So, a lot of things going wrong, we need to check what is missing and install. Circos has a couple of commands bundled in its package that help us working through the errors. Best way to run them is to cd into Circos bin directory
then you are missing the Config::General module and possibly other modules.
$ cd /Applications/circos-0.55/bin/ /Applications/circos-0.55/bin$ ./list.modules In my case, running this script gave me a list of the required modules for Circos Circos requirements Carp Config::General Data::Dumper Digest::MD5 File::Basename File::Spec::Functions FindBin GD GD::Polyline Getopt::Long Graphics::ColorObject IO::File List::MoreUtils List::Util Math::Bezier Math::BigFloat Math::Round Math::VecStat Memoize POSIX Params::Validate Pod::Usage Readonly Regexp::Common Set::IntSpan Storable Time::HiRes
Another script checks for the current status of each module (still from the same dir)
/Applications/circos-0.55/bin$ ./test.modules Circos: requirements ok Carp fail Config::General is not usable (it or a sub-module is missing) ok Data::Dumper ok Digest::MD5 ok File::Basename ok File::Spec::Functions ok FindBin fail GD is not usable (it or a sub-module is missing) fail GD::Polyline is not usable (it or a sub-module is missing) ok Getopt::Long fail Graphics::ColorObject is not usable (it or a sub-module is missing) ok IO::File ok List::MoreUtils ok List::Util fail Math::Bezier is not usable (it or a sub-module is missing) ok Math::BigFloat ok Math::Round fail Math::VecStat is not usable (it or a sub-module is missing) ok Memoize ok POSIX ok Params::Validate ok Pod::Usage fail Readonly is not usable (it or a sub-module is missing) ok Regexp::Common fail Set::IntSpan is not usable (it or a sub-module is missing) ok Storable ok Time::HiRes
We have to address everything that failed in the test. In this case,
Set::IntSpan. We leave GD behind for a moment and focus on the other modules (this list might vary for each Perl installation, so you might need to install more or less modules, but the commands are similar).
The easiest way to install module in Perl is to use CPAN, the repository of Perl modules. It has an interactive shell that we can use, and we will see how to do that. In order to make sure our installation works we use sudo and call cpan (from any directory)
$ sudo cpan If this is the first time you are running it, just answer yes to all config questions and you are good to go. Now we have to install the five modules required. By using the command install, that can be achieved cpan$ install Config::General -output omitted- cpan$ install Graphics::ColorObject -output omitted- cpan$ install Math::Bezier -output omitted- cpan$ install Math::VecStat -output omitted- cpan$ install Readonly -output omitted- cpan$ install Set::IntSpan -output omitted-
Now, we deal with the last module and usually the most labourious to install,
GD. Ideally you should have all possible library support for
GD and for this you have to install additional libraries. We are going to start with two of the most common and see if we need anything else. Usually
libpng are required by
GD. So, let’s download both of them
$ mkdir srctemp $ cd srctemp srctemp$ curl -O http://www.ijg.org/files/jpegsrc.v8d.tar.gz srctemp$ tar -xzvf jpegsrc.v8d.tar.gz srctemp$ cd jpeg-8d srctemp/jpeg-8d$ ./configure srctemp/jpeg-8d$ make srctemp/jpeg-8d$ sudo make install srctemp/jpeg-8d$ cd .. srctemp$ curl -O ftp://ftp.simplesystems.org/pub/libpng/png/src/libpng-1.5.10.tar.gz srctemp$ tar -xzvf libpng-1.5.10.tar.gz srctemp$ cd libpng-1.5.10 srctemp/libpng-1.5.10$ ./configure srctemp/libpng-1.5.10$ make srctemp/libpng-1.5.10$ sudo make install
That should do it for now. We will download
GD and check if the configuration we have so far is enough. GD’s website is still down, but we can get the source from Bitbucket and use identical commands to install is
srctemp$ curl -O https://bitbucket.org/pierrejoye/gd-libgd/get/GD_2_0_33.tar.gz srctemp$ tar -xzvf GD_2_0_33.tar.gz srctemp$ cd pierrejoye-gd-libgd-5551f61978e3/src srctemp/pierrejoye-gd-libgd-5551f61978e3/src$ ./configure
At the end of the configuration run, you should see something like this
** Configuration summary for gd 2.0.33: Support for PNG library: yes Support for JPEG library: yes Support for Freetype 2.x library: yes Support for Fontconfig library: yes Support for Xpm library: no Support for pthreads: yes
In my case, I’m good to go. But if in your case
Fontconfig are missing, you would have to download, configure, make and install them, just like
libjpeg. So now
srctemp/pierrejoye-gd-libgd-5551f61978e3/src$ make srctemp/pierrejoye-gd-libgd-5551f61978e3/src$ sudo make install
We are almost there. The last step is to install
GD in Perl. Normally, if we use cpan to install it on OS X, it fails. So, we will have to do it by hand. We go to CPAN website and download the latest Perl’s GD implementation and with similar commands to above we install it.
srctemp$ curl -O http://search.cpan.org/CPAN/authors/id/L/LD/LDS/GD-2.46.tar.gz (if curl fails copy and past on your browser) srctemp$ tar -xzvf GD-2.46.tar.gz srctemp$ cd GD-2.46 srctemp/GD-2.46$ perl Makefile.PL srctemp/GD-2.46$ make srctemp/GD-2.46$ sudo make install
you should see some output, maybe some warnings, but if you followed all the steps above the installation worked. You can run the
test.modules script in order to check.
Windows users should use Windows' built-in handling of
.tgz files (in Windows Vista or newer). The
.tgz extension is a short version of
.tar.gz, which more explicitly indicates that the file is a
tar archive which has been subsequently compressed with
If you are unfamiliar with the Windows DOS command line, these tutorials should help.
Circos uses command-line flags, which are required. In the very least, you need to specify the image configuration file using
These flags in described in the Runtime Parameters tutorial.
It's a good idea to add the
bin/ directory in the distribution to your
PATH so that you can run
bin/circos from anywhere.
Assuming you have Circos in
ROOT=~/software/circos/current as described above, append this to your
You'll need to explicitly execute either
~/.bash_profile for this to take effect
> . ~/.bashrc # or > . ~/.bash_profile
Finally, test that your
PATH has been modified,
> cd ~ > echo $PATH ~/software/circos/current/bin: ... > which circos ~/software/circos/current/bin/circos
To run Circos, you'll need to invoke perl and pass the Circos script as an argument, along with any command-line parameters
C:>perl C:\path\to\circos\bin\circos [any command-line parameters]
Documentation uses UNIX paths and commands. On Windows, if you see instruction to run a script, such as
> tools/bin/binlinks ...
interpret it as
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.
References to command-line commands like
cat are specific to UNIX. It should be clear what is being attempted, such as reporting the current working directory (
echo %cd% on Windows) or listing a file (
echo on Windows).
Check whether you have any missing modules
> pwd ~/software/circos/current > bin/circos -modules ok 1.26 Carp ok 0.37 Clone ok 2.50 Config::General ok 3.33 Cwd ok 2.145 Data::Dumper ...
If any modules missing, refer to Perl Modules tutorial for details about installing them.
/bin/env: no such file or directory
On UNIX, if you see an error like this when you try to run Circos
-bash: /bin/env: No such file or directory
then the location of the
env binary on your system is not
/bin/env. For example, on Mac OS X
env is in
First check where your
env binary is
> which env /usr/bin/env
Now either change the first line in
or (better) make a symlink from
> sudo su > cd /bin > ln -s /usr/bin/env env
You should get a man page. On the other hand, if you get an error like
If you don't yet have any data to use, you can play with running Circos using the example data set, included in the distribution. The commands below are for UNIX systems—for Windows, see
> cd example # run.out will contain debug report # image files are circos.png and circos.svg > ./run # explicitly specify configuration file > ../bin/circos -conf etc/circos.conf # with more debugging > ../bin/circos -conf etc/circos.conf -debug_group summary,io,timer # with all debugging > ../bin/circos -conf etc/circos.conf -debug_group _all # silently > ../bin/circos -conf etc/circos.conf -silent
When you download and unpack Circos, you'll have a directory structure as follows
circos-x.xx CHANGES README TODO bin/ etc/ fonts/ lib/ tiles/ tools/
Tutorials are available separately and provide the files in
The Circos script is located in this directory. Circos is written
in Perl and is comprised of a single executable file
The distribution includes a large number of data files that are required by the tutorials. Most of these data files are parsed versions of output of the UCSC Genome Viewer Table Browser. A few of the data files contain randomly generated data.
Circos global configuration files live here, such as
fonts.conf. These files are imported into other configuration
files (e.g. tutorial configuration files).
The contents of the color and font files are described in the Configuration File section.
Tutorial configuration files are located in
TrueType (TTF) fonts used by Circos. These fonts are defined in
etc/fonts.conf. Circos supports only TTF fonts (not Postscript or OTF).
Code libraries. You don't need to look.
Tiles for pattern fills.
Various helper tools for Circos to manipulate (e.g. count links with
tools/binlinks) and parse (e.g. tabular visualization using
Tutorials are available separately and are the documentation
for Circos. Each tutorial has an associated image and configuration
Tutorials are organized into groups and sections. Each group illustrates a feature set of Circos, and individual sections illustrate the configuration syntax for specific aspects of the feature set.
tutorials/ ... 2/ 1/ 2/ circos.conf ticks.conf ideogram.conf 3/ ... ...
All of the tutorial configuration files will import global
configuration files from
etc/, such as