Optimization

Low-level optimizer classes for direct parameter optimization.

Site-Class Model Optimizers

M0Optimizer

class crabml.optimize.optimizer.M0Optimizer(alignment, tree, use_f3x4=True, optimize_branch_lengths=True)

Optimize parameters for M0 codon model.

This optimizer estimates: - kappa (transition/transversion ratio) - omega (dN/dS ratio) - branch lengths (individual or global scaling)

Using maximum likelihood estimation.

__init__(alignment, tree, use_f3x4=True, optimize_branch_lengths=True)

Initialize optimizer.

Parameters

alignmentAlignment

Codon alignment

treeTree

Phylogenetic tree

use_f3x4bool

Use F3X4 codon frequencies (True) or uniform (False)

optimize_branch_lengthsbool

Optimize individual branch lengths (True) or use global scaling (False)

compute_log_likelihood(params)

Compute negative log-likelihood for optimization.

Return type:

float

Parameters

paramsnp.ndarray

If optimize_branch_lengths is True:

[log(kappa), log(omega), log(branch1), log(branch2), …]

If optimize_branch_lengths is False:

[log(kappa), log(omega), log(branch_scale)]

Returns

float

Negative log-likelihood

optimize(init_kappa=2.0, init_omega=0.4, method='L-BFGS-B', maxiter=200)

Optimize parameters to maximize likelihood.

Return type:

Tuple[float, float, float]

Parameters

init_kappafloat

Initial kappa value

init_omegafloat

Initial omega value

methodstr

Optimization method (default ‘L-BFGS-B’)

maxiterint

Maximum number of iterations

Returns

tuple

(kappa, omega, log_likelihood) if optimize_branch_lengths is True Branch lengths are updated in the tree directly

M1aOptimizer

class crabml.optimize.optimizer.M1aOptimizer(alignment, tree, use_f3x4=True, optimize_branch_lengths=True, init_with_m0=True)

Optimize parameters for M1a (NearlyNeutral) codon model.

Estimates: - kappa (transition/transversion ratio) - omega0 (dN/dS for purifying class, constrained < 1) - p0 (proportion in purifying class) - branch lengths (individual or global scaling)

__init__(alignment, tree, use_f3x4=True, optimize_branch_lengths=True, init_with_m0=True)

Initialize M1a optimizer.

Parameters

init_with_m0bool

Initialize branch lengths by optimizing M0 first (default: True). This dramatically improves convergence.

compute_log_likelihood(params)

Compute negative log-likelihood for optimization.

Return type:

float

optimize(init_kappa=2.0, init_omega0=0.5, init_p0=0.7, method='L-BFGS-B', maxiter=200)

Optimize M1a parameters.

Return type:

Tuple[float, float, float, float]

M2aOptimizer

class crabml.optimize.optimizer.M2aOptimizer(alignment, tree, use_f3x4=True, optimize_branch_lengths=True, init_with_m0=True)

Optimize parameters for M2a (PositiveSelection) codon model.

Estimates: - kappa - omega0 (purifying, < 1) - omega2 (positive selection, > 1) - p0, p1 (proportions) - branch lengths

__init__(alignment, tree, use_f3x4=True, optimize_branch_lengths=True, init_with_m0=True)

Initialize M2a optimizer.

Parameters

init_with_m0bool

Initialize branch lengths by optimizing M0 first (default: True).

compute_log_likelihood(params)

Compute negative log-likelihood for optimization.

Return type:

float

optimize(init_kappa=2.0, init_omega0=0.5, init_omega2=2.0, init_p0=0.5, init_p1=0.3, method='L-BFGS-B', maxiter=200)

Optimize M2a parameters.

Return type:

Tuple[float, float, float, float, float, float]

M3Optimizer

class crabml.optimize.optimizer.M3Optimizer(alignment, tree, n_classes=3, use_f3x4=True, optimize_branch_lengths=True, init_with_m0=True)

Optimize parameters for M3 (Discrete) codon model.

Matches PAML’s codeml implementation exactly: - Parameter layout: [kappa, logit_p0..logit_p_{K-2}, omega_0..omega_{K-1}, log(branches)…] - Proportion transform: PAML’s f_and_x (softmax with implicit last class) - Bounds: kappa [1e-4, 999], logits [-99, 99], omegas [1e-6, 999] - Initialization: PAML’s GetInitialsCodon - Optimizer: L-BFGS-B (equivalent to PAML’s ming2) - Post-optimization: sortwM3 (sort omegas ascending)

