/archaeoriddle

CDAL collaborative ABM

Primary LanguageR

DOI

The Archaeoriddle

If you don't know where to start, you may want to have a look at thearchaeoriddle.com!

Preamble

The Archaeoriddle Project has been implemented and developed by the Computational and Digital Archaeology Lab at the McDonald Institute, University of Cambridge, based on ideas from Enrico Crema and Xavier Rubio-Campillo. It is primarily funded by a grant from the British Academy (SRG2223\230262) and the Marie SkΕ‚odowska-Curie Actions (H2020-MSCA-IF No. 101020631/ArchBiMod), but would not have been possible without support from the ENCOUNTER project (ERC grant agreement No. 801953).

This repository compile together all the elements developed throughout this project. They can be divided in three main components, that are all detailed later in this file.

  1. The Bookdown : a compiled version is available online here. This standalone document details every aspect of the project. It should allow the reproduction and exploration of every aspect of the project ( πŸ“ ./doc/bookdown/).
  2. The Original Challenge one instance of archaeoriddle's simulation, including the website, data and 5 participants contribution ( πŸ“ ./doc/shinyapp/ & ./doc/bookdown/data_original/).
  3. The R package : contains all the above and the underlying R-functions, tests and associated documentation ( πŸ“ ./)

This repository has the structure of an R package. This allows each sub-component of the Archaeoriddle to easily use and call functions and data shared common to the different part of the project. It also greatly simplify the use of the different functions used throughout the bookdown for anyone who would like to play and recreate its own Archaeoriddle world.

Note: The version v0.1.2 of this repository is the last version that has been shared with reviewers during the revision process of the paper "Assessing the inferential power of quantitative methods in archaeology via simulated datasets: the archaeoriddle challenge", by: Cortell-Nicolau, A., Carrignon, S., RodrΓ­guez-Palomo, I., Hromada, D., Kahlenberg, R., Mes, A., Priss, D., Yaworsky, P., Zhang, X., Brainerd, L., Lewis, J., Redhouse, D., Simmons, C., Coto-Sarmiento, M., Daems, D., Deb, A., Lawrence D., O’Brien, M., Riede, F., Rubio-Campillo, X., Crema, E.

This version includes the modifications asked by the reviewers and is the one archived on zenodo with this DOI: 10.5281/zenodo.14024548.

The Bookdown

This is the main outcome of the Archaeoriddle project, detailing all the other sub-components. An online version is available at: www.thearchaeoriddle.org. It is associated with a forum intended to be a place where anyone can come to discuss the project, issues encountered while using the package or simply curious to explore and exchange about inference in archaeology in general.

The Archaeoriddle bookdown guides you through the Archaeoriddle project, allowing you to follow everything step and decision taken ; which models have been chosen at different level and why. Coupled with the functions provided by the R package, you will be able to use code chunks to reproduce elements of interest yourself, create your own world, with its unique mountains, seas, and islands. You will be able to generate settlements, distribute populations that fluctuate based on parameters you will choose. The bookdown also facilitates recreating your own challenge. It will take you through all steps to generate your own radiocarbon deposits and create output files to share with students or colleagues and find out who can infer your original parameters.

The source for the bookdown is stored in doc/bookdown/. This folder contains all the files and documents needed to compile the Archaeoriddle's bookdown. It also houses the output and original files shared for the original Archaeoriddle's challenge.

If you want to compile the bookdown yourself, we invite you to read this chapter of the bookdown.

Useful files & folders for this component:

If you compile the bookdown yourself, some folder will be generated (data_tmp and data_toshare) that will be used to store file generated during the compilation (the new world, csv outputs, etc...). Here a quick overview of what they will look like:

The Original Challenge

The Original Challenge correspond to a specific instance of the archaeoriddle, called 'Rabbithole'. This includes : a landscape, an 'ecological map', a set of parameters that have been used to carry set of simulations among which one has been chosen. From the outcome of the simulation, carbon deposit have been generated and csv with list of C14 dates create. The map of the landscape and the ecological raster, togethe with a select set of csv file among these generated where shared publicly with archaeologists via an online website. The website is still available here on the 1st of November 2024, but will probably disappear anytime soon ; but the source to generate the website are provided in this repository here.

On the website, three research questions were asked:

  • RQ1. What was the relationship between the two groups? Was it peaceful or hostile?
  • RQ2. What was the population trajectory of each group?
  • RQ3. What was the rate of dispersal of poppy chewers?

