commit dadb6a4d88f1f035c95e60929554ba58bccf4760
Author: Florent Chuffart <florent.chuffart@ens-lyon.fr>
Date:   Fri Jul 11 16:43:38 2014 +0200

    Natively compute dyad shift an common_wp_pvalue in align_inter_strain_nucs

diff --git a/doc/sphinx_doc/tuto.rst b/doc/sphinx_doc/tuto.rst
index 3d996fa..4201ca8 100644
--- a/doc/sphinx_doc/tuto.rst
+++ b/doc/sphinx_doc/tuto.rst
@@ -11,8 +11,28 @@ script `main.r` that extracts information (nucleosome position and indicators)
 from the dataset.
 
 
-Dataset and Configuration File
-------------------------------
+Python and R Common Configuration File
+--------------------------------------
+
+First of all we define in one place some configuration variables that will be launch by python and R scripts. This file is **configurator.py**. The execution of this python script dumps variables into the **nucleo_miner_config.json** that will be launch by both kind of scriopts (R and puython).
+
+To do this launch at the root of your project the following command line:
+
+.. code:: bash
+
+  python src/current/configurator.py
+  
+
+$$$ other python script to describe:
+- libcoverage.py
+- wf.py
+
+
+
+
+
+Dataset and Configuration Variables
+-----------------------------------
 
 We want to compare nucleosomes of 3 yeast strains: 
 
@@ -29,7 +49,7 @@ markers:
 - H3K14ac
 - H4K12ac
 
-In order to simplify the design of exeriment, we considere Mnase as a marker. 
+In order to simplify the design of experiment, we considere Mnase as a marker. 
 For each couple `(strain, marker)` we perform 3 replicates. So, theoritically 
 we should have `3 * (1 + 5) * 3 = 54` samples. In practice we only obtain 2 
 replicates for `(YJM, H3K4me1)`. Each one of the 53 samples is indentify by a 
@@ -236,11 +256,11 @@ id  Illumina reads  aligned and filtred reads  ratio   `.bed` file size  TF inpu
 55  52424414        47117107                   89,88%  3811 Mo           119 Mo              1477  s.
 ==  ==============  =========================  ======  ================  ==================  ================  
 
-For some reasons (manipulation efficency, e.g. PCR...), we remove samples 33, 45, 48 and 55.
+For some reasons (manipulation efficiency, e.g. PCR...), we remove samples 33, 45, 48 and 55.
 
 
 Run TemplateFilter on Mnase Samples
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Finally, for each sample we perfome TemplateFilter analysis. 
 
@@ -291,15 +311,9 @@ Inferring Nucleosome Position and Extracting Read Counts
 
 
 
