# Counting topologies#

**Yan Wong**

This tutorial is intended to be a gentle introduction to the combinatorial
treatment of tree topologies in `tskit`

. For a more formal introduction,
see the Identifying and counting topologies section of the
official `tskit`

documentation.

The *topology* of a single tree is the term used to describe the branching pattern,
regardless of the lengths of the branches. For example, both trees below have the
same topology, although the branch lengths differ:

```
import tskit
node_labels = {0: "a", 1: "b", 2: "c"} # avoid confusion by using letters to label tips
tree = tskit.Tree.generate_comb(3)
display(tree.draw_svg(node_labels=node_labels, y_axis=True))
deep_tree = tskit.Tree.generate_comb(10).tree_sequence.simplify([0, 1, 2]).first()
display(deep_tree.draw_svg(node_labels=node_labels, y_axis=True))
```

Note

The treatment of topologies in `tskit`

is restricted to trees with a single defined root,
without nodes with a single child (i.e. trees must consist of nodes that are either leaves,
or internal nodes with two or more children). For convenience in the examples
below, trees are drawn with the tips flagged as samples, although whether a node is a sample or
not does not change the topology of the tree.

## Tree labellings and shapes#

The topology of a tree also takes into account the labelling of tips, so that
the trees below, although they have the same *shape*, count as three
different topologies:

## Show code cell source

```
from string import ascii_lowercase
from IPython.display import SVG
def str_none(s, prefix=None):
if s is not None:
if prefix is None:
return str(s)
else:
return prefix + " = " + str(s)
return None
def draw_svg_trees(trees, node_labels={}, x_lab_attr=None, width=100, height=150, space=10):
w = width + space
h = height + space
trees = list(trees)
s = f'<svg height="{h}" width="{w * len(trees)}" xmlns="http://www.w3.org/2000/svg">'
s += f'<style>.x-axis {{transform: translateY({space}px)}}</style>'
for i, tree in enumerate(trees):
s += tree.draw_svg(
size=(width, height),
canvas_size=(w, h),
root_svg_attributes={"x": i * w},
node_labels=node_labels,
x_label=str_none(getattr(tree.rank(), x_lab_attr or "", None), x_lab_attr)
)
s += '</svg>'
return SVG(s)
draw_svg_trees(tskit.all_tree_labellings(tree), node_labels={u: ascii_lowercase[u] for u in tree.samples()})
```

These are, in fact, the only possible three labellings for a three-tip tree of that shape. There is only one other possible shape for a three-tip tree, and for this shape, all labelling orders are equivalent (in other words, there is only one possible labelling):

## Show code cell source

```
tskit.Tree.generate_star(3).draw_svg(node_labels={})
```

A 3-tip tree therefore has only four possible topologies.
These can be generated with the `all_trees()`

function.

```
generated_trees = tskit.all_trees(3)
print("For a three-tip tree there are", len(list(generated_trees)), "labelled topologies.")
```

```
For a three-tip tree there are 4 labelled topologies.
```

Here they are, plotted out with their shapes enumerated from zero:

## Show code cell source

```
draw_svg_trees(
tskit.all_trees(3),
node_labels={u: ascii_lowercase[u] for u in tree.samples()},
x_lab_attr="shape"
)
```

### Enumerating shapes and labellings#

For a tree with four tips, more topologies and shapes are possible. As before, we can generate the
topologies using `all_trees()`

. Alternatively, if we only want the (unlabelled) shapes,
we can use the `all_tree_shapes()`

function:

```
print("For a four-tip tree there are", len(list(tskit.all_trees(4))), "labelled topologies.")
generated_trees = tskit.all_tree_shapes(4)
print("These can be categorised into", len(list(generated_trees)), "shapes.")
```

```
For a four-tip tree there are 26 labelled topologies.
These can be categorised into 5 shapes.
```

Again, we can give each shape a number or *index*, starting from zero:

## Show code cell source

```
draw_svg_trees(tskit.all_tree_shapes(4), x_lab_attr="shape")
```

Each of these shapes will have a separate number of possible labellings, and trees with
these labellings can be created using `all_tree_labellings()`

:

