- Bernard L. 2019. “Ten Years of ArkeoGIS: Feedback on the Challenges and Benefits of Digitally Sharing Archeological Data”, Workshop #2 DARIAH-CH, 2019, Neuchâtel, Switzerland. hal-02865759
- European Archaeological Council. 2024. Revisiting the Valletta Convention for the Digital Age: Position statement on archiving primary archaeological data (EAC Guidelines 6). doi: 10.5281/zenodo.10695890
- Garstki, K. (ed.) 2022. Critical Archaeology in the Digital Age. Los Angeles, UCLA Cotsen Institute of Archaeology Press. https://escholarship.org/uc/item/0vh9t9jq
- Gupta, N., S. Blair, R. Nicholas. 2020. “What We See, What We Don’t See: Data Governance, Archaeological Spatial Databases and the Rights of Indigenous Peoples in an Age of Big Data”, Journal of Field Archaeology, 45, 39–50. doi: 10.1080/00934690.2020.1713969
- Kansa, E. C., S. Whitcher Kansa. 2013. “We All Know That a 14 Is a Sheep: Data Publication and Professionalism in Archaeological Communication”, Journal of Eastern Mediterranean Archaeology and Heritage Studies, 1, 1, 88–97. doi: 10.1353/ema.2013.0007
- Kansa, E. C., S. Whitcher Kansa. 2022. “Promoting Data Quality and Reuse in Archaeology through Collaborative Identifier Practices”. Proceedings of the National Academy of Sciences, 119, 43, e2109313118. doi: 10.1073/pnas.2109313118
- Marwick B., S. E. Pilaar Birch. 2018. “A Standard for the Scholarly Citation of Archaeological Data as an Incentive to Data Sharing”, Advances in Archaeological Practice, 6, 2, 125–143. 10.1017/aap.2018.3
- McKeague, P. et al. 2019. “Mapping Our Heritage: Towards a Sustainable Future for Digital Spatial Information and Technologies in European Archaeological Heritage Management”, Journal of Computer Applications in Archaeology, 2, 1, 89-104, doi: 10.5334/jcaa.23
- McPherron, S. P. 2022. “Is a Decentralized, Non-standardized Approach to Data Sharing in Archaeology Good Enough?”, in Kandel, A. W., M. N. Haidle, C. Sommer (eds), Human Origins – Digital Future, Heidelberg, Propylaeum. doi: 10.11588/propylaeum.882.c13446
- Nicholson, C., S. Kansa, N. Gupta, R. Fernandez. 2023. “Will it ever be FAIR?: Making Archaeological Data Findable, Accessible, Interoperable, and Reusable”, Advances in Archaeological Practice, 11, 1, 63–75. doi: 10.1017/aap.2022.40
- Selhofer, H. G. Geser. 2015. D2.2 Second Report on Users’ Needs. Ariadne WP15 Study. Version 2.2.
- Strupler N. 2021. “Re-discovering Archaeological Discoveries. Experiments with Reproducing Archaeological Survey Analysis”, Internet Archaeology, 56. doi: 10.11141/ia.56.6.
- Tedersoo, L., Küngas, R., Oras, E., Köster, K., Eenmaa, H., Leijen, Ä., Pedaste, M., Raju, M., Astapova, A., Lukner, H. and Kogermann, K., 2021. “Data sharing practices and data availability upon request differ across scientific disciplines”. Scientific data, 8, 1, 192. doi: https://doi.org/10.1038/s41597-021-00981-0
- 2019. Helsinki Initiative on Multilingualism in Scholarly Communication. Helsinki: Federation of Finnish Learned Societies, Committee for Public Information, Finnish Association for Scholarly Publishing, Universities Norway & European Network for Research Evaluation in the Social Sciences and the Humanities. doi: 10.6084/m9.figshare.7887059
Documentación técnica de la aplicación
Esta documentación también está disponible en la pestaña “Ajuda” de la aplicación y en una “vignette” del paquete en el repositorio CRAN.
Traducción al español de esta documentación: Nicolas Delsol.
- Instalación
- Recomendaciones comunitarias
- Uso
- Reproducibilidad
- Exportaciones desde y hacia aplicaciones de terceros
- Parámetros avanzados
- Agradecimientos
- Referencias
Instalación
archeoViz
se puede utilizar de dos maneras:
- localmente, en la máquina del usuario
- de forma remota, después de implementar la aplicación en un servidor distante
Uso local
El paquete se puede instalar desde CRAN con:
install.packages("archeoViz")
La versión de desarrollo está disponible en GitHub y se puede instalar con:
# install.packages("devtools")
devtools::install_github("sebastien-plutniak/archeoviz")
Luego, cargue el paquete e inicie la aplicación con:
library(archeoViz)
archeoViz()
Uso distante
Para implementar archeoViz
en su servidor Shiny, primero descargue y descomprima el paquete:
# configure el directorio de trabajo en su servidor Shiny:
setwd(dir = "/some/path/")
# descargar el package:
download.file(url = "https://github.com/sebastien-plutniak/archeoviz/archive/master.zip",
destfile = "archeoviz.zip")
# unzip:
unzip(zipfile = "archeoviz.zip")
Luego, abre https://<your-shiny-server>/archeoviz-main
.
Para configurar la aplicación con tus datos y preferencias, edita el archivo app.R
, ubicado en la raíz del directorio:
archeoViz(objects.df = NULL, # data.frame con datos sobre los objetos
refits.df = NULL, # data.frame opcional para reinstalar datos
timeline.df = NULL, # data.frame opcional para la cronología de excavación
default.group =NULL, # méthode de groupement des données,
# par couche ("by.layer") ou "by.variable"
title = NULL, # titulo del sitio / data set
home.text = NULL, # Contenido HTML para mostrar en la página de inicio
lang = "fr" # lenguaje de interfaz ("en": Inglés, "fr": Francés, "it": Italiano, "pt": Portugués, "es": Español)
set.theme = "cosmo") # tema gráfico para la interfaz Shiny
Los valores posibles para el parámetro set.theme
se ilustran en esta página. El idioma de la aplicación se puede configurar con el parámetro lang.
Demostración
Las instancias de demostración de la aplicación se implementan en el servidor Huma Num Shiny:
archeoViz
en francés.archeoViz
en inglés.archeoViz
en alemán.archeoViz
en italiano.archeoViz
en portugués.archeoViz
en español.archeoViz
en rumano.
Los casos de uso reales se presentan en el archeoViz Portal.
Recomendaciones comunitarias
Reportar errores
Si encuentra un error, complete un issue con todos los detalles necesarios para reproducirlo.
Suggerir cambios
Sugerencias de cambios a archeoViz son bienvenidas. Estas solicitudes pueden referirse a funciones adicionales, cambios en la documentación, ejemplos adicionales, nuevas características, etc. Se puede hacer llenando un issue y, aún mejor, usando un pull requests y el modelo de Fork and Pull de GitHub.
Uso
Teniendo restos arqueológicos de un sitio determinado, archeoViz
está diseñado para reducir las barreras técnicas para cumplir tres objetivos:
- exploración espacial básica y generación de informes gráficos sencillos;
- publicación previa rápida de datos arqueológicos, destinada a la comunidad científica;
- implementación rápida de una herramienta de visualización y comunicación destinada a un público más amplio.
Además, archeoViz
es un recurso pedagógico adecuado para enseñar análisis espacial en arqueología, estructuración de datos, ciencia abierta y flujo de trabajo reproducible.
N.B.: en consecuencia, archeoViz
no pretende reemplazar herramientas de análisis más sofisticadas (por ejemplo, GIS, paquetes estadísticos, etc.)
Información espacial en archeoViz
Los arqueólogos registran la ubicación de los objetos arqueológicos en diferentes escalas y granularidades. En consecuencia, utilizan diferentes conceptos geométricos para representar la ubicación.
Puntos, ubicación exacta: objetos trazados
El uso de coordenadas de cuadrícula o “estación total” electrónica permite registrar la ubicación individual de los objetos en el campo. En ese caso, la ubicación se representa como puntos en archeoViz
(tripletes de coordenadas x, y, z).
Puntos, ubicación vaga: niveles arbitrários, baldes, objetos tamizados y errores de registro
Sin embargo, también es común que las coordenadas x, y, z, por objeto no estén disponibles, por diferentes motivos debido a:
- errores de registro, pérdida de información, lo que resulta en la necesidad de reemplazar uno de varios valores de coordenadas por rangos (por ejemplo, falta un valor X para un objeto y se reemplaza por los valores X mínimo y máximo del cuadrado donde se encuentra este objeto). fue encontrado);
- elección del método (p. ej., excavación realizada y registrada utilizando asadores de profundidad arbitraria, objetos tamizados, etc.).
En todos estos casos, tenemos que lidiar con la ubicación imprecisa, cuando los objetos no se pueden ubicar como puntos sino que se encuentran en algún lugar entre rangos de coordenadas. La ubicación imprecisa puede afectar a una, dos o tres dimensiones espaciales (las coordenadas x, y, z, respectivamente).
Esta función también puede utilizarse para tener en cuenta la imprecisión de los instrumentos topográficos.
Líneas
Las líneas son geometrías útiles para representar relaciones. En arqueología, pueden ser relaciones de remontajes entre fragmentos de objetos, orientación (medición de fábrica), etc.
Las líneas se generan a partir de datos cargados como datos de reensamblaje, ya sea desde la pestaña “Datos” o utilizando el parámetro refits.df
en la función archeoViz()
.
Superficies
Las superficies son geometrías útiles para representar niveles del terreno, zanjas, fosos, etc. En archeoViz
, esto puede conseguirse definiendo un subconjunto de puntos que resuman la superficie deseada y activando después la visualización del casco convexo de este subconjunto.
Remontajes y medición de fábrica
Remontajes
Los remontajes suelen ser registrados por los arqueólogos de dos maneras:
- por conjuntos de objetos de remontajes: usando una tabla de dos columnas, donde una fila corresponde a un objeto. La primera columna almacena la identificación única del objeto y la segunda columna almacena la identificación del conjunto de objetos al que pertenece este objeto.
- reensamblando relaciones: usando una tabla de dos columnas, donde una fila corresponde a una relación. La primera columna almacena la identificación única del primer objeto y la segunda columna almacena la identificación única del segundo objeto.
Aunque la segunda estructura de datos es más precisa, la primera se usa con más frecuencia.
archeoViz
procesa y representa las dos estructuras de datos de dos maneras:
- los conjuntos de objetos de remontajes deben describirse usando una columna específica en la tabla
objects.df
(p. ej., `object_refits) y están representados por el color de los puntos en los gráficos ( como cualquier otra variable); - las relaciones de remontajes deben describirse usando la tabla
refits.df
y se visualizan como segmentos que conectan los objetos de remontaje en las parcelas.
Medición de fábrica
Hasta ahora archeoViz
no maneja correctamente las mediciones de fábrica. Sin embargo, el proceso utilizado para representar remontajes también se puede adaptar y utilizar para representar las mediciones de fábrica. Esto requiere distorsionar la estructura de datos de la siguiente manera:
- suponiendo que las mediciones de fábrica se registraron con dos mediciones en cada objeto (y no con mediciones de inmersión y hundimiento),
- diferentes valores id únicos deben ser dados a los dos puntos, y las dos mediciones se procesan como si fueran dos objetos reensamblados.
Vea un ejemplo de este método aquí.
Formato de datos
Se pueden cargar tres tipos de datos en archeoViz
:
- una tabla de “objetos” (obligatoria), con datos sobre los objetos;
- una tabla de “remontajes” (opcional), con datos sobre los objetos de reacondicionamiento;
- una tabla de “cronología” (opcional), con datos sobre cuándo se excavó o midió cada cuadrado del sitio.
Formatear datos
Las tablas deben ser archivos CSV con la primera fila que contiene las etiquetas de las columnas. Se permiten contenidos en HTML. Esto hace posible, en particular, agregar enlaces a recursos externos (por ejemplo, a identificadores permanentes de objetos en otras bases de datos, o a identificadores de conceptos en ontologías / tesauros estándar, etc.).
El formateo de sus datos se puede hacer:
- ya sea usando un editor de hojas de cálculo en su máquina para generar archivos CSV;
- o, para la tabla de objetos , usando la aplicación SEAHORS para cargue sus datos, defina las variables (en la pestaña “Cargar datos”) y expórtelos al formato archeoViz (en la pestaña “Tabla” / “exportaciones archeoViz”). También es posible enviar directamente los datos a una instancia
archeoViz
en línea.
Tabla de objetos
Una fila describe un solo objeto con los siguientes campos obligatorios:
- id: valor alfanumérico, identificador único del objeto
- xmin: valor numérico, coordenada del objeto en el eje X (en cm)
- ymin: valor numérico, coordenada del objeto en el eje Y (en cm)
- zmin: valor numérico, coordenada del objeto en el eje Z (valor de profundidad positivo en cm)
- layer: valor alfanumério, identificador de la capa del objeto
- object_type: valeur alphanumérique, categoría del objeto
Además, los campos opcionales son posibles, incluidos:
- square_x: valor alfanumérico, identificador del cuadrado en el eje X
- square_y: valor alfanumérico, identificador del cuadrado en el eje Y
- year: valor numérico, año en que se excavó el objeto
- xmax: valor numérico, cuando la ubicación X del objeto está incluida en un rango de coordenadas X
- ymax: valor numérico, cuando la ubicación Y del objeto está incluida en un rango de coordenadas Y
- zmax: valor numérico, cuando la ubicación Z del objeto está incluida en un rango de coordenadas Z
- object_edit: número ilimitado de variables adicionales que describen el objeto (los nombres de campo deben comenzar con object_ y tener diferentes sufijos)
Las etiquetas de los cuadrados de la cuadrícula:
- están ordenados alfanuméricamente;
- no se muestran para evitar visualizaciones erróneas, si el número de etiquetas no corresponde exactamente al número total de cuadrados de 100 cm que se pueden definir en el rango de coordenadas mínimas y máximas contenidas en las variables xmin e ymin;
- se puede completar con los parámetros
add.x.square.labels
yadd.y.square.labels
dearcheoViz()
para agregar las etiquetas que faltan (en los ejes X e Y de la cuadrícula, respectivamente).
Mesa de montaje
Se puede cargar una tabla de datos con dos columnas para reajustar los datos (formato CSV). Cada fila debe contener los identificadores únicos de dos objetos de reacondicionamiento (correspondientes a los valores de la columna id
en la tabla de objetos).
Tabla de línea de tiempo
Se puede cargar una tabla (formato CSV) sobre el historial de excavaciones. La fila indica el año en que se excavó o midió cada cuadrado de la cuadrícula del sitio. Esta tabla debe incluir las siguientes variables:
- year: valor numérico, el año de excavación
- square_x: valor alfanumérico, identificador del cuadrado excavado en el eje X
- square_y: valor alfanumérico, identificador del cuadrado excavado en el eje Y
Cargar datos
Hay cuatro formas de ingresar datos en archeoViz
:
- cargar tablas de datos a través de la pestaña “Cargar datos”,
- generar datos aleatorios en la pestaña “Cargar datos”;
- cargar tablas de datos a través de los parámetros de la función
archeoViz
, en la interfaz R; - cargar tablas de datos a través de parámetros de URL, cuando se usa una instancia en línea de
archeoViz
.
A través de la interfaz de la aplicación
Los tres tipos de tablas se pueden cargar en la pestaña “Cargar datos”. El separador CSV (uno de: coma, punto y coma, tabulación) y el carácter utilizado para los puntos decimales (punto o coma).
Generando Datos Aleatorios
El uso de datos generados aleatoriamente es posible con fines de demostración. Para activar esta función, configure el control deslizante en “Cargar datos” a un valor superior a 0 (establecer el valor nuevamente en 0 desactiva la función). Se genera un conjunto de datos de “objetos”, un conjunto de datos de “remontajes” y un conjunto de datos de “cronología”, lo que permite probar todas las funcionalidades de archeoViz
.
A través de los parámetros de la función R
La función de inicio de archeoViz (archeoViz()
) se puede ejecutar sin parámetros
archeoViz()
o usando los parámetros objects.df
, refits.df
o timeline.df
para ingresar datos.marcos sobre los objetos arqueológicos , las relaciones de remontajes entre estos objetos y la cronología de la excavación, respectivamente.
archeoViz(objects.df = NULL, # data.frame con datos sobre los objetos
refits.df = NULL, # data.frame para reacondicionar objetos
timeline.df = NULL) # data.frame opcional para la cronología de excavación
A través de parámetros de URL
La URL de una instancia en línea de archeoViz
puede incluir los parámetros:
objects.df=
refits.df=
timeline.df=
cuyos valores deben ser la URL de un archivo CSV respetando el formato archeoViz descrito anteriormente. Por ejemplo:
https://analytics.huma-num.fr/archeoviz/fr/?objects.df=https://zenodo.org/record/8003880/files/bilzingsleben.csv
Configuración secundaria de datos
Una vez que se cargan los datos, se puede realizar una subselección de los datos en el menú del lado izquierdo. La agrupación se puede realizar cruzando los siguientes parámetros: el modo de ubicación, las capas y la categoría del objeto.
Por Modo de ubicación
Si todos los objetos tienen una ubicación exacta o una ubicación vaga, no se propone ninguna opción. Sin embargo, si el conjunto de datos incluye una ubicación tanto exacta como imprecisa, es posible seleccionar solo una de estas opciones o ambas.
Por capa o categoría de objeto
Los datos se pueden agrupar de dos maneras: ya sea según su capa o según la variable “object_” seleccionada. Esta opción determina los colores de los puntos en los gráficos 3D y 2D y cómo agrupar los puntos al calcular cascos convexos y superficies de regresión 3D. Los subconjuntos se pueden definir por categorías de objetos, utilizando los campos “variable” y “valures”. Una vez que se selecciona uno de los “object_type” (u otras posibles variables “object_”), sus valores aparecen a continuación y se pueden seleccionar usando las casillas de verificación. La selección debe validarse haciendo clic en el botón “Validar”. Esta selección determina los datos que se mostrarán en los gráficos y tablas.
Visualización interactiva
Características generales
Los gráficos en las pestañas “Gráfico 3D”, “Mapa”, “Sección X” y “Sección Y” se generan utilizando plotly
.
Todos los gráficos son dinámicos e incluyen una barra de menú encima del gráfico con varias opciones (generar un archivo de imagen, hacer zoom, mover la vista, etc.). Consulte los detalles en el sitio web plotly
.
Al hacer clic en el elemento de una leyenda, se modifica la visualización:
- un simple clic en un elemento activa/desactiva su visualización;
- un doble clic en un elemento solo muestra este elemento (otro doble clic lo cancela).
Esta función permite elegir qué capas se muestran. Además, se puede establecer el tamaño de los puntos y si se deben representar o no las relaciones de reposición.
Finalmente, al hacer clic en un punto, se muestra información sobre ese punto en la tabla debajo del gráfico.
Visualización de la incertidumbre espacial
En archeoViz
, se hace una distinción entre ubicación exacta (dada como coordenadas x, y, z) y ubicaciones vagas (dada como rangos de coordenadas). Se pueden mostrar ambos tipos de ubicaciones. La incertidumbre de las ubicaciones vagas se puede visualizar representando objetos no como puntos sino como líneas, planos y volúmenes (si se dan rangos de coordenadas para una, dos o tres dimensiones espaciales, respectivamente). Tenga en cuenta que esta función consume muchos recursos y su uso con demasiados datos puede ralentizar significativamente la aplicación.
Salidas gráficas
Se pueden generar varios resultados gráficos enarcheoViz
.
- Los gráficos en las pestañas “Gráfico 3D”, “Mapa“, “Sección X” y “Sección Y” se pueden exportar:
- en formato SVG (haciendo clic en el ícono de “cámara” en la barra de menú sobre el gráfico),
- como gráficos interactivos en formato HTML, haciendo clic en el botón “Exportar“.
- El pequeño mapa en las pestañas “Sección X” y “Sección Y” se puede exportar en SVG haciendo clic en el enlace “Descargar mapa“.
- El plano de la cronología de la excavación se puede exportar en formato SVG haciendo clic en el botón “Descargar“.
Estadísticas espaciales
archeoViz
incluye algunas funcionalidades de análisis espacial, destinadas a un uso básico y exploratorio.
Superficies de regresión
En la pestaña “Gráfico 3D“, al hacer clic en “Calcular superficies” y “Validar” se muestra la superficie de regresión asociada con cada capa (con al menos 100 puntos). Las superficies se calculan utilizando el modelo aditivo generalizado implementado en el paquete mgcv
.
Cascos convexos
En la pestaña “Visualización 3D“, los cascos convexos se muestran:
- marcando la casilla “cascos convexos”,
- seleccionando, en el menú que aparece, los subconjuntos de puntos para los que deben calcularse los cascos,
- pulsando “Validar”.
El casco convexo asociado con cada capa (con al menos 20 puntos) se muestran. Los cascos convexos se calculan usando el paquetecxhull
.
densidad kernel 2D
En la pestaña “Mapa“, al marcar la casilla “Calcular densidad” y hacer clic en “Validar” se genera un mapa con líneas de contorno que muestran la densidad de los puntos. La densidad se puede calcular para todos los puntos juntos o por capa (con al menos 30 puntos). La densidad del núcleo 2D se calcula con la función kde2d
del paquete MASS
(a través de ggplot2
).
Reproducibilidad
archeoViz
es, por definición, una aplicación interactiva. Sin embargo, varias características garantizan la reproducibilidad y comunicabilidad del resultado de las interacciones con la aplicación.
- La visualización 3D se puede exportar en un formato independiente HTML interactivo, teniendo en cuenta la selección de datos realizada por el usuario.
- En la pestaña “Reproducibilidad”, se genera dinámicamente un comando R, teniendo en cuenta la configuración actual de la aplicación realizada por el usuario.
- En un uso más avanzado, los parámetros de URL permiten configurar una instancia en línea de los parámetros de interés de la aplicación y comunicarla mediante el envío de la URL.
Exportaciones desde y hacia aplicaciones de terceros
archeoViz
fue diseñado como uno de los componentes básicos de un ecosistema digital descentralizado para datos y análisis arqueológicos. En esta perspectiva, las características y funciones se distribuyen en múltiples aplicaciones interconectadas, en lugar de concentrarse en unos pocos sistemas. En consecuencia, los datos se pueden exportar e importar entre archeoViz
y otras aplicaciones basadas en la web. Tenga en cuenta que, hasta ahora, las funcionalidades de exportación solo están disponibles cuando se utilizan instancias archeoViz
en línea.
Exportar desde archeoViz
archeofrag es un paquete R y una aplicación web para evaluar y evaluar las distinciones entre unidades espaciales arqueológicas (por ejemplo, capas) basado en el análisis de las relaciones de remontajes entre fragmentos de objetos. La versión web de la aplicación incluye métodos para medir la cohesión y la mezcla de unidades espaciales y compararlas con datos simulados. Si se inicia una instancia de archeoViz
con datos de remontaje, estos datos se pueden analizar con archeofrag
de la pestaña “Statistics”. Cf. este ejemplo.
El Seriograph es una aplicación web (parte del SPARTAAS) collection) para visualizar cambios en la distribución cuantitativa de tipos de artefactos en series ordenadas o desordenadas de unidades espaciales. Si se inicia una instancia en línea de archeoViz con un conjunto de datos con al menos 2 valores diferentes para la variable layers
y 2 valores diferentes para object_type
entonces estos datos se pueden analizar con la aplicación Seriograph
desde la pestaña “Statistics”.
Cf. este ejemplo.
Importar a archeoViz
SEAHORS es una aplicación web y paquete R para visualizar la distribución espacial de restos arqueológicos. Como se mencionó, SEAHORS se puede usar para importar, remodelar y enviar un conjunto de datos a una instancia en línea de la aplicación archeoViz
.
Parámetros avanzados
La función archeoViz()
se puede configurar con múltiples parámetros opcionales, relacionados con:
- os datos de entrada (ya detallados arriba),
- el contenido de la página de inicio (ya detallado arriba),
- la cuadrícula,
- la preconfiguración de los parámetros que se pueden configurar a través de la interfaz de la aplicación
- el comportamiento reactivo de la aplicación con respecto a la generación de gráficos,
- export HTML,
- los parámetros de URL.
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 = 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
)
Cuadrícula
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érico. Tamaño (ancho y alto) en centímetros de los cuadrados en el sistema de cuadrícula. El valor predeterminado es 100 cm.
- reverse.axis.values : caractères. Nombre del eje o ejes a invertir (cualquier combinación de “x”, “y”, “z”).
- reverse.square.names : carácter. Nombre del eje o ejes para los que invertir el orden de las etiquetas cuadradas (cualquier combinación de “x”, “y”, “z”).
- add.x.square.labels : carácter. Etiquetas cuadradas adicionales para el eje “x”.
- add.y.square.labels : carácter. Etiquetas cuadradas adicionales para el eje “y”.
Preajuste de parámetros
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: carácter. Al iniciar la aplicación, nombre de la variable a preseleccionar.
- class.values: carácter. vector de caracteres. Al iniciar la aplicación, nombres de los valores para preseleccionar.
- default.group: carácter. carácter. Al iniciar la aplicación, ajuste preestablecido de la variable utilizada para agrupar datos (una de “by.layer” o “by.variable”).
- location.mode: carácter. Al iniciar la aplicación, ajuste preestablecido de los métodos de ubicación (cualquier combinación de “exact”, “fuzzy”, “show.uncertainty”).
- map.z.val: numérico. Valores mínimos y máximos de las coordenadas Z para mostrar en el gráfico del mapa.
- map.density: carácter. Al iniciar la aplicación, si desea calcular y mostrar los contornos de densidad en el gráfico del mapa (uno de “no”, “overall”, “by.variable”).
- map.refits: TRUE o FALSE. Ya sea para mostrar remontaje en el gráfico del mapa.
- plot3d.hulls: TRUE o FALSE. Al iniciar la aplicación, si calcular y mostrar cascos convexos en el gráfico 3D.
- hulls.class.values: carácter. Al iniciar la aplicación, los nombres de los subconjuntos de puntos para los que se calcularán los cascos convexos.
- plot3d.surfaces: TRUE o FALSE. Al iniciar la aplicación, si calcular y mostrar la regresión en el gráfico 3D.
- plot3d.refits: TRUE o FALSE. Al iniciar la aplicación, si mostrar remontaje en el gráfico de sección 3D.
- point.size: numérico. Al iniciar la aplicación, el tamaño de los puntos en las visualizaciones.
- sectionX.x.val: numérico. Al iniciar la aplicación, los valores mínimos y máximos de las coordenadas X se mostrarán en el gráfico de la sección X.
- sectionX.y.val: numérico. Al iniciar la aplicación, los valores mínimos y máximos de las coordenadas Y se mostrarán en el gráfico de la sección Y.
- sectionX.refits: TRUE o FALSE. Al iniciar la aplicación, si se muestran los remontajes en el gráfico de la sección X.
- sectionY.x.val: numérico. Al iniciar la aplicación, los valores mínimos y máximos de las coordenadas X se mostrarán en el gráfico de la sección Y.
- sectionY.y.val: numérico. Al iniciar la aplicación, los valores mínimos y máximos de las coordenadas Y se mostrarán en el gráfico de la sección Y.
- sectionY.refits: TRUE o FALSE. Al iniciar la aplicación, si se muestran los reacondicionamientos en el gráfico de la sección Y.
- camera.center: numérico. En el gráfico 3D, coordenadas del punto al que mira la cámara (valores predeterminados: x=0, y=0, z=0).
- camera.eye: numérico. En el gráfico 3D, las coordenadas de la posición de la cámara (valores predeterminados: x=1,25, y=1,25, z=1,25).
Visualización de gráficos reactivos
archeoViz(run.plots = FALSE)
- run.plots: TRUE o FALSE. Si calcular y mostrar gráficos inmediatamente (sin requerir que el usuario haga clic en el botón “Actualizar”).
Controlar los formatos de exportación
- html.export: TRUE o FALSE. Si permitir o no que las figuras se exporten como widgets HTML interactivos.
- table.export: TRUE o FALSE. Permita o no permita la transferencia de datos a aplicaciones de terceros en la pestaña “Estadísticas”.
Parámetros de URL
Una instancia de archeoViz
implementada en línea en un servidor se puede configurar con parámetros de URL. Los parámetros admitidos incluyen:
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
(Los siguientes parámetros no son compatibles con la versión actual: 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
.)
Los parámetros deben escribirse usando la sintaxis de URL (?param1=value¶m2=value2) y tener el mismo tipo de valores que cuando se usan en la interfaz de R. Por ejemplo, la siguiente URL inicia una instancia de archeoViz utilizando el conjunto de datos Bilzingsleben:
Esta URL hace lo mismo, pero también incluye la tabla de reacondicionamiento (parámetro &refits.df=
) y activa la visualización de las relaciones de reacondicionamiento en los gráficos 3D y de mapa:
La siguiente URL inicia el conjunto de datos de Bilzingsleben, preconfigurando la aplicación para:
- agrupa los puntos por variable (parámetro
default.group
, con valorby.variable
en lugar deby.layer
) - selecciona solo las “Astas” (parámetro
class.values
) - redefine el tamaño de la cuadrícula (parámetro
square.size
, 500 cm en lugar del valor predeterminado de 100 cm) - habilitar la visualización inmediata de los gráficos (parámetro
run.plots
) - modifica el título de la página (parámetro
title
) - modifica el contenido de la página de inicio con contenidos HTML básicos (parámetro
home.txt
)
<a href="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%20antlers&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=Antlers%20at%20Bilzingsleben&home.text=Many%20antlers&objects.df=https://zenodo.org/record/8003880/files/bilzingsleben.csv
Tenga en cuenta que los parámetros add.x.square.labels
, add.y.square.labels
, location.mode
, et class.values
, que aceptan valores simples o múltiples en la interfaz de R (p. ej., c(“value1”, “value2”)) solo aceptan un valor cuando se establecen como parámetros de URL (esta es una restricción debido a la sintaxis de la URL).
Agradecimientos
La aplicación y el paquete archeoViz
son desarrollados y mantenidos por Sébastien Plutniak. Arthur Coulon, Solène Denis, Olivier Marlet y Thomas Perrin probaron y apoyaron el proyecto en su etapa inicial. Renata Araujo, Laura Coltofean, Sara Giardino, Julian Laabs, y Nicolas Delsol tradujeron la aplicación al portugués, rumano, italiano, alemán, y español respectivamente.
Referencias
Software
- Plutniak, Sébastien, Renata Araujo, Laura Coltofean, Nicolas Delsol, Sara Giardino, Julian Laabs. 2023. “archeoViz. Visualisation, Exploration, and Web Communication of Archaeological Spatial Data”. v1.3.2, DOI: 10.5281/zenodo.7460193.
- Plutniak, Sébastien, Anaïs Vignoles. 2023. “The archeoViz Portal: Dissemination of Spatial Archaeological Datasets”, portail web, https://analytics.huma-num.fr/archeoviz/home.
Articulos
- Plutniak, Sébastien. Submitted. “archeoViz: an R package for the Visualisation, Exploration, and Web Communication of Archaeological Spatial Data”. Journal of Open Source Software.
- Plutniak, Sébastien. 2023. “Visualiser et explorer la distribution spatiale du mobilier archéologique : l’application archeoViz et son portail web”. Bulletin de la Société préhistorique française, 120(1), p. 70-74.
Presentationes
- Plutniak, Sébastien. 2023. “Fostering the Publication of Spatial Archaeological Data: a Decentralized Approach. The archeoViz Web Application and its Portal”, diapositivas de una presentación en la Universidad de 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, diapositivas de una presentación en el SITRADA workshop, Paris.
Sitios web
- El blog archeoViz. Data visualization in archaeology. Re-use, visualization, dissemination of spatial data: https://archeoviz.hypotheses.org
Documentation technique de l’application archeoViz
Cette documentation est également disponible dans l’onglet « Aide » de l’application et dans une vignette du package sur le CRAN.
- Installation
- Recommandations communautaires
- Utilisation
- L’information spatiale dans archeoViz
- Remontages et mesures de fabrique
- Format de données
- Charger des données
- Sous-sélection de données
- Visualisations interactives
- Généralités
- Sorties graphiques
- [Visualisation de l’incertitude spatiale](#visualisation-de-l-incertitude spatiale)
- Statistiques spatiales
- Reproductibilité
- Exports depuis et vers des applications tierces
- Paramètres avancés
- Remerciements
- Références et ressources
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:
install.packages("archeoViz")
La version de développement peut être téléchargée depuis GitHub:
# install.packages("devtools")
devtools::install_github("sebastien-plutniak/archeoviz")
Après quoi, chargez le package et lancez l’application avec:
library(archeoViz)
archeoViz()
Déployée
Pour déployer archeoViz
sur votre Shiny server, téléchargez premièrement le package:
# 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:
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.
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.archeoViz
en anglais.archeoViz
en allemand.archeoViz
en espagnol.archeoViz
en italien.archeoViz
en portugais.archeoViz
en roumain.
Des cas d’applications à divers sites archéologiques sont rassemblés sur le Portail archeoViz.
Recommandations communautaires
Signaler un bug
Si vous rencontrez un bug, ouvrez une issue 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 ou, mieux encore, en employant une pull requests et le modèle GitHub Fork and Pull.
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 entre fragments d’objets, d’orientation (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 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:
- 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.
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.
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 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 instancearcheoViz
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 100cm 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
etadd.y.square.labels
de la fonctionarcheoViz()
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
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
.
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.
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
.
Enveloppes convexes
Dans l’onglet “Vue 3D”, l’affichage des enveloppes convexes se réalise en:
- cochant la case “Enveloppes convexes”,
- sélectionnant, dans le menu qui s’affiche, les sous-ensembles de points pour lesquels les enveloppes doivent être calculées,
- 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 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.
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
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, alors ces données peuvent être analysées avec archeofrag
à partir de l’onglet “Statistiques”. Cf. cet exemple.
Le Seriograph est une application web (inclues dans la collection SPARTAAS) 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.
Lorsqu’une instance d’archeoViz
est executée avec un jeu de données contenant au moins 2 valeurs différentes pour la variable layers
et 2 valeurs différentes pour la variable object_type
, alors ces données peuvent être analysées avec l’application Seriograph
à partir de l’onglet “Statistiques”. Cf. cet exemple.
Import vers archeoViz
SEAHORS est une application web et un package R permettant de visualiser la distribution spatiale d’objets archéologiques. Comme indiqué ci dessus, 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),
- 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 = 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
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 (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
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 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¶m2=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:
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:
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 valeurby.variable
plutôt queby.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 100cm) - 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
)
<a href="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%20antlers&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=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).
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. 2023. “archeoViz. Visualisation, Exploration, and Web Communication of Archaeological Spatial Data”. v1.3.2, DOI: 10.5281/zenodo.7460193.
- Plutniak, Sébastien, Anaïs Vignoles. 2023. “The archeoViz Portal: Dissemination of Spatial Archaeological Datasets”, portail web, https://analytics.huma-num.fr/archeoviz/home.
Articles
- Plutniak, Sébastien. Submitted. “archeoViz: an R package for the Visualisation, Exploration, and Web Communication of Archaeological Spatial Data”. Journal of Open Source Software.
- Plutniak, Sébastien. 2023. “Visualiser et explorer la distribution spatiale du mobilier archéologique : l’application archeoViz et son portail web”. 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”, 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, 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
Documents and References related to the archeoViz Application
Publications
- Plutniak, Sébastien. 2023. “archeoViz: an R package for the Visualisation, Exploration, and Web Communication of Archaeological Spatial Data”. Journal of Open Source Software. 8 (92), 5811, doi: 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”. Bulletin de la Société préhistorique française, 120(1), p. 70-74.
Presentation slides
- Plutniak, Sébastien, Anaïs Vignoles, Élisa Caron-Laviolette. 2024. “Keep Control of Your Data! A Decentralized, Open-Source and Community-Driven Approach to Archaeological Data Sharing Through the archeoViz Portal”, slides of a presentation given at the EAA 2024 conference, Rome, Italy.
- Plutniak, Sébastien. 2023. “Fostering the Publication of Spatial Archaeological Data: a Decentralized Approach. The archeoViz Web Application and its Portal”, slides of a presentation at the 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, slides of a presentation at the SITRADA workshop, Paris.
Software
- Plutniak, Sébastien, Anaïs Vignoles. 2023. “The archeoViz Portal: Dissemination of Spatial Archaeological Datasets”, web portal, https://analytics.huma-num.fr/archeoviz/home.
- Plutniak, Sébastien, Renata Araujo, Sara Giardino, Julian Laabs. 2025 “archeoViz. Visualisation, Exploration, and Web Communication of Archaeological Spatial Data”. v1.4.0, DOI: 10.5281/zenodo.15341154.
- Plutniak, Sébastien, Renata Araujo, Sara Giardino, Julian Laabs. 2023. “archeoViz. Visualisation, Exploration, and Web Communication of Archaeological Spatial Data”. v1.3.0, DOI: 10.5281/zenodo.8180527.
- Plutniak, Sébastien, Renata Araujo, Sara Giardino, Julian Laabs. 2023. “archeoViz. Visualisation, Exploration, and Web Communication of Archaeological Spatial Data”. v1.2.1, DOI: 10.5281/zenodo.8092474.
- Plutniak, Sébastien, Renata Araujo, Sara Giardino. 2023. “archeoViz. Visualisation, Exploration, and Web Communication of Archaeological Spatial Data”. v1.1.1, DOI: 10.5281/zenodo.7938998.
- Plutniak, Sébastien. 2023. “archeoViz. Visualisation, Exploration, and Web Communication of Archaeological Excavation Data”. v0.2.1, DOI: 10.5281/zenodo.7512526.
archeoViz Portal
The archeoViz Portal, as a data repository, is referenced in:
- Cat OPIDoR: https://cat.opidor.fr/index.php/Portail_archeoViz
- re3data.org, doi: 10.17616/r31njnoz
- fairsharing.org, doi: https://fairsharing.org/6317
Technical documentation of the archeoViz application
The documentation is also available in the “Guidelines” tab of the application and on the github repository.
- Installation
- Community Guidelines
- Use
- Reproducibility
- Exports from and to Third-party Applications
- Advanced Parameters
- Acknowledgments
- References
Installation
archeoViz
can be used in two ways:
- locally, on the user’s machine
- remotely, after deploying the app on a distant server
Local use
The package can be installed from CRAN with:
install.packages("archeoViz")
The development version is available on GitHub and can be installed with:
# install.packages("devtools")
devtools::install_github("sebastien-plutniak/archeoviz")
Then, load the package and launch the app with:
library(archeoViz)
archeoViz()
Remote use
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
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.
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.
Translation
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.
Use
Having archaeological remains from a given site, archeoViz
is designed to lower the technical barriers to fulfill three objectives:
- basic spatial exploration and generation of simple graphical reports;
- fast pre-publication of archaeological data, intended for the scientific community;
- fast deployment of a visualisation and communication tool intended for a broader audience.
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.)
Spatial Information in archeoViz
Archaeologists record the location of archaeological objects at different scales and granularity. Accordingly, they use different geometrical concepts to represent location.
Points, Exact Location: Plotted Objects
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).
Points, Vague Location: Spits, Buckets, Sieved Objects, and Recording Errors
However, it is also common that x, y, z, coordinates by object are not available, for different reasons due to:
- recording errors, loss of information, resulting in the need to replace one of several coordinates values by ranges (e.g., a X value is missing for an object and is replaced by the minimal and maximal X values of the square where this object was found); choice of method (e.g., excavation made and recorded using spits of arbitrary depth, sieved objects, etc.).
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
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
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 and Fabric Measurements
Refittings
Refittings are usually recorded by archaeologists in two ways:
- by sets of refitting objects: using a two columns table, where a row corresponds to an object. The first column stores the object’s unique id and the second column stores the id of the set of refitting objects this object belongs to.
- 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 and represents the two data structures in two ways:
- sets of refitting objects must be described using a specific column in the
objects.df
table (e.g.object_refits
) and are represented by the color of points in the plots (like any other variable); - refitting relationships must be described using the
refits.df
table and are visualised as segments connecting the refitting objects in the plots.
Fabric Measurements
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:
- assuming that fabric measurements were recorded with two measurements
on each object (and not with dip and plunge measurements), - different unique
id
values must be given to the two points, and - the two measures are processed as if they were two refitting objects.
See an example of this method here.
Data Format
Three types of data can be loaded in archeoViz
:
- an “objects” table (mandatory), with data about the objects;
- a “refits” table (optional), with data about the refitting objects;
- a “timeline” table (optional) giving the year when each square of the site was excavated or surveyed.
Formatting Data
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:
- either using a spreadsheet editor on your machine to generate CSV files;
- or, for the
objects table,
using the SEAHORS application to load your data, define the variables (in the “Load data” tab), and export it to thearcheoViz
format (in the “Table” / “archeoViz exports” tab). It is also possible to directly send the data to an onlinearcheoViz
instance.
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
- ymin: numerical value, coordinate of the object on the Y axis
- zmin: numerical value, coordinate of the object on the Z axis (positive depth value)
- 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 variables 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 to avoid erroneous displays, if the number of labels does not correspond exactly to the total number of 100 (cm, m, km) 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
andadd.y.square.labels
parameters of thearcheoViz()
function in order to add the missing labels (on the X and Y axes of the grid, respectively).
Refitting Table
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).
Timeline 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:
- year: numerical value, the year of excavation
- square_x: alphanumerical value, identifier of the excavated square on the X axis
- square_y: alphanumerical value, identifier of the excavated square on the Y axis
Background Drawing
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.
Data Input
There are four ways to input data in archeoViz
:
- uploading data tables through the “Input data” tab,
- loading data tables through the
archeoViz
function’s parameters, in the R interface; - uploading data tables through URL parameters, when using an online instance of
archeoViz
. - generating random data in the “Input data” tab;
Through the Application Interface
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).
Through URL parameters
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
Generating Random Data
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.
Through the R function parameters
archeoViz
’s launching function (archeoViz()
) can be run without parameter
archeoViz()
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.
archeoViz(objects.df = NULL, # data.frame with data about the objects
refits.df = NULL, # data.frame for refitting objects
timeline.df = NULL) # optional data.frame for the excavation timeline
Rotating the points
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.
Data Sub-setting
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.
By Location Mode
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.
By Layer or Object Category
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.
Interactive visualisation
General features
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:
- a simple click on an item activates/deactivates its display;
- a double click on an item displays this item only (another double click cancels it).
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.
Visualising Spatial Uncertainty
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.
Graphical outputs
Several graphical outputs can be generated in archeoViz
.
- The plots in the “3D plot”, “Map”, “Section X”, and “Section Y” tabs can be exported:
- in SVG format (by clicking on the “camera” icon in the menu bar above the plot),
- as interactive plots in HTML format, by clicking on the “Export” button.
- The small map in the “Section X” and “Section Y” tabs can be exported in SVG by clicking on the “Download Map” link.
- The plan of the excavation chronology can be exported in SVG format by clicking on the “Download” button.
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, convex hulls can be displayed as follows:
- tick the “Convex hulls” box,
- select, from the menu that appears, the subsets of points for which convex hulls are to be calculated,
- click on “Validate”.
Convex hulls associated with each subsets with at least 20 points are displayed. 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.
- The 3D visualisation can be exported in an interactive HTML standalone format, considering the data selection made by the user.
- In the “Reproducibility” tab, an R command is dynamically generated, considering the current application settings made by the user.
- In a more advanced use, the URL parameters makes it possible to set an online instance of the application parameters of interest and to communicate it by sending the URL.
Exports from and to Third-party Applications
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.
Export from archeoViz
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.
Import to archeoViz
SEAHORS is a web application and R package to visualise the spatial distribution of archaeological remains. As mentioned above, SEAHORS can be used to import, reshape, and send a dataset to an online instance of the archeoViz
application.
Advanced parameters
The archeoViz()
function can be set with multiple optional parameters, related to:
- the input data (see above),
- the contents of the home page (see above),
- the square grid,
- the presetting of the parameters that can be set through the application’s graphical interface,
- the reactive behavior of the application regarding the generation of plots,
- the HTML export,
- the URL parameters.
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
)
Coordinates
archeoViz(unit = "cm", rotation = 0, reverse.axis.values = NULL)
- unit: character. Unit for spatial distances. One of “cm”, “m”, “km”.
- rotation: integer. Value (degrees) for the in-plane rotation of the point cloud.
- reverse.axis.values: character. Name of the axis or axes to be reversed (any combination of “x”, “y”, “z”).
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.
Square grid
archeoViz(square.size = 100,
grid.orientation = NULL,
reverse.square.names = NULL,
add.x.square.labels = NULL, add.y.square.labels = NULL
)
- square.size: numerical. Size (width and height) of the squares in the grid system. Default value is 100.
- grid.orientation: numerical. Orientation (degrees, positive or negative) of the grid (0 corresponds to a north orientation).
- 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.
Background drawing
archeoViz(background.map = NULL)
- background.map: data frame or matrix. Coordinates to draw lines on the background of the 3D and Map plots. See for example the Anyskop Blowout instance.
Parameter presetting
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: 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, preset of the variable used to group data (one of “by.layer” or “by.variable”).
- location.mode: character. At the launch of the app, preset of the location methods (any combination of “exact”, “fuzzy”, “show.uncertainty”).
- 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.
- hulls.class.values: character. At the launch of the app, names of the points subsets for which to compute convex hulls.
- 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.
- point.size: integer. At the launch of the app, size of the points in the plots.
- 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
archeoViz(run.plots = FALSE)
- run.plots: TRUE or FALSE. Whether to immediately compute and show plots (without requiring the user to click on the “Refresh” button).
Control Export Formats
- html.export : TRUE or FALSE. Whether or not to allow figures to be exported as interactive HTML widgets.
- table.export: TRUE or FALSE. Allow or disallow data transfer to third-party applications in the “Statistics” tab.
URL parameters
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:
- groups the points by variable (parameter
default.group
, with walueby.variable
instead ofby.layer
) - selects only the “Antlers” (parameter
class.values
) - redefines the size of the square grid (parameter
square.size
, 500 instead of the 100 default value) - enable the immediate display of the plots (parameter
run.plots
) - modifies the title of the page (parameter
title
) - modifies the content of the home page with basic HTML contents (parameter
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).
Acknowledgments
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.
References
Software
- 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.5, DOI: 10.5281/zenodo.12200494.
- Plutniak, Sébastien, Anaïs Vignoles. 2023. “The archeoViz Portal: Dissemination of Spatial Archaeological Datasets”, web portal, https://analytics.huma-num.fr/archeoviz/home.
Papers
- 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.
- Plutniak, Sébastien. 2023. “Visualiser et explorer la distribution spatiale du mobilier archéologique : l’application archeoViz et son portail web”. Bulletin de la Société préhistorique française, 120(1), p. 70-74.
Presentations
- Plutniak, Sébastien. 2023. “Fostering the Publication of Spatial Archaeological Data: a Decentralized Approach. The archeoViz Web Application and its Portal”, slides of a presentation at the 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, slides of a presentation at the SITRADA workshop, Paris.
Websites
- The archeoViz. Data visualization in archaeology. Re-use, visualization, dissemination of spatial data blog: https://archeoviz.hypotheses.org