Package 'avotrex'

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] , Thomas J. Matthews [aut] , Paul Dufour [ctb], Ferran Sayol [ctb], Pedro Cardoso [ctb]
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

Help Index


AvoBind - Bind extinct species to the tree

Description

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.

Usage

AvoBind(tree, node, per, per_fixed = FALSE, sp_name,
 time_graft = FALSE, terminal = FALSE, mindist = 0.1)

Arguments

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 == FALSE. If per_fixed == TRUE, then the point along the branch where the grafting occurs: value between 0-1, with a larger number meaning the grafting occurs closer to the rootward end of the branch. If time_graft = TRUE, the specific point (in millions of years, if BirdTree trees are used) for the grafting to occur.

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 per argument, rather than random (FALSE; default). Is ignored if time_graft = TRUE.

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 avotrex:::AgeBind(). The specific point is provided using the per argument.

terminal

Logical value: if time_graft = TRUE, is the species being grafted to a terminal branch.

mindist

If time_graft = TRUE, but the provided grafting time point (per) 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 mindist below the parent node or above the child node.

Value

Returns a tree of class "phylo", with the extinct species grafted on.

Author(s)

Joe Wayman, Tom Matthews and Pedro Cardoso (AgeBind)


AvoPhylo: Building phylogenies based on the AvoTrex extinct bird trait database and BirdTree backbone

Description

Grafting extinct species onto BirdTree phylogenies using the AvoTrex database

Usage

AvoPhylo(ctrees, avotrex, tax, PER = 0.2, PER_FIXED = 0.75, mindist =
  0.1, ord = FALSE, Ntree, n.cores = 1, cluster.ips = NULL)

Arguments

ctrees

Either (i) object (of class multiPhylo) containing multiple BirdTree phylogenies. Individual trees within the multiPhylo object must be of class 'phylo', see the ape package. Or (ii) an individual tree object of class 'phylo'.

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 AvoBind for more details). Can be left at the default value.

PER_FIXED

Point along a branch (expressed as a fraction of the branch length, rootward) to graft the species in the phylogeny database (avotrex argument) which are set to TRUE in the per_fixed column (to reduce very short branch lengths) (see AvoBind for more details). Can be left at the default value.

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 mindist below the parent node or above the child node.

ord

Should the trees within ctrees be kept in order (TRUE) and all used (i.e., the output list of trees is in the same order as ctrees) in the grafting, or should trees be randomly sampled from ctrees (FALSE; the default) prior to grafting. If ord == TRUE, Ntree must equal the length of ctrees. If only a single tree is provided, this argument does nothing.

Ntree

The number of trees to sample from the supplied number of BirdTree trees (i.e., ctrees), if ord == FALSE. Value must be greater or equal to the number of supplied trees (length(ctrees)). If ord == TRUE, Ntree must equal the length of ctrees.

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.

Details

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

Value

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.

References

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

Examples

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

Avotrex phylo dataset

Description

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

Usage

data("AvotrexPhylo")

Format

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"

Details

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.

References

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

Examples

data(AvotrexPhylo)

Bird Tree taxonomic data

Description

Dataset from Jetz et al. (2012) detailing the BirdTree taxonomy used in the BirdTree backbone phylogenetic trees.

Usage

data("BirdTree_tax")

Format

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

Details

If necessary, more details than the __description__ above ~~

Source

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

References

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

Examples

data(BirdTree_tax)

Bird Tree trees

Description

Two Bird Tree backbone trees obtained from Jetz et al. (2012).

Usage

data("BirdTree_trees")

Format

A multiPhylo object consisting of two elements.

Details

If necessary, more details than the __description__ above

Source

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

References

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

Examples

data(BirdTree_trees)

Plot Model Fits for an 'avophylo' Object

Description

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

Usage

## S3 method for class 'avophylo'
plot(
  x,
  tips = "extinct",
  tips_col = NULL,
  order = NULL,
  family = NULL,
  genus = NULL,
  species = NULL,
  avotrex,
  tax,
  lvls = NULL,
  ...
)

Arguments

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

tips_col

Colour of tip labels. If tips = "all_dif" this needs to be a vector of length two, with the first value being the colour for extinct species, and the second for extant species.

order

Prune the tree to only show a specific order (should be a character vector of length = 1). Taxonomy follows BirdTree, see the data(BirdTree_taxa) file. For extinct order names, see the data(AvotrexPhylo) file.

family

As for order, but for families.

genus

As for order, but for genera.

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 lvls argument also needs to be provided.

avotrex

The Avotrex phylo dataset used to generate the trees. For most use cases, this will have been loaded using data(AvotrexPhylo).

tax

The Jetz et al. (2012) BirdTree taxonomy .csv. Supplied as data within the package.

lvls

If species is just a single species, how many levels back (rootward) should be plotted. Uses the tidytree::tree_subset function (see help documentation of that function for further info).

...

Other plotting arguments from the ape package's plot.phylo can be provided.

Value

Generates a phylogeny plot of x.

Examples

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

Plot Model Fits for an 'multiAvophylo' Object

Description

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

Usage

## S3 method for class 'multiAvophylo'
plot(
  x,
  tips = "extinct",
  tips_col = NULL,
  order = NULL,
  family = NULL,
  genus = NULL,
  species = NULL,
  avotrex,
  tax,
  lvls = NULL,
  ...
)

Arguments

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

tips_col

Colour of tip labels. If tips = "all_dif" this needs to be a vector of length two, with the first value being the colour for extinct species, and the second for extant species.

order

Prune the tree to only show a specific order (should be a character vector of length = 1). Taxonomy follows BirdTree, see the data(BirdTree_taxa) file. For extinct order names, see the data(AvotrexPhylo) file.

family

As for order, but for families.

genus

As for order, but for genera.

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 lvls argument also needs to be provided.

avotrex

The Avotrex phylo dataset used to generate the trees. For most use cases, this will have been loaded using data(AvotrexPhylo).

tax

The Jetz et al. (2012) BirdTree taxonomy .csv. Supplied as data within the package.

lvls

If species is just a single species, how many levels back (rootward) should be plotted. Uses the tidytree::tree_subset function (see help documentation of that function for further info).

...

Other plotting arguments from the ape package's plot.phylo can be provided.

Value

Generates a phylogeny plot for each tree in x.

Examples

#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 set of three AvoPhylo trees

Description

A "multiAvophylo" object containing two AvoPhylo trees, generated using the AvoPhylo function. Includes 610 extinct species.

Usage

data(treesEx)

Format

An object of class 'multiAvophylo'

Examples

data(treesEx)