0 — Directory Structure and Configuration

1. UNIX vs Windows

UNIX vs Windows

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.

Circos has been designed with an approach familiar to UNIX users: no interface, plain-text configuration and command-line utilities. Windows users will find this at first unfamiliar, but relatively quickly to pick up. 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. 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.txt vs ../file.txt vs file.txt)

Windows users unfamiliar with the DOS command line should read these tutorials:

• Windows command line tutorial
• Windows command line prompt in 15 minutes

Perl Installation

Windows users will likely be 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, but that too can be learned quickly.

UNIX has Perl installed by default, and unless your system is ancient (if perl -v reports a version earlier than 5.8, it's time to upgrade), you already have a recent version.

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.

Details of this process are listed in the Perl and Modules section.

Circos Installation

UNIX users can unpack the Circos archive using tar (e.g., tar xvfz circos-0.54.tar.gz). Windows users should use Windows' built-in handling of .tar.gz files (in Windows Vista or newer), or a free archive utility like 7-Zip, or the venerable (but not free) WinRAR or WinZip. You'll need to first uncompress the file to create the .tar archive and then unpack it to extract the distribution files.

Circos installation details are listed in the Distribution and Installation section.

From the command line, you'll need to run perl and use the circos script as the argument

perl bin\circos -conf tutorials\2\2\circos.conf

Windows won't know what to do with the bin\circos file otherwise.

Circos tutorials are included in a separate package which you will need to download.

path delimiter

Windows file paths use \ as a directory separator, whereas UNIX uses /. The UNIX convention is used throughout the tutorials. Thus when you see

tutorials/2/2/circos.conf

in any of the tutorials or documents, read

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, such as tutorial images). On Windows this directory does not exist.

You can always overwrite the output directory and file defined in the configuration file using -outputdir and -outputfile parameters

# on Windows, executed from the Circos installation directory
perl bin\circos -conf tutorials\2\2\circos.conf -outputdir . -outputfile tutorial_image.png

Circos tutorials are included in a separate package which you will need to download.

Details of this process are listed in the Runtime Parameters section.

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.