Skip to contents

DAISIEprep Tutorial

Source: vignettes/Tutorial.Rmd
Tutorial.Rmd

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:

library(DAISIEprep)
library(ape)
library(phylobase)
#> 
#> Attaching package: 'phylobase'
#> The following object is masked from 'package:ape':
#> 
#>     edges
library(ggtree)
#> ggtree v3.12.0 For help: https://yulab-smu.top/treedata-book/
#> 
#> If you use the ggtree package suite in published research, please cite
#> the appropriate paper(s):
#> 
#> Guangchuang Yu, David Smith, Huachen Zhu, Yi Guan, Tommy Tsan-Yuk Lam.
#> ggtree: an R package for visualization and annotation of phylogenetic
#> trees with their covariates and other associated data. Methods in
#> Ecology and Evolution. 2017, 8(1):28-36. doi:10.1111/2041-210X.12628
#> 
#> LG Wang, TTY Lam, S Xu, Z Dai, L Zhou, T Feng, P Guo, CW Dunn, BR
#> Jones, T Bradley, H Zhu, Y Guan, Y Jiang, G Yu. treeio: an R package
#> for phylogenetic tree input and output with richly annotated and
#> associated data. Molecular Biology and Evolution. 2020, 37(2):599-603.
#> doi: 10.1093/molbev/msz240
#> 
#> Guangchuang Yu, Tommy Tsan-Yuk Lam, Huachen Zhu, Yi Guan. Two methods
#> for mapping and visualizing associated data on phylogeny using ggtree.
#> Molecular Biology and Evolution. 2018, 35(12):3041-3043.
#> doi:10.1093/molbev/msy194 
#> 
#> Attaching package: 'ggtree'
#> The following object is masked from 'package:phylobase':
#> 
#>     MRCA
#> The following object is masked from 'package:ape':
#> 
#>     rotate
library(ggimage)
#> Loading required package: ggplot2
library(castor)
#> Loading required package: Rcpp

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.

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.

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.

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!).

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.

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.

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).

island_tbl <- island_tbl()
island_tbl
#> Class:  Island_tbl 
#> [1] clade_name      status          missing_species col_time       
#> [5] col_max_age     branching_times min_age         species        
#> [9] clade_type     
#> <0 rows> (or 0-length row.names)

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:

island_tbl <- extract_island_species(
  phylod = phylod,
  extraction_method = "min"
)
island_tbl
#> Class:  Island_tbl 
#>   clade_name     status missing_species   col_time col_max_age branching_times
#> 1    Plant_g nonendemic               0 0.38003405       FALSE              NA
#> 2    Plant_i    endemic               0 0.04960523       FALSE              NA
#>   min_age species clade_type
#> 1      NA Plant_g          1
#> 2      NA Plant_i          1

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.

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.

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.

island_tbl <- extract_island_species(
  phylod = phylod,
  extraction_method = "asr"
)
island_tbl
#> Class:  Island_tbl 
#>   clade_name  status missing_species  col_time col_max_age branching_times
#> 1    Plant_g endemic               0 0.7648553       FALSE    0.380034....
#>   min_age      species clade_type
#> 1      NA Plant_g,....          1

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.
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.

data_list[[1]]
#> $island_age
#> [1] 1
#> 
#> $not_present
#> [1] 99

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). 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.

data_list[[2]]
#> $colonist_name
#> [1] "Plant_g"
#> 
#> $branching_times
#> [1] 1.0000000 0.7648553 0.3800341
#> 
#> $stac
#> [1] 2
#> 
#> $missing_species
#> [1] 0
#> 
#> $type1or2
#> [1] 1

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



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.

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.

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:

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.

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().

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.

phylod <- phylobase::phylo4d(coccyzus_tree, endemicity_status)

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

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.

phylod <- add_asr_node_states(
  phylod = phylod,
  asr_method = "parsimony",
  tie_preference = "mainland"
)

Plot the phylogeny with the node states:

plot_phylod(phylod = phylod)


Extract the data from the phylogeny:

island_tbl <- extract_island_species(
  phylod = phylod,
  extraction_method = "asr"
)
island_tbl
#> Class:  Island_tbl 
#>              clade_name     status missing_species col_time col_max_age
#> 1 Coccyzus_melacoryphus nonendemic               0 1.789425       FALSE
#>   branching_times   min_age      species clade_type
#> 1              NA 0.5483906 Coccyzus....          1

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.

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.

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.

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
  )
}
#> Warning in extract_species_asr(phylod = phylod, species_label = as.character(phylod@label[i]), : Root of the phylogeny is on the island so the colonisation
#>               time from the stem age cannot be collected, colonisation time
#>               will be set to infinite.

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.

plot_phylod(finches_phylod)

island_tbl
#> Class:  Island_tbl 
#>                                 clade_name     status missing_species  col_time
#> 1                    Coccyzus_melacoryphus nonendemic               0 1.7894251
#> 2 Zenaida_galapagoensis_GALAPAGOS_AF251531    endemic               0 3.1933725
#> 3                                    C_fus    endemic               0       Inf
#> 4      Mimus_macdonaldi_GALAPAGOS_KF411075    endemic               0 4.4853284
#> 5                         M_magnirostris_1    endemic               0 0.8544740
#> 6           Progne_modesta_GALAPAGOS_L573A    endemic               0 3.0014710
#> 7      Pyrocephalus_dubius_Galapagos_cas01    endemic               0 9.3661766
#> 8             D_petechia_Galapagos_sancris    endemic               0 0.1400011
#>   col_max_age branching_times   min_age      species clade_type
#> 1       FALSE              NA 0.5483906 Coccyzus....          1
#> 2       FALSE    0.050253....        NA Zenaida_....          1
#> 3       FALSE    1.322705....        NA C_fus, C....          1
#> 4       FALSE    3.680027....        NA Mimus_ma....          1
#> 5       FALSE    0.222988....        NA M_magnir....          1
#> 6       FALSE    0.387570....        NA Progne_m....          1
#> 7       FALSE    0.825248....        NA Pyroceph....          1
#> 8       FALSE    0.057946....        NA D_petech....          1

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.

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

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:

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:

island_tbl@island_tbl$species[[3]]
#>  [1] "C_fus"  "C_oliv" "P_cras" "G_diff" "C_pau"  "C_par"  "C_psi"  "C_hel" 
#>  [9] "C_pal"  "G_sep"  "G_for"  "G_ful"  "G_con"  "G_mag"  "G_scan"

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
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
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:

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:

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.

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.

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