Potter's Signal in Ceramic Vessel Forms: A Pairwise Morphometric Approach

This repository contains the data and the software compendium for the article "Potter's Signal in Ceramic Vessel Forms: A Pairwise Morphometric Approach". The compendium covers the complete workflow: from the processing of the source vessel images to the calibration of similarity thresholds on ethnographic material and the network analysis of two archaeological assemblages. Each folder contains its own README file with a detailed description of the scripts.

OVERALL STRUCTURE OF THE REPOSITORY
The repository is organized by the stages of the study.

1. dataset (SVG)
The original ethnographic data: 556 vector contours (SVG) of averaged vessel profiles - 478 vessels made on kick wheels by 24 potters and 78 vessels made on hand-operated wheels by 4 potters.

2. data_preparation
GUI tools and batch-processing scripts for preparing the images and extracting morphometric features.
• average_contour: generates symmetric averaged contours from the source vessel images.
• CRP_measurement: interactive measurement of the Chord-Radial Profile (CRP) and export to Excel.
• EFA_preparation: batch conversion of images and SVG files into standardized binary silhouettes for Elliptic Fourier Analysis (EFA).

3. main_analysis
The core of the study: calibration of the similarity thresholds on the ethnographic kick-wheel sample by Monte Carlo cross-validation, the test of their robustness to the number of potters, and the test of their transfer to hand-operated-wheel pottery (Sections 5-6 of the article).

4. archaeology_case_1
Application of the method to the 380 Roman-period red-slip vessels from the Frontovoe 3 cemetery, Crimea (Section 7.1): application of the thresholds, overlap of the two methods, chronological statistics of the links, and comparison with conventional clustering of elliptic Fourier coefficients.

5. archaeology_case_2
Application of the method to the 358 early medieval vessels from 19 cemeteries of the North Caucasus (Section 7.2): application of the thresholds, overlap of the two methods, distribution of links within sites, within regions and between regions with permutation tests, and comparison with conventional clustering at the regional and site levels.

GLOBAL DEPENDENCIES (REQUIREMENTS)
The following Python libraries are required for the whole compendium:
pip install opencv-python numpy pandas scipy scikit-learn statsmodels numba matplotlib svgpathtools openpyxl tqdm networkx python-igraph leidenalg Pillow
(Note: the tkinter library is part of the standard Python distribution, but on Linux "sudo apt-get install python3-tk" may be required.)

REPRODUCIBILITY
All stochastic steps use a fixed random seed (42), so repeated runs give identical results. The vessel-level network graphs used by some scripts (frontovoe_2_methods_graph.graphml in archaeology_case_1; CRP_graph.graphml and EFA_graph.graphml in archaeology_case_2) were built in Gephi from the lists of pairs that passed the thresholds (sheet Matches_Only of the inference results) and are provided in the corresponding results folders.

SCENARIO A: REPRODUCING THE RESULTS OF THE ARTICLE
To replicate the computations described in the article, run the scripts in the following order.

Step 1. Data preparation (folder 2)
The prepared data (CRP measurements in Excel and EFA silhouettes in PNG) are included in the repository, so this step is needed only to re-create them from the source images. The contour preparation involves manual steps (placement of the profile end points, optional node editing), so re-created data may differ slightly from the published ones.
1. Process the source vessel images with average_contour.py to obtain averaged SVG contours.
2. Use CRP_measurement.py to measure the 49 profile points and save them in Excel format.
3. Use preparation_efa.py to create binary silhouettes (1024 x 1024 PNG) for EFA.

Step 2. Calibration on the ethnographic material (folder 3)
1. Run 1)CRP_and_EFA_analysis.py. The script performs 10,000 Monte Carlo cross-validation iterations with potter-level splitting, selects the thresholds, and saves the results to the results folder.
2. Run 2)threshold_robustness_check.py to assess how precision changes with the number of potters.
3. Run 3)calibration_for_hand-operated-pottery_CRP.py and 4)calibration_for_hand-operated-pottery_EFA.py to test the thresholds on hand-operated-wheel pottery.

Step 3. Archaeological case studies (folders 4 and 5)
For each case study, run in sequence:
1. 1)CRP_inference.py and 2)EFA_inference.py (application of the thresholds to the archaeological data).
2. 3)search_common_pairs(Jaccard).py (pairs found by both methods, "golden pairs", and the Jaccard coefficient).
3. The statistical scripts: 4)edge_chronology_statistics.py for case 1; 4)network_sites_analysis.py for case 2.
4. 5)baseline_comparison.py (and 6)baseline_comparison_site-level.py for case 2) for the comparison with conventional clustering.

SCENARIO B: APPLICATION TO NEW ARCHAEOLOGICAL MATERIAL
This guide is intended for researchers who wish to apply the method to new archaeological assemblages in order to identify candidate groups of vessels of shared production origin.

STAGE 1. Standardization of the input data
1. Photograph the vessels under standardized conditions (strictly frontal view, vessel on a horizontal surface, camera at the mid-height of the vessel).
2. Process the contour image of each vessel with average_contour.py. If necessary, remove smoothing artifacts manually in node-editing mode. Save the results as SVG.
3. Convert the resulting SVG files (or the original vessel images) into binary silhouettes with preparation_efa.py.

STAGE 2. Feature extraction
1. Open CRP_measurement.py, load the SVG file, and place the markers on the top and bottom points of the profile. Measure the profile and save the data to a common Excel file (the first column contains the vessel ID, followed by 49 columns of profile measurements, i.e. distances from the chord to the contour).
2. Make sure that the folder with the binary silhouettes (PNG) is ready for EFA.

STAGE 3. Selection and application of similarity thresholds
The thresholds depend on the manufacturing technology. Choose the thresholds that correspond to the technology of your material and set them in the SETTINGS block of the inference scripts.
For pottery made on a kick wheel:
• CRP (Gradient metric): threshold 0.1279 (98th percentile)
• EFA (Euclidean metric): threshold 0.9782 (99th percentile)
For pottery made on a hand-operated wheel:
• CRP (Gradient metric): threshold 0.0972 (90th percentile)
• EFA (Euclidean metric): threshold 0.9428 (79th percentile)
Thresholds for handmade pottery have not been calibrated; for such material the hand-operated-wheel thresholds are only the closest available approximation.
Run 1)CRP_inference.py (with the path to your Excel file with CRP data) and 2)EFA_inference.py (with the path to the folder with silhouettes). The output consists of Excel files with all pairs and with the pairs that passed the threshold (sheet Matches_Only). The pairs found by both methods can be identified with 3)search_common_pairs(Jaccard).py.

STAGE 4. Interpretation of the results
• The detected pairs are candidate links, not attributions to a particular potter. Morphological similarity above the threshold is consistent with a common production unit, but also with a shared morphological tradition, a common typology or common distribution networks; the resulting groups should be tested against other evidence.
• The precision of individual pairs decreases as the number of potters contributing to an assemblage grows (Section 6.4 of the article). Individual pairs are most reliable in small assemblages and when they are found by both methods; in large assemblages the method is most informative at the level of the network as a whole, i.e. the distribution of links across contexts.