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

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