Update Documentation (concept and input_output)

doc/source/concept.rst

@@ -4,46 +4,48 @@
 Substitution rate-adjustment strategy in a nutshell
 ===================================================
 
-To position ancient WGD events with respect to speciation events in a phylogeny, it is common practice to superimpose a paralog *K*:sub:`S` distribution for a species of interest with ortholog *K*:sub:`S` distributions between this species and other species to obtain a mixed plot. 
-However, when the lineages involved exhibit different substitution rates, the *K*:sub:`S` distributions are built on different *K*:sub:`S` scales and a direct comparison among them is likely to mislead the phylogenetic interpretation of WGD signatures or the divergence order.
+To position ancient whole-genome duplication (WGD) events with respect to speciation events in a phylogeny, it is common practice to superimpose a paralog *K*:sub:`S` distribution for a species of interest with ortholog *K*:sub:`S` distributions between this species and other species, resulting in a mixed paralog--ortholog *K*:sub:`S` plot. 
+However, when the lineages involved exhibit different substitution rates, the various *K*:sub:`S` distributions are built on different *K*:sub:`S` scales and a direct comparison among them is likely to mislead the phylogenetic interpretation of WGD signatures or order of divergences.
 
-``ksrates`` is an open-source tool offering a rate-adjustment strategy that brings all the distributions to a common *K*:sub:`S` scale by compensating for the synonymous substitution rate differences relative to one species. The final mixed plot produced by ``ksrates`` features adjustemnts in the position of the ortholog *K*:sub:`S` distributions that help in the clarification of WGD placement in the context of the provided phylogenetic tree.
+*ksrates* is an open-source tool offering a rate-adjustment strategy that brings all the distributions to a common *K*:sub:`S` scale by compensating for the differences in synonymous substitution rates relative to one focal species. The final mixed plot produced by *ksrates* features rate-adjusted positions of the ortholog *K*:sub:`S` distributions that help clarifying the placement of WGDs in the context of the provided phylogenetic tree.
 
-For more details about the rate-adjustment strategy, see our `preprint <https://www.biorxiv.org/content/10.1101/2021.02.28.433234v1>`__.
+For more detail about the methodology, please see our `preprint <https://www.biorxiv.org/content/10.1101/2021.02.28.433234v1>`__.
 
 
 .. _`explained_example`:
 
 Explained example
 =================
 
-This explained example studies the phylogenetic placement of WGD signatures present in oil palm (*Elaeis guineensis*) paralog *K*:sub:`S` distribution in the context of a small monocots phylogeny composed by the species of interest (oil palm), *Oryza sativa* (rice) and their outgroup *Asparagus officinalis* (asparagus). Such input tree is provided in Newick format: ``((palm, rice)), asparagus)``.
-From the perspective of oil palm history there are two divergence nodes (i.e. ortholog *K*:sub:`S` distributions) to be rate-adjusted, namely palm-rice and palm-asparagus.
+In this explained example use case the phylogenetic placement of WGD signatures present in oil palm's (*Elaeis guineensis*) paralog *K*:sub:`S` distribution is studied. This is done in the context of a small monocot phylogeny composed of the focal species (oil palm), *Oryza sativa* (rice) and their outgroup *Asparagus officinalis* (asparagus). The input tree in Newick format for this phylogeny is: ``((palm, rice)), asparagus)``. From the evolutionary perspective of oil palm there are two species divergence nodes: palm--rice and palm--asparagus.
 
