Title: | A Global Dataset of Anthropogenic Extinct Birds and their Traits: Phylogeny Builder |
---|---|
Description: | Grafts the extinct bird species from the 'Avotrex' database (Sayol et al., in review) on to the 'BirdTree' phylogenies <https://birdtree.org>, using a set of different commands. |
Authors: | Joseph Wayman [aut, cre] |
Maintainer: | Joseph Wayman <[email protected]> |
License: | GPL-3 |
Version: | 1.3.1 |
Built: | 2025-02-25 03:15:55 UTC |
Source: | https://github.com/joe-wayman/avotrex |
Binds an extinct species at either (1) a randomly selected point along a branch, after truncating either end, (2) a specific fraction along a branch, or (3) a specific time point along a branch.
AvoBind(tree, node, per, per_fixed = FALSE, sp_name, time_graft = FALSE, terminal = FALSE, mindist = 0.1)
AvoBind(tree, node, per, per_fixed = FALSE, sp_name, time_graft = FALSE, terminal = FALSE, mindist = 0.1)
tree |
Tree object (i.e., phylogeny) |
node |
Target node |
per |
The fraction (0 to a max value of 0.5) of total
branch length to truncate at either end of the branch for
grafting (e.g. 0.2 cuts of 20% of the total branch
length from either end) if |
per_fixed |
Logical argument: whether to graft a species on at an exact
point (as a fraction) along a branch (TRUE), which is chosen using the
|
sp_name |
Name of the grafted species. |
time_graft |
Should the grafting occur at a particular time point (in
millions of years if BirdTree trees provided) along a given branch, using
|
terminal |
Logical value: if |
mindist |
If |
Returns a tree of class "phylo", with the extinct species grafted on.
Joe Wayman, Tom Matthews and Pedro Cardoso (AgeBind)
Grafting extinct species onto BirdTree phylogenies using the AvoTrex database
AvoPhylo(ctrees, avotrex, tax, PER = 0.2, PER_FIXED = 0.75, mindist = 0.1, ord = FALSE, Ntree, n.cores = 1, cluster.ips = NULL)
AvoPhylo(ctrees, avotrex, tax, PER = 0.2, PER_FIXED = 0.75, mindist = 0.1, ord = FALSE, Ntree, n.cores = 1, cluster.ips = NULL)
ctrees |
Either (i) object (of class multiPhylo) containing multiple
BirdTree phylogenies. Individual trees within the multiPhylo object must be
of class 'phylo', see the |
avotrex |
The AvoTrex extinct species phylogeny database. This database contains the information and commands required to graft the extinct species on to the BirdTree trees. If edited, column names must remain unchanged. |
tax |
The Jetz et al. (2012) BirdTree taxonomy .csv. Supplied as data within the package. |
PER |
Percentage/fraction for branch truncation based on random grafting
(see |
PER_FIXED |
Point along a branch (expressed as a fraction
of the branch length, rootward) to graft the species in the
phylogeny database ( |
mindist |
When fixing the grafting of a given species at
a specific time point, but the provided grafting time point
is too old (i.e., older than the parent node) or too young
(i.e., younger than the child node) relative to the focal
branch, grafting will occur |
ord |
Should the trees within |
Ntree |
The number of trees to sample from the supplied
number of BirdTree trees (i.e., |
n.cores |
Number of cores used to build the phylogeny. Default is one (will run with parallel processing) |
cluster.ips |
Cluster location. Keep as default. |
Function to build phylogenies incorporating the extinct species from the
AvoTrex extinct birds database (Sayol et al.). AvoTrex provides data on
geographical location, island endemicity, volancy, body size and standard
external and skeleton morphological measurements for 610 extinct bird
species. The AvoPhylo function provides a pipeline to incorporate the extinct
species from AvoTrex into the "BirdTree" phylogenies of extant birds (Jetz et
al. 2012). Utilising codes assigned to each species based on their known
taxonomic affinities, the function binds each species in turn to a provided
BirdTree phylogeny. Input phylogenies (i.e., BirdTree trees) must be of class
'phylo', see phylo
.
BirdTree phylogenies can be sourced from: https://birdtree.org/
As certain species need to be grafted onto the tree before other species, a number of the species are grafted in a set order. This ordering is controlled through the “sp_id”, “phylo_id” and “group” columns in the extinct species phylogeny database. Before grafting, the database is ordered by the “sp_id” column, with the “phylo_id” and “group” columns used to filter out particular groups of species (i.e., those classified as "xS" in the "phylo_id" column) to be grafted in different orders (i.e., either a randomised order within groups, or a fixed order within groups). See the package vignette, as well as Sayol et al. and Matthews et al., for further details.
For a subset of species (primarily those in older clades), we
have constrained the grafting to take place at a specific time
point (value in the 'time_fixed' column) along a given branch,
rather than at a randomly selected point. If, due to the
topology of the underlying BirdTree tree, it is not possible
to undertake this grafting along a given branch (i.e., the
time point for grafting is either older than the parent node
or younger than the child node, in respect to a given focal
branch), we graft the species just below the parent node or
just above the child node (using a branch length set by
mindist
- if mindist
is longer than the focal
branch in a given grafting event, it is adjusted accordingly).
As some of the grafting codes (see table below) randomly place
the given species within a group of species, a genus, or a
family, and some species groups are randomised before grafting
(see above), it is useful to run the grafting procedure over a
a number of trees to average out the randomisation. Therefore,
the function can be run in parallel using the argument
n.cores
. Note that the function will run on one core as
default and if only one tree is supplied. Trees for grafting
can be randomly selected from a number of input trees by
giving the function a group of input trees using the argument
ctrees
and then defining a smaller number using
Ntree
. If the maximum number of input trees is to be
used, Ntree
should equal length(ctrees)
. If you
want the outputted list of trees to match the order of trees
in ctrees
, set ord = TRUE
.
If Ntree
> 1, a progress bar will be displayed.
A variety of different plotting options are available, see
the plot.avophylo
documentation.
Codes | Full name | Definition |
S | Sister | Grafted as a sister to a known extant or extinct species already in the tree |
SSG | Sister species group | Grafted as a sister to a group of extant and/or extinct species already in the tree |
SGG | Sister genus group | Grafted as a sister to an entire extant or extinct genus (i.e., for the first grafted representative of an extinct genus) |
SGG2 | Sister genus group 2 | Grafted as sister to multiple genera. This was for when a species was sister to a subfamily or some other large specific clade |
SFG | Sister family group | Grafted as a sister to an entire extant or extinct family already present in the tree (i.e., for the first grafted representative of an extinct family) |
SOG | Sister order group | Grafted as a sister to an entire order already present in the tree (i.e., for the first grafted representative of an extinct order) |
RSG | Random species group | Grafted to a randomly selected species from a pre-defined group of species (i.e., from which is believed to have close affinities |
RGG | Random genus group | Grafted to a randomly selected species from a given genus. For example, if an extinct species was believed to be a finch derived from a European finch species, but the exact sister species is unknown. |
RGG2 | Random genus group 2 | Grafted to a randomly selected species from a group of genera (e.g. when all that is known is that the species is from a specific subfamily). Currently not used in the database, but the relevant functionality has been kept in the R script, as it could be useful for future studies. |
RFG | Random family group | Grafted to a randomly selected species from a given family |
RSGG | Random sister genus group | Grafted as sister to a randomly selected genus from a pre-defined group of genera |
RSGG2 | Random sister genus group 2 | Grafted as sister to a randomly selected genus from a pre-defined family |
The function returns an object of class 'multiAvophylo', which is a list consisting of N trees (each of class 'avophylo' and 'phylo') that were selected from the supplied set of input trees. These ouput trees have all had the extinct species from AvoTrex grafted on.
Matthews et al. (IN REVIEW) The global loss of avian functional and phylogenetic diversity from extinctions in the Holocene and Late Pleistocene
Sayol et al. (IN PREP) The global loss of avian functional and phylogenetic diversity from extinctions in the Holocene and Late Pleistocene
# data(BirdTree_trees) # data(BirdTree_tax) # data(AvotrexPhylo) # trees <- AvoPhylo(ctrees = BirdTree_trees, # avotrex = AvotrexPhylo, PER = 0.2, PER_FIXED = 0.75, # mindist = 0.1, ord = FALSE, # tax = BirdTree_tax, Ntree = 1, n.cores = 1, cluster.ips = NULL) # class(trees) # trees[[1]] # class(trees[[1]]) #See the plot.avophylo documentation for the different available #plotting options.
# data(BirdTree_trees) # data(BirdTree_tax) # data(AvotrexPhylo) # trees <- AvoPhylo(ctrees = BirdTree_trees, # avotrex = AvotrexPhylo, PER = 0.2, PER_FIXED = 0.75, # mindist = 0.1, ord = FALSE, # tax = BirdTree_tax, Ntree = 1, n.cores = 1, cluster.ips = NULL) # class(trees) # trees[[1]] # class(trees[[1]]) #See the plot.avophylo documentation for the different available #plotting options.
The dataset provides instructions to graft extinct bird species from Sayol et al. (IN PREP) on to existing BirdTree phylogenies using the AvoPhylo function from the Avotrex package. Instructions are provided in various columns (see format).
data("AvotrexPhylo")
data("AvotrexPhylo")
A data frame with 610 rows and the following variables:
sp_id
a character vector detailing the order in which species are joined
phylo_id
a character vector detailing the order in which species are joined and whether a species is part of a group (see details)
per_fixed
a logical vector
time_fixed
a numeric vector detailing a specific time point for grafting or NA
group
a numeric vector detailing a group code or NA (see details)
species
a character vector detailing species name with an underscore
order
a character vector detailing species order
family
a character vector detailing species family
genus
a character vector detailing species genus
jetz_order
a character vector detailing species order within the Jetz phylogeny
jetz_family
a character vector detailing species family within the Jetz phylogeny
jetz_genus
a character vector detailing species genus within the Jetz phylogeny
type
a character vector of codes. The codes determine how and where the species is grafted to the tree. See details and function "AvoPhylo"
sister_order
a character vector. Provides the order within the BirdTree backbone tree to join the extinct species to, or randomly within, depending on the code within the column "type"
sister_clade
a character vector. Provides the clade within the BirdTree backbone tree to join the extinct species to, or randomly within, depending on the code within the column "type"
sister_family
a character vector. Provides the family within the BirdTree backbone tree to join the extinct species to, or randomly within, depending on the code within the column "type"
sister_genus
a character vector. Provides the genus within the BirdTree backbone tree to join the extinct species to, or randomly within, depending on the code within the column "type"
sister_species
a character vector. Provides the species within the BirdTree backbone tree to join the extinct species to depending on the code within the column "type"
sister_species_group
a character vector. Provides the group of species within the BirdTree backbone tree to join the extinct species to, or randomly within, depending on the code within the column "type"
As certain species need to be grafted onto the tree before other species, a number of the species are grafted in a set order. This ordering is controlled through the “sp_id”, “phylo_id” and “group” columns in the extinct species phylogeny database. Before grafting, the database is ordered by the “sp_id” column, with the “phylo_id” and “group” columns used to filter out particular groups of species (i.e., those classified as "xS" in the "phylo_id" column) to be grafted in different orders (i.e., either a randomised order within groups, or a fixed order within groups). See the package vignette for further details.
Some species are grafted at specific time points along a branch (column "time_fixed").
As some of the codes within the column "type" (see table below) randomly place the given species within a group of species, a genus, or a family, and some species groups are randomised before grafting (see above), it is useful to run the grafting proceedure over a a number of trees to average out the randomisation (see function "AvoPhylo").
See the package vignette, and the help file for AvoPhylo() for more information.
Matthews et al. (IN REVIEW) The global loss of avian functional and phylogenetic diversity from extinctions in the Holocene and Late Pleistocene.
Sayol et al. (IN PREP) The global loss of avian functional and phylogenetic diversity from extinctions in the Holocene and Late Pleistocene
data(AvotrexPhylo)
data(AvotrexPhylo)
Dataset from Jetz et al. (2012) detailing the BirdTree taxonomy used in the BirdTree backbone phylogenetic trees.
data("BirdTree_tax")
data("BirdTree_tax")
A data frame with 9993 observations on the following 11 variables.
Genus
a character vector detailing the Bird Tree genus
Species
a character vector detailing the Bird Tree species name
TipLabel
a character vector detailing the tip label (genus and species name separated by an underscore)
English
a character vector detailing the common name for the species
Taxonomy
a character vector detailing the Bird Tree taxonomy
Clade
a character vector detailing the Bird Tree clade
BLFamilyLatin
a character vector detailing the Bird Tree family name (latin)
BLFamilyEnglish
a character vector detailing the Bird Tree family name (common)
FamSequID
a numeric vector
Order
a character vector detailing the Bird Tree order
OscSubOsc
a character vector
If necessary, more details than the __description__ above ~~
Jetz, W., Thomas, G., Joy, J. et al. The global diversity of birds in space and time. Nature 491, 444–448 (2012). https://doi.org/10.1038/nature11631
Jetz, W., Thomas, G., Joy, J. et al. The global diversity of birds in space and time. Nature 491, 444–448 (2012). https://doi.org/10.1038/nature11631
data(BirdTree_tax)
data(BirdTree_tax)
Two Bird Tree backbone trees obtained from Jetz et al. (2012).
data("BirdTree_trees")
data("BirdTree_trees")
A multiPhylo object consisting of two elements.
If necessary, more details than the __description__ above
Jetz, W., Thomas, G., Joy, J. et al. The global diversity of birds in space and time. Nature 491, 444–448 (2012). https://doi.org/10.1038/nature11631
Jetz, W., Thomas, G., Joy, J. et al. The global diversity of birds in space and time. Nature 491, 444–448 (2012). https://doi.org/10.1038/nature11631
data(BirdTree_trees)
data(BirdTree_trees)
S3 method for class 'avophylo'.
plot.avophylo
creates plots for objects of class
'avophylo'. The exact plot(s) constructed depends on the
argument values provided (see examples below and also the
package vignette). The function uses the ape package's
plot.phylo and can take any argument from that
function (e.g. the type
argument).
If AvoPhylo
is used to produce a list of trees
of class 'multiAvophylo', then plot.multiAvophylo
is
first called. This plots individual trees in turn (with the
user required to press 'enter' to move to the next plot).
The user will need to play around with plotting window size, and/or export the image, particularly if many tips are included.
Note - if using the lvls
argument, a warning is
provided. This comes from the tidytree::tree_subset
function and appears to be a bug (but the plot should be
checked for sense).
## S3 method for class 'avophylo' plot( x, tips = "extinct", tips_col = NULL, order = NULL, family = NULL, genus = NULL, species = NULL, avotrex, tax, lvls = NULL, ... )
## S3 method for class 'avophylo' plot( x, tips = "extinct", tips_col = NULL, order = NULL, family = NULL, genus = NULL, species = NULL, avotrex, tax, lvls = NULL, ... )
x |
An object of class 'avophylo'. |
tips |
What tip labels to present. Can be one of
"extinct" (just tip labels of extinct species), "none" (no
tip labels) or "all_same" (show all labels, with same colour
labels for all species), or "all_dif" (show all labels, with
different colour labels for extant and extinct species).
The latter needs to be used in combination with the
|
tips_col |
Colour of tip labels. If |
order |
Prune the tree to only show a specific order
(should be a character vector of length = 1). Taxonomy
follows BirdTree, see the |
family |
As for |
genus |
As for |
species |
Prune the tree to only show a specific set of
species. Should be a vector of at least length = 1. If only
a single species name is provided, the |
avotrex |
The Avotrex phylo dataset used to generate the
trees. For most use cases, this will have been loaded using
|
tax |
The Jetz et al. (2012) BirdTree taxonomy .csv. Supplied as data within the package. |
lvls |
If |
... |
Other plotting arguments from the ape package's plot.phylo can be provided. |
Generates a phylogeny plot of x
.
# Generate a set of trees # data(BirdTree_trees) # data(BirdTree_tax) # data(AvotrexPhylo) # trees <- AvoPhylo(ctrees = BirdTree_trees, # avotrex = AvotrexPhylo, PER = 0.2, PER_FIXED = 0.75, # tax = BirdTree_tax, Ntree = 2, n.cores = 2, # cluster.ips = NULL) #For here, we can load in an example set of two trees #generated using the above code data(treesEx) #order (owls) - just show extinct tip names (in red) and using #a fan plot plot(treesEx[[1]], avotrex = AvotrexPhylo, tax = BirdTree_tax, order = "Strigiformes", tips = "extinct", type = "fan", tip.color = "red", cex = 0.4) #family (plot all three trees this time) plot(treesEx, avotrex = AvotrexPhylo, tax = BirdTree_tax, family = "Threskiornithidae", tips = "extinct", tip.color = "red", cex = 0.5) #genus - cladogram plot plot(treesEx[[2]], avotrex = AvotrexPhylo, tax = BirdTree_tax, genus = "Aplonis", tips = "extinct", type = "cladogram", tip.color = "red", cex = 0.5) #species (& show all tip names in same colour) species2 <- c("Anas_itchtucknee", "Anas_sp_VitiLevu", "Anas_platyrhynchos", "Ara_tricolor") plot(treesEx[[2]], avotrex = AvotrexPhylo, tax = BirdTree_tax, species = species2, tips = "all_same", type = "cladogram", tip.color = "blue", cex = 0.5) #same as previous, but extinct and extant diff colours plot(treesEx[[2]], avotrex = AvotrexPhylo, tax = BirdTree_tax, species = species2, cex = 0.5, tips = "all_dif", tips_col = c("red", "darkgreen"), type = "cladogram") ##single species 2 levels back plot(treesEx[[2]], avotrex = AvotrexPhylo, tax = BirdTree_tax, species = "Ara_tricolor", tips = "all_dif", tips_col = c("red", "darkgreen"), lvls = 2, type = "phylogram", cex = 0.6)
# Generate a set of trees # data(BirdTree_trees) # data(BirdTree_tax) # data(AvotrexPhylo) # trees <- AvoPhylo(ctrees = BirdTree_trees, # avotrex = AvotrexPhylo, PER = 0.2, PER_FIXED = 0.75, # tax = BirdTree_tax, Ntree = 2, n.cores = 2, # cluster.ips = NULL) #For here, we can load in an example set of two trees #generated using the above code data(treesEx) #order (owls) - just show extinct tip names (in red) and using #a fan plot plot(treesEx[[1]], avotrex = AvotrexPhylo, tax = BirdTree_tax, order = "Strigiformes", tips = "extinct", type = "fan", tip.color = "red", cex = 0.4) #family (plot all three trees this time) plot(treesEx, avotrex = AvotrexPhylo, tax = BirdTree_tax, family = "Threskiornithidae", tips = "extinct", tip.color = "red", cex = 0.5) #genus - cladogram plot plot(treesEx[[2]], avotrex = AvotrexPhylo, tax = BirdTree_tax, genus = "Aplonis", tips = "extinct", type = "cladogram", tip.color = "red", cex = 0.5) #species (& show all tip names in same colour) species2 <- c("Anas_itchtucknee", "Anas_sp_VitiLevu", "Anas_platyrhynchos", "Ara_tricolor") plot(treesEx[[2]], avotrex = AvotrexPhylo, tax = BirdTree_tax, species = species2, tips = "all_same", type = "cladogram", tip.color = "blue", cex = 0.5) #same as previous, but extinct and extant diff colours plot(treesEx[[2]], avotrex = AvotrexPhylo, tax = BirdTree_tax, species = species2, cex = 0.5, tips = "all_dif", tips_col = c("red", "darkgreen"), type = "cladogram") ##single species 2 levels back plot(treesEx[[2]], avotrex = AvotrexPhylo, tax = BirdTree_tax, species = "Ara_tricolor", tips = "all_dif", tips_col = c("red", "darkgreen"), lvls = 2, type = "phylogram", cex = 0.6)
S3 method for class 'multiAvophylo'. See the
plot.avophylo
documentation for more
information.
Plots individual trees in turn (with the user required to press 'enter' to move to the next plot).
## S3 method for class 'multiAvophylo' plot( x, tips = "extinct", tips_col = NULL, order = NULL, family = NULL, genus = NULL, species = NULL, avotrex, tax, lvls = NULL, ... )
## S3 method for class 'multiAvophylo' plot( x, tips = "extinct", tips_col = NULL, order = NULL, family = NULL, genus = NULL, species = NULL, avotrex, tax, lvls = NULL, ... )
x |
An object of class 'multiAvophylo'. |
tips |
What tip labels to present. Can be one of
"extinct" (just tip labels of extinct species), "none" (no
tip labels) or "all_same" (show all labels, with same colour
labels for all species), or "all_dif" (show all labels, with
different colour labels for extant and extinct species).
The latter needs to be used in combination with the
|
tips_col |
Colour of tip labels. If |
order |
Prune the tree to only show a specific order
(should be a character vector of length = 1). Taxonomy
follows BirdTree, see the |
family |
As for |
genus |
As for |
species |
Prune the tree to only show a specific set of
species. Should be a vector of at least length = 1. If only
a single species name is provided, the |
avotrex |
The Avotrex phylo dataset used to generate the
trees. For most use cases, this will have been loaded using
|
tax |
The Jetz et al. (2012) BirdTree taxonomy .csv. Supplied as data within the package. |
lvls |
If |
... |
Other plotting arguments from the ape package's plot.phylo can be provided. |
Generates a phylogeny plot for each tree in x
.
#See the plot.avophylo documentation for further examples data(treesEx) #family (plot both trees in turn) plot(treesEx, avotrex = AvotrexPhylo, tax = BirdTree_tax, family = "Threskiornithidae", tips = "extinct", tip.color = "red", cex = 0.5)
#See the plot.avophylo documentation for further examples data(treesEx) #family (plot both trees in turn) plot(treesEx, avotrex = AvotrexPhylo, tax = BirdTree_tax, family = "Threskiornithidae", tips = "extinct", tip.color = "red", cex = 0.5)
A "multiAvophylo" object containing two AvoPhylo trees, generated using the AvoPhylo function. Includes 610 extinct species.
data(treesEx)
data(treesEx)
An object of class 'multiAvophylo'
data(treesEx)
data(treesEx)