MaizeGenetics.net

 Phylogeographer Documentation Overview:

1.) Background on Analysis
2.) Program Basics
3.) Geographic Display
4.) Maps
5.) Trees
6.) Matrices
7.) Matrix Graphing
8.) Results Table
9.) Results Editor

1.) Background on Analysis

Many hypotheses in phylogeography and in much of biology can be represented in terms of distance matrices (Smouse et al. 1986). Most genetic relationships can be represented by distance matrices, and they are often the preferred way to described intraspecific relationships were gene flow between multiple populations is continuous. And since almost all-geographic hypotheses can be described with distance matrices, it is a natural to evaluate genetic-geographic hypotheses with distance matrices.

The Mantel test was originally developed to examine associations between dissimilarity matrices, and this test has been expanded with correlation versions and permutation tests (Smouse et al. 1986; Sokal and Rohlf 1995). This program implements correlation and partial correlation versions of this test (Smouse et al. 1986). Matrices X1 and X2 are predictors of matrix Y. Partial correlation (YX1.X2) estimates the correlation between Y and X1, while keeping X2 constant. Significance is determined by permuting the Y matrix, while the X matrices are held constant (Dietz 1983; Sokal and Rohlf 1995).

I have used this program, to evaluate whether various dispersal hypotheses or clinal hypotheses better explain the genetic differentiation of teosinte populations (Buckler et al. 2000). Our genetic distance matrix was based on isozyme data, while the dispersal and clinal hypotheses were developed using this program. Other examples of this type of analysis can be found for the Yanomama Indians were linguistic, geographic, and genetic hypotheses were compared (Smouse et al. 1986; Sokal et al. 1986). The spread of agriculture was related to human dispersals in Europe by comparing genetic, geographic, and archaeologically based hypotheses (Sokal et al. 1991).

Buckler, E. S., IV, M. M. Goodman, T. P. Holtsford, J. F. Doebley, and J. Sanchez G. 2000. The phylogeography of Zea mays. (PDF) 

Dietz, E. J. 1983. Permutation tests for association between two distance matrices. Syst. Zool. 32:21-26.

Smouse, P. E., J. C. Long, and R. R. Sokal. 1986. Multiple regression and correlation extensions of the Mantel test of matrix correspondence. Syst. Zool. 35:627-632.

Sokal, R. R., N. L. Oden, and C. Wilson. 1991. Genetic evidence for the spread of agriculture in Europe by demic diffusion. Nature 351:143-145.

Sokal, R. R., and F. J. Rohlf. 1995. Biometry. W. H. Freeman and Co., New York.

Sokal, R. R., P. E. Smouse, and J. V. Neel. 1986. The genetic structure of a tribal population, the Yanomama Indians. XV. Patterns inferred by autocorrelation analysis. Genetics 114:259-287.


2.) Program Basics

There are four basic windows: result editor, results table, geographic display, and the matrix graph. The program starts out in the result editor. All menu choices are underlined; file names are placed in "quotes".

Overview of what to do:

1. From results editor:

 Load genetic distance matrix by choosing File|Open and then selecting the "DistanceMatrix" file.

2. From geographic display

a. Open the geographic display by choosing Window|Geographic Display

b. Add map by choosing Background|Add Map and then select "MexicoMap.bin"

c. Load geographic tree by choosing Trees|Open Tree and then select "BasicDispersal.tree"

d. Choose for by geographic display by selecting Trees|ZmaysBaseTree

e. Modify branch connections by clicking mouse on descendent node and dragging and releasing on the ancestral node.

f. Move a node by holding the shift key and simultaneously dragging the node. This will only work for nodes that do not have fixed positions (open circles).

3. Return to the results editor

a. Use Analysis|Tree to Matrix to convert the tree into a new dispersal hypothesis matrix (name this "dispersal")

b. Use Analysis|Tree to Matrix to convert the tree into a new linear hypothesis matrix by clicking the linear checkbox (name this "linear")

