archeoViz est une application dédiée à l’archéologie. Elle permet de visualiser, d’explorer interactivement, et d’exposer et communiquer rapidement sur le web des données archéologiques spatialisées. Elle propose des visualisations en 3D et 2D, génère des coupes et des cartes des restes archéologiques, permet de réaliser des statistiques spatiales simples (enveloppes convexes, surfaces de régression, estimation de densité par noyau en 2D), et de visualiser une chronologie interactive des fouilles d’un site. archeoViz peut être utilisée localement ou déployée sur un serveur, soit en chargeant des données via l’interface, soit en lançant l’application avec un jeu de donnée spécifique. L’interface est disponible en anglais, français, italien, et portugais.

Utilisation

Considérant les objets archéologiques d’un site de fouille ou de prospection, archeoViz est conçu pour réduire les freins techniques à la réalisation de trois objectifs:

l’exploration spatiale basique et la production de documents graphiques analytiques;
la pré-publication rapide de données archéologiques, à destination de la communauté scientifique;
le déploiement aisé d’un outil d’exposition et de communication, à destination d’un plus large public.

En outre, archeoViz constitue une ressource pédagogique adaptée à l’enseignement des notions d’analyse spatiale en archéologie, de structuration de données, de science ouverte et de reproductibilité.

N.B.: par conséquent, archeoViz n’est pas destiné à se substituer à des outils d’analyse plus sophistiqués (e.g., SIG, packages de statistiques spatiales, etc.)

Formater des données

Trois types de données peuvent être chargées dans archeoViz :

un tableau “objects” (requis), à propos des objets ;
un tableau “refits” (optionnel), à propos des relations de remontage ;
un tableau “timeline” (optionnel), à propos des carrés du site et des années où ils ont été fouillés ou prospectés.

Les tableaux doivent être au format CSV et la première ligne doit contenir les noms des variables (le symbole séparateur du CSV peut être défini dans l’interface). Les contenus au format HTML sont autorisés. Cela permet notamment d’introduire références vers des ressources complémentaires du jeu de données (par exemple l’identifiant unique de l’objets dans une autre base de données, ou ceux des concepts d’ontologies employés pour décrire l’objet, etc.).

Le formatage des données peut être réalisé :

soit en utilisant un tableur sur votre machine permettant d’exporter des fichiers CSV ;
ou, pour le tableau des objets, en utilisant l’interface de l’application SEAHORS en chargeant vos données, définissant les variables (onglet “Load data”), puis en les exportant au format archeoViz (onglet “Table” / “archeoViz exports”). Il est également possible de les transférer directement à une instance archeoViz en ligne.

Tableau des objets

Chaque ligne décrit un objet et doit comporter les variables obligatoires suivantes :

id : valeur alphanumérique, identifiant unique de l’objet
xmin : valeur numérique, coordonnée de l’objet en axe X (en cm)
ymin : valeur numérique, coordonnée de l’objet en axe Y (en cm)
zmin : valeur numérique, coordonnée de l’objet en axe Z (valeur positive de profondeur en cm)
layer : valeur alphanumérique, identifiant de la couche de l’objet
object_type : valeur alphanumérique, catégorie de l’objet

De plus, des variables optionnelles sont possibles :

