RelaxClockAveraging

RelaxClockAveraging is a BEAST package for Bayesian averaging over strict, uncorrelated relaxed, and autocorrelated relaxed molecular-clock models. The model uses a shared branch-rate vector and mixture likelihoods so that clock-model uncertainty is sampled jointly with tree and substitution parameters.

The package supports direct BEAST XML use, BEAST3 typed/spec XML, a BEAUti clock-model template, and LPhy/LPhyBEAST XML generation.

Repository Layout

• mixture-beast: BEAST classes, operators, loggers, examples, and BEAUti template packaging.
• mixture-lphy: LPhy generators and functions for the mixture clock model.
• mixture-lphybeast: LPhyBEAST mappings from LPhy objects to BEAST XML.
• mixture-lphybeast-launcher: Maven launcher for .lphy -> XML conversion.
• mixture-beast/src/test/resources/mixture.beast/examples: maintained BEAST XML examples.
• mixture-beast/src/main/resources/mixture.beast/fxtemplates: BEAUti clock-model template (ships inside the module JAR).
• scripts: local BEAST3 validation and smoke-run helpers.

Requirements

• JDK 25.
• Maven.
• BEAST.base 2.8.0 beta5 or a compatible BEAST3 build.
• LPhy 1.8.0-beta1 and LPhyBEAST 2.0.0-SNAPSHOT for LPhyBEAST conversion.
• Optional: BEAGLE. If BEAGLE is unavailable, BEAST runs with the Java likelihood core.

If Maven cannot resolve lphybeast:2.0.0-SNAPSHOT, install the matching LPhyBEAST 2.0 snapshot into the local Maven repository first.

Build

Build and test from the repository root:

mvn -q test
mvn -q -DskipTests package

The BEAST package zip is written to:

mixture-beast/target/mixture-beast-0.1.0.zip

Install as a BEAST Package

On macOS, install the built package into the BEAST 2.8 package directory:

rm -rf "$HOME/Library/Application Support/BEAST/2.8/mixture"
PKG_DIR="$HOME/Library/Application Support/BEAST/2.8/ClockModelAveraging"
rm -rf "$PKG_DIR"
mkdir -p "$PKG_DIR"
ditto -x -k mixture-beast/target/mixture-beast-0.1.0.zip "$PKG_DIR"

The BEAST package is named ClockModelAveraging. The installed package contains version.xml, lib/mixture-beast-0.1.0.jar, examples/, and fxtemplates/SVSRelaxedClockTemplate.xml.

Developer Quick Run (no package install)

For local development, run BEAST or BEAUti directly against the compiled module via exec-maven-plugin, without building the release ZIP or installing it into the BEAST package directory. BEAST_PACKAGE_PATH is pointed at target/classes, so the package (including the BEAUti template) is picked up straight from the build output:

Run BEAST headless against a maintained example:

mvn -pl mixture-beast compile exec:exec -Dbeast.args="src/test/resources/mixture.beast/examples/mixture-typed.xml"

Run BEAUti, with the Mixture Clock templates available immediately under Clock Model:

mvn -pl mixture-beast compile exec:exec -Dbeast.module=beast.fx -Dbeast.main=beastfx.app.beauti.Beauti

XML examples live in mixture-beast/src/test/resources/mixture.beast/examples/ (see below); the BEAUti template lives in mixture-beast/src/main/resources/mixture.beast/fxtemplates/SVSRelaxedClockTemplate.xml (see BEAUti Template below).

BEAST XML Examples and Validation

Five complete XML examples are maintained under mixture-beast/src/test/resources/mixture.beast/examples/:

• mixture.xml: legacy-compatible full hierarchical mixture.
• mixture-typed.xml: BEAST3 typed/spec full hierarchical mixture.
• strict-typed.xml: fixed strict-clock baseline, no relaxed raw-rates machinery.
• ucln-fixed-typed.xml: fixed UCLN relaxed clock using the shared-rates implementation and fixed indicator 0.
• ac-fixed-typed.xml: fixed autocorrelated relaxed clock using the shared-rates implementation and fixed indicator 1.

The full mixture examples use the relaxed-clock switching operator schedule: IndicatorGibbsOperator, ACSubtreeUIncrementOperator, UCLDStdevNonCenteredOperator, ACSigma2NonCenteredOperator, and UCACSwitchBridgeOperator. The fixed relaxed-clock examples keep only the operators for their active relaxed-clock class. AlphaAnnealingOperator is implemented but intentionally excluded from the shipped examples because it requires an alpha-coupled mixture-likelihood setup.

