Tutorial.Rmd

---
title: "DAISIEprep Tutorial"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{DAISIEprep Tutorial}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## In this tutorial, the main features of `DAISIEprep` are explained. The objective is to identify island colonisation events from time-calibrated phylogenetic trees, assign an island endemicity status (endemic, non-endemic, not present) to each of them, and then extract times of colonisation of the island and diversification within the island.

### The tutorial is divided into 3 sections:
1. **Single phylogeny example** - Using a simulated phylogeny including island 
and non-island species, learn how to extract and format island data for running DAISIE.

2. **Empirical example using Galápagos bird phylogenies** - Extract and format
data for DAISIE analyses using several different "real" phylogenies including 
species of birds from the Galápagos islands.

3. **Adding missing species** - How to add missing species, lineages, etc, to 
your DAISIE data list.


Load the required packages:
```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.align = "center",
  fig.height = 5,
  fig.width = 7
)
```


```{r setup}
library(DAISIEprep)
library(ape)
library(phylobase)
library(ggtree)
library(ggimage)
library(castor)
```

## 1. Single Phylogeny Example

#### In this section we demonstrate a simple example of extracting and formatting data from a single phylogeny. We use a simulated phylogeny, which faciliates explaining how the data is structured. 

First we simulate a phylogeny using the package `ape`.

```{r simulate phylogeny}
set.seed(
  1,
  kind = "Mersenne-Twister",
  normal.kind = "Inversion",
  sample.kind = "Rejection"
)
phylo <- ape::rcoal(10)
```

**Important: `DAISIEprep` requires the tip labels (taxon names) in the phylogeny to be 
formatted as genus name and species name separated by an underscore (e.g. "Canis_lupus"). ** They can
also optionally have tags appended after the species name (separated by underscore, e.g. "Canis_lupus_123"; "Canis_lupus_familiaris_123"). This is common if there are multiple tips in the phylogeny for a single species, when multiple populations or multiple subspecies have been sampled. Samples with the same Genus_species name on the tip will be considered to be of the same species, even if they have subsequent sampling or subspecies tags.


Here we add tip labels to the simulated phylogeny. In this case, all taxa sampled are different plant species from the same genus.
```{r}
phylo$tip.label <- c("Plant_a", "Plant_b", "Plant_c", "Plant_d", "Plant_e",
                     "Plant_f", "Plant_g", "Plant_h", "Plant_i", "Plant_j")
```

Then we convert the phylogeny to a `phylo4` class defined in the package
`phylobase`. This allows users to easily work with data for each tip in
the phylogeny, for example whether they are endemic to the island or not.

```{r convert phylo to phylo4}
phylo <- phylobase::phylo4(phylo)
phylobase::plot(phylo)
```

Now we have a phylogeny in the `phylo4` format to which we can easily append data. In this example,
we randomly simulate island endemicity status for each tip, assuming each species has an
equal probability of being not on the island (`"not_present"`), endemic to the
island (`"endemic"`) or non-endemic to the island (`"nonendemic"`). (**In a real example
this should be based on the actual endemicity status of each species!**).

```{r create island endemcity data}
endemicity_status <- sample(
  x = c("not_present", "endemic", "nonendemic"),
  size = length(phylobase::tipLabels(phylo)),
  replace = TRUE,
  prob = c(0.6, 0.2, 0.2)
)
```

Next, we can add the endemicity data to our phylogenetic tree using the `phylo4d`
class, again from the `phylobase` package. This call is designed for
phylogenetic and trait data to be stored together. The endemicity status needs
to be converted into a data frame in order for the column to be labelled 
correctly.

```{r convert to phylo4d}
phylod <- phylobase::phylo4d(phylo, as.data.frame(endemicity_status))
```

We can now visualise our phylogeny with the island endemicity statuses plotted at
the tips. This uses the `ggtree` and `ggplot2` packages.

```{r plot phylogeny with tip data}
plot_phylod(phylod = phylod)
```

Now that we can see the tips that are present on the island, we can
extract them to form our island community data set that can be used in the
`DAISIE` R package to fit likelihood models of island colonisation and 
diversification.

