Assemblage Similarity as Inference: A Four-Layer Framework for Archaeological Network Construction

Supplementary Materials Assemblage Similarity as Inference: A Layered Framework for Archaeological Network Construction This package contains everything needed to reproduce every number, table and figure in the paper, plus the library (arqsim) that implements the framework. 1. What is here arqsim/ the library (10 modules, ~1,900 lines) test_arqsim.py 27 tests verifying the paper's mathematical claims fetch_data.py downloads the two published datasets from their AUTHORS' repos reproduce_all.py runs the whole pipeline and prints the headline numbers study_main.py §5: main validation study (13 methods x 3 regimes x 12 worlds) q_sweep.py §5.3: the q dial experiments_2_3.py §5.7-5.8: frontier sweep + aggregation experiment benchmark_empirical.py §6: benchmark on Cibola and SWSN backbone_fdr.py FDR-controlled backbone + convergence study (run on YOUR data) demo_pipeline.py §7: the protocol applied end-to-end (a worked example) figures.py regenerates Figures 1-5 from the CSVs md2docx.js markdown -> Word converter used to build the manuscript outputs/ all CSVs and figures as published pyproject.toml installable package definition requirements.txt pinned environment The archaeological data are not included. The Cibola and Southwest Social Networks datasets belong to Peeples (2018) and Mills et al. (2013) and are distributed from their own repositories. Bundling copies here would fork the data, hide subsequent corrections, and blur authorship. fetch_data.py downloads them from the source at run time. Please cite the original publications when using them — the script prints the citations. 2. Quick start # 1. install pip install -e . # 2. verify the implementation (should print: 27 passed) python -m pytest test_arqsim.py -q # 3. get the published datasets (only needed for §6) python fetch_data.py # 4. reproduce everything (~25-40 min) python reproduce_all.py reproduce_all.py prints the headline value from each table next to the value published in the paper, so a mismatch is immediately visible. Use --quick for a fast smoke test (it will not reproduce the exact numbers) or --skip-empirical if you do not want to download the data. 3. Reproducibility Every stochastic step is seeded. Running the pipeline twice on the same machine gives identical results, and the CSVs in outputs/ are exactly those used in the manuscript. Two honest caveats: Louvain community detection and Monte Carlo null models depend on the RNG. We fix seeds throughout, so results are deterministic given the same library versions. Different versions of networkx or numpy may shift the last decimal. The structure diagnostic (diagnose.structure_profile) is a Monte Carlo estimate. We report its stability across independent runs in §6.5 (Cibola: gradient in 6/6 runs; SWSN AD1050: no structure in 5/5). Single runs will vary by ±1 in z. Environment used for the published results: python 3.12 numpy 2.4.4 scipy 1.17.1 pandas 3.0.2 networkx 3.6.1 scikit-learn matplotlib scipy >= 1.11 is required for scipy.stats.random_table (the fixed-margin null). 4. Using the framework on your own data Your data is a site-by-type matrix of raw integer counts — not percentages, and not chronologically apportioned values (see §6.4 of the paper for why that matters). import numpy as np from arqsim import diagnose, hill, backbone, uncertainty, evaluate X = ... # (n_sites x n_types) raw counts # LAYER 1 — diagnose the regime BEFORE computing any similarity. # Reports coverage, typological resolution, sampling adequacy, blocks-vs-gradient, # and the fraction of pairs indistinguishable from chance. report = diagnose.diagnose(X) # LAYER 2 — q is a DECLARED hypothesis about where the social signal lives. # low q = rare, diagnostic types (closer to homology; noisier) # high q = common types (stable; vulnerable to functional convergence) S = hill.hill_overlap_matrix(X, q=0.5) # LAYER 3 — an edge exists because it is significant, not because it beat a threshold. bb = backbone.residual_backbone(X, n_null=500) signed = bb.signed_backbone() # +1 tie, -1 BOUNDARY, 0 chance # THE CHECK EVERYONE SHOULD RUN AND ALMOST NOBODY DOES. # Under any defensible social model this should be ~0. cent = evaluate.eigen_centrality(np.clip(S, 0, None)) print(uncertainty.size_artefact(X, cent)) demo_pipeline.py is a complete worked example of the five-step protocol from §6.2. 5. Known limitations of the code Time-averaging is not modelled by simulate.py. Assemblages are sampled at a single synchronic moment; real assemblages are palimpsests. This makes our tests optimistic (§8.5). Extending the generator here is the most valuable contribution a reader could make. Transmission is neutral (beta=0) in all published runs. The generator supports conformist/anticonformist bias, but we did not explore it. Chao-type corrections have a floor. Below ~30 artefacts per assemblage they are unstable and make the size bias worse. diagnose() warns; the code does not stop you. sdsm_binary has little power on coarse typologies (dense presence matrices). Use residual_backbone there. This is why it is the default. 6. License and citation Code: MIT. Do what you like with it, including disagreeing with it. If the framework is useful, please cite the paper. If you find an error, we would rather hear about it than not: the argument of the paper is that methods should be checkable, and that obligation applies to ours. 7. Supplementary text and the extended manuscript supplementary_text.md contains the material referenced from the article as §S1–§S5: the extended theoretical framework (the full Hill-family exposition and numerical verification), the complete specification of the generative model, the protocol in full, and a pointer to the statistical audit. manuscript_extended_version.md is the unabridged draft (≈22,000 words) from which the submitted article (≈13,300 words) was condensed. It is archived here so that nothing argued in the longer version is lost: every passage cut for length survives in it. Where the two differ, the submitted article is authoritative — the extended version was not re-audited after the final round of corrections. 8. Verifying the empirical tables (one command) verify_tables.py re-derives every number in Tables 7-9 directly from the two published CSVs and checks them against the values printed in the paper, reporting PASS/FAIL for each. It trusts no pre-computed results. python fetch_data.py # downloads the data from the authors' repository python verify_tables.py # ~1-2 min; --fast for a rough check Expected: ALL 12 CHECKS PASSED. The size artefact for Aitchison on the Southwest data comes out at -0.727 and the FDR backbone leaves 94.6 % (Cibola) and 78.8 % (SWSN) of pairs indistinguishable from chance, reproducing the paper. 8. Running the backbone on your own data python backbone_fdr.py mycounts.csv --backbone-csv edges.csv Input: raw integer counts, sites in rows, types in columns. It reports the FDR-controlled number of ties, boundaries, and pairs indistinguishable from chance — and, crucially, a convergence table, so you can see the edge count stabilise rather than trusting a bound. Two traps it protects you from: An empty backbone can be an arithmetic artefact. With B permutations the smallest attainable p is 1/(B+1); if that exceeds the Benjamini–Hochberg threshold, the procedure cannot reject anything and returns zero edges for reasons that have nothing to do with your data. The script warns. No boundaries ≠ no boundaries. On 31 sites (Cibola) not one boundary survives correction; on 223 sites (SWSN) 2,535 do. A negative boundary result on a small network is a power problem, not a finding. The script says so. Do not take the worst-case bound (B ≥ 2m/α, ~10⁶ permutations for 223 sites) as a reason not to correct: Benjamini–Hochberg is adaptive, and both our datasets converged by B ≈ 20,000 — three seconds for Cibola, eighteen for the Southwest. 9. Manuscript figures outputs/fig1_workflow.png is Figure 1 of the article (the validation architecture, simplified for print). outputs/fig0_workflow.png is an expanded version of the same diagram, giving the full specification of each stage — the generative model's four steps, the split between what the method sees and what is withheld, the five scoring criteria, and the pathologies specific to each published dataset. It is referenced from the Figure 1 caption. Both are provided as editable SVG (fig1_simple.svg, workflow_diagram.svg). outputs/fig1–fig5 are the five figures in the paper (see outputs/FIGURES.md for the figure→section map). figures.py regenerates them from the CSVs; md2docx.js is the markdown→Word converter used to build the manuscript, including table and figure embedding. Neither is needed to use arqsim — they are included for completeness of the reproduction chain.