# Making a DateLife query

    library(datelife)

To query DateLife’s chronogram database, taxon names provided as input are processed and matched to the Open Tree of Life taxonomy (OTT). This is done with the function `make_datelife_query()`.

Next, we present some usage examples of this function.

### When `input` is list or vector of taxon names

We can process a single taxon:

    query1 <- make_datelife_query(input = "Canis")
    #> ---> Phylo-processing 'input'.
    #> * 'input' is not a phylogeny.
    #> ---> Making a DateLife query.
    #> ---> Runnning TNRS to match input names to reference taxonomy (OTT).
    #>
      |
      |                                                                      |   0%
      |
      |======================================================================| 100%
    #> ---> Working with the following taxon: Canis.
    #> DateLife query done!

Or several taxon names:

    query10 <- make_datelife_query(input = rep("Canis", 10))
    #> ---> Phylo-processing 'input'.
    #> * 'input' is not a phylogeny.
    #> ---> Making a DateLife query.
    #> ---> Runnning TNRS to match input names to reference taxonomy (OTT).
    #>
      |
      |                                                                      |   0%
      |
      |======================================================================| 100%
    #> ---> Working with the following 10 taxa: Canis | Canis | Canis | Canis | Canis | Canis | Canis | Canis | Canis | Canis.
    #> DateLife query done!

In any case, the output is a list:

    query10
    #> $cleaned_names
    #>  [1] "Canis" "Canis" "Canis" "Canis" "Canis" "Canis" "Canis" "Canis" "Canis"
    #> [10] "Canis"
    #>
    #> $ott_ids
    #>  Canis  Canis  Canis  Canis  Canis  Canis  Canis  Canis  Canis  Canis
    #> 372706 372706 372706 372706 372706 372706 372706 372706 372706 372706
    #>
    #> $phy
    #> [1] NA
    #>
    #> attr(,"class")
    #> [1] "datelifeQuery"

### When `input` names are not found in the taxonomy

The function returns `NA` as taxonomic id for the missing name:

    make_datelife_query2(input = c("Canis", "werewolf", "jupiter"))
    #> ---> Phylo-processing 'input'.
    #> * 'input' is not a phylogeny.
    #> ---> Runnning TNRS to match input names to reference taxonomy (OTT).
    #>
      |
      |                                                                      |   0%
      |
      |=======================                                               |  33%
    #> Warning: werewolf are not matched
    #>
      |
      |===============================================                       |  67%
    #> Warning: jupiter are not matched
    #>
      |
      |======================================================================| 100%
    #> $cleaned_names
    #> [1] "Canis"    "werewolf" "jupiter"
    #>
    #> $tnrs_names
    #> [1] "Canis" NA      NA
    #>
    #> $ott_ids
    #> [1] 372706     NA     NA
    #>
    #> $phy
    #> [1] NA
    #>
    #> attr(,"class")
    #> [1] "datelifeQuery"

### Subspecies can also be searched

    make_datelife_query2(input = "Canis mesomelas elongae")
    #> ---> Phylo-processing 'input'.
    #> * 'input' is not a phylogeny.
    #> ---> Runnning TNRS to match input names to reference taxonomy (OTT).
    #>
      |
      |                                                                      |   0%
      |
      |======================================================================| 100%
    #> $cleaned_names
    #> [1] "Canis mesomelas elongae"
    #>
    #> $tnrs_names
    #> [1] "Canis mesomelas elongae"
    #>
    #> $ott_ids
    #> [1] 576165
    #>
    #> $phy
    #> [1] NA
    #>
    #> attr(,"class")
    #> [1] "datelifeQuery"

    all_subspecies <- c("Canis mesomelas elongae", "Canis mesomelas elongae")
    make_datelife_query2(input = all_subspecies)
    #> ---> Phylo-processing 'input'.
    #> * 'input' is not a phylogeny.
    #> ---> Runnning TNRS to match input names to reference taxonomy (OTT).
    #>
      |
      |                                                                      |   0%
      |
      |======================================================================| 100%
    #> $cleaned_names
    #> [1] "Canis mesomelas elongae" "Canis mesomelas elongae"
    #>
    #> $tnrs_names
    #> [1] "Canis mesomelas elongae" "Canis mesomelas elongae"
    #>
    #> $ott_ids
    #> [1] 576165 576165
    #>
    #> $phy
    #> [1] NA
    #>
    #> attr(,"class")
    #> [1] "datelifeQuery"

    one_subspecies <- c("Canis mesomelas elongae", "Canis adustus", "Lycalopex fulvipes")
    make_datelife_query2(input = one_subspecies)
    #> ---> Phylo-processing 'input'.
    #> * 'input' is not a phylogeny.
    #> ---> Runnning TNRS to match input names to reference taxonomy (OTT).
    #>
      |
      |                                                                      |   0%
      |
      |=======================                                               |  33%
      |
      |===============================================                       |  67%
      |
      |======================================================================| 100%
    #> $cleaned_names
    #> [1] "Canis mesomelas elongae" "Canis adustus"
    #> [3] "Lycalopex fulvipes"
    #>
    #> $tnrs_names
    #> [1] "Canis mesomelas elongae" "Canis adustus"
    #> [3] "Lycalopex fulvipes"
    #>
    #> $ott_ids
    #> [1] 576165 621176 996573
    #>
    #> $phy
    #> [1] NA
    #>
    #> attr(,"class")
    #> [1] "datelifeQuery"