Before we extract species, we will first create an object to store all of the 
island colonists' information. This uses the `island_tbl` class introduced
in this package (`DAISIEprep`). The `island_tbl` is an S4 class. This `island_tbl`
object can then easily be converted to a DAISIE data list using the function 
`create_daisie_data` (more information on this below).

```{r create island_tbl}
island_tbl <- island_tbl()
island_tbl
```

We can see that this is a object containing an empty data frame. In order to fill
this data frame with information on the island colonisation and diversification
events we can run:

```{r extract island data}
island_tbl <- extract_island_species(
  phylod = phylod,
  extraction_method = "min"
)
island_tbl
```
The function `extract_island_species()` is the main function in `DAISIEprep` to 
extract data from the phylogeny. In the example above, we used the "min" extraction
algorithm. The "min" algorithm extracts island community data with the assumptions
of the DAISIE model (i.e. no back-colonisation from the island to the mainland), but we recommend using
the "asr" algorithm when back-colonisation events are present in the data (for example, one species within a large endemic island radiation colonised another island or mainland). 
Each row in the `island_tbl` corresponds to a separate colonisation of the island. **In this case, two colonist lineages were identified using the 'min' extraction algorithm, one endemic and another non-endemic.**


However, if we do not want to use the "min" algorithm, and instead want to 
extract the most likely colonisations inferred in an ancestral
state reconstruction, we need to know the probability of the ancestors of the 
island species being on the island to determine the time of colonisation. To do 
this we can fit one of many ancestral state reconstruction methods. Here we use 
maximum parsimony as it is a simple method that should prove reliable for 
reconstructing the ancestral species areas (i.e. on the island or not on the
island) for most cases. First, we translate our extant species endemicity status 
to a numeric representation of whether that species is on the island. We add one,
as the ancestral state reconstruction method cannot handle zero as a state. 

```{r}
phylod <- add_asr_node_states(phylod = phylod, asr_method = "parsimony")
```

Now we can plot the phylogeny, which this time includes the node labels for the 
presence/absence on the island in ancestral nodes.

```{r plot phylogeny with tip and node data}
plot_phylod(phylod = phylod)
```

\
\

Sidenote: if you are wondering what the probabilities are at each node
and whether this should influence your decision to pick a preference for island
or mainland when the likelihoods for each state are equal, we can plot the
probabilities at the nodes to visualise the ancestral state reconstruction using
`plot_phylod(phylod = phylod, node_pies = TRUE)`.

\

Now we can extract island colonisation and diversification times from the phylogeny
using the reconstructed ancestral states of island presence/absence. 

```{r}
island_tbl <- extract_island_species(
  phylod = phylod,
  extraction_method = "asr"
)
```

```{r display asr island_tbl}
island_tbl
```
**As you can see, in this case using the `asr` algorithm we find a single colonisation of the island**,
as can be seen by the fact that the `island_tbl` only has one row.


\

Now that we have the `island_tbl` we can convert this to the DAISIE data list to be used by the DAISIE inference
model. 

To convert to the DAISIE data list ( i.e. the input data of the DAISIE inference 
model) we use `create_daisie_data()`, providing the `island_tbl` as input. We also need to specify:


- The age of the island or archipelago. Here we use an island age
of one million years (`island_age = 1`).
- Whether the colonisation times 
extracted from the phylogenetic data should be considered precise 
(`precise_col_time = TRUE`). We will not discuss the details of this here, but
briefly by setting this to `TRUE` the data will tell the DAISIE model that the 
colonisation times are known without error. Setting `precise_col_time = FALSE`
will change tell the DAISIE model that the colonisation time is 
uncertain and should interpret this as the upper limit to the time of 
colonisation and integrate over the uncertainty between this point and either 
the present time or to the first branching point (either speciation or 
divergence into subspecies). 
- The number of 
species in the mainland source pool. Here we set it to 100
(`num_mainland_species = 100`). This will be used to calculate the number of 
species that could have potentially colonised the island but have not. When we
refer to the mainland pool, this does not necessarily have to be a continent,
it could be a different island if the source of species immigrating to an island
is largely from another nearby island (a possible example of this could be 
Madagascar being the source of species colonising Comoros). This
information is used by the DAISIE model to calculate the colonisation rate of 
the island.

