Treeview module

TreeStyle

class TreeStyle

New in version 2.1.

Contains all the general image properties used to render a tree

– About tree design –

Parameters: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 –

Parameters:
  • 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 (359) – 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 –

Parameters:
  • 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 (False) – 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 –

Parameters:
  • 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 –

Parameters:
  • 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)
Parameters:
  • 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 Face container that can be used as 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”, “float-behind” and “aligned”.
class Face

Base Face object. All Face types (i.e. TextFace, SeqMotifFace, etc.) inherit the following options:

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.color – background color of face plus all its margins.
  • inner_background.color – background color of the face excluding margins
  • border – Border around face margins.
  • inner_border – Border around face excluding margins.

border and inner_border sub-parameters:

Parameters:
  • (inner_)border.type (0) – 0=solid, 1=dashed, 2=dotted
  • (inner_)border.width (None) – a positive integer number. 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.color (black) – RGB or color name in SVG_COLORS

See also specific options for each face type.

class TextFace(text, ftype='Verdana', fsize=10, fgcolor='black', penwidth=0, fstyle='normal', tight_text=False, bold=False)

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 color name in SVG_COLORS
  • penwidth – Penwdith used to draw the text.
  • fstyle – “normal” or “italic”
  • tight_text (False) – When False, boundaries of the text are

approximated according to general font metrics, producing slightly worse aligned text faces but improving the performance of tree visualization in scenes with a lot of text faces.

class AttrFace(attr, ftype='Verdana', fsize=10, fgcolor='black', penwidth=0, text_prefix='', text_suffix='', formatter=None, fstyle='normal', tight_text=False)

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, width=None, height=None, is_url=False)

Creates a node Face using an external image file.

Parameters:
  • img_file – path to the image file.
  • width (None) – if provided, image will be scaled to this width (in pixels)
  • height (None) – if provided, image will be scaled to this height (in pixels)
  • is_url (False) – if True, img_file is considered a URL and the image is automatically downloaded

If only one dimension value (width or height) is provided, the other will be calculated to keep aspect ratio.

class CircleFace(radius, color, style='circle', label=None)

New in version 2.1.

Creates a Circle or Sphere Face.

Parameters:
  • radius – integer number defining the radius of the face
  • color – Color used to fill the circle. RGB code or name in SVG_COLORS
  • style (“circle”) – Valid values are “circle” or “sphere”
  • label – optional text string to annotate the face: Default value is None;

label can also be a dict with attributes text, font, color, and fontsize color defaults to circle color (because it looks nice with “sphere”), font to Verdana, fontsize to 12

class RectFace(width, height, fgcolor, bgcolor, label=None)

New in version 2.3.

Creates a Rectangular solid face.

Parameters:label – optional text string to annotate the face: Default value is None;

label can also be a dict with attributes text, font, color, and fontsize color defaults to background color, font to Verdana, fontsize to 12

class StackedBarFace(percents, width, height, colors=None, line_color=None)
class SequenceFace(seq, seqtype='aa', fsize=10, fg_colors=None, bg_colors=None, codon=None, col_w=None, alt_col_w=3, special_col=None, interactive=False)

Creates a new molecular sequence face object. :param seq: Sequence string to be drawn :param seqtype: Type of sequence: “nt” or “aa” :param fsize: Font size, (default=10)

You can set custom colors for amino-acids or nucleotides:

Parameters:
  • codon (None) – a string that corresponds to the reverse translation of the amino-acid sequence
  • col_w (None) – width of the column (if col_w is lower than font size, letter wont be displayed)
  • fg_colors (None) – dictionary of colors for foreground, with as keys each possible character in sequences, and as value the colors
  • bg_colors (None) – dictionary of colors for background, with as keys each possible character in sequences, and as value the colors
  • alt_col_w (3) – works together with special_col option, defines the width of given columns
  • special_col (None) – list of lists containing the bounds of columns to be displayed with alt_col_w as width
  • interactive (False) – more info can be displayed when mouse over sequence
class InteractiveLetterItem(*arg, **karg)

This is a class

hoverEnterEvent(e)

when mouse is over

hoverLeaveEvent(e)

when mouse leaves area

class SeqMotifFace(seq=None, motifs=None, seqtype='aa', gap_format='line', seq_format='()', scale_factor=1, height=10, width=10, fgcolor='slategrey', bgcolor='slategrey', gapcolor='black')

New in version 2.2.

Creates a face based on an amino acid or nucleotide sequence and a list of motif regions.

Parameters:
  • seq (None) – a text string containing an aa or nt sequence. If not provided, seq and compactseq motif modes will not be available.
  • motifs (None) –

    a list of motif regions referred to original sequence. Each motif is defined as a list containing the following information:

    motifs = [[seq.start, seq.end, shape, width, height, fgcolor, bgcolor, text_label],
         [seq.start, seq.end, shape, width, height, fgcolor, bgcolor, text_label],
         ...
        ]

    Where:

    • seq.start: Motif start position referred to the full sequence (1-based)
    • seq.end: Motif end position referred to the full sequence (1-based)
    • shape: Shape used to draw the motif. Available values are:
      • o = circle or ellipse
      • > = triangle (base to the left)
      • < = triangle (base to the left)
      • ^ = triangle (base at bottom)
      • v = triangle (base on top )
      • <> = diamond
      • [] = rectangle
      • () = round corner rectangle
      • line = horizontal line
      • blank = blank space
      • seq = Show a color and the corresponding letter of each sequence position
      • compactseq = Show a thinh vertical color line for each sequence position
    • width: total width of the motif (or sequence position width if seq motif type)
    • height: total height of the motif (or sequence position height if seq motif type)
    • fgcolor: color for the motif shape border
    • bgcolor: motif background color. Color code or name can be preceded with the “rgradient:” tag to create a radial gradient effect.
    • text_label: a text label in the format ‘FontType|FontSize|FontColor|Text’, for instance, arial|8|white|MotifName”“
  • gap_format (line) – default shape for the gaps between motifs
  • seq_format (blockseq) – default shape for the seq regions not covered in motifs
class BarChartFace(values, deviations=None, width=200, height=100, colors=None, labels=None, min_value=0, max_value=None, label_fsize=6, scale_fsize=6)

New in version 2.2.

Parameters:
  • values – a list of values each representing a vertical bar.
  • width (200) – width of the bar chart.
  • height (100) – height of the bar chart
  • colors (None) – a list of colors, one per bar value
  • label (None) – a list of labels, one per bar
  • min_value (0) – min value to set the scale of the chart.
  • max_value (None) – max value to set the scale of the chart.
class PieChartFace(percents, width, height, colors=None, line_color=None)

New in version 2.2.

Parameters:
  • percents – a list of values summing up 100.
  • width – width of the piechart
  • height – height of the piechart
  • colors – a list of colors (same length as percents)
  • line_color – color used to render the border of the piechart (None=transparent)
class ProfileFace(max_v, min_v, center_v, width=200, height=40, style='lines', colorscheme=2, values_vector=None, deviations_vector=None)

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).

Parameters: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.

Parameters: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:
../_images/svg_colors.png
COLOR_SCHEMES
random_color(h=None, l=None, s=None, num=None, sep=None, seed=None)

returns the RGB code of a random color. Hue (h), Lightness (l) and Saturation (s) of the generated color could be fixed using the pertinent function argument.