Add README, LICENSE, documentation and infrastructure updates. (#20)

.github/workflows/build.yml

@@ -49,6 +49,11 @@ jobs:
         run: |
           make
 
+      - name: Check for dead links
+        working-directory: book
+        run: |
+          make linkcheck
+
       - name: Move built HTML book
         if: github.event_name == 'release'
         working-directory: book
@@ -86,3 +91,4 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.ACTIONS }} 
         with:
           build_dir: book_output/
+

README.md

@@ -0,0 +1,9 @@
+# README
+
+## License
+
+The license is [CC-BY-SA-4](https://creativecommons.org/licenses/by-sa/4.0/).
+
+Some of the code blocks have dependencies licensed as [GPL3](https://opensource.org/licenses/gpl-3.0.html).
+
+See [here](https://creativecommons.org/2015/10/08/cc-by-sa-4-0-now-one-way-compatible-with-gplv3/) for a statement on the compatibility of the `GPL` and Creative Commons licenses.

book/Makefile

@@ -7,4 +7,8 @@ all: $(INDEX)
 clean:
 	rm -rf _build
 
+linkcheck:
+	jupyter-book build . --builder linkcheck
+
+
 $(INDEX): $(MDFILE) _config.yml _toc.yml build.sh references.bib

book/_toc.yml

@@ -22,4 +22,8 @@ parts:
   - caption: Appendix
     chapters:
     - file: markdown/appendix/interactive.md
+    - file: markdown/appendix/holoviews_in_slides
+    - file: markdown/appendix/observable_in_slides
+    - file: markdown/appendix/python_dependencies
+    - file: markdown/appendix/acknowledgements
     - file: markdown/bibliography

book/build.sh

@@ -1,5 +1,5 @@
 REPORTDIR=_build/html/reports
-jupyter-book build -W .
+jupyter-book build -n -W  --keep-going .
 RV=$?
 if [ $RV -ne 0 ];
 then

book/intro.md

@@ -1 +1,32 @@
 # Introduction
+
+This book is a collection of visualisations developed for teaching population genetics.
+The goal is to create a collection of interactive content that can be remixed alongside existing course material.
+
+The icons near the top right of this page will take you to the `GitHub` repository for this book.
+
+## Technologies used
+
+* [Jupyter book](https://www.jupyterbook.org)
+* [Observable](https://www.observablehq.com) notebooks.
+  These are pure JavaScript inserted into the book via [embedding](https://observablehq.com/@observablehq/introduction-to-embedding).
+* [Holoviews](https://www.holoviews.org) creates interactive JavaScript applications that require Python.
+  These pages require [MyBinder](https://mybinder.readthedocs.io/) to function, which just takes a few mouse clicks!.
+  See {ref}`here <interactive_python_notebooks>` for details.
+
+## Integrating the information into existing courses.
+
+* Direct links to the many of the pages "just work" in "learning management" systems such as [Canvas](https://www.instructure.com/canvas).
+  The exception is the pages requiring `MyBinder`.
+  These pages need to be launched in the binder, or...
+* ...you can use them in slides as described {ref}`here <interactive_python_in_slides>`.
+* The Observable content can also be used in slides.
+  See {ref}`here <observable_in_slides>` for instructions for `Jupyter` .
+
+## License
+
+The license is [CC-BY-SA-4](https://creativecommons.org/licenses/by-sa/4.0/).
+
+Some of the code blocks have dependencies licensed as [GPL3](https://opensource.org/licenses/gpl-3.0.html).
+
+See [here](https://creativecommons.org/2015/10/08/cc-by-sa-4-0-now-one-way-compatible-with-gplv3/) for a statement on the compatibility of the `GPL` and Creative Commons licenses.

book/markdown/appendix/acknowledgements.md

@@ -0,0 +1,5 @@
+# Acknowledgements
+
+* David Kirby, UCI
+* Aaron Ragsdale, U. Wisconsin
+* The `tskit` and `msprime` communities

book/markdown/appendix/holoviews_in_slides.md

@@ -0,0 +1,39 @@
+(interactive_python_in_slides)=
+
+# Using interactive Python applets in slideshow presentations
+
+It is possible to use the interactive Python applications in slideshows.
+Doing this makes this content available for lectures, etc..
+You *do not* need internet access for the applets to function.
+
+You need the following tools, all of which can be installed using `pip`:
+
+* [jupyter](https://www.jupyter.org) notebook
+* [RISE](https://rise.readthedocs.io/en/stable/)
+* [hide_code](https://github.com/kirbs-/hide_code)
+
+We highly recommend using a `virtualenv`
+
+```{note}
+The installation and setup instructions for `hide_code` did not "just work" for the author.
+Each command needs a `--user` flag.
+
+`RISE` is not compatible with `jupyter-lab`.
+You must use the classic notebook interface.
+```
+
+Once the above are installed, you can generate slides, hide the code, and the slide will contain a working applet.
+
+## Additional hints
+
+* You may want to redefine the `height` and `width` output of the plots in order to better fill the slides.
+  Doing so will cause the images to be far too big in the regular notebook view, but they will look good in the slide view.
+* The pages of this book allow the Python code to be copied.
+  If you mouse over a code block, a "page" icon appears in the top right.
+  Click it, and the code block will be copied to your clip board.
+  This copy method is the simplest way to get the examples into your own slideshows.
+
+## Caveats and limitations
+
+* Using this type of content in lecture slides basically commits you to bringing your own laptop to class.
+  You need a fully-functional Python environment, etc., and you are unlikely to find such a thing on the ancient Windows PC at the podium in your classroom.

book/markdown/appendix/observable_in_slides.md

@@ -0,0 +1,29 @@
+(observable_in_slides)=
+
+# Using Observable content in Jupyter presentations
+
+You can display the observable content in Jupyter notebooks (and slideshows).
+Note that you *do need* internet access for the content to display!
+
+The following Python code will display {ref}`this <fixation_in_diploid_population>` Observable widget in a Jupyter output cell:
+
+``` python
+from IPython.core.display import display, HTML
+script="""
+<iframe width="75%" height="750" frameborder="0"
+  src="https://observablehq.com/embed/@molpopgen/fixation-under-directional-selection?cells=detail_plot%2Cviewof+N%2Cviewof+num_copies%2Cviewof+selection_coefficient%2Cviewof+dominance%2Cviewof+show_genotypes"></iframe>
+"""
+display(HTML(script))
+```
+
+Using the tools described {ref}`here <interactive_python_in_slides>`, you can hide the Python code needed to display the applet.
+
+## Additional hints
+
+* The `iframe` code needed to embed the Observable content can be copied from the source code for this project.
+  Alternately, you can generate your own embed code manually from the [author's collection](https://www.observablehq.com/@molpopgen).
+
+## Limitations
+
+* The applications may be quite small in the slides.
+  We are currently not sure if there is a way to rescale them.

book/markdown/appendix/python_dependencies.md

@@ -0,0 +1,40 @@
+---
+jupytext:
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+
+# Python dependencies
+
+The Python requirements for this book are:
+
+```{code-cell}
+---
+tags: ['remove-input']
+---
+
+with open("../../../requirements.txt", "r") as f:
+	x = f.readlines()
+	print(''.join(x))
+```
+
+The above list is defined in `requirements.txt` in the `GitHub` repository.
+
+The precise versions of all packages used to create this book are:
+
+```{code-cell}
+---
+tags: ['remove-input']
+---
+
+import subprocess
+
+lockfile = subprocess.run(["pip", "freeze"], stdout=subprocess.PIPE)
+print(lockfile.stdout.decode('utf-8'))
+```

book/markdown/classic_selection_drift/diploid_fixation.md

@@ -1,3 +1,5 @@
+(fixation_in_diploid_population)=
+
 # Fixation in a diploid population
 
 <iframe width="100%" height="750" frameborder="0"

book/references.bib

@@ -24,9 +24,7 @@ @ARTICLE{Tavare1984-fm
   pages    = "119--164",
   month    =  oct,
   year     =  1984,
-  keywords = "popgen-course-material",
-  issn     = "0040-5809",
-  doi      = "10.1016/0040-5809(84)90027-3"
+  keywords = "popgen-course-material"
 }
 
 @ARTICLE{Ralph2020-cg,
@@ -73,11 +71,42 @@ @ARTICLE{Ralph2020-cg
   year      =  2020,
   keywords  = "genealogy; genotype statistics; tree
                sequence;MyPapers;fwdpy11\_manual;fwdpy\_paper;popgen-course-material;Paula",
-  language  = "en",
-  issn      = "0016-6731, 1943-2631",
-  pmid      = "32357960",
-  doi       = "10.1534/genetics.120.303253",
-  pmc       = "PMC7337078"
+  language  = "en"
+}
+
+@ARTICLE{Jouganous2017-tg,
+  title     = "Inferring the Joint Demographic History of Multiple Populations:
+               Beyond the Diffusion Approximation",
+  author    = "Jouganous, Julien and Long, Will and Ragsdale, Aaron P and
+               Gravel, Simon",
+  abstract  = "Understanding variation in allele frequencies across populations
+               is a central goal of population genetics. Classical models for
+               the distribution of allele frequencies, using forward
+               simulation, coalescent theory, or the diffusion approximation,
+               have been applied extensively for demographic inference, medical
+               study design, and evolutionary studies. Here we propose a
+               tractable model of ordinary differential equations for the
+               evolution of allele frequencies that is closely related to the
+               diffusion approximation but avoids many of its limitations and
+               approximations. We show that the approach is typically faster,
+               more numerically stable, and more easily generalizable than the
+               state-of-the-art software implementation of the diffusion
+               approximation. We present a number of applications to human
+               sequence data, including demographic inference with a
+               five-population joint frequency spectrum and a discussion of the
+               robustness of the out-of-Africa model inference to the choice of
+               modern population.",
+  journal   = "Genetics",
+  publisher = "Genetics Soc America",
+  volume    =  206,
+  number    =  3,
+  pages     = "1549--1567",
+  month     =  jul,
+  year      =  2017,
+  keywords  = "demographic inference; diffusion approximation; joint allele
+               frequency spectrum; moments
+               equations;polygenic\_inference\_R01;fwdpy11\_manual;popgen-course-material;Stehany",
+  language  = "en"
 }
 
 @ARTICLE{Kreitman1983-xr,
@@ -98,10 +127,7 @@ @ARTICLE{Kreitman1983-xr
   pages    = "412--417",
   year     =  1983,
   keywords = "popgen-course-material",
-  language = "en",
-  issn     = "0028-0836",
-  pmid     = "6410283",
-  doi      = "10.1038/304412a0"
+  language = "en"
 }
 
 % The entry below contains non-ASCII chars that could not be converted
@@ -149,10 +175,7 @@ @ARTICLE{Kim2002-to
   month    =  feb,
   year     =  2002,
   keywords = "Optimum shift paper;popgen-course-material",
-  language = "en",
-  issn     = "0016-6731",
-  pmid     = "11861577",
-  pmc      = "PMC1461968"
+  language = "en"
 }
 
 @BOOK{Wakeley2008-hd,
@@ -169,8 +192,7 @@ @BOOK{Wakeley2008-hd
   year      =  2008,
   keywords  = "Optimum shift
                paper;simbook;intro2simulation;popgen-course-material",
-  language  = "en",
-  isbn      = "9780974707754"
+  language  = "en"
 }
 
 @ARTICLE{Watterson1975-ej,
@@ -185,8 +207,5 @@ @ARTICLE{Watterson1975-ej
   year     =  1975,
   keywords = "Optimum shift
               paper;libseq\_manual;pylibseq\_manual;polygenic\_inference\_R01;popgen-course-material",
-  language = "en",
-  issn     = "0040-5809",
-  pmid     = "1145509",
-  doi      = "10.1016/0040-5809(75)90020-9"
+  language = "en"
 }

requirements.txt

@@ -5,5 +5,3 @@ matplotlib
 numpy
 msprime==1.0.1
 pandas
-pytest
-scipy