```{r} 
data_list <- create_daisie_data(
  data = island_tbl,
  island_age = 1,
  num_mainland_species = 100,
  precise_col_time = TRUE
)
```

Below we show two elements of the DAISIE data list produced. The first
element `data_list[[1]]` in every DAISIE data list is the island community
metadata, containing
the island age and the number of species in the mainland pool that did not 
leave descendants on the island at the present day. This is important information
for DAISIE inference, 
as it is possible some mainland species colonised the island but went extinct
leaving no trace of their island presence.

```{r}
data_list[[1]]
```

Next is the first element containing information on island colonists (every
element `data_list[[x]]` in the list after the metadata contains information on 
individual island
colonists). This contains the name of the colonist, the number of missing 
species, and the branching times, which is a vector containing the age of the island, the
colonisation time and the times of any cladogenesis events. Confusingly, it may be that
the branching times vector contains no branching times: when there are only two
numbers in the vector these are the island age followed by the colonisation time. Then 
there is the stac, which stands for status of colonist. This is a number which
tells the DAISIE model how to identify the endemicity and colonisation uncertainty
of the island colonist ([these are explained here if you are interested](https://cran.r-project.org/package=DAISIE/vignettes/stac_key.html)).
Lastly, the type1or2 defines which macroevolutionary
regime an island colonist is in. By macroevolutionary regime we mean the set of
rates of colonisation, speciation and extinction for that colonist. Most 
applications will assume all island clades have the same regime and thus all
are assigned type 1. However, if there is **a priori** expectation that one
clade significantly different from the rest, e.g. the Galápagos finches amongst
the other terrestrial birds of the Galápagos archipelago this clade can be 
set to type 2.

```{r}
data_list[[2]]
```

This data list is now ready to be used in the DAISIE maximum likelihood inference model
from the R package `DAISIE`. For more information on the DAISIE data structures
and their application in the DAISIE models see this [vignette on optimising parameters using DAISIE](https://CRAN.R-project.org/package=DAISIE/vignettes/demo_optimize.html)

\
\


## 2. Galápagos Empirical Example

#### In this section we demonstrate an empirical use case of the package on the avifauna of the Galápagos archipelago, which uses several phylogenies for different island colonists.

In the previous example we used a single phylogeny and extracted the
colonisation and branching events from it. However, it could be the case that 
island species have been sampled in different phylogenies. Here we look at an example for the terrestrial
birds of the Galápagos archipelago. There are 8 
time-calibrated phylogenies to extract the colonisation and diversification date from. 

First, the phylogenies need to be loaded using the function `read.nexus()` from 
the R package `ape`. Here the data is stored in `extdata` so we use 
`system.file()` to find the file and read it into the environment. This code is
functionally doing the same this as `data()` if the data were stored in the data/
folder, so if the code seems confusing just remember it is loading the phylogeny
into memory for each group.

```{r}
coccyzus_tree <- ape::read.nexus(
  file = system.file("extdata", "Coccyzus.tre", package = "DAISIEprep")
)
columbiformes_tree <- ape::read.nexus(
  file = system.file("extdata", "Columbiformes.tre", package = "DAISIEprep")
)
finches_tree <- ape::read.nexus(
  file = system.file("extdata", "Finches.tre", package = "DAISIEprep")
)
mimus_tree <- ape::read.nexus(
  file = system.file("extdata", "Mimus.tre", package = "DAISIEprep")
)
myiarchus_tree <- ape::read.nexus(
  file = system.file("extdata", "Myiarchus.tre", package = "DAISIEprep")
)
progne_tree <- ape::read.nexus(
  file = system.file("extdata", "Progne.tre", package = "DAISIEprep")
)
pyrocephalus_tree <- ape::read.nexus(
  file = system.file("extdata", "Pyrocephalus.tre", package = "DAISIEprep")
)
setophaga_tree <- ape::read.nexus(
  file = system.file("extdata", "Setophaga.tre", package = "DAISIEprep")
)
```

Currently the phylogenies are loaded as S3 phylo objects, however, we want to
convert them into S4 phylobase objects.

```{r convert Galapagos phylos to phylo4}
coccyzus_tree <- as(coccyzus_tree, "phylo4")
columbiformes_tree <- as(columbiformes_tree, "phylo4")
finches_tree <- as(finches_tree, "phylo4")
mimus_tree <- as(mimus_tree, "phylo4")
myiarchus_tree <- as(myiarchus_tree, "phylo4")
progne_tree <- as(progne_tree, "phylo4")
pyrocephalus_tree <- as(pyrocephalus_tree, "phylo4")
setophaga_tree <- as(setophaga_tree, "phylo4")
```

Now that all of the phylogenies are loaded we can inspect them. Let's start with
the phylogeny for the genus *Coccyzus*:

```{r}
phylobase::plot(coccyzus_tree, cex = 0.1)
```

We can now create a table (data frame) of the *Coccyzus* species that are on the
island and their island endemicity status. This table can be imported from a .csv
or spreadsheet if you prefer.

The species names on the tree (tips labels) can be extracted using 
`phylobase::tiplabels(coccyzus_tree)`. **Make sure the spelling matches exactly
including any whitespace and underscores, and the case of the names.**

```{r}
island_species <- data.frame(
  tip_labels = c("Coccyzus_melacoryphus_GALAPAGOS_L569A",
                 "Coccyzus_melacoryphus_GALAPAGOS_L571A"),
  tip_endemicity_status = c("nonendemic", "nonendemic")
)
```

In order to not have to specify the endemicity status for all species in the 
phylogeny and instead focus only the island species, we can easily assign the endemicity status for the rest of the
species in the tree. Using the `island_species` data frame produced above,
which specifies the island endemicity status of only the species that are found on the island,
we can generate the rest of the endemicity statuses for those species that are in the phylogeny
but are not present on the island using `create_endemicity_status()`.

```{r}
endemicity_status <- create_endemicity_status(
  phylo = coccyzus_tree,
  island_species = island_species
)
```

Now we have the endemicity status for all *Coccyzus* species in the phylogeny, we can 
combine our phylogenetic data and endemicity status data into a single data
structure, the `phylo4d` class from the `phylobase` R package, in exactly the 
same way as in the [single phylogeny example](## 1. Single Phylogeny Example).

```{r}
phylod <- phylobase::phylo4d(coccyzus_tree, endemicity_status)
```

We can visualize the endemicity status of these species on the tree.

```{r plot coccyzus phylogeny with tip data}
plot_phylod(phylod = phylod)
```

\

We are now ready to extract the relevant data from the phylogeny, to produce the
`island_tbl` for the *Coccyzus* tree. For this step we use the "asr" method to
extract the data which requires inferring the ancestral geography of each species.

```{r}
phylod <- add_asr_node_states(
  phylod = phylod,
  asr_method = "parsimony",
  tie_preference = "mainland"
)
```

Plot the phylogeny with the node states:
```{r plot phylogeny with tip and node data Coccyzus}
plot_phylod(phylod = phylod)
```

\

Extract the data from the phylogeny:
```{r extract Coccyzus}
island_tbl <- extract_island_species(
  phylod = phylod,
  extraction_method = "asr"
)
```


```{r}
island_tbl
```

Instead of assigning the endemicity to each of the Galapagos bird phylogenies 
and converting them to `phylo4d` objects (as we did for *Coccyzus* above ), 
this has already been done and the 
data objects have been prepared in advance and are ready to be used.

```{r load galapagos phylod data}
coccyzus_phylod <- readRDS(
  file = system.file("extdata", "coccyzus_phylod.rds", package = "DAISIEprep")
)
columbiformes_phylod <- readRDS(
  file = system.file(
    "extdata", "columbiformes_phylod.rds", package = "DAISIEprep"
  )
)
finches_phylod <- readRDS(
  file = system.file("extdata", "finches_phylod.rds", package = "DAISIEprep")
)
mimus_phylod <- readRDS(
  file = system.file("extdata", "mimus_phylod.rds", package = "DAISIEprep")
)
myiarchus_phylod <- readRDS(
  file = system.file("extdata", "myiarchus_phylod.rds", package = "DAISIEprep")
)
progne_phylod <- readRDS(
  file = system.file("extdata", "progne_phylod.rds", package = "DAISIEprep")
)
pyrocephalus_phylod <- readRDS(
  file = system.file(
    "extdata", "pyrocephalus_phylod.rds", package = "DAISIEprep"
  )
)
setophaga_phylod <- readRDS(
  file = system.file("extdata", "setophaga_phylod.rds", package = "DAISIEprep")
)
```

We now have the data for all 8 phylogenies in the correct format, that is: 
a dated phylogeny, with tips written in "Genus_species" 
or "Genus_species_TAG" format and with the island endemicity status specified
for all tips. We are now ready to extract the
island data from these trees using `extract_island_species()`, using the "asr"
algorithm. 

```{r extract first Galapagos clade}
island_tbl <- extract_island_species(
  phylod = coccyzus_phylod,
  extraction_method = "asr"
)
```

We can now loop through the rest of the Galapagos phylogenies and add them to the 
island data.

```{r extract the other Galapagos clades}
galapagos_phylod <- list(
  coccyzus_phylod, columbiformes_phylod, finches_phylod, mimus_phylod,
  myiarchus_phylod, progne_phylod, pyrocephalus_phylod, setophaga_phylod
)

for (phylod in galapagos_phylod) {
  island_tbl <- extract_island_species(
    phylod = phylod,
    extraction_method = "asr",
    island_tbl = island_tbl
  )
}
```

This will return a warning message for the Darwin's finches as the root state of
the finches phylogeny is inferred to be present on the island, as there is only a single
mainland outgroup in the example phylogeny. This means that the colonisation time will
be extracted in `asr` as infinite and then when the island_tbl is converted into a DAISIE
data list this will become a colonist that could have colonised anywhere from 
the island origin to the present. For this example this colonisation time is 
not a problem, however, for empirical analyses it is recommended to have many
more mainland outgroup species in the tree to ensure the ancestral state 
reconstructions can accurately detect the stem age of the island clade. 

```{r plot Darwins finches}
plot_phylod(finches_phylod)
```

```{r inspect final island table}
island_tbl
```

Now we have the `island_tbl` with all the data on the colonisation, 
branching times, and composition of each island colonist. We can convert
it to a DAISIE data list to be applied to the DAISIE inference 
model. Here we use an island age of the Galápagos archipelago of four million years,
and assume that all colonisation time extracted are precise. Whether they are
in fact precise is not covered in this tutorial, and when using this pipeline
to process different data it may be worth toggling the `precise_col_time` to 
`FALSE` to check whether assuming uncertainty in colonisation times influences
conclusions. 

```{r create Galapagos data list} 
data_list <- create_daisie_data(
  data = island_tbl,
  island_age = 4,
  num_mainland_species = 100,
  precise_col_time = TRUE
)
```
The `data_list` produced above is now ready for your DAISIE analyses! 
[See vignette on optimising parameters using DAISIE](https://CRAN.R-project.org/package=DAISIE/vignettes/demo_optimize.html)

## 3. Adding missing species 

It is often the case that phylogenetic data is not available for some island 
species or even entire lineages present in the island community. But we can still
include these species in our DAISIE analyses.
Furthermore, even in the cases where a dated phylogeny does exist,
it may not be open-source and available to use for the 
extraction. In the latter cases, it may be possible to know the stem age or crown
age if reported in the literature with the published phylogeny. This section 
is about the tools that `DAISIEprep` provides in order to handle missing data,
and generally to handle species that are missing and need to be input into the
data manually.

For this section, as with the previous section, the core data structure we are
going to work with is the `island_tbl`. We will use the `island_tbl` for the 
Galápagos birds produced in the last section. I


### 3.1 Adding missing species to an island clade that has been sampled in the phylogeny

This option is for cases in which a clade has been sampled in the phylogeny, and at least 1 colonisation or 1 branching time is available, but 1 or more species were not sampled.
For this example, we imagine that 2 species of Galápagos finch have not been 
sampled, and that we want to add them as missing species to the Galápagos 
finch clade that is sampled in the phylogeny.
The finches have the clade name "C_fus" in the `island_tbl` (third row). 
To assign two missing species
to this clade we use following code:

```{r}
island_tbl <- add_missing_species(
  island_tbl = island_tbl,
  # num_missing_species equals total species missing
  num_missing_species = 2,
  # name of a sampled species you want to "add" the missing to
  # it can be any in the clade
  species_to_add_to = "C_fus"
)
```

The argument `species_name` uses a representative sampled species from that island clade
to work out which colonist in the `island_tbl` to assign the specified number
of missing species (`num_missing_species`) to. In this case we used the species
in the clade name, however, this could also have been any sampled species from the 
clade, which include: 

```{r}
island_tbl@island_tbl$species[[3]]
```

With the new missing species added to the `island_tbl` we can repeat the
conversion steps above using `create_daisie_data()`
to produce data accepted by the DAISIE model.

### 3.2 Adding a lineage with just one species on the island (singleton) when a phylogeny is not available for the lineage, but a colonisation time estimate exists

The next option for adding **a singleton lineage (just one species on the island)** when a phylogeny is not available
to conduct the extraction using `extract_island_species()` but an estimate of the stem age of 
the island colonist is known from the literature. In this case, we need to input all 
the information on the lineage manually ourselves. For illustrative purposes
we use an imaginary Galápagos bird lineage with 1 species, which is not in our 
data set, and fabricate the time of colonisation. 

The input needed are: 

  * `island_tbl` to add to an existing `island_tbl`
  * `clade_name` a name to represent the clade, can either be a specific species
  from the clade or a genus name, or another name that represent those species
  * `status` either "endemic" or "nonendemic"
  * `missing_species` **In the case of a lineage with just 1 species (i.e. not an island radiation) 
  the number of missing species is zero, as by adding the colonist it already counts as
  one automatically.** 
  * `col_time` the time of colonisation in million years before the present
  * `col_max_age` a boolean (TRUE/FALSE) on whether the colonisation time is 
  precise or should be considered a maximum upper bound on the time of 
  colonisation with some uncertainty
  * `branching_times` the times an island clade has speciated *in situ* on the 
  island. If an island clade has not speciated (i.e. is a singleton) this is NA.
  * `min_age` is the minimum lower bound time of colonisation, if to be used when
  the colonisation time is assumed to be an upper bound.
  * `species` a vector of species names contained within colonist
  * `clade_type` a number representing which set of rates the colonist is assumed
  to be under, default is 1, as number greater than one assume this clade is 
  exceptionally different in its colonisation and diversification dynamics

```{r}
island_tbl <- add_island_colonist(
  island_tbl = island_tbl,
  clade_name = "Bird_a",
  status = "endemic",
  # clade with just 1 species, missing_species = 0
  # because adding the lineage already counts as 1
  missing_species = 0,
  col_time = 2.5,
  col_max_age = FALSE,
  branching_times = NA_real_,
  min_age = NA_real_,
  species = "Bird_a",
  clade_type = 1
)
```

With the new missing species added to the `island_tbl` we can repeat the
conversion steps above using `create_daisie_data()`
to produce data accepted by the DAISIE model.


### 3.3 Adding a lineage with 2 or more species on the island when a phylogeny is not available for the lineage, but a colonisation time estimate exists

Taking the example above in `3.2`, but when the **lineage has more 2 or more species**. In this case, we
we use an imaginary Galápagos bird lineage with 3 species, which is not in our 
data set, and fabricate the time of colonisation. 

The input needed are: 

  * `island_tbl` to add to an existing `island_tbl`
  * `clade_name` a name to represent the clade, can either be a specific species
  from the clade or a genus name, or another name that represent those species
  * `status` either "endemic" or "nonendemic"
  * `missing_species` **The number of missing species in this case should be `n-1`, 
  because adding the lineage manually already counts as 1.** 
  * `col_time` the time of colonisation in million years before the present
  * `col_max_age` a boolean (TRUE/FALSE) on whether the colonisation time is 
  precise or should be considered a maximum upper bound on the time of 
  colonisation with some uncertainty
  * `branching_times` the times an island clade has speciated *in situ* on the 
  island. If an island clade has not speciated (i.e. is a singleton) this is NA.
  * `min_age` is the minimum lower bound time of colonisation, if to be used when
  the colonisation time is assumed to be an upper bound.
  * `species` a vector of species names contained within colonist
  * `clade_type` a number representing which set of rates the colonist is assumed
  to be under, default is 1, as number greater than one assume this clade is 
  exceptionally different in its colonisation and diversification dynamics

```{r}
island_tbl <- add_island_colonist(
  island_tbl = island_tbl,
  clade_name = "Bird_b",
  status = "endemic",
  # the total species is 3 and all are missing
  # but we add missing_species = 2 because
  # adding the lineage already counts as 1
  missing_species = 2,
  col_time = 2.5,
  col_max_age = FALSE,
  branching_times = NA_real_,
  min_age = NA_real_,
  clade_type = 1,
  species = c("Bird_b", "Bird_c", "Bird_d")
)
```

With the new missing species added to the `island_tbl` we can repeat the
conversion steps above using `create_daisie_data()`
to produce data accepted by the DAISIE model.

### 3.4 Adding a lineage when a phylogeny is not available for the lineage, and no colonisation estimate is available.

Taking the examples above in `3.2` and `3.3` but assuming we did not have any phylogenetic data
or colonisation time estimate for
the island clade, we could again insert the species as missing but this time not
give the colonisation time. When this colonist later gets processed by the DAISIE
inference model it will be assumed it colonised the island any time between the 
island's formation (in the case of the Galápagos four million years ago) and the 
present.

 * `missing_species` **In the case of a lineage with just 1 species (i.e. not an island radiation) 
  the number of missing species is zero, as by adding the colonist it already counts as
  one automatically. In the case of an island clade of more than one 
  species, the number of missing species in this case should be `n-1`.** 

Example for adding lineage with 1 species:
```{r}
island_tbl <- add_island_colonist(
  island_tbl = island_tbl,
  clade_name = "Bird_e",
  status = "endemic",
  # clade with just 1 species, missing_species = 0
  # because adding the lineage already counts as 1
  missing_species = 0,
  col_time = NA_real_,
  col_max_age = FALSE,
  branching_times = NA_real_,
  min_age = NA_real_,
  clade_type = 1,
  species = "Bird_e"
)
```

Example for adding lineage with 5 species:
```{r}
island_tbl <- add_island_colonist(
  island_tbl = island_tbl,
  clade_name = "Bird_f",
  status = "endemic",
  # the total species is 5 and all are missing
  # but we add missing_species = 4 because
  # adding the lineage already counts as 1
  missing_species = 4,
  col_time = NA_real_,
  col_max_age = FALSE,
  branching_times = NA_real_,
  min_age = NA_real_,
  clade_type = 1,
  species = c("Bird_f", "Bird_g", "Bird_h",
              "Bird_i", "Bird_j")
)
```

With the new missing species added to the `island_tbl` we can repeat the
conversion steps above using `create_daisie_data()`
to produce data accepted by the DAISIE model.

### 3.5 Adding a lineage when a phylogeny is not available for the entire island lineage, but a crown age or minimum colonisation time estimate exists

Taking the example above in `3.2`, but assuming we did not have a colonisation time 
estimate, but we did have a crown age estimate or an estimate for the 
minimum (latest) time the island could have been colonised by the lineage. When this colonist 
later gets processed by the DAISIE inference model it will be assumed 
it colonised the island any time between the 
island's formation (in the case of the Galápagos four million years ago) and the 
crown or minimum age. In the example below we assume a crown age of 2 million years.

```{r}
island_tbl <- add_island_colonist(
  island_tbl = island_tbl,
  clade_name = "Bird_k",
  status = "endemic",
  missing_species = 0,
  col_time = NA_real_,
  col_max_age = FALSE,
  branching_times = NA_real_,
  min_age = 2,
  species = "Bird_k",
  clade_type = 1
)
```

With the new missing species added to the `island_tbl` we can repeat the
conversion steps above using `create_daisie_data()`
to produce data accepted by the DAISIE model.

```{r} 
data_list <- create_daisie_data(
  data = island_tbl,
  island_age = 4,
  num_mainland_species = 100,
  precise_col_time = TRUE
)
```