View source: R/landscapeFPK_Intrinsic.R
landscapeFPK_Intrinsic | R Documentation |
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.
landscapeFPK_Intrinsic(params, states, timefrompresent, grainScaleFPK = 100)
getTraitBoundsFPK(traitData)
plot_landscapeFPK_model(
params,
grainScaleFPK = 1000,
traitName = "Trait",
plotLandscape = TRUE
)
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 |
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 |
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).’
A vector of values representing character displacement of that lineage over a single time step.
David W. Bapst, loosely based on studying the code for function Sim_FPK
from package BBMV
.
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.
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
.
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")
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.