archeoViz Vignette

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.

Installation

archeoViz can be used in two ways:

Local use

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:

Deployed use

To deploy archeoViz on your Shiny server, first download and unzip the package:

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:

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

Demonstration instances of the application are deployed on the Huma Num Shiny server:

Real use cases are presented on the archeoViz Portal.

Community guidelines

Reporting bugs

If you encounter a bug, please fill an issue with all the details needed to reproduce it.

Suggesting changes

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.

Use

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.)

Data input

There are three ways to input data in archeoViz:

  1. uploading tables in the “Input data” tab,
  2. using randomly generated data from the “Input data” tab;
  3. set the archeoViz main function’s parameters before running the application.

Loading files through the Input data tab

Tables for three types of data can be uploaded from the “Input data” tab:

  • an “objects” table (mandatory), with data about the objects;
  • a “refits” table (optional), with data about the refitting objects;
  • a “timeline” table (optional), with data about when each square of the site was excavated.

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.).

Objects table

A row describes a single object with the following mandatory fields:

  • id: alphanumerical value, unique identifier of the object
  • xmin: numerical value, coordinate of the object on the X axis (in cm)
  • ymin: numerical value, coordinate of the object on the Y axis (in cm)
  • zmin: numerical value, coordinate of the object on the Z axis (positive depth value in cm)
  • layer: alphanumerical value, identifier of the object’s layer
  • object_type: alphanumerical value, category of the object

In addition, optional fields are possible, including:

  • square_x: alphanumerical value, identifier of the square on the X axis
  • square_y: alphanumerical value, identifier of the square on the Y axis
  • year : numerical value, year when the object was excavated
  • xmax: numerical value, when the X location of the object is included in a range of X coordinates
  • ymax: numerical value, when the Y location of the object is included in a range of Y coordinates
  • zmax: numerical value, when the Z location of the object is included in a range of Z coordinates
  • object_edit: unlimited number of additional variable describing the object (field names must start with object_ and have different suffixes)

The labels of the squares of the grid:

  • are ordered alpha-numerically;
  • are not displayed, in order to avoid erroneous displays, if the number of labels does not correspond exactly to the total number of 100 cm squares that can be defined in the range of minimum and maximum coordinates contained in the xmin and ymin variables;
  • can be completed with the 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).

Random data

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.

Through function parameters

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.

Data sub-setting

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.

Location mode

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.

Objects category

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.

Data subgroups

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.

Objects selection

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.

Interactive visualisation

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.

Graphical outputs

Several graphical outputs can be generated in archeoViz.

Reffiting

Refitting are usually recorded by archaologists in two ways:

  1. by sets of refitting objects: using a two columns table, where a row corresponds to an object. The first column stores the object’ unique id and the second column stores the id of the set of refitting objects this object belongs to.
  2. by refitting relationships: using a two columns table, where a row corresponds to a relationship. The first column stores the first object’s unique id and the second column stores the second object’s unique id.

Although the second data structure is more accurate, the first is more commonly used.

archeoViz processes the two data structures in different ways:

Spatial statistics

archeoViz includes some spatial analysis functionalities, intended for basic and exploratory use.

Regression surfaces

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.

Convex hulls

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.

2D kernel density

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).

Reproducibility

archeoViz is, by definition, an interactive application. However, several features guarantee the reproducibility and communicability of the result of interactions with the application.

Advanced parameters

The archeoViz() function can be set with multiple optional parameters, related to:

Square grid

  • square.size: numerical. Size (width and height) in centimeter of the squares in the grid system. Default value is 100 cm.
  • reverse.axis.values: character. Name of the axis or axes to be reversed (any combination of “x”, “y”, “z”).
  • reverse.square.names: character. Name of the axis or axes for which to reverse the order of the square labels (any combination of “x”, “y”, “z”).
  • add.x.square.labels: character. Additional square labels for the “x” axis.
  • add.y.square.labels: character. Additional square labels for the “y” axis.

Parameters presetting

  • class.variable: character. At the launch of the app, name of the variable to preselect.
  • class.values: character vector. At the launch of the app, names of the values to preselect.
  • default.group: character. At the launch of the app, preselection of the variable used to group data (one of “by.layer” or “by.variable”).
  • location.mode: character. At the launch of the app, preselection of the location method (one of “exact”, “fuzzy”, “exact.fuzzy”).
  • map.z.val: numerical. Minimal and maximal Z coordinates values to display in the map plot.
  • map.density: character. At the launch of the app, whether to compute and show density contours in the map plot (one of “no”, “overall”, “by.variable”).
  • map.refits: TRUE or FALSE. Whether to show refits in the map plot.
  • plot3d.hulls: TRUE or FALSE. At the launch of the app, whether to compute and show convex hulls in the 3D plot.
  • plot3d.surfaces: TRUE or FALSE. At the launch of the app, whether to compute and show regression in the 3D plot.
  • plot3d.refits: TRUE or FALSE. At the launch of the app, whether to show refits on the 3D section plot.
  • sectionX.x.val: numerical. At the launch of the app, minimal and maximal X coordinates values to display in the X section plot.
  • sectionX.y.val: numerical. At the launch of the app, minimal and maximal Y coordinates values to display in the X section plot.
  • sectionX.refits: TRUE or FALSE. At the launch of the app, whether to show refits in the X section plot.
  • sectionY.x.val: numerical. At the launch of the app, minimal and maximal X coordinates values to display in the Y section plot.
  • sectionY.y.val: numerical. At the launch of the app, minimal and maximal Y coordinates values to display in the Y section plot.
  • sectionY.refits: TRUE or FALSE. At the launch of the app, whether to show refits in the Y section plot.
  • camera.center: numerical. In 3D plot, coordinates of the point to which the camera looks at (default values: x=0, y=0, z=0).
  • camera.eye: numerical. In 3D plot, coordinates of the camera’s position (default values: x=1.25, y=1.25, z=1.25).

Reactive plot display

  • run.plots: TRUE or FALSE. Whether to immediately compute and show plots (without requiring the user to click on the buttons in the interface).

Acknowledgment

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.

References