Make tskit formatting consistent

Author: hyanwong

phylogen.md

@@ -16,9 +16,10 @@ kernelspec:
 
 (sec_phylogen)=
 
-# `Tskit` for phylogenetics
+# {program}`Tskit` for phylogenetics
 
-`Tskit`, the tree sequence toolkit, can be used as an efficient library for very large evolutionary trees. `Tskit` makes it easy to deal with trees with millions of
+{program}`Tskit`, the tree sequence toolkit, can be used as an efficient library for
+very large evolutionary trees. {program}`Tskit` makes it easy to deal with trees with millions of
 tips, as in the example below:
 
 ```{code-cell}
@@ -77,7 +78,7 @@ import tsconvert  # used for reading tree sequences from different formats
 ts = tsconvert.from_newick("(A:6,((B:1,C:1):2,(D:2,E:2):1):3);", span=1000)
 ```
 
-The "succinct tree sequence" format used by `tskit` can also store mutations
+The "succinct tree sequence" format used by {program}`tskit` can also store mutations
 (and optionally a reference genome) along with the tree(s). This results in a
 single unified representation of large genomic datasets, storing trees,
 sequence data and metadata in a single efficient structure. Examples are given
@@ -92,11 +93,11 @@ sorting. An overview, and links to further details are given at the
 
 ## Hints for phylogeneticists
 
-Unlike other phylogenetic libraries, `tskit` is designed to efficiently store not just 
+Unlike other phylogenetic libraries, {program}`tskit` is designed to efficiently store not just 
 single trees, but sequences of correlated trees along a genome. This means that the
 library has some features not found in more standard phylogenetic libraries.
 Here we focus on the {ref}`sec_python_api`,
-introducing seven `tskit` concepts that may be useful to those with a background in
+introducing seven {program}`tskit` concepts that may be useful to those with a background in
 phylogenetics (each is linked to a separate section below):
 
 1. An evolutionary tree is always contained within a "tree sequence".
@@ -149,7 +150,7 @@ tree.tree_sequence  # When output in a notebook, prints a summary of the tree se
 (sec_phylogen_ids)=
 ### Integer node and edge IDs
 
-The plot above labels nodes by their name, but internally the `tskit` library relies
+The plot above labels nodes by their name, but internally the {program}`tskit` library relies
 heavily on integer IDs. Here's the same tree with node IDs plotted instead:
 
 ```{code-cell}
@@ -164,9 +165,9 @@ integer ID starting from 0 to `ts.num_nodes - 1` (IDs can be allocated in any or
 often the tips are labelled starting from 0 but this is not necessarily so, and
 is not the case in the example above).
 
-For efficiency reasons, tree traversal routines, as well as many other `tskit` methods,
-tend to return integer IDs. You can use this ID to get specific information about the
-node and its position in the tree, for example
+For efficiency reasons, tree traversal routines, as well as many other {program}`tskit`
+methods, tend to return integer IDs. You can use this ID to get specific information
+about the node and its position in the tree, for example
 
 ```{code-cell}
 node_id = 4
@@ -187,8 +188,8 @@ Other methods also exist to
 Rather than refer to "branches" of a tree, tskit tends to refer to
 {ref}`sec_terminology_edges` (the term "edge" emphasises that these can span
 {ref}`sec_phylogen_multiple_trees`, although for tree sequences containing a single
-tree, the terms are interchangeable). Like other entities in `tskit`, edges are referred
-to by an integer ID. For instance, here is the edge above the internal node 4
+tree, the terms are interchangeable). Like other entities in {program}`tskit`, edges
+are referred to by an integer ID. For instance, here is the edge above the internal node 4
 
 ```{code-cell}
 node_id = 4
@@ -233,7 +234,7 @@ Often we are only have detailed information about specific nodes that we have sa
 such as genomes A, B, C, D, and E in the example above. These are designated as
 *sample nodes*, and are plotted as square nodes. The concept of
 {ref}`sample nodes<sec_data_model_definitions_sample>` is integral
-to the `tskit` format. They can be identified by using the
+to the {program}`tskit` format. They can be identified by using the
 {meth}`Node.is_sample` and {meth}`Tree.is_sample` methods, or can be listed using
 {meth}`TreeSequence.samples` or {meth}`Tree.samples()` (internally, the `node.flags`
 field is used to {ref}`flag up<sec_node_table_definition>` which nodes are samples):
@@ -283,19 +284,19 @@ tree.tree_sequence.nodes_time
 (sec_phylogen_node_time)=
 ### Nodes must have times
 
-Perhaps the most noticable different between a `tskit` tree and the encoding of trees
-in other phylogenetic libraries is that `tskit` does not explicitly store branch lengths.
+Perhaps the most noticable different between a {program}`tskit` tree and the encoding of trees
+in other phylogenetic libraries is that {program}`tskit` does not explicitly store branch lengths.
 Instead, each node has a *time* associated with it. Branch lengths can therefore be
 found by calculating the difference between the time of a node and the time of its
 parent node.
 
-Since nodes *must* have a time, `tskit` trees aways have these (implicit) branch
+Since nodes *must* have a time, {program}`tskit` trees aways have these (implicit) branch
 lengths. To represent a tree ("cladogram") in which the branch lengths are not
 meaningful, the {attr}`TreeSequence.time_units` of a tree sequence can be
 specified as `"uncalibrated"` (see below)
 
-Another implication of storing node times rather than branch lengths is that `tskit`
-trees are always directional (i.e. they are "rooted"). The reason that `tskit` stores
+Another implication of storing node times rather than branch lengths is that {program}`tskit`
+trees are always directional (i.e. they are "rooted"). The reason that {program}`tskit` stores
 times of nodes (rather than e.g. genetic distances between them) is to ensure temporal 
 consistency. In particular it makes it impossible for a node to be an ancestor of a
 node in one tree, and a descendant of the same node in another tree in the tree sequence.
@@ -310,7 +311,7 @@ print("Time units are", tree.tree_sequence.time_units)
 tree.draw_svg(y_axis=True)
 ```
 
