.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "CIRCOS 1" .TH CIRCOS 1 "2018-10-28" "perl v5.26.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" .Vb 5 \& _\|_\|_\|_ _ \& / _\|_\|_(_)_ _\|_ _\|_\|_ _\|_\|_ _\|_\|_ \& | | | | \*(Aq_\|_/ _\|_/ _ \e/ _\|_| \& | |_\|_\|_| | | | (_| (_) \e_\|_ \e \& \e_\|_\|_\|_|_|_| \e_\|_\|_\e_\|_\|_/|_\|_\|_/ \& \& round is good .Ve .PP circos \- generate circular data visualizations .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& # without \-conf Circos will search for configuration \& circos \& \& # use specific configuration file \& circos \-conf circos.conf \& \& # diagnose required modules \& circos \-modules \& \& # detailed debugging for code components \& # see http://www.circos.ca/documentation/tutorials/configuration/debugging \& circos \-debug_group GROUP1,[GROUP2,...] \& \& # full debugging \& circos \-debug_group _all \& \& # absolutely no reporting \& circos ... [\-silent] \& \& # configuration dump of a block (or block tree) of \& # any parameters that match REGEXP (optional) \& circos \-cdump [BLOCK1/[BLOCK2/...]]{:REGEXP} \& circos \-cdump ideogram \& circos \-cdump ideogram:label \& circos \-cdump ideogram/spacing \& \& # override configuration parameters \& circos \-param image/radius=2000p \-param ideogram/show=no \& \& # for fun \- randomize all colors in the image except for \& # COLOR1, COLOR2,... \& circos \-randomcolor COLOR1,[COLOR2,...] \& circos \-randomcolor white,black \& \& # brief help \& circos \-h \& \& # man page \& circos \-man \& \& # version \& circos \-v .Ve .SH "SUPPORT" .IX Header "SUPPORT" For support please use the Google Group .PP .SH "DESCRIPTION" .IX Header "DESCRIPTION" Circos generates circular data visualizations. It is ideal for exploring relationships between objects or positions. .PP Circos does not have an interface. It is driven by plain-text configuration files (see below). This makes Circos scriptable and easily incorporated into automatic data analysis and reporting pipelines. .SS "Uses" .IX Subsection "Uses" Circos was initially designed to visualize genomic information, specifically genomic rearrangements in tumor genomes. Although some important parameters in configuration files are named to be intuitve to biologists (e.g. \*(L"chromosomes\*(R"), Circos is not limited to the kind of data it can display. Circular heatmaps, histograms, scatter plots and other types of data displays can be easily made from data collected in other fields, such as meteorology, social science, and computer security. .SS "Salience and Relevance" .IX Subsection "Salience and Relevance" One of the challenges in creating data visualizations is to aptly map what is important (relevance) onto graphical elements that stand out from others (salience). Being able to emphasize (e.g. change color) or attenuate (e.g. add transparency or even hide) salience of information without changing the original data input files is a key feature of Circos. .PP How data is displayed can be easily changed by writing rules, which are evaluated at run-time. Rules can be designed to apply to all data points or only to those that pass certain conditions. Conditions can be based on any property of the data (value, position, format). Rules can be chained into a decision tree making it possible to progressively change the format of data based on the output of other rules. .SS "Data Input Format" .IX Subsection "Data Input Format" Data input formats are plain-text and made to be as simple as possible. .SS "Is it right for you?" .IX Subsection "Is it right for you?" Circos is not a solution. It's a tool to solve visualization problems. For a given problem, you are not guaranteed that Circos is appropriate. .SH "CONFIGURATION" .IX Header "CONFIGURATION" Plain-text configuration file, which define a hierarchy of parameters, control creation of images. These files determine which files Circos uses for its input data, how the data are shown, the layout and formatting of elements in the image as well as system parameters that control low-level functions. .SS "Syntax" .IX Subsection "Syntax" Configuration is plain-text and composed of hierarchical blocks. Some blocks, such as \f(CW\*(C` are mandatory, while others like \&\f(CW\*(C` are optional. .PP To get started, refer to the quick guide tutorial. .PP .PP A typical configuration file might look like this .PP .Vb 2 \& # chromosome name and length definitions \& karyotype = myfile.txt \& \& # image size and format \& \& ... \& \& \& # position and size of ideograms \& \& ... \& \& \& # frequency, position and labeling of tick marks \& \& ... \& \& \& # position, type and format of data tracks \& \& \& ... \& # run\-time rules to change data format and visibility \& \& \& ... \& \& ... \& \& \& ... \& \& \& # colors, fonts and fill patterns \& <> \& \& # system parameters \& <> .Ve .SS "Modularity" .IX Subsection "Modularity" Configuration from one file can be included in another, making it possible to have a very modular setup. For example, if several kinds of images are made for a single project, there can be project-wide configuration definitions which are then complemeted, and possibly overwritten, by image-specific configuration. .PP The \f(CW\*(C`<> directive imports one configuration file into another. .PP .Vb 2 \& # circos.conf \& <> \& \& # ideogram.conf \& <> \& <> \& ... .Ve .PP In the tutorials, you'll find that the \f(CW\*(C` and \f(CW\*(C` blocks are imported into the main configuration file. Because these blocks can get quite large, the main configuration file is more legible if they are relegated to separate files. .PP Parameter definitions that do not frequently change, such as color and font definitions, are conventionally imported from files found in \fIetc/\fR in the distribution. Every Circos image should have .PP .Vb 8 \& # image size, output file name \& \& <> \& \& # color names and lists, location of fonts, fill patterns \& <> \& # low\-level system parameters \& <> .Ve .SS "Overriding with *" .IX Subsection "Overriding with *" To override a parameter that has been included from a file, use the \f(CW\*(C`*\*(C'\fR suffix. The suffix is required because multiple definitions of a parameter are not allowed, except in cases where a parameter is may have more than one value. .PP .Vb 6 \& \& # included file defines \*(Aqradius\*(Aq \& <> \& # this will override the radius value \& radius* = 2500p \& .Ve .PP The \f(CW\*(C`*\*(C'\fR suffix can be repeated to specify which value takes precedence in a block. .PP .Vb 3 \& radius = 1500p \& radius* = 2500p \& radius** = 3000p # this instance of radius will be used .Ve .SS "Overriding with Command Line" .IX Subsection "Overriding with Command Line" Any configuration parameter in a unique block name can be specified on the command line using .PP .Vb 1 \& \-param PATH/PARAM=value .Ve .PP For example, .PP .Vb 4 \& \& show = no \& ... \& \& \& \-param ideogram/show=no .Ve .PP and .PP .Vb 6 \& \& \& default = 0.01r \& \& ... \& \& \& \-param ideogram/spacing/default=0.01r .Ve .SS "Accessing Parameters" .IX Subsection "Accessing Parameters" The \f(CW\*(C`conf()\*(C'\fR function is used in the configuration file to retrieve the value of a parmameter. It can be used to retrieve any parameter, not just those set by \f(CW\*(C`\-param\*(C'\fR). This provides a very flexible system for changing the configuration at the command line. .PP For example, in this case the karyotype file name will change as the \f(CW\*(C`species\*(C'\fR parameter is changed either in the configuration file or using the flag. Similarly, the color palette size and name can be adjusted. .PP .Vb 9 \& # circos.conf \& species = human \& palette = blues \& num_colors = 9 \& karytotype = data/karyotype/karyotype.conf(species).txt \& ... \& \& color = conf(palette)\-seq\-conf(num_colors) \& ... \& \& > circos ... \-param species=rat \-param palette=reds \-param num_colors=5 .Ve .PP Multiple parameters can be redefined, each with its own \f(CW\*(C`\-param\*(C'\fR flag .PP .Vb 1 \& \-param show_ticks=no \-param image/radius=2000p .Ve .SS "Merging Blocks" .IX Subsection "Merging Blocks" Multiple instances of the following blocks are automatically merged: \f(CW\*(C`, \f(CW\*(C`, \f(CW\*(C`, \f(CW\*(C`, \f(CW\*(C`, \f(CW\*(C`, \f(CW\*(C` and \f(CW\*(C`. .PP The purpose of this is to allow you to add to canonical definitions. .PP .Vb 2 \& # this file defines default , and \& <> \& \& # add to the colors block \& \& mycolor = 150,25,25 \& .Ve .SS "Absolute and Relative Paths" .IX Subsection "Absolute and Relative Paths" The use of absolute paths are used in configuration file is discouraged. Doing so makes your configuration less modular and unuseable on another system. .PP For example, if Joe's files are organized thus .PP .Vb 3 \& /user/joe/project/ \& data/genes.txt \& etc/circos.conf .Ve .PP he could use .PP .Vb 1 \& file = /user/joe/project/data/genes.txt .Ve .PP and run Circos from his home directory .PP .Vb 2 \& > cd ~ \& > circos \-conf project/etc/circos.conf .Ve .PP It would be much better for him to define .PP .Vb 1 \& file = data/genes.txt .Ve .PP and run Circos from the project/ directory .PP .Vb 2 \& > cd ~/project \& > circos .Ve .PP Now, if he creates a tarball of all the project files (e.g. \f(CW\*(C`project.tgz\*(C'\fR), anyone could use the files by executing exactly the same commands. .PP When you define a file with a relative path, such as .PP .Vb 1 \& file = data/genes.txt .Ve .PP Circos will look for this file relative to several reasonable start points, such as the location of the configuration file that you are using, one level up from the configuration location, your current directory, and so on. .PP To see where Circos is searching for files, use .PP .Vb 1 \& > circos \-debug_group io .Ve .PP This is the same mechanism used to find the initial configuration file. If you run Circos without the \f(CW\*(C`\-conf\*(C'\fR flag, .PP .Vb 2 \& > cd ~/project \& > circos .Ve .PP then Circos will look for .PP .Vb 6 \& ~/project/circos.conf \& ~/project/etc/circos.conf \& ~/project/data/circos.conf \& ~/project/../circos.conf \& ~/project/../etc/circos.conf \& ... .Ve .PP If the configuration file cannot be found, Circos will default to looking into its distribution directory. .PP Users who are unaware of this feature often manage to get away with unorganized project files because this automatic file search feature. The purpose of this feature is to make your life easier when you know what you're doing \*(-- not necessarily to make it possible when you don't know what you're doing. .PP If you want to redefine the search paths, see the \f(CW\*(C`data_path\*(C'\fR parameter in \f(CW\*(C`etc/housekeeping.conf\*(C'\fR in the distribution directory, or overide it in your configuration file .PP .Vb 2 \& <> \& data_path* = ... .Ve .SH "OPTIONS" .IX Header "OPTIONS" .SS "Configuration" .IX Subsection "Configuration" .IP "\-configfile \s-1FILE\s0" 4 .IX Item "-configfile FILE" Name of configuration file. This is required. .Sp Circos will attempt to guess the location of this file, searching for \&\f(CW\*(C`circos.conf\*(C'\fR in \f(CW\*(C`.\*(C'\fR, \f(CW\*(C`..\*(C'\fR, and \f(CW\*(C`../..\*(C'\fR. This is described above. .SS "Output Format" .IX Subsection "Output Format" .IP "\-png, \-nopng" 4 .IX Item "-png, -nopng" .PD 0 .IP "\-svg, \-nosvg" 4 .IX Item "-svg, -nosvg" .PD Toggles output of \s-1PNG\s0 and \s-1SVG\s0 files. .SS "Image Elements" .IX Subsection "Image Elements" .IP "\-show_ticks, \-noshow_ticks" 4 .IX Item "-show_ticks, -noshow_ticks" .PD 0 .IP "\-show_tick_labels, \-noshow_tick_labels" 4 .IX Item "-show_tick_labels, -noshow_tick_labels" .PD Override the display of ticks and their labels. These are both usually defined in the block. .Sp These flags are shortcuts to .Sp .Vb 2 \& \-param show_ticks=no \& \-param show_tick_labels=no .Ve .SS "Output Paths" .IX Subsection "Output Paths" .IP "\-outputdir \s-1DIR,\s0 \-dir \s-1DIR\s0" 4 .IX Item "-outputdir DIR, -dir DIR" .PD 0 .IP "\-outputfile \s-1FILE,\s0 \-file \s-1FILE\s0" 4 .IX Item "-outputfile FILE, -file FILE" .PD Change the output directory and filename. The \s-1FILE\s0 can contain a path. .SS "Debugging" .IX Subsection "Debugging" .IP "\-debug" 4 .IX Item "-debug" Turn on basic debugging output. Reports information from .Sp .Vb 1 \& image, io, layer, summary, timer .Ve .Sp debug groups (see below). .IP "\-debug_group {+\-}GROUP1,[{+\-}GROUP2,...]" 4 .IX Item "-debug_group {+-}GROUP1,[{+-}GROUP2,...]" Turn on debugging output for specific groups. For a list of groups, see .Sp .Sp To add a group to the output prefix it with +. To remove it, with \-. .Sp .Vb 2 \& # use default debugging groups but exclude layer and io \& \-debug \-debug_group \-layer,\-io \& \& # use default debugging groups and add spacing \& \-debug \-debug_group +spacing \& \& # explicitly specify the groups \& \-debug_group png,io,timer .Ve .Sp To list the groups that are supported, use the flag without an argument .Sp .Vb 1 \& \-debug_group .Ve .Sp Those listed with a \*(L"*\*(R" are turned on by default. To change this, adjust \f(CW\*(C`debug_group\*(C'\fR in \f(CW\*(C`etc/housekeeping.conf\*(C'\fR in the distribution directory. .IP "\-time" 4 .IX Item "-time" Report timing information. Same as \f(CW\*(C`\-debug_group +timer\*(C'\fR. .IP "\-silent" 4 .IX Item "-silent" Generate no reporting. .IP "\-paranoid, \-noparanoid" 4 .IX Item "-paranoid, -noparanoid" Run in paranoid mode (default), or not. The default for this setting is defined by \f(CW\*(C`paranoid\*(C'\fR in \f(CW\*(C`etc/housekeeping.conf\*(C'\fR. .IP "\-warnings, \-nowarnings" 4 .IX Item "-warnings, -nowarnings" Display warnings, or not (default). The default for this setting is defined by \f(CW\*(C`warnings\*(C'\fR in \f(CW\*(C`etc/housekeeping.conf\*(C'\fR. .IP "\-fakeerror =item \-fakeerror \s-1CAT\s0 =item \-fakeerror ,ID =item \-fakeerror \s-1CAT,ID\s0" 4 .IX Item "-fakeerror =item -fakeerror CAT =item -fakeerror ,ID =item -fakeerror CAT,ID" Fake an error by displaying the error message for category \s-1CAT\s0 and error name \s-1ID.\s0 If one or neither are specified, lists which errors are available. .Sp Unless you truly enjoy seeing error messages, there should be little reason for you to want to use this. .SS "Usage" .IX Subsection "Usage" .IP "\-version" 4 .IX Item "-version" Show the version. .IP "\-help" 4 .IX Item "-help" Show brief usage synopsis. .IP "\-man" 4 .IX Item "-man" Show man page. .SS "Goofing Around" .IX Subsection "Goofing Around" .IP "\-randomcolor [color1,color2,...]" 4 .IX Item "-randomcolor [color1,color2,...]" Randomize the color of every element in the image, except for an optional list of colors. .Sp For example, to keep the background white and anything that is black, .Sp .Vb 1 \& \-randomcolor white,black .Ve .SH "DOCUMENTATION" .IX Header "DOCUMENTATION" .RS 4 For full documentation, see .Sp .RE .SH "AUTHOR" .IX Header "AUTHOR" Martin Krzywinski martink@bcgsc.ca \&\f(CW@MKrzywinski\fR .PP Canada's Michael Smith Genome Sciences Centre 100\-570 W 7th Ave Vancouver \s-1BC V5Z 4S6\s0 Canada .PP .SH "RESOURCES" .IX Header "RESOURCES" .PP .SH "CITING" .IX Header "CITING" If you are using Circos in a publication, please cite as .PP Krzywinski, M., J. Schein, I. Birol, J. Connors, R. Gascoyne, D. Horsman, S. Jones, and M. Marra. 2009. Circos: an Information Aesthetic for Comparative Genomics. Genome Res 19:1639\-1645. .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" Ken Youens-Clark kyclark@gmail.com .SH "SEE ALSO" .IX Header "SEE ALSO" Hive plots .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright 2004\-2017 Martin Krzywinski, all rights reserved. .PP This script is free software; you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. .PP This script is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See the \&\s-1GNU\s0 General Public License for more details. .PP You should have received a copy of the \s-1GNU\s0 General Public License along with this script; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, \s-1MA\s0 02111\-1307 \s-1USA\s0