-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
executable file
·371 lines (227 loc) · 10.4 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
################################################################
Circos - flexible and automatable circular data visualization
Martin Krzywinski
Canada's Michael Smith Genome Sciences Center
British Columbia Cancer Agency
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