Add instructions for running the tutes

Fixes tskit-dev#119

Author: hyanwong

Diff for: _static/download_data.py

@@ -0,0 +1,18 @@
+"""
+Simple script to download all .trees files within the `data` directory on GitHub,
+saving to a local `data` directory
+"""
+
+import os
+import json
+import urllib.request
+
+if not os.path.isdir("data"):
+    os.mkdir("data")  # Make a "data" directory within the current folder
+# Get the list of data files
+info = urllib.request.urlopen("https://api.github.com/repos/tskit-dev/tutorials/git/trees/main?recursive=1")
+files = json.loads(info.read().decode(info.info().get_content_charset('utf-8')))['tree']
+# Save the data files to the data directory
+for path in [file['path'] for file in files]:
+    if path.startswith("data/") and path.endswith(".trees"):
+        urllib.request.urlretrieve("https://raw.github.com/tskit-dev/tutorials/main/" + path, path)

Diff for: basics.md

@@ -65,18 +65,19 @@ concepts behind {program}`tskit`, the tree sequence toolkit.
 ## Terminology
 
 ::::{margin}
-:::{seealso}
-Many of the terms below are also {ref}`covered <tskit:sec_data_model_definitions>`
-in the official {program}`tskit` docs
+:::{note}
+See {ref}`here <sec_intro_downloading_datafiles>` to run the code in this tutorial on
+your own computer
 :::
 ::::
 
 A tree sequence is a data structure which describes a set of
 evolutionary trees, together with some associated data that specifies, for example,
 the location of mutations in the tree sequence.
 
-Below are the most important terms and concepts that you'll encounter in these tutorials, 
-but first we'll {func}`~tskit.load` a tree sequence from a `.trees` file using the
+Below are the most important {ref}`terms and concepts <tskit:sec_data_model_definitions>`
+that you'll encounter in these tutorials,  but first we'll {func}`~tskit.load` a tree
+sequence from a `.trees` file using the
 {ref}`tskit:sec_python_api` (which will be used in the rest of this tutorial):
 
 ```{code-cell} ipython3

Diff for: intro.md

@@ -22,6 +22,20 @@ 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`
 
+:::{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.
+:::
+
+## Other sources of help
+
+Videos and publications about tree sequences are listed on our
+[Learn page](https://tskit.dev/learn.html). 
+
 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
@@ -30,11 +44,55 @@ similar forums for other software in the tree sequence [development community](h
 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.
-:::
+(sec_intro_running)=
+
+## Running tutorial code
+
+It is not necessary to run code in the tutorials yourself: tutorials can be followed by
+simply reading each page. However, it is also possible to run the tutorial code
+on your own computer, which will allow you to experiment with the examples provided.
+The recommended way to do this is from within a
+[Jupyter notebook](https://jupyter.org). As well as installing Jupyter, you will also
+need to install the various Python libraries, most importantly
+``tskit``, ``msprime``, ``numpy``, and ``matplotlib``. These and other packages are
+listed  in the [requirements.txt](https://raw.githubusercontent.com/tskit-dev/tutorials/main/requirements.txt)
+file; a shortcut to installing the necessary software is therefore:
+
+```
+python3 -m pip install -r https://raw.githubusercontent.com/tskit-dev/tutorials/main/requirements.txt
+```
+
+In addition, to run the {ref}`R tutorial<sec_tskit_r>` you will need to install the R
+[reticulate](https://rstudio.github.io/reticulate/) library, and if running in a Jupyter,
+the [IRkernel](https://irkernel.github.io) library. This can be done by running the
+following command within R:
+
+```
+install.packages(c("reticulate", "IRkernel")); IRkernel::installspec()
+```
+
+(sec_intro_downloading_datafiles)=
+
+### Downloading tutorial datafiles
+
+Many of the tutorials use pre-existing tree sequences stored in the ``data`` directory.
+These can be downloaded from the internet by running the script stored in
+[https://tskit-dev/tutorials/_static/download_data.py](https://tskit-dev/tutorials/_static/download_data.py).
+If you are running the code in the tutorials from within a Jupyter notebook
+then you can simply load this code into a new cell by using the
+[%load cell magic](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-load).
+Just run the following in a Jupyter code cell:
+
+```
+%load https://tskit-dev/tutorials/_static/download_data.py
+```
+
+Executing the resulting Python code should download the data files, allowing code like
+the following to run successfully
+
+```{code-cell} ipython3
+import tskit
+ts = tskit.load("data/basics.trees")
+print(f"The file 'data/basics.trees' exists, and contains {ts.num_trees} trees")
+```