---
title: "Case study: the true finches"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Case study: the true finches}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup, include = FALSE}
library(datelife)
```

The family Fringillidae is a taxon that includes the true finches. Let's see what is known about their time of divergence.

## 1. Getting species names within the family Fringillidae

DateLife searches its chronogram database using species names standardized to a [unified taxonomy](https://tree.opentreeoflife.org/about/taxonomy-version/ott3.3) constructed by the Open Tree of Life project.

When working with taxon names above the species level in DateLife, the first step is to obtain all species names belonging to the taxon of interest. 

We will get all species names belonging to the family Fringillidae, using the flag `get_spp_from_taxon = TRUE` from the function `datelife::make_datelife_query()`:

```r
dquery <- datelife::make_datelife_query(input = "fringillidae",               
                                   get_spp_from_taxon = TRUE)

#> ... Making a DateLife query.
#> ... Phylo-processing 'input'.
#> 'input' is not a phylogeny.
#>   |=========================================================| 100%
#>   |=========================================================| 100%
#>   |=========================================================| 100%
#>   |=========================================================| 100%
#>   |=========================================================| 100%
#> Working with the following taxa:
#>	Crithagra sulphurata | Crithagra citrinelloides | Crithagra mozambica | Crithagra capistrata | Crithagra burtoni | Crithagra rufobrunnea | Crithagra flaviventris | Callacanthis burtoni | Chaunoproctus ferreorostris | Rhynchostruthus socotranus | Chlorophonia cyanea | Chlorophonia occipitalis | Chlorophonia flavirostris | Akialoa obscura | Euphonia gouldi | Euphonia plumbea | Euphonia elegantissima | Euphonia luteicapilla | Euphonia chrysopasta | Euphonia fulvicrissa | Euphonia hirundinacea | Euphonia chlorotica | Euphonia cyanocephala | Euphonia rufiventris | Euphonia minuta | Euphonia cayennensis | Euphonia xanthogaster | Euphonia violacea | Euphonia pectoralis | Euphonia musica | Euphonia anneae | Euphonia affinis | Euphonia laniirostris | Euphonia finschi | Psittirostra psittacea | Urocynchramus pylzowi | Telespiza cantans | Telespiza ultima | Palmeria dolei | Oreomystis bairdi | Loxops coccineus | Loxops mana | Loxops caeruleirostris | Himatione sanguinea | Rhodopechys sanguineus | Paroreomyza montana | Pseudonestor xanthophrys | Vestiaria coccinea | Bucanetes githagineus | Hemignathus parvus | Hemignathus wilsoni | Hemignathus virens | Hemignathus munroi | Hemignathus flavus | Hemignathus kauaiensis | Hemignathus stejnegeri | Loxioides bailleui | Eremopsaltria mongolica | Rhodospiza obsoleta | Peucedramus taeniatus | Cyanerpes caeruleus | Cyanerpes cyaneus | Cyanerpes nitidus | Cyanerpes lucidus | Fringillaria goslingi | Fringillaria striolata | Fringillaria impetuani | Fringillaria poliopleura | Fringillaria tahapisi | Hemispingus atropileus | Hemispingus verticalis | Hemispingus auricularis | Hemispingus calophrys | Hemispingus rufosuperciliaris | Hemispingus superciliaris | Hemispingus trifasciatus | Hemispingus piurae | Hemispingus xanthophthalmus | Hemispingus parodii | Hemispingus goeringi | Hemispingus melanotis | Hemispingus frontalis | Hemispingus reyi | Rowettia goughensis | Embernagra platensis | Schoeniclus rusticus | Schoeniclus aureolus | Schoeniclus elegans | Schoeniclus siemsseni | Schoeniclus spodocephala | Schoeniclus yessoensis | Tersina viridis | Orthogonys chloricterus | Buarremon apertus | Buarremon assimilis | Buarremon atricapillus | Buarremon basilicus | Buarremon virenticeps | Buarremon torquatus | Peucaea aestivalis | Peucaea cassinii | Peucaea botterii | Phaeothlypis fulvicauda | Donacospiza albifrons | Platyspiza crassirostris | Melopyrrha nigra | Carduelis citrinella | Carduelis corsicana | Carduelis carduelis | Uragus sibiricus | Melamprosops phaeosoma | Hesperiphona vespertina | Pyrrhoplectes epauletta | Haemorhous mexicanus | Haemorhous purpureus | Haemorhous cassinii | Kozlowia roborowskii | Serinus syriacus | Serinus albogularis | Serinus atrogularis | Serinus citrinipectus | Serinus citrinella | Serinus pusillus | Serinus canaria | Serinus alario | Serinus striolatus | Serinus melanochrous | Serinus whytii | Serinus mennelli | Serinus reichardi | Serinus scotops | Serinus flavivertex | Serinus totta | Serinus estherae | Serinus hypostictus | Serinus leucopygius | Serinus thibetanus | Serinus gularis | Serinus dorsostriatus | Serinus canicollis | Serinus serinus | Linaria flavirostris | Linaria cannabina | Chloris monguilloti | Chloris sinica | Chloris spinoides | Chloris ambigua | Chloris chloris | Spinus yarrellii | Spinus spinus | Spinus olivaceus | Spinus uropygialis | Spinus siemiradzkii | Spinus atriceps | Spinus dominicensis | Spinus xanthogastrus | Spinus magellanicus | Spinus pinus | Spinus notatus | Spinus tristis | Spinus spinescens | Spinus crassirostris | Spinus barbatus | Spinus atratus | Spinus lawrencei | Spinus psaltria | Spinus cucullatus | Neospiza concolor | Loxia curvirostra | Loxia pytyopsittacus | Loxia leucoptera | Loxia scotica | Eophona migratoria | Eophona personata | Haematospiza sipahi | Mycerobas icterioides | Mycerobas melanozanthos | Mycerobas affinis | Mycerobas carnipes | Pinicola subhimachala | Pinicola enucleator | Linurgus olivaceus | Leucosticte sillemi | Leucosticte arctoa | Leucosticte australis | Leucosticte nemoricola | Leucosticte tephrocotis | Leucosticte atrata | Leucosticte brandti | Carpodacus vinaceus | Carpodacus rodopeplus | Carpodacus davidianus | Carpodacus rhodochlamys | Carpodacus rubescens | Carpodacus synoicus | Carpodacus severtzovi | Carpodacus rodochroa | Carpodacus erythrinus | Carpodacus roseus | Carpodacus nipalensis | Carpodacus trifasciatus | Carpodacus rubicilloides | Carpodacus pulcherrimus | Carpodacus thura | Carpodacus eos | Carpodacus rubicilla | Carpodacus grandis | Carpodacus edwardsii | Carpodacus puniceus | Carpodacus formosanus | Coccothraustes coccothraustes | Acanthis hornemanni | Acanthis cabaret | Acanthis flammea | Pyrrhula nipalensis | Pyrrhula erythaca | Pyrrhula erythrocephala | Pyrrhula murina | Pyrrhula leucogenis | Pyrrhula aurantiaca | Pyrrhula pyrrhula | Fringilla montifringilla | Fringilla teydea | Fringilla coelebs | Fringilla polatzeki | Calcarius lapponicus | Calcarius pictus | Calcarius ornatus | Calcarius mccownii | Emberiza variabilis | Emberiza hortulana | Emberiza pusilla | Emberiza cioides | Emberiza tristrami | Emberiza cabanisi | Emberiza jankowskii | Emberiza cineracea | Emberiza rutila | Emberiza sahari | Emberiza buchanani | Emberiza chrysophrys | Emberiza capensis | Emberiza cia | Emberiza schoeniclus | Emberiza stewarti | Emberiza godlewskii | Emberiza pallasi | Emberiza leucocephalos | Emberiza socotrana | Emberiza melanocephala | Emberiza bruniceps | Emberiza koslowi | Emberiza cirlus | Emberiza flaviventris | Emberiza affinis | Emberiza fucata | Emberiza citrinella | Emberiza sulphurata | Emberiza caesia | Plectrophenax nivalis | Plectrophenax hyperboreus | Melophus lathami | Cyanoloxia glaucocaerulea | Cyanoloxia cyanoides | Cyanoloxia rothschildii | Caryothraustes canadensis | Caryothraustes poliogaster | Cyanocompsa brissonii | Cyanocompsa parellina | Passerina caerulea | Passerina cyanea | Passerina amoena | Passerina ciris | Passerina leclancherii | Passerina rositae | Passerina versicolor | Parkerthraustes humeralis | Spiza americana | Pheucticus aureoventris | Pheucticus ludovicianus | Pheucticus melanocephalus | Pheucticus chrysogaster | Pheucticus tibialis | Cardinalis cardinalis | Cardinalis sinuatus | Cardinalis phoeniceus | Porphyrospiza caerulescens | Rhodothraupis celaeno | Periporphyrus erythromelas
#> DateLife query done!
```

Inspect the structure of the output:

```r
str(dquery)

