Treeview module — A Python Environment for (phylogenetic) Tree Exploration

### Navigation

- index
- modules |
- next |
- previous |
- ETE documentation »
- ETE’s Reference Guide »

# Treeview module

Contents

- Treeview module
  - TreeStyle
  - NodeStyle
  - Faces
  - Color names

## TreeStyle

class `TreeStyle`

  New in version 2.1.

  Contains all the general image properties used to render a tree

  – About tree design –

  Variables: | layout_fn (None) – Layout function used to dynamically control the aspect of nodes. Valid values are: None or a pointer to a method, function, etc.

  – About tree shape –

  Variables: | mode (“r”) – Valid modes are ‘c’(ircular) or ‘r’(ectangular). orientation (0) – If 0, tree is drawn from left-to-right. If 1, tree is drawn from right-to-left. This property only makes sense when “r” mode is used. rotation (0) – Tree figure will be rotate X degrees (clock-wise rotation). min_leaf_separation (1) – Min separation, in pixels, between two adjacent branches branch_vertical_margin (0) – Leaf branch separation margin, in pixels. This will add a separation of X pixels between adjacent leaf branches. In practice, increasing this value work as increasing Y axis scale. arc_start (0) – When circular trees are drawn, this defines the starting angle (in degrees) from which leaves are distributed (clock-wise) around the total arc span (0 = 3 o’clock). arc_span (360) – Total arc used to draw circular trees (in degrees). margin_left (0) – Left tree image margin, in pixels. margin_right (0) – Right tree image margin, in pixels. margin_top (0) – Top tree image margin, in pixels. margin_bottom (0) – Bottom tree image margin, in pixels.

  – About Tree branches –

  Variables: | scale (None) – Scale used to draw branch lengths. If None, it will be automatically calculated. optimal_scale_level (“mid”) – Two levels of automatic branch scale detection are available: `"mid"` and `"full"`. In `full` mode, branch scale will me adjusted to fully avoid dotted lines in the tree image. In other words, scale will be increased until the extra space necessary to allocated all branch-top/bottom faces and branch-right faces (in circular mode) is covered by real branches. Note, however, that the optimal scale in trees with very unbalanced branch lengths might be huge. If `"mid"` mode is selected (as it is by default), optimal scale will only satisfy the space necessary to allocate branch-right faces in circular trees. Some dotted lines (artificial branch offsets) will still appear when branch-top/bottom faces are larger than branch length. Note that both options apply only when `scale` is set to None (automatic). root_opening_factor (0.25) – (from 0 to 1). It defines how much the center of a circular tree could be opened when adjusting optimal scale, referred to the total tree length. By default (0.25), a blank space up to 4 times smaller than the tree width could be used to calculate the optimal tree scale. A 0 value would mean that root node should always be tightly adjusted to the center of the tree. complete_branch_lines_when_necessary (True) – True or False. Draws an extra line (dotted by default) to complete branch lengths when the space to cover is larger than the branch itself. extra_branch_line_type (2) – 0=solid, 1=dashed, 2=dotted extra_branch_line_color” (“gray”) – RGB code or name in `SVG_COLORS` force_topology (False) – Convert tree branches to a fixed length, thus allowing to observe the topology of tight nodes draw_guiding_lines (True) – Draw guidelines from leaf nodes to aligned faces guiding_lines_type (2) – 0=solid, 1=dashed, 2=dotted. guiding_lines_color (“gray”) – RGB code or name in `SVG_COLORS`

  – About node faces –

  Variables: | allow_face_overlap (False) – If True, node faces are not taken into account to scale circular tree images, just like many other visualization programs. Overlapping among branch elements (such as node labels) will be therefore ignored, and tree size will be a lot smaller. Note that in most cases, manual setting of tree scale will be also necessary. draw_aligned_faces_as_table (True) – Aligned faces will be drawn as a table, considering all columns in all node faces. children_faces_on_top (True) – When floating faces from different nodes overlap, children faces are drawn on top of parent faces. This can be reversed by setting this attribute to false.

  – Addons –

  Variables: | show_border (False) – Draw a border around the whole tree show_scale (True) – Include the scale legend in the tree image show_leaf_name (False) – Automatically adds a text Face to leaf nodes showing their names show_branch_length (False) – Automatically adds branch length information on top of branches show_branch_support (False) – Automatically adds branch support text in the bottom of tree branches

  – Tree surroundings –

  The following options are actually Face containers, so graphical elements can be added just as it is done with nodes. In example, to add tree legend:

  >     TreeStyle.legend.add_face(CircleFace(10, "red"), column=0)
  >     TreeStyle.legend.add_face(TextFace("0.5 support"), column=1)

  Variables: | aligned_header – a `FaceContainer` aligned to the end of the tree and placed at the top part. aligned_foot – a `FaceContainer` aligned to the end of the tree and placed at the bottom part. legend – a `FaceContainer` with an arbitrary number of faces representing the legend of the figure. legend_position=4 (4) – TopLeft corner if 1, TopRight if 2, BottomLeft if 3, BottomRight if 4 title – A text string that will be draw as the Tree title

