Choose one route into Bayesian modeling with JDistlib

Start here

What are you trying to do?

Route A · recommended quick start

CSV → JDM → compiled model → MCMC → conclusion

WorkedMcmcCsvJdmExample.java is a deliberately verbose, line-by-line-commented Java program. It uses the checked-in CSV dataset and JDM model, so it runs without downloads or editing.

1. Load and validate dataRead the named y CSV column into a primitive double[].
2. Load and compile JDMRead UTF-8 source, bind N/y, call ModelScript.compile, and check its gradient.
3. Customize and sampleSet warmup, retained draws, target acceptance, tree depth, and metric adaptation; launch four dispersed seeded NUTS chains.
4. Diagnose and visualizePrint R-hat, ESS, MCSE, acceptance, divergences, depth, E-BFMI, and failures; export trace, rank, ACF, and energy plots.
5. Summarize and concludeReport posterior summaries, P(mu > 0), an exact cross-check, a predictive draw, and a conclusion conditional on convergence.

double[] y = readNumericColumn(csvPath, "y");
String source = new String(Files.readAllBytes(modelPath), UTF_8);
Map<String, double[]> data = new LinkedHashMap<>();
data.put("N", new double[] {y.length});
data.put("y", y);

CompiledModelScript compiled = ModelScript.compile(source, data);
BayesianModel model = compiled.model();
SamplingOptions options = SamplingOptions.builder()
    .warmupIterations(600).sampleIterations(1200)
    .targetAcceptance(0.90).maximumTreeDepth(11)
    .adaptMassMatrix(true).denseMassMatrix(false).build();
ChainResult[] chains = Chains.parallel(
    new NoUTurnSampler(), model, initialStates,
    options, BASE_SEED, 4);
McmcDiagnosticReport report = McmcDiagnostics.analyze(
    new String[] {"mu"}, chains);

Run the complete file

From the repository root, compile the packaged JAR and examples with ./gradlew compileDocumentationExamples on macOS/Linux or gradlew.bat compileDocumentationExamples on Windows. The classpath wildcard deliberately remains valid when the project version changes.

macOS/Linux:

java -cp "build/libs/*:build/documentation-examples" \
  examples.WorkedMcmcCsvJdmExample

Windows:

java -cp "build\libs\*;build\documentation-examples" examples.WorkedMcmcCsvJdmExample

Optional arguments are CSV_PATH JDM_PATH OUTPUT_DIRECTORY. The default output directory contains mu-trace.svg, mu-ranks.svg, mu-autocorrelation.svg, energy.svg, retained-draws.csv, diagnostics.json, and a self-contained report.html.

Interpret computation before evidence

For the checked-in data, the seeded run has a posterior mean near 0.22, posterior SD near 0.35, and a 95% interval crossing zero. The example first verifies chain status, R-hat, ESS, divergences, depth, E-BFMI, and failures; only then does it conclude that computation is healthy but the data do not establish the sign of the mean.

Route B · pure Java

Build a posterior without learning JDM or Stan

McmcWorkflowExamples.java constructs a beta-binomial model entirely with Java objects. The model definition changes, but gradient checking, SamplingOptions, parallel chains, diagnostics, and graph exports are the same.

BayesianModel model = new ModelBuilder()
    .data("n", 10).data("y", 7)
    .parameter("theta", Constraints.bounded(0, 1), 0.5)
    .factor("prior", new String[] {"theta"},
        ModelFactors.betaPrior("theta", 2, 2))
    .factor("likelihood", new String[] {"n", "y", "theta"},
        ModelFactors.binomialObservation("y", "n", "theta"))
    .build();

Use this route when models are assembled dynamically, data already live in Java services, or your team prefers compiler-checked Java APIs. For a CSV array bound to both the Java builder and JDM frontend, see McmcDataIngestionExamples.java. Continue with the model-layer reference and ModelBuilder JavaDoc.

Route C · trans-dimensional Java · expanded in 0.9.1

Use reversible-jump MCMC when model dimension really changes

JDistlib’s Java-only RJMCMC layer stores variable-length parameter states. The general engine accounts for forward and reverse proposal densities, boundary-dependent move-selection probabilities, dimension matching, and Jacobians. The additive sparse-subset engine uses sorted integer indices when the candidate universe is much larger than a bit mask.

Route D · examples by feature

Start from code the build verifies

For an applied narrative rather than an API catalog, use the posterior-prediction vignette or the difficult-chain diagnostics vignette.

Route E · JDM and Stan source

Choose the script depth you need

No Stan background required

Learn only as much model language as your route needs