Merge pull request tskit-dev#102 from hyanwong/intro-page

Intro page

Author: jeromekelleher

_config.yml

@@ -30,6 +30,7 @@ sphinx:
     config:
       todo_include_todos: true
       intersphinx_mapping:
+        py: ["https://docs.python.org/3", null]
         tskit: ["https://tskit.dev/tskit/docs/stable", null]
         msprime: ["https://tskit.dev/msprime/docs/stable", null]
         pyslim: ["https://pyslim.readthedocs.io/en/stable", null]

analysing_tree_sequences.md

@@ -16,7 +16,8 @@ kernelspec:
 
 (sec_analysing_tree_sequences)=
 
-# Analysing tree sequences
+# _Analysing tree sequences_
+% remove underscores in title when tutorial is complete or near-complete
 
 :::{todo}
 Add all stats material from https://tskit.dev/tskit/docs/stable/tutorial.html

args.md

@@ -16,7 +16,9 @@ kernelspec:
 
 (sec_args)=
 
-# ARGs as tree sequences
+# _ARGs as tree sequences_
+% remove underscores in title when tutorial is complete or near-complete
+
 
 :::{todo}
 We can simulate some ARGs in msprime, explain how we can losslessly represent ARGs and get all the information you could want.

basics.md

@@ -157,7 +157,7 @@ associated with a parent node ID and a child node ID. The time of the parent nod
 strictly greater than the time of the child node, and the difference in these times is
 sometimes referred to as the "length" of the edge. Since trees in a tree sequence are
 usually taken to represent marginal trees along a genome, as well as the time dimension
-each edge also has a genomic _span_, defined by the edge's *left* and a *right* position
+each edge also has a genomic _span_, defined by a *left* and a *right* position
 along the genome. There are 15 edges in the tree sequence above. Here's an example of
 one of them:
 
@@ -278,9 +278,9 @@ In the plot above, since the the only mutation is above node 8 in the last tree,
 a {attr}`~Mutation.derived_state` of "G", we know that the samples descending from node
 8 in the first tree (sample genomes 2, 4, and 5) have a "G" at {attr}`~Site.position` 257,
 while the others have the {attr}`~Site.ancestral_state` of "T". This means that Ada is
-homozygous for "T", Bob is homozygous for "G", and Cat is heterozygous "T|G".
+homozygous for "T", Bob is homozygous for "G", and Cat is heterozygous "T/G".
 In other words the ancestral state and the details of any mutations at that site,
-when coupled with the tree topology at the site {attr}`~Site.position` is sufficient to
+when coupled with the tree topology at the site {attr}`~Site.position`, is sufficient to
 define the allelic state possessed by each sample.
 
 Note that even though the genome is 1000 base pairs long, the tree sequence only contains

completing-forward-sims.md

@@ -11,15 +11,12 @@ kernelspec:
 
 # Completing forwards simulations
 