-Although branch lengths are not stored explicitly, for convenience `tskit` provides a
+Although branch lengths are not stored explicitly, for convenience {program}`tskit` provides a
 {meth}`Tree.branch_length` method:
 
 ```{code-cell}
@@ -342,7 +343,7 @@ print(
 
 It is worth noting that this distance is the basis for the "genetic divergence"
 between two samples in a tree. For this reason, an equivalent way to carry out the
-calculation is to use {meth}`TreeSequence.divergence`, part of the the standard `tskit`
+calculation is to use {meth}`TreeSequence.divergence`, part of the the standard {program}`tskit`
 {ref}`sec_stats` framework, setting `mode="branch"` and
 `windows="trees"`. This is a more flexible approach, as it allows the distance between
 multiple sets of samples in {ref}`sec_phylogen_multiple_trees` to be calculated
@@ -364,7 +365,7 @@ print(
 (sec_phylogen_multiroot)=
 ### Roots and multiroot trees
 
-In `tskit`, {ref}`sec_data_model_tree_roots` of trees are defined with respect to the
+In {program}`tskit`, {ref}`sec_data_model_tree_roots` of trees are defined with respect to the
 sample nodes. In particular, if we move back in time along the tree branches from a
 sample, the oldest node that we encounter is defined as a root. The ID of a root can be
 obtained using {attr}`Tree.root`:
@@ -374,7 +375,7 @@ print("The root node of the following tree has ID", tree.root)
 tree.draw_svg()
 ```
 
-But in `tskit`, we can also create a single "tree" consisting of multiple unlinked
+But in {program}`tskit`, we can also create a single "tree" consisting of multiple unlinked
 clades. In our example, we can create one of these phylogenetically unusual objects
 if we remove the edge above node 4, by
 {ref}`editing the underlying tables<sec_tables_editing>`:
@@ -389,8 +390,8 @@ new_tree = new_ts.first()
 new_tree.draw_svg()
 ```
 
-Although there are two separate topologies in this plot, in `tskit` terminology, it is
-considered a single tree, but with two roots:
+Although there are two separate topologies in this plot, in {program}`tskit` terminology,
+it is considered a single tree, but with two roots:
 
 ```{code-cell}
 print("The first tree has", len(new_tree.roots), "roots:", new_tree.roots)
@@ -408,7 +409,7 @@ empty_tree.draw_svg()
 ```
 
 The samples here are {ref}`sec_data_model_tree_isolated_nodes`. This may seem like a
-strange corner case, but in `tskit`, isolated sample nodes are used to represent
+strange corner case, but in {program}`tskit`, isolated sample nodes are used to represent
 {ref}`sec_data_model_missing_data`. This therefore represents a tree in which
 relationships between the samples are not known. This could apply, for instance,
 in regions of the genome where no genetic data exists, or where genetic ancestry
@@ -429,7 +430,7 @@ Demo some phylogenetic methods. e.g.
 (sec_phylogen_unified_structure)=
 ## Storing and accessing genetic data
 
-`Tskit` has been designed to capture both evolutionary tree topologies and the genetic
+{program}`Tskit` has been designed to capture both evolutionary tree topologies and the genetic
 sequences that evolve along the branches of these trees. This is achieved by defining
 {ref}`sec_terminology_mutations_and_sites` which are associated with specific positions
 along the genome.
@@ -468,13 +469,13 @@ for node_id, alignment in zip(
 (sec_phylogen_multiple_trees)=
 ## Multiple trees
 
-Where `tskit` really shines is when the ancestry of your dataset cannot be adequately
+Where {program}`tskit` really shines is when the ancestry of your dataset cannot be adequately
 represented by a single tree. This is a pervasive issue in genomes (even from different
 species) that have undergone recombination in the past. The resulting series of
 {ref}`local trees<sec_what_is_local_trees>` along a genome are highly correlated
 (see {ref}`sec_concepts`).
 
-Instead of storing each tree along a genome separately, `tskit` records the genomic
+Instead of storing each tree along a genome separately, {program}`tskit` records the genomic
 coordinates of each edge, which leads to enormous efficiencies in storage and
 analysis. As a basic demonstration, we can repeat the edge removal example
 {ref}`above <sec_phylogen_multiroot>`, but only remove the ancestral link above node 4
@@ -498,7 +499,7 @@ generate 2 trees in the tree sequence, which differ only in the presence of abse
 a single branch. We do not have to separately store the entire tree on the right: all
 the edges that are shared between trees are stored only once.
 
-The rest of the `tskit` tutorials will lead you through the concepts involved with
+The rest of the {program}`tskit` tutorials will lead you through the concepts involved with
 storing and analysing sequences of many correlated trees. For a simple introduction, you
 might want to start with {ref}`sec_what_is`.