### Choosing between homonyms

Taxonomic homonyms are valid names that are used for different biological entities. For example, the genus name Aotus refers to a monkey and a grass. TNRS is smart enough to choose a taxonomic context for a set of names, but it is not infallible.

For example, when referring to the grass, TNRS chooses the correct taxon id:

    make_datelife_query2(input = c("Aotus", "Poa", "Arabidopsis"))
    #> ---> Phylo-processing 'input'.
    #> * 'input' is not a phylogeny.
    #> ---> Runnning TNRS to match input names to reference taxonomy (OTT).
    #>
      |
      |                                                                      |   0%
      |
      |=======================                                               |  33%
      |
      |===============================================                       |  67%
      |
      |======================================================================| 100%
    #> $cleaned_names
    #> [1] "Aotus"       "Poa"         "Arabidopsis"
    #>
    #> $tnrs_names
    #> [1] "Aotus (genus in kingdom Archaeplastida)"
    #> [2] "Poa"
    #> [3] "Arabidopsis"
    #>
    #> $ott_ids
    #> [1] 559026 985636 309275
    #>
    #> $phy
    #> [1] NA
    #>
    #> attr(,"class")
    #> [1] "datelifeQuery"

But when referring to the monkey, TNRS still chooses the grass:

    make_datelife_query2(input = c("Aotus", "Insulacebus", "Microcebus"))
    #> ---> Phylo-processing 'input'.
    #> * 'input' is not a phylogeny.
    #> ---> Runnning TNRS to match input names to reference taxonomy (OTT).
    #>
      |
      |                                                                      |   0%
      |
      |=======================                                               |  33%
      |
      |===============================================                       |  67%
      |
      |======================================================================| 100%
    #> $cleaned_names
    #> [1] "Aotus"       "Insulacebus" "Microcebus"
    #>
    #> $tnrs_names
    #> [1] "Aotus (genus in kingdom Archaeplastida)"
    #> [2] "Insulacebus"
    #> [3] "Microcebus"
    #>
    #> $ott_ids
    #> [1]  559026 6145234  734824
    #>
    #> $phy
    #> [1] NA
    #>
    #> attr(,"class")
    #> [1] "datelifeQuery"

To make sure that we get the taxonomic id and data for the taxon we want, we can specify a “taxonomic context”:

    rotl::tnrs_contexts()

    make_datelife_query2(input = c("Aotus", "Insulacebus", "Microcebus"), context_name = "Mammals")

### Making a query from an inclusive taxonomic group

