Tutorial.md

Tutorial

Node and Tree classes.

To make a tree in the treeplotter library, we create nodes, links between them, and finally store them in a tree. First, let's import the package and create a root node object.

>>> from treeplotter.tree import Node, Tree
>>> root = Node(value=1.0, name=None)

Now lets say this root has three initial children, only one of which has a name. Let's create these children and then set their relationship to root.

>>> child1 = Node(value=0.5, name=None)
>>> child2 = Node(value=1.0, name=None)
>>> child3 = Node(value=3.0, name="A")
>>> root.children = {child1, child2, child3}
>>> root.children
{<tree.Node value=0.5, name=None>, <tree.Node value=1.0, name=None>, <tree.Node value=3.0, name=A>}

Let's now create some grandchildren and a single great-grandchild in the tree:

>>> granchild1 = Node(value=0.5, name=None)
>>> granchild2 = Node(value=3.0, name="B")
>>> granchild3 = Node(value=2.0, name="C")
>>> greatgrandchild = Node(value=1.0, name="D")

We can add a list of children to a given node via the Node.add_children method. We can also add a single child with ther Node.add_child method.

>>> child1.add_children([granchild1, granchild2])
>>> child2.add_child(granchild3)
>>> granchild1.add_child(greatgrandchild)

Also included in treeplotter is a method for easily creating several nodes as a "lineage" called Node.add_path_of_children. The values provided will then automatically create nodes and set their relationships. Let's add two paths of children from the root.

>>> value_path = [root.value, 4.0, 1.0, 0.5, 2.0]
>>> root.add_path_of_children(path=value_path, final_node_name="Full path")

>>> value_path_2 = [root.value, 1.0, 2.0, 1.0]
>>> root.add_path_of_children(path=value_path_2, final_node_name="Testing overwrite")

To create a Tree object, just pass the root node!

>>> tree = Tree(root=root)
>>> tree
<tree.Tree nodes=13>

There are several other properties and methods for working with trees in the package. See the source for these.

Making a Tree Diagram

We now have our tree object in the package. But who cares? We want to see it! To do so, use the plotter.create_tree_diagram function. Pass our tree to the tree parameter. If you'd like to save a screenshot of the tree (assuming you've followed the proper install instructions in Installation.md), pass webshot=True to the function. The save_path is a path to a folder which will be created upon running the function. For instance, if I wanted to save the visualization to a folder called mytree in my home directory, I would use:

>>> from treeplotter.plotter import create_tree_diagram
>>> create_tree_diagram(
...     tree=tree,
...     save_path="/Users/lukepoeppel/mytree",
...     webshot=True,
...     verbose=True
... )
>>> # This will display some logs and save an image of the tree to your desired directory. 

Additionally, you can call tree.show(save_path, verbose) to return (and save) a wand.Image object. This is useful when working with the package in Jupyter, for example. This method will return a file called shot.png in the requests save_path directory. The above tree creates the following image:

Image Support and Styling

You can attach an image to a node object to display it in the visualization. Here's a demo of some of the ways we can style a tree (wrapping TreantJS and Raphaël). First, we create three nodes with images:

>>> n1 = Node(name="Cat", image="/Users/lukepoeppel/treeplotter/tests/static/cat_small.jpg")
>>> n2 = Node(name="Friend O' Cat", image="/Users/lukepoeppel/treeplotter/tests/static/owl_small.jpg")
>>> n3 = Node(name="Foe O' Cat", image="/Users/lukepoeppel/treeplotter/tests/static/rabbit_small.jpg")
>>> n1.add_children([n2, n3])

We would like the connectors between the nodes to be step-wise and the ends to be arrows. We can do this by using ConnectorStyle:

>>> from treeplotter.style import ConnectorStyle
>>> arrow_connector = ConnectorStyle(
...     arrow_end="classic", # these come from the Raphaël documentation. 
...     arrow_width="wide",
...     arrow_length="long"
... )

We also want the nodes in our tree to be baby-blue with a border radius of 10px. We can customize the node's style using NodeStyle:

>>> from treeplotter.style import NodeStyle
>>> node_style = NodeStyle(
...     background_color="#89ADF0",
...     border_radius="10px"
... )

Let's now create our tree. There are two final customizations allowed in the Tree class: the orientation and connector_type (options are "curve", "bCurve", "step", and "straight"). We can pass all of the information to the tree as follows:

>>> animal_tree = Tree(
...     root=n1,
...     connector_type="step",
...     connector_style=arrow_connector,
...     orientation="west",
...     node_style=node_style
... )

Now when we create our diagram, we want the background color of the HTML file (and screenshot) to be red. We can do this by setting a hex color in the background_color parameter:

>>> create_tree_diagram(
...     tree=animal_tree,
...     save_path="/Users/lukepoeppel/treeplotter/tests/t14",
...     background_color="#cf2b2b",
...     webshot=True,
...     verbose=True
... )

This creates the following image: