update doc

Author: bqminh

doc/Command-Reference.md

@@ -2,7 +2,7 @@
 layout: userdoc
 title: "Command Reference"
 author: 95438353+HectorBanos, Diep Thi Hoang, Dominik Schrempf, Heiko Schmidt, Jana Trifinopoulos, Minh Bui, Thomaskf, Trongnhan Uit
-date:    2024-05-16
+date:    2024-06-28
 docid: 19
 icon: book
 doctype: manual
@@ -330,16 +330,16 @@ Further options:
 
 | Option | Usage and meaning |
 |----------|------------------------------------------------------------------------------|
-| `--link-exchange-rates` | Turn on linked exchangeability estimation for a profile mixture model. Note that the model must have specified `GTR20` exchangeabilities for eg.`GTR20+C20+G`. This option also produces a nexus file `GTRPMIX.nex` with the exchangeability matrix obtained from the optimization. This file can be later used for phylogenetic inference with the use of the `-mdef` flag|
-| `--gtr20-model` | Specify the initial exchangeabilities for linked exchangeability estimation. Note that this must be used with `--link-exchange-rates.` |
+| `--link-exchange` | Turn on linked exchangeability estimation for a profile mixture model. Note that the model must have specified `GTR20` exchangeabilities for eg.`GTR20+C20+G`. This option also produces a nexus file `GTRPMIX.nex` with the exchangeability matrix obtained from the optimization. This file can be later used for phylogenetic inference with the use of the `-mdef` flag|
+| `--init-exchange` | Specify the initial exchangeabilities for linked exchangeability estimation. Note that this must be used with `--link-exchange`. |
 
 ### Example usages:
 
 * Estimate linked exchangeabilities for a protein alignment `prot.phy` under C60+G model and a guide tree `guide.treefile`, where optimization is initialized from LG exchangeabilities
 
-        iqtree -s prot.phy -m GTR20+C60+G --link-exchange-rates --gtr20-model LG -te guide.treefile
+        iqtree -s prot.phy -m GTR20+C60+G --link-exchange --init-exchange LG -te guide.treefile
 