You can run it for one taxon name only:

    make_datelife_query2(input = "Canis",
                         get_spp_from_taxon = TRUE,
                         reference_taxonomy = "ott")
    #> ---> Phylo-processing 'input'.
    #> * 'input' is not a phylogeny.
    #> ---> Runnning TNRS to match input names to reference taxonomy (OTT).
    #>
      |
      |                                                                      |   0%
      |
      |======================================================================| 100%
    #> ---> Getting species for the following taxon names :Canis.
    #> ---> Obtaining taxonomic data from lineages within genus 'Canis' with OTT id number = 372706.
    #> * Found the following taxonomic ranks: species, subspecies, no rank - terminal, no rank.
    #> * There are 21 subspecies.
    #> * There are 42 total species.
    #> * There are 36 species in OpenTree's synthetic tree.
    #> ---> Retrieving taxonomic info for 36 species names within 'Canis' that are in the OpenTree synthetic tree.
    #> $cleaned_names
    #> [1] "Canis"
    #>
    #> $tnrs_names
    #>                      3612500                      5835572
    #>                "Canis dirus"               "Canis anthus"
    #>                       113383                       752755
    #>                "Canis rufus"             "Canis simensis"
    #>                       621168                       621176
    #>               "Canis aureus"              "Canis adustus"
    #>                       247331                       346723
    #>              "Canis latrans"         "Canis himalayensis"
    #>                       346728                      4941918
    #>               "Canis indica" "Canis environmental sample"
    #>                      7655930                      7655947
    #>            "Canis ameghinoi"             "Canis nehringi"
    #>                      7655949                      7655942
    #>            "Canis palustris"                "Canis lanka"
    #>                      7655948                      7655939
    #>             "Canis pallipes"                 "Canis gezi"
    #>                      7655951                      7655935
    #>            "Canis primaevus"            "Canis chrysurus"
    #>                      7655937                      7655941
    #>          "Canis dukhunensis"               "Canis kokree"
    #>                      7655952                      7655940
    #>              "Canis sladeni"           "Canis himalaicus"
    #>                      7655934                      7655936
    #>               "Canis chanco"         "Canis curvipalatus"
    #>                      7655943                      7655931
    #>            "Canis lateralis"           "Canis argentinus"
    #>                      7655953                      7655946
    #>           "Canis tarijensis"                "Canis naria"
    #>                      7655950                      7655933
    #>             "Canis peruanus"             "Canis cautleyi"
    #>                      7655954                      6145382
    #>              "Canis ursinus"           "Canis antarticus"
    #>                      6145383                      7655938
    #>                "Canis dingo"             "Canis etruscus"
    #>                       666235                       247341
    #>            "Canis mesomelas"                "Canis lupus"
    #>
    #> $ott_ids
    #>                Canis dirus               Canis anthus
    #>                    3612500                    5835572
    #>                Canis rufus             Canis simensis
    #>                     113383                     752755
    #>               Canis aureus              Canis adustus
    #>                     621168                     621176
    #>              Canis latrans         Canis himalayensis
    #>                     247331                     346723
    #>               Canis indica Canis environmental sample
    #>                     346728                    4941918
    #>            Canis ameghinoi             Canis nehringi
    #>                    7655930                    7655947
    #>            Canis palustris                Canis lanka
    #>                    7655949                    7655942
    #>             Canis pallipes                 Canis gezi
    #>                    7655948                    7655939
    #>            Canis primaevus            Canis chrysurus
    #>                    7655951                    7655935
    #>          Canis dukhunensis               Canis kokree
    #>                    7655937                    7655941
    #>              Canis sladeni           Canis himalaicus
    #>                    7655952                    7655940
    #>               Canis chanco         Canis curvipalatus
    #>                    7655934                    7655936
    #>            Canis lateralis           Canis argentinus
    #>                    7655943                    7655931
    #>           Canis tarijensis                Canis naria
    #>                    7655953                    7655946
    #>             Canis peruanus             Canis cautleyi
    #>                    7655950                    7655933
    #>              Canis ursinus           Canis antarticus
    #>                    7655954                    6145382
    #>                Canis dingo             Canis etruscus
    #>                    6145383                    7655938
    #>            Canis mesomelas                Canis lupus
    #>                     666235                     247341
    #>
    #> $phy
    #> [1] NA
    #>
    #> attr(,"class")
    #> [1] "datelifeQuery"