#> List of 3
#>  $ cleaned_names: Named chr [1:289] "Crithagra sulphurata" "Crithagra #> citrinelloides" "Crithagra mozambica" "Crithagra capistrata" ...
#>   ..- attr(*, "names")= chr [1:289] "Fringillidae1" "Fringillidae2" #> "Fringillidae3" "Fringillidae4" ...
#>  $ ott_ids      : Named int [1:289] 903281 328908 1083721 901359 318589 #> 455546 903271 405220 242220 455541 ...
#>   ..- attr(*, "names")= chr [1:289] "Crithagra sulphurata" "Crithagra #> citrinelloides" "Crithagra mozambica" "Crithagra capistrata" ...
#>  $ phy          : logi NA
#>  - attr(*, "class")= chr "datelifeQuery"
```

We have 289 species names belonging to the family Fringillidae according to OpenTree's unified taxonomy. We did not provide an input tree, so `$phy` is `NA`.

## 2. Search the species names across a chronogram database

Load the prebuilt OpenTree chronogram database object names `opentree_chronograms`:

```r
utils::data("opentree_chronograms", package = "datelife")
```

Use your `datelifeQuery` object named `dquery` to search the chronogram database:

```r
dres <- datelife::get_datelife_result(input = dquery, cache = opentree_chronograms)

