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, 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.
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.
Circos has been designed with an approach that should be familiar to UNIX users: no interface, plain-text configuration and command-line utilities. If you are a Windows user, this might seem a little unusual at first. The tutorials in this section that cover installation, configuration, and Perl modules discuss the differences between Circos usage on UNIX and Windows.
You do not need to know Perl to run Circos, but you do need to be familiar with
You'll be working entirely on the command-line and text editor in UNIX. Windows users unfamiliar with the DOS command-line should read the following tutorials
UNIX has Perl installed by default, and unless your system is ancient. To check your Perl version,
> perl -v
Anything earlier than 5.8 should be upgraded.
If you're a Windows user, it's likely that you're unfamiliar with Perl. There is nothing to fear—it is just like any other application you have installed. You'll need to use it from the DOS command-line and know only the basics which are covered in the two tutorials linked to above.
Where possible, use the manager to install modules instead of the CPAN shell. CPAN is the Comprehensive Perl Archive Network and hosts, among other things, Perl modules contributed by the community. Details of downloading and installing modules can be found in the Perl and Modules section.
On UNIX, you only need to unpack the Circos archive in a suitable location with
tar. For example,
> tar xvfz circos-0.67-pre4.tgz
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
Circos installation details are listed in the Distribution and Installation section.
For UNIX users the
bin/circos file is executable, so just run that. The first line of
which automatically uses the perl binary in your
PATH. If you don't have
/bin/env, it may be in
/bin/usr/env, such as on Mac OS X.
Windows users will need to run perl explicitly and use the circos script as the argument.
Windows won't know what to do with the
bin\circos file otherwise.
Windows file paths use
\as a directory separator, whereas UNIX
/. The UNIX convention is used throughout the tutorials.
Windows users should interpret paths like
Circos tutorials are included in a separate package which you will need to download.
Because the directory structure of UNIX and Windows is different, you may need to adjust the output directory for tutorial examples. For example, on UNIX
/tmp is used as a scratch directory (e.g. for creating temporary files). On Windows this directory does not exist.
You can overwrite the output directory and file defined in the configuration file using
-outputfile parameters. For more information about these and other parameters, see the Runtime Parameters tutorial.
# on Windows, executed from the Circos installation directory perl bin\circos -conf tutorials\2\2\circos.conf -outputdir . -outputfile tutorial_image.png
In some tools and tutorial directories you'll come across UNIX batch files that look something like this
# tools/tableviewer/makeimage #!/bin/bash ... cat samples/table-$n.txt | bin/parse-table -conf samples/parse-table-$n.conf | bin/make-conf -dir data ...
These are written in the BASH shell (a UNIX scripting language) and cannot be run directly on Windows (e.g. in a DOS window). To run these files you'll need to install a UNIX shell environment for Windows like Cygwin.