Updates the docs to reflect new functionality. Fixes #7

StuntsPT · StuntsPT · commit 1e835a7f7f56 · 2018-03-09T14:45:54.000Z
diff --git a/docs/description.md b/docs/description.md
@@ -52,12 +52,10 @@ The average absolute difference between AAF<sub>present</sub> and AAF<sub>future
 
 The RONA method as implemented in *pyRona* is not performed exactly as the original from [Rellstab et al. 2016](doi.wiley.com/10.1111/mec.13889).
 
-Instead of relying on LFFM like the original, *pyRona* is instead prepared to get association data from the software [*Baypass*](http://www1.montpellier.inra.fr/CBGP/software/baypass/). The method can be red about in [Gautier 2015](https://www.ncbi.nlm.nih.gov/pubmed/26482796). Being able to use output from LFMM is also in the [future plans](https://github.com/StuntsPT/pyRona/issues/7).
-
-This means the instead of using allele frequencies, *pyRona* uses the normalized allele frequencies outputted by *Baypass*. This is in our opinion superior to using the allele frequencies directly, since it removes any potential effect of population structuring.
-
 Instead of ranking the environmental factors by *p*-value of the difference teste between present and future values, *pyRona* will calculate the RONA value for the "N" environmental variables ranked by the number of associated loci. By default "N" is 3, but *pyRona* can take any user provided value.
 
 *pyRona* offers an option to remove outliers before calculating the regression. This removal uses the ["Mahalanobis distance"](https://en.wikipedia.org/wiki/Mahalanobis_distance) to remove 0, 1 or "all" the outliers in the data. By default, no outlier removal is performed.
 
+In addition to relying on LFFM like the original, *pyRona* is also prepared to get association data from the software [*Baypass*](http://www1.montpellier.inra.fr/CBGP/software/baypass/). The method can be red about in [Gautier 2015](https://www.ncbi.nlm.nih.gov/pubmed/26482796). When *Baypass* results are provided as input, instead of using allele frequencies, *pyRona* uses the normalized allele frequencies calculated by *Baypass*. This is in our opinion superior to using the allele frequencies directly, since it removes any potential effect of population structuring.
+
 Finally, similar to the original method, *pyRona* provides an average RONA value for each selected environmental variable, but unlike the the original method,our implementation will calculate the average RONA weighted by the regression R² value. This means that associations with a lower regression coefficient will contribute less to the final RONA value than those with higher R² values.
diff --git a/docs/index.md b/docs/index.md
@@ -26,6 +26,7 @@ A python implementation of "Risk of non Adaptedness" method (with a bit of R too
 * [Method description](description.md)
 * [Usage](usage.md)
   * [Wrapping BayPass](baypass.md)
+  * [Wrapping LFMM](lfmm.md)
 * [Output](output.md)
 * [Citation](citation.md)
 * [Future Plans](future.md)
diff --git a/docs/install.md b/docs/install.md
@@ -30,7 +30,7 @@ Due to the way different Operating Systems handle dependencies specific instruct
 
 ## Important note
 
-Note that *pyRona* will also automatically install an *R* script called `Baypass_workflow.R` under `~/.local/bin` that can be used to automate the usage of the software *BayPass*, whose output can be used as input for *pyRona*. For more information on this script, please see the [baypass section](baypass.md).
+Note that *pyRona* will also automatically install two *R* scripts called `Baypass_workflow.R` and `LFMM_workflow.R` under `~/.local/bin` that can be used to automate the usage of the upstream software *BayPass* and *LFMM*, whose output can be used as input for *pyRona*. For more information on these scripts, please see the [baypass](baypass.md) and [LFMM](lfmm.md) sections.
 
 
 ## Alternative methods (AKA 'expert mode')
diff --git a/docs/lfmm.md b/docs/lfmm.md
@@ -0,0 +1,33 @@
+# Wrapping LFMM
+
+*pyRona* can take the output of *LFMM* as input to calculate the RONA values. Due to this, *pyRona* includes an `R` script named `LFMM_workflow.R` that can be used to automate and wrap *LFMM* analyses.
+Not that it is highly recommended that you give *LFMM*'s [manual](https://bcm-uga.github.io/lfmm/reference/index.html), [tutorial](https://bcm-uga.github.io/lfmm/articles/lfmm), and [paper](http://dx.doi.org/10.1093%2Fmolbev%2Fmst063) a through read before using this script.
+
+
+## LFMM_workflow.R
+
+This script will automate the workflow for the [LFMM](https://bcm-uga.github.io/lfmm/index.html)
+software by Olivier François and Kevin Caye, which is described in [this paper](http://dx.doi.org/10.1093%2Fmolbev%2Fmst063).
+It does **no error handling** of any kind, nor any logging. It just automates
+the procedures outlined in the manual with some degrees of freedom.
+Please be careful when using it. It may kill your kittens and/or burn your
+house down, but worst of all, it will tend to make you lazy regarding the inner
+workings of *LFMM*.
+The script takes no arguments, but all the variables you should need to edit
+are presented at the start of the script, coupled with a short description.
+
+
+### Variables
+
+In the beginning of the script there are several line with empty variables. You should fill in the correct values for your case in order to use it.
+Each option is pretty much self documented with both an explanation of what is expected and an example.
+
+
+### Functions
+
+The rest of the script is comprised of functions to wrap the LFMM functionality. You should not have to change anything here to get a complete run as all the parameters that are likely be changed can be from the "Variables" section.
+
+
+### Running the script
+
+Simply enter values for the variables at the beginning of the script and run it in R. It is recommended that you take a close look at the "PCA variance explained" plot to choose the best "K" to use, which will likely mean perform multiple runs.
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -6,6 +6,7 @@ pages:
     - 'Method description': 'description.md'
     - 'Usage': 'usage.md'
         - 'Wrapping BayPass': 'baypass.md'
+        - 'Wrapping LFMM': 'lfmm.md'
     - 'Output': 'output.md'
     - 'Citation': 'citation.md'
     - 'Future Plans': 'future.md'
diff --git a/docs/usage.md b/docs/usage.md
@@ -7,32 +7,56 @@ This section describes how to use *pyRona*. All options as of version 0.2.0 are
 * Getting help
     - Simply calling the program, or issuing the single argument `-h` will print all the available options on the console
 
+* Positional arguments:
+    - The first argument should be the name of the program whose results you wish to analyse. *pyRona* can take one of two options here:
+        - `baypass`:Process Baypass results
+        - `lfmm`:Process LFMM results
+
+    - Depending on which you choose, some of the other options will be different.
+
 * I/O options
-    - *pyRona* **requires** several files as input, that should be specified inn the following options:
-        - `-pc`: File containing current environmental variables (formatted as per *BayPass* input)
-        - `-fc`: File containing future environmental variables (formatted the same as the present conditions file)
-        - `-pop`: File with names of populations (one population per line)
-        - `-beta`: *BayPass* output "summary_betai"
-        - `-pij`: *BayPass* output "PIJ"
-    - Furthermore, *pyRona* also requires an output to be specified, for saving the RONA plot.
-        - `-out`: File where the plot will be saved. This option is extension aware, and entering the extension as "PDF", "SVG" or "PNG", will make *pyRona* save the plot in the respective format.
+    - *pyRona* **requires** several files as input, that should be specified in the following options:
+        - Common options to both *Baypass* and *LFMM*:
+            - `-pc`: File containing current environmental variables, formatted as per the upstream program input (*Baypass* or *LFMM*)
+            - `-fc`: File containing future environmental variables, formatted as per the upstream program input (*Baypass* or *LFMM*)
+            - `-out`: File where the plot will be saved. This option is extension aware, and entering the extension as "PDF", "SVG" or "PNG", will make *pyRona* save the plot in the respective format
+        - *Baypass* specific options:
+            - `-pop`: File with names of populations (one population per line)
+            - `-beta`: *BayPass* output "summary_betai"
+            - `-pij`: *BayPass* output "PIJ"
+        - *LFMM* specific options:
+            - `-assoc`: File containing a matrix of *p*-values as outputted by *LFMM*
+        - `-geno`: The input file used for *LFMM*. Should be in the *LFMM* format
+
 * Parameters
     - *pyRona* requires some parameters to be set in order to perform the analysis. These are:
-        - `-bf`: Bayes Factor threshold. This is the value above which associations are considered significant.
-        - `-covars`: [**optional**] Number of covars to calculate the RONA for (default: 3)
-        - `-outliers`: [**optional**] Number of outliers to remove - "0" skips outlier removal, "1" removes a maximum of 1 outlier (if there is one), "2" removes any number of markers considered outliers (default: 2)
-        - `-immutables`: Number of covariates to skip from the environmental variables file. Usefull to skip variables that are the same in te present covars and future covars file, such as latitude (default: 3).
-        - `-ronatype`: Defines the RONA is calculated. `absdiff` performs calculations as described in Rellstab et al. 2016 - using the absolute value of the differences, `diff` uses the differences without modulus, and `dist` accounts simply for the distance between the future condition and the trendline (default: `absdiff`).
+        - Common options to both *Baypass* and *LFMM*:
+            - `-covars`: [**optional**] Number of covars to calculate the RONA for (default: 3)
+            - `-outliers`: [**optional**] Number of outliers to remove - "0" skips outlier removal, "1" removes a maximum of 1 outlier (if there is one), "2" removes any number of markers considered outliers (default: 2)
+            - `-immutables`: Covariates to skip from the environmental variables file. Useful to skip variables that are the same in te present covars and future covars file, such as latitude (default: 1 2 3)
+            - `-ronatype`: Defines the RONA is calculated. `absdiff` performs calculations as described in Rellstab et al. 2016 - using the absolute value of the differences, `diff` uses the differences without modulus, and `dist` accounts simply for the distance between the future condition and the trendline (default: `absdiff`)
+        - *Baypass* specific options:
+            - `-bf`: Bayes Factor threshold. This is the value above which associations are considered significant
+        - *LFMM* specific options:
+            - `-P`: *p*-value threshold. This is the value below which associations are considered significant
+
 * Other options (**all optional**)
     - *pyRona* allows for setting some further miscellaneous options:
-        - `-no-plots`: Do not draw the individual regression plots.
-        - `-no-weighted-means`: Use this option if you wish to use *means* instead of *weighted means* for the RONA calculation.
+        - `-no-plots`: Do not draw the individual regression plots. This is the default, and you should set it to "0" or "False" to draw the individual plots
+        - `-no-weighted-means`: Set this option to "1" or "True" if you wish to use *means* instead of *weighted means* for the RONA calculation
+
+
+## Example runs:
+
+```
+pyRona baypass -pc Popfiles/ENVFILE -fc Popfiles/ENVFILE_rpc26 -beta Analyses/Baypass/mcmc_aux/Qsuber_GBS_07_loki_mcmc_aux_summary_betai.out -pij Analyses/Baypass/mcmc_aux/Qsuber_GBS_07_loki_mcmc_aux_summary_pij.out -pop Popfiles/popnames_single_GEO.txt -bf 15 -outliers 0 -out ~/Desktop/rpc26.pdf -covars 4
+```
 
+This command will execute *pyRona* set to analyse *Baypass* output using the input files specified by `-pc`, `-fc`, `-beta`, `-pij` and `-pop`, using the value `15` as the BF threshold, skipping outlier removal and calculating the RONA value for the most frequent 4 associated environmental variables. The plot will be saved as a PDF under `~/Desktop/rpc26.pdf`.
 
-## Example run:
 
 ```
-pyRona -pc Popfiles/ENVFILE -fc Popfiles/ENVFILE_rpc26 -be Analyses/Baypass/mcmc_aux/Qsuber_GBS_07_loki_mcmc_aux_summary_betai.out -pij Analyses/Baypass/mcmc_aux/Qsuber_GBS_07_loki_mcmc_aux_summary_pij.out -pop Popfiles/popnames_single_GEO.txt -bf 15 -outliers 0 -out ~/Desktop/rpc26.pdf -covars 4
+pyRona lfmm -pc ~/aa/present_covars.txt -fc ~/aa/RCP26_covars.txt -out ~/Desktop/LFMM_rpc26.pdf -P 0.01 -assoc ~/aa/scaled_lfmm_results.csv -geno ~/aa/qsuber.lfmm
 ```
 
-This command will execute *pyRona* using the input files specified by `-pc`, `-fc`, `-be`, `-pij` and `-pop`, using the value `15` as the BF threshold, skipping outlier removal and calculating the RONA value for the most frequent 4 associated environmental variables. The plot will be saved as a PDF under `~/Desktop/rpc26.pdf`.
+This command will execute *pyRona* set to analyse *LFMM* output using the input files specified by `-pc`, `-fc`, `-assoc` and `-geno`, using the value `0.01` as the *p*-value threshold, skipping outlier removal (default) and calculating the RONA value for the most frequent 3 associated environmental variables (default). The plot will be saved as a PDF under `~/Desktop/LFMM_rpc26.pdf`.
