Rate-matrix scaling

Scaling assigns a biological unit to every phylogenetic branch. PalantiR supports two distinct synonymous units, and code should name the intended one explicitly whenever the distinction matters.

Constructor input	Stored value	Meaning of one branch-length unit
`"synonymous"`, `"dS"`, or `"ds"`	`"dS"`	One neutral synonymous substitution per synonymous opportunity, equivalent to one neutral nucleotide substitution per site
`"synonymous-per-codon"`	`"synonymous-per-codon"`	One expected synonymous event per codon at stationarity
`"non-synonymous"`	`"non-synonymous"`	One expected amino-acid-changing event per codon at stationarity
`"standard"` or `"substitution"`	`"substitution"`	One expected substitution of any kind per codon at stationarity
`"none"`	`"none"`	No rate normalization

Since version 1.3.0, scaling_type = "synonymous" selects the dS gauge. Earlier PalantiR releases used that name for the event-count-per-codon gauge; that historical behavior remains available as "synonymous-per-codon".

use_genetic_code("Standard nuclear")
MutationSelection(..., scaling_type = "synonymous")            # dS
MutationSelection(..., scaling_type = "synonymous-per-codon")  # event count

The dS gauge

GY94

For GY94, PalantiR constructs the neutral generator $\widetilde Q^{(1)}$ by setting $\omega=1$. If $\pi$ is its stationary codon distribution, its total neutral rate is

\[ r_{\mathrm{tot}}^{(1)} = \sum_i \pi_i \sum_{j\ne i}\widetilde q_{ij}^{(1)}. \]

PalantiR divides the selected generator by $S_{dS}=r_{\mathrm{tot}}^{(1)}/3$. The neutral reference consequently has three substitutions per codon per dS unit, or one per nucleotide site. This denominator is independent of the selected $\omega$.

Let $N_S$ be the stationary synonymous flux of this dS-scaled neutral reference. On a stationary branch of length $D$, the expected synonymous count across $n$ codon sites is

\[ E[C_S] = nN_SD. \]

Thus histories recover the branch length as $\widehat D=C_S/(nN_S)$, rather than as synonymous events per codon. For the same neutral reference, the expected nonsynonymous count under GY94 is $E[C_A]=n\omega N_A D$, which gives the usual opportunity-corrected dN/dS.

Mutation–selection models

For mutation–selection models, PalantiR builds a mutation-only neutral reference by removing amino-acid fitness differences. All fitness profiles derived from the same nucleotide mutation model therefore share one neutral clock. A selected profile is not renormalized by its realized synonymous flux, which can change with codon composition or selection.

The model object reports neutral_total_rate, neutral_synonymous_rate, and synonymous_opportunities. The last quantity is $N_S$, the expected number of synonymous opportunities per codon per dS unit under the neutral reference. It also stores a per-state vector, dS_outflux, for time-heterogeneous rescaling. The canonical value recorded in model$scaling_type is "dS".

Event-count gauges

For an event class $A$, PalantiR computes the stationary flux

\[ S_A(Q,\pi)= \sum_i\pi_i\sum_{j\ne i}q_{ij} \mathbf 1\{i\rightarrow j\in A\}. \]

Dividing $Q$ by this flux makes a stationary branch of length one carry one expected event in $A$ per codon. This definition gives the "synonymous-per-codon", "non-synonymous", and "substitution" gauges. It is an event budget, rather than an opportunity-corrected evolutionary distance.

Time-heterogeneous branches

When a fitness profile, population size, or other model parameter changes on a branch, the inherited codon distribution is generally not stationary under the new generator. PalantiR therefore integrates the requested branch-length currency along the transient; it does not assume the destination model starts at equilibrium.

For dS, let $Q^0_{dS}$ be the neutral reference expressed in dS units and

\[ h_i^{dS}=\frac{1}{3}\sum_{j\ne i}(Q^0_{dS})_{ij}. \]

If the selected process enters the branch with distribution $p_0$ and runs for intrinsic time $\tau$, the exact rescaler chooses $\tau$ so that

\[ \int_0^\tau p_0^T e^{Qu}h^{dS}\,du =D\,(\pi_{\mathrm{dest}}^T h^{dS}), \]

where $D$ is the supplied branch length and $\pi_{\mathrm{dest}}$ is the destination model’s equilibrium distribution. The selected generator $Q$ still controls the substitution history; the neutral functional supplies only the clock used for the scalar time change. Consequently, dS scaling preserves neutral nucleotide time through a fitness or population-size shift without forcing one realized synonymous event per codon. Event-count gauges use the corresponding selected event-class outflux instead. See Temporal Heterogeneity Rescaling for the numerical implementation.

Choosing a gauge

Use dS scaling when tree lengths represent neutral nucleotide substitutions per site, including lengths estimated from noncoding sequence or fourfold degenerate positions, or when a branch or branch-site test is meant to compare nonsynonymous change against a fixed synonymous distance. Use "synonymous-per-codon" only when the desired input is a stationary expected number of synonymous events per codon. Use "substitution" or "non-synonymous" when the corresponding event count is the intended clock.

These gauges are not numerically interchangeable. At stationarity,

\[ Q_{dS}=N_SQ_{\mathrm{syn/codon}}, \qquad D=\frac{C_S}{nN_S}. \]

The engine-validation report tests both synonymous definitions directly, including GY94 and mutation–selection dS branches.