Computational Reproducibility Guide

Article: 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

Overview

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

Repository structure

scripts/
├── Dockerfile                        ← Container definition (pinned base image + dependencies)
├── requirements.txt                  ← Exact Python package versions
├── run_pipeline.sh                   ← Entrypoint: runs training → validation → predictions
├── .dockerignore                     ← Files excluded from the Docker build context
│
├── main.py                           ← Pipeline orchestrator (CLI entry point)
├── train_validate.py                 ← Model training & validation (all classifiers)
├── benchmark_runner.py               ← Runs all model × augmentation combinations
├── dirichlet_predictive_model.py     ← Bayesian Dirichlet-multinomial classifier
├── dirichlet_pipeline.py             ← Dirichlet feature extraction pipeline
├── data_loader.py                    ← ODS / CSV data loading & cleaning
├── data_pipeline.py                  ← Unified train / valid / predict data bundle
├── augmentation.py                   ← Bootstrap & Poisson jitter augmentation
├── ensemble.py                       ← Ensemble consensus & King-model selection
├── model_loader.py                   ← Deserialise saved joblib models
├── collect_predictions_by_id.py      ← Aggregate per-model CSVs into wide table
├── report_html.py                    ← HTML report generation
├── generate_figures.py               ← Generates publication figures (Sankey, confusion matrix, type portrait, stacked bar)
├── generate_global_training_report.py← Cross-experiment global summary
├── io_paths.py                       ← Output directory layout helpers
│
└── data/
    └── Puntas_TODOS.ods              ← Input dataset (APRIORI / MODEL_CHECKING / APOSTERIORI sheets)

Prerequisites

No Python installation is required on the host machine.

Step-by-step reproduction

1 — Clone / download the code

# If distributed via a repository:
git clone <repository-url>
cd <repository>/scripts

# Or simply unzip the supplementary archive and enter the scripts/ folder.

2 — Build the Docker image

Run this command from inside the scripts/ directory (where the Dockerfile lives):

docker build -t puntas-ml .

This will:

• Pull the pinned base image (python:3.11.9-slim-bookworm)
• Install all Python packages at their exact pinned versions (see requirements.txt)
• Copy all source files and the input dataset into the image

Expected build time: 2–5 minutes (depends on internet speed; packages are ~500 MB).

3 — Create an output directory on your machine

Windows (PowerShell):

mkdir output

macOS / Linux:

mkdir output

4 — Run the full pipeline

Windows (PowerShell):

docker run --rm -v "${PWD}\output:/app/output" puntas-ml

macOS / Linux:

docker run --rm -v "$(pwd)/output:/app/output" puntas-ml

The container will execute three sequential steps:

1. Training & validation — trains all classifiers (Logistic Regression, SVM, Random Forest, MLP, Prototypical, four Siamese variants) under all augmentation strategies (none, bootstrap, bootstrap+Poisson) and both cross-validation modes (holdout, LOOCV), with and without Dirichlet features.
2. Consensus prediction — aggregates per-model predictions into a wide table with majority-vote consensus and King-model selection (by F1-macro).
3. Output collection — copies all artefacts to /app/output (bound to your local output/ folder).

Expected runtime: 20–60 minutes on a modern laptop (CPU only; no GPU required).

5 — Inspect the results

After the run completes, the output/ directory will contain:

output/
├── ml_train/
│   ├── index.html                            ← Interactive benchmark overview
│   ├── benchmark_report_*.html               ← Per-strategy HTML reports
│   ├── summary_*.csv                         ← Metrics table (accuracy, F1, etc.)
│   ├── <run_id>/
│   │   ├── models/model.joblib               ← Serialised trained model
│   │   ├── metrics/metrics.json              ← Validation metrics (JSON)
│   │   ├── confusion_matrix.png              ← Confusion matrix plot
│   │   └── roc_curve.png                     ← ROC curve plot
│   └── ...
├── predictions/
│   ├── <run_id>.csv                          ← Per-model APOSTERIORI predictions
│   ├── aposteriori_predictions_wide.csv      ← Wide consensus table
│   ├── aposteriori_predictions_wide.html     ← Human-readable consensus report
│   └── predictions_summary.csv              ← King + Matched + per-model columns
└── figures/
    ├── fig_sankey_600dpi.png                 ← Sankey: expert type → model prediction
    ├── fig_confusion_norm_600dpi.png         ← Normalised confusion matrix
    ├── fig_breakdown_stacked_600dpi.png      ← Stacked bar prediction breakdown
    └── fig_type_portrait_600dpi.png          ← Per-type prediction portrait
    ├── predictions/
    │   ├── dirichlet_posteriors_train.csv
    │   ├── dirichlet_posteriors_valid.csv
    │   └── dirichlet_posteriors_aposteriori.csv
    └── plots/
        └── Dirichlet_*.svg                   ← Per-site Dirichlet probability plots

Reproducibility guarantees

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

Running individual scripts (advanced)

You can also enter the container interactively and run scripts manually:

docker run --rm -it -v "$(pwd)/output:/app/output" puntas-ml bash

Inside the container:

# Train only specific models
python main.py data/Puntas_TODOS.ods \
    --models rf svm \
    --augmentations none \
    --outdir ml_train \
    --preddir predictions \
    --random-state 42

# Run Dirichlet model only
python dirichlet_predictive_model.py data/Puntas_TODOS.ods \
    --plot --verbose

# Collect and summarise predictions
python collect_predictions_by_id.py \
    --pred-dir predictions \
    --outdir ml_train \
    --metric f1_macro

Software dependencies

All packages are installed from PyPI at the exact versions listed below:

Input data

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)

Type.6 is intentionally excluded from all analyses — see Methods section of the article.

Licence

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.

Citation

If you use this code or data, please cite the original article:

[Author et al. (in press). A Machine Learning Framework for Chronological 
Classification of Archaeological Samples Based on Lithic Typology Distributions. 
Journal of Archaeological Science. DOI: XXXX]

Contact

For questions about the code or data, please open an issue in the repository or contact