-This preprocessing step consists in the 4 main steps embed in the `wf.py` and 
-described bellow. As a preamble, this script computes `samples` `samples_mnase` 
-and `strains` that will be used along the 4 steps.
+The second part of the tutorial uses `R` (http://http://www.r-project.org). It consists in a set of R scripts taht will be sourced in an R console launched at the root of your project. the R srcipts are:
 
-
-The second part of the tutoriel use `R` (http://http://www.r-project.org). It 
-consists in the following main steps:
-
-  - compute_rois.R
+  - headers.R
   - extract_maps.R
   - compare_common_wp.R
   - split_samples.R
@@ -307,24 +321,98 @@ consists in the following main steps:
   - get_size_factors  
   - launch_deseq.R
 
-Computing Common Genome Region Between Strains
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The Script headers.R
+^^^^^^^^^^^^^^^^^^^^
+
+The script header.R is included in each other scripts. It is in charge of: 
+
+  - launching libraries used in thes scripts
+  - launching configuration (design, strain, marker...)
+  - computing and caching CURs
+
+In your R console, run the following command line:
 
 .. code:: bash
 
-  R CMD BATCH src/current/compute_rois.R
+  R CMD BATCH src/current/header.R
+
+
+The Script extract_maps.R
+^^^^^^^^^^^^^^^^^^^^^^^^^
+This script is in charge of extracting Maps for well positioned and fuzzy nucleosomes. First of all, this script computed intra and inter strain nucleosome maps for each CUR. This step is executed in parallel on many cores using the BoT library. Next, it collects results and produces well positioned, fuzzy and UNR maps.
+
+The well-positioned map for BY is collected in the result directory and is called **BY_wp.tab**. It is composed of following columns:
+
+ - chr, the number of the chromosome 
+ - lower_bound, the lower bound of the nucleosome
+ - upper_bound, the upper bound of the nucleosome 
+ - cur_index, index of the CUR
+ - index_nuc, the index of the nucleosome in the CUR
+ - wp, 1 if it is a well positioned nucleosome, 0 else
+ - nb_reads, the number of reads that supports this nucleosome
+ - nb_nucs, the number of TemplateFilter nucleosome across replicates (= the number of replicates if it is a well-positioned nucleosome)
+ - llr_1, for a well-positioned nucleosome, it is the LLR1 between the first and the second TemplateFilter nucleosome.
+ - llr_2, for a well-positioned nucleosome, it is the LLR1 between the second and the first TemplateFilter nucleosome.
+ - wp_llr, for a well-positioned nucleosome, it is the LLR2 overall TemplateFilter nucleosomes.
+ - wp_pval, for a well-positioned nucleosome, it is the p-value chi square test obtained with the LLR2 (**1-pchisq(2.LLR2, df=4)**)
+ - dyad_shift, for a well-positioned nucleosome, it is shift between the two extreme TemplateFilter nucleosome dyad positions. 
+
+The fuzzy map for BY is collected in the result directory and is called **BY_fuzzy.tab**. It is composed of following columns:
+
+ - chr, the number of the chromosome 
+ - lower_bound, the lower bound of the nucleosome
+ - upper_bound, the upper bound of the nucleosome 
+ - cur_index, index of the CUR
+
+The common well-position map for BY and RM strains is collected in the result directory and is called **BY_RM_common_wp.tab**. It is composed of following columns:
+
+ - cur_index, the index of the CUR
+ - index_nuc_BY, the index of the BY nucleosome in the CUR
+ - index_nuc_RM,the index of the RM nucleosome in the CUR
+ - llr_score, the LLR3 score between th eBy and RM nucleosomes
+ - common_wp_pval,  the p-value chi square test obtained with the LLR3 (**1-pchisq(2.LLR3, df=2)**)
 
+The common UNR map for BY and RM strains is collected in the result directory and is called **BY_RM_common_unr.tab**. It is composed of following columns:
 
-Extracting Maps for Well Positionned and Fuzzy Nucleosomes
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ - cur_index, the index of the CUR
+ - index_nuc_BY, the index of the BY nucleosome in the CUR
+ - index_nuc_RM,the index of the RM nucleosome in the CUR
+
+To execute this script, run the following command line in your R console:
 
 .. code:: bash
 
-  R CMD BATCH src/current/extract_maps.R
+  source("src/current/extract_maps.R")
+
+
+The Script compare_common_wp.R
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This script is used to compare inter strain distances between common well-positioned nucleosomes. 
+
+For example, it compute the file **BY_RM_common_wp_diff.tab** that contains dyad shifts between two well-positioned nucleosomes. It is composed of following columns:
+ - cur_index, the index of the CUR
+ - index_nuc_BY, the index of the BY nucleosome in the CUR
+ - index_nuc_RM,the index of the RM nucleosome in the CUR
+ - llr_score, the LLR3 score between th eBy and RM nucleosomes
+ - common_wp_pval,  the p-value chi square test obtained with the LLR3 (**1-pchisq(2.LLR3, df=2)**)
+ - diff, the dyad shifts between two well-positioned nucleosomes
+
+It also translates well-positioned nucleosome maps from a strain to an other strain and stores it into a table. 
+
+For example, the file **results/2014-04/RM_wp_tr_2_BY.tab** contains RM well-positioned nucleosome translated into the BY genome referential. It is composed of following columns:
+
+ - strain_ref, the reference genome (in which positioned are defined)
+ - begin, the translated lower bound of the nucleosome
+ - end, the translated upper bound of the nucleosome
+ - chr, the number of chromosome for the reference genome (in which positioned are defined)
+ - length, the length of the nucleosome (could be negative)
+ - cur_index, the index of the CUR
+ - index_nuc, the index of the nucleosome in the CUR
+
 
 
-Compute Distance Between Well Positionned Nucleosomes 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+To execute this script, run the following command line in your R console:
 
 .. code:: bash
 
@@ -378,7 +466,7 @@ Each filename is under the form
 Where combi is in {BY_RM, BY_YJM, RM_YJM} for each strain combination, marker is 
 in {H3K4me1, H3K4me3, H3K9ac, H3K14ac, H4K12ac} for each post translational 
 histone modification and form is in {wp, fuzzy, wpfuzzy} considering well 
-positionned nucleosomes, fuzzy nucleosomes or both for SNEP computation.
+positioned nucleosomes, fuzzy nucleosomes or both for SNEP computation.
 
 
 