Validate the examples:

scripts/beast3_validate_xml.sh mixture-beast/src/test/resources/mixture.beast/examples/mixture.xml
scripts/beast3_validate_xml.sh mixture-beast/src/test/resources/mixture.beast/examples/mixture-typed.xml
scripts/beast3_validate_xml.sh mixture-beast/src/test/resources/mixture.beast/examples/strict-typed.xml
scripts/beast3_validate_xml.sh mixture-beast/src/test/resources/mixture.beast/examples/ucln-fixed-typed.xml
scripts/beast3_validate_xml.sh mixture-beast/src/test/resources/mixture.beast/examples/ac-fixed-typed.xml

Run the examples:

scripts/beast3_run.sh -overwrite mixture-beast/src/test/resources/mixture.beast/examples/mixture.xml
scripts/beast3_run.sh -overwrite mixture-beast/src/test/resources/mixture.beast/examples/mixture-typed.xml
scripts/beast3_run.sh -overwrite mixture-beast/src/test/resources/mixture.beast/examples/strict-typed.xml
scripts/beast3_run.sh -overwrite mixture-beast/src/test/resources/mixture.beast/examples/ucln-fixed-typed.xml
scripts/beast3_run.sh -overwrite mixture-beast/src/test/resources/mixture.beast/examples/ac-fixed-typed.xml

Run any XML by path:

scripts/beast3_run.sh -overwrite /path/to/analysis.xml

Run the maintained short-chain example check:

SMOKE_CHAIN_LENGTH=2000 scripts/validate_beast3_examples.sh

The local scripts build the package from the checkout before invoking BEAST.

BEAUti Template

The BEAUti clock-model template is:

mixture-beast/src/main/resources/mixture.beast/fxtemplates/SVSRelaxedClockTemplate.xml

It is compiled into the module JAR at build time, so BEAST3/BEAUti discovers it automatically via module-path resource scanning — no separate install step is needed beyond installing the package (see above).

After installing the package zip, open BEAUti 3 / BEAST.base 2.8+ and select:

Clock Model -> Mixture Clock for full hierarchical averaging over strict vs relaxed clocks, with UCLN vs autocorrelated averaging inside the relaxed class.

Clock Model -> Mixture Clock (fixed UCLN) for a fixed UCLN relaxed clock with no model switching.

Clock Model -> Mixture Clock (fixed Autocorrelated) for a fixed autocorrelated relaxed clock with no model switching.

Use BEAUti's built-in Strict Clock for strict-only analyses. mixture-beast/src/test/resources/mixture.beast/examples/strict-typed.xml is supplied as a simple baseline XML example.

The full mixture template uses the same UC/AC clock-mixing operators as the full mixture examples. The fixed relaxed-clock templates use only their active-class operators.

Validate XML saved from BEAUti:

scripts/beast3_validate_xml.sh /path/to/saved.xml

LPhy to BEAST XML

The LPhyBEAST path generates BEAST3-valid XML from:

mixture-lphy/examples/test.lphy

Generate XML from LPhy:

mvn -q -pl mixture-lphybeast-launcher exec:exec \
  -Dlphybeast.args="convert --packagedir ../target/lphybeast-packages -o ../target/lphybeast-test.xml -l 2000 -le 100 ../mixture-lphy/examples/test.lphy"

The generated XML is written to:

mixture-lphy/target/lphybeast-test.xml

Validate and run the generated XML:

xmllint --noout mixture-lphy/target/lphybeast-test.xml
scripts/beast3_validate_xml.sh mixture-lphy/target/lphybeast-test.xml
scripts/beast3_run.sh -overwrite mixture-lphy/target/lphybeast-test.xml

The generated XML uses the BEAST3 typed/spec path for the custom mixture components, includes the same SVS relaxed-clock operators, and keeps simulation-only allocation variables out of the MCMC state.

Regression Checks

Before updating the package or opening a pull request, run the build commands, the short-chain example check, and the LPhyBEAST conversion/validation commands above. Warnings about missing BEAGLE JNI and BEAST operator tuning suggestions are not test failures.

Citation

Citation information will be added when available.

License

MIT - see LICENSE.txt.