Computational Reproducibility Guide
\nArticle: A Machine Learning Framework for Chronological Classification of Archaeological Samples Based on Lithic Typology Distributions Journal: Journal of Archaeological Science Complies with: JAS Data & Code Availability / Transparency & Replicability Policy
\n\n\nThis repository contains all code and data required to fully reproduce the quantitative results reported in the article. The pipeline is containerised with Docker so that any researcher can obtain identical outputs on any operating system (Windows, macOS, Linux) without manual dependency installation.
\n\n\nscripts/\n\u251c\u2500\u2500 Dockerfile ← Container definition (pinned base image + dependencies)\n\u251c\u2500\u2500 requirements.txt ← Exact Python package versions\n\u251c\u2500\u2500 run_pipeline.sh ← Entrypoint: runs training → validation → predictions\n\u251c\u2500\u2500 .dockerignore ← Files excluded from the Docker build context\n\u2502\n\u251c\u2500\u2500 main.py ← Pipeline orchestrator (CLI entry point)\n\u251c\u2500\u2500 train_validate.py ← Model training & validation (all classifiers)\n\u251c\u2500\u2500 benchmark_runner.py ← Runs all model × augmentation combinations\n\u251c\u2500\u2500 dirichlet_predictive_model.py ← Bayesian Dirichlet-multinomial classifier\n\u251c\u2500\u2500 dirichlet_pipeline.py ← Dirichlet feature extraction pipeline\n\u251c\u2500\u2500 data_loader.py ← ODS / CSV data loading & cleaning\n\u251c\u2500\u2500 data_pipeline.py ← Unified train / valid / predict data bundle\n\u251c\u2500\u2500 augmentation.py ← Bootstrap & Poisson jitter augmentation\n\u251c\u2500\u2500 ensemble.py ← Ensemble consensus & King-model selection\n\u251c\u2500\u2500 model_loader.py ← Deserialise saved joblib models\n\u251c\u2500\u2500 collect_predictions_by_id.py ← Aggregate per-model CSVs into wide table\n\u251c\u2500\u2500 report_html.py ← HTML report generation\n\u251c\u2500\u2500 generate_figures.py ← Generates publication figures (Sankey, confusion matrix, type portrait, stacked bar)\n\u251c\u2500\u2500 generate_global_training_report.py← Cross-experiment global summary\n\u251c\u2500\u2500 io_paths.py ← Output directory layout helpers\n\u2502\n\u2514\u2500\u2500 data/\n \u2514\u2500\u2500 Puntas_TODOS.ods ← Input dataset (APRIORI / MODEL_CHECKING / APOSTERIORI sheets)| Software | \nMinimum version | \nDownload | \n
|---|---|---|
| Docker Desktop (Windows / macOS) | \n24.x | \nhttps://www.docker.com/products/docker-desktop | \n
| Docker Engine (Linux) | \n24.x | \nhttps://docs.docker.com/engine/install/ | \n
No Python installation is required on the host machine.
\n\n\n# If distributed via a repository:\ngit clone <repository-url>\ncd <repository>/scripts\n\n# Or simply unzip the supplementary archive and enter the scripts/ folder.Run this command from inside the scripts/ directory (where the Dockerfile lives):
docker build -t puntas-ml .This will:
\npython:3.11.9-slim-bookworm)requirements.txt)Expected build time: 2–5 minutes (depends on internet speed; packages are ~500 MB).
\nWindows (PowerShell):
\nmkdir outputmacOS / Linux:
\nmkdir outputWindows (PowerShell):
\ndocker run --rm -v \"${PWD}\\output:/app/output\" puntas-mlmacOS / Linux:
\ndocker run --rm -v \"$(pwd)/output:/app/output\" puntas-mlThe container will execute three sequential steps:
\n/app/output (bound to your local output/ folder).Expected runtime: 20–60 minutes on a modern laptop (CPU only; no GPU required).
\nAfter the run completes, the output/ directory will contain:
output/\n\u251c\u2500\u2500 ml_train/\n\u2502 \u251c\u2500\u2500 index.html ← Interactive benchmark overview\n\u2502 \u251c\u2500\u2500 benchmark_report_*.html ← Per-strategy HTML reports\n\u2502 \u251c\u2500\u2500 summary_*.csv ← Metrics table (accuracy, F1, etc.)\n\u2502 \u251c\u2500\u2500 <run_id>/\n\u2502 \u2502 \u251c\u2500\u2500 models/model.joblib ← Serialised trained model\n\u2502 \u2502 \u251c\u2500\u2500 metrics/metrics.json ← Validation metrics (JSON)\n\u2502 \u2502 \u251c\u2500\u2500 confusion_matrix.png ← Confusion matrix plot\n\u2502 \u2502 \u2514\u2500\u2500 roc_curve.png ← ROC curve plot\n\u2502 \u2514\u2500\u2500 ...\n\u251c\u2500\u2500 predictions/\n\u2502 \u251c\u2500\u2500 <run_id>.csv ← Per-model APOSTERIORI predictions\n\u2502 \u251c\u2500\u2500 aposteriori_predictions_wide.csv ← Wide consensus table\n\u2502 \u251c\u2500\u2500 aposteriori_predictions_wide.html ← Human-readable consensus report\n\u2502 \u2514\u2500\u2500 predictions_summary.csv ← King + Matched + per-model columns\n\u2514\u2500\u2500 figures/\n \u251c\u2500\u2500 fig_sankey_600dpi.png ← Sankey: expert type → model prediction\n \u251c\u2500\u2500 fig_confusion_norm_600dpi.png ← Normalised confusion matrix\n \u251c\u2500\u2500 fig_breakdown_stacked_600dpi.png ← Stacked bar prediction breakdown\n \u2514\u2500\u2500 fig_type_portrait_600dpi.png ← Per-type prediction portrait\n \u251c\u2500\u2500 predictions/\n \u2502 \u251c\u2500\u2500 dirichlet_posteriors_train.csv\n \u2502 \u251c\u2500\u2500 dirichlet_posteriors_valid.csv\n \u2502 \u2514\u2500\u2500 dirichlet_posteriors_aposteriori.csv\n \u2514\u2500\u2500 plots/\n \u2514\u2500\u2500 Dirichlet_*.svg ← Per-site Dirichlet probability plots| Mechanism | \nImplementation | \n
|---|---|
| Fixed random seed | \n--random-state 42 passed to all stochastic estimators | \n
| Pinned Python version | \npython:3.11.9-slim-bookworm (Dockerfile FROM) | \n
| Pinned library versions | \nAll packages fixed in requirements.txt | \n
| Disabled thread-level parallelism | \nOMP_NUM_THREADS=1, OPENBLAS_NUM_THREADS=1, MKL_NUM_THREADS=1 | \n
| Disabled Python hash randomisation | \nPYTHONHASHSEED=0 | \n
| Headless matplotlib backend | \nMPLBACKEND=Agg — no display required | \n
| Non-root container execution | \nRuns as unprivileged archaeo user | \n
\n\n\n\nNote on hardware variation: Floating-point arithmetic is deterministic given the same CPU instruction set. Minor numerical differences (< 1e-10) may appear if comparing results between x86-64 and ARM64 (Apple Silicon) hosts, but these do not affect any classification outcome or reported metric.
\n
You can also enter the container interactively and run scripts manually:
\ndocker run --rm -it -v \"$(pwd)/output:/app/output\" puntas-ml bashInside the container:
\n# Train only specific models\npython main.py data/Puntas_TODOS.ods \\\n --models rf svm \\\n --augmentations none \\\n --outdir ml_train \\\n --preddir predictions \\\n --random-state 42\n\n# Run Dirichlet model only\npython dirichlet_predictive_model.py data/Puntas_TODOS.ods \\\n --plot --verbose\n\n# Collect and summarise predictions\npython collect_predictions_by_id.py \\\n --pred-dir predictions \\\n --outdir ml_train \\\n --metric f1_macroAll packages are installed from PyPI at the exact versions listed below:
\n| Package | \nVersion | \nPurpose | \n
|---|---|---|
numpy | \n1.26.4 | \nArray operations | \n
pandas | \n2.2.2 | \nTabular data / ODS reading | \n
scipy | \n1.13.1 | \nStatistical functions (Dirichlet log-likelihood) | \n
scikit-learn | \n1.5.1 | \nClassical ML classifiers, CV, metrics | \n
joblib | \n1.4.2 | \nModel serialisation & parallelism control | \n
torch | \n2.3.1 | \nDeep Siamese network (CPU build) | \n
odfpy | \n1.4.1 | \nODS spreadsheet engine | \n
openpyxl | \n3.1.5 | \nExcel/ODS compatibility layer | \n
matplotlib | \n3.9.1 | \nFigure generation | \n
| File | \nFormat | \nDescription | \n
|---|---|---|
data/Puntas_TODOS.ods | \nOpenDocument Spreadsheet | \nLithic assemblage dataset with three sheets: APRIORI (training set of dated assemblages), MODEL_CHECKING (validation set), APOSTERIORI (undated assemblages for chronological prediction) | \n
Feature columns used: Type.1, Type.2, Type.3, Type.4, Type.5, Type.7, Metal, Campanif Target column: Phase (integer, chronological period) Identifier column: Yacimiento (site name, used as observation ID)
\n\n\n\n\n
Type.6is intentionally excluded from all analyses — see Methods section of the article.
The source code is released under the MIT Licence (see LICENSE file if included). The dataset (Puntas_TODOS.ods) is released under CC BY 4.0.
If you use this code or data, please cite the original article:
\n[Author et al. (in press). A Machine Learning Framework for Chronological \nClassification of Archaeological Samples Based on Lithic Typology Distributions. \nJournal of Archaeological Science. DOI: XXXX]For questions about the code or data, please open an issue in the repository or contact
", "lang": { "id": "eng", "title": { "en": "English" } }, "type": { "id": "notes", "title": { "de": "Anmerkungen", "en": "Notes" } } } ], "creators": [ { "person_or_org": { "family_name": "Jim\u00e9nez-Puerto", "given_name": "Joaqu\u00edn", "identifiers": [ { "identifier": "0000-0001-9760-9602", "scheme": "orcid" } ], "name": "Jim\u00e9nez-Puerto, Joaqu\u00edn", "type": "personal" } }, { "affiliations": [ { "id": "01460j859", "identifiers": [ { "identifier": "01460j859", "scheme": "ror" }, { "identifier": "grid.157927.f", "scheme": "grid" }, { "identifier": "0000 0004 1770 5832", "scheme": "isni" } ], "name": "Universitat Polit\u00e8cnica de Val\u00e8ncia" } ], "person_or_org": { "family_name": "Trull", "given_name": "Oscar", "identifiers": [ { "identifier": "0000-0003-2896-8606", "scheme": "orcid" } ], "name": "Trull, Oscar", "type": "personal" } }, { "person_or_org": { "family_name": "Troncoso", "given_name": "Alicia", "identifiers": [ { "identifier": "0000-0002-9801-7999", "scheme": "orcid" } ], "name": "Troncoso, Alicia", "type": "personal" } }, { "affiliations": [ { "id": "01r9z8p25", "identifiers": [ { "identifier": "01r9z8p25", "scheme": "ror" }, { "identifier": "grid.10041.34", "scheme": "grid" }, { "identifier": "0000 0001 2106 0879", "scheme": "isni" } ], "name": "Universidad de La Laguna" } ], "person_or_org": { "family_name": "Pardo-Gord\u00f3", "given_name": "Salvador", "identifiers": [ { "identifier": "0000-0002-1060-1526", "scheme": "orcid" } ], "name": "Pardo-Gord\u00f3, Salvador", "type": "personal" } } ], "description": "We present a similarity-based framework for the chronological attribution of undated archaeological assemblages, grounded in Siamese Neural Networks (SNNs) and specifically designed for the small sample sizes, compositional uncertainty, and diffuse phase boundaries that characterize most prehistoric datasets. Unlike conventional supervised classifiers, which require sufficient per-class examples to define stable decision boundaries, SNNs reformulate chronological inference as a pairwise relational problem: the model estimates the probability that two assemblages belong to the same chronological phase, mimicking the comparative reasoning implicit in typological analysis while rendering it reproducible and transferable. The quadratic growth of training pairs with sample size substantially amplifies the effective training set without additional radiocarbon data, a critical advantage in data-scarce contexts.
\nThe framework is evaluated on 185 radiocarbon-dated bifacial flint arrowhead assemblages from eastern Iberia (ca. 3500–1900 cal. BC), organized into six chronological phases spanning the Late Neolithic to the Early Bronze Age. Multiple Siamese configurations — logistic regression, MLP, random forest, and deep learning encoders — are compared against standard MLP and SVM baselines. The best-performing configuration (DL with bootstrap augmentation and Dirichlet-multinomial compositional variables) achieves a macro F1 of 21.4% and balanced accuracy of 21.8%, representing a consistent improvement over both baselines and over a stratified random classifier (expected macro F1: ~17%) across all class-balanced metrics. Per-type analysis reveals that predictive accuracy correlates with morphological distinctiveness: foliaceous types reach 96.5% agreement with expert assignments, while pedunculate forms — whose typological boundaries are inherently contested — present the greatest classification challenge, a pattern that mirrors the gradient of archaeological interpretive confidence.
\nThe input structure of the framework — assemblage-level frequency vectors of artifact types — is standard across the main material categories used for chronological inference in prehistoric archaeology, including ceramics, lithic industries, and faunal assemblages. The approach is therefore directly transferable to other material traditions and regional sequences, and its outputs are formally compatible with Bayesian chronological modelling pipelines. The framework requires only typological frequency data routinely collected during excavation and post-excavation analysis, involves negligible computational cost relative to radiometric methods, and can be deployed at early stages of site investigation to generate provisional chronological attributions — providing an operational basis for decisions about sampling strategy, resource allocation, and the prioritization of contexts for absolute dating. As radiocarbon coverage and regional reference databases expand, the framework scales accordingly, functioning as a cost-effective first-pass instrument within a broader chronological workflow rather than as a replacement for higher-resolution analytical methods.
", "languages": [ { "id": "eng", "title": { "en": "English" } } ], "publication_date": "2026-04-17", "publisher": "Zenodo", "resource_type": { "id": "dataset", "title": { "de": "Datensatz", "en": "Dataset" } }, "rights": [ { "description": { "en": "The Creative Commons Attribution license allows re-distribution and re-use of a licensed work on the condition that the creator is appropriately credited." }, "icon": "cc-by-icon", "id": "cc-by-4.0", "props": { "scheme": "spdx", "url": "https://creativecommons.org/licenses/by/4.0/legalcode" }, "title": { "en": "Creative Commons Attribution 4.0 International" } } ], "subjects": [ { "subject": "Similarity-based classification" }, { "subject": "copper age" }, { "subject": "Small sample machine learning" }, { "subject": "Bayesian chronological modelling" } ], "title": "SUPPLEMENTARY MATERIAL: Pairwise Similarity Learning for Chronological Attribution of Archaeological Assemblages: A Siamese Neural Network Approach", "version": "1.0" }, "parent": { "access": { "owned_by": { "user": "46830" }, "settings": { "accept_conditions_text": null, "allow_guest_requests": false, "allow_user_requests": false, "secret_link_expiration": 0 } }, "communities": { "default": "f466a75b-69ca-4b60-abb5-22e87ae9d073", "entries": [ { "access": { "member_policy": "open", "members_visibility": "public", "record_submission_policy": "open", "review_policy": "open", "visibility": "public" }, "children": { "allow": false }, "created": "2022-07-20T09:51:14.532802+00:00", "custom_fields": {}, "deletion_status": { "is_deleted": false, "status": "P" }, "id": "f466a75b-69ca-4b60-abb5-22e87ae9d073", "links": {}, "metadata": { "curation_policy": "The aim of this community is to collect research data published in Zenodo by members of Universitat de València.
\r\n", "page": "Datasets collection from Universitat de València researchers, managed and curated by the Libraries and Documentation Service.
\r\n\r\n\r\n\r\n
\r\n", "title": "Universitat de Val\u00e8ncia (UV) Research Data" }, "revision_id": 0, "slug": "universitat_valencia", "updated": "2022-07-20T10:17:44.029695+00:00" } ], "ids": [ "f466a75b-69ca-4b60-abb5-22e87ae9d073" ] }, "id": "19628744", "pids": { "doi": { "client": "datacite", "identifier": "10.5281/zenodo.19628744", "provider": "datacite" } } }, "pids": { "doi": { "client": "datacite", "identifier": "10.5281/zenodo.19628745", "provider": "datacite" }, "oai": { "identifier": "oai:zenodo.org:19628745", "provider": "oai" } }, "revision_id": 4, "stats": { "all_versions": { "data_volume": 0.0, "downloads": 0, "unique_downloads": 0, "unique_views": 32, "views": 35 }, "this_version": { "data_volume": 0.0, "downloads": 0, "unique_downloads": 0, "unique_views": 32, "views": 35 } }, "status": "published", "swh": {}, "updated": "2026-04-17T10:16:58.985956+00:00", "versions": { "index": 1, "is_latest": true } }