Or two or more:

    make_datelife_query2(input = c("Canis", "Elephas"),
                         get_spp_from_taxon = TRUE,
                         reference_taxonomy = "ott")
    #> ---> Phylo-processing 'input'.
    #> * 'input' is not a phylogeny.
    #> ---> Runnning TNRS to match input names to reference taxonomy (OTT).
    #>
      |
      |                                                                      |   0%
      |
      |===================================                                   |  50%
      |
      |======================================================================| 100%
    #> ---> Getting species for the following taxon names :Canis, Elephas.
    #> ---> Obtaining taxonomic data from lineages within genus 'Canis' with OTT id number = 372706.
    #> * Found the following taxonomic ranks: species, subspecies, no rank - terminal, no rank.
    #> * There are 21 subspecies.
    #> * There are 42 total species.
    #> * There are 36 species in OpenTree's synthetic tree.
    #> ---> Retrieving taxonomic info for 36 species names within 'Canis' that are in the OpenTree synthetic tree.
    #> ---> Obtaining taxonomic data from lineages within genus 'Elephas' with OTT id number = 541927.
    #> * Found the following taxonomic ranks: subspecies, no rank, no rank - terminal, species.
    #> * There are 5 subspecies.
    #> * There are 8 total species.
    #> * There are 7 species in OpenTree's synthetic tree.
    #> ---> Retrieving taxonomic info for 7 species names within 'Elephas' that are in the OpenTree synthetic tree.
    #> $cleaned_names
    #> [1] "Canis"   "Elephas"
    #>
    #> $tnrs_names
    #>                      3612500                      5835572
    #>                "Canis dirus"               "Canis anthus"
    #>                       113383                       752755
    #>                "Canis rufus"             "Canis simensis"
    #>                       621168                       621176
    #>               "Canis aureus"              "Canis adustus"
    #>                       247331                       346723
    #>              "Canis latrans"         "Canis himalayensis"
    #>                       346728                      4941918
    #>               "Canis indica" "Canis environmental sample"
    #>                      7655930                      7655947
    #>            "Canis ameghinoi"             "Canis nehringi"
    #>                      7655949                      7655942
    #>            "Canis palustris"                "Canis lanka"
    #>                      7655948                      7655939
    #>             "Canis pallipes"                 "Canis gezi"
    #>                      7655951                      7655935
    #>            "Canis primaevus"            "Canis chrysurus"
    #>                      7655937                      7655941
    #>          "Canis dukhunensis"               "Canis kokree"
    #>                      7655952                      7655940
    #>              "Canis sladeni"           "Canis himalaicus"
    #>                      7655934                      7655936
    #>               "Canis chanco"         "Canis curvipalatus"
    #>                      7655943                      7655931
    #>            "Canis lateralis"           "Canis argentinus"
    #>                      7655953                      7655946
    #>           "Canis tarijensis"                "Canis naria"
    #>                      7655950                      7655933
    #>             "Canis peruanus"             "Canis cautleyi"
    #>                      7655954                      6145382
    #>              "Canis ursinus"           "Canis antarticus"
    #>                      6145383                      7655938
    #>                "Canis dingo"             "Canis etruscus"
    #>                       666235                       247341
    #>            "Canis mesomelas"                "Canis lupus"
    #>                      7654243                      7654244
    #>         "Elephas armeniacus"          "Elephas namadicus"
    #>                      7654245                      3607197
    #>               "Elephas zulu"         "Elephas bombifrons"
    #>                      6144032                      7654246
    #>         "Elephas celebensis"    "Palaeoloxodon lomolinoi"
    #>                       541928
    #>            "Elephas maximus"
    #>
    #> $ott_ids
    #>                Canis dirus               Canis anthus
    #>                    3612500                    5835572
    #>                Canis rufus             Canis simensis
    #>                     113383                     752755
    #>               Canis aureus              Canis adustus
    #>                     621168                     621176
    #>              Canis latrans         Canis himalayensis
    #>                     247331                     346723
    #>               Canis indica Canis environmental sample
    #>                     346728                    4941918
    #>            Canis ameghinoi             Canis nehringi
    #>                    7655930                    7655947
    #>            Canis palustris                Canis lanka
    #>                    7655949                    7655942
    #>             Canis pallipes                 Canis gezi
    #>                    7655948                    7655939
    #>            Canis primaevus            Canis chrysurus
    #>                    7655951                    7655935
    #>          Canis dukhunensis               Canis kokree
    #>                    7655937                    7655941
    #>              Canis sladeni           Canis himalaicus
    #>                    7655952                    7655940
    #>               Canis chanco         Canis curvipalatus
    #>                    7655934                    7655936
    #>            Canis lateralis           Canis argentinus
    #>                    7655943                    7655931
    #>           Canis tarijensis                Canis naria
    #>                    7655953                    7655946
    #>             Canis peruanus             Canis cautleyi
    #>                    7655950                    7655933
    #>              Canis ursinus           Canis antarticus
    #>                    7655954                    6145382
    #>                Canis dingo             Canis etruscus
    #>                    6145383                    7655938
    #>            Canis mesomelas                Canis lupus
    #>                     666235                     247341
    #>         Elephas armeniacus          Elephas namadicus
    #>                    7654243                    7654244
    #>               Elephas zulu         Elephas bombifrons
    #>                    7654245                    3607197
    #>         Elephas celebensis    Palaeoloxodon lomolinoi
    #>                    6144032                    7654246
    #>            Elephas maximus
    #>                     541928
    #>
    #> $phy
    #> [1] NA
    #>
    #> attr(,"class")
    #> [1] "datelifeQuery"