-The detection of substituion rate differences makes use of principles of the relative rate test (REF) and requires therefore an outgroup species.
-The pipeline breaks down the tree into *trios* composed by the species pair of a ortholog distribution and the outgroup used for its rate-adjustment. The example tree gives only one trio, "palm, rice, asparagus", where palm-rice divergence will be rate-adjusted with outgroup asparagus.
+.. figure:: _images/tree.svg
+    :align: center
+    :width: 250
+    :alt: Input phylogenetic tree composed by oil palm, rice and asparagus as the outgroup.
+
+The detection of substitution rate differences among lineages and the decomposition of ortholog *K*:sub:`S` mode estimates into branch-specific contributions use methodology similar to relative rate testing and requires the help of an outgroup species.
+Therefore, *ksrates* breaks down the input tree into *trios* composed of the focal species, a diverged species and an outgroup species. The input tree in this examples defines only one such trio, ``palm, rice, asparagus``. Here the ortholog *K*:sub:`S` distribution of the palm--rice species divergence (or more specifically, its mode) will be rate-adjusted using asparagus as an outgroup.
 
 .. note ::
-    Palm-asparagus divergence has no outgroup in this tree and can't be adjusted; to be able to take it into account one should extend the phylogeny with one extra species that can function as their outgroup, e.g. *Spirodela polyrhiza*: ``(((palm, rice), asparagus), spirodela)``. 
-    By default, if more than one outgroup is available for a species pair, multiple rate-adjustments are performed and the mean among them is taken as consensus. For example, in the extended tree palm-rice would be adjusted both with ``asparagus`` and ``spirodela`` outgroups.
+    The palm--asparagus divergence has no outgroup in this tree and thus can't be rate adjusted; to be able to do so one would need to extend the phylogeny with one additional species that can function as their outgroup, e.g. *Spirodela polyrhiza*: ``(((palm, rice), asparagus), spirodela)``. 
+    By default, if more than one outgroup is available for a species pair, multiple rate-adjustments are performed and the mean among them is taken as consensus. For example, in the extended tree palm--rice would be adjusted both with ``asparagus`` and ``spirodela`` as the outgroup.
 
-The three ortholog *K*:sub:`S` distributions obtained from palm-rice-asparagus trio are approximated to their estimated mode (1.53 *K*:sub:`S`) with associated standard deviation (Figure 1; for more details please refer to Supplementary Materials, currently in preprint).
+The three ortholog *K*:sub:`S` distributions obtained from the ``palm, rice, asparagus`` trio are approximated to their estimated mode with associated standard deviation (Figure 1; for more details please refer to `Supplementary Materials <https://www.biorxiv.org/content/10.1101/2021.02.28.433234v1.supplementary-material>`__, currently in preprint).
 
-.. figure:: _images/ortholog_distribution_peak.svg
+.. figure:: _images/orthologs_distribution_trio.svg
     :align: center
-    :width: 350
-    :alt: The figure shows the bell-shaped ortholog KS distribution obtained for palm and rice approximated to a vertical line passing through the estimated mode (1.53 KS). A thin colored rectangular box behind this line highlights the associated standard deviation (0.01 KS).
+    :width: 800
 
-    The ortholog distribution for palm and rice is approximated to a vertical line passing through its esitmated mode (1.53 *K*:sub:`S`).
+    Figure 1: The three ortholog *K*:sub:`S` distributions for the ``palm, rice, asparagus`` trio. Their estimated mean mode is indicated by a black vertical line. A thin colored box ranges from one standard deviation (sd) below to one sd above the mean mode estimate.
 
-Through principles of the relative rate test the ortholog *K*:sub:`S` estimate between palm and rice (1.53 *K*:sub:`S`) is decomposed into the two branch-specific *K*:sub:`S` contributions: palm contributes with 0.365 while rice with 1.17. The difference between them suggests that palm has a much lower substitution rate than rice.
+Using methodology similar to relative rate testing the ortholog *K*:sub:`S` mode estimate between palm and rice (*K*:sub:`S`\=\1.53) is decomposed into the two branch-specific *K*:sub:`S` contributions: the palm branch contributes a low *K*:sub:`S` of 0.365 while the rice branch contributes a *K*:sub:`S` of 1.17. The considerable difference between them suggests that palm has a much lower synonymous substitution rate than rice.
 