__init__(alignment, tree, n_classes=3, use_f3x4=True, optimize_branch_lengths=True, init_with_m0=True)

compute_log_likelihood(params)

Compute negative log-likelihood.

PAML parameter layout: [kappa, logit_p0..logit_p_{K-2}, omega_0..omega_{K-1}, log(branch)…]

Return type:

float

optimize(init_kappa=2.0, init_omegas=None, init_proportions=None, method='L-BFGS-B', maxiter=500, n_restarts=1)

Optimize M3 parameters matching PAML’s codeml.

Uses L-BFGS-B (equivalent to PAML’s ming2) with PAML’s initialization formulas from GetInitialsCodon. By default uses a single run with random initialization (matching PAML). Set n_restarts > 1 for more robust optimization at the cost of speed.

Returns (kappa, omegas, proportions, log_likelihood)

Return type:

Tuple[float, list[float], list[float], float]

M7Optimizer

class crabml.optimize.optimizer.M7Optimizer(alignment, tree, ncatG=10, use_f3x4=True, optimize_branch_lengths=True, init_with_m0=True)

Optimize parameters for M7 (beta) codon model.

Estimates: - kappa (transition/transversion ratio) - p_beta (beta distribution shape parameter 1) - q_beta (beta distribution shape parameter 2) - branch lengths

__init__(alignment, tree, ncatG=10, use_f3x4=True, optimize_branch_lengths=True, init_with_m0=True)

Initialize M7 optimizer.

Parameters

init_with_m0bool

Initialize branch lengths by optimizing M0 first (default: True).

compute_log_likelihood(params)

Compute negative log-likelihood for optimization.

Return type:

float

optimize(init_kappa=2.0, init_p_beta=0.5, init_q_beta=0.5, method='L-BFGS-B', maxiter=200)

Optimize M7 parameters.

Return type:

Tuple[float, float, float, float]

M8Optimizer

class crabml.optimize.optimizer.M8Optimizer(alignment, tree, ncatG=10, use_f3x4=True, optimize_branch_lengths=True, init_with_m0=True)

Optimize parameters for M8 (beta & omega>1) codon model.

Estimates: - kappa (transition/transversion ratio) - p0 (proportion in beta distribution) - p_beta (beta shape parameter 1) - q_beta (beta shape parameter 2) - omega_s (omega for positive selection class, > 1) - branch lengths

__init__(alignment, tree, ncatG=10, use_f3x4=True, optimize_branch_lengths=True, init_with_m0=True)

Initialize M8 optimizer.

Parameters

init_with_m0bool

Initialize branch lengths by optimizing M0 first (default: True).

compute_log_likelihood(params)

Compute negative log-likelihood for optimization.

Return type:

float

optimize(init_kappa=2.0, init_p0=0.9, init_p_beta=0.7, init_q_beta=1.5, init_omega_s=2.5, method='L-BFGS-B', maxiter=200)

Optimize M8 parameters.

Return type:

Tuple[float, float, float, float, float, float]

M8aOptimizer

class crabml.optimize.optimizer.M8aOptimizer(alignment, tree, ncatG=10, use_f3x4=True, optimize_branch_lengths=True, init_with_m0=True)

Optimize parameters for M8a (beta & omega=1) codon model.

This is the null model for the M8a vs M8 likelihood ratio test. The only difference from M8 is that omega_s is fixed to 1.0 (not optimized).

Estimates: - kappa (transition/transversion ratio) - p0 (proportion in beta distribution) - p_beta (beta shape parameter 1) - q_beta (beta shape parameter 2) - branch lengths

Note: omega_s is FIXED to 1.0 (neutral), NOT optimized.

__init__(alignment, tree, ncatG=10, use_f3x4=True, optimize_branch_lengths=True, init_with_m0=True)

Initialize M8a optimizer.

Parameters

init_with_m0bool

Initialize branch lengths by optimizing M0 first (default: True).

compute_log_likelihood(params)

Compute negative log-likelihood for optimization.

Return type:

float

optimize(init_kappa=2.0, init_p0=0.9, init_p_beta=0.7, init_q_beta=1.5, method='L-BFGS-B', maxiter=200)

Optimize M8a parameters.

Return type:

Tuple[float, float, float, float, float]

Returns

tuple

(kappa, p0, p_beta, q_beta, log_likelihood) Note: omega_s is always 1.0 (not returned as it’s fixed)

Branch Model Optimizers

BranchModelOptimizer

Branch-Site Model Optimizers

BranchSiteModelAOptimizer