Sometimes, only some input taxon names are inclusive:

    make_datelife_query2(input = c("Mus", "Mus musculus"),
                         get_spp_from_taxon = c(TRUE, FALSE),
                         reference_taxonomy = "ott")
    #> ---> Phylo-processing 'input'.
    #> * 'input' is not a phylogeny.
    #> ---> Runnning TNRS to match input names to reference taxonomy (OTT).
    #>
      |
      |                                                                      |   0%
      |
      |===================================                                   |  50%
      |
      |======================================================================| 100%
    #> ---> Getting species for the following taxon names :Mus.
    #> ---> Obtaining taxonomic data from lineages within genus 'Mus' with OTT id number = 1068778.
    #> * Found the following taxonomic ranks: species, subspecies, no rank - terminal, no rank.
    #> * There are 20 subspecies.
    #> * There are 84 total species.
    #> * There are 60 species in OpenTree's synthetic tree.
    #> ---> Retrieving taxonomic info for 60 species names within 'Mus' that are in the OpenTree synthetic tree.
    #> ---> Adding species data from inclusive taxon names.
    #> $cleaned_names
    #> [1] "Mus musculus" "Mus"
    #>
    #> $tnrs_names
    #>
    #>                            "Mus musculus"
    #>                                   7067432
    #>                     "Mus cf. callewaerti"
    #>                                   5857433
    #>                  "Mus cf. setulosus West"
    #>                                   5857432
    #>                "Mus cf. tenellus TA-2014"
    #>                                   5857436
    #>                    "Mus cf. baoulei West"
    #>                                   5857434
    #>             "Mus cf. callewaerti TA-2014"
    #>                                   3608901
    #>                              "Mus neavei"
    #>                                    844274
    #>                             "Mus sorella"
    #>                                    844277
    #>                            "Mus tenellus"
    #>                                    844280
    #>                     "Mus cf. musculoides"
    #>                                    844282
    #>                                "Mus bufo"
    #>                                   3608883
    #>                         "Mus callewaerti"
    #>                                   5857435
    #>                             "Mus mahomet"
    #>                                   7067433
    #> "Mus sp. musculoides-minutoides DPL-2017"
    #>                                    369735
    #>                             "Mus baoulei"
    #>                                    403204
    #>                               "Mus emesi"
    #>                                    996648
    #>                         "Mus musculoides"
    #>                                   1000695
    #>                             "Mus indutus"
    #>                                    759679
    #>                            "Mus mattheyi"
    #>                                    845966
    #>                          "Mus minutoides"
    #>                                    845980
    #>                           "Mus setulosus"
    #>                                   1000702
    #>                              "Mus haussa"
    #>                                   1000700
    #>                        "Mus cf. saxicola"
    #>                                    887682
    #>                         "Mus shortridgei"
    #>                                    542525
    #>                            "Mus saxicola"
    #>                                    845970
    #>                          "Mus platythrix"
    #>                                    348560
    #>                          "Mus terricolor"
    #>                                    451263
    #>                             "Mus booduga"
    #>                                    289304
    #>                              "Mus triton"
    #>                                    542521
    #>                             "Mus spretus"
    #>                                    542528
    #>                              "Mus cookii"
    #>                                    845976
    #>                          "Mus spicilegus"
    #>                                   1027340
    #>                             "Mus famulus"
    #>                                    922493
    #>                              "Mus caroli"
    #>                                   1010350
    #>                        "Mus fragilicauda"
    #>                                    185328
    #>                       "Mus crociduroides"
    #>                                    542493
    #>                              "Mus pahari"
    #>                                   6144910
    #>                       "Mus terraereginae"
    #>                                   7654766
    #>                             "Mus aegaeus"
    #>                                   7654768
    #>                              "Mus camini"
    #>                                   7654773
    #>                             "Mus paulina"
    #>                                   7654776
    #>                            "Mus vulpinus"
    #>                                   7654767
    #>                          "Mus arboricola"
    #>                                   7654772
    #>                             "Mus nigrita"
    #>                                   7654775
    #>                          "Mus tomentosus"
    #>                                   7654774
    #>                          "Mus proconodon"
    #>                                   7654771
    #>                      "Mus microdontoides"
    #>                                   7654770
    #>                           "Mus leptosoma"
    #>                                   3608899
    #>                           "Mus oubanguii"
    #>                                   3608881
    #>                             "Mus goundae"
    #>                                   3608904
    #>                            "Mus orangiae"
    #>                                   3608880
    #>                           "Mus phillipsi"
    #>                                   3608890
    #>                             "Mus setzeri"
    #>                                   3608886
    #>                          "Mus fernandoni"
    #>                                   3608885
    #>                             "Mus vulcani"
    #>                                   3608874
    #>                              "Mus mayori"
    #>                                   7654769
    #>                            "Mus colletti"
    #>                                   6144906
    #>                             "Mus canguru"
    #>                                    542509
    #>                            "Mus musculus"
    #>                                    542519
    #>                          "Mus cervicolor"
    #>                                    845973
    #>                         "Mus macedonicus"
    #>
    #> $ott_ids
    #>                                                             Mus cf. callewaerti
    #>                                  542509                                 7067432
    #>                  Mus cf. setulosus West                Mus cf. tenellus TA-2014
    #>                                 5857433                                 5857432
    #>                    Mus cf. baoulei West             Mus cf. callewaerti TA-2014
    #>                                 5857436                                 5857434
    #>                              Mus neavei                             Mus sorella
    #>                                 3608901                                  844274
    #>                            Mus tenellus                     Mus cf. musculoides
    #>                                  844277                                  844280
    #>                                Mus bufo                         Mus callewaerti
    #>                                  844282                                 3608883
    #>                             Mus mahomet Mus sp. musculoides-minutoides DPL-2017
    #>                                 5857435                                 7067433
    #>                             Mus baoulei                               Mus emesi
    #>                                  369735                                  403204
    #>                         Mus musculoides                             Mus indutus
    #>                                  996648                                 1000695
    #>                            Mus mattheyi                          Mus minutoides
    #>                                  759679                                  845966
    #>                           Mus setulosus                              Mus haussa
    #>                                  845980                                 1000702
    #>                        Mus cf. saxicola                         Mus shortridgei
    #>                                 1000700                                  887682
    #>                            Mus saxicola                          Mus platythrix
    #>                                  542525                                  845970
    #>                          Mus terricolor                             Mus booduga
    #>                                  348560                                  451263
    #>                              Mus triton                             Mus spretus
    #>                                  289304                                  542521
    #>                              Mus cookii                          Mus spicilegus
    #>                                  542528                                  845976
    #>                             Mus famulus                              Mus caroli
    #>                                 1027340                                  922493
    #>                        Mus fragilicauda                       Mus crociduroides
    #>                                 1010350                                  185328
    #>                              Mus pahari                       Mus terraereginae
    #>                                  542493                                 6144910
    #>                             Mus aegaeus                              Mus camini
    #>                                 7654766                                 7654768
    #>                             Mus paulina                            Mus vulpinus
    #>                                 7654773                                 7654776
    #>                          Mus arboricola                             Mus nigrita
    #>                                 7654767                                 7654772
    #>                          Mus tomentosus                          Mus proconodon
    #>                                 7654775                                 7654774
    #>                      Mus microdontoides                           Mus leptosoma
    #>                                 7654771                                 7654770
    #>                           Mus oubanguii                             Mus goundae
    #>                                 3608899                                 3608881
    #>                            Mus orangiae                           Mus phillipsi
    #>                                 3608904                                 3608880
    #>                             Mus setzeri                          Mus fernandoni
    #>                                 3608890                                 3608886
    #>                             Mus vulcani                              Mus mayori
    #>                                 3608885                                 3608874
    #>                            Mus colletti                             Mus canguru
    #>                                 7654769                                 6144906
    #>                            Mus musculus                          Mus cervicolor
    #>                                  542509                                  542519
    #>                         Mus macedonicus
    #>                                  845973
    #>
    #> $phy
    #> [1] NA
    #>
    #> attr(,"class")
    #> [1] "datelifeQuery"

