Help for package ppgm

Type:

Package

Title:

PaleoPhyloGeographic Modeling of Climate Niches and Species Distributions

Version:

1.1

Description:

Reconstruction of paleoclimate niches using phylogenetic comparative methods and projection reconstructed niches onto paleoclimate maps. The user can specify various models of trait evolution or estimate the best fit model, include fossils, use one or multiple phylogenies for inference, and make animations of shifting suitable habitat through time. This model was first used in Lawing and Polly (2011), and further implemented in Lawing et al (2016) and Rivera et al (2020). Lawing and Polly (2011) <doi:10.1371/journal.pone.0028554> "Pleistocene climate, phylogeny and climate envelope models: An integrative approach to better understand species' response to climate change" Lawing et al (2016) <doi:10.1086/687202> "Including fossils in phylogenetic climate reconstructions: A deep time perspective on the climatic niche evolution and diversification of spiny lizards (Sceloporus)" Rivera et al (2020) <doi:10.1111/jbi.13915> "Reconstructing historical shifts in suitable habitat of Sceloporus lineages using phylogenetic niche modelling.".

Imports:

ape, fields, geiger, gifski, methods, phangorn, phytools, stringi, parallel, doParallel, foreach

Depends:

R (≥ 4.4.0), R (≥ 2.10), sp, sf

License:

GPL (≥ 3)

Encoding:

UTF-8

LazyData:

true

LazyDataCompression:

RoxygenNote:

7.3.2

Suggests:

knitr, rmarkdown, testthat (≥ 3.0.0)

Config/testthat/edition:

Config/testthat/parallel:

true

VignetteBuilder:

knitr

NeedsCompilation:

Packaged:

2025-03-12 15:53:39 UTC; alexandra.howard

Author:

A. Michelle Lawing [aut, cph], Alexandra Howard [aut, cre], Maria-Aleja Hurtado-Materon [aut]

Maintainer:

Alexandra Howard <alexandra.howard@ag.tamu.edu>

Repository:

CRAN

Date/Publication:

2025-03-12 16:20:02 UTC

addFossil

Description

Adds a fossil as a tip to a specified phylogeny given either an age range that the fossil occurs in, a specific edge that the fossil diverged from, or both. If the specific edge placement for the fossil is unknown, then this function randomly places the fossil on any edge that is within the age range.

Usage

addFossil(tree, mintime = 0, maxtime = NA, name = "fossil", edge = NA)

Arguments

tree

An object of the class "phylo"

mintime

The minimum age of the fossil. If no minimum time is specified, the default value is 0.

maxtime

The maximum age of the fossil. If no maximum time is specified, the default value is the maximum tree age.

name

The name of the fossil to appear as a tip.label.

edge

The edge on the tree where the fossil presumably diverged. If no edge is specified, then the function randomly selects an edge within the age range of the fossil.

Details

There are several random components to this function. First, if an edge is not specified to place a fossil, then an edge is randomly selected that is within the age range of the fossil. Second, the exact placement of the node leading to the fossil is randomly selected within the age range specified. Third, the length of the edge leading to the fossil is randomly selected with constraints on the maximum length of the edge, where the maximum length of the edge cannot render the fossil younger than the minimum time of occurrence as specified in the mintime argument.

Value

An object of the class "phylo".

Author(s)

A. Michelle Lawing, Alexandra F. C. Howard

Examples

mytree <- phytools::pbtree(n=20)
newtree <- addFossil(mytree, mintime = max(mytree$edge.length)/2, maxtime= max(mytree$edge.length))
plot(newtree)

getBioclimVars

Description

This function retrieves the bioclimatic variables described in Nix & Busby (1986) for the specified variables and the specified time period.

Usage

getBioclimVars(occurrences, which.biovars=c(1:19), 
use.paleoclimate=TRUE, paleoclimateUser=NULL, layerAge=c(0:20))

Arguments

occurrences