c. Use the Analysis|Matrix to correlate the genetic, dispersal, and linear hypotheses

d. Use the Analysis|Matrix and the partial matrix option to control for linear hypotheses while correlating genetic and dispersal hypotheses

e. To save the text of the results choose File|Save Text.

4. Open the Results Table

a. Open the results table by choosing Window|Results Table.

b. Rerun the previous matrix correlations, and this time the results will be save in the results table.

c. Choose File|Save Results to save these correlation results to a spreadsheet readable format.

5. From the Matrix Graph

a. Open the matrix graphing by choosing Window|Matrix Graph

b. Select the genetic matrix by choosing X Axis|GeneticDist

c. Select the disperal matrix by choosing Y Axis|Dispersal

d. Use the mouse to click on outliers of the distribution

That is it for the basics!


3.) Geographic Display

What is the geographic display?

-The geographic display makes it possible to view the map of your area, while displaying your tree with information on the nodes and their relations to one another. Dispersal tree hypotheses can be developed in this geographic display.

How to get to the Geographic Display?

-When the program is first opened you will be the Results Editor, from here go to Window in the menu on top, click and highlight Geographic Display and click on it. A new screen entitled geographic display will come up on the screen.

TREES

How to add a tree?

-Go to Trees in the menu. It will pull down another menu. From there go to either New Tree or Open Tree. The format of a tree file is covered in the tree section.

How to save a tree?

-Select Tree|Save Tree. When this comes up another box will appear, select the item to save and then click Save. When the following screen comes up, name the file and then click OK.

How to change the connections (branches) of a tree?

-Click on the decendent node and drag the mouse to the ancestral node.

NODES

What are nodes?

-Nodes are the circles on the tree connected by branches. These generally represent the populations in the study. Nodes are fixed if a cross appears in the center; they are unfixed w/o a cross.

-To display the name of the node, place the mouse over that node.

-Double click on node to get information on it, such as longitude, latitude, name distance in km, and what it is connected to:

A: = ancestor node

D: = descendent node

How to connect the nodes?

-Place mouse on top of the node, click and hold, while dragging mouse down to the place where you want your new node to be, then release.

How to add a node?

-Go Modify|Add Node. The new node will always appear in the upper left-hand corner of the map. This node will be unfixed and must be named.

How to remove (delete) a node?

-Double click on node. When box comes up on screen click Remove Node.

How to move a node?

-Place mouse on top of the node, click and hold, while dragging mouse down to the place where you want your new node to be, then release.

How to change a node from being fixed to unfixed?

-Double click on the node and a box with all the particulars on that node will come up. To change it from a fixed to unfixed node make sure the box next to Fixed Position doesn?t have a check mark in it. Then you are able to manipulate the latitude and longitude measurements, names, etc.

How to prevent overcrowding?

-If there are too many nodes go to Modify|Hide Tips. The ancestral nodes will only be left on the map.

How to deal with overlapping nodes?

-Go to Modify|Overlap Nodes. It will be activated when a check mark is beside it. This feature does not put them in their correct geographic location.

How to know if the tree is already loaded into the computer?

-Under Tree|Geographic Display screen, trees already loaded will appear beneath the bar and when in use will be marked by a check.

How to calculate branch lengths?

-Go to Modify|Calculate Branch Lengths. (This is done automatically when you can the length of something.)

How to denote nodes of different taxa?

-Go to Modify|Change Groups

-Every node will be listed in Group 0. To make a different group hit Add and then highlight the line you would like transferred over to another group (e.g. select that group 1, or the like).

-There will be a change in the color of the various taxa depicted. Be aware that highlighted species and groups of a different color don?t appear that way on a print out.

How to move the lines (nodes) back to their original taxa?

-Go to Modify|Change Groups

-To move the lines back into their original group, move them back to zero by highlighting them and then pressing the Group 0 button on the screen.

BACKGROUND

How to add a map?

-Go to Background|Add Map. The format of a map file is covered in the map section.

-Select map from Background read file.