### The function `get_opentree_species()`

The function `get_opentree_species()` works under the hood to extract species names within a given taxonomic group.

This is how it fails:

    get_opentree_species()
    #> * Both 'taxon_name' and 'ott_id' arguments are missing.
    #> Please provide at least one - returning NA.
    #> [1] NA

    get_opentree_species(taxon_name = c("Canis", "Elephas"))
    #> This function can only process one taxon name at a time.
    #> Please provide just one taxon name - returning NA.
    #> [1] NA

    get_opentree_species(ott_id = c(372706, 541927))
    #> This function can only process one OTT id at a time.
    #> Please provide just one OTT id number - returning NA.
    #> [1] NA

    # TOFIX:
    # datelife::get_opentree_species(taxon_name = "Canis", ott_id = 541927)

By default, it only return species that are in OpenTree’s synthetic tree:

    get_opentree_species(taxon_name = "Canis")
    #> ---> Obtaining taxonomic info for all children within OTT taxon, genus 'Canis' (input name = Canis), with OTT id number = 372706.
    #> * Found the following taxonomic ranks: species, subspecies, no rank - terminal, no rank.
    #> * There are 21 subspecies.
    #> * There are 42 total species.
    #> * There are 36 species in OpenTree's synthetic tree.
    #> ---> Retrieving taxonomic info for 36 species names within 'Canis' that are in the OpenTree synthetic tree.
    #> $tnrs_names
    #>                      3612500                      5835572
    #>                "Canis dirus"               "Canis anthus"
    #>                       113383                       752755
    #>                "Canis rufus"             "Canis simensis"
    #>                       621168                       621176
    #>               "Canis aureus"              "Canis adustus"
    #>                       247331                       346723
    #>              "Canis latrans"         "Canis himalayensis"
    #>                       346728                      4941918
    #>               "Canis indica" "Canis environmental sample"
    #>                      7655930                      7655947
    #>            "Canis ameghinoi"             "Canis nehringi"
    #>                      7655949                      7655942
    #>            "Canis palustris"                "Canis lanka"
    #>                      7655948                      7655939
    #>             "Canis pallipes"                 "Canis gezi"
    #>                      7655951                      7655935
    #>            "Canis primaevus"            "Canis chrysurus"
    #>                      7655937                      7655941
    #>          "Canis dukhunensis"               "Canis kokree"
    #>                      7655952                      7655940
    #>              "Canis sladeni"           "Canis himalaicus"
    #>                      7655934                      7655936
    #>               "Canis chanco"         "Canis curvipalatus"
    #>                      7655943                      7655931
    #>            "Canis lateralis"           "Canis argentinus"
    #>                      7655953                      7655946
    #>           "Canis tarijensis"                "Canis naria"
    #>                      7655950                      7655933
    #>             "Canis peruanus"             "Canis cautleyi"
    #>                      7655954                      6145382
    #>              "Canis ursinus"           "Canis antarticus"
    #>                      6145383                      7655938
    #>                "Canis dingo"             "Canis etruscus"
    #>                       666235                       247341
    #>            "Canis mesomelas"                "Canis lupus"
    #>
    #> $ott_ids
    #>                Canis dirus               Canis anthus
    #>                    3612500                    5835572
    #>                Canis rufus             Canis simensis
    #>                     113383                     752755
    #>               Canis aureus              Canis adustus
    #>                     621168                     621176
    #>              Canis latrans         Canis himalayensis
    #>                     247331                     346723
    #>               Canis indica Canis environmental sample
    #>                     346728                    4941918
    #>            Canis ameghinoi             Canis nehringi
    #>                    7655930                    7655947
    #>            Canis palustris                Canis lanka
    #>                    7655949                    7655942
    #>             Canis pallipes                 Canis gezi
    #>                    7655948                    7655939
    #>            Canis primaevus            Canis chrysurus
    #>                    7655951                    7655935
    #>          Canis dukhunensis               Canis kokree
    #>                    7655937                    7655941
    #>              Canis sladeni           Canis himalaicus
    #>                    7655952                    7655940
    #>               Canis chanco         Canis curvipalatus
    #>                    7655934                    7655936
    #>            Canis lateralis           Canis argentinus
    #>                    7655943                    7655931
    #>           Canis tarijensis                Canis naria
    #>                    7655953                    7655946
    #>             Canis peruanus             Canis cautleyi
    #>                    7655950                    7655933
    #>              Canis ursinus           Canis antarticus
    #>                    7655954                    6145382
    #>                Canis dingo             Canis etruscus
    #>                    6145383                    7655938
    #>            Canis mesomelas                Canis lupus
    #>                     666235                     247341

