# archeoViz: an R package for the Visualisation, Exploration, and Web Communication of Archaeological Spatial Data

Sébastien Plutniak

<figure><img src="image_1.png" /></figure>

## To cite this version:

Sébastien Plutniak. archeoViz: an R package for the Visualisation, Exploration, and Web Communication of Archaeological Spatial Data. Journal of Open Source Software, 2023, 8 (92), pp.5811. 10.21105/joss.05811. hal-04360514

HAL Id: hal-04360514

https://hal.science/hal-04360514v1

Submitted on 21 Dec 2023

HAL is a multi-disciplinary open access
archive for the deposit and dissemination of sci-
entific research documents, whether they are pub-
lished or not. The documents may come from
teaching and research institutions in France or
abroad, or from public or private research centers.

L'archive ouverte pluridisciplinaire HAL, est
destinée au dépôt et à la diffusion de documents
scientifiques de niveau recherche, publiés ou non,
émanant des établissements d'enseignement et de
recherche français ou étrangers, des laboratoires
publics ou privés.

<figure><img src="image_2.png" /></figure>

Distributed under a Creative Commons CC BY 4.0 - Attribution - International License
# archeoViz: an R package for the Visualisation, Exploration, and Web Communication of Archaeological Spatial Data

Sébastien Plutniak 1

1 CNRS, CITERES-LAT, Université de Tours, Tours, France

DOI: 10.21105/joss.05811

## Software

* Review ⚙️

* Repository ⚙️

* Archive ⚙️

Editor: Olivia Guest ⚙️

## Reviewers:

* @bischrob

* @nevrome

* @joeroe

Submitted: 02 June 2023

Published: 11 December 2023

## License

Authors of papers retain copyright and release the work under a Creative Commons Attribution 4.0 International License (CC BY 4.0).

## Summary

archeoViz is an R Shiny application for the visualisation, interactive exploration, and web communication of archaeological spatial data (Plutniak et al., 2023; Plutniak, 2023). 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 (Bernard, 2019; Selhofer & Geser, 2015). 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 (Plutniak et al., 2023; Plutniak, 2023).

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. (Couillet et al., 2022),

* R packages:

- recexcavaAR (Schmid & Serbe, 2017) (no longer maintained)

- SEAHORS (Royer et al., 2023), 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 (Smith et al., 2015), Aspectus (Vurpillot et al., 2018), a "4D system" (Ortega-Alvarado et al., 2022) 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 (Bernard, 2019), BDA (Perrin, 1960), 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 (Figure 1).
<figure><img src="image_3.png" /><figcaption>**Figure 1:** The four ways to use archeoViz: local (green solid line), remote and dynamic (dashed line), remote and static with data publication on a third party service (black solid line), remote and static without data publication (blue solid line).</figcaption></figure>

# 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 (Figure 2):

* 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
<figure><img src="image_4.png" /><figcaption>Figure 2: archeoViz interface.</figcaption></figure>

## 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 (Table 1).

<table><caption>Table 1: 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.</caption><thead><tr><th>id</th><th>square_x</th><th>square_y</th><th>xmin</th><th>xmax</th><th>ymin</th><th>ymax</th><th>zmin</th><th>zmax</th><th>layer</th><th>object_type</th><th>object_misc</th></tr></thead><tbody><tr><td>1</td><td>A</td><td>1</td><td>50</td><td>54</td><td>66</td><td>70</td><td>20</td><td>1</td><td>lithic</td><td></td><td>biface</td></tr><tr><td>2</td><td>B</td><td>2</td><td>130</td><td></td><td>144</td><td></td><td>30</td><td>35</td><td>2a</td><td>fauna</td><td>deer antler</td></tr></tbody></table>

## 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 (Royer et al., 2023) 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 (Chang et al., 2020) application embedded in an R package (R Core Team, 2023). It relies on the plotly (Sievert, 2020), ggplot2 (Wickham, 2016), and htmlwidgets (Vaidyanathan et al., 2023) packages for the graphical outputs, and spatial statistics use functions from the cxhull (Laurent, 2023) and mgcv (Wood, 2017) 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

