Merge branch 'master' into fix/HS6986/MorphMaxVNotZ

Author: bqminh

doc/Command-Reference.md

@@ -1,8 +1,8 @@
 ---
 layout: userdoc
 title: "Command Reference"
-author: Hector Banos, Diep Thi Hoang, Dominik Schrempf, Heiko Schmidt, Jana Trifinopoulos, Minh Bui, Thomas Wong, Nhan Ly-Trong
-date:    2025-03-28
+author: Hector Banos, Diep Thi Hoang, Dominik Schrempf, Heiko Schmidt, Jana Trifinopoulos, Minh Bui, Thomas Wong, Nhan Ly-Trong, Hiroaki Sato
+date:    2025-05-30
 docid: 19
 icon: book
 doctype: manual
@@ -295,7 +295,7 @@ The following `MODEL`s are available:
 | Protein    | Mixture models: C10, ..., C60 (CAT model) ([Lartillot and Philippe, 2004]), EX2, EX3, EHO, UL2, UL3, EX_EHO, LG4M, LG4X, CF4. See [Protein models](Substitution-Models#protein-models) for more details. |
 | Codon      | MG, MGK, MG1KTS, MG1KTV, MG2K, GY, GY1KTS, GY1KTV, GY2K, ECMK07/KOSI07, ECMrest, ECMS05/SCHN05 and combined empirical-mechanistic models. See [Codon models](Substitution-Models#codon-models) for more details. |
 | Binary     | JC2, GTR2. See [Binary and morphological models](Substitution-Models#binary-and-morphological-models) for more details. |
-| Morphology | MK, ORDERED. See [Binary and morphological models](Substitution-Models#binary-and-morphological-models) for more details. |
+| Morphology | MK, (GTRX), ORDERED. WARNING: GTRX (which can also be invoked as GTR) can only be applied to data with non-arbitrary state labels (e.g., recoded amino acids [for practical application, see [Najle et al., 2023]; [xgrau/recoded-mixture-models]] and certain types of genomic information) and should not be used for general morphological characters (transformational morphological characters; for the term, see [Sereno, 2007]). See [Binary and morphological models](Substitution-Models#binary-and-morphological-models) for more details. |
 
 The following `FreqType`s are supported:
 
@@ -802,4 +802,7 @@ The first few lines of the output file example.phy.sitelh (printed by `-wslr` op
 [Strimmer and von Haeseler, 1997]: http://www.pnas.org/content/94/13/6815.long
 [Yang, 1994]: https://doi.org/10.1007/BF00160154
 [Yang, 1995]: http://www.genetics.org/content/139/2/993.abstract
+[Najle et al., 2023]: https://doi.org/10.1016/j.cell.2023.08.027
+[xgrau/recoded-mixture-models]: https://github.com/xgrau/recoded-mixture-models
+[Sereno, 2007]: https://doi.org/10.1111/j.1096-0031.2007.00161.x
 

doc/Substitution-Models.md

@@ -2,7 +2,7 @@
 layout: userdoc
 title: "Substitution Models"
 author: Hector Banos, Cuong Cao Dang, Heiko Schmidt, Jana Trifinopoulos, Minh Bui, Nhan Ly-Trong, Hiroaki Sato
-date:    2024-05-27
+date:    2024-05-30
 docid: 10
 icon: book
 doctype: manual
@@ -360,15 +360,26 @@ Binary and morphological models
 
 The binary alignments should contain state `0` and `1`, whereas for morphological data, the valid states are `0` to `9` and `A` to `V`.
 
-| Model   | Explanation |
-|---------|------------------------------------------------------------------------|
-| JC2     | Jukes-Cantor type model for binary data.|
-| GTR2    | General time reversible model for binary data.|
-| MK      | Jukes-Cantor type model for morphological data.|
-| ORDERED | Allowing exchange of neighboring states only.|
+| Model      | Explanation |
+|------------|------------------------------------------------------------------------|
+| JC2        | Jukes-Cantor type model for binary data.|
+| GTR2       | General time reversible model for binary data.|
+| MK         | Jukes-Cantor type model for morphological data with equal rates.|
+| GTRX (GTR) | General time reversible model for morphological (or rather, multistate; **see the warning below**) data with unequal rates.|
+| ORDERED    | Allowing exchange of neighboring states only.|
+
+Except for `GTR2` that has unequal state frequencies, all other models have equal state frequencies. Users can change how state frequencies are modeled in morphological models by appending `+FQ`, `+F`, `+F{...}`, or `+FO`.
 
-Except for `GTR2` that has unequal state frequencies, all other models have equal state frequencies.
+> **WARNING**: Models with unequal rates and/or frequencies (e.g., `GTR2+FO`, `MK+FO`, `GTRX+FQ`, `GTRX+FO`) should not be applied to general morphological characters (transformational morphological characters; for the term, see [Sereno, 2007]) as their state labels are fundamentally arbitrary. These models are for data with non-arbitrary state labels (e.g., recoded amino acids [for practical application, see [Najle et al., 2023]; [xgrau/recoded-mixture-models]] and certain types of genomic information). For morphological data, it is the common practice to apply the `MK+FQ+ASC` model (or for ordered [additive] characters `ORDERED+FQ+ASC`) (for `+ASC`, see below) with or without rate heterogeneity across characters parameters.
 
+> **WARNING**: If you use `GTRX` for your multistate data, because of its sometimes very great number of free parameters, please make sure your data are sufficiently large and always test for model fit.
+
+
+> **TIP**: Recent studies have indicated that applying a single morphological model to morphological data with heterogeneity of state space among characters may not be appropriate ([Khakurel et al., 2024]; [Mulvey et al., 2025]; [Huang, 2025 preprint]), and users may need to partition data by the number of states in each character before analyzing them in IQ-TREE. For information on how to analyze partitioned morphological data in IQ-TREE and some caveats about it, please refer to [davidcerny/GEOS26100-Fall2022], https://davidcerny.github.io/post/teaching_revbayes/, [Černý & Simonoff (2023)], and [ej91016/MorphoParse].
+{: .tip}
+
+> **TIP**: For binary morphological characters where `0`s represent ancestral conditions and `1`s represent derived conditions, mainly neomorphic (`absent`/`present`) morphological characters (for the term, see [Sereno, 2007]), allowing asymmetrical frequencies in models would make sense (see e.g. [Pyron, 2017]; [Sun et al., 2018]; https://ms609.github.io/hyoliths/bayesian.html). This can be achieved in IQ-TREE, for example, by using the `GTR2` model.
+{: .tip}
 
 >**TIP**: If morphological alignments do not contain constant sites (typically the case), then [an ascertainment bias correction model (`+ASC`)](#ascertainment-bias-correction) should be applied to correct the branch lengths for the absence of constant sites.
 {: .tip}
@@ -462,5 +473,15 @@ Users can fix the parameters of the model. For example, `+I{0.2}` will fix the p
 [Yang, 1995]: http://www.genetics.org/content/139/2/993.abstract
 [Yang et al., 1998]: http://mbe.oxfordjournals.org/content/15/12/1600.abstract
 [Zharkikh, 1994]: https://doi.org/10.1007/BF00160155
-
+[Sereno, 2007]: https://doi.org/10.1111/j.1096-0031.2007.00161.x
+[Pyron, 2017]: https://doi.org/10.1093/sysbio/syw068
+[Sun et al., 2018]: https://doi.org/10.1098/rspb.2018.1780
+[xgrau/recoded-mixture-models]: https://github.com/xgrau/recoded-mixture-models
+[Najle et al., 2023]: https://doi.org/10.1016/j.cell.2023.08.027
+[Khakurel et al., 2024]: https://doi.org/10.1093/sysbio/syae033
+[Mulvey et al., 2025]: https://doi.org/10.1093/sysbio/syae055
+[Huang, 2025 preprint]: https://doi.org/10.1101/2025.04.22.650124
+[ej91016/MorphoParse]: https://github.com/ej91016/MorphoParse
+[davidcerny/GEOS26100-Fall2022]: https://github.com/davidcerny/GEOS26100-Fall2022
+[Černý & Simonoff (2023)]: https://doi.org/10.1038/s41598-023-35784-3
 

workshop/index.md

@@ -11,7 +11,7 @@ Throughout the year, members of IQ-TREE development team teach workshops on mole
 
 | Date |  Course Name and Materials | Location | Instructor |
 |------|---------------|----------------------------|-------------|
-| May 22 - Jun 1, 2025 | [Workshop on Molecular Evolution](https://molevolworkshop.github.io), [IQ-TREE 3 tutorial](molevol_tutorial2025) | Marine Biological Laboratory, Woods Hole, USA | Course Assistants |
+| May 22 - Jun 1, 2025 | [Workshop on Molecular Evolution](https://molevolworkshop.github.io), [IQ-TREE 3 tutorial](molevol_tutorial2025) | Marine Biological Laboratory, Woods Hole, USA | Hanon Solomon McShea |
 
 ### Past Workshops
 
@@ -21,6 +21,7 @@ IQ-TREE was taught as part of the following workshops:
 |------|---------------|----------------------------|-------------|
 | Aug 4-9, 2024 | [28th Bioinformatics Workshop on Virus Evolution and Molecular Epidemiology (VEME)](https://veme.climade.health/) | Brasilia, Brazil | Heiko Schmidt |
 | Jul 15-19, 2024 | [Croucher Summer Course on Virus Evolution and Epidemiology](https://projects.croucher.org.hk/summer-courses/virus-evolution-and-epidemiology) | Hongkong | Heiko Schmidt |
+| May 24 - Jun 3, 2024 | [Workshop on Molecular Evolution](https://molevolworkshop.github.io), IQ-TREE 2 tutorial | Marine Biological Laboratory, Woods Hole, USA | Blake Fauskee |
 | May 26 - Jun 5, 2023 | [Workshop on Molecular Evolution](https://molevolworkshop.github.io), [IQ-TREE 2 tutorial](molevol2023) | Marine Biological Laboratory, Woods Hole, USA | Bui Quang Minh |
 | Aug 20-25, 2023 | [27th Bioinformatics Workshop on Virus Evolution and Molecular Epidemiology (VEME)](https://veme.climade.health/27th-international-bioinformatics-workshop-on-virus-evolution-and-molecular-epidemiology-veme/) | Stellenbosch, South Africa | Heiko Schmidt |
 | July 27-29, 2022 | [IQ-TREE workshop tutorial](sydney2022) | [13th Sydney Phylogenetics Workshop](https://meep.sydney.edu.au/workshops/), Online | Bui Quang Minh |