-:::{note}
-Link to other tutorial sections on forward sims
-:::
-
 The ``msprime`` simulator generates tree sequences using the backwards in
 time coalescent model. But it is also possible to output tree sequences
 from [forwards-time](https://doi.org/10.1371/journal.pcbi.1006581)
 simulators such as [SLiM](https://messerlab.org/slim)
-and [fwdpy11](https://fwdpy11.readthedocs.io/).
+and [fwdpy11](https://fwdpy11.readthedocs.io/) (see the
+{ref}`sec_tskit_forward_simulations` tutorial).
 There are many advantages to using forward-time simulators, but they
 are usually quite slow compared to similar coalescent simulations. In this
 section we show how to combine the best of both approaches by simulating

counting_topologies.md

@@ -16,7 +16,9 @@ kernelspec:
 
 (sec_counting_topologies)=
 
-# Counting topologies
+# _Counting topologies_
+% remove underscores in title when tutorial is complete or near-complete
+
 
 :::{todo}
 Add examples of using {meth}`TreeSequence.count_topologies` and introduce {ref}`sec_combinatorics`

development.md

@@ -1,4 +1,20 @@
-# Development
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.12
+    jupytext_version: 1.9.1
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+
+(sec_development)=
+
+# _Development_
+% remove underscores in title when tutorial is complete or near-complete
 
 :::{note}
 Add content for helping developers to add more tutorials.

forward_sims.md

@@ -1,7 +1,22 @@
-# Forward simulations
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.12
+    jupytext_version: 1.9.1
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
 
 (sec_tskit_forward_simulations)=
 
+# _Forward simulations_
+% remove underscores in title when tutorial is complete or near-complete
+
+
 :::{note}
 Add forward simulations.
 :::

getting_started.md

@@ -87,7 +87,7 @@ for tree in ts.trees():
 print(f"Tree {ts.last().index} covers {ts.last().interval}")
 ```
 ::::{margin}
-:::{warning}
+:::{caution}
 For efficiency, {meth}`~TreeSequence.trees` repeatedly returns the
 same tree object, updating it internally to reflect the (usually small) changes
 between adjacent trees. So take care to treat each tree within the ``for``
@@ -110,7 +110,7 @@ that there's a corresponding {meth}`TreeSequence.first` method to return the fir
 
 Above, we stopped iterating after Tree 4 to limit the printed output, but iterating
 forwards through trees in a tree sequence (or indeed backwards using the standard Python
-``reversed`` function) is efficient. That means it's quick, for example to check if all
+{func}`~py:reversed` function) is efficient. That means it's quick, for example to check if all
 the trees in a tree sequence have fully coalesced (which is to be expected in
 reverse-time, coalescent simulations, but not always for tree sequences produced by
 {ref}`forward simulation <sec_tskit_forward_simulations>`).

intro.md

@@ -1,8 +1,40 @@
-# Tskit tutorials
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.12
+    jupytext_version: 1.9.1
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
 
-This is the home of tskit tutorials.
+# Tree sequence tutorials
 
+**Welcome!**
 
-:::{warning}
-This site is under heavy development.
+This site contains a number of tutorials to develop your understanding of
+[tree sequences](https://tskit.dev/learn.html#what) and software programs,
+such as [msprime](https://tskit.dev/msprime), that use them.
+
+If you are new to the world of tree sequences, we suggest you start with the
+first tutorial: {ref}`sec_what_is`
+
+We aim to be a friendly, welcoming open source community.
+Questions and discussion about using {program}`tskit`, the tree sequence toolkit
+should be directed to the
+[GitHub discussion forum](https://github.com/tskit-dev/tskit/discussions), and there are
+similar forums for other software in the tree sequence [development community](https://github.com/tskit-dev),
+such as for [msprime](https://github.com/tskit-dev/msprime/discussions) and
+[tsinfer](https://github.com/tskit-dev/tsinfer/discussions).
+
+:::{note}
+Tutorials are under constant development. Those that are still a work in progress and
+not yet ready for use are shown in _italics_ in the list of tutorials.
+
+We very much welcome help developing existing tutorials or writing new ones. Please open
+or contribute to a [GitHub issue](https://github.com/tskit-dev/tutorials/issues) if you
+would like to help out.
 :::

no_mutations.md

@@ -13,7 +13,9 @@ kernelspec:
 
 (sec_tskit_no_mutations)=
 
-# Do you really need mutations?
+# _Do you really need mutations?_
+% remove underscores in title when tutorial is complete or near-complete
+
 
 Maybe not! This tutorial takes you through a number of common tasks 
 and shows how to do things by working directly with the underlying 

simplification.md

@@ -22,10 +22,10 @@ def create_notebook_data():
 # create_notebook_data()  # uncomment to recreate the tree seqs used in this notebook
 ```
 
-
 (sec_simplification)=
 
-# Simplification
+# _Simplification_
+% remove underscores in title when tutorial is complete or near-complete
 
 :::{todo}
 Create content. See https://github.com/tskit-dev/tutorials/issues/52