Via the website, everyone had access to fou squares representing 4 zones of 'Rabbithole' from which data about occupation was given. People who wanted to participate were then able to request five additional zones that will be 'excavated' for them and they then received datasets covering the zones they picked.

Map of rabbithole with square Map of rabbithole
Map of publicly available sites of Rabbithole: On the left, the squares available; on the right, the names and cultures of the settlements.

Proposals

The original challenge received 5 proposals that can be explore via the links below. A snapshot of the proposals the way they were provided by the authors after the revision process are also provided on the zenodo repository. We here briefly summarize the proposal and give links to the original source of them.

P1 by Deborah Priß and Raphael Kahlenberg

Authors used agent-based modeling combined with exploratory data analysis to study dispersal and site preference in Rabbithole, using ArcGIS Pro and R for calibration and trajectory computation, resulting in an ABM built with NetLogo that correctly predicted group interactions and movements but revealed discrepancies in expansion rates due to differing population trajectories.

Source: https://github.com/dpriss/Archaeoriddle_Kahlenberg_Priss

Citation: Priß, D., & Kahlenberg, R. (2024). dpriss/Archaeoriddle_Kahlenberg_Priss: Archaeoriddle Kahlenberg and Priß (v1_Archaeoriddle). Zenodo. https://doi.org/10.5281/zenodo.14062675

P2 by Xuan Zhang

The author employed point-process modeling to predict potential occupation and assess conflict between groups, finding increased hostilities and mortality over time due to growing populations and settlements, despite non-time-dependent hostility rules.

Source: https://github.com/Xuan-Zhang-arc/Archaeoriddle_PPM_HG_F_relationship/

Citation: Xuan Zhang. (2024). Using Point Process Modelling to detect cooperation vs competition (Archaeoriddle RQ1) (Archaeoriddle). Zenodo. https://doi.org/10.5281/zenodo.12803445

P3 by Peter Yaworsky

The author utilized species-distribution modeling in R to develop a four-stage approach that successfully modeled historical population distributions and dispersal patterns of farmers and foragers, highlighting a southerly to northerly farming dispersal and a decline in hunter-gatherer populations.

Source: https://doi.org/10.5281/zenodo.8260754

Citation: Yaworsky, P. (2023). Archeo-Riddle Submission 2023. Zenodo. https://doi.org/10.5281/zenodo.8260754

P4 by Alexes Mes:

The author employed a friction-based strategy and hierarchical Bayesian phase modeling in R to analyze and successfully predict the complex dispersal patterns and expansion rates of Poppy-chewers in Rabbithole, incorporating spatial and environmental factors.

Source: https://github.com/AlexesMes/Archeaoriddle_RabbitWorld

Citation: Alexes, M. (2024). Archeaoriddle RabbitWorld. Zenodo. https://doi.org/10.5281/zenodo.14218979

P5 by Daniel Hromada

The author used a qualitative analysis to infer hostility between Poppy-chewers and Rabbit-skinners by comparing the shorter settlement persistence of Rabbit-sinner in the region Poppy-chewers exist, separated by a sea, to its persistence in other regions under equal conditions.

Source: here and here

Citation: Hromada, D. (2024). Exploring the 'Hostile vs. Peaceful' Archaeoriddle Dilemma Using the NALANA Method. 10.13140/RG.2.2.10753.47207.

The original challenge is detailed in this chapter of the bookdown.

Useful files & folders for this component:

The R-Package

This overal structure of this repository is a R package. To install it, the most simple way will be by using devtools function github_install() by doing: devtools::install_github("acortell3/archaeoriddle"). Most of the functions defined in the package are described in details in the bookdown.

The package will be used if you want to follow the bookdown or recompile it. It will also allows you to easily re-use the functions defined in the package to re-explore the proposal of the original challenge, create your own model of interaction, explore and modify the underlying model used throughout the Archaeoriddle project.

To install the package, the easiest is probably to use devtools function install_github: devtools::install_github("acortell3/archaeoriddle")

Full file structure:

doc/

man/

  • πŸ“„ A_rates.Rd,πŸ“„ Gpd.Rd,... and all other Rd files: files automatically generated by ROxygen to generate R documentation (shown when using ?Gpd when the package is loaded`

R/