paper.md

title	tags	authors	affiliations	date	bibliography	toccolor	citecolor	linkcolor	urlcolor	output
archeoViz: an R package for the Visualisation, Exploration, and Web Communication of Archaeological Spatial Data	R archaeology archeology data visualisation data vizualisation spatial analysis spatial statistics	name orcid affiliation Sébastien Plutniak 0000-0002-6674-3806 1	name index CNRS, CITERES-LAT, Université de Tours, Tours, France 1	7 December 2023	paper.bib	teal	teal	teal	teal	pdf_document toc toc_depth number_sections false 4 true

Summary

archeoViz is an R Shiny application for the visualisation, interactive exploration, and web communication of archaeological spatial data [@Plutniak2023archeoviz1.3.3; @Plutniak2023bspf]. It generates interactive 3D plots, 2D cross sections and 2D maps of archaeological objects and their refitting relationships, and display an interactive timeline of the work made in a site. Spatial statistics methods can be applied (convex hull, regression surfaces, 2D kernel density estimation) and data can be directly exported to other online applications to run other methods. This application is designed as the building block of a decentralised web edition network for archaeological data: 1) users can deploy archeoViz instances specific to their datasets on the server of their choice; 2) the archeoViz Portal, a companion online application, references and documents with metadata these archeoViz instances, increasing their discoverability and audience on the web, both for scientists and the general audience interested in archaeology. It can also be used as an educational resource to introduce learners to spatial analysis, data formats, reproducible workflow, open science, and computational archaeology.

Statement of Need

For more than a century, archaeologists have generated spatially coordinated data during fieldwork. However, the results of these efforts are generally kept in inaccessible notebooks and hard drives, or –in the best cases– analysed and summarised as figures in publications, without providing the original data. Recent literature stressed that the lack of

1. accessible and handy tools,
2. training in data management,
3. time to prepare data for publication, and
4. recognition related to data publishing

are factors explaining the insufficient availability of field archaeological data [@SelhoferGeser2015; @Bernard2019]. Given the reluctance of archaeologists to publish data, archeoViz indirectly fosters data publication by demonstrating reuse, from the case of spatial archaeological data at the site level [@Plutniak2023archeoviz1.3.3; @Plutniak2023bspf].

Its minimal and multilingual interface (viz. issue 1) and the simple data structure it requires (viz. issues 2, 3) make it handy to use and fast to deploy on the web. This contributes to promoting datasets as citable scientific outputs and also provides recognition to their creators (viz. issue 4).

State of the Field

Archaeological Visualisation Software

First, archeoViz is related to other archaeological visualisation software relying on similar technologies. However, this software differs with regard to their specialisations and are available in various formats as scripts, applications, or packages:

• Dataset-specific scripts or web applications:
  • Shannon McPherron's R Shiny Plot it application (unpublished),
  • Anthony Sécher's PyCoCu python script,
• R Shiny application implementing specific statistical methods, e.g. [@CouilletEtal2022],
• R packages:
  • recexcavAAR [@SchmidSerbe2017] (no longer maintained)
  • SEAHORS [@RoyerEtal2023], which offers more advanced visualisation features than archeoViz while being limited to this aspect.

Geographic Information Systems

Second, archeoViz is a lightweight, complementary alternative to more complex archaeological software, e.g. ArchField [@SmithEtal2015], Aspectus [@VurpillotEtal2018], a “4D system” [@OrtegaalvaradoEtal2022] and to the more demanding association of GIS software and export libraries, e.g. Potree, GeoNetwork or QGIS and its Qgis2threejs plugin to export in HTML format.

Online Data Repositories

Third, regarding data publication and versioning, archeoViz relates to web repositories that include visualisation features, e.g. arkeoGIS [@Bernard2019], BDA [@Perrin2019], Field, and CyberSW. It differs in being a stand-alone application, in focusing on intra-site data and the representation of individual archaeological objects, and in taking into account the third spatial dimension. Unlike these centralised repositories, archeoViz is designed as the building block of a decentralised web edition network for archaeological data, made of as many archeoViz instances as there are datasets.

The Building Block of a Decentralised Web Edition Network for Archaeological Data

Since the 1960s, numerous attempts at building up standards and repositories were made in archaeology. All projects tended to collect as much data as possible and several independent databases existed with the same themes. The pitfalls of this centralised approach were addressed in the early 2000s with the development of the semantic web, ontologies, and linked open data technologies.

