Contributing a RevBayes tutorial

Getting started

This tutorial will take you through the steps of contributing a new RevBayes tutorial to this website.

In order to build and test your tutorial, you will need to download and host an instance of the RevBayes website on your local machine. The site was built using Jekyll and is hosted by GitHub Pages. Please refer to the README.md in the site’s GitHub repository for instructions on setting up and hosting the site on your computer.

This website is generated from simple plain-text files in Markdown format with YAML front matter, with additional support for accessing/modifying page attribute data using Liquid templates. This tutorial presumes the reader is already at least somewhat familiar with these markup tools.

Tutorial directory organization

Each tutorial follows the same general file organization:

revbayes.github.io
└── tutorials
    └── new_tutorial
        ├── data/
        ├── scripts/
        ├── figures/
        └── index.md <-- main text of tutorial

Specifically, your new RevBayes tutorial should be placed in its own directory (e.g. new_tutorial) under the tutorials directory of the root website repository. The main text of the tutorial should be written in a Markdown file named index.md (although any unique name will work). If the tutorial uses additional data, scripts or image files they should be stored in the subdirectories data, scripts and figures respectively. Your tutorial can include additional pages or other files, but the above basic components are used in integrating your tutorial with the rest of the website.

Writing tutorial front matter

In order for Jekyll to process your tutorial’s page, it must include YAML front matter, indicated by

---
---

You will populate the front matter with YAML attributes that are used to organize your tutorial on the RevBayes website. The most basic attributes are title, subtitle, authors which are displayed in the tutorial’s title header section.

---
title: How to science
subtitle: A postmodern experience
authors:
- Alice
- Bob
level: 0
---

The level attribute is used to group tutorials with similar levels of complexity in the tutorial index. At the moment, only these levels are recognized:

level: 0 is for Introduction to RevBayes

level: 1 is for Introduction to MCMC

level: 2 is for Model Selection and Testing

level: 3 is for Standard tree inference

level: 4 is for Complex hierarchical models for phylogenetic inference

level: 5 is for Discrete Morphology

level: 6 is for Comparative methods

level: 7 is for Diversification Rate Estimation

level: 8 is for Biogeography

level: 9 is for Demographic Inference

Any other level is for Miscellaneous tutorials

Front matter attributes

Here is a glossary of all the tutorial attributes used by this site.

Filling in the overview box

At the top of each tutorial, an Overview box is displayed with a list of prerequisite tutorials and a table of contents. Take another look at the overview for this tutorial.

Including prerequisites

If you would like to refer users to prequisite tutorials in the tutorial’s overview section, list the names of the prequisite tutorials in the prerequisites YAML attribute. Tutorials can be referred to by any unique path identifier, ignoring index.md and .md suffixes.

prerequisites:
- intro
- ctmc
- clocks/simple

Filling in the table of contents

To create a heading that will be included in the table of contents, you can use the section and subsection Liquid tags, which take the heading text and anchor id as arguments, separated by a pipe |. Sections are referenced using the ref Liquid tag.

{% section This is a section header | section1 %}

This is a reference to {% ref section1 %}

This is a section header

---

This is a reference to

{% subsection This is a subsection header | subsection1 %}

This is a reference to {% ref subsection1 %}

This is a subsection header

---

This is a reference to

Including data files and scripts

At the top of each tutorial, the Data files and scripts box contains a list of files that can be downloaded by clicking the icon.

Data files and scripts

Data Files

• example.nex

Scripts

• example.Rev

Files in the data and scripts directories of your tutorial are added to the Data files and scripts box automatically. You can include files from another tutorial by listing their relative paths in the include_files YAML front matter attribute. You can exclude files using the exclude_files attribute.

include_files:
    - ctmc/data/primates_and_galeopterus_cytb.nex
exclude_files:
    - data/useless_file.nex

Including script snippets

You can dynamically include snippets from your script files using the snippet filter. You can extract a range of line numbers using the lines option, or you can extract a block of text using the block option. You can refer to the script file by name, or you can use a Liquid variable, for instance, obtained from the page.files array, or using the match_file filter.

Here are lines 1-7 of `example.Rev`
{{ "example.Rev" | snippet:"line","1-7" }}

Here is the third block of text from `{{ page.files[1].name }}`
{{ page.files[1] | snippet:"block","3" }}

{% assign example_script = "example.Rev" | match_file %}

Here are the second and third blocks of text from `{{ example_script.name }}`
{{ example_script | snippet:"block#","2-3" }}

Here are lines 1-7 of example.Rev

# this is an example Rev script
# this is line 2
a ~ dnExp(1)

