implement support for the iqtree rate heterogeneity models

[GavinHuttley]

The following points should be separate issues, happy for those to be created and the item checked of here. The new issues should all have the next milestone attached.

• attach a listing of the abbreviations as a tsv file to this issue: descriptions and citations for the different rate heterogeneity methods supported by iqtree2 @thomaskf
• define the syntax that iqtree2 supports for combining substitution model names with rate heterogeneity variants @thomaskf
• implement available_rate_heterogeneity() function analogous to available_models() @rmcar17
• implement enum for the abbreviations @rmcar17
• implement function to produce the full model specification, taking the substitution model enum and the rate heterogeneity enum and returning the iqtree2 compatible model specification @rmcar17
• connect the build_tree and fit_model functions to the above
• document the available_rate_heterogeneity() function

[thomaskf]

I am attaching a listing of the abbreviations as a tsv file to this issue: descriptions and citations for the different rate heterogeneity methods supported by iqtree2.
rhas.txt

[thomaskf]

To specify substitution models, state frequency and rate heterogeneity type. The general syntax is:

MODEL+FreqType+RateType

where MODEL is a model name, +FreqType (optional) is the frequency type and +RateType (optional) is the rate heterogeneity type.

The following MODELs are available:

DataType	MODEL names
DNA	JC, F81, K80, HKY, TN, TNe, K81, K81u, TPM2, TPM2u, TPM3, TPM3u, TIM, TIMe, TIM2, TIM2e, TIM3, TIM3e, TVM, TVMe, SYM, GTR
Amino acid	Blosum62, cpREV, Dayhoff, DCMut, EAL, ELM, FLAVI, FLU, GTR20, HIVb, HIVw, JTT, JTTDCMut, LG, mtART, mtMAM, mtREV, mtZOA, mtMet, mtVer, mtInv, Poisson, PMB, Q.bird, Q.insect, Q.mammal, Q.pfam, Q.plant, Q.yeast, rtREV, VT, WAG

The following FreqTypes are supported:

FreqType	Description
+F	Empirical state frequency observed from the data.
+FO	State frequency optimized by maximum-likelihood from the data. Note that this is with letter-O and not digit-0.
+FQ	Equal state frequency.

The following RateTypes are supported:

RateType	Description
+I	Allowing for a proportion of invariable sites.
+G	Discrete Gamma model (Yang, 1994) with default 4 rate categories. The number of categories can be changed with e.g. +G8.
+I+G	Invariable site plus discrete Gamma model (Gu et al., 1995).
+R	FreeRate model (Yang, 1995; Soubrier et al., 2012) that generalizes +G by relaxing the assumption of Gamma-distributed rates. The number of categories can be specified with e.g. +R6. DEFAULT: 4 categories
+I+R	invariable site plus FreeRate model.

Examples:

• DNA: GTR+FO+I+G, HKY+R5, K80
• Amino acid: GTR20+F+I+R10, LG+G

[rmcar17]

Thanks @thomaskf, working on the next steps! A couple of questions:

1. Does the order of the FreqType and RateType matter in the model string?
2. Does the order of, for instance, the I and G in RateType matter? For instance is +G+I valid?
3. Defaults? Is it F for FreqType? Nothing for RateType?

[thomaskf]

@rmcar17 Thanks! The answers to your questions are as follows:

1. Yes, the order does matter. The order must be MODEL+FreqType+RateType
2. The order of elements inside RateType does not matter. That means both +I+G and +G+I work (and, say R3, both +I+R3 and +R3+I work), although the users (and IQ-TREE) usually put +I before +G or +R when writing out the model.
3. Correct!

[rmcar17]

* [x]  implement enum for the abbreviations @rmcar17

As the rate heterogeneity things can be mixed and matched and parametised, I've gone for a class design pattern rather than an enum

[rmcar17]

We now support these features!