-The ortholog *K*:sub:`S` estimate of palm-rice is then adjusted by rescaling it as twice the branch contribution of palm (*K*:sub:`S` --> 0.365 + 0.365 = 0.73). The position of the divergence line results then largely shifted towards left from 1.53 to 0.73 *K*:sub:`S` (Figure 2) and it is now adapted to the slower scale of palm paralog distribution. Interestingy, the rate-adjusted mixed plot offers a new interpretation for the placement of the older WGD signature located around 0.9 *K*:sub:`S`, from being palm-specific to be shared with rice and potentially other monocots.
+The ortholog *K*:sub:`S` mode estimate of palm--rice is then rate adjusted by rescaling it to twice the contribution of the palm branch (*K*:sub:`S` --> 2 * 0.365 = 0.73). The position of the (mode) divergence line thus largely shifts towards the left to the other side of the second WGD peak, from *K*:sub:`S`\=\1.53 to *K*:sub:`S`\=\0.73 (Figure 2)---it is now rate-adjusted to the *K*:sub:`S` scale of the paralog *K*:sub:`S` distribution of oil palm.
+The rate-adjusted mixed plot offers a different interpretation for the phylogenetic placement of the older WGD signature (located at a *K*:sub:`S` of around 0.9) than a naive mixed plot would: instead of suggesting the WGD to be a palm-specific event it is now suggested to be an event shared by both rice and palm. This new founding likely matches the proposed monocots *tau* WGD event.
 
 .. figure:: _images/mixed_palm_corrected.svg
     :align: center
     :width: 800
-    :alt: In this figure the mixed plot shows the rate-adjusted ortholog KS distribution for oil palm and rice as a vertical line superimposed to the paralog KS distribution of oil palm. The vertical line has been shifted towards left and has crossed a WGD peak from its right side to its left side, as highlighted by an arrow.
-
-    The ortholog *K*:sub:`S` estimate (red vertical line) has been shifted towards left after rate-adjustment, as highlighted by the red arrows starting from the original position and pointing at the new rate-adjusted position. 
 
+    Figure 2: Rate-adjusted mixed *K*:sub:`S` distribution plot. The rate-adjustment has shifted the ortholog *K*:sub:`S` estimate (red vertical line) towards the left, as indicated by the red arrow at the bottom starting from the original position and pointing to the new rate-adjusted position. 

doc/source/configuration.rst

@@ -82,7 +82,7 @@ The [PARAMETERS] section includes:
 
 * For ortholog divergence *K*:sub:`S`
 
-    * **num_bootstrap_iterations**: number of bootstrap iterations for mode/median estimation. [Default: 200]
+    * **num_bootstrap_iterations**: number of bootstrap iterations for mode estimation. [Default: 200]
     * **divergence_colors**: list of colors assigned to the divergence nodes: all divergence lines coming from the same divergence node share the same color. [Default: 8 colors]
 
 * For the ortholog *K*:sub:`S` distribution plots
@@ -206,4 +206,4 @@ This is an optional configuration file that contains several \"expert\" paramete
 * **max_mixture_model_iterations**: maximum number of EM iterations for mixture modeling. [Default: 300]
 * **max_mixture_model_components**: maximum number of components considered during execution of the mixture models. [Default: 5]
 * **max_mixture_model_ks**: upper limit for the *K*:sub:`S` range in which the exponential-lognormal and lognormal-only mixture models are performed. [Default: 5]
-* **extra_paralogs_analyses_methods**: flag to toggle the optional analysis of the paralog *K*:sub:`S` distribution with non default mixture model methods (see section :ref:`paralogs_analyses` and Supplementary Materials) [Default: "no"]
+* **extra_paralogs_analyses_methods**: flag to toggle the optional analysis of the paralog *K*:sub:`S` distribution with non default mixture model methods (see section :ref:`paralogs_analyses` and Supplementary Materials) [Default: "no"]