RJMCMC-DECODE

Bayesian density-based clustering from nearest-neighbor distance mixtures.

Overview

This repository contains research code for clustering 2D spatial point patterns with heterogeneous local densities. The core idea is to summarize each point by its k-th nearest-neighbor distance, model the resulting distance distribution with a finite mixture of Poisson-process intensity components, and infer the number of components with reversible-jump Markov chain Monte Carlo (RJMCMC). The inferred density levels are then mapped back to the spatial domain to recover clusters.

The codebase combines:

• a legacy MATLAB implementation of the DECODE-style clustering workflow,
• a newer self-contained prototype with Adaptive Metropolis (AM), Delayed Rejection (DR), and RJMCMC,
• synthetic datasets and plotting utilities used for method development and validation.

This project is best read as a research-method repository rather than a packaged software library.

Method Summary

Given a 2D point set, the workflow is:

1. Compute the k-th nearest-neighbor distance for each point.
2. Represent the distance distribution as a mixture of homogeneous Poisson-process components, each with its own intensity parameter.
3. Use RJMCMC to infer both the number of mixture components and their parameters.
4. Convert inferred component structure into density thresholds.
5. Expand spatially connected regions under those thresholds to obtain clusters and noise labels.

The nearest-neighbor likelihood is implemented in Likelihood_NN.m, while cluster expansion is handled by MCMC_FindDen.m.

Main Entry Points

1. Modern demo

am_dr_rjmcmc_demo.m is the cleanest entry point for understanding the current method. It:

• generates synthetic 2D point data,
• computes 10-nearest-neighbor distances,
• runs an AM + DR + RJMCMC sampler,
• summarizes the posterior over the number of mixture components,
• produces diagnostic and result plots.

Use this script if you want a self-contained demonstration of the modeling approach.

2. Legacy DECODE pipeline

The original workflow is organized as:

• Decode_main.m: data preparation and RJMCMC sampling
• MCMC_map.m: posterior analysis of sampled component counts and parameters
• Dencluster_MCMC.m: density-threshold-based cluster reconstruction and visualization

For synthetic benchmark datasets in this repository, Decode_main supports:

• flag = 9 for DS1.csv
• flag = 10 for DS2.csv
• flag = 11 for DS3.csv
• flag = 12 for DS4.csv

This path is useful if you want to inspect the original DECODE-style clustering pipeline and its intermediate .mat outputs.

3. Validation script

validate_am_dr_rjmcmc.m provides a short smoke test for the updated AM/DR integration inside Decode_main. It runs a shortened chain on a synthetic dataset and checks that delayed rejection and adaptive covariance are actually exercised.

Repository Structure

Key files and folders:

• am_dr_rjmcmc_demo.m: self-contained modern prototype
• Decode_main.m: main legacy sampling pipeline
• MCMC_map.m: posterior summaries for sampled mixture structure
• Dencluster_MCMC.m: cluster recovery and plotting
• RJMCMC_AMDR_WithinUpdate.m: AM + DR within-model update step
• Likelihood_NN.m: nearest-neighbor mixture likelihood
• MCMC_FindDen.m: recursive density-connected cluster expansion
• ChooseData.m: older earthquake-data selection and preprocessing workflow
• datasets/: synthetic datasets DS1 to DS4
• synthetic datasets/: additional synthetic data assets, notebooks, and plotting scripts

The workspace also contains saved MATLAB intermediates such as MCMCdata.mat, y_para.mat, classxy.mat, and mix_para.mat, which are used by the legacy pipeline.

Quick Start

Requirements

• MATLAB
• Statistics and Machine Learning Toolbox for knnsearch used by am_dr_rjmcmc_demo.m

The legacy scripts also rely on standard MATLAB I/O functions such as readmatrix, writematrix, save, and load.

Run the modern demo

From MATLAB, with the repository folder on the path:

am_dr_rjmcmc_demo

This will generate synthetic data, run the sampler, print posterior summaries, and display figures.

Run the legacy pipeline on a synthetic dataset

Example using DS1.csv:

Num = 5000;
Decode_main(9, Num);
MCMC_map(9, 30, Num, 10, 1);

This sequence prepares nearest-neighbor distances, runs RJMCMC, summarizes the posterior over component counts, and launches cluster reconstruction.

For shorter non-plotting runs during development:

Num = 200;
opts = struct();
opts.MakePlots = false;
opts.RunPostProcess = false;
Decode_main(9, Num, opts);

Run the validation script

validate_am_dr_rjmcmc

Datasets

The repository includes multiple synthetic datasets intended for benchmarking clustering behavior under varying density structure:

• datasets/DS1.csv
• datasets/DS2.csv
• datasets/DS3.csv
• datasets/DS4.csv

Additional plotting scripts, notebooks, and derived assets are stored under synthetic datasets/.

The older code also contains hooks for earthquake-event data and DBF-based preprocessing, but those workflows depend on external data files and are less self-contained than the synthetic benchmarks bundled here.

Outputs

Typical outputs include:

• sampled parameter traces saved in y_para.mat,
• preprocessed nearest-neighbor data saved in MCMCdata.mat,
• posterior summaries such as mix_para.mat,
• recovered cluster assignments such as classxy.mat,
• MATLAB figures showing posterior occupancy, convergence diagnostics, histograms, and clustered point patterns.

Notes on Reproducibility

This repository contains active research code and historical scripts developed over time. For the most reproducible experience:

• start with am_dr_rjmcmc_demo.m for a self-contained run,
• use validate_am_dr_rjmcmc.m to check the updated sampler path,
• treat the legacy DECODE scripts as method-development code with saved intermediates and dataset-specific assumptions.

Some scripts contain historical export paths or workflow assumptions from the original development environment. These do not affect the conceptual method, but they may require local adjustment if you extend the legacy pipeline.

Citation

If you use this repository in academic work, cite the associated method description and acknowledge this codebase as the implementation source. If you want, this section can be updated later with a paper citation or a preferred BibTeX entry.