1. Nicola Segata
  2. CirClader

Overview

First very partial draft of the manual....


PREREQUISITES:

- biopython
- matplotlib




==============================================================================

GraphiPhlAn is a software tool for producing high-quality circular 
representations of taxonomic and phylogenetic trees 

drawing, annotating, adding quantitative and
qualitative information, and decorating phylogenetic and taxonomic trees. 




==============================================================================

------------------------------------------------------------------------------
GLOBAL TREE OPTIONS:
------------------------------------------------------------------------------

Global structural and visual characteristics affecting the entire tree are
specified in the annotation file with a two-column tab separated syntax with the
following pattern

global_tree_option	global_tree_option_value

where global_tree_option can be any of the following: 

ignore_branch_len [def. 0 = False] : specify whether to display the tree with
    fixed branch length (i.e. 0) or with the values specified in the input 
    tree. If the input tree is not containing branch length information, branch 
    lengths will not be showed regardless of this option 

total_plotted_degrees [def. 360] : the total circular portion used in plotting 
    the tree. 360 means that the tree uses the full rotational space. Small 
    trees are usually best displayed with a limited total_plotted_degrees value.

start_rotation [def 0] : the default starting rotational position for the first 
    leaf of the tree 

clade_separation [def 0.0] : specify a fractional separation between clades 
    which is proportional to the branch distance between subtrees. It option can
    be used to visually separate more clades that are reciprocally deep 
    branching.  

branch_bracket_depth [def 0.25] : the relative position of the branch bracket 
    which is the radial segment from which the child taxa branches originate.  

branch_bracket_width [def 1.0] : the width of the branch bracket relative to 
    the position of the most separated child roots

------------------------------------------------------------------------------
GRAPHICAL TREE OPTIONS:
------------------------------------------------------------------------------

The graphical tree options are the most common way of personalizing the trees.
They can be referred to specific clade, to set of clades, or to all clade. The
syntax is the following.

[clade_name{+|*|^}]	graphical_tree_option	graphical_tree_option_value

If the clade name is omitted the option is applied to ALL clades. The clade
can be specified with the full label comprising all names from the root of the
tree or with the last level only (if last level names are not unique, multiple
matching clades will be affected by the command). Optionally, at the end of the
clade name, one of the following character can be added (see below for the
meaning of these symbols): +, *, ^

The "graphical_tree_option" can be:

clade_marker_size [def. 20.0] : the size of the marker representing the root 
    of the clade inside the tree