class `FaceContainer`

  New in version 2.1.

  Use this object to create a grid of faces. You can add faces to different columns.

  `add_face`(face, column)

    add the face face to the specified column

## NodeStyle

class `NodeStyle`(*args, **kargs)

  New in version 2.1.

  A dictionary with all valid node graphical attributes.

  Parameters: | fgcolor (#0030c1) – RGB code or name in `SVG_COLORS` bgcolor (#FFFFFF) – RGB code or name in `SVG_COLORS` node_bgcolor (#FFFFFF) – RGB code or name in `SVG_COLORS` partition_bgcolor (#FFFFFF) – RGB code or name in `SVG_COLORS` faces_bgcolor (#FFFFFF) – RGB code or name in `SVG_COLORS` vt_line_color (#000000) – RGB code or name in `SVG_COLORS` hz_line_color (#000000) – RGB code or name in `SVG_COLORS` hz_line_type (0) – integer number vt_line_type (0) – integer number size (3) – integer number shape (“circle”) – “circle”, “square” or “sphere” draw_descendants (True) – Mark an internal node as a leaf. hz_line_width (0) – integer number representing the width of the line in pixels. A line width of zero indicates a cosmetic pen. This means that the pen width is always drawn one pixel wide, independent of the transformation set on the painter. vt_line_width (0) – integer number representing the width of the line in pixels. A line width of zero indicates a cosmetic pen. This means that the pen width is always drawn one pixel wide, independent of the transformation set on the painter.

## Faces

`add_face_to_node`(face, node, column, aligned=False, position='branch-right')

  Adds a Face to a given node.

  Parameters: | face – A `Face` instance

  Parameters: | node – a tree node instance (`Tree`, `PhyloTree`, etc.) column – An integer number starting from 0 position (“branch-right”) – Possible values are “branch-right”, “branch-top”, “branch-bottom”, “float”, “aligned”

class `Face`

  Standard definition of a Face node object.

  This class is not functional and it should only be used to create other face objects. By inheriting this class, you set all the essential attributes, however the update_pixmap() function is required to be reimplemented for convenience.

  User adjustable properties:

  Parameters: | margin_left (0) – in pixels margin_right (0) – in pixels margin_top (0) – in pixels margin_bottom (0) – in pixels opacity (1.0) – a float number in the (0,1) range rotable (True) – If True, face will be rotated when necessary (i.e. when circular mode is enabled and face occupies an inverted position.) hz_align (0) – 0 left, 1 center, 2 right vt_align (1) – 0 top, 1 center, 2 bottom background – background of face plus its margins inner_background – background of the face border (None) – Border around face margins. Integer number representing the width of the face border line in pixels. A line width of zero indicates a cosmetic pen. This means that the pen width is always drawn one pixel wide, independent of the transformation set on the painter. A “None” value means invisible border. inner_border (None) – Border around face . Integer number representing the width of the face border line in pixels. A line width of zero indicates a cosmetic pen. This means that the pen width is always drawn one pixel wide, independent of the transformation set on the painter. A “None” value means invisible border.

class `TextFace`(text, ftype='Verdana', fsize=10, fgcolor='#000000', penwidth=0, fstyle='normal')

  Static text Face object

  Parameters: | text – Text to be drawn ftype – Font type, e.g. Arial, Verdana, Courier fsize – Font size, e.g. 10,12,6, (default=10) fgcolor – Foreground font color. RGB code or name in `SVG_COLORS` penwidth – Penwdith used to draw the text. fstyle – “normal” or “italic”

class `AttrFace`(attr, ftype='Verdana', fsize=10, fgcolor='#000000', penwidth=0, text_prefix='', text_suffix='', formatter=None, fstyle='normal')

  Dynamic text Face. Text rendered is taken from the value of a given node attribute.

  Parameters: | attr – Node’s attribute that will be drawn as text ftype – Font type, e.g. Arial, Verdana, Courier, (default=”Verdana”) fsize – Font size, e.g. 10,12,6, (default=10) fgcolor – Foreground font color. RGB code or name in `SVG_COLORS` penwidth – Penwdith used to draw the text. (default is 0) text_prefix – text_rendered before attribute value text_suffix – text_rendered after attribute value formatter – a text string defining a python formater to process the attribute value before renderer. e.g. “%0.2f” fstyle – “normal” or “italic”

class `ImgFace`(img_file)

  Creates a new image face object.

  Parameters: | img_file – Image file in png,jpg,bmp format

class `CircleFace`(radius, color, style='circle')

  New in version 2.1.

  Creates a Circle or Sphere Face.

  Arguments radius:
  | integer number defining the radius of the face
  Arguments color:
  | Color used to fill the circle. RGB code or name in `SVG_COLORS`
  Arguments “circle” style:
  | Valid values are “circle” or “sphere”

class `SequenceFace`(seq, seqtype, fsize=10, aafg=None, aabg=None, ntfg=None, ntbg=None)

  Creates a new molecular sequence face object.

  Parameters: | seq – Sequence string to be drawn seqtype – Type of sequence: “nt” or “aa” fsize – Font size, (default=10)

  You can set custom colors for aminoacids or nucleotides:

  Parameters: | aafg – a dictionary in which keys are aa codes and values are foreground RGB colors aabg – a dictionary in which keys are aa codes and values are background RGB colors ntfg – a dictionary in which keys are nucleotides codes and values are foreground RGB colors ntbg – a dictionary in which keys are nucleotides codes and values are background RGB colors

class `ProfileFace`(max_v, min_v, center_v, width=200, height=40, style='lines', colorscheme=2)

  A profile Face for ClusterNodes

  Parameters: | max_v – maximum value used to build the build the plot scale. max_v – minimum value used to build the build the plot scale. center_v – Center value used to scale plot and heatmap. width (200) – Plot width in pixels. height (40) – Plot width in pixels. style (lines) – Plot style: “lines”, “bars”, “cbars” or “heatmap”. colorscheme (2) – colors used to create the gradient from min values to max values. 0=green & blue; 1=green & red; 2=red & blue. In all three cases, missing values are rendered in black and transition color (values=center) is white.

class `TreeFace`(tree, tree_style)

  New in version 2.1.

  Creates a Face containing a Tree object. Yes, a tree within a tree :)

  Parameters: | tree – An ETE Tree instance (Tree, PhyloTree, etc...) tree_style – A TreeStyle instance defining how tree show be drawn

class `StaticItemFace`(item)

  New in version 2.1.

  Creates a face based on an external QtGraphicsItem object. QGraphicsItem object is expected to be independent from tree node properties, so its content is assumed to be static (drawn only once, no updates when tree changes).

  Arguments item: | an object based on QGraphicsItem

class `DynamicItemFace`(constructor, *args, **kargs)

  New in version 2.1.

  Creates a face based on an external QGraphicsItem object whose content depends on the node that is linked to.

  Arguments constructor:
  | A pointer to a method (function or class constructor) returning a QGraphicsItem based object. “constructor” method is expected to receive a node instance as the first argument. The rest of arguments passed to ItemFace are optional and will passed also to the constructor function.

## Color names

`SVG_COLORS`

  > Apart from RGB color codes, the following SVG color names are supported:

### Navigation

- index
- modules |
- next |
- previous |
- ETE documentation »
- ETE’s Reference Guide »