You can override that behaviour and get all species by setting `synth_tree_only = FALSE`:

    get_opentree_species(taxon_name = "Canis", synth_tree_only = FALSE)
    #> ---> Obtaining taxonomic info for all children within OTT taxon, genus 'Canis' (input name = Canis), with OTT id number = 372706.
    #> * Found the following taxonomic ranks: species, subspecies, no rank - terminal, no rank.
    #> * There are 21 subspecies.
    #> * There are 42 total species.
    #> * There are 36 species in OpenTree's synthetic tree.
    #> ---> Returning taxonomic info for 42 species names within genus 'Canis'.
    #> $tnrs_names
    #>                      3612500                      5835572
    #>                "Canis dirus"               "Canis anthus"
    #>                       113383                       752755
    #>                "Canis rufus"             "Canis simensis"
    #>                       621168                       621176
    #>               "Canis aureus"              "Canis adustus"
    #>                       247331                       346723
    #>              "Canis latrans"         "Canis himalayensis"
    #>                       346728                      5925604
    #>               "Canis indica"         "Canis sp. KEB-2016"
    #>                       470950                      5338950
    #>          "Canis sp. CANInt1"    "Canis sp. Russia/33,500"
    #>                       247325                      5338951
    #>                  "Canis sp."   "Canis sp. Belgium/36,000"
    #>                      4941918                      7655930
    #> "Canis environmental sample"            "Canis ameghinoi"
    #>                      7655947                      7655949
    #>             "Canis nehringi"            "Canis palustris"
    #>                      7655942                      7655948
    #>                "Canis lanka"             "Canis pallipes"
    #>                      7655939                      7655951
    #>                 "Canis gezi"            "Canis primaevus"
    #>                      7655935                      7655937
    #>            "Canis chrysurus"          "Canis dukhunensis"
    #>                      7655941                      7655952
    #>               "Canis kokree"              "Canis sladeni"
    #>                      7655940                      7655934
    #>           "Canis himalaicus"               "Canis chanco"
    #>                      7655936                      7655943
    #>         "Canis curvipalatus"            "Canis lateralis"
    #>                      7655931                      7655953
    #>           "Canis argentinus"           "Canis tarijensis"
    #>                      7655946                      7655950
    #>                "Canis naria"             "Canis peruanus"
    #>                      7655933                      7655954
    #>             "Canis cautleyi"              "Canis ursinus"
    #>                      6145382                      6145383
    #>           "Canis antarticus"                "Canis dingo"
    #>                      7655938                      3612504
    #>             "Canis etruscus"             "Canis spelaeus"
    #>                       666235                       247341
    #>            "Canis mesomelas"                "Canis lupus"
    #>
    #> $ott_ids
    #>                Canis dirus               Canis anthus
    #>                    3612500                    5835572
    #>                Canis rufus             Canis simensis
    #>                     113383                     752755
    #>               Canis aureus              Canis adustus
    #>                     621168                     621176
    #>              Canis latrans         Canis himalayensis
    #>                     247331                     346723
    #>               Canis indica         Canis sp. KEB-2016
    #>                     346728                    5925604
    #>          Canis sp. CANInt1    Canis sp. Russia/33,500
    #>                     470950                    5338950
    #>                  Canis sp.   Canis sp. Belgium/36,000
    #>                     247325                    5338951
    #> Canis environmental sample            Canis ameghinoi
    #>                    4941918                    7655930
    #>             Canis nehringi            Canis palustris
    #>                    7655947                    7655949
    #>                Canis lanka             Canis pallipes
    #>                    7655942                    7655948
    #>                 Canis gezi            Canis primaevus
    #>                    7655939                    7655951
    #>            Canis chrysurus          Canis dukhunensis
    #>                    7655935                    7655937
    #>               Canis kokree              Canis sladeni
    #>                    7655941                    7655952
    #>           Canis himalaicus               Canis chanco
    #>                    7655940                    7655934
    #>         Canis curvipalatus            Canis lateralis
    #>                    7655936                    7655943
    #>           Canis argentinus           Canis tarijensis
    #>                    7655931                    7655953
    #>                Canis naria             Canis peruanus
    #>                    7655946                    7655950
    #>             Canis cautleyi              Canis ursinus
    #>                    7655933                    7655954
    #>           Canis antarticus                Canis dingo
    #>                    6145382                    6145383
    #>             Canis etruscus             Canis spelaeus
    #>                    7655938                    3612504
    #>            Canis mesomelas                Canis lupus
    #>                     666235                     247341

