--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/pca.xml	Mon Apr 09 12:03:06 2012 -0400
@@ -0,0 +1,66 @@
+<tool id="gd_pca" name="PCA" version="1.0.0">
+
+  <command interpreter="python">
+    pca.py "$input" "$input.extra_files_path" "$output" "$output.extra_files_path"
+  </command>
+
+  <inputs>
+    <param name="input" type="data" format="wped" label="Dataset" />
+  </inputs>
+
+  <outputs>
+    <data name="output" format="html" />
+  </outputs>
+
+  <!--
+  <tests>
+    <test>
+      <param name="input" value="fake" ftype="wped" >
+        <metadata name="base_name" value="admix" />
+        <composite_data value="test_out/prepare_population_structure/prepare_population_structure.html" />
+        <composite_data value="test_out/prepare_population_structure/admix.ped" />
+        <composite_data value="test_out/prepare_population_structure/admix.map" />
+        <edit_attributes type="name" value="fake" />
+      </param>
+
+      <output name="output" file="test_out/pca/pca.html" ftype="html" compare="diff" lines_diff="2">
+        <extra_files type="file" name="admix.geno" value="test_out/pca/admix.geno" />
+        <extra_files type="file" name="admix.ind" value="test_out/pca/admix.ind" />
+        <extra_files type="file" name="admix.snp" value="test_out/pca/admix.snp" />
+        <extra_files type="file" name="coordinates.txt" value="test_out/pca/coordinates.txt" />
+        <extra_files type="file" name="explained.txt" value="test_out/pca/explained.txt" />
+        <extra_files type="file" name="par.admix" value="test_out/pca/par.admix" compare="diff" lines_diff="10" />
+        <extra_files type="file" name="PCA.pdf" value="test_out/pca/PCA.pdf" compare="sim_size" delta = "1000" />
+      </output>
+      
+    </test>
+  </tests>
+  -->
+
+  <help>
+**What it does**
+
+The users selects a set of data generated by the Galaxy tool to "prepare to look for population structure". The PCA tool runs a Principal Component Analysis on the input genotype data and constructs a plot of the top two principal components. It also reports the following estimates of the statistical significance of the analysis.
+
+1. Average divergence between each pair of populations.  Specifically, from the covariance matrix X whose eigenvectors were computed, we can compute a "distance", d, for each pair of individuals (i,j): d(i,j) = X(i,i) + X(j,j) - 2X(i,j).  For each pair of populations (a,b) now define an average distance: D(a,b) = \sum d(i,j) (in pop a, in pop b) / (\|pop a\| * \|pop b\|).  We then normalize D so that the diagonal has mean 1 and report it.
+
+2. Anova statistics for population differences along each eigenvector. For each eigenvector, a P-value for statistical significance of differences between each pair of populations along that eigenvector is printed.  +++ is used to highlight P-values less than 1e-06.  \*\*\* is used to highlight P-values between 1e-06 and 1e-03.  If there are more than 2 populations, then an overall P-value is also printed for that eigenvector, as are the populations with minimum (minv) and maximum (maxv) eigenvector coordinate. [If there is only 1 population, no Anova statistics are printed.] 
+
+3. Statistical significance of differences between populations. For each pair of populations, the above Anova statistics are summed across eigenvectors. The result is approximately chisq with d.o.f. equal to the number of eigenvectors. The chisq statistic and its p-value are printed. [If there is only 1 population, no statistics are printed.]
+
+We post-process the output of the PCA tool to estimate "admixture fractions".  For this, we take three populations at a time and determine each one's average point in the PCA plot (by separately averaging first and second coordinates).  For each combination of two center points, modeling two ancestral populations, we try to model the third central point as having a certain fraction, r, of its SNP genotypes from the second ancestral population and the remainder from the first ancestral population, where we estimate r.  The output file "coordinates.txt" then contains pairs of lines like
+
+projection along chord Population1 -> Population2
+  Population3: 0.12345
+
+where the number (in this case 0.1245) is the estimation of r.  Computations with simulated data suggests that the true r is systematically underestimated, perhaps giving roughly 0.6 times r.
+
+**Acknowledgments**
+
+We use the programs "smartpca" and "ploteig" downloaded from
+
+http://genepath.med.harvard.edu/~reich/Software.htm
+
+and described in the paper "Population structure and eigenanalysis". by Nick Patterson, Alkes L.Price and David Reich, PLoS Genetics, 2 (2006), e190.
+  </help>
+</tool>