Functions¶
- plot_phylo.plot_phylo.plot_phylo(tree, ax, xpos=0, ypos=0, width=10, height=10, show_axis=False, show_support=True, align_tips=False, rev_align_tips=False, branch_lengths=True, scale_bar=True, scale_bar_width=None, reverse=False, outgroup=None, col_dict={}, label_dict={}, font_size=10, line_col='black', line_width=1, bold=[], collapse=[], collapse_names=[], auto_ax=True, dots=False)¶
Parameters¶
- treestr
Either the path to a newick formatted tree or a string containing a newick formatted tree. Required.
- axmatplotlib.axes._axes.Axes
An open matplotlib ax object where the tree will be plotted. Required.
- xposfloat
Desired position of the root node of the tree on the x axis of ax, in axis units. Default 0.
- yposfloat
Desired position of the bottom of the tree on the y axis of ax, in axis units. Default 0.
- heightfloat
Desired height of the tree, in axis units. Default 10.
- widthfloat
Desired width of the tree, in axis units. Default 10.
- show_axisbool
Show the axis on the output tree. Default True. This can be toggled later directly on the matplotlib ax.
- show_supportbool
Display branch support on the internal nodes of the tree. Default False.
- align_tipsbool
If True, the tip labels will be aligned rather than positioned at the end of the branches. Default False.
- rev_align_tips: bool
If True the tip labels are right aligned if reverse=False and left aligned if reverse=True.
- branch_lengthsbool
If True, the branch lengths provided in the tree are used, otherwise all branches are fixed to the same length. Default True.
- scale_bar: bool
If True and branch_lengths is True, draw a scale bar.
- scale_bar_width: float
Width of scale bar in axis units. If not specified, the scale bar will be 1/4 of the width of the tree.
- reverse: bool
If True, reverse the tree on the y-axis, showing the root on the right hand side. Default False.
- outgroup: str
Leaf to use as an outgroup, must be identical to the name of the leaf in the tree file.
- col_dictdict
User provided dictionary with tip labels as keys and colours (in any format accepted by matplotlib
as values. If this is not specified all labels will be black, if only some labels are specified all others will be black.
- label_dict: dict
User provided dictionary with current tip labels as keys and desired tip labels as values. If this is not specified all labels will be as specified in the newick, if some labels are specified all others will match the newick.
- font_sizeint
Font size for tip labels. Default 10.
- line_colstr or tuple
Line colour, in any format allowed by matplotlib https://matplotlib.org/stable/users/explain/colors/colors.html. Default is black.
- line_widthfloat
Line width. Default 2.
- bold: list
List of tip labels to show in bold.
- collapse: list
List of strings to search for in the tip labels of monophyletic clades and collapse if the string is found in all labels
- collapse_names: list
Names, in the same order as collapse, for the collapsed nodes from the collapse list
- auto_ax: bool
If True, determine axis limits automatically
Returns¶
- boxesdict
Dictionary where keys are tip labels and values are the boundary box on the image of each tip label.
- plot_phylo.draw_tree.add_leaf(tree, ax, ps, posi, appearance, structure, collapse, collapseD, countD, dots=False)¶
Function to position and label the leaves of the tree.
Parameters¶
- treeete3.Tree
ete3 Tree object
- axmatplotlib.axes._axes.Axes
An open matplotlib ax object
- ps: list
Used internally, list of tip labels and x and y positions
- posi: dict
Dictionary with position parameters
- appearance: dict
Dictionary with appearance parameters
- structure: dict
Dictionary with structure parameters
- collapse: list
List of strings to search for in the tip labels of monophyletic clades and collapse if the string is found in all labels
- collapseD: dict
Dictionary showing which nodes to collapse and the replacement names
- countD: dict
Dictionary of how many leaves are represented by collapsed nodes
- dots: bool
Not yet implemented
Returns¶
- y+posi[‘yint’]: int
The y-axis position of the leaf
- y: int
Previous position on y axis
- ps: list
Used internally, list of tip labels and x and y positions
- plot_phylo.draw_tree.adjust_dots(ax, xpos, ypos, markersize)¶
Currently not fully implemented
- plot_phylo.draw_tree.collapse_nodes(tree, collapse_list, collapse_names)¶
Function to collapse monophyletiic groups in which all tip labels contain a particular strings. Works by replacing the node with one of its leaves and setting the branch length to the mean for the clade.
Parameters¶
- treeete3.Tree
ete3 Tree object
- collapse_list: list
List of strings to search for in the tip labels of monophyletic clades and collapse if the string is found in all labels
- collapse_names: list
Names, in the same order as collapse, for the collapsed nodes from the collapse list
Returns¶
- tree: ete3.Tree
The edited tree object with COLLAPSE in the relevant leaf names
- collapseD: dict
Dictionary where keys are the edited names of the leafs representing collapsed nodes and values are the new name this collapsed node should be given in the tree.
- countD: dict
Dictionary showing how many leaves are represented by each collapsed node
- plot_phylo.draw_tree.draw_tree(tree, ax, x=0, y=0, x0=0, ps=[], dims={'depth': [5, 5, 5], 'height': 10, 'width': 10}, structure={'align_tips': False, 'branch_lengths': True, 'rev_align_tips': False, 'reverse': False}, appearance={'bold': [], 'col_dict': {}, 'font_size': 10, 'label_dict': {}, 'line_col': 'black', 'line_width': 1, 'show_support': True}, collapse=[], collapseD={}, countD={}, dots=False)¶
Plot a phylogenetic tree in matplotlib
Parameters¶
- treeete3.Tree
ete3 Tree object
- axmatplotlib.axes._axes.Axes
An open matplotlib ax object
- xfloat
Current position on x axis.
- yfloat
Current position on y axis.
- ps: list
Used internally, list of tip labels and x and y positions
- height: float
Height of the tree in axis units
- width: float
Width of the tree in axis units
- depth: tuple(float, float, float)
Total height and width of the original tree in terms of number of nodes, total branch length, number of tips
- align_tips: bool
If True, the tip labels will be aligned rather than positioned at the end of the branches. Default False.
- rev_align_tips: bool
If True the tip labels are right aligned if reverse=False and left aligned if reverse=True.
- branch_lengths: bool
If True, use the branch lengths provided in the tree, otherwise fix all branches to the same length. Default True.
- reverse: bool
If True, reverse the tree on the y-axis, showing the root on the right hand side. Default False.
- appearance: dict
Dictionary of parameters specifying the appearance of the tree.
- collapse: list
Collapse nodes where possible based on strings in the list.
- collapseD:
Dictionary where keys are the edited names of the leafs representing collapsed nodes and values are the new name this collapsed node should be given in the tree.
Returns¶
- y float
Position of previous node on y axis.
- ym float
Position of current node on y axis.
- ps list
List of lists - ordered as tip labels, tip label text objects, alignment lines (if aligned). All are in the same order.
- plot_phylo.amend_tree.auto_axis(ax, textobj, xpos, ypos, width, height, depth, scale_bar, branch_lengths, reverse)¶
Adjust the axis limits around the tree automatically (rather than using user definted values).
Parameters¶
- axmatplotlib.axes._axes.Axes
An open matplotlib ax object
- textobj: list of matplotlib.text.Text
List of text objects containing tip labels, used to ensure the labels are within the limits of the plot
- xposfloat
User defined desired position of the root node of the tree on the x axis of ax, in axis units.
- yposfloat
User defined desired position of the bottom of the tree on the y axis of ax, in axis units.
- heightfloat
User defined desired height of the tree, in axis units. Default 10.
- widthfloat
User defined desired width of the tree, in axis units. Default 10.
- depth: tuple(float, float, float)
Total height and width of the original tree in terms of number of nodes, total branch length, number of tips
- scale_bar: bool
User defined - True to draw a scale bar, else False
- branch_lengths: bool
User defined - True to use true branch lengths, False to use fixed branch lengths
- reverse: bool
If True, the tree is reversed on the y-axis, showing the root on the right hand side. Default False.
Returns¶
- cboxes: dict
Dictionary where keys are tip labels and values are the boundary boxes of the tip labels on the plot
- ax: matplotlib.axes._axes.Axes
A modified open matplotlib ax object
- plot_phylo.amend_tree.draw_scale_bar(ax, width, height, depth, left, bottom, scale_bar_width=None, appearance={'font_size': 10})¶
Adds a scale bar to the tree - only when branch lengths are specified.
The default length is 0.25 * total tree width, or it can be specified using scale_bar_width.
Parameters¶
- axmatplotlib.axes._axes.Axes
An open matplotlib ax objectmatplotlib.axes._axes.Axes An open matplotlib ax object
- heightfloat
Height of the tree, in axis units.
- widthfloat
Width of the tree, in axis units.
- depth: tuple(float, float, float)
Total height and width of the original tree in terms of number of nodes, total branch length, number of tips
- bottom: float
The bottom position of the tree on the y axis
- scale_bar_width: float
The desired width of the scale bar, if not specified tree width * 0.25 is used
- appearance: dict
Dictionary of parameters specifying the appearance of the tree.
- plot_phylo.amend_tree.reverse_align(ax, ps, reverse)¶
Realigns the text in the tip labels so that for a standard tree, the text is right aligned, for a mirrored tree (root on the right), the text is left aligned. Only used when tip labels are set to be aligned.
This has to happen once the whole plot is drawn as the limits of the text only exist once the text exists.
Parameters¶
- axmatplotlib.axes._axes.Axes
An open matplotlib ax object
- pslist
List of lists - ordered as tip labels, tip label text objects, alignment lines (if aligned). All are in the same order.
- reverse: bool
If True, reverse the tree on the y-axis, showing the root on the right hand side. Default False.
Returns¶
- ps_newlist
List of lists - ordered as tip labels, tip label text objects, alignment lines (if aligned). All are in the same order. Updated based on new alignment.
- plot_phylo.get_boxes.get_boxes(ax, texts)¶
Converts a list of text objects to their co-ordinates on the axis in axis units.
Parameters¶
- axmatplotlib.axes._axes.Axes,
An open matplotlib ax object where the tree will be plotted.
- textslist
A list of matplotlib.pyplot.text objects representing the tip labels from the tree and their metadata.
Returns¶
- boxposdict
A dictionary of dictionaries where the top level keys are the tip labels. Within each subdictionary the key value pairs are index (position in the tree starting from the top) and the minimum, maximum and central position of the text box on the x and y axis, as index, xmin, xmid, xmax and ymin, ymid and ymax.