-Click on file and load, this may take a few minutes. **Map will start out as a ".tsv" file, to make the loading process faster, once it is loaded, go back to Background|Save Map as Binary. The suffix ".bin" will be appended to ".tsv".

How to clear a map?

-Go to Background|Clear Map.

How to magnify a map?

-Go to Background|Zoom In to magnify an area on the map. This is two fold. Or press the + button

-To see a larger portion of the map, go to Background|Zoom Out. This is two fold as well. Or press the -- button.

-To set Specific Magnifications, put desired numbers into the box between Zoom In (positive sign) and Zoom Out (negative sign). Hit Enter when finished.

How to set Maximum and Minimum altitudes?

-To set maximum altitude click on the white box beneath the words "Map Legend." Then key in the desired altitude and press "Enter." Everything above this altitude will appear white.

- To set minimum altitude, click on the bottom black box in the column entitled "Map Legend." This changes the sea level when numbers are set, once enter is hit, everything below this altitude will appear black in color. Negative values are fine, and this might be used to derive maps during the ice age, when sea levels were lower.

How to save the tree and background image to a file?

-Go to Background|Screen to GIF file


4.) Maps

This program requires maps with latitude and longitude tags and the elevation of all intersecting points. This type of data can be obtained from several sources including the Lamont-Doroughty Earth Observatory. For example world topography can be found here. Save a subset of this data set in tsv format (tab separated values) and add the number of longitude and latitude rows to beginning of the file.

Maps can be opened first as tsv files by Phylogeographer, and then they can be saved from the program as a new binary file. If the TSV file any scientific notation, it will not load properly (I am trying to fix this). The binary files load much faster than the text files and should be used for future uses.

Here is an example Map files:

15	8							
	245.42	245.5	245.58	245.67	245.75	245.83	245.92	246
31.417	-39	-47	-49	-46	-47	-28	-22	-21
31.5	-33	-38	-37	-31	-12	-16	-8	-5
31.583	-19	-21	-19	35		20	25	-10
31.667		-8	45	50		30	26	2
	-10	105	120	60	55	45	35	17
31.833	110	125	80	80	80	65	50	41
31.917	75	75	75	80	80	80	75	86
32	85	75	83	80	110	105	110	145
	50	69	86	90	106	122	132	174
32.167	53		99	112	147	145	178	268
32.25	66	77	91	132	154	201	286	353
	63	82	116	149		254	400	326
32.417	61	99	129	192	250	349	301	325
32.5	63	94	138	252	353	263		347
32.583	60	97	167	409	359	201	245	262
								

ZmaysTree

(BC001xxxxx:40.34041,BH004xxxxx:53.563034,(BT008xxxxx:86.42275,BV011xxxxx:35.51092,BM005xxxxx:51.594917)
CBalAnc:175.2843)SBalAnc;

#Geography

SBalAnc? 17.85 -99.41 

BC001xxxxx 17.50 -99.50 

CBalAnc? 18.98 -100.57 

BT008xxxxx 18.38 -100.05 

BV011xxxxx 19.08 -100.25 

BM005xxxxx 19.41 -100.75 

BH004xxxxx 18.28 -99.18 

Parts of File:
Tree Name
Tree in phylip format
#Geography << header for beginning of geography section>>
TaxaName Latitude Longitude

Notes:
Most of the trees have named ancestral nodes, as this is useful for reconstructing geographic pathways. This is not necessary for
the original tree; the program will add the ancestral nodes. If nodes are unnamed, they will be placed at random geographic
positions.

Branch lengths are after the ":". Branch lengths are not required for the initial input tree, as the program will calculate them.

Taxon names can be any length, however, keeping them at 10 characters makes the interaction with PHYLIP programs simpler.

Taxa names in the geography section that are followed by a "?" are considered unfixed in their geographic position. The user can
move unfixed nodes in the geographic display. It is useful to differentiate between sampled populations, which come from specific
locations, and ancestral nodes, which have postulated positions. Fixed versus unfixed can also be modified in the geographic display.