a matrix or data.frame with three columns and rows to represent individuals. The first column must be species name for extant occurrences or the age in closest Ma for fossil occurrences. Second and third column must be Longitude and Latitude.

which.biovars

a vector of the numbers of the bioclimatic variables that should be returned. The bioclimatic variables number correspond to the table at (https://www.worldclim.org/data/bioclim.html).

use.paleoclimate

if left blank, default North America paleoclimate data is used. If FALSE, user submitted paleoclimate must be provided

paleoclimateUser

list of data frames with paleoclimates, must be dataframes with columns: GlobalID, Longitude, Latitude, bio1, bio2,...,bio19.

layerAge

vector with the ages of the paleoclimate dataframes, if using user submitted paleoclimate data

Details

The occurrences argument should contain all extant or all fossils. Columns should be in the format: Species, Longitude, Latitude for extant data.

If using the provided paleoclimate data:

Modern time period uses the Hijmans et al. (2005) high resolution climate interpolations.

The time period 10 Ma uses the GCM by Micheels et al (2011) for the Tortonian.

The time period 15 Ma uses the GCM by Krapp & Jungclaus (2011) for the Middle Miocene.

For the one million year intervals outside the modern and past GCMs, the climate was interpolated based on the benthic marine foram stable oxygen isotope ratio curve from Ruddiman et al 1989. The scale of these variables is at a 50 km equidistant point grain size.

Value

Returns a data frame with the original occurrences input appended with columns of bioclimate variables as specified. If fossils are included, the returned bioclimate variables are from the closest 1 Ma interval of isotopically scaled climate.

Author(s)

A. Michelle Lawing, Alexandra F. C. Howard, Maria-Aleja Hurtado-Materon

References

Hijmans, R. J. et al. (2005) Very high resolution interpolated climate surfaces for global land areas

Krapp, M. and Jungclaus, J. H. (2011) The Middle Miocene climate as modeled in an atmosphere-ocean-biosphere model. Climate of the Past 7(4):1169-1188

Micheels, A. et al. (2011) Analysis of heat transport mechanisms from a Late Miocene model experiment with a fully-coupled atmosphere-ocean general circulation model. Palaeogeography, Palaeoclimatology, Palaeocology 304: 337-350

Nix, H. and Busby, J. (1986) BIOCLIM, a bioclimatic analysis and prediction system. CSIRO annual report. CSIRO Division of Water and Land Resources, Canberra.

Ruddiman, W. F. et al. (1989) Pleistocene evolution: Northern hemisphere ice sheets and North Atlantic Ocean. Paleoceanography 4: 353-412

Examples

data(occurrences)
biooccur <- getBioclimVars(occurrences,which.biovars=c(3,5))
#returns data frame with bioclimate variables 3 and 5 for occurrence data

getEnvelopes

Description

This function gets the bioclimate envelopes of species and nodes.

Usage

getEnvelopes(treedata_min, treedata_max, node_est)

Arguments

treedata_min

tree data object with min estimate of the climate envelope for each species.

treedata_max

tree data object with max estimate of the climate envelope for each species

node_est

the estimate of all the nodes, both min and max

Details

Function derives the minimum, and maximum of each climate variable

Value

An array containing climate envelopes for each node

Author(s)

A. Michelle Lawing, Alexandra F. C. Howard

Examples

data(sampletrees)
data(occurrences)
tree <- sampletrees[[25]]
biooccu <- getBioclimVars(occurrences, which.biovars=1)
sp_data_min<- tapply(biooccu[,4],biooccu$Species,min)
sp_data_max<- tapply(biooccu[,4],biooccu$Species,max)
treedata_min <- geiger::treedata(tree,sp_data_min,sort=TRUE,warnings=F)
treedata_max <- geiger::treedata(tree,sp_data_max,sort=TRUE,warnings=F)
full_est <- nodeEstimateEnvelopes(treedata_min,treedata_max)
node_est <- full_est$est
example_getEnvelopes <- getEnvelopes(treedata_min, treedata_max, node_est)

getGeoRate

Description

This function calculates the change in suitable habitat through time in geographic space.

Usage

getGeoRate(envelope, tree, which.biovars, use.paleoclimate=TRUE, 
paleoclimateUser=NULL, layerAge=c(0:20))

Arguments

envelope

the min and max climate envelope of each lineage for each time slice, as outputted by getEnvelopes()

tree

the phylogeny of all species. An object of class phylo

which.biovars

a vector of the numbers of the bioclimate variables to be included. The bioclimate variables number correspond to the table at (https://www.worldclim.org/data/bioclim.html).

use.paleoclimate

if left blank, default North America paleoclimate data is used. If FALSE, user submitted paleoclimate must be provided

paleoclimateUser

list of data frames with paleoclimates, must be dataframes with columns: GlobalID, Longitude, Latitude, bio1, bio2,...,bio19. (see getBioclimvars()).

layerAge

vector with the ages of the paleoclimate dataframes, if using user submitted paleoclimate data

Details

Calculates rate of geographic change of all lineages. Outputs both the geographic center change, and the geographic size change.

Value

geo_center change in geographic center of suitable climate envelope

geo_size change in geographic size of suitable climate envelope

time_int time intervals

Author(s)

A. Michelle Lawing, Alexandra F. C. Howard, Maria A. Hurtado-Materon

Examples

data(sampletrees)
data(occurrences)
data(paleoclimate)
tree <- sampletrees[[25]]
occu <- getBioclimVars(occurrences, which.biovars=1)
sp_data_min<- tapply(occu[,4],occu$Species,min)
sp_data_max<- tapply(occu[,4],occu$Species,max)
treedata_min <- geiger::treedata(tree,sp_data_min,sort=TRUE,warnings=F)
treedata_max <- geiger::treedata(tree,sp_data_max,sort=TRUE,warnings=F)
full_est <- nodeEstimateEnvelopes(treedata_min,treedata_max)
node_est <- full_est$est
example_getEnvelopes <- getEnvelopes(treedata_min, treedata_max, node_est)
example_getGeoRate <- getGeoRate(example_getEnvelopes, tree, which.biovars=1)

getLineageClimate

Description

This function calculates the suitable climate for each specific lineage, starting at the tips and going back through time to the root.

Usage

getLineageClimate(envelope, tree, which.biovars, 
use.paleoclimate=TRUE, paleoclimateUser=NULL, layerAge=c(0:20))

Arguments

envelope

the min and max climate envelope of each lineage for each time slice, as outputted by getEnvelopes()

tree

the phylogeny of all species. An object of class phylo

which.biovars

a vector of the numbers of the bioclimate variables to be included. The bioclimate variables number correspond to the table at (https://www.worldclim.org/data/bioclim.html).

use.paleoclimate

if left blank, default North America paleoclimate data is used. If FALSE, user submitted paleoclimate must be provided

paleoclimateUser

list of data frames with paleoclimates, must be dataframes with columns: GlobalID, Longitude, Latitude, bio1, bio2,...,bio19. (see getBioclimvars()).

layerAge

vector with the ages of the paleoclimate dataframes, if using user submitted paleoclimate data

Details

Calculates suitable climate for each specific lineage given reconstructed climate envelopes from getEnvelopes(). Returns dataframe of all estimated occurrences for every lineages for every time slice of paleoclimate.

Value

matchedClim list of occurrences points for each lineage, for each time slice of paleoclimate data

lineage list of lineage specific nodes, as output from phangorn::Ancestors

Author(s)

A. Michelle Lawing, Alexandra F. C. Howard, Maria A. Hurtado-Materon

Examples

data(sampletrees)
data(occurrences)
data(paleoclimate)
occu <- getBioclimVars(occurrences, which.biovars=1)
tree <- sampletrees[[25]]
#species minimum for biovariable 1
sp_data_min<- tapply(occu[,4],occu$Species,min)
#species maximum for biovariable 1
sp_data_max<- tapply(occu[,4],occu$Species,max)
#convert to treedata object
treedata_min <- geiger::treedata(tree,sp_data_min,sort=TRUE,warnings=F) 
treedata_max <- geiger::treedata(tree,sp_data_max,sort=TRUE,warnings=F)
#estimate node values using Brownian Motion
full_est <- nodeEstimateEnvelopes(treedata_min,treedata_max)
node_est <- full_est$est #extract only node estimates
#calculate climate envelopes
example_getEnvelopes <- getEnvelopes(treedata_min, treedata_max, node_est)
#calculate lineage specific climate
example_getLinClim <- getLineageClimate(example_getEnvelopes, tree, which.biovars=1)

getTimeSlice

Description

This function extracts estimated ancestral reconstructions for continuous characters any time specified along a phylogeny for all lineages present at the specified time.

Usage

getTimeSlice(timeSlice, tree, trait, model = "BM", plot.est = FALSE)

Arguments

timeSlice

single numeric or a vector with the time (or times) to extract the estimated ancestor reconstructions.

tree

an object of the class "phylo" that should be dated

trait

a vector of both tip values and node estimates that correspond to tree

model

if model = "estimate", the best fit model of evolution. If the model was specified, then model is the specified model, passes to geiger::fitContinuous(). Model options currently supported are: "BM", "OU", "EB", "lambda", "kappa", "delta"

plot.est

a conditional stating whether or not to plot the results

Details

The estimated reconstruction relies on an interpolation between node or between tip and node estimates of the trait. This method assumes a constant rate of evolution along the lineage where the interpolation is taking place.

Value

edge for each time specified, a vector of edges that are present during that time are returned

est for each time specified, a vector of estimates of the ancestral reconstruction along each edge

Author(s)

A. Michelle Lawing, Alexandra F. C. Howard

Examples

data(sampletrees)
data(occurrences)
occurrences <- getBioclimVars(occurrences, which.biovars=1)
sp_data_min<- tapply(occurrences[,4],occurrences$Species,min)
treedata_min <- geiger::treedata(sampletrees[[1]], sp_data_min)
ex_est <- nodeEstimate(treedata_min, 1, model = 'BM') #runs BM model
ex_timeSlice <- getTimeSlice(10,treedata_min$phy,c(treedata_min$data[,1],ex_est$est))

nodeEstimate

Description

This function estimates the ancestral character states for continuous characters given a model of evolution or using the best fit model of evolution from the fitContinuous function in the geiger package. The ancestral states are estimated using GLS described in Martins and Hansen (1997).

Usage

nodeEstimate(treedata.obj, traitnum, model = "BM", bounds = list(), 
control = list(), plot.est = FALSE)

Arguments

treedata.obj

an object of the class "treedata".

traitnum

the column number of the trait within the treedata object to be reconstructed.

model

the model of evolution to use in the ancestral state reconstruction. Options are "estimate", "BM", "OU", "EB", "lambda", "kappa", "delta", "mtrend","rtrend".

bounds

bounds used for the model, passes to fitContinuous(), uses default if none specified.

control

setting used for optimization of the model likelihood. Passes to fitContinuous().

plot.est

logical. whether or not to plot the traitgram of the estimated ancestor states.

Details

See the fitContinuous() details for descriptions of the models of evolution and parameter estimation. nodeEstimate() currently supports the following models of evolution: Brownian motion (Felsenstein, 1973), Ornstein-Uhlenbeck (Butler and King, 2004), early-burst (Harmon et al., 2010), lambda (Pagel, 1999), kappa (Pagel, 1999), and delta (Pagel, 1999).

Value

an object of the class "nodeEstimate".

model if model = "estimate", the best fit model of evolution. If the model was specified, then model is the specified model.

est the ancestral node estimates of the continuous character.

phy the phylogeny used for the estimates, which might be transformed depending on the evolutionary model.

BM if model = "BM", returned values from fitContinuous() where the model is "BM"

OU if model = "OU", returned values from fitContinuous() where the model is "OU"

EB if model = "EB", returned values from fitContinuous() where the model is "EB"

lambda if model = "lambda", returned values from fitContinuous() where the model is "lambda"

kappa if model = "kappa", returned values from fitContinuous() where the model is "kappa"

delta if model = "delta", returned values from fitContinuous() where the model is "delta"

mtrend if model = "mtrend', returned values from fitContinuous() where the model is "mean_trend"

rtrend if model = "rtrend', returned values from fitContinuous() where the model is "rate_trend"

fitted if model = "estimate", returned values from the best fit model of evolution.

Author(s)

A. Michelle Lawing, Alexandra F. C. Howard

References

Butler, M. A. and King, A. A. (2004) Phylogenetic comparative analysis: a modeling approach for adaptive evolution. American Naturalist, 164:683-695.

Felsenstein, J. (1973) Maximum likelihood estimation of evolutionary trees from continuous characters. American Journal of Human Genetics, 25:471-492

Harmon, L. J. et al. (2010) Early bursts of body size and shape evolution are rare in comparative data. Evolution, 64:2385-2396

Martins, E. P. and Hansen, T. F. (1997) Phylogenies and the comparative method: a general approach to incorporating phylogenetic information into the analysis of interspecific data. American Naturalist, 149, 646–667.

Pagel M. (1999) Inferring the historical patterns of biological evolution. Nature, 401:877-884

Examples

data(sampletrees)
data(occurrences)
occurrences <- getBioclimVars(occurrences, which.biovars=4)
sp_data_min<- tapply(occurrences[,4],occurrences$Species,min)
ex <- geiger::treedata(sampletrees[[1]], sp_data_min)
nodeEstimate(ex, 1, model = 'OU') #runs OU model

nodeEstimateEnvelopes

Description

This function estimates climate envelopes at nodes with the optional placement of fossils on randomly assigned or specified edges on a tree.

Usage

nodeEstimateEnvelopes(treedata_min, treedata_max, fossils=FALSE, 
fossils.edges=FALSE, model="BM", bounds=list(), control=list(), 
use.paleoclimate = TRUE, paleoclimateUser = NULL, layerAge = c(0:20), 
which.biovars = which.biovars)

Arguments

treedata_min

tree data object with min estimate of the climate envelope – list where first object is phylogeny, and second object is array of species with climate data variables (species must match)

treedata_max

tree data object with max estimate of the climate envelope

fossils

a matrix with three columns of age, longitude, and latitude, in that order, and rows that are entries for fossil occurrences.

fossils.edges

the edge number that the fossil occurs on

model

the model of evolution to use in the ancestral state reconstruction. Options are "estimate", "BM", "OU", "EB", "lambda", "kappa", "delta", "mtrend","rtrend".

bounds

bounds used for the model, passes to fitContinuous(), uses default if none specified.

control

setting used for optimization of the model likelihood. Passes to fitContinuous().

use.paleoclimate

if left blank, default North America paleoclimate data is used. If FALSE, user submitted paleoclimate must be provided

paleoclimateUser

list of data frames with paleoclimates, must be dataframes with columns: GlobalID, Longitude, Latitude, bio1, bio2,...,bio19. (see getBioclimvars()).

layerAge

vector with the ages of the paleoclimate dataframes, if using user submitted paleoclimate data

which.biovars

A vector of the numbers of the bioclimate variables that should be returned. The bioclimate variables number correspond to the Hijmans table at (https://www.worldclim.org/data/bioclim.html).

Details

function adds fossils to trees according to addFossil(), then passes to nodeEstimate().