* Bernard, L. (2019). *Ten years of ArkeoGIS: Feedback on the challenges and benefits of digitally sharing archeological data*. https://hal.science/hal-02865759

* Chang, W., Cheng, J., Allaire, J. J., Xie, Y., & McPherson, J. (2020). *shiny: Web application framework for R*. https://CRAN.R-project.org/package=shiny

* Couillet, A., Rougier, H., Todisco, D., Marot, J., Gillet, O., & Crevecoeur, I. (2022). New visual analytics tool and spatial statistics to explore archeological data: The case of the paleolithic sequence of La Roche-à-Pierrot, Saint-Césaire, France. *Journal of Computer Applications in Archaeology*, 5(1), 19–34. https://doi.org/10.5334/jcaa.81

* Laurent, S. (2023). *cxhull: Convex hull*. https://CRAN.R-project.org/package=cxhull

* Ortega-Alvarado, G.-F., Lidia M., Conde-Rodríguez, F., & Jurado-Rodríguez, J. M. (2022). Integrated and interactive 4D system for archaeological stratigraphy. *Archaeological and Anthropological Sciences*, 14(203). https://doi.org/10.1007/s12520-022-01667-3

* Perrin, T. (1960). BDA : une Base de Données Archéologique collaborative en ligne. *Bulletin de la Société préhistorique française*, 116(1), 159-162. https://doi.org/10.3406/bspf.2019.14988

* Plutniak, S. (2023). Visualiser et explorer la distribution spatiale du mobilier archéologique: l'application archeoViz et son portail web. *Bulletin de la Société préhistorique française*, 120(1), 70-74.

* Plutniak, S., Araujo, R., Coltofean, L., Delsol, N., Giardino, S., & Laabs, J. (2023). *archeoViz. Visualisation, exploration, and web communication of archaeological spatial data*. https://doi.org/10.5281/zenodo.10200892

* R Core Team. (2023). *R: A language and environment for statistical computing*. R Foundation for Statistical Computing. https://www.R-project.org/
Royer, A., Discamps, E., Plutniak, S., & Thomas, M. (2023). SEAHORS: Spatial exploration of ArcHaeological objects in R shiny. *Peer Community Journal*, 3(e55). https://doi.org/10.24072/pcjournal.289

Schmid, C., & Serbe, B. (2017). *recexcavAAR: 3D reconstruction of archaeological excavations*. https://CRAN.R-project.org/package=recexcavAAR

Selhofer, H., & Geser, G. (2015). *D2.2 second report on users' needs* [Ariadne WP15 Study]. Ariadne. http://legacy.ariadne-infrastructure.eu/wp-content/uploads/2019/01/ARIADNE_D2.2_Second_report_on_users_needs.pdf

Sievert, C. (2020). *Interactive web-based data visualization with R, plotly, and shiny*. Chapman & Hall/CRC. https://doi.org/10.1201/9780429447273

Smith, N. G., Howland, M., & Levy, T. E. (2015). Digital archaeology field recording in the 4th dimension: ArchField c++ a 4D GIS for digital field work. *2015 Digital Heritage, 2*, 251–258. https://doi.org/10.1109/DigitalHeritage.2015.7419505

Vaidyanathan, R., Xie, Y., Allaire, J., Cheng, J., Sievert, C., & Russell, K. (2023). *htmlwidgets: HTML widgets for R*. https://CRAN.R-project.org/package=htmlwidgets

Vurpillot, D., Verriez, Q., & Thivet, M. (2018). Aspectus: A flexible collaboration tool for multimodal and multiscalar 3D data exploitation. *Studies in Digital Heritage, 2*(2), 150–165. https://doi.org/10.14434/sdh.v2i2.24446

Wickham, H. (2016). *ggplot2: Elegant graphics for data analysis*. Springer-Verlag. https://doi.org/10.1007/978-3-319-24277-4

Wood, S. N. (2017). *Generalized additive models: An introduction with R* (2nd ed.). Chapman; Hall/CRC. https://doi.org/10.1201/9781315370279