clade_marker_color [def. #FFFFFF, i.e. white] : the fill color of the marker 
    representing the root of the clade inside the tree

clade_marker_shape [def. 'o', i.e. circle] : the shape of the clade marker. 
    See the Marker Shapes table below for the allowed options

clade_marker_edge_width [def. 0.5] : the thickness of the border for clade 
    markers

clade_marker_edge_color [def. #000000, i.e. black] : the color of the markers' 
    border


When added after the name of a valid clade, the following three characters can
be used to apply the same property to multiple parts of the clade' subtree

* : the specified clade and all its descendants are affected by the property
+ : the specified clade and all its terminal nodes are affected 
^ : all (an only) the terminal nodes of the specified clade are affected

------------------------------------------------------------------------------
ANNOTATION OPTIONS
------------------------------------------------------------------------------

[clade_name]	annotation_option	graphical_tree_option_value

We call annotations the shadings highlighting clades and the corresponding
subtree. Annotations can be colored, their alpha-channel can be globally
regulated, and have a label associated with them. Specifically, the options
available for annotations are:

annotation [def. no annotation] : the label the be associated and displayed for
    the annotation. This can assume several formats:
      1. str (a string not containing ':'): the string to be displayed entirely 
         (an only) on the shading
      2. key:str : the (supposedly short) key will be displayed on the 
         annotation shading, whereas the full key:string label will be reported 
         as external legend
      3. *:str : a key will be generated and used as the 2. "key:str" case
      4. * : the name of the clade (specifically the last taxonomic level only) 
         will be used as the 'str' in the 1. case above
      5. *:* : the combination of the 3. and 4. cases above

annotation_font_size [def. 7] : the font size of the annotation label

annotation_font_stretch [def. 0] : horizontal font compactness (0 is minimal)

annotation_rotation [def 0] : the rotation of the label. As default the rotation
    is perpendicular to the radial position of the label. It can be changed to 
    90 so that the labels are less likely to overlap

annotation_background_color [def. grey] : the color of the annotation background

annotation_background_edge_color [def annotation_background_color] : the color 
    of the edge for the annotation background


------------------------------------------------------------------------------
RING OPTIONS
------------------------------------------------------------------------------

We call rings the graphical elements external to the tree itself that can be
seen as "circular heatmaps", "circular barplots", and actually more (like
indicator elements). These "rings" are linked directly to the internal tree as
each segment of the rings correspond to a tree leaf (and potentially to internal
nodes as well). Multiple rings can be specified for the same image and each must
have a progressive associated number (level "1" being the most internal ring).

The general syntax for rings is:

[clade_name]	ring_option	ring_level	ring_option_value

If clade_name is not present or if it is "*" the ring option is applied to all
the ring sectors in the "ring_level". The "ring_level" is a integer number that
must always be specified.

Here are the possible ring options:

ring_color [def. black] : the color of the ring segment 

ring_width [def. 1.0] : the width of the ring segment a fraction of the total 
    circular width available for the specific clade

ring_height [def. highest height for the rings in the same level, or 0.1 if no
    heights are specific] : the height of the circular segment. If not specific 
    the same default height (0.1*size of the tree) is applied for all ring 
    segment in the level, otherwise the height is equal to the biggest height 
    value in the level.

ring_alpha [def. 1.0]: the transparency value. 0.0 means completely transparent
    (thus invisible), 1.0 means completely opaque (no transparencies) 

ring_shape [def. R]: the shape of the ring. Default is 'R' for rectangular which
    means that the whole available area is used. The alternative is currently 
    'v' only which means a triangular shape that can be used as pointing arrow 
    for highlighting specific clades. 

ring_edge_width [def 0.1]: the width of the border of the ring segment

ring_edge_color [def None, which means 'ring_color']: the color of the border 
    of the ring segment

Some additional ring options refer to non clade-specific aspects like the label
of the ring itself or the graphical separation between rings. These options are
specified without a clade name in the following tree-column format:

global_ring_option     ring_level      global_ring_option_value

Specifically, the ring options can be:

ring_label [def. None]: the label to be displayed at "stat_rotation" position 
    for the rings. total_plotted_degrees should be less than 360 to make space 
    for these labels

ring_label_font_size [def. 11]: the font size of the ring labels

ring_internal_separator_thickness [def.  0.0 which means absent]: the thickness 
    of the circular line separating different ring levels. This is referred 
    to the most internal of the two sides of each ring.

ring_external_separator_thickness [def.  0.0 which means absent]: the thickness
    of the circular line separating different ring levels. This is referred to 
    the most external of the two sides of each ring.

ring_separator_color [def. 'k' for black]: the color of the circular line 
    separating different ring levels.



 

------------------------------------------------------------------------------
COLORS
------------------------------------------------------------------------------

Colors are strings that can be:
- one of the following 'default' colors: blue, green, red, cyan, magenta, 
    yellow, black, white
- a one-letter shortcut for the above colors: 'b' (blue), 'g' (green), 
    'r' (red), 'c' (cyan), 'm' (magenta), 'y' (yellow), 'k' (black), 
    'w' (white) 

- a RGB color code in the hexadecimal format: #rrggbb, for example #FF0000
    corresponds to (full) red

------------------------------------------------------------------------------
MARKER SHAPES:
------------------------------------------------------------------------------

As of August 2012 we support the marker types available in matplotlib version
1.1.1. Specifically here are the codes for the markers. Note that some of them
are shapes with internal color-filled space, other are edge- or point-only
markers.

'.' : point marker
',' : pixel marker
'o' : circle marker
'v' : triangle_down marker
'^' : triangle_up marker
'<' : triangle_left marker
'>' : triangle_right marker
'1' : tri_down marker
'2' : tri_up marker
'3' : tri_left marker
'4' : tri_right marker
's' : square marker
'p' : pentagon marker
'*' : star marker
'h' : hexagon1 marker
'H' : hexagon2 marker
'+' : plus marker
'x' : x marker
'D' : diamond marker
'd' : thin_diamond marker
'|' : vline marker
'_' : hline marker