landscapeFPK_Intrinsic: Intrinsic Trait Evolution Model for a Macroevolutionary...

In bomeara/treevo: Using ABC to Understand Trait Evolution

Intrinsic Trait Evolution Model for a Macroevolutionary Landscape on a Fokker-Planck-Kolmogorov Potential Surface (Boucher et al., 2018)

Description

This function describes a discrete-time Fokker-Planck-Kolmogorov Potential Surface model (the FPK model for short), described for trait macroevolution by Boucher et al. (2018), and included here in TreEvo for use as an intrinsic trait model. This model can be used to describe a complex landscape of hills and valleys for a bounded univariate trait space.

Usage

landscapeFPK_Intrinsic(params, states, timefrompresent, grainScaleFPK = 100)

getTraitBoundsFPK(traitData)

plot_landscapeFPK_model(
  params,
  grainScaleFPK = 1000,
  traitName = "Trait",
  plotLandscape = TRUE
)

Arguments

params	A vector containing input parameters for the given model (see Description below on what parameters).
states	Vector of current trait values for a taxon. May be multiple for some models, but generally expected to be only a single value. Multivariate TreEvo is not yet supported.
timefrompresent	The amount of time from the present - generally ignored except for time-dependent models.
grainScaleFPK	To calculate the potential-surface landscape, the trait space is discretized into fine intervals, and the potential calculated for each interval. The scale of this discretization can be controlled with this argument, which specifies the number of intervals used (default is 1000 intervals).
traitData	A set of trait data to calculate distant bounds from for use with this model.
traitName	The name given to the trait, mainly for use in the macroevolutionary landscape plot.
plotLandscape	If TRUE, the estimated macroevolutionary landscape is plotted by the function.

Details

The FPK model is a four parameter model for describing the evolution of a trait without reference to the traits of other taxa (i.e. an intrinsic model in the terminology of package TreEvo). Three of these parameters are used to describe the shape of the landscape, which dictates a lineage's overall deterministic evolutionary trajectory on the landscape, while the fourth parameter (sigma) is a dispersion parameter that describes the rate of unpredictable, stochastic change.

The bounds on the trait space are treated as two additional parameters, but these are intended in the model as described by Boucher et al. to be treated as nuisance parameters. Boucher et al. intentionally fix these bounds at a far distance beyond the range of observed trait values, so in order to ensure they have as little effect on the evolutionary trajectories as possible.

The discrete time Fokker-Planck-Kolmogorov model used here describes a landscape specific to a population at a particular time, with a particular trait value. This landscape represents a potential surface, where height corresponds to a tendency to change in that direction. This allows for multiple optima, and assigns different heights to those optima, which represent the current attraction for a population to move toward that trait value. The shape of this potential surface is the macroevolutionary landscape. which Boucher et al describe the shape of using a fourth-order polynomial with the cubic component removed:

V(x) = ax^4 + bx^2 + cx

Where x is the trait values within the bounded interval - for simplicity, these are internally rescaled to sit within the arbitrary interval (-1.5 : 1.5). The parameters thus that describe the landscape shape are the coefficients a, b, and c. To calculate the landscape, the trait space is discretized into fine intervals, and the potential calculated for each interval. The scale of this discretization can be controlled by the user.

Note that if the landscape has a single peak, or if the potential surface is flat, the model effectively collapses to Brownian Motion, or Ornstein-Uhlenbeck with a single optima. To (roughly) quote Boucher et al: ‘Finally, note that both BM and the OU model are special cases of the FPK model: BM corresponds to V(x)=0 and OU to V(x)=((alpha/sigma^2)*x^2)-((2*alpha*theta/(sigma^2))*x).’

Value

A vector of values representing character displacement of that lineage over a single time step.

Author(s)

David W. Bapst, loosely based on studying the code for function Sim_FPK from package BBMV.

References

Boucher, F. C., V. Demery, E. Conti, L. J. Harmon, and J. Uyeda. 2018. A General Model for Estimating Macroevolutionary Landscapes. Systematic Biology 67(2):304-319.

See Also

An alternative approach in TreEvo to estimating a macroevolutionary landscape with multiple optima is the intrinsic model multiOptimaIntrinsic, however this model requires an a priori choice on the number of optima and the assumption that the optima have similar attractor strength. Other intrinsic models are described at intrinsicModels.

Examples

set.seed(444)
traitData<-rnorm(100,0,1)
# need traits to calculate bounds
bounds<-getTraitBoundsFPK(traitData)
# pick a value at random
trait<-0

# two peak symmetric landscape example
params<-c(
	a=2,
	b=-4,
	c=0,
	sigma=1,
	bounds)

plot_landscapeFPK_model(params)

# simulate under this model - simulated trait DIVERGENCE
landscapeFPK_Intrinsic(params=params, states=trait, timefrompresent=NULL)

# simulate n time-steps, repeat many times, plot results
repeatSimSteps<-function(params,trait,nSteps){
	for(i in 1:nSteps){
	# add to original trait value to get new trait value
		trait<-trait+landscapeFPK_Intrinsic(
			params=params, states=trait, timefrompresent=NULL)
			}
	trait
	}
repSim<-replicate(30,repeatSimSteps(params,trait,20))
hist(repSim,main="Simulated Trait Values")


# uneven two peak symmetric landscape example
params<-c(
	a=2,
	b=-4,
	c=0.3,
	sigma=1,
	bounds)
plot_landscapeFPK_model(params)

# simulate under this model - simulated trait DIVERGENCE
landscapeFPK_Intrinsic(params=params, states=trait, timefrompresent=NULL)

repSim<-replicate(30,repeatSimSteps(params,trait,20))
hist(repSim,main="Simulated Trait Values")

bomeara/treevo documentation built on Aug. 19, 2023, 6:52 p.m.