PopFunc: Bayesian Model-Averaging of Parametric Coalescent Models

PopFunc is a BEAST3 package that enables Bayesian inference of parametric population-growth models under a flexible model-averaging framework. By using discrete indicator variables, PopFunc allows users to explore multiple candidate demographic models in a single run without prior commitment to a single growth function.

The repository has two modules:

• popfunc-beast — the BEAST3 package itself: the population growth models (constant, exponential, logistic, Gompertz, expansion, piecewise Cons-Exp-Cons) plus stochastic variable selection across them.
• popfunc-lphybeast — an LPhyBeast extension that lets you write these models as LPhy scripts (see examples/*.lphy) and convert them to BEAST3 XML.

Documentation

1. Introduction

   • High-level overview of PopFunc’s motivation, theoretical background, and typical use cases.

2. Installation & Requirements

   • Detailed setup instructions, prerequisites, and compatibility notes.

3. Bayesian Model Averaging (BMA) Setup & Basic Usage

   • How to configure model indicators, enable multiple parametric growth models, and interpret outputs.

4. Examples & Tutorials

   • Step-by-step demonstrations, scripts, and recommended workflows for applying PopFunc to real or simulated data.

If you have any questions or need further help, feel free to check out the BEAST Users Google Group.

For developer

Build both modules, skipping tests:

mvn clean package -DskipTests

This produces the installable BEAST package ZIP at popfunc-beast/target/popfunc-beast-<version>.zip, and popfunc-lphybeast/target/popfunc-lphybeast-<version>.jar.

Unlike a plain BEAST package, PopFunc's examples are LPhy scripts, not static BEAST XML — convert one to XML with LPhyBeast first, then run it through BEAST3:

lphybeast examples/jcCoalExponential.lphy

Project folder structure

popfunc-beast/
└── src/main/java/popfunc/beast/evolution/populationmodel/
    ├── ConstantGrowth, ExponentialGrowth, LogisticGrowth,
    │   GompertzGrowth_f0, GompertzGrowth_t50, ExpansionGrowth,
    │   Cons_Exp_ConsGrowth        (the growth models)
    ├── StochasticVariableSelection (model-averaging indicator)
    └── PopFuncWith{UpOp,UpDownOp,AVMNOp}  (operator-contribution mixin interfaces)

popfunc-lphybeast/
└── src/main/java/popfunc/lphybeast/
    ├── spi/LBPopfunc.java                    (LPhyBEASTMapping provider)
    └── tobeast/
        ├── generators/PopFuncCoalescentToBEAST.java
        └── values/*ToBEAST.java              (one converter per growth model)

examples/          (LPhy scripts, not BEAST XML — see "For developer" above)
docs/              (see Documentation above)

Releasing

Zip folder structure

The BEAST package ZIP produced by popfunc-beast (mvn clean package -DskipTests) contains:

version.xml
popfunc.src.jar
lib/
└── popfunc-beast-<version>.jar
examples/          (copied from the repo-root examples/ directory)

popfunc-lphybeast does not build a BEAST package ZIP — like other LPhyBeast extension modules (e.g. lphybeast-mm), it publishes as a plain jar for LPhyBeast to pick up.

1. Maven Central release (JARs)

Push a v* tag to trigger .github/workflows/ci-publish.yml, which sets the Maven version from the tag, builds, tests, GPG-signs, and publishes both modules to Maven Central:

git tag v0.1.0
git push origin v0.1.0

Monitor the run at: https://github.com/LinguaPhylo/PopFunc/actions/workflows/ci-publish.yml

2. GitHub release (BEAST package ZIP)

First remove -SNAPSHOT from <version> in popfunc-beast/pom.xml so it matches the release (e.g. 0.1.0-SNAPSHOT -> 0.1.0), then build the ZIP locally:

mvn clean package -DskipTests

Note: if you skip the manual edit above, the build still succeeds, but the module jar bundled inside the ZIP (lib/popfunc-beast-<version>.jar) will carry the -SNAPSHOT suffix — that's meant for dev/testing builds, not an official release. Alternatively, instead of hand-editing pom.xml, run:

mvn versions:set -DnewVersion=<version> -DgenerateBackupPoms=false

The ZIP is written to popfunc-beast/target/popfunc-beast-<version>.zip. Then manually:

1. Go to https://github.com/LinguaPhylo/PopFunc/releases/new
2. Choose the matching tag (e.g. v0.1.0), fill in the release title/notes
3. Upload popfunc-beast/target/popfunc-beast-<version>.zip as a release asset
4. Publish

Enjoy exploring PopFunc!