#> ... Searching the chronogram database.
#> Search done!
#>
#> Input taxon names were found in 19 chronograms.
```

Results from the chronogram search are returned as a `datelifeResult` object, which is a named list of patristic matrices. Each element of the list corresponds to a chronogram that has been translated to a distance matrix or patristic matrix. The main reason for this is that pruning is much faster on a matrix than on a `phylo` object:

```r
class(dres)
#> [1] "datelifeResult"

typeof(dres)
#> [1] "list"

class(dres[[1]])
#> [1] "matrix" "array"
```

Names on your `datelifeResult` object correspond to study citations from source chronograms:

```r
names(dres)

#> [1] "Hooper, Daniel M., Trevor D. Price. 2017. Chromosomal inversion differences correlate with range overlap in passerine birds. Nature Ecology & Evolution 1 (10): 1526-1534"                                                                                                                                                              
#> [2] "Roquet, C., Lavergne, S., & Thuiller, W. (2014). One Tree to Link Them All: A Phylogenetic Dataset for the European Tetrapoda. PLoS Currents. doi:10.1371/currents.tol.5102670fff8aa5c918e78f5592790e48\n"                                                                                                                              
#> [3] "Roquet, C., Lavergne, S., & Thuiller, W. (2014). One Tree to Link Them All: A Phylogenetic Dataset for the European Tetrapoda. PLoS Currents. doi:10.1371/currents.tol.5102670fff8aa5c918e78f5592790e48\n"                                                                                                                              
#> [4] "Oliveros, C. H., Field, D. J., Ksepka, D. T., Barker, F. K., Aleixo, A., Andersen, M. J., … Faircloth, B. C. (2019). Earth history and the passerine superradiation. Proceedings of the National Academy of Sciences, 116(16), 7916–7925. doi:10.1073/pnas.1813206116\n"                                                                
#> [5] "Kimball, R. T., Oliveros, C. H., Wang, N., White, N. D., Barker, F. K., Field, D. J., … Braun, E. L. (2019). A Phylogenomic Supertree of Birds. Diversity, 11(7), 109. doi:10.3390/d11070109\n"                                                                                                                                         
#> [6] "Kimball, R. T., Oliveros, C. H., Wang, N., White, N. D., Barker, F. K., Field, D. J., … Braun, E. L. (2019). A Phylogenomic Supertree of Birds. Diversity, 11(7), 109. doi:10.3390/d11070109\n"                                                                                                                                         
#> [7] "Uyeda, J. C., Pennell, M. W., Miller, E. T., Maia, R., & McClain, C. R. (2017). The Evolution of Energetic Scaling across the Vertebrate Tree of Life. The American Naturalist, 190(2), 185–199. doi:10.1086/692326\n"                                                                                                                  
#> [8] "Hedges, S. Blair, Julie Marin, Michael Suleski, Madeline Paymer, Sudhir Kumar. 2015. Tree of life reveals clock-like speciation and diversification. Molecular Biology and Evolution 32 (4): 835-845"                                                                                                                                   
#> [9] "Hedges, S. Blair, Julie Marin, Michael Suleski, Madeline Paymer, Sudhir Kumar. 2015. Tree of life reveals clock-like speciation and diversification. Molecular Biology and Evolution 32 (4): 835-845"                                                                                                                                   
#> [10] "Claramunt, Santiago, Joel Cracraft. 2015. A new time tree reveals Earth historys imprint on the evolution of modern birds. Science Advances 1 (11): e1501005-e1501005"                                                                                                                                                                  
#> [11] "Gibb, Gillian C., Ryan England, Gerrit Hartig, P.A. (Trish) McLenachan, Briar L. Taylor Smith, Bennet J. McComish, Alan Cooper, David Penny. 2015. New Zealand passerines help clarify the diversification of major songbird lineages during the Oligocene. Genome Biology and Evolution 7 (11): 2983-2995."                            
#> [12] "Barker, F. Keith, Kevin J. Burns, John Klicka, Scott M. Lanyon, Irby J. Lovette. 2015. New insights into New World biogeography: An integrated view from the phylogeny of blackbirds, cardinals, sparrows, tanagers, warblers, and allies. The Auk 132 (2): 333-348."   

