---
title: "archeoViz. Visualisation, exploration et communication web de données spatiales archéologiques"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{archeoViz. Visualisation, exploration et communication web de données spatiales archéologiques}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```



`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* du mobilier archéologique, permet de visualiser la *chronologie* des travaux sur un site. Il est possible d'y réaliser des *statistiques spatiales* simples (enveloppes convexes, surfaces de régression, estimation de densité par noyau en 2D) ainsi que d'*exporter des données* vers d'autres applications en ligne pour appliquer des méthodes plus complexes. `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 allemand, anglais, italien, français, portugais et roumain. Page web: https://archeoviz.hypotheses.org.



- [**Installation**](#installation)
  - [Locale](#locale)
  - [Distante](#distante)
  - [Démonstration](#démonstration)
- [**Recommandations communautaires**](#recommandations-communautaires)
  - [Signaler un bug](#signaler-un-bug)
  - [Soumettre une modification](#soumettre-une-modification)
  - [Traduire](#traduire)
- [**Utilisation**](#utilisation)
  - [L'information spatiale dans archeoViz](#linformation-spatiale-dans-archeoviz)
    - [Points, localisation exacte : les objets relevés](#points-localisation-exacte--les-objets-relevés)
    - [Points, localisation vague : passes, seaux, tamis et erreurs d'enregistement](#points-localisation-vague--passes-seaux-tamis-et-erreurs-denregistement)
    - [Lignes](#lignes)
    - [Surfaces](#surfaces)
  - [Remontages et mesures de fabrique](#remontages-et-mesures-de-fabrique)
      - [Remontages](#remontages)
      - [Mesures de fabrique](#mesures-de-fabrique)   
  - [Format de données](#formater-des-données)
     - [Formater des données](#formater-des-données)
     - [Tableau des objets](#tableau-des-objets)
     - [Tableau des remontages](#tableau-des-remontages)
     - [Tableau de la chronologie](#tableau-de-la-chronologie)
     - [Dessin d'arrière-fond](#dessin-darrière-fond)
     - [Unités](#unités)
  - [Charger des données](#charger-des-données)
     - [Via l'interface de l'application](#via-linterface-de-lapplication)
     - [Via les paramètres de la fonction R](#via-les-paramètres-de-la-fonction-r)
     - [Via les paramètres d'une URL](#via-les-paramètres-dune-url)
     - [Par génération de données aléatoires](#par-génération-de-données-aléatoires)
     - [Rotation des points](#rotation-des-points)
  - [Sous-sélection de données](#sous-sélection-de-données)
     - [Par mode de localisation](#par-mode-de-localisation)
     - [Par couche ou catégorie d'objet](#par-couche-ou-catégorie-dobjet)
  - [Visualisations interactives](#visualisations-interactives)
    - [Généralités](#généralités)
    - [Sorties graphiques](#sorties-graphiques)
    - [Visualisation de l'incertitude spatiale](#visualisation-de-l-incertitude-spatiale)    
  - [Statistiques spatiales](#statistiques-spatiales)  
     - [Surfaces de régression](#surfaces-de-régression)
     - [Enveloppes convexes](#enveloppes-convexes)
     - [Estimation 2D de densité par noyau](#estimation-2d-de-densité-par-noyau)
- [**Reproductibilité**](#reproductibilité)  
- [**Exports depuis et vers des applications tierces**](#exports-depuis-et-vers-des-applications-tierces)
    - [Export depuis archeoViz](#export-depuis-archeoviz)
    - [Import vers archeoViz](#import-vers-archeoviz)
- [**Paramètres avancés**](#paramètres-avancés)  
  - [Carroyage](#carroyage)
  - [Pré-sélection des paramètres](#pré-sélection-des-paramètres)
  - [Affichage réactif des visualisations](#affichage-réactif-des-visualisations)
  - [Contrôle des formats d'export](#contrôle-des-formats-d-export)
  - [Paramètres URL](#paramètres-url)
- [**Remerciements**](#remerciements)
- [**Références et ressources**](#références-et-ressources)
  - [Logiciels](#logiciels)
  - [Articles](#articles)
  - [Présentations](#présentations)
  - [Sites web](#sites-web)
 
 
# Installation

`archeoViz` peut être employée de deux manières:

* localement, sur la machine de l'utilisateur
* à distance, après déploiement sur un serveur distant

## Locale

Le package peut être installé depuis le CRAN:

```r
install.packages("archeoViz")
```

La version de développement peut être téléchargée depuis *GitHub*:

```r
# install.packages("devtools")
devtools::install_github("sebastien-plutniak/archeoviz")
```

Après quoi, chargez le package et lancez l'application avec:

```r
library(archeoViz)
archeoViz()
```

## Déployée

Pour déployer `archeoViz` sur votre Shiny server, téléchargez premièrement le package:

```{r, eval=FALSE}
# déterminez le répertoire de travail dans votre shiny server:
setwd(dir = "/some/path/")
# téléchargez le package:
download.file(url = "https://github.com/sebastien-plutniak/archeoviz/archive/master.zip",
              destfile = "archeoviz.zip")
# décompression:
unzip(zipfile = "archeoviz.zip")
```

Puis, rendez-vous à `https://<your-shiny-server>/archeoviz-main`.

Pour paramétrer l'application avec vos données et préférences, éditez le fichier `app.R` situé à la racine du répertoire de l'application:

```{r, eval=FALSE}
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 des fouilles
          default.group =NULL, # méthode de groupement des données,
                               # par couche ("by.layer") ou "by.variable"
          title = NULL,        # titre du site / du jeu de données
          home.text = NULL,    # contenu HTML à afficher sur la page d'accueil
          lang = "fr"          # langue de l'interface ("de": Allemand, "en": Anglais, "fr": Français, "it": Italien "pt": Portugais, "es": Espagnol)
          set.theme = "cosmo") # thème graphique de l'interface Shiny
```

Les valeurs possibles pour le paramètre  `set.theme` sont illustrées sur [cette page](https://rstudio.github.io/shinythemes/).
La langue de l'application peut être définie avec le paramètre `lang`.

## Démonstration

Des instances de démonstration de l'application sont déployées sur le Shiny server d'*Huma Num*:

* [`archeoViz` en français](https://analytics.huma-num.fr/archeoviz/fr).
* [`archeoViz` en anglais](https://analytics.huma-num.fr/archeoviz/en).
* [`archeoViz` en allemand](https://analytics.huma-num.fr/archeoviz/de).
* [`archeoViz` en espagnol](https://analytics.huma-num.fr/archeoviz/es).
* [`archeoViz` en italien](https://analytics.huma-num.fr/archeoviz/it).
* [`archeoViz` en portugais](https://analytics.huma-num.fr/archeoviz/pt).
* [`archeoViz` en roumain](https://analytics.huma-num.fr/archeoviz/ro).

Des cas d'applications à divers sites archéologiques sont rassemblés sur le [*Portail archeoViz*](https://analytics.huma-num.fr/archeoviz/home).

# Recommandations communautaires

## Signaler un bug
Si vous rencontrez un bug, ouvrez une [*issue*](https://github.com/sebastien-plutniak/archeoviz/issues) en indiquant tous les détails nécessaires pour le reproduire.

## Suggérer un changement
Les suggestions de modifications sont bienvenues.
Les demandes peuvent concerner des fonctions additionnelles, des modifications dans la documentation, des exemples additionnels, de nouvelles fonctionnalités, etc.
Elles peuvent être faites en ouvrant une [issue](https://github.com/sebastien-plutniak/archeoviz/issues) ou, mieux encore, en employant une  *pull requests* et le modèle GitHub [ Fork and Pull](https://docs.github.com/articles/about-pull-requests).

## Traduire

Un soin particulier est accordé au multilinguisme. L'interface de l'application est disponible en plusieurs langues et les traduction dans des langues supplémentaires sont bienvenues. Pour cela, éditez ce [fichier](https://github.com/sebastien-plutniak/archeoviz/blob/main/R/load_interface_terms_utf8.R) et soumettez une *pull request*.


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

## L'information spatiale dans archeoViz

Les archéologues enregistrent la localisation des objets archéologique à différentes échelles et granularité. En fonction de cela, ils utilisent différentes concepts géométriques pour représenter ces localisations.

### Points, localisation exacte : les objets relevés

L'utilisation d'un carroyage ou d'une “station totale” permet d'enregistrer la localisation individuelle des objets sur le terrain.
Dans ce cas, dans  `archeoViz`, localisation de ces objets sera visualisée par des points (des triplets de valeurs de coordonnées x, y, z).

### Points, localisation vague : passes, seaux, tamis et erreurs d'enregistement

Toutefois, il est fréquent que les coordonnées x, y, z des objets ne soit pas disponible, pour différentes raisons:

* des erreurs d'enregistrement, des pertes d'information, entraînant la nécessité de remplacer une ou plusieurs valeurs de coordonnées par des intervalles de valeurs (par exemple, une valeur X est manquante pour un objet et est remplacée par les valeurs X minimale et maximale du carré où cet objet a été trouvé) ;
* le choix de la méthode (par exemple, lors d'une fouille réalisée et enregistrée à l'aide de passes de profondeur arbitraire ou, encore, des objets issus de refus de tamis, etc.)

Dans tous ces cas, les localisations à traiter sont vagues, lorsque la localisation des objets n'est pas connue univoquement mais se situe quelque part au sein d'intervalles de coordonnées.
La localisation vague peut concerner une, deux, ou trois dimensions spatiales (respectivement les coordonnées x, y et z).

Cette fonctionnalité peut également être employée pour tenir compte de l'imprécision des instruments de relevé.

### Lignes

Les lignes sont des géométries utiles pour représenter des relations. En archéologie, il peut s'agir de relations de [remontages](#remontages) entre fragments d'objets,  d'orientation ([mesures de fabrique](#mesures-de-fabrique)), etc. 
Dans `archeoViz`, les lignes sont générées à partir des données chargées comme données de remontage, soit à partir de l'onglet “Données”, soit avec le paramètre `refits.df` de la fonction `archeoViz()`.

### Surfaces

Les surfaces sont des géométries utiles pour représenter des niveaux de sol, des tranchées, des fosses, etc. 
Dans `archeoViz`, ceci peut être réalisé, en définissant un sous-ensemble de points résumant la surface souhaitée, puis en affichant l'[enveloppe convexe](#enveloppes-convexes) de ce sous-ensemble.


## Remontages et mesures de fabrique

### Remontages 

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

1. 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.
2. 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.


### Mesures de fabrique

Pour l'heure, `archeoViz` ne gère pas les mesures de fabrique à proprement dit. Néanmoins, la procédure employée pour représenter les remontages peut être adaptée et employée pour représenter les mesures de fabriques. Cela suppose toutefois de tordre la logique de la structure des données de la manière suivante:

* en supposant que les mesures de fabriques ont été enregistrées en prenant deux mesures de localisation par objet (au contraire, donc, de mesure d'orientation et de pendage),
* des valeurs d'identifiants uniques `id` doivent être attribuées aux deux points, et
* les deux localisations sont traitées comme s'il s'agissait d'une relation de remontage entre deux objets.  

Un exemple de cette méthode est visible  [ici](https://analytics.huma-num.fr/archeoviz/shuidonggou2).

## 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 de 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*](https://aurelienroyer.shinyapps.io/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 
* **ymin**: *valeur numérique*, coordonnée de l'objet en axe Y 
* **zmin**: *valeur numérique*, coordonnée de l'objet en axe Z (valeur positive de profondeur)
* **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, m, km) 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
    
   
### Dessin d'arrière-fond

Un dessin d'arrière-plan peut être affiché dans les visualisations “3D” et “Carte”. Ceci permet par exemple d'afficher le plan d'un site en fonds d'un nuage de points.
Cette fonctionnalité nécessite un tableau de données où chaque ligne contient les coordonnées X et Y des points à utiliser pour le dessin. À noter que les lignes seront tracées en suivant l'ordre des points dans le tableau.
Le système de coordonnées utilisé doit être le même que celui utilisé pour les objets.
Pour dessiner plusieurs lignes, une colonne supplémentaire (intitulée “group”) est nécessaire, et doit indiquer pour chaque point l'identifiant unique de la ligne à laquelle le point appartient. 
Le jeu de données doit être chargé via le paramètre `background.map`.
    
### Unités

Par défaut, toutes les  distances dans `archeoViz` sont exprimées en centimètres.
Il est cependant possible de spécifier une autre unité en donnant l'une des valeurs suivantes au paramètre `unit` : “cm”, “m”, “km”. Ce paramètre détermine le contenu de la légende relative à la taille des carrés de la grille.
    
## Charger des données

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

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


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




### 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:

```{r, eval=FALSE}
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.

```{r, eval=FALSE}
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](https://analytics.huma-num.fr/archeoviz/fr/?objects.df=https://zenodo.org/record/8003880/files/bilzingsleben.csv)

### 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`.


### Rotation des points

Il est possible de modifier l'orientation des points en plan. Dans l'onglet “Données”, sélectionnez une valeur (en degrés) et validez en cliquant sur le bouton “Validez la sélection”.


## 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
 
Si tous les objets ont des localisation soit exactes soit vagues, aucune option n'est proposée.
Par contre,  le jeu de données comprend des localisations des deux types, alors  il est possible de n'en sélectionner qu'un type ou les deux.


### Par couche ou catégorie d'objet

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



## Visualisations interactives

### Généralités

Les visualisations dans les onglets “Vue 3D”, “Carte”, “Section X” et  “Section Y” sont générées à l'aide de la librairie  [`plotly`](https://CRAN.R-project.org/package=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`](http://plotly.github.io/getting-to-know-the-plotly-modebar/).

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.

Enfin, cliquer sur un point active l'affichage d'informations à son sujet dans le tableau présent sous les visualisations.

### Visualisation de l'incertitude spatiale

Dans `archeoViz`, une distinction est faite entre les localisations exactes (données sous la forme de coordonnées x, y, z) et les localisations vagues (données sous la forme d'intervalles de coordonnées).
Il est possible d'afficher 
Les deux types de localisations peuvent être visualisées.
Les incertitudes des localisations peuvent être rendues en représentant les objets non pas comme des points mais comme des lignes, des plans, ou des volumes (si des intervalles de coordonnées sont précisés pour, respectivement, une, deux ou trois dimensions spatiales). 
Cette dernière option est gourmande en ressources, l'appliquer à un nombre important d'objets peut ralentir considérablement l'application.

### 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 miniature dans les onglets “Section X” et “Section Y” peut être exporté au format SVG en cliquant sur le lien “Télécharger plan”.
* 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`](https://CRAN.R-project.org/package=mgcv).

### Enveloppes convexes

Dans l'onglet “Vue 3D”, l'affichage des enveloppes convexes se réalise en:

1. cochant la case “Enveloppes convexes”,
2. sélectionnant, dans le menu qui s'affiche, les sous-ensembles de points pour lesquels les enveloppes doivent être calculées,
3. appuyant sur  “Valider”.

Les enveloppes convexes associées à chaque sous-ensemble de points comportant au moins 20 points sont alors affichées. 
Le calcul des enveloppes est réalisé avec le package [`geometry`](https://CRAN.R-project.org/package=geometry).

### 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`](https://CRAN.R-project.org/package=MASS) (à travers le package  [`ggplot2`](https://CRAN.R-project.org/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.

## Exports depuis et vers des applications tierces

`archeoViz` a été conçu comme l'une des pièces d'un écosystème numérique décentralisé pour les données et analyses archéologiques.
Dans cette approche, les fonctionnalités sont distribuées entre de multiples applications interconenctées, plutôt que concentrées dans un petit nombre de systèmes.
Par conséquent, les données peuvent être exportées et importées entre  `archeoViz` et d'autres applications web. Notez que, jusqu'ici, les fonctionnalités d'export ne sont disponibles que dans le cas d'instances `archeoViz` déployées en ligne.


### Export depuis archeoViz

À partir de l'onglet “Statistiques” d'`archeoViz`, il est possible d'exporter les données vers d'autres applications en ligne. La possibilité de certains exports est conditionnée au type de données ou à la satisfaction d'un nombre minimal de valeurs.


[*archeofrag*](https://analytics.huma-num.fr/Sebastien.Plutniak/archeofrag) est un package R et une application web permettant d'estimer et d'évaluer les  distinctions entre unités spatiales archéologiques (par ex. des couches) à partir de l'analyse des relations de remontage entre fragments d'objets. La  version web de l'application intègre des méthodes pour mesurer la cohésion et le mélange d'unités spatiales et de les comparer à des données simulées. Lorsqu'une instance d'`archeoViz` est executée avec des [données de remontage](#tableau-des-remontages), alors ces données peuvent être exportées vers `archeofrag`. Cf. cet [exemple](https://analytics.huma-num.fr/archeoviz/grotte16).

Le [*Seriograph*](https://analytics.huma-num.fr/ModAthom/seriograph/) est une application web (issue de la collection  [SPARTAAS](https://spartaas.gitpages.huma-num.fr/r-package/)) pour visualiser des changements quantitatifs dans la distribution de types d'artefacts dans des séries ordonnées ou non-ordonnées d'unités spatiales. L'export vers le `Seriograph` est uniquement possible depuis les instances d'`archeoViz` déployées en ligne dont le jeu de données possède (au moins) 2 valeurs différentes pour la variable `layer` et 2 valeurs différentes pour la variable sélectionnée (`object_type` par défaut). Voir cet [exemple](https://analytics.huma-num.fr/archeoviz/poeymau).


[*Amado online*](https://app.ptm.huma-num.fr/amado/) est une application en ligne permettant d'analyser des tableaux de contingence. Les lignes et les colonnes peuvent être réordonnées manuellement et des sériations et classifications automatiques peuvent être exécutées. L'export vers `Amado online` est uniquement possible depuis les instances d'`archeoViz` déployées en ligne dont le jeu de données possède (au moins) 2 valeurs différentes pour la variable `layer` et 2 valeurs différentes pour la variable sélectionnée (`object_type` par défaut).  Voir cet [exemple](https://analytics.huma-num.fr/archeoviz/tai).


[*explor*](https://cran.r-project.org/package=explor) est une application R Shiny / package R permettant d'explorer interactivement les résultats d'analyses multidimensionnelles. L'export vers `explor` est uniquement possible depuis les instances d'`archeoViz` déployées en ligne dont le jeu de données possède (au moins) 2 valeurs différentes pour la variable `layer` et 2 valeurs différentes pour la variable sélectionnée (`object_type` par défaut). La version d'`explor` utilisée depuis `archeoViz` est une adaptation de l'application originale, limitées aux analyses factorielles de correspondances. Voir cet [exemple](https://analytics.huma-num.fr/archeoviz/tai).


[*shinyHeatmaply*](https://cran.r-project.org/package=shinyHeatmaply) est une application R Shiny / package R permettant de générer et d'explorer interactivement des cartes de chaleur (*heatmaps*). Plusieurs distances et méthodes de classifications peuvent être apploquées. L'export vers `shinyHeatmaply` est uniquement possible depuis les instances d'`archeoViz` déployées en ligne dont le jeu de données possède (au moins) 2 valeurs différentes pour la variable `layer` et 2 valeurs différentes pour la variable sélectionnée (`object_type` par défaut). La version de `shinyHeatmaply` utilisée depuis `archeoViz` est une adaptation de l'application originale. Voir cet [exemple](https://analytics.huma-num.fr/archeoviz/grande-rivoire).



### Import vers archeoViz

[*SEAHORS*](https://aurelienroyer.shinyapps.io/Seahors) est une application web et un package R permettant de visualiser la distribution spatiale d'objets archéologiques. Comme indiqué  [ci dessus](#formater-des-données), *SEAHORS* peut être employé pour importer, transformer, et transmettre un jeu de donnée à une instance en ligne d'`archeoViz`.

## Paramètres avancés

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

* données à charger (traité [ci-dessus](#par-paramétrage-de-la-fonction)),
* contenu de la page d'accueil (traité [ci-dessus](#déployée)),
* [carroyage](#carroyage),
* [pré-paramètrage](#pré-sélection-des-paramètres) des paramètres pouvant être définis dans l'interface graphique,
* [comportement réactif](#affichage-réactif-des-visualisations) de l'application à propos du calcul et de l'affichage des visualisations.
* [export HTML](#export-html).

```{r, eval=FALSE}
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
          )
```

### Carroyage

```{r, eval=FALSE}
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
          )
```

* **square.size** : numérique. Taille (longueur et largeur)  des carrés du carroyage. La valeur par défaut est 100
* **unit** : caractères. Unité pour les distances spatiales. Soit 'cm', 'm' ou 'km'.
* **rotation** : numérique. integer. Valeur (en degrés) pour la rotation à appliquer en plan au nuage de points.
* **grid.orientation** : numérique. Orientation (en degrés) du carroyage par rapport au nord.
* **background.map** : data frame ou matrix. Coordonnées pour tracer des lignes en arrière-plan des visualisations en 3D et en plan.
* **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

```{r, eval=FALSE}
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 (une combinaison des valeurs possibles “exact”, “fuzzy”, “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.
* **hulls.class.values**:  caractères. Au lancement de l'application, noms des sous-ensembles de points pour lesquels calculer les enveloppes convexes.
* **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.
* **point.size**: entier. Au lancement de l'application, taille des points dans les visualisations.
* **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

```{r, eval=FALSE}
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 de cliquer sur le bouton “Rafraîchir”).

### Contrôle des formats d'export

* **html.export**: TRUE ou FALSE. Afficher ou non les boutons permettant d'exporter les visualisations en format HTML interactif.
* **table.export**: TRUE ou FALSE. Permettre ou non le transfert des données à des [applications tierces](#exports-depuis-et-vers-des-applications-tierces) dans l'onglet “Statistiques”.

### 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 supportés comprennent:

* `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`, `point.size`, `lang`, `set.theme`, `camera.center`, `camera.eye`, `html.export`, `table.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://zenodo.org/record/8003880):

[https://analytics.huma-num.fr/archeoviz/en/?objects.df=https://zenodo.org/record/8003880/files/bilzingsleben.csv](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](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 tel que:

1. les points sont groupés par variable (paramètre `default.group`, avec la valeur `by.variable` plutôt que `by.layer`)
2. seuls les “Antlers” sont sélectionnés (paramètre `class.values`)
3. la taille des carrés du carroyage est redéfinie (paramètre `square.size` 500 cm au lieu de la valeur par défaut 100cm)
4. l'affichage immédiat des graphiques est activé (paramètre `run.plots`)
5. le titre de la page est modifé (paramètre `title`)
6. le contenu de la page d'accueil est modifié, 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%20<b>antlers</b>&objects.df=https://zenodo.org/record/8003880/files/bilzingsleben.csv](https://analytics.huma-num.fr/archeoviz/en/?default.group=by.variable&class.values=Antler&square.size=500&run.plots=TRUE&title=Anters%20at%20Bilzingsleben&home.text=Many%20<b>antlers</b>&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).





# Remerciements

L'application et le package `archeoViz` sont développés et maintenus par Sébastien Plutniak. Arthur Coulon, Solène Denis, Olivier Marlet, et Thomas Perrin ont testé et soutenu ce projet durant ses premières étapes. Renata Araujo, Laura Coltofean, Sara Giardino, Julian Laabs et Nicolas Delsol ont traduit l'application respectivement en portugais, roumain, italien, allemand, et espagnol.

# Références et ressources

## Logiciels 

* Plutniak, Sébastien, Renata Araujo, Laura Coltofean, Nicolas Delsol, Sara Giardino, Julian Laabs. 2024. “archeoViz. Visualisation, Exploration, and Web Communication of Archaeological Spatial Data”. v1.3.4, DOI: [10.5281/zenodo.7460193](https://doi.org/10.5281/zenodo.7460193).
* Plutniak, Sébastien, Anaïs Vignoles. 2023. “[The archeoViz Portal: Dissemination of Spatial Archaeological Datasets](https://hal.science/hal-04156271)”, portail web, https://analytics.huma-num.fr/archeoviz/home.

## Articles

* Plutniak, Sébastien. 2023. “archeoViz: an R package for the Visualisation, Exploration, and Web Communication of Archaeological Spatial Data”. *Journal of Open Source Software*, 92(8), 5811, DOI: [10.21105/joss.05811](https://doi.org/10.21105/joss.05811).
* Plutniak, Sébastien. 2023. “[Visualiser et explorer la distribution spatiale du mobilier archéologique : l'application archeoViz et son portail web](https://www.prehistoire.org/offres/doc_inline_src/515/0-BSPF_2023_1_2e_partie_Correspondance_PLUTNIAK.pdf)”. *Bulletin de la Société préhistorique française*, 120(1), p. 70-74.

## Présentations

* Plutniak, Sébastien. 2023. “[Fostering the Publication of Spatial Archaeological Data: a Decentralized Approach. The archeoViz Web Application and its Portal](https://hal.science/hal-04146410)”, support d'une présentation à l'University of Florida, Gainesville.
* Plutniak, Sébastien, Anaïs Vignoles. 2023. “[L’application web / package archeoViz et son portail web. Une solution décentralisée d’éditorialisation de données archéologiques spatialisées](https://hal.science/hal-04070444), support d'une présentation à l'atelier SITRADA, Paris.

## Sites web

* Le blog *archeoViz. Data visualization in archaeology. Re-use, visualization, dissemination of spatial data*: https://archeoviz.hypotheses.org