->**NOTE**: For better and faster performance, read the [recommendations](Complex-Models#linked-gtr-exchangeabilities-models) provided in the Complex Models section.
+>**NOTE**: For better and faster performance, read the [recommendations](Estimating-amino-acid-substitution-models#estimating-linked-exchangeabilities) provided in the Estimating amino acid substitution models section.
 
 
 Rate heterogeneity

doc/Estimating-amino-acid-substitution-models.md

@@ -2,7 +2,7 @@
 layout: userdoc
 title: "Estimating amino acid substitution models"
 author: 95438353+HectorBanos, Cuongbb, Minh Bui, Thomaskf
-date:    2024-05-14
+date:    2024-06-28
 docid: 12
 icon: info-circle
 doctype: manual
@@ -172,14 +172,14 @@ To estimate a non-reversible model from a folder of alignments:
 Estimating linked exchangeabilities
 -----------------------------------
 
-Starting with version 2.3.1, IQ-TREE allows users to estimate linked exchangeabilities under [profile mixture models](Substitution-Models#protein-mixture-models).
+Starting with version 2.3.5, IQ-TREE allows users to estimate linked exchangeabilities under [profile mixture models](Substitution-Models#protein-mixture-models).
 
 To start with, we show an example:
 
-    iqtree2 -s <alignment> -m GTR20+C60+G4 --link-exchange-rates -te  <guide_tree> -me 0.99
+    iqtree2 -s <alignment> -m GTR20+C60+G4 --link-exchange -te  <guide_tree> -me 0.99
 
 Here, IQ-TREE applies a (freely-estimated) 20x20 rate matrix `GTR20` with the
-[profile mixture model](Substitution-Models#protein-mixture-models) `C60` (other model such as C10 can also be used) and Gamma rate heterogeneity across sites. The option `--link-exchange-rates` tells
+[profile mixture model](Substitution-Models#protein-mixture-models) `C60` (other model such as C10 can also be used) and Gamma rate heterogeneity across sites. The option `--link-exchange` tells
 IQ-TREE to link GTR20 rates across all 60 mixture classes: without this option
 IQ-TREE will estimate 60 GTR20 matrices!
 
@@ -195,7 +195,7 @@ This command will produce an output file with suffix `.GTRPMIX.nex`. This file c
     iqtree2 -s <alignment> -mdef <.GTRPMIX.nex file> -m GTRPMIX+C60+G4
 
 
-The optimizer in IQ-TREE by default initializes exchangeability rates to be all equal, which are the least biased but may make the subsequent optimization quite slow. If users have a good guess of the rate values, the option `--gtr20-model` can be used. For example, `--gtr20-model LG` will intialize the exchangeability to that
+The optimizer in IQ-TREE by default initializes exchangeability rates to be all equal, which are the least biased but may make the subsequent optimization quite slow. If users have a good guess of the rate values, the option `--init-exchange` can be used. For example, `--init-exchange LG` will intialize the exchangeability to that
 of the LG model before optimization. Choosing good starting values can make estimation considerably faster. Apart from LG, users can specify any matrix, including those defined by the `-mdef` option with a [NEXUS model file](Complex-Models#nexus-model-file). Another use of this option is to _test the robustness_ of the optimizer with different starting points.
 
 Note that the user can estimate exchangeabilities jointly with weights of the profiles, branch lengths, and rates. This can be very time-consuming. If the goal is to optimize exchangeabilities, one can fix the other parameters to reasonable estimates (for eg. fixing branch lengths and rates has been shown to perform adequately for the estimation of exchangeabilities).

doc/Frequently-Asked-Questions.md

@@ -2,7 +2,7 @@
 layout: userdoc
 title: "Frequently Asked Questions"
 author: Heiko Schmidt, Jana Trifinopoulos, Minh Bui, Rob Lanfear
-date:    2024-06-25
+date:    2024-06-29
 docid: 9
 icon: question-circle
 doctype: manual
@@ -75,10 +75,26 @@ How do I interpret ultrafast bootstrap (UFBoot) support values?
 ---------------------------------------------------------------
 <div class="hline"></div>
 
-The ultrafast bootstrap (UFBoot) feature (`-bb` option) was published in  ([Minh et al., 2013]). One of the main conclusions is, that UFBoot support values are more unbiased: 95% support correspond roughly to a probability of 95% that a clade is true. So this has a different meaning than the normal bootstrap supports (where you start to believe in the clade if it has >80% BS support). For UFBoot, you should only start to believe in a clade if its support is >= 95%. Thus, the interpretations are different and you should not compare BS% with UFBoot% directly. 
-
-Moreover, it is recommended to also perform the SH-aLRT test ([Guindon et al., 2010]) by adding `-alrt 1000` into the IQ-TREE command line. Each branch will then be assigned with SH-aLRT and UFBoot supports. One would typically start to rely on the clade if its SH-aLRT >= 80% and UFboot >= 95%. 
-
+The ultrafast bootstrap (UFBoot) feature (`-bb` option) was published in ([Minh et al., 2013]). 
+One conclusions from the __analysis of many gene trees__ is that UFBoot support values are
+more unbiased: 95% support correspond roughly to a probability of 95% that a
+clade is true. So this has a different meaning than the normal (more conservative) 
+bootstrap supports.
+For UFBoot, you should only start to rely on a branch if its support is >=
+95%. Thus, the interpretations are different and you should not compare BS% with
+UFBoot% directly.
+
+Moreover, it is recommended to also perform the SH-aLRT test ([Guindon et al., 2010]), 
+e.g., by adding `-alrt 1000` into the IQ-TREE command line. Each branch will
+then be assigned with SH-aLRT and UFBoot supports. One would be more confident 
+if a clade has its SH-aLRT >= 80% and UFboot >= 95%. 
+
+> NOTE: These recommendations only apply to single gene trees. If you reconstruct
+> a "concatenation" tree from many genes in a phylogenomic analysis, they do not
+> hold anymore. In fact, UFBoot supports and even the more conservative Felsenstein's 
+> bootstrap supports will tend to be 100% and there has been plenty of literature
+> about this issue. You are recommended to compute concordance factors for
+> any phylogenomic analysis.
 
 How does IQ-TREE treat gap/missing/ambiguous characters?
 ---------------------------------------------------------