#> [13] "Barker, F. Keith, Kevin J. Burns, John Klicka, Scott M. Lanyon, Irby J. Lovette. 2015. New insights into New World biogeography: An integrated view from the phylogeny of blackbirds, cardinals, sparrows, tanagers, warblers, and allies. The Auk 132 (2): 333-348."                                                                   

#> [14] "Jetz, W., G. H. Thomas, J. B. Joy, K. Hartmann, A. O. Mooers. 2012. The global diversity of birds in space and time. Nature 491 (7424): 444-448"                                                                                              
#> [15] "Jetz, W., G. H. Thomas, J. B. Joy, K. Hartmann, A. O. Mooers. 2012. The global diversity of birds in space and time. Nature 491 (7424): 444-448"                                                                                                                                                                                        
#> [16] "Barker, F. K., K. J. Burns, J. Klicka, S. M. Lanyon, I. J. Lovette. 2013. Going to extremes: contrasting rates of diversification in a recent radiation of New World passerine birds. Systematic Biology 62 (2): 298-320."                                                                                                              
#> [17] "Burns, Kevin J., Allison J. Shultz, Pascal O. Title, Nicholas A. Mason, F. Keith Barker, John Klicka, Scott M. Lanyon, Irby J. Lovette. 2014. Phylogenetics and diversification of tanagers (Passeriformes: Thraupidae), the largest radiation of Neotropical songbirds. Molecular Phylogenetics and Evolution 75: 41-77."              

#> [18] "Price, Trevor D., Daniel M. Hooper, Caitlyn D. Buchanan, Ulf S. Johansson, D. Thomas Tietze, Per Alström, Urban Olsson, Mousumi Ghosh-Harihar, Farah Ishtiaq, Sandeep K. Gupta, Jochen Martens, Bettina Harr, Pratap Singh, Dhananjai Mohan. 2014. Niche filling slows the diversification of Himalayan songbirds. Nature 509: 222-225."

