diff --git a/doc/Advanced-Tutorial.md b/doc/Advanced-Tutorial.md index d64b32c..59d1e97 100644 --- a/doc/Advanced-Tutorial.md +++ b/doc/Advanced-Tutorial.md @@ -143,8 +143,7 @@ Choosing the right partitioning scheme --------------------------------------
-ModelFinder implements a greedy strategy ([Lanfear et al., 2012]) that starts with the full partition model and subsequentially -merges two genes until the model fit does not increase any further: +ModelFinder integrates the PartitionFinder algorithm ([Lanfear et al., 2012]) that starts with the full partition model and subsequently merges two partition subsets until the model fit does not increase any further: iqtree -s example.phy -p example.nex -m MFP+MERGE # for version 1.x change -p to -spp @@ -166,16 +165,31 @@ To resemble PartitionFinder and save time: iqtree -s example.phy -p example.nex -m TESTMERGEONLY # for version 1.x change -p to -spp +Starting with version 3.1.4, PartitionFinder supports the marginal Akaike Information Criterion (mAIC; [Susko et al., 2026]) as an optional criterion for partition merging. To apply PartitionFinder-mAIC: -To reduce the computational burden IQ-TREE implements the *relaxed hierarchical clustering algorithm* ([Lanfear et al., 2014]), which is invoked via `-rcluster` option: + iqtree -s example.phy -p example.nex -m MFP+MERGE -merit mAIC - iqtree -s example.phy -p example.nex -m MF+MERGE -rcluster 10 - # for version 1.x change -p to -spp +If you use PartitionFinder-mAIC in a publication, please cite: +> TBD +PartitionFinder implementation includes four merging algorithms, which differ in how thoroughly they search the space of partitioning schemes and how many pairs they merge per iteration: -to only examine the top 10% partition merging schemes (similar to the `--rcluster-percent 10` option in PartitionFinder). +| Algorithm | IQ-TREE Command | Description | Reference | +| ------------------------------------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | +| Greedy | `greedy` | At each iteration, evaluates all candidate subset pairs and merges the single pair that gives the best information-criterion score. | [Lanfear et al., 2012] | +| Relaxed hierarchical clustering | `rcluster` | At each iteration, evaluates only the top k% most similar candidate subset pairs and merges the best-scoring one. | [Lanfear et al., 2014] | +| Fast hierarchical relaxed clustering | `rclusterf` | At each iteration, evaluates only the top k% most similar candidate subset pairs and merges multiple compatible pairs at once. (IQ-TREE default). | [Lanfear et al., 2014] | +| k-means | `kmeans` | Estimates an evolutionary rate for each site, then iteratively clusters individual sites by rate using k-means, without relying on predefined data blocks. | [Frandsen et al., 2015] | +The following options control the details of the merging procedure: +| Option | Description | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `-merit` | Specify either `AIC`, `AICc`, `BIC` or `mAIC` for the partition merging criterion. *DEFAULT: `BIC`* | +| `--merge` | Specify either `rclusterf`, `rcluster`, `greedy` or `kmeans` algorithm. *DEFAULT: `rclusterf`* | +| `--rclusterf` | Specify the percentage of most similar candidate partition pairs retained for merging at each iteration (this automatically selects the fast relaxed clustering algorithm). *DEFAULT: 10* | +| `--rcluster` | Specify the percentage of most similar candidate partition pairs retained for merging at each iteration (this automatically selects the relaxed clustering algorithm). *DEFAULT: 10* | +| `--rcluster-max` | Specify the maximum number of most similar candidate partition pairs retained for merging at each iteration (only for the fast relaxed clustering and relaxed clustering algorithms). *DEFAULT: 10 × number of partitions in the full partition model* | Ultrafast bootstrapping with partition model -------------------------------------------- @@ -586,7 +600,9 @@ See [Command Reference](Command-Reference) for a complete list of all options av [Kishino et al., 1990]: https://doi.org/10.1007/BF02109483 [Kishino and Hasegawa, 1989]: https://doi.org/10.1007/BF02100115 [Lanfear et al., 2012]: https://doi.org/10.1093/molbev/mss020 +[Susko et al., 2026]: https://doi.org/10.1093/sysbio/syag013 [Lanfear et al., 2014]: https://doi.org/10.1186/1471-2148-14-82 +[Frandsen et al., 2015]: https://doi.org/10.1186/s12862-015-0283-7 [Lopez et al., 2002]: http://mbe.oxfordjournals.org/content/19/1/1.full [Nei et al., 2001]: https://doi.org/10.1073/pnas.051611498 [Seo et al., 2005]: https://doi.org/10.1073/pnas.0408313102