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, and display an
interactive timeline of the work made in a site. Simple
spatial statistics can be performed (convex hull, regression
surfaces, 2D kernel density estimation), as well as exporting
data to other online applications for more complex methods.
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, German, Italian, Portuguese, Romanian, and Spanish.
Website: https://archeoviz.hypotheses.org.
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 ("de": German, "en": English, "fr": French, "it": Italian, "pt": Portuguese, "es": Spanish)
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:
archeoViz
in German.archeoViz
in English.archeoViz
in French.archeoViz
in Spanish.archeoViz
in Italian.archeoViz
in Portuguese.archeoViz
in Romanian.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.
In the development of archeoViz
, particular attention is
paid to multilingualism. The application interface is available in
several languages and translations into additional languages are
welcome. To do so, please edit this file
and submit a pull request.
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.)
Archaeologists record the location of archaeological objects at different scales and granularity. Accordingly, they use different geometrical concepts to represent location.
Using grid coordinates or electronic “total station” enables
recording the individual location of objects on the field. In that case,
the location are represented as points in archeoViz
(triplets of x, y and z coordinates).
However, it is also common that x, y, z, coordinates by object are not available, for different reasons due to:
In all these cases, we have to deal with vague location, when objects cannot be located as points but are somewhere between ranges of coordinates. Vague location can concern one, two, or the three spatial dimensions (the x, y, z coordinates, respectively).
Note that this feature can also be used to deal with the imprecision of topographical instruments.
Lines are useful geometries for representing relationships. In
archaeology, these can be refitting
relationships between object fragments, orientation (fabric measurements, etc. Lines are
generated from data loaded as refitting data, either from the “Data”
tab, or with the refits.df
parameter of the
archeoViz()
function.
Surfaces are useful geometries for representing ground levels,
trenches, pits, etc. In archeoViz
, this can be achieved by
defining a subset of points summarising the desired surface, then
displaying the convex hull of this
subset.
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 and represents the two data
structures in two ways:
objects.df
table (e.g. object_refits
)
and are represented by the color of points in the plots (like any other
variable);refits.df
table and are visualised as segments connecting
the refitting objects in the plots.So far, archeoViz
does not handle fabric measurements
properly. However, the process used to represent refittings can also
adapted and used to represent fabric measurements. This requires to
distort the data structure as follows:
id
values must be given to the two
points, andSee an example of this method here.
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 / thesauri, 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:
A background drawing can be displayed in the 3D and Map plots. This
feature makes it possible, for example, to show a site map behind a
point cloud. It requires a data table in which each row gives the X and
Y coordinates of the points to be used to draw. Note that the lines will
be drawn following the order of the points in the table. The coordinates
system used must be the same that the one used for the objects. To draw
several lines, an additional column (named “group”) is required,
containing for each point the unique identifier of the line to which
this point belongs to. The data set is loaded using the
background.map
parameter.
By default, all distances in archeoViz
are in
centimeter. However, it can be changed by giving the unit
parameter one of the following value: “cm”, “m”, “km”. This parameter
determines the contents of the legend of the square size.
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).
The URL of an online instance of archeoViz
can include
the parameters:
objects.df=
refits.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
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.
You can change the orientation of the points in the plan. In the “Data” tab, select a value (in degrees) and click on the “Validate selection” button to confirm.
Once data are loaded, a sub-selection of the data can be done in the left side menu. Grouping can be done by crossing the following parameters: the mode of location, the layers, and the category of object.
If all the objects have exact location or vague location, then no option is proposed. However, if the dataset includes both exact and vague location, then it is possible to select only one or both of these options.
The data can be grouped in two ways: either based on their layer or on the selected “object_” variable. This option determines the colours of the points in the 3D and 2D plots and how to group points when computing convex hulls and 3D regression surfaces. 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 to be displayed in the plots and tables.
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.
Finally, clicking on a point displays information about that point in the table below the plot.
In archeoViz
, a distinction is made between exact
location (given as x, y, z coordinates) and vague locations (given as
ranges of coordinates). Both types of locations can be displayed. The
uncertainty of vague locations can be visualised by representing objects
not as points but as lines, planes, and volumes (if ranges of
coordinates are given for one, two, or three spatial dimensions,
respectively). Note that this feature is resource intensive and using it
with too much data can significantly slow down the application.
Several graphical outputs can be generated in
archeoViz
.
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, convex hulls can be displayed as follows:
Convex hulls associated with each subsets with at least 20 points are
displayed. 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.
archeoViz
was designed as one of the building blocks of
a decentralised digital ecosystem for archaeological data and analysis.
In this perspective, features and functions are distributed in multiple
interconnected applications, rather than concentrated into few systems.
Consequently, data can be exported and imported between
archeoViz
and other web-based applications. Note that, so
far, the export functionalities are only available when using online
archeoViz
instances.
Data can be exported to other online applications from
archeoViz
“Statistics” tab. Some exports are possible only
for specific types of data or if a minimum number of values is
satisfied.
archeofrag
is an R package and web application to assess and evaluate the
distinctions betwen archaeological spatial units (e.g. layers) based on
the analysis of refitting relationships between fragments of objects.
The web version of the application includes methods to measure the
cohesion and admixture of spatial units, and compare it to simulated
data. If an instance of archeoViz
is launched with refitting data, then this data can be analysed
with archeofrag
. See an example here.
The Seriograph
is a web application (part of the SPARTAAS
collection) to visualise changes in the quantitative distribution of
artefacts types in ordered or unordered series of spatial units. Export
to Seriograph
is available from online
archeoViz
instance (only) for dataset with at least 2
different values for the layer
variable and 2 different
values for the selected variable (by default, object_type
).
See an example here.
Amado
online is an on-line application for analysing contingency
tables. Amado online
allows you to manually reorder rows
and columns, and perform automatic seriation and classification. Export
to Amado online
is available from online
archeoViz
instance (only) for dataset with at least 2
different values for the layer
variable and 2 different
values for the selected variable (by default, object_type
).
See an example here.
explor is
an R Shiny / R package application for interactively exploring the
results of multi-dimensional analyses. Export to explor
is
available from online archeoViz
instance (only) for dataset
with at least 2 different values for the layer
variable and
2 different values for the selected variable (by default,
object_type
). The version of explor
used from
archeoViz
is a fork of the original application, adapted to
run correspondence analysis. See an example here.
shinyHeatmaply
is an R Shiny / R package application to generate and interactively
explore heatmaps. Multiple statistical distance and classification
methods can be applied. Export to shinyHeatmaply
is
available from online archeoViz
instance (only) for dataset
with at least 2 different values for the layer
variable and
2 different values for the selected variable (by default,
object_type
). The version of shinyHeatmaply
used from archeoViz
is a fork of the original application.
See an example here.
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, unit = "cm", rotation = 0,
grid.orientation = NULL, background.map = NULL,
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 = FALSE, hulls.class.values = NULL,
plot3d.surfaces = NULL, plot3d.refits = NULL, point.size = 2,
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, table.export = TRUE
)
archeoViz(square.size = 100, unit = "cm", rotation = 0,
grid.orientation = NULL, background.map = NULL,
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
,
point.size
, sectionX.y.val
,
sectionY.x.val
, sectionY.y.val
,
lang
, set.theme
, camera.center
,
camera.eye
, html.export
,
table.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 instead of the 100 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, Laura Coltofean, Sara Giardino, Julian Laabs, and
Nicolas Delsol translated the application into Portuguese, Romanian,
Italian, German, and Spanish respectively.