| makePBDBtaxonTree {paleotree} | R Documentation |
Creating a Taxon-Tree from Taxonomic Data Downloaded from the Paleobiology Database
Description
The function makePBDBtaxonTree creates phylogeny-like
object of class phylo from the taxonomic information
recorded in a taxonomy download from the PBDB for
a given group. Two different algorithms are provided,
the default being based on parent-child taxon relationships,
the other based on the nested Linnean hierarchy. The function
plotTaxaTreePBDB is also provided as a minor helper
function for optimally plotting the labeled topologies that are
output by makePBDBtaxonTree.
Usage
makePBDBtaxonTree(
taxaDataPBDB,
rankTaxon,
method = "parentChild",
tipSet = NULL,
cleanTree = TRUE,
annotatedDuplicateNames = TRUE,
APIversion = "1.2",
failIfNoInternet = TRUE
)
plotTaxaTreePBDB(taxaTree, edgeLength = 1)
Arguments
taxaDataPBDB |
A table of taxonomic data collected from
the Paleobiology Database, using the taxa list option
with |
rankTaxon |
The selected taxon rank; must be one of |
method |
Controls which algorithm is used for calculating
the taxon-tree. The default option is |
tipSet |
This argument only impacts analyses where
|
cleanTree |
When |
annotatedDuplicateNames |
A logical determining whether duplicate taxon names,
when found in the Paleobiology Database for taxa (presumably reflecting an issue with
taxa being obsolete but with incomplete seniority data), should be annotated to include
sequential numbers so to modify them, via function |
APIversion |
Version of the Paleobiology Database API used by
|
failIfNoInternet |
If the Paleobiology Database or another
needed internet resource cannot be accessed, perhaps because of
no internet connection, should the function fail (with an error)
or should the function return |
taxaTree |
A phylogeny of class |
edgeLength |
The edge length that the plotted tree should be plotted
with ( |
Details
This function should not be taken too seriously. Many groups in the Paleobiology Database have out-of-date or very incomplete taxonomic information. This function is meant to help visualize what information is present, and by use of time-scaling functions, allow us to visualize the intersection of temporal and phylogenetic, mainly to look for incongruence due to either incorrect taxonomic placements, erroneous occurrence data or both.
Note however that, contrary to common opinion among some paleontologists, taxon-trees may be just as useful for macroevolutionary studies as reconstructed phylogenies (Soul and Friedman, 2015).
Value
A phylogeny of class phylo, where each tip is a taxon of the given rankTaxon. See additional details
regarding branch lengths can be found in the sub-algorithms used to create the taxon-tree by this function:
parentChild2taxonTree and taxonTable2taxonTree.
Depending on the method
used, either the element $parentChild or $taxonTable is added to the list structure of
the output phylogeny object, which was used as input for one of the two algorithms mentioned above.
Please note that when applied to output from the taxa option of the API version 1.1, the taxon names returned are the original taxon names as 'accepted_name' is not available in API v1.1, while under API v1.2, the returned taxon names should be the most up-to-date formal names for those taxa. Similar issues also effect the identification of parent taxa, as the accepted name of the parent ID number is only provided in version 1.2 of the API.
Author(s)
David W. Bapst
References
Peters, S. E., and M. McClennen. 2015. The Paleobiology Database application programming interface. Paleobiology 42(1):1-7.
Soul, L. C., and M. Friedman. 2015. Taxonomy and Phylogeny Can Yield Comparable Results in Comparative Palaeontological Analyses. Systematic Biology (doi:10.1093/sysbio/syv015)
See Also
Two other functions in paleotree are used as sub-algorithms by makePBDBtaxonTree
to create the taxon-tree within this function,
and users should consult their manual pages for additional details:
parentChild2taxonTree and taxonTable2taxonTree
Closely related functions for
Other functions for manipulating PBDB data can be found at taxonSortPBDBocc,
occData2timeList, and the example data at graptPBDB.
Examples
# Note that most examples here use argument
# failIfNoInternet = FALSE so that functions do
# not error out but simply return NULL if internet
# connection is not available, and thus
# fail gracefully rather than error out (required by CRAN).
# Remove this argument or set to TRUE so functions DO fail
# when internet resources (paleobiodb) is not available.
set.seed(1)
#get some example occurrence and taxonomic data
data(graptPBDB)
#get the taxon tree: Linnean method
graptTreeLinnean <- makePBDBtaxonTree(
taxaDataPBDB = graptTaxaPBDB,
rankTaxon = "genus",
method = "Linnean",
failIfNoInternet = FALSE)
#get the taxon tree: parentChild method
graptTreeParentChild <- makePBDBtaxonTree(
taxaDataPBDB = graptTaxaPBDB,
rankTaxon = "genus",
method = "parentChild",
failIfNoInternet = FALSE)
if(!is.null(graptTreeParentChild) &
!is.null(graptTreeLinnean)){
# if those functions worked...
# let's plot these and compare them!
plotTaxaTreePBDB(graptTreeParentChild)
plotTaxaTreePBDB(graptTreeLinnean)
}
# pause 3 seconds so we don't spam the API
Sys.sleep(3)
####################################################
# let's try some other groups
###################################
#conodonts
conoData <- getCladeTaxaPBDB("Conodonta",
failIfNoInternet = FALSE)
if(!is.null(conoData)){
conoTree <- makePBDBtaxonTree(
taxaDataPBDB = conoData,
rankTaxon = "genus",
method = "parentChild")
# if it worked, plot it!
plotTaxaTreePBDB(conoTree)
}
# pause 3 seconds so we don't spam the API
Sys.sleep(3)
#############################
#asaphid trilobites
asaData <- getCladeTaxaPBDB("Asaphida",
failIfNoInternet = FALSE)
if(!is.null(asaData)){
asaTree <- makePBDBtaxonTree(
taxaDataPBDB = asaData,
rankTaxon = "genus",
method = "parentChild")
# if it worked, plot it!
plotTaxaTreePBDB(asaTree)
}
# pause 3 seconds so we don't spam the API
Sys.sleep(3)
###############################
#Ornithischia
ornithData <- getCladeTaxaPBDB("Ornithischia",
failIfNoInternet = FALSE)
if(!is.null(ornithData)){
ornithTree <- makePBDBtaxonTree(
taxaDataPBDB = ornithData,
rankTaxon = "genus",
method = "parentChild")
# if it worked, plot it!
plotTaxaTreePBDB(ornithTree)
# pause 3 seconds so we don't spam the API
Sys.sleep(3)
#try Linnean!
#but first... need to drop repeated taxon first: Hylaeosaurus
# actually this taxon seems to have been repaired
# as of September 2019 !
# findHylaeo <- ornithData$taxon_name == "Hylaeosaurus"
# there's actually only one accepted ID number
# HylaeoIDnum <- unique(ornithData[findHylaeo,"taxon_no"])
# HylaeoIDnum
# so, take which one has occurrences listed
# dropThis <- which((ornithData$n_occs < 1) & findHylaeo)
# ornithDataCleaned <- ornithData[-dropThis,]
ornithTree <- makePBDBtaxonTree(
ornithData,
rankTaxon = "genus",
method = "Linnean",
failIfNoInternet = FALSE)
# if it worked, plot it!
plotTaxaTreePBDB(ornithTree)
}
# pause 3 seconds so we don't spam the API
Sys.sleep(3)
#########################
# Rhynchonellida
rhynchData <- getCladeTaxaPBDB("Rhynchonellida",
failIfNoInternet = FALSE)
if(!is.null(rhynchData)){
rhynchTree <- makePBDBtaxonTree(
taxaDataPBDB = rhynchData,
rankTaxon = "genus",
method = "parentChild")
# if it worked, plot it!
plotTaxaTreePBDB(rhynchTree)
}
#some of these look pretty messy!