archeoViz is designed along the same line. Rather than collecting all data in the same place as in the centralised approach, archeoViz users create a particular instance of archeoViz for each dataset to visualise and communicate. These instances can be deployed on the server of their choice (e.g., shinyapps.io, huma-num, or any other institutional or personal server). Nevertheless, archeoViz can be used in four ways, from purely local (on the user’s machine), to purely remote, assuming or not data publication on third-party repositories (\autoref{fig:workflow}).

Key Features

Interface and Functionalities

The archeoViz interface is available in several languages, namely English, Italian, French, German, Spanish, Portuguese, and Romanian. This interface has two parts (\autoref{fig:interface}):

• a left-side menu with options for data sub-selections
• a right-side panel with tabs to display the results of the functionalities.

These functionalities include:

• Interactive visualisations and exports (SVG and HTML) of:
  • 3D plot
  • 2D map plot
  • 2D section plot on the X axis
  • 2D section plot on the Y axis
• Summary statistics and data export to third-party applications
• Reproducibility features, i.e. automatic generation of the command line to reproduce the current setting of the application
• Timeline of the findings discovery
• Guidelines for the application

Data Input

Input data must be CSV files, loaded either through the application interface or in the command line, using the launching function's parameters. The data structure is kept as simple as possible, with (few) mandatory and some optional variables (\autoref{tab:input}).

\scriptsize

id	square_x	square_y	xmin	xmax	ymin	ymax	zmin	zmax	layer	object_type	object_misc
1	A	1	50	54	66	70	20		1	lithic	biface
2	B	2	130		144		30	35	2a	fauna	deer antler

: \normalsize Example of an input CSV file. Mandatory variables are in bold type. “max” coordinates are for objects inaccurately located within a range. An unlimited number of variables named using the “object_” prefix can be added. \label{tab:input}

\normalsize

Research Using archeoViz

So far, 43 datasets have been edited on the web using archeoViz instances. They include about 370,000 objects and 11,000 refitting relationships (between fragments of broken objects). To increase their discoverability and audience, the archeoViz Portal gathers their references and metadata, and makes it possible to browse the list of instances with keywords and through a map.

Interoperability between software tools is key to their diffusion and adoption. The SEAHORS package [@RoyerEtal2023] can generate CSV files in the archeoViz format and send them to an online archeoViz instance. Data can be exported from archeoViz to

• the archeofrag application for refitting analysis
• the seriograph application for seriation
• an online instance of the explor R package / Shiny application for correspondence analysis
• the AMADO online application, for seriation and classification.

Resources and Examples

archeoViz is available on CRAN and the code of the development version is available on Github. Documentation is made available embedded in the application (Guidelines tab) and as Vignettes, in English, French, and Spanish. A website presents the application in a less technical way, https://archeoviz.hypotheses.org. Users can receive news and find support by subscribing to the archeoViz mailing list. Multiple use cases can be browsed through the archeoViz Portal, that are also referenced in the HAL.science and Isidore repositories.

Acknowledgements

archeoViz is an R Shiny [@ChangEtal2020] application embedded in an R package [@Rcoreteam2023]. It relies on the plotly [@Sievert2020], ggplot2 [@Wickham2016], and htmlwidgets [@VaidyanathanEtal2023] packages for the graphical outputs, and spatial statistics use functions from the cxhull [@Laurent2023] and mgcv [@Wood2017] packages.

I thank Anaïs Vignoles and Élisa Caron-Laviolette (co-maintainers of the archeoViz Portal), Renata Araujo (Portuguese translation), Laura Coltofean (Romanian translation), Nicolas Delsol (Spanish translation), Sara Giardino (Italian translation), Julian Laabs (German translation), and the early users for their feedback and support: Astolfo Araujo, Jean-Pierre Chadelle, Elsa Defranoult, Solène Denis, Emmanuel Discamps, Mathieu Langlais, Maureen Le Doaré, Grégor Marchand, Jean-Claude Marquet, Alexandre Michel, Thomas Perrin, Anthony Sécher, Peter Tóth. Finally, I acknowledge the tDAR team at the Center for Digital Archaeology, where this paper was written and the SEADDA European COST action that funded this research stay.

References