API Reference

strainchoosr.create_colored_tree_tip_image(tree_to_draw, representatives, output_file, color='red', mode='r', rotation=0)

Given a list of representatives, shows (for now) a phylogeny that has those representatives highlighted in a color to show it off.

Parameters:
  • tree_to_draw – an ete3 Tree object. This won’t get modified at any point.
  • representatives – List with each strain name that should be highlighted.
  • output_file – File to write output to, including extension. Works with .pdf, .png, and .svg
  • color – Color to show selected strains as. Defaults to red. Other choices available can be found at http://etetoolkit.org/docs/latest/reference/reference_treeview.html#ete3.SVG_COLORS
  • mode – method for tree drawing - options are r for rectangular or c for circular
  • rotation – how much to rotate the tree (in a clockwise direction). Default is 0.
strainchoosr.find_next_leaf(diverse_leaves, tree)

Given a set of leaves we’ve already decided represent the most diversity, find the next leaf that contributes the most diversity.

Parameters:
  • diverse_leaves – List of leaves that we’ve already decided represent the most diversity possible - each entry in this list should be an ete3.TreeNode object
  • tree – an ete3.Tree object that contains the nodes listed in diverse_leaves
Returns:

an ete3.TreeNode object representing the leaf that adds the most diversity to diverse_leaves
strainchoosr.find_starting_leaves(tree, starting_leaf_list)

Gets the start of what the most diverse set of strains should be. If starting_leaf_list has nothing in it, the two strains that are the farthest apart will be picked (longest total branch length between them). If there is one entry in starting leaf list, the list returned will be that leaf plus whatever leaf on the tree is the farthest from it. If more than two leaves are in starting_leaf_list, nothing happens and just the original list will get returned.

Parameters:
  • tree – An ete3.Tree object
  • starting_leaf_list – A list of ete3.TreeNode objects.
Returns:

A list of ete3.TreeNode objects representing the most diverse starting set possible
strainchoosr.generate_html_report(completed_choosr_list, output_report)

Generates a nice(ish) looking HTML report detailing StrainChoosr output.

Parameters:
  • completed_choosr_list – List of CompletedChoosr objects - each of these has a list of leaf names, path to an image file, and a name
  • output_report – filename to write HTML report. Will overwrite a report that already exists.
strainchoosr.get_leaf_names_from_nodes(leaf_nodes)

Given a list of ete3.TreeNode objects, will give the node names for each one.

Parameters:leaf_nodes – List of ete3.TreeNode objects.
Returns:list of the names of the TreeNode objects.
strainchoosr.get_leaf_nodes_from_names(tree, leaf_names)

Given a list of names and a phylogenetic tree, returns an ete3.TreeNode object for each leaf name. If a node can’t be found, a RuntimeError is raised. If more than one leaf has the same name, only the first will be returned.

Parameters:
  • tree – An ete3.Tree object.
  • leaf_names – List of leaf names that
Returns:
strainchoosr.get_version()

Uses pkg_resources to figure out what version StrainChoosr is.

Returns:StrainChoosr X.Y.Z if a version was found, otherwise StrainChoosr (Unknown version)
strainchoosr.modify_tree_with_weights(tree, weights)

Given an ete3 Tree object and a dictionary where keys are node names in the tree and values are multipliers (can be generated with read_weights_file), returns a new tree where each branch in the weights dictionary is multiplied by the multiplier specified.

Parameters:
  • tree – an ete3.Tree object
  • weights – Dictionary where keys are names of nodes/tips in the tree, and values are weights by which branch lengths will be multiplied
Returns:

A new ete3.Tree where branch lengths have been modified.
strainchoosr.pd_greedy(tree, number_tips, starting_strains)

Implements the greedy algorithm described in Species Choice for Comparative Genomics: Being Greedy Works (Pardi 2005 and Phylogenetic Diversity and the Greedy Algorithm (Steel 2005).

Parameters:
  • tree – An ete3.Tree object
  • number_tips – Number of strains you want to pick out.
  • starting_strains – List of ete3.TreeNode objects that make up your starting strains. If empty, will be chosen automatically
Returns:

List of ete3.TreeNode objects representing the maximum possible amount of diversity.
strainchoosr.read_weights_file(weights_file)

Given a tab separated file with leaf names for a phylogenetic tree in column one and multipliers for that leaf’s branch length in column two, will create a dictionary with leaf names as keys and multipliers as values

Parameters:weights_file – Path to a tab-separated text file described above.
Returns:dictionary with leaf names as keys and multipliers as values
strainchoosr.run_strainchoosr(treefile, number_representatives, starting_strains=[], output_name='strainchoosr_output', tree_mode='r', weight_file=None, verbosity='info', rep_strain_color='red')

Runs the strainchoosr pipeline and prints strains picked as diverse to the terminal.

Parameters:
  • treefile – Path to a newick-formatted treefile.
  • number_representatives – List of numbers of representatives.
  • starting_strains – List of leaf names that should make up starting strains. Defaults to nothing, so starting strains automatically get chosen
  • output_name – Base name for output file - defaults to strainchoosr_output
  • tree_mode – Mode for displaying tree in output HTML file. Can be r for rectangualar or c for circular. Defaults to r.
  • weight_file – If specified, is a path to a file that modifies branch lengths. File should be tab-separated, with leaf names in column one and multiplier in column two
  • verbosity – verbosity level: options are debug for loads of information, info for regular amounts, or warning for almost none.
  • rep_strain_color – Color for strains picked to be shown in html report. Defaults to red.
Returns:

dictionary where number of strains is the key and the value is a list of representatives