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 app interface is available in English, French, Italian, and Portuguese.
archeoViz can be used in two ways:
The package can be installed from CRAN with:
The development version is available on GitHub and can be installed with:
Then, load the package and launch the app with:
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
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 ("en": English, "fr": French, "it": Italian, "pt": Portuguese) set.theme = "cosmo") # graphic theme for the Shiny interface
The possible values for the
set.theme parameter are illustrated on this page. The language of the application can be set with the
Demonstration instances of the application are deployed on the Huma Num Shiny server:
Real use cases are presented on the archeoViz Portal.
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:
archeoViz is not intended to replace more sophisticated analysis tools (e.g., GIS, statistical packages, etc.)
There are three ways to input data in
archeoVizmain 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). Contents in html are allowed. This makes possible, in particular, to add links to external resources (e.g., the permanent identifier of the object’s in other databases, or of the concepts used to describe the object, etc.).
A row describes a single object with the following mandatory fields:
In addition, optional fields are possible, including:
object_and have different suffixes)
The labels of the squares of the grid:
add.y.square.labelsparameters of the
archeoViz()function in order to add the missing labels (on the X and Y axes of the grid, respectively).
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’s launching function (
archeoViz()) can be run without parameter
or by using the
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”, “Map”, “Section X”, and “Section Y” tabs, 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
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
Refitting are usually recorded by archaologists in two ways:
Although the second data structure is more accurate, the first is more commonly used.
archeoViz processes the two data structures in different ways:
object_refits) and are represented by the color of points in the plots (as for any other variable);
refits.dftable and are visualised as segments connecting the refitting objects in the plots.
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
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
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
archeoViz is, by definition, an interactive application. However, several features guarantee the reproducibility and communicability of the result of interactions with the application.
archeoViz() function can be set with multiple optional parameters, related to:
archeoViz(objects.df=NULL, refits.df=NULL, timeline.df=NULL, title=NULL, home.text=NULL, lang="en", set.theme="cosmo", square.size = 100, reverse.axis.values = NULL, reverse.square.names = NULL, add.x.square.labels = NULL, add.y.square.labels = NULL, class.variable = NULL, class.values = NULL, default.group = "by.layer", location.mode = NULL, map.z.val = NULL, map.density = "no", map.refits = NULL, plot3d.hulls = NULL, plot3d.surfaces = NULL, plot3d.refits = NULL, sectionX.x.val = NULL, sectionX.y.val = NULL, sectionX.refits = NULL, sectionY.x.val = NULL, sectionY.y.val = NULL, sectionY.refits = NULL, camera.center = NULL, camera.eye = NULL, run.plots = FALSE )
archeoViz(square.size = 100, reverse.axis.values = NULL, reverse.square.names = NULL, add.x.square.labels = NULL, add.y.square.labels = NULL )
archeoViz(class.variable = NULL, class.values = NULL, default.group = "by.layer", location.mode = NULL, map.z.val = NULL, map.density = "no", map.refits = NULL, plot3d.hulls = NULL, plot3d.surfaces = NULL, plot3d.refits = NULL, sectionX.x.val = NULL, sectionX.y.val = NULL, sectionX.refits = NULL, sectionY.x.val = NULL, sectionY.y.val = NULL, sectionY.refits = NULL, camera.center = NULL, camera.eye = NULL )
archeoViz application and package is developed and maintained by Sébastien Plutniak. Arthur Coulon, Solène Denis, Olivier Marlet, and Thomas Perrin tested and supported the project in its early stage. Renata Araujo and Sara Giardino translated the application into Portuguese and Italian, respectively.