#> [19] "Price, Trevor D., Daniel M. Hooper, Caitlyn D. Buchanan, Ulf S. Johansson, D. Thomas Tietze, Per Alström, Urban Olsson, Mousumi Ghosh-Harihar, Farah Ishtiaq, Sandeep K. Gupta, Jochen Martens, Bettina Harr, Pratap Singh, Dhananjai Mohan. 2014. Niche filling slows the diversification of Himalayan songbirds. Nature 509: 222-225."
```


## 3. Summarizing a `datelifeResult` object

What if you want to plot all your `datelifeResult` chronograms individually? What if you want a single tree summarizing all your source chronograms? The function `datelife::summary.datelifeResult()` will get all types of summaries for you, so you can access them later:

```r
dsumm <- summary(dres, datelife_query = dquery)

#> Trying with overlap = 2
#>
#> Success!
#>
#> ... Calculating a median summary chronogram.
#>   |==========================================================| 100%
#>   |==========================================================| 100%
#>   |==========================================================| 100%
#> 1 out of 13 chronograms tried:  Ok.
#> 2 out of 13 chronograms tried:  Ok.
#> 3 out of 13 chronograms tried:  Ok.
#> 4 out of 13 chronograms tried:  Ok.
#> 5 out of 13 chronograms tried:  Ok.
#> 6 out of 13 chronograms tried:  Ok.
#> 7 out of 13 chronograms tried:  Ok.
#> 8 out of 13 chronograms tried:  Ok.
#> 9 out of 13 chronograms tried:  Ok.
#> 10 out of 13 chronograms tried:  Ok.
#> 12 out of 19 chronograms tried:  Ok.
#> 13 out of 19 chronograms tried:  Ok.
#> 14 out of 19 chronograms tried:  Ok.
#> 15 out of 19 chronograms tried:  Ok.
#> 16 out of 19 chronograms tried:  Ok.
#> 17 out of 19 chronograms tried:  Ok.
#> 18 out of 19 chronograms tried:  Failed.
#> 19 out of 19 chronograms tried:  Ok.
#>
#>  Synthesizing 18 chronograms with SDM
#>   |==========================================================| 100%
#>   |==========================================================| 100%
#>   |==========================================================| 100%
```

Now we can explore different age summaries.

### 3.1 Source chronograms:

Chronograms that matched our database search, and that were pruned to contain only the species names we looked for are called source chronograms. These can be accessed as follow:

```r
dsumm$phylo_all

#> 19 phylogenetic trees
```

By study name:

```r
dsumm$phylo_all$`Gibb, Gillian C., Ryan England, Gerrit Hartig, P.A. (Trish) McLenachan, Briar L. Taylor Smith, Bennet J. McComish, Alan Cooper, David Penny. 2015. New Zealand passerines help clarify the diversification of major songbird lineages during the Oligocene. Genome Biology and Evolution 7 (11): 2983-2995.`

#> Phylogenetic tree with 7 tips and 6 internal nodes.
#> 
#> Tip labels:
#>   Schoeniclus_spodocephala, Emberiza_tristrami, Emberiza_chrysophrys, #> Emberiza_pusilla, Schoeniclus_aureolus, Serinus_canaria, ...
#> 
#> Rooted; includes branch lengths.
```

Or, by index position:

```r
names(dsumm$phylo_all)[1]

#> [1] "Hooper, Daniel M., Trevor D. Price. 2017. Chromosomal inversion differences correlate with range overlap in passerine birds. Nature Ecology & Evolution 1 (10): 1526-1534"

dsumm$phylo_all[[1]]

#> Phylogenetic tree with 44 tips and 43 internal nodes.
#> 
#> Tip labels:
#>   Peucedramus_taeniatus, Peucaea_botterii, Schoeniclus_spodocephala, #> Schoeniclus_aureolus, Emberiza_chrysophrys, Emberiza_pusilla, ...
#> 
#> Rooted; includes branch lengths.
```