Positive latitudes are north of equator, and positive longitudes are east of Greenwich. Spaces or tabs should be used to separate the
columns.

6.) Matrices

This program loads PHYLIP style matrices (Felsenstein?s style of matrices). These are square matrices, and they can be symmetric or asymmetric.

Here is an example matrix file:

5 Dispersal

BC001xxxxx 0.0 302.04745 251.13564 267.21964 93.90344 

BT008xxxxx 302.0475 0.0 121.93367 138.01767 315.27008 

BV011xxxxx 251.13564 121.93367 0.0 87.105835 264.35828 

BM005xxxxx 267.2196 138.01767 87.105835 0.0 280.44226 

BH004xxxxx 93.90344 315.27008 264.35825 280.44226 0.0 

5 Linear

BC001xxxxx 0.0 114.089584 192.9225 250.44585 93.26711 

BT008xxxxx 114.089584 0.0 80.58466 136.3875 92.09314 

BV011xxxxx 192.9225 80.58466 0.0 64.216354 143.21759 

BM005xxxxx 250.44585 136.3875 64.216354 0.0 207.37762 

BH004xxxxx 93.26711 92.09314 143.21759 207.37762 0.0 

Parts of File:
Number of Matrices (unnecessary if only one)
NumberOfTaxa MatrixName
TaxaName d1 d2 d3 d4
etc.

Notes:
Matrices are not required to have names, but it makes it much simpler to keep track of them if they have names.
Taxon names can be any length, however, keeping them at 10 characters makes the interaction with PHYLIP programs simpler.


7.) Matrix Graphing

Why graph the matrices?

This provides a quick way to examine the relationship between two distance matrices. Outliers may also be examined.

How to make a scatter plot?

-Make sure matrices are available for analysis, if not go to File|Open Matrix and select a matrix file.

-Select the matrix to be plotted along the X Axis from the X Axis menu.

-Select the matrix to be plotted along the Y Axis from the Y Axis menu.

-Clicking on a point will provide information about the point at the top of the scatter plot.

-To zoom in on region of the plot, drag the mouse over the region of interest.

-To reset the graph to the original image hit Shift-R.



8.) Results Table

What is the results table?

-It is a simple spreadsheet formating of the results. The results can be output to the results table, and then they can be saved to a spreadsheet readable file.

How do you direct output to the results table?

- Once the results table is open, output is directed there. The table is opened by selecting Window|Results Table.

How you open and save results tables?

- The table can be saved by selecting File|Save Results. An old table can be open by selecting File|Load Results.

How do you sort results?

- The results can be sorted by clicking on the header.


9.) Results Editor

What is the Results Editor?

-The results editor is the center of analysis and jumping off point for working with the geographical displays. Trees and matrices can be loaded and analyzed in the results editor. When beginning this program you will always start in the results editor.

How to open your tree from the Results Editor?

-Go to File|Open Tree, and then select your tree.

How to open matrices from Results Editor?

-Go to File|Open Matrices, and then select your matrix.

How to convert a tree into a distance matrix?

-Go to Analysis|Tree to Matrix

-Choose a tree and then choose a matrix. Choose new if you would like to give it a new name, and then enter the matrix name below.

-Select the type of nodes to be included in the matrix. These should be the same nodes for which there is other data. Hypothetical ancestral nodes are often left out of the matrix, although they are used to calculate the dispersal routes.

-Select linear distance in order to calculate the linear geographic distance between the nodes, while ignoring the dispersal routes indicated by the tree.

-Hit the Run button.

How to correlate matrices with one another?

-Go to Analyze|Matrix.

-Select the Y and X1 matrices. Currently you have to do Pearson correlations, and it is best of sort the rows and columns so that the same taxa are being compared in both analyses.

-To carry out a partial correlation, select a X2 matrix, and select the Partial Correlation checkbox.

-Set the number of repetitions for the permutation tests by entering a valid number above 0.

-Hit the Run button.