```
for shape_index, tree in enumerate(tskit.all_tree_shapes(4)):
labellings = tskit.all_tree_labellings(tree)
num_labellings = len(list(labellings))
print(
f"Tree shape {shape_index} for a four-tip tree has "
f"{num_labellings} labelling{'' if num_labellings==1 else 's'}."
)
```

```
Tree shape 0 for a four-tip tree has 1 labelling.
Tree shape 1 for a four-tip tree has 6 labellings.
Tree shape 2 for a four-tip tree has 4 labellings.
Tree shape 3 for a four-tip tree has 12 labellings.
Tree shape 4 for a four-tip tree has 3 labellings.
```

Any tree topology for a tree of \(N\) tips can therefore be described by a
shape index combined with a labelling index. This is known as the
*rank* of a tree, and it can be obtained using the
`Tree.rank()`

method. For instance, here is the rank of a simulated tree
of 10 tips:

## Show code cell source

```
import msprime
num_tips = 10
simulated_ts = msprime.sim_ancestry(10, ploidy=1, random_seed=123)
simulated_tree = simulated_ts.first()
print("The topology of the simulated tree below can be described as", simulated_tree.rank())
ascii_node_labels = {u: ascii_lowercase[u] for u in simulated_tree.samples()}
simulated_tree.draw_svg(node_labels=ascii_node_labels)
```

```
The topology of the simulated tree below can be described as Rank(shape=1270, label=205540)
```

A tree with the same topology (i.e. the same shape and labelling, but ignoring
the branch lengths) can be generated using the `Tree.unrank()`

method, by
specifying the number of tips and the appropriate `(shape, labelling)`

tuple:

```
new_tree = tskit.Tree.unrank(num_tips, (1270, 21580))
new_tree.draw_svg(node_labels=ascii_node_labels)
```

Note that this method generates a single tree in a new tree sequence whose a default sequence length is 1.0.

## Methods for large trees#

The number of possible topologies for a tree with \(N\) tips grows very rapidly with \(N\). For instance, with 10 tips, there are 282,137,824 possible topologies.

For this reason, the `all_trees()`

, `all_tree_shapes()`

and
`all_tree_labellings()`

methods do not return a list of trees
but an iterator over the trees. This means it is perfectly possible to start
iterating over (say) all tree shapes for a tree of 100 leaves, but
the iterator will not finish before the death of our galaxy.

```
for num_trees, tree in enumerate(tskit.all_tree_shapes(100)):
shape = tree.rank().shape
b2 = tree.b2_index()
print(f"A 100-tip tree with shape index {shape} has a b2 balance index of {b2}")
if num_trees > 5:
break # better not let this run too long!
```

```
A 100-tip tree with shape index 0 has a b2 balance index of 2.0000000000000013
A 100-tip tree with shape index 1 has a b2 balance index of 1.9986759016244608
A 100-tip tree with shape index 2 has a b2 balance index of 1.9960946599243323
A 100-tip tree with shape index 3 has a b2 balance index of 1.9958336776669476
A 100-tip tree with shape index 4 has a b2 balance index of 1.9973695449917637
A 100-tip tree with shape index 5 has a b2 balance index of 1.992978538300552
A 100-tip tree with shape index 6 has a b2 balance index of 1.9927249774271467
```

For similar combinatorial reasons, the `Tree.rank()`

method can be
inefficient for large trees. To compare the topology of two trees, you are
therefore recommended to use e.g. the `Tree.kc_distance()`

method
rather than comparing ranks directly.

```
simulated_tree = simulated_ts.first(sample_lists=True) # kc_distance requires sample lists
if simulated_ts.first(sample_lists=True).kc_distance(simulated_tree) == 0:
print("Trees are identical")
# To compare to the new_tree we need to fix
# print("The simulated and topology-constructed trees have the same topology")
```

```
Trees are identical
```

Despite the combinatorial explosion associated with topologies of
many-tip trees, it is still possible to efficiently count
the number of *embedded topologies* in a large tree.

### Embedded topologies#

An embedded topology is a a topology involving a subset of the tips of a tree.
If the tips are classified into (say) three groups, red, green, and blue,
we can efficiently count all the embedded three-tip trees which have
one tip from each group using the `Tree.count_topologies()`

method.

## Show code cell source

