Overview
This module allows you to simulate the evolution of correlated traits, and cloesly mirror the functionality of PDAPsimul.
There are two correlated trait models that can be run in this package, Brownian Motion and Ornstein-Uhlenbeck.
The Ornstein-Uhlenbeck process is a stochastic function that exhibits a mean reverting tendency. It can be thought of as a moving average.
Both models can be simulated in a gradual fashion, where the traits of daughter nodes depend on the branch length, and in a speciational fashion, where all branch lengths are set to 1.
Finally, there is a punctuated equilibrium model which implements a speciational Brownian motion model, with the exception that only one daughter species experiences a change of traits
A User Guide
Chose the "New Character Model" option in the "Character" menu you should now see a Covariance Matrix Model, PDSIM_Brownian Motion and Ornstein-Uhlenbeck menu items. The Ornstein-Uhlenbeck and Brownian Motion models can be used like continuous character models, and should be available for any calculations you would do with continuous character models.
Co Variance matrix
The Co Variance matrix requires a Tree for running simulations, and a continuous trait matrix to calculate default values for starting models. You must create these before creating a new Co Variance matrix.
Upon creating a co variance matrix, you will see a square matrix with the name of each trait in the continuous trait matrix as a column title, and all row titles set to "(trait name): unassigned."
This is the covariance matrix showing the correlation between all pairs of traits, and the default values were calculated from the correlation of traits in the trait matrix. The row titles also tell you what model controls the evolution of a particular trait. To assign a model to control trait evolution, simply right click the row title.
When a model is assigned to control a trait, a dialog will ask you if you wish to assign default values for the character to that model. By doing so you will lose any current settings of the model. The default settings are designed to help create a null hypothesis for later statistic tests.
Evolution of the traits can be simulated on the tree once all the traits are assigned models. Under the Co Variance matrix menu chose the "Run Simulation" option. A diabog box will prompt you for a model name, the number of replicates to run, and a step size.
* The step size should only be non-zero when bounding is used. A non-zero step size causes values for all traits to be calculated each step along branches. This increases the amount of necessary processing time.
* Warning: Some branch lengths can be very long (10^6), and specify a small step size (10) will take an unreasonable amount of time to complete simulations. When specifying step sizes, make sure to take branch lengths into account.
Show cholesky: Changes the values displayed in the matrix to the values of the cholesky matrix used to generate correlated random numbers, and an option to add new continuous character simulation.
Continuous character models can also be created with the new model option under character models.
PDSIM-Brownian Motion
Trait variance: This represents the variance around a mean arising from random motion of the trait. If Variance of mean at tips is 0 then this represents the expected variance of the trait at tips of the tree. I have tested to make sure this works for trees with contemporaneous tips, and I believe it should generally work, but temporally heterogeneous tips are untested.
Root state: Simply the value of the trait at the root node of the tree.
Mean state at tips: The expected mean state of the trait at the tips of the tree. If this is different than the root state there is directional component to the motion of traits. This is somewhat analogous to the mean velocity of a group molecules diffusing in a liquid. If a trait as a whole has a tendency to move over evolutionary time then this is reflected by a difference between root states and mean tip states.
Variance of mean at tips: This value represents the variance of the mean velocity of traits. Though trait means do not exist for individual nodes per say, a variance of means at tips results in a distribution of velocity of traits. More practically the total variance of a trait at the tips will be the sum of the trait variance and the variance of the mean. Also, trait movement is drawn from a correlated normal distribution and the mean movement is not, so the correlation between traits will also be lower as the variance of the mean at tips is greater.
Ignore branch length: Tells the simulator to treat all branches as 1 unit in length.
Punctuated: Tells the simulator to treat nodes with the same name as representing the same unchanged species. All chance is distributed to nodes who's names differ from the parent nodes name.
Use bounding: Specifies that traits cannot take on values outside of certain bounds. When telling the simulator to use bounding it is also
It is important to consider how often the simulator checks to see if traits have gone out of bounds on longer branches. I have not developed any guidelines on setting step size yet. When specified the lower and upper bound values are used, and of course the lower bound value must be smaller than the upper bound value.
Bounding Types: Types of bounding are described in the bounding section.
Set to defaults: Prompts you for a matrix and character to set as the default values for this model.
Ornstein-Uhlenbeck
Most of the parameters of the Ornstein Uhlenbeck model are similar to those in the brownian motion model, the key differences are the use of peaks instead of means, and the addition of a decay variable.
Peaks: peaks represent the mean the the Ornstein Uhlenbeck model has a tendency to revert to. Unlike means in brownain motion the peak variable is explicitly stored for each node during calculations.
Decay: The decay is a measure of the strength of the tendency of this model to revert to the mean. Higher decays will lead to less variability around a peak.
Bounding procedures
A number of bounding procedures exist, and are set by the user as an parameter of the simulation.
Truncate Change: sets an out of bound trait to the boundary value.
Flip: causes the trait to step away from the bound instead of over it, if this move also takes the trait out of bounds then the truncation method is used.
Hard Bounce: the trait moves its full step distance, but reveres the direction of motion at the bound.
Softbounce: reduces motion toward the bound by a factor dependent on the distance of a trait from the bound.
Replace: if a trait moves out of bounds then the step is simply ignored and recalculated from its initial value.
Simulation Results
The simulation results can be saved as .sim files or .csv files.
.sim files: .sim file only save the information for the first two traits, but can be opened by PDANOVA for statistical processing. If you intend to open these files in PDANOVA, make sure to specify the DOS format end line.
.csv files: .csv files save the results in a comma separated format that can be opened by most spreadsheet software.
Statistical Analysis This option runs does a serious of statistical test similar to those performed by PDANOVA, and a new window for looking at these results.
Once calculated all simulation results can be reopened by choosing the model name from the "Open Simulation Data" at the bottom of the "Character" menu.
Statistical Results
Under the statistics menu there are a number of options for displaying summary statistics which are fairly self explanatory. When chosen they will update the numbers in the matrix to reflect the proper information, but they is currently very little visual feed-back to tell you which statistic you are looking at.
Which ever statistic you are currently looking at can be saved to a .csv file for exporting to an external program.
A menu option also allows you to view the f and p-value. For a user chosen continuous character matrix when compared to the simulation results. The chosen matirx must have the same number of taxa as the simulation results for taxa to be properly grouped. The P value tells you the percentage of runs which have an F value smaller then the F value of the matrix chosen by the user.
Statistical results can also be reopened by choosing the model name from the "Open Simulation Data" at the bottom of the "Character" menu.
Statistical Results
Open up the example "00a-FelsteinsContrasts.nex" in the correlation directory.
Go to "Character Matrix Editor" in the Character Menu, and chose the 'I' shaped cursor in order to edit text.
change the first column header to "Body Mass" and the second column header to "Home Range"
Select "New Character Model" > PDSIM_Brownian Motion.
Title the new model "Body Mass."
Click the check box "Use bounding".
Select bounding type "Replacement".
Enter a lower bound of "-1.5229" and upper "4.176"
change "Root State" to ".3010"
Select "New Character Model" > PDSIM_Brownian Motion.
Title the new model "Home Range."
Click the check box "Use bounding".
Select bounding type "Replacement".
Enter a lower bound of "-3.0" and "3.3010"
change "Root State" to "1.8036"
Select "New Character Model" > Co Variance Matrix.
This should open a window with a 2x2 matrix. If not, abandon all hope and send me a bug report.
Click on a row header which reads Unassigned.
A window should pop up and show a few models to chose from, chose the appropriate model.
Check the box set model to defaults for this trait
repeat for Home range
The Row titles should now read:
(Body Mass) Body Mass.
(Home Range) Home Range.
From the Co-Variance Matrix menu in the Co Variance Matrix window chose Run Simulation.
In the pop-up window change the number of runs to 1,000.
Even though we use bounding we will leave step size at 0 for now.
click OK.
It may be running the simulation for a few minutes.
At Prompt Change TODO:FIXME to My Simulation .
A new window titled MY Simulation (for now) will show the simulation results with the column
header listing a taxon and trait name, and the row header listing the run number.
Chose the "Do Statistical Analysis" from the Simulation menu.
Assign the first 19 taxa (Tm,Ur...Pp,Pt,Pq) To group one, and the rest to group two.
You will have to to use the Scroll right and Scroll left buttons to assign all the taxa to groups.
A number of statistic results are displayed and can be viewed by selecting the submenu "Show Summary Statistic" under the "Statistics" Menu.
But for now, chose "Get F and P Value for Data Matrix."
On the pop up menu chose a character trait.
Then, again chose the Felstein Matrix under stored matrices.
This value should be comperable to that in Garland's paper.
Fin!