square_x : valeur alphanumérique, identifiant du carré de l’objet en axe X
square_y : valeur alphanumérique, identifiant du carré de l’objet en axe Y
year : valeur numérique, année de fouille de l’objet
xmax : valeur numérique, lorsque la localisation de l’objet en X est comprise dans un intervalle de coordonnées
ymax : valeur numérique, lorsque la localisation de l’objet en Y est comprise dans un intervalle de coordonnées
zmax : valeur numérique, lorsque la localisation de l’objet en Z est comprise dans un intervalle de coordonnées
object_edit : nombre non limité de variables additionnelles décrivant l’objet (les noms de colonnes doivent commencer par object_ et avoir des suffixes différents

Les labels des carrés du carroyage :

sont ordonnés alpha-numériquement ;
ne sont pas affichés, afin d’éviter des affichages erronés, si le nombre de labels ne correspond pas exactement au nombre total de carrés de 100 cm pouvant être définis dans l’intervalle des coordonnées minimales et maximales contenues dans les variables xmin et ymin ;
peuvent être complétés avec les paramètres add.x.square.labels et add.y.square.labels de la fonction archeoViz() afin d’ajouter les labels manquants (respectivement, sur les axes X et Y du carroyage).

Tableau des remontages

Un tableau à deux colonnes peut être chargé pour les remontages entre objets (format CSV). Chaque ligne doit contenir les identifiants uniques des deux objets liés à une relation de remontage (en correspondance avec les valeurs de la colonne id du tableau des objets).

Tableau de la chronologie

Optionnellement, un tableau (CSV) peut être chargé à propos du déroulé de la fouille. Chaque ligne est relative à un carré de fouille et indique quand ce carré a été fouillé ou prospecté. Le tableau doit comporter les variables suivantes :

year : valeur numérique, année de fouille
square_x : valeur alphanumérique, identifiant du carré en axe X
square_y : valeur alphanumérique, identifiant du carré en axe Y

Charger des données

Quatre manières permettent de charger des données dans archeoViz:

en téléchargeant des tableaux à partir de l’onglet “Données” ;
en générant des données aléatoires dans l’onglet “Données” ;
en chargeant des tableaux à travers les paramètres de la fonction archeoViz, dans un environnement R ;
en téléchargeant des tableaux via les paramètres d’URL, lors de l’utilisation d’une instance archeoViz en ligne.

Via l’interface de l’application

Des tableaux pour trois types de données peuvent être chargés à partir de l’onglet “Données”. Le séparateur CSV (la virgule, le point-virgule ou la tabulation) et le caractère distinguant les décimales dans les nombres (point ou virgule) peuvent être paramétrés.

Par génération de données aléatoires

À des fins de démonstration, il est possible d’employer des données générées aléatoirement. Déplacer le curseur sur une valeur supérieure à 0, dans l’onglet “Données”, active cette fonctionnalité (replacer le curseur sur 0 la désactive). Des données d’objets, de remontage, et de chronologie de la fouille sont alors générés, permettant de tester toutes les fonctionnalités d’archeoViz.

Via les paramètres de la fonction R

La fonction de lancement d’archeoViz() peut être exécutée sans définir de paramètres:

archeoViz()

ou en employant les paramètres objects.df, refits.df, timeline.df afin de charger des données relatives, respectivement, aux objets, aux remontages, et à la chronologie.

archeoViz(objects.df = NULL,  # data.frame pour les objets
          refits.df = NULL,   # data.frame optionnel pour les remontages
          timeline.df = NULL) # data.frame optionnel pour la chronologie

Via les paramètres d’une URL

L’URL d’une instance archeoViz en ligne peut être complétée avec les paramètres :

objects.df=
`refits.df=``
timeline.df=

prenant pour valeurs l’URL d’un fichier CSV respectant le format archeoViz décrit ci-dessus. Par exemple : https://analytics.huma-num.fr/archeoviz/fr/?objects.df=https://zenodo.org/record/8003880/files/bilzingsleben.csv

Sous-sélection de données

Après que les données soient chargées, des sous-sélections peuvent être réalisées en employant les options du menu gauche de l’interface. Plusieurs paramètres sont possibles: le mode de localisation, les catégories des objets, et la définition de sous-groupes de données.

Par mode de localisation

La localisation des objets archéologiques peut avoir été enregistrée de différentes manières, plus ou moins précises: d’une part, de manière exacte avec des points (localisés par un triplé de coordonnées x, y et z) et, d’autre part, de manière plus ou moins imprécise sur des lignes, des plans, ou au sein de volumes (avec différentes ensembles de paires de valeurs x, y et/ou z). Dans archeoViz, une distinction est faite entre les localisations exactes (les points) et les autres types de localisations vagues (lignes, plans, volumes). Il est possible d’afficher les deux types de localisations (exactes et vagues), ainsi que de visualiser les incertitudes de localisation sous la forme de lignes, plans et volumes. Cette dernière option est gourmande en ressources, l’utiliser avec des données trop nombreuses peut ralentir considérablement l’application.

Par catégorie d’objet

Des sous-ensembles de données peuvent être définis à partir des catégories des objets, en employant les champs “Variable” et “Valeurs”. Après que l’une des variables ait été sélectionnée (“object_type” ou une autre “object_” variable possible), ses valeurs apparaissent en dessous et peuvent être sélectionnées en cochant les items. La sélection doit être validée en cliquant sur le bouton “Valider”. Cette sélection détermine les données qui seront présentées dans les graphiques et tableaux.

Sous-groupes de données

Il est, de plus, possible de préciser si les couleurs doivent être définies en fonction des couches ou en fonction de la variable objet sélectionnée.

Des sous-groupes de données peuvent être définies de deux manières: soit par couche ou en fonction de la variable “object_” sélectionnée. Cette option détermine l’application des couleurs dans les graphiques 3D et 2D et les sous-groupes de données auxquels sont appliqués les calculs de surface de régression et d’enveloppes convexes.

Par objet

Dans les onglets “Vue 3D”, “Carte”, “Section X” et “Section Y”, cliquer sur un point active l’affichage d’informations à son sujet dans le tableau présent sous la visualisation.

Remontages

Les remontages sont généralement enregistrés de deux manières par les archéologues:

par ensemble d’objets remontant entre eux: en employant alors un tableau à deux colonnes où une ligne correspond à un objet. La première colonne contient l’identifiant unique de l’objet et la deuxième colonne contient l’identifiant unique de l’ensemble d’objets remontant entre eux auquel l’objet considéré appartient.
par relation de remontage : en employant alors un tableau à deux colonnes où une ligne correspond à une relation de remontage. La première colonne contient l’identifiant unique du premier objet et la deuxième colonne contient l’identifiant unique du deuxième objet.

Bien que la seconde structure de donnée soit plus précise, c’est la première qui est le plus fréquemment employée.

Ces deux structures de données sont traitées différemment dans archeoViz :

les ensembles d’objets remontant entre eux doivent être décrits dans une colonne spécifique dans le tableau objects.df table (nommée par ex. object_refits) et sont représentés par la couleur des points dans les visualisations (comme pour tout autre variable) ;
les relations de remontage doivent être décrits dans un tableau refits.df et sont visualisés par des segments reliant les objets liés par des relations de remontage.

Visualisations interactives

Les visualisations dans les onglets “Vue 3D”, “Carte”, “Section X” et “Section Y” sont générées à l’aide de la librairie plotly. Toutes ces visualisations sont dynamiques et sont surmontées d’une barre de menu comportant plusieurs options (générer un fichier image, zoomer, déplacer le point de vue, etc.). Davantage de détails sont disponibles sur le site de plotly.

Cliquer sur un item de la légende modifie l’affichage:

un simple clic sur un item active/désactive son affichage;
un double clic sur un item limite l’affichage à cet item seul (un autre double clic annule cette sélection).

Cette fonctionnalité permet de définir les couches devant être affichées. De plus, la taille des points peut être ajustée, ainsi que l’affichage ou non des relations de remontage.

Sorties graphiques

Plusieurs sorties graphiques peuvent être générées dans archeoViz.

Les visualisations en 3D, en plan et en sections peuvent être exportées :
- au format SVG, en cliquant sur l’icône “appareil photo” de la barre de menu s’affichant au-dessus des visualisations ;
- en format HTML interactif, en cliquant sur le bouton “Exporter” dans la colonne droite de l’interface.
Le plan de la chronologie des fouilles peut être téléchargé au format SVG en cliquant sur le bouton “Télécharger”.

Statistiques spatiales

archeoViz comporte quelques fonctionnalités d’analyse spatiale, destinées à usage simple et exploratoire.

Surfaces de régression

Dans l’onglet “Vue 3D”, cliquer sur “Calculer les surfaces” puis “Valider” affiche les surfaces de régression associées à chaque sous-ensemble de points (couche), comportant au moins 100 points. Les surfaces sont calculées grâce au modèle additif généralisé implémenté dans le package mgcv.

Enveloppes convexes

Cliquer sur “Calculer les enveloppes” puis “Valider”, dans l’onglet “Vue 3D”, affiche les enveloppes convexes associées à chaque sous-ensemble de points (couches), comportant au moins 20 points. Les enveloppes sont calculées en employant le package cxhull.

Estimation 2D de densité par noyau

Dans l’onglet “Plan”, cocher la case “Calculer la densité” et cliquer sur “Valider” génère un plan comportant des lignes de contour représentant la densité des points. La densité peut être calculée pour l’ensemble des points ou par couche (comportant au moins 30 points). L’estimation bidimensionnelle de densité par noyau est calculée avec la fonction kde2d du package MASS (à travers le package ggplot2).

Reproductibilité

archeoViz est, par définition, une application interactive. Toutefois, plusieurs fonctionnalités permettent de satisfaire les besoins de reproductibilité et de communicabilité des résultats d’interactions avec l’application.

La visualisation 3D est exportable dans un format interactif HTML standalone, tenant compte de la sous-sélection de données effectuée par l’utilisateur (dans le menu latéral gauche).
Dans l’onglet “Reproductibilité”, une commande R est générée dynamiquement, tenant compte du paramétrage de l’application réalisé par l’utilisateur en agissant avec l’interface graphique.
Dans un usage plus avancé, les paramètres d’URL permettent de paramétrer une instance en ligne de l’application avec des paramètres d’intérêt et de la communiquer l’ensemble en envoyant l’URL à un tiers.

Paramètres avancés

La fonction archeoViz() admet de nombreux paramètres optionnels, relatifs aux :

données à charger (traité ci-dessus),
contenu de la page d’accueil (traité ci-dessus),
carroyage,
pré-paramètrage des paramètres pouvant être définis dans l’interface graphique,
comportement réactif de l’application à propos du calcul et de l’affichage des visualisations.
export HTML.

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
          )

Carroyage

archeoViz(square.size = 100,
          reverse.axis.values = NULL, reverse.square.names = NULL,
          add.x.square.labels = NULL, add.y.square.labels = NULL
          )

square.size : numérique. Taille (longueur et largeur) en centimètre des carrés du carroyage. La valeur par défaut est 100 cm.
reverse.axis.values : caractères. Nom de l’axe ou des axes à inverser (une combinaison de ‘x’, ‘y’, ‘z’).
reverse.square.names : caractères. Nom de l’axe ou des axes pour lesquels inverser l’ordre des labels de carrés (une combinaison de ‘x’, ‘y’, ‘z’).
add.x.square.labels : caractères. Labels de carrés additionnels pour l’axe ‘x’.
add.y.square.labels : caractères. Labels de carrés additionnels pour l’axe ‘y’.

Pré-sélection des paramètres

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
          )

class.variable : caractères. Au lancement de l’application, nom de la variable à pré-sélectionner.
class.values : caractères. Au lancement de l’application, nom des valeurs à pré-sélectionner.
default.group : caractères. Au lancement de l’application, pré-sélection de la variable à employer pour grouper les données (soit “by.layer” ou “by.variable”).
location.mode : caractères. Au lancement de l’application, pré-sélection du ou des modes de localisation à afficher (“exact”, “fuzzy”, ou “show.uncertainty”).
map.z.val : numérique. Au lancement de l’application, valeurs minimale et maximale des coordonnées Z à présélectionner dans la visualisation en plan.
map.density : caractères. Au lancement de l’application, calculer et afficher ou non les courbes de densité dans la visualisation en plan (soit “no”, “overall”, ou “by.variable”).
map.refits : TRUE ou FALSE. Afficher ou non les remontages dans la visualisation en plan.
plot3d.hulls : TRUE ou FALSE. Au lancement de l’application, calculer et afficher ou non les enveloppes convexes dans la visualisation 3D.
plot3d.surfaces : TRUE ou FALSE. Au lancement de l’application, calculer et afficher ou non les surfaces de régression dans la visualisation 3D.
plot3d.refits : TRUE ou FALSE. Au lancement de l’application, afficher ou non les remontages dans la visualisation 3D.
sectionX.x.val : numérique. Au lancement de l’application, valeurs minimale et maximale des coordonnées X à présélectionner dans la visualisation en section X.
sectionX.y.val : numérique. Au lancement de l’application, valeurs minimale et maximale des coordonnées Y à présélectionner dans la visualisation en section X.
sectionX.refits : TRUE ou FALSE. Au lancement de l’application, afficher ou non les remontages dans la visualisation en section X.
sectionY.x.val : numérique. Au lancement de l’application, valeurs minimale et maximale des coordonnées X à présélectionner dans la visualisation en section Y.
sectionY.y.val : numérique. Au lancement de l’application, valeurs minimale et maximale des coordonnées Y à présélectionner dans la visualisation en section Y.
sectionY.refits : TRUE ou FALSE. Au lancement de l’application, afficher ou non les remontages dans la visualisation en section Y.
camera.center : numérique. Au lancement de l’application, coordonnées du point vers lequel la caméra est orientée dans la visualisation 3D (valeurs par défaut: x=0, y=0, z=0).
camera.eye : numérique. Au lancement de l’application, coordonnées de la position de la caméra dans la visualisation 3D (valeurs par défaut: x=1.25, y=1.25, z=1.25).

Affichage réactif des visualisations

archeoViz(run.plots = FALSE)

run.plots : TRUE ou FALSE. Si les visualisations doivent, ou non, être immédiatement calculées et affichées (sans nécessiter un clic sur les boutons de l’interface).

Export HTML

html.export : TRUE ou FALSE. Afficher ou non les boutons permettant d’exporter les visualisations en format HTML interactif.

Paramètres URL

Une instance archeoViz deployée en ligne sur un serveur peut être paramétrée en ajustant les paramètres de l’URL. Les paramètres acceptés supportés:

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

(Les paramètres suivants ne sont pas supportés dans la version actuelle de l’application: map.z.val, sectionX.x.val, sectionX.y.val, sectionY.x.val, sectionY.y.val, lang, set.theme, camera.center, camera.eye, html.export.)

Les paramètres doivent être écris en respectant la syntaxe URL (?param1=value&param2=value2) et avoir le même type de valeurs que dans leur usage dans l’interface R. Par exemple, l’URL suivante lance une instance archeoViz à partir du tableau principal du jeu de données Bilzingsleben:

https://analytics.huma-num.fr/archeoviz/en/?objects.df=https://zenodo.org/record/8003880/files/bilzingsleben.csv

Cette URL fait de même, mais inclut également le tableau des remontages (paramètre &refits.df=) et active l’affichage immédiat des relations de remontage dans le graphique 3D et le plan :

https://analytics.huma-num.fr/archeoviz/en/?map.refits=TRUE&plot3d.refits=TRUE&objects.df=https://zenodo.org/record/8003880/files/bilzingsleben.csv&refits.df=https://zenodo.org/record/8003880/files/bilzingsleben-antlers-refits.csv

L’URL suivante lance le jeu de données Bilzingsleben, en pré-réglant l’application telle que:

les points sont groupés par variable (paramètre default.group, avec la valeur by.variable plutôt que by.layer)
ne sélectionne que les “Antlers” (paramètre class.values)
redéfini la taille des carrés du carroyage (paramètre square.size 500 cm au lieu de la valeur par défaut 100 cm)
active l’affichage immédiat des graphiques (paramètre run.plots)
modifie le titre de la page (paramètre title)
modifie le contenu de la page d’accueil, illustrant l’usage d’un simple balisage HTML (paramètre home.txt)

https://analytics.huma-num.fr/archeoviz/en/?default.group=by.variable&class.values=Antler&square.size=500&run.plots=TRUE&title=Antlers%20at%20Bilzingsleben&home.text=Many%20antlers&objects.df=https://zenodo.org/record/8003880/files/bilzingsleben.csv

À noter que les paramètres add.x.square.labels, add.y.square.labels, location.mode, et class.values, qui admettent des valeurs simples ou multiples dans l’interface R (par ex. c(“value1”, “value2”)) n’admettent qu’une seule valeur lorsqu’employé comme paramètre d’URL (il s’agit d’une restriction liée à la syntaxe URL).

archeoViz. Visualisation, exploration et communication web de données spatiales archéologiques

Installation

Locale

Déployée

Démonstration

Recommandations communautaires

Signaler un bug

Suggérer un changement