# this is the second block
# this is line 6
b ~ dnBeta(1,1)

Here is the third block of text from example.Rev

# this is the third block
# this is line 10
c := a + b

Here are the second and third blocks of text from example.Rev

b ~ dnBeta(1,1)

c := a + b

Formatting code

You can format code using the ``` or ~~~ fenced code delimiters. By default, tutorial code is formatted for Rev

```
for (i in 1:n_branches) {
   br_lens[i] ~ dnExponential(10.0)
   moves[mvi++] = mvScale(br_lens[i]) 
}
```

for (i in 1:n_branches) {
   br_lens[i] ~ dnExponential(10.0)
   moves[mvi++] = mvScale(br_lens[i]) 
}

Code representing output from the Rev console can be formatted using the {:.Rev-output} class

```
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
```
{:.Rev-output}

Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Other formatting options

Other code formats can be assigned using the {:.} syntax.

{:.bash} - bash console input

```
ls tutorials
grep phylogenetics tutorial.md
```
{:.bash}

ls tutorials
grep phylogenetics tutorial.md

{:.instruction} - Instruction box

> Lorem ipsum dolor sit amet, consectetur adipiscing elit,
> sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
{:.instruction}

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

{% aside %} - Aside box

{% aside Aside header %}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
{% endaside %}

Aside header

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

{:.info} - Optional information box

> ## Info header
> Lorem ipsum dolor sit amet, consectetur adipiscing elit,
> sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
{:.info}

Info header

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Blockquote

> Lorem ipsum dolor sit amet, consectetur adipiscing elit,
> sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Math notation

Mathematical notation using $\LaTeX$ symbols are rendered with MathJax. You can write inline math using the $...$, $$...$$ or \\(...\\) delimiters, while display math uses \\[...\\]. You can alternatively write display math using $$...$$ if it is separated from the previous text by a line break.

Inline math
$S = \mathbb{R}$
$$f(x) = x^2$$
\\(\implies \min_{x\in S}f(x) = 0\\)
is cool

Display math \\[f(a) = \frac{1}{2\pi i}\int_{\gamma}\frac{f(z)}{z-a}dz\\]

Alternative display math

$$\int(1-e^{-x})^n\,dx=x-\sum_{p=1}^n\tfrac{1}{p}(1-e^{-x})^p$$

Inline math $S = \mathbb{R}$ \(f(x) = x^2\) \(\implies \min_{x\in S}f(x) = 0\) is cool

Display math \[f(a) = \frac{1}{2\pi i}\int_{\gamma}\frac{f(z)}{z-a}dz\]

Alternative display math

\[\int(1-e^{-x})^n\,dx=x-\sum_{p=1}^n\tfrac{1}{p}(1-e^{-x})^p\]

Referencing equations

You can number and reference equations using the \label, \tag and \ref Latex commands.

$$\begin{align}
\frac{(s-1)^b}{(s x + y)^{b+p}} &= \frac{1}{(s x +y)^p}\left(\frac{s-1}{s x + y}\right)^b \label{equation1}\tag{1} \\
&= \sum_{i=0}^b \binom{b}{i}(-1)^i \frac{(x+y)^i}{x^b(sx+y)^{i+p}} \label{equation2}\tag{2}
\end{align}$$

This is a reference to Equation $\ref{equation1}$. This is a reference to Equation $\ref{equation2}$.

\[\begin{align} \frac{(s-1)^b}{(s x + y)^{b+p}} &= \frac{1}{(s x +y)^p}\left(\frac{s-1}{s x + y}\right)^b \label{equation1}\tag{1} \\ &= \sum_{i=0}^b \binom{b}{i}(-1)^i \frac{(x+y)^i}{x^b(sx+y)^{i+p}} \label{equation2}\tag{2} \end{align}\]

This is a reference to Equation $\ref{equation1}$. This is a reference to Equation $\ref{equation2}$.

Modularizing your tutorial

You can modularize your tutorial by putting major sections in separate markdown files in your tutorial directory. These can be included in the main text using the include_relative Liquid tag. Make sure that only the main text Markdown file contains YAML front matter.

For example, if you have an external file external_file.md with the following contents

This is an external *Markdown* file
without [YAML](http://camel.readthedocs.io/en/latest/yamlref.html) front matter.

This *file* will be __formatted__ ~~as plain text~~ like the rest of the main text.

You can even include $\LaTeX$.

You can include it in the main text as follows

{% include_relative external_file.md %}

This is an external Markdown file without YAML front matter.

This file will be formatted as plain text like the rest of the main text.

You can even include $\LaTeX$.

Making alternative versions of your tutorial

Any Markdown file in your tutorial directory will be rendered as a separate tutorial as long as it has YAML front matter. For example, if we make a copy of the same external file (say external_file-yaml.md) and simply add an empty front matter section, then Jekyll will automatically generate this page when building the website.

This makes it easy for you to create alternative versions of your tutorial. Each alternative versions is built from a Markdown file with YAML front matter, each of which then includes one or more external Markdown module text files that do not include front matter. Consider the following example modular tutorial structure.

new_tutorial
├── data/
├── scripts/
├── figures/
├── modules/ <-- module files (no front matter)
│   ├── intro.md
│   ├── exercise1.md
│   ├── exercise2.md
│   └── exercise3.md
├── new_tutorial.md <-- tutorial page (with front matter)
└── v2.md           <-- tutorial page (with front matter)

In this example, there are two versions of the tutorial, both of which will get listed on the main Tutorials page. If you do not want your tutorial listed in the Tutorials index, use the index: false attribute in the YAML front matter.

Linking to other tutorials

You can reference another tutorial using the page_ref and page_url Liquid tags, or with the match_page filter. As with Prerequisites, tutorials can be referred to by any unique path identifier, ignoring index.md and .md suffixes.

This is a reference to the {% page_ref intro %} tutorial.

{% assign var = "ctmc" %}
This how to link to the {% page_ref {{ var }} %} tutorial using a liquid variable,

{% assign tut = "clocks/simple" | match_page %}
This is how to retrieve the *{{ tut.title }}* tutorial page by name.

The relative URL of the `{{ var }}` tutorial is `{% page_url {{ var }} %}`.

This is a reference to the Getting Started with RevBayes and Rev Language Syntax tutorial.

This how to link to the Nucleotide substitution models tutorial using a liquid variable,

This is how to retrieve the Simple Diversification Models & Estimating Time Trees tutorial page by name.

The relative URL of the ctmc tutorial is /tutorials/ctmc/.

Figures

Figures can be included from the figures subdirectory (or elsewhere) using the figure and figcaption Liquid tags. Figures are referenced using the ref Liquid tag.

{% figure example %}
<img src="figures/example.png" width="200">
{% figcaption %}
This is an example figure caption. You can include *Markdown* and $\LaTeX$.
{% endfigcaption %}
{% endfigure %}
  
This is a reference to {% ref example %}

This is a reference to

Tables

Table can be included in Markdown using the table and tabcaption Liquid tags. Tables are referenced using the ref Liquid tag.

{% table exampletable %}
  |    Range    | Bits  | Size | State |
  |-------------|-------|------|-------|
  |$\emptyset$  |  000  |  0   |   0   |
  |A            |  100  |  1   |   1   |
  |B            |  010  |  1   |   2   |
  |C            |  001  |  1   |   3   |
  |AB           |  110  |  2   |   4   |
  |AC           |  101  |  2   |   5   |
  |BC           |  011  |  2   |   6   |
  |ABC          |  111  |  3   |   7   |

   {% tabcaption %}
    Example table caption
   {% endtabcaption %}
{% endtable %}
  
This is a reference to {% ref exampletable %}

Range	Bits	Size	State
$\emptyset$	000	0	0
A	100	1	1
B	010	1	2
C	001	1	3
AB	110	2	4
AC	101	2	5
BC	011	2	6
ABC	111	3	7

This is a reference to

Printing to PDF

You can prevent any element from being printed when the tutorial is sent to PDF or a printer by tagging it with {:.no-print}.

Citations and bibliography

You can include a citation using the cite and citet Liquid tags.

This is a citation {% cite Felsenstein1981 %}.  
This is an in-text citation of {% citet Felsenstein1981 %}.  
This is a citation with multiple sources {% cite Felsenstein1981 Hoehna2016b %}.

This is a citation (Felsenstein 1981).
This is an in-text citation of Felsenstein (1981).
This is a citation with multiple sources (Felsenstein 1981; Höhna et al. 2016).

Citations are included in the References section at the end of each tutorial. References are formatted according to the CSL style for Systematic Biology.

1. Felsenstein J. 1981. Evolutionary Trees from DNA Sequences: a Maximum Likelihood Approach. Journal of Molecular Evolution. 17:368–376. 10.1007/BF01734359
2. Höhna S., Landis M.J., Heath T.A., Boussau B., Lartillot N., Moore B.R., Huelsenbeck J.P., Ronquist F. 2016. RevBayes: Bayesian Phylogenetic Inference Using Graphical Models and an Interactive Model-Specification Language. Systematic Biology. 65:726–736. 10.1093/sysbio/syw021