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.
1 — Configuration and Installation
1. UNIX vs Windows
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.
Try the Active State Perl build for Circos. It includes all the necessary modules.
Need to install modules? See A Guide to Installing Modules and its corresponding tutorial for Windows users.
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.
Need to run Bash shell batch files in Windows? You'll need to install a UNIX command line shell, like Cygwin.
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 or read through the Perl Journal archive.
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
- concept of directories and files
- navigating directories at the command prompt
- creating and deleting directories at the command prompt
- concept of absolute and relative paths (e.g.
/path/file.txtvs../file.txtvsfile.txt)
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
Perl Installation
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.
Windows users should install Strawberry Perl or ActiveState Perl. Both have package managers that help you install, update and remove modules.
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.
Circos Installation
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 gzip.
You can unpack the archive with 3rd party utilities like the free 7-Zip, or the venerable (but not free) WinZip.
Circos installation details are listed in the Distribution and Installation section.
Running Circos
For UNIX users the bin/circos file is executable, so just run that. The first line of bin/circos is
#!/bin/env perl
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.
perl bin\circos
Details about running Circos can be found in the Distribution and Installation section. Command-line flags that adjust run-time parameters are described in the Runtime Parameters tutorial.
path delimiter
Windows file paths use \as a directory separator, whereas UNIX
uses /. The UNIX convention is used throughout the tutorials.
Windows users should interpret paths like
tutorials/2/2/circos.conf
as
tutorials\2\2\circos.conf
Circos tutorials are included in a separate package which you will need to download.
Configuration
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 -outputdir and -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
Batch Files
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.