If you know the OTT id of your group, you can use it:

    get_opentree_species(ott_id = 541927)
    #> ---> Obtaining taxonomic data from lineages within genus 'Elephas' with OTT id number = 541927.
    #> * Found the following taxonomic ranks: subspecies, no rank, no rank - terminal, species.
    #> * There are 5 subspecies.
    #> * There are 8 total species.
    #> * There are 7 species in OpenTree's synthetic tree.
    #> ---> Retrieving taxonomic info for 7 species names within 'Elephas' that are in the OpenTree synthetic tree.
    #> $tnrs_names
    #>                   7654243                   7654244                   7654245
    #>      "Elephas armeniacus"       "Elephas namadicus"            "Elephas zulu"
    #>                   3607197                   6144032                   7654246
    #>      "Elephas bombifrons"      "Elephas celebensis" "Palaeoloxodon lomolinoi"
    #>                    541928
    #>         "Elephas maximus"
    #>
    #> $ott_ids
    #>      Elephas armeniacus       Elephas namadicus            Elephas zulu
    #>                 7654243                 7654244                 7654245
    #>      Elephas bombifrons      Elephas celebensis Palaeoloxodon lomolinoi
    #>                 3607197                 6144032                 7654246
    #>         Elephas maximus
    #>                  541928

    get_opentree_species(ott_id = 541927, synth_tree_only = FALSE)
    #> ---> Obtaining taxonomic data from lineages within genus 'Elephas' with OTT id number = 541927.
    #> * Found the following taxonomic ranks: subspecies, no rank, no rank - terminal, species.
    #> * There are 5 subspecies.
    #> * There are 8 total species.
    #> * There are 7 species in OpenTree's synthetic tree.
    #> ---> Returning taxonomic info for 8 species names within genus 'Elephas'.
    #> $tnrs_names
    #>                   7654243                   7654244                   7654245
    #>      "Elephas armeniacus"       "Elephas namadicus"            "Elephas zulu"
    #>                   3607197                   6144032                   7654246
    #>      "Elephas bombifrons"      "Elephas celebensis" "Palaeoloxodon lomolinoi"
    #>                   3607200                    541928
    #>      "Elephas planifrons"         "Elephas maximus"
    #>
    #> $ott_ids
    #>      Elephas armeniacus       Elephas namadicus            Elephas zulu
    #>                 7654243                 7654244                 7654245
    #>      Elephas bombifrons      Elephas celebensis Palaeoloxodon lomolinoi
    #>                 3607197                 6144032                 7654246
    #>      Elephas planifrons         Elephas maximus
    #>                 3607200                  541928

To get species for multiple (more than one) taxon names:

    ott_ids <- c(541927, 100)

    # TODO: make a function out of the following code
    # then it can replace code inside datelife_query_get_spp, section # getting species
    species_list <- lapply(ott_ids,
                           function(x) {
                             datelife::get_opentree_species(ott_id = x,
                                                  synth_tree_only = TRUE)
                            })
    #> ---> Obtaining taxonomic data from lineages within genus 'Elephas' with OTT id number = 541927.
    #> * Found the following taxonomic ranks: subspecies, no rank, no rank - terminal, species.
    #> * There are 5 subspecies.
    #> * There are 8 total species.
    #> * There are 7 species in OpenTree's synthetic tree.
    #> ---> Retrieving taxonomic info for 7 species names within 'Elephas' that are in the OpenTree synthetic tree.
    #> ---> Obtaining taxonomic data from lineages within species 'Schidax sp. 'squamaria'' with OTT id number = 100.
    #> * Found the following taxonomic ranks: species.
    #> * There are 0 subspecies.
    #> * There are 1 total species.
    #> * There are 1 species in OpenTree's synthetic tree.
    #> ---> Retrieving taxonomic info for 1 species names within 'Schidax sp. 'squamaria'' that are in the OpenTree synthetic tree.
    return_names <- unlist(sapply(species_list, "[", "tnrs_names"))
    return_ott_ids <- unlist(sapply(species_list, "[", "ott_ids"))
    names(return_names) <- return_ott_ids
    names(return_ott_ids) <- return_names

    list(tnrs_names = return_names,
         ott_ids = return_ott_ids)
    #> $tnrs_names
    #>                   7654243                   7654244                   7654245
    #>      "Elephas armeniacus"       "Elephas namadicus"            "Elephas zulu"
    #>                   3607197                   6144032                   7654246
    #>      "Elephas bombifrons"      "Elephas celebensis" "Palaeoloxodon lomolinoi"
    #>                    541928                       100
    #>         "Elephas maximus" "Schidax sp. 'squamaria'"
    #>
    #> $ott_ids
    #>      Elephas armeniacus       Elephas namadicus            Elephas zulu
    #>                 7654243                 7654244                 7654245
    #>      Elephas bombifrons      Elephas celebensis Palaeoloxodon lomolinoi
    #>                 3607197                 6144032                 7654246
    #>         Elephas maximus Schidax sp. 'squamaria'
    #>                  541928                     100