[walterxie]

Converts 12 BEAST 2 examples to BEAST 3. The full write-up is in MIGRATION-REPORT-batch2.md.

• Clocks: testRandomLocalClock, testRelaxedClock, testUCLNclock.json
• Tip dates / partitions: testTipDates, testTipDates2, testSRD06, testMultipleAlignments_randomTaxaOrder
• Simulators: testDirectSimulator, testDirectSimulator2, testDirectSimulatorHierarchical, testSeqGen, testSimulatedAlignment

Each file keeps the original's data, weights and loggers. A comment at the top of each file lists its proper priors and the changes made by the conversion.

Review requests

#	Request	Status
1	Proper priors, in both versions	✅ done
2	Start the slide at its tuned size	✅ done
3	Posterior comparison against 2.7.9	⏳ handled in a separate GitHub issue
4	Input<BranchRateModel> in SequenceSimulator / SimulatedAlignment	✅ done
5	Run the changed release scripts end to end	⏳ handled in a separate GitHub issue

Proper priors (BEAST 2 and BEAST 3)

This is a change to the model, made in both the BEAST 3 files and their BEAST 2 sources in legacy/. It follows #199 and BEAUti's defaults (#208):

• rates and sizes get LogNormal(M = 0, S = 8) in log space;
• kappa gets LogNormal(1, 1.25).

File	Parameter	2.7.8 original	Now
testRandomLocalClock	hky.kappa / popSize / rates	none (flat)	LogNormal(1, 1.25) / LogNormal(0, 8) / LogNormal(0, 8) on each rate
testRelaxedClock	hky.kappa / popSize / ucld.stdev	none (flat)	LogNormal(1, 1.25) / LogNormal(0, 8) / LogNormal(0, 8)
testUCLNclock.json	birthRate	Uniform(0, ∞)	LogNormal(0, 8)
testTipDates	hky.kappa / clockRate	OneOnX / none	LogNormal(1, 1.25) / LogNormal(0, 8)
testTipDates2, testSRD06	hky.kappa (SRD06: both partitions)	OneOnX	LogNormal(1, 1.25)
testMultipleAlignments	clockRate / popSize	OneOnX	LogNormal(0, 8)
testSimulatedAlignment	hky.kappa / popSize	none (flat)	LogNormal(1, 1.25) / LogNormal(0, 8)

Changes made by the conversion

