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 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.
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, like languages such as Python or Ruby, is an interpreted language. This means that you do not need to compile the Circos code — it is read in by the Perl executable (that ships with, or has been installed, for your operating system), which in turn interprets it, compiles it and runs the code.
Perl modules are third-party code that adds functionality to the core language. Your installation of Perl will include core modules. In addition to these, you'll need to install the following modules to run Circos.
Config::General (v2.50 or later) Font::TTF GD List::MoreUtils Math::Bezier Math::Round Math::VecStat Params::Validate Readonly Regexp::Common Set::IntSpan (v1.16 or later) Text::Format
On UNIX, to list all the required modules (many in the list will be core modules, and therefore already part of the Perl distribution), run
# this script only works on UNIX, not Windows > cd bin > ./list.modules
and to test which ones you are missing,
# this script only works on UNIX, not Windows > cd bin > ./test.modules ok Carp ok Clone ok Config::General ok Cwd ok Data::Dumper ok Digest::MD5 ok File::Basename ok File::Spec::Functions ok File::Temp ok FindBin ok Font::TTF::Font ok GD ok GD::Image ok GD::Polyline ok Getopt::Long ok IO::File ok List::MoreUtils ok List::Util ok Math::Bezier ok Math::BigFloat ok Math::Round ok Math::VecStat ok Memoize ok POSIX ok Params::Validate ok Pod::Usage ok Readonly ok Regexp::Common ok Set::IntSpan ok Storable ok Sys::Hostname ok Text::Balanced ok Text::Format ok Time::HiRes
To install these modules, use the CPAN module to quickly download, compile and install them. CPAN will follow dependencies and generally do the right thing. Windows users should use their Perl's installation package manager (see below).
> perl -MCPAN -e shell ... cpan>install Math::Bezier ...
Modules use either the
Makefile.PL system, or the Build system. For purposes here, these are equivalent but require slightly different commands.
To install a module that uses the
Makefile.PL system, such as Set::IntSpan.
# download module > wget http://search.cpan.org/CPAN/authors/id/S/SW/SWMCD/Set-IntSpan-1.16.tar.gz # unpack archive > tar xvfz Set-IntSpan-1.16.tar.gz > cd Set-IntSpan-1.16 # configure and compile > perl Makefile.PL Checking if your kit is complete... Looks good Writing Makefile for Set::IntSpan > make cp IntSpan.pm blib/lib/Set/IntSpan.pm Manifying blib/man3/Set::IntSpan.3 > make test » make test PERL_DL_NONLAZY=1 /home/martink/perl/5.10.0/bin/perl "-MExtUtils::Command::MM" "-e" "test_harness(0, 'blib/lib', 'blib/arch')" t/*.t t/binary.t .... ok t/bsearch.t ... ok ... t/spans.t ..... ok t/subclass.t .. ok t/unary.t ..... ok All tests successful. Files=18, Tests=1931, 0 wallclock secs ( 0.28 usr 0.03 sys + 0.36 cusr 0.06 csys = 0.73 CPU) Result: PASS # install (keep in mind file permission requirements, as described below) > make install
# download module > wget http://search.cpan.org/CPAN/authors/id/D/DR/DROLSKY/Params-Validate-0.95.tar.gz # unpack archive > tar xvfz Params-Validate-0.95.tar.gz > cd Params-Validate-0.95 # configure and compile > perl Build.PL Creating new 'MYMETA.yml' with configuration results Creating new 'Build' script for 'Params-Validate' version '0.95' > ./Build Building Params-Validate cc -Ic -I/home/martink/perl/5.10.0/lib/5.10.0/x86_64-linux/CORE -DXS_VERSION="0.95" -DVERSION="0.95" -fPIC -c -fno-strict-aliasing -pipe -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -I/usr/include/gdbm -O2 -o lib/Params/Validate.o lib/Params/Validate.c ExtUtils::Mkbootstrap::Mkbootstrap('blib/arch/auto/Params/Validate/Validate.bs') cc -shared -O2 -o blib/arch/auto/Params/Validate/Validate.so lib/Params/Validate.o > ./Build test t/01-validate.t ............ ok t/02-noop.t ................ ok t/03-attribute.t ........... ok ... t/30-hashref-alteration.t .. ok t/kwalitee.t ............... skipped: This test is only run for the module author t/pod-coverage.t ........... skipped: This test is only run for the module author t/pod.t .................... skipped: This test is only run for the module author All tests successful. Files=32, Tests=497, 1 wallclock secs ( 0.10 usr 0.04 sys + 0.78 cusr 0.13 csys = 1.05 CPU) Result: PASS # install (keep in mind file permission requirements, as described below) > ./Build install
CPAN should work seamlessly. Many users have difficulty with the GD module, which has numerous dependencies. Paulo Nuin has a nice blog entry that shows how he handled his Mac OS X Circos installation.
If you are missing a module, you'll see an error like the following when you run Circos.
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-multi /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.
In this case Perl is complaining that the module
cannot be found. You'll need to install Config::General (see above).
On UNIX, use the
bin/test.modules script (see above) to see which modules you are missing.
On UNIX systems, if during installation you obtain a file or directory creation permission error, you are likely attempting to write the module files into your system's perl install tree which is owned by root (administrative user).
... Running make test PERL_DL_NONLAZY=1 /usr/bin/perl "-MExtUtils::Command::MM" "-e" "test_harness(0, 'blib/lib', 'blib/arch')" t/*.t t/run....ok All tests successful. Files=1, Tests=68, 1 wallclock secs ( 0.27 cusr + 0.26 csys = 0.53 CPU) /usr/bin/make test -- OK Running make install mkdir /usr/local/share/man: Permission denied at /System/Library/Perl/ 5.8.8/ExtUtils/Install.pm line 112 make: *** [pure_site_install] Error 13 /usr/bin/make install -- NOT OK
Repeat the installation as root (administrator)
> sudo su > perl -MCPAN -e shell ...
makeon Mac OS X
If modules won't install because your system complains that it doesn't have
bash: make command not found
To test whether you have make
> which make /usr/bin/make
Sometimes an unsuccessful make can be due to an error during the compilation.
Could not make: Unknown error
If you know you have Xcode (
which make confirms this, typically
/usr/bin/make), install the module manually. For example, if Params::Validate was giving problems,
> wget http://search.cpan.org/CPAN/authors/id/D/DR/DROLSKY/Params-Validate-0.95.tar.gz > tar xvfz Params-Validate-0.95.tar.gz > cd Params-Validate-0.95 > ./Build # note the build error in the next step > Build make