diff --git a/doc/src/learn.md b/doc/src/learn.md index 8628cb59b7367280d965c1bbe3fb86ae1d1a104f..9a3a7b67995016fde0bae5663839ec3dfbd2bcf3 100644 --- a/doc/src/learn.md +++ b/doc/src/learn.md @@ -6,6 +6,46 @@ space is explored to maximize aphid likelihood. ## Heuristic starting point { #init } +If not every [initial parameter](./use.md#init) +has been specified by user, +aphid uses the following procedure to automatically choose initial parameters. + +*(this reuses notations from the [likelihood formula](./likelihood.md))* + +First, calculate the mean branches lengths among the selected trees: +\\[ + <!-- cmdrun cat ./preamble.mathjax--> + \begin{align} + m_a &= \frac{1}{G}\sum_g{a_g}\qquad\qquad + m_b = \frac{1}{G}\sum_g{b_g}\\\\ + m_c &= \frac{1}{G}\sum_g{c_g}\qquad\qquad + m_d = \frac{1}{G}\sum_g{d_g} + \end{align} +\\] + +Then, calculate the frequency of discordant topologies among the selected trees: +\\[ + \begin{align} + f_{ac} &= \frac{1}{G}\sum_g{𝟙(T_g = \ACB)}\\\\ + f_{bc} &= \frac{1}{G}\sum_g{𝟙(T_g = \BCA)} + \end{align} +\\] + +Then use these as default starting points: + +\\[ + \begin{align} + \tau_1 &= \theta \times \frac{m_a + m_b}{4} \\\\ + \tau_2 &= \tau_1 + \theta \times \frac{m_c + m_d}{4} \\\\ + \pils &= e^{2\frac{\tau_1 - \tau_2}{\theta}} \\\\ + \pac &= f_{ac} - \pils / 3 \\\\ + \pbc &= f_{bc} - \pils / 3 \\\\ + \pab &= 1 - \pac - \pbc \\\\ + \po &= 1 / |gt| + \end{align} +\\] + + ## Reparametrization { #transform } Exploring a constrained space is more difficult @@ -71,3 +111,7 @@ then here is the reparametrization formula: Instead of the constrained \\(𝜃\\), \\(𝜏_1\\), \\(𝜏_2\\) *etc.*, the concrete optimisation targets for aphid are the unconstrained \\(s_𝜃\\), \\(s_{𝜏_1}\\), \\(s_{𝛥𝜏}\\) *etc.* + +## Maximizing likelihood + +<!-- HERE: into BFGS + Wolfe --> diff --git a/doc/src/use.md b/doc/src/use.md index 7125d5cc4a66622404975670dac3f3d1d60c0479..0809ae8a8e0ea99c23f03cd7c6abd108c6b9cfe4 100644 --- a/doc/src/use.md +++ b/doc/src/use.md @@ -88,7 +88,7 @@ TODO: clarify (see the [geometry filter](preprocess.md#geometry)) -### The `[init]` table +### The `[init]` table { #init } This additional table can be set to specify starting point(s) for likelihood exploration.