archeoViz is a packaged R Shiny application for the visualisation, exploration, and web communication of archaeological excavation data. It includes interactive 3D and 2D visualisations, can generate cross sections and map of the remains, can run basic spatial statistics methods (convex hull, regression surfaces, 2D kernel density estimation), and display an interactive timeline of an excavation. archeoViz can be used locally or deployed on a server, either by allowing the user to load data through the interface or by running the app with a specific data set. The interface is available in English and in French.
archeoViz can be used in two ways:
The package can be installed from GitHub with:
Then, load the package and launch the app with:
To deploy archeoViz on your Shiny server, first download and unzip the package:
# set the working directory on your shiny server:
setwd(dir = "/some/path/")
# download the package:
download.file(
url = "https://github.com/sebastien-plutniak/archeoviz/archive/master.zip",
destfile = "archeoviz.zip")
# unzip it:
unzip(zipfile = "archeoviz.zip")Then, go to https://<your-shiny-server>/archeoviz-main.
To set the app with your data and preferences, edit the app.R file, located at the root of the directory:
archeoViz(objects.df = NULL, # data.frame with data about the objects
refits.df = NULL, # optional data.frame for refitting data
timeline.df = NULL, # optional data.frame for the excavation timeline
title = NULL, # title of the site / data set
home.text = NULL, # html content to display on the home page
lang = "en" # interface language (English or French)
set.theme = "cosmo") # graphic theme for the Shiny interfaceThe possible values for the set.theme parameter are illustrated on this page. The language of the application can be set with the lang parameter, either with an “en”/“English” or “fr”/“French” value.
Demonstration instances of the application are deployed on the Huma Num Shiny server:
For a real case use, see the example of the prehistoric Poeymaü cave in the Pyrenees (note that this application is a modified version of archeoViz).
If you encounter a bug, please fill an issue with all the details needed to reproduce it.
Suggestions of changes to archeoViz are welcome. These requests may concern additional functions, changes to documentation, additional examples, new features, etc. They can be made by filling an issue and, even better, using pull requests and the GitHub Fork and Pull model.
Having archaeological remains from a given site, archeoViz is designed to lower the technical barriers to fulfil three objectives:
N.B.: consequently, archeoViz is not intended to replace more sophisticated analysis tools (e.g., GIS, statistical packages, etc.)
There are three ways to input data in archeoViz:
archeoViz main function’s parameters before running the application.Tables for three types of data can be uploaded from the “Input data” tab:
The tables must be .csv files with the first row used containing the columns’ labels (the separator can be set). More details about the required formats and columns are provided in the “Input data” tab.
For demonstration purposes using randomly generated data is made possible. To activate this feature, set the slider in “Input data” to a value higher than 0 (setting the value back to 0 deactivates the feature). An “objects” data set, a “refits” data set, and a “timeline” data set are generated, making it possible to test all the archeoViz functionalities.
archeoViz’s launching function (archeoViz()) can be run without parameter
or by using the objects.df, refits.df, or timeline.df parameters to input data.frames about the archaeological objects, refitting relationships between these objects, and the chronology of the excavation, respectively.
Once data are loaded, a sub-selection of the data set can be done in the left side menu. Several parameters are possible: the type of location recording, the category of the objects, and the way to group the data.
The location of archaeological objects can be recorded in different ways, depending on the precision of the data: as points (xyz coordinates), on lines, plans, or within a volume (ranges of x, y, and z values). In archeoViz, a distinction is made between exact locations (points) and the other types of fuzzy location methods (lines, plans, volumes). The radio buttons allow selecting these options.
Sub-sets can be defined by object categories, using the “variable” and “values” fields. Once one of the “object_type” (or other possible “object_” variables) is selected, its values appear below and can be selected using the tick boxes. The selection must be validated by clicking on the “Validate” button. This selection determines the data that will be displayed in the plots and tables.
The data can be grouped in two ways: either by layer or by the selected “object_” variable. This option determines the colours of the points in the 3D and 2D plots and the subsets when computing surfaces and convex hulls.
In the “3D plot” tab, clicking on a point displays information about that point in the table below the plot.
The plots in the “3D plot”, “Map”, “Section X”, and “Section Y” tabs are generated using the plotly library. All the plots are dynamic and include a menu bar above the plot with several options (generating an image file, zooming, moving the view, etc). See details on the plotly website.
Clicking on a legend’s item modifies the display:
This feature makes it possible to choose which layers are shown. In addition, the size of the points can be set and whether the refitting relationships must be represented or not.
Several graphical outputs can be generated in archeoViz.
plotly include an export function in .svg format.archeoViz includes some spatial analysis functionalities, intended for basic and exploratory use.
In the “3D plot” tab, clicking on “Compute surfaces” and “Validate” displays the regression surface associated with each layer (with at least 100 points). The surfaces are computed using the generalized additive model implemented in the mgcv package.
In the “3D plot” tab, clicking on “Compute hulls” and “Validate” displays the convex hull associated with each layer (with at least 20 points). The convex hulls are computed using the cxhull package.
In the “Map” tab, ticking the “Compute density” box and clicking on “Validate” generates a map with contour lines showing the points’ density. Density can be computed for all the points together or by layer (with at least 30 points). The 2D kernel density is computed with the kde2d function of the MASS package (through ggplot2).