Skip to content
adisidevPublic

About

MATLAB + R pipeline for automatic die analysis of ancient coins, with die-labeled datasets of Neronian denarii (arXiv:2112.00290)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

30 Commits

Folders and files

Repository files navigation

diegest

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).

How it works

The pipeline has two stages:

  1. 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.
  2. 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.

Repository layout

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

Requirements

  • MATLAB (developed with R2021b) with the Image Processing, Statistics and Machine Learning, and Parallel Computing toolboxes, plus VLFeat 0.9.21 (run its vl_setup before the driver). The same requirements cover the optional GUI in matlab/app/, which wraps step 2 below and adds an interactive keypoint preview; see matlab/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, and viridisLite.
  • Optionally Python 3 with numpy<2, pillow, and hdf5storage to build datasets on machines without MATLAB.

Running on your own coins

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_coins

2. 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" --restart

The 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.

Choosing the iteration count

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.

Included data: Nero denarii

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)

Runtime

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.

Related software

  • 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.

Citing

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}
}

License

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.

About

MATLAB + R pipeline for automatic die analysis of ancient coins, with die-labeled datasets of Neronian denarii (arXiv:2112.00290)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages