Die estimation via unsupervised statistical learning: a MATLAB + R pipeline for automatic die analysis of ancient coins, with ready-to-use grayscale image datasets of Neronian denarii.
Point it at a folder of coin photographs and it produces pairwise die-dissimilarity matrices and a Bayesian clustering of coins into dies. The method is described in Unsupervised Statistical Learning for Die Analysis in Ancient Numismatics (arXiv:2112.00290; see Citing).
The pipeline has two stages:
- MATLAB — image dissimilarities (
matlab/). Each image is scaled, denoised (total variation + CLAHE), and landmarked with Gaussian-process keypoints; SIFT descriptors at those keypoints are matched and geometrically filtered between every pair of coins, yielding a Procrustes-based dissimilarity and a match count per pair. These are combined into a single normalized distance matrix. - R — Bayesian microclustering (
R/). The distance matrix is clustered with a chaperones MCMC sampler over die partitions; a posterior co-clustering matrix is summarized to a point estimate with SALSO. When ground-truth die labels exist, normalized mutual information is reported.
| Path | Purpose |
|---|---|
matlab/pipeline/ |
Dissimilarity pipeline (GP keypoints → SIFT → Procrustes) |
matlab/app/ |
App Designer GUI over the dissimilarity stage, with keypoint preview |
matlab/data/ |
Dataset exporter, schema validator, and loader |
R/clustering/ |
Bayesian distance microclustering and SALSO summary |
config/ |
Clustering hyperparameters |
data/mat/ |
Nero denarii grayscale datasets (Git LFS) |
scripts/ |
Python dataset exporter |
paper/ |
Manuscript sources and figures |
- MATLAB (developed with R2021b) with the Image Processing, Statistics and
Machine Learning, and Parallel Computing toolboxes, plus
VLFeat 0.9.21 (run its
vl_setupbefore the driver). The same requirements cover the optional GUI inmatlab/app/, which wraps step 2 below and adds an interactive keypoint preview; seematlab/app/README.md. - R with
aricode,beepr,bmixture,cluster,collapse,cowplot,ggplot2,gtools,hms,import,msm,mvtnorm,optimx,plyr,readr,reshape2,rootSolve,salso,Rtsne,viridis, andviridisLite. - Optionally Python 3 with
numpy<2,pillow, andhdf5storageto build datasets on machines without MATLAB.
Arrange one dataset as a folder of subfolders, one subfolder per die (or per hypothesized group; use a single folder if no grouping is known):
my_coins/
die_A/img_001.jpg
die_A/img_002.jpg
die_B/img_003.jpg
...
1. Export to the dataset schema (MATLAB, or Python without MATLAB):
addpath('matlab/pipeline/helper_functions', 'matlab/data')
export_grouped_images('path/to/my_coins', 'data/mat/my_coins.mat', 'my_coins')python scripts/export_grouped_images.py path/to/my_coins data/mat/my_coins.mat my_coins2. Compute dissimilarities (MATLAB):
run('path/to/vlfeat-0.9.21/toolbox/vl_setup.m')
setenv('DIEGEST_DATA_MAT', fullfile(pwd, 'data/mat/my_coins.mat'))
setenv('DIEGEST_DATASET_ID', 'my_coins')
setenv('DIEGEST_OUTPUT_DIR', fullfile(pwd, 'results/matlab'))
setenv('DIEGEST_N_LANDMARKS', '300') % keypoints per image, see below
setenv('DIEGEST_RAD_CUT', '150') % radial crop in pixels, see below
run('matlab/pipeline/main.m')This writes a square distance CSV and a _labels.csv ordering table to the
output directory. Two parameters are dataset-dependent and worth tuning:
DIEGEST_N_LANDMARKS (number of GP keypoints; pick the largest value that does
not start placing keypoints in flat, uninformative regions — 300 was used for
the Nero obverses) and DIEGEST_RAD_CUT (radius removing the edge/legend
region after scaling to height 380). In our tests the two faces preferred
different settings: reverse types did best with DIEGEST_N_LANDMARKS=190 and
DIEGEST_RAD_CUT=50, obverses with 300 and 75–150. All other parameters (TV
weights 0.8/0.7, CLAHE clip 0.001, RBF length scale 5, match ratio 1.3, filter
fraction 0.2, rotation limit π/3) are the pipeline defaults described in the
paper.
3. Cluster into dies (R, from R/clustering because of relative
source() calls):
cd R/clustering
Rscript diegest_cluster.R "../../results/matlab/DISTANCE.csv" \
"../../results/matlab/DISTANCE_labels.csv" \
"../../config/clustering_hyperparameters.csv" --restartThe hyperparameter file sets the expected cluster-size prior (mean 5, variance
15), maximum cluster size 25, and 750,000 MCMC iterations (half burn-in,
thinning 10). Outputs include diagnostic plots, checkpoints, and a final
_prediction.csv with the estimated die partition; the estimator used, the
number of clusters found, and NMI against the folder grouping are printed when
available.
The shipped 750,000 is a starting value, not a recommendation — size it for your dataset as described next.
The sampler proposes one pair of coins per iteration, so how well a chain
has mixed depends on how many iterations it has run relative to the number of
pairs, n(n-1)/2. A fixed iteration count therefore means very different
things at different dataset sizes: 750,000 iterations is more than 90 passes
over a 125-image set and barely half a pass over a 1,600-image one. Budget a
few multiples of n(n-1)/2 and check the diagnostics rather than reusing one
number.
Measured plateaus on our test datasets — the earliest point from which NMI stops moving (within 0.005) and the posterior cluster count stops both drifting and shifting, and stays that way for every longer cutoff:
| Dataset | Images clustered | Pairs | Iterations to plateau | Coverage |
|---|---|---|---|---|
| Reverse, RIC I² 57 | 112 | 6,216 | 20,000 | 3.2× |
| Reverse, RIC I² 55 | 125 | 7,750 | 25,000 | 3.2× |
| Reverse, RIC I² 62 | 243 | 29,403 | 500,000 | 17× |
| Reverse, RIC I² 60 | 532 | 141,246 | 500,000 | 3.5× |
| Reverse, RIC I² 53 | 586 | 171,405 | 250,000 | 1.5× |
| Obverse | ~1,600 | ~1.29 M | 1,000,000 | 0.8× |
Plateaus landed between roughly 1× and 20× coverage, most of them in the low single digits. The practical consequence is that the same fixed budget is wasteful at one end and insufficient at the other: 750,000 iterations is around 30× more than the small reverse types need, and short of what the obverses do.
Longer chains past the plateau buy stability, not accuracy. Beyond it the between-seed spread in NMI keeps shrinking while the mean stops improving, so extra iterations make a run more reproducible rather than more correct. Spend them when you need a stable answer, not a better one.
Report the cluster count and per-die sensitivity alongside NMI. NMI is weakly sensitive to over-segmentation — it penalises splitting a die far more gently than merging two — so a partition with far too many clusters can still post a high NMI. The cluster count, and how much of each true die lands in one predicted cluster, are what actually reveal it. The driver prints the count next to the NMI for this reason.
data/mat/ ships six die-labeled grayscale datasets of Neronian denarii,
stored via Git LFS, ready to run through the pipeline above. Obverses are
studied as a single set because the mint combined obverse dies with reverse
dies of several types; reverses are grouped by RIC I² type:
| File | Coin face | Images | Dies |
|---|---|---|---|
nero_obverse.mat |
Obverse | 1,606 | 303 |
nero_reverse_ric53.mat |
Reverse, RIC I² 53 | 586 | 171 |
nero_reverse_ric55.mat |
Reverse, RIC I² 55 | 130 | 35 |
nero_reverse_ric57.mat |
Reverse, RIC I² 57 | 112 | 20 |
nero_reverse_ric60.mat |
Reverse, RIC I² 60 | 532 | 167 |
nero_reverse_ric62.mat |
Reverse, RIC I² 62 | 243 | 55 |
Each MAT file (v7.3) contains source-resolution grayscale uint8 images, die
group labels, filenames, SHA-256 checksums of the source photographs, and
dataset metadata. See data/README.md for the schema and rights notes. To
check a dataset's structure and counts:
addpath('matlab/data')
validate_image_dataset('data/mat/nero_obverse.mat', 1606, 303)On an Apple M1 Max (32 GB RAM): roughly 1 hour for the obverse dissimilarity matrix (~1,600 images), then about 2 hours to cluster it at the 1,000,000 iterations it needs. The small reverse types are minutes rather than hours at their own budgets — RIC I² 55 reaches its plateau at 25,000 iterations in about two minutes end to end, prior fitting included. Dissimilarity time scales quadratically in the number of images; clustering time scales with the iteration count you choose, which is itself set by the pair count (see Choosing the iteration count). Both depend on cores and MCMC settings.
- diegest-cluster — a newer R implementation of the clustering stage with a Shiny UI, resumable chunked runs, and progress/metrics tooling.
- RedClust.jl — Julia package for Bayesian clustering of high-dimensional data using pairwise dissimilarities.
If you use this code or data, please cite the paper:
@article{heinecke2021unsupervised,
title = {Unsupervised Statistical Learning for Die Analysis in Ancient Numismatics},
author = {Heinecke, Andreas and Mayer, Emanuel and Natarajan, Abhinav and Singhania, Adi},
journal = {arXiv preprint arXiv:2112.00290},
year = {2021}
}The software in this repository is released under the terms in LICENSE.
Third-party dependencies (VLFeat, R packages), coin photographs, and manuscript
content may carry their own licenses and rights; see data/README.md for the
image-rights note.