• SubtreeSlide → kernel.BactrianSubtreeSlide. Each slide starts at its tuned size, from BEAST 3 runs with acceptance about 0.3. The sizes run from 6×10⁻⁵ (testSimulatedAlignment) and 0.008–0.73 to 21000–27000 (testMultipleAlignments, whose trees are in years).
  • They are kept rather than BEAUti's new start size, 0.01 (Start the BEAUti subtree slide at size 0.01 #201), as Convert the calibration and tree-prior examples to BEAST 3, with proper priors #199's examples are. For the two extreme files, tuning could not get from 0.01 to the tuned size within a run (Auto-tuning can't recover from a step size that starts too large (1/n gain) #200).
• offset="0.0" is dropped, since an offset of 0 is no shift. BEAST 3 applies a non-zero offset by wrapping the distribution in OffsetReal / OffsetInt.
• Parameter domains come from the Java Input each parameter feeds, using the narrowest when it feeds several. Upper bounds are not kept.
• Parameter size: RandomLocalClockModel rates / indicators become vectors. BEAST 2 resized them per branch at start-up.
• Prior wrapper, operator classes and tree scalers are mapped to their BEAST 3 equivalents.
• testSRD06: two unused state nodes are removed in BEAST 3 and commented out in legacy/.

Where the files are

• A BEAST 3 file sits at the same relative path as its BEAST 2 source: examples/legacy/<file> → examples/<file>.
• The seqgen examples need beast-fx classes, so they are in beast-fx/src/test/resources/beast.fx/examples/, with their BEAST 2 sources moved to beast.fx/examples/legacy/. They ship as examples/beastfx/:
  • the BEAST.app package zip includes them;
  • release/{Linux,Windows}/assemble-bundle.sh and release/Mac/build-sign-dmg.sh extract them;
  • the release READMEs are updated.
• The JSON examples testHKY.json and testUCLNclock.json now ship in the release: beast-base/src/assembly/package.xml included only *.xml, so both were missing from the BEAST.base package zip and hence from every installer. Checked: both are in the rebuilt zip's examples/, and both pass bin/beast -validate.
• New legacy/README.md: the legacy/ files are BEAST 2 XML, not converted, and must still run in BEAST 2.8.x with the old, deprecated, classes (until their removal in 3.0.0).

Java changes

SequenceSimulator and SimulatedAlignment: branchRateModel takes the BranchRateModel interface, so both BEAST 3 and legacy clocks are accepted. Their siteModel input still takes only the BEAST 3 SiteModel, so a plain BEAST 2 seqgen XML still does not run in BEAST 3.

Tests

• beast-base ExampleXmlParsingTest: new method test_ThatLegacyXmlExamplesParse parses every XML/JSON directly in beast.base/examples/legacy/ (41 files) in BEAST 2.8.
• New beast-fx ExampleXmlParsingTest: parses and runs beast.fx/examples, and parses beast.fx/examples/legacy.

Validation (after merging master)

Check	Result
bin/beast -validate / bin/beast-fx -validate, all 12 BEAST 3 files	✅ pass
Changed BEAST 2 files: BEAST 2.8 (-validate) / BEAST 2.7.7 (-validate, beast-base ones)	✅ pass / ✅ pass
Full beast-base suite, including ExampleDeprecationTest (#199) and the new legacy test	✅ 569 tests, 0 failures, 3 skipped
beast-fx ExampleXmlParsingTest	✅ 3 tests pass
Parameter domains match the Java inputs they feed	✅ no mismatches

Not in this PR: the posterior comparison against BEAST 2.7.9 (request 3) and the end-to-end run of the changed release scripts (request 5) will be handled in a separate GitHub issue. Open items are listed in TODO-migrate-legacy-xmls-batch2.md.

Bug found: #205 (fixed in #206)

JSONProducer wrote parameter domains in a form BEAST 3 could not read back. This was reported in #205 and fixed in #206 (merged). testUCLNclock.json was written by hand before the fix.

[alexeid]

Thanks Walter, careful conversions, and good to have the seqgen examples shipping. Since you opened this we've decided the examples must not use improper priors (see #199 and CompEvol/beast2#1225 for what we did with batch 1). Requests:

1. Proper priors, in both versions. testRandomLocalClock (kappa, popSize, rates), testRelaxedClock (kappa, popSize, ucld.stdev) and testTipDates (clockRate) have estimated parameters with no prior. The LogUniform[1e-8, 1e8] stand-ins for OneOnX should go too. Batch 1 uses LogNormal(M=0, S=8) for rates and sizes and LogNormal(1, 1.25) for kappa. The BEAST 2 originals need the same change, in a beast2 PR like CompEvol/beast2#1225.
2. Slide sizes. Start BactrianSubtreeSlide at its tuned size, not 1.0. On substitution-scale trees, 1.0 never tunes down within a run (#200).
3. Posterior comparison against 2.7.9 (steps 2–4), after 1, since the priors change the posteriors.
4. SequenceSimulator / SimulatedAlignment: Input<BranchRateModel> instead of the spec Base would keep legacy clocks in BEAST 2 XML working, since the class only uses the interface.
5. Could someone run the changed release scripts end to end before the next RC?

[alexeid]

Thanks Walter, approving. Points 1, 2 and 4 look good: no estimated parameter is left with an improper prior (ucld.mean has none, but it's fixed), the tuned slide sizes are in, and the seqgen input accepts legacy clocks.

On 1: your proper priors are in the legacy/ copies rather than the beast2 repo's originals. For the comparison (3) that's fine. I ran all six edited legacy files in BEAST 2.7.9 and they run cleanly, so they can serve as the BEAST 2 reference. The comparison write-up should just say these are the reference files, rather than the v2.7.8 originals the beast3-test README points to.

One small thing for later: the package assembly only includes examples/*.xml, so the JSON examples (testUCLNclock.json here, and the existing testHKY.json) don't ship.