archeoViz
is a packaged R Shiny application for the visualisation, exploration, and web communication of archaeological spatial data. It includes interactive 3D and 2D visualisations, can generate cross sections and maps 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:
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 ("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 lang
parameter.
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 fulfill three objectives:
In addition, archeoViz
is a suitable pedagogical resource for teaching spatial analysis in archaeology, data structuring, open science, and reproducible workflow.
N.B.: consequently, archeoViz
is not intended to replace more sophisticated analysis tools (e.g., GIS, statistical packages, etc.)
Three types of data can be loaded in archeoViz
:
The tables must be CSV files with the first row containing the column labels. Contents in HTML are allowed. This makes it possible, in particular, to add links to external resources (e.g., to objects permanent identifier in other databases, or to concepts identifiers in standard ontologies / thesaurii, etc.).
Formatting your data can be done:
objects table,
using the SEAHORS application to load your data, define the variables (in the “Load data” tab), and export it to the archeoViz
format (in the “Table” / “archeoViz exports” tab). It is also possible to directly send the data to an online archeoViz
instance.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.x.square.labels
and add.y.square.labels
parameters of the archeoViz()
function in order to add the missing labels (on the X and Y axes of the grid, respectively).A data table with two columns can be uploaded for refitting data (CSV format). Each row must contain the unique identifiers of two refitting objects (corresponding to the values of the id
column in the objects table).
A table (CSV format) can be uploaded about excavation history. Row gives the year when each grid square of the site was excavated or surveyed. This table must include the following variables:
There are four ways to input data in archeoViz
:
archeoViz
function’s parameters, in the R interface;archeoViz
.The three types of tables can be loaded in the “Input data” tab. The CSV separator (one of: comma, semicolon, tabulation) and the character used for decimal points (period or comma).
Using randomly generated data is made possible for demonstration purposes. 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.
The URL of an online instance of archeoViz
can include the parameters:
objects.df=
timeline.df=
whose values must be the URL of a CSV file observing the archeoViz
format described above. For example: https://analytics.huma-num.fr/archeoviz/en/?objects.df=https://zenodo.org/record/8003880/files/bilzingsleben.csv
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 may have been recorded in different, more or less precise ways: on the one hand, exactly with points (located by a triplet of x, y and z coordinates) and, on the other hand, more or less imprecisely with lines, planes, or within volumes (with different sets of x, y and/or z value pairs). In archeoViz
, a distinction is made between exact location (points) and other types of vague location (located on lines, planes, and volumes). Both types of locations (exact and vague) can be displayed, and location uncertainties can also be visualised as lines, planes and volumes. This last option is resource intensive, and using it with too much data can significantly slow down the application.
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 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
.
Refittings are usually recorded by archaeologists 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:
objects.df
table (e.g. object_refits
) and are represented by the color of points in the plots (as for any other variable);refits.df
table 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 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
).
archeoViz
is, by definition, an interactive application. However, several features guarantee the reproducibility and communicability of the result of interactions with the application.
The 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.ratio = 1, 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 = c(0, 0, 0), camera.eye = c(1.25, 1.25, 1.25),
run.plots = FALSE, html.export = TRUE
)
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
)
An instance of archeoViz
deployed online on a server can be set with URL parameters. Supported parameters include:
objects.df
, refits.df
, timeline.df
title
, home.text
reverse.axis.values
, reverse.square.names
square.size
add.x.square.labels
, add.y.square.labels
class.variable
, class.values
default.group
location.mode
map.density
, map.refits
plot3d.hulls
, plot3d.surfaces
, plot3d.refits
sectionX.refits
sectionY.refits
run.plots
(The following parameters are not supported in the current version: map.z.val
, sectionX.x.val
, sectionX.y.val
, sectionY.x.val
, sectionY.y.val
, lang
, set.theme
, camera.center
, camera.eye
, html.export
.)
The parameters must be written using the URL syntax (?param1=value¶m2=value2) and have the same type of values than when used in the R interface. For example, the following URL launches an archeoViz
instance using the Bilzingsleben dataset:
This URL does the same, but also includes the refitting table (parameter &refits.df=
) and set the activate the display of the refitting relationships in the 3D and map plots:
The following URL launches the Bilzingsleben dataset, pre-setting the app to:
default.group
, with walue by.variable
instead of by.layer
)class.values
)square.size
, 500 cm instead of the 100 cm default value)run.plots
)title
)home.txt
)Note that the parameters add.x.square.labels
, add.y.square.labels
, location.mode
, and class.values
, which accept simple or multiple values in the R interface (e.g. c(“value1”, “value2”)) only accept one value when set as URL parameters (this is a restriction due to the URL syntax).
The 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.