```
big_tree = tskit.load("data/topologies_sim_speciestree.trees").first()
# Check all observed topologies have the same counts
assert list(big_tree.count_topologies()[0, 1, 2].values()) == [32, 32]
styles = [
f".node.sample.p{p.id} > .sym " + "{" + f"fill: {colour}" + "}"
for colour, p in zip(['red', 'green', 'blue'], big_tree.tree_sequence.populations())
]
big_tree.draw_svg(style="".join(styles), node_labels={}, time_scale="rank", x_label="big_tree")
```

In this tree, it is clear that the green and blue tips never cluster together.
The `Tree.count_topologies()`

method exhaustively looks at all
combinations of one red, one blue, and one green tip, and confirms that we never see
the topology grouping green and blue. However, as might be expected from
examination of the plot above, a red tip is equally likely to be a sister to a
green tip as to a blue tip:

```
# By default `count_topologies` chooses one tip from each population, like setting
# sample_sets=[ts.samples(p.id) for p in ts.populations() if len(ts.samples(p.id)) > 0]
topology_counter = big_tree.count_topologies()
colours = ['red', 'green', 'blue']
styles = [f".n{u}>.sym {{fill: {c} }}" for u, c in enumerate(colours)]
embedded_counts = topology_counter[0, 1, 2]
for embedded_tree in tskit.all_trees(3):
rank = embedded_tree.rank()
number_of_instances = embedded_counts[rank]
label = f"{number_of_instances} instances embedded in big_tree"
display(embedded_tree.draw_svg(style="".join(styles), node_labels={}, x_label=label))
```

## Methods over tree sequences#

It can be useful to count embedded topologies over an entire tree sequence.
For instance, we might want to know the number of embedded topologies
that support Neanderthals as a sister group to europeans versus africans.
`Tskit`

provides the efficient `TreeSequence.count_topologies()`

method to
do this incrementally, without having to re-count the topologies
independently in each tree.

## Show code cell source

```
from myst_nb import glue
ts = tskit.load("data/topologies_sim_stdpopsim.trees")
print(f"Loaded a stdpopsim of {ts.num_trees} African+European+Chinese trees, each with {ts.num_samples} tips")
glue("seq_len", int(ts.sequence_length/1000), display=False)
```

```
Loaded a stdpopsim of 465 African+European+Chinese trees, each with 6000 tips
```

Although the trees in this tree sequence are very large, counting the embedded topologies is quite doable (for speed in this demo we are only simulating 49 kilobases, but calculating the average over an entire chromosome simply takes a little longer)

```
from datetime import datetime
names = {"YRI": "African", "CEU": "European", "CHB": "Chinese"}
colours = {"YRI": "yellow", "CEU": "green", "CHB": "blue"}
population_map = {p.metadata["id"]: p.id for p in ts.populations()}
sample_populations = list(sorted({ts.node(u).population for u in ts.samples()}))
topology_span = {tree.rank(): 0 for tree in tskit.all_trees(len(sample_populations))}
start = datetime.now()
total = 0
for topology_counter, tree in zip(ts.count_topologies(), ts.trees()):
embedded_topologies = topology_counter[sample_populations]
weight = tree.span / ts.sequence_length
for rank, count in embedded_topologies.items():
topology_span[rank] += count * weight
total += count
print(f"Counted {total} embedded topologies in {datetime.now() - start} seconds")
```

```
Counted 3720000000000 embedded topologies in 0:00:07.953739 seconds
```

## Show code cell source

```
ntips = len(sample_populations)
styles = ".sample text.lab {baseline-shift: super; font-size: 0.7em;}"
node_labels = {}
for p in range(ntips):
name = ts.population(sample_populations[p]).metadata["id"]
node_labels[p] = names[name]
styles += f".n{p}>.sym {{fill: {colours[name]} }}"
total = sum(topology_span.values())
for rank, weight in topology_span.items():
label = f"{weight/total *100:.1f}% of genome"
embedded_tree = tskit.Tree.unrank(ntips, rank)
display(embedded_tree.draw_svg(size=(160, 150), style="".join(styles), node_labels=node_labels, x_label=label))
```

Perhaps unsurprisingly, the most common topology is the one that groups the non-African populations together (although there are many trees of the other two topologies, mostly reflecting genetic divergence prior to the emergence of humans out of Africa).

For an example with real data, see Topological analysis in the Tskit for population genetics tutorial.