Revise README

README.Rmd

@@ -65,11 +65,11 @@ library("epichains")
 
 # Quick start
 
-## Core functionality
+## Chain likelihoods
 
 _{{ packagename }}_ provides four main functions: 
 
-### [likelihood()](https://epiverse-trace.github.io/epichains/reference/likelihood.html)
+### [`likelihood()`](https://epiverse-trace.github.io/epichains/reference/likelihood.html)
 
 This function calculates the likelihood/loglikelihood of observing a vector of outbreak summaries obtained from transmission chains. Summaries here refer to transmission chain sizes or lengths/durations.
 
@@ -98,8 +98,12 @@ likelihood_eg <- likelihood(
 likelihood_eg
 ```
 
+## Chain simulation
 
-### [simulate_tree()](https://epiverse-trace.github.io/epichains/reference/simulate_tree.html) 
+There are three simulation functions, herein referred to colelctively as the `simulate_*()` functions.
+``
+
+### [`simulate_tree()`](https://epiverse-trace.github.io/epichains/reference/simulate_tree.html) 
 
 `simulate_tree()` simulates an outbreak from a given number of infections.
 It retains and returns information on infectors (ancestors), infectees, the generation of infection, and the time, if a serial distribution is specified.
@@ -121,53 +125,76 @@ sim_tree_eg <- simulate_tree(
 head(sim_tree_eg)
 ```
 
-`simulate_tree()` can model population-level intervention by reducing the $R_0$,
-using the `intvn_mean_reduction` argument.
+### [`simulate_summary()`](https://epiverse-trace.github.io/epichains/reference/simulate_summary.html)
 
-To illustrate this, we will use the previous example and specify
-a population-level intervention that reduces $R_0$ by $50\%$.
+`simulate_summary()` is basically `simulate_tree()` except that it does not retain
+information on each infector and infectee. It returns the eventual size or length/duration of each transmission chain.
 
+Here is an example to simulate the previous examples without intervention,
+returning the size of each of the $10$ chains. It assumes a poisson offspring distribution with
+mean of $0.9$.
 ```{r}
 set.seed(123)
 
-sim_tree_intvn_eg <- simulate_tree(
+simulate_summary_eg <- simulate_summary(
   nchains = 10,
   statistic = "size",
   offspring_dist = "pois",
-  intvn_mean_reduction = 0.5,
   stat_max = 10,
-  serials_dist = function(x) 3,
   lambda = 0.9
 )
 
-head(sim_tree_intvn_eg)
+# Print the results
+simulate_summary_eg
 ```
 
-### [simulate_summary()](https://epiverse-trace.github.io/epichains/reference/simulate_summary.html)
+### [`simulate_tree_from_pop()`](https://epiverse-trace.github.io/epichains/reference/simulate_tree_from_pop.html)
 
-`simulate_summary()` is basically `simulate_tree()` except that it does not retain
-information on each infector and infectee. It returns the eventual size or length/duration of each transmission chain.
+`simulate_tree_from_pop()` simulates outbreaks based on a specified population size and pre-existing immunity until the susceptible pool runs out.
+
+Here is a quick example where we simulate an outbreak in a population of size $1000$. We assume individuals have a poisson offspring distribution with mean, $\text{lambda} = 1$, and serial interval of $3$:
+```{r}
+set.seed(7)
+
+sim_tree_from_pop_eg <- simulate_tree_from_pop(
+  pop = 1000,
+  offspring_dist = "pois",
+  lambda = 1,
+  serials_dist = function(x) {3}
+  )
+
+head(sim_tree_from_pop_eg)
+```
+
+#### Simulating interventions
+
+All the `simulate_*()` functions can model interventions that reduce the $R_0$,
+using the `intvn_mean_reduction` argument. In general, these can be
+interpreted as population-level interventions.
+
+To illustrate this, we will use the previous examples for each function and specify
+a population-level intervention that reduces $R_0$ by $50\%$.
+
+Using `simulate_tree()`, we can specify an initial number of cases
+and a population level intervention, `intvn_mean_reduction`, that reduces $R_0$ by $50\%$.
 
-Here is an example to simulate the previous examples without intervention,
-returning the size of each of the $10$ chains. It assumes a poisson offspring distribution with
-mean of $0.9$.
 ```{r}
 set.seed(123)
 
-simulate_summary_eg <- simulate_summary(
+sim_tree_intvn_eg <- simulate_tree(
   nchains = 10,
   statistic = "size",
   offspring_dist = "pois",
+  intvn_mean_reduction = 0.5,
   stat_max = 10,
+  serials_dist = function(x) 3,
   lambda = 0.9
 )
 
-# Print the results
-simulate_summary_eg
+head(sim_tree_intvn_eg)
 ```
 
-Here is an example with an intervention that reduces $R_0$ by $50\%$.
-
+Here is an example with `simulate_summary()`, modelling an intervention that reduces $R_0$ by $50\%$.
 ```{r}
 simulate_summary_intvn_eg <- simulate_summary(
   nchains = 10,
@@ -182,23 +209,19 @@ simulate_summary_intvn_eg <- simulate_summary(
 simulate_summary_intvn_eg
 ```
 
-
-### [simulate_tree_from_pop()](https://epiverse-trace.github.io/epichains/reference/simulate_tree_from_pop.html)
-
-`simulate_tree_from_pop()` simulates outbreaks based on a specified population size and pre-existing immunity until the susceptible pool runs out.
-
-Here is a quick example where we simulate an outbreak in a population of size $1000$. We assume individuals have a poisson offspring distribution with mean, $\text{lambda} = 1$, and serial interval of $3$:
+Finally, let's use `simulate_tree_from_pop()`.
 ```{r}
 set.seed(7)
 
-sim_tree_from_pop_eg <- simulate_tree_from_pop(
+sim_tree_from_pop_intvn_eg <- simulate_tree_from_pop(
   pop = 1000,
   offspring_dist = "pois",
+  intvn_mean_reduction = 0.5,
   lambda = 1,
   serials_dist = function(x) {3}
   )
 
-head(sim_tree_from_pop_eg)
+head(sim_tree_from_pop_intvn_eg)
 ```
 
 ## Other functionalities