Tutorial-2.md

+# Simulating phylogenies
+
+A great advantage of `TiPS`, besides its computational efficiency, is that it can generate phylogenies from the population dynamics trajectories using a backward-in-time approach.
+
+For this, we may need a vector of sampling dates.
+
+For the SIR example, these are stored here:
+
+``` r
+dates <- system.file("extdata", "SIR-dates.txt", package = "TiPS")
+```
+
+The `simulate_tree` function simulates a phylogeny from a trajectory object and uses a set of sampling dates:
+
+``` r
+sir_tree <- simulate_tree(
+  simuResults = traj_dm,
+  dates = dates,
+  deme = c("I"), # the type of individuals that contribute to the phylogeny
+  sampled = c(I = 1), # the type of individuals that are sampled and their proportion of sampling
+  root = "I", # type of individual at the root of the tree
+  isFullTrajectory = FALSE, # deads do not generate leaves
+  nTrials = 5,
+  addInfos = FALSE) # additional info for each node
+```
+
+The `sampled` option can be used for labeled phylogenies (i.e. with multiple host types) but it requires specifying the proportion of each label type. The `root` option indicates the state of the individual initiating the dynamics. See the next section for details.
+
+The complete phylogeny can be obtained (therefore neglecting the sampling dates) with the option `isFullTrajectory`.
+
+Finally, some runs may fail to simulate a phylogeny from a trajectory for stochastic reasons. The `nTrials` parameter indicates the number of unsuccessful trials allowed before giving up.
+
+The simulated phylogeny can be visualised using:
+
+``` r
+ape::plot.phylo(sir_tree, cex = .5)
+```
+
+Writing the tree in an output file with the option `outFile` is possible. If a file name is given as input, by default the tree is written in a Newick format. To write the simulated tree in a Nexus format, the option `format` must be specified and fixed to Nexus (option `format = "nexus"`).
+
+```r
+sir_tree <- simulate_tree(
+  simuResults = traj_dm,
+  dates = dates,
+  deme = c("I"),
+  sampled = c(I = 1),
+  root = "I",
+  isFullTrajectory = FALSE,
+  nTrials = 5,
+  addInfos = FALSE,
+  outFile = "sir_tree.nexus",
+  format = "nexus"
+)
+```