---
title: 'arabesque tutorial: quick documentation'
disqus: hackmd
---



*Arabesque* quick tutorial (v.0)
===

Réalisation : Equipe gflowiz, 2019.

Licence : CC-BY-SA.

## Contents

[TOC]

## Introduction générale

***arabesque*** is a web application for thematic flow mapping developped, developed as part of the *geographic flow visualisation (gflowiz project)*. See: https://geoflowiz.hypotheses.org for details.

arabesque is available free of charge at the following address: http://arabesque.ifsttar.fr/

The general documentation (work in progress) and computer code are provide on the following repository: https://github.com/gflowiz/arabesque

***arabesque*** is configured to work correctly on Chromium and Mozilla.

***arabesque*** allows you to import your own flow datasets, in the form of an origin-destination matrix (list format in CSV), explore them, filter them to create a readable flow map, in accordance with the principles of cartographic semiology

The realization of a flowmap in arabesque is composed of 5 steps:
1: Importing flow data
2: flow data data (links and nodes) processing
(creation of indicators, statistics)
3: Data mining and filtering
4: Graphical Symbolisation
5: Export

## 1. Data importation

For a first discovery of ***arabesque***, you can use the data sets provided as example in the **Demo section**.


For this tutorial, we used the French national commuting in 2015 (flows up to 100 commuters).

Source : Mobilités professionnelles en 2015 : déplacements domicile - lieu de travailRecensement de la population - Base flux de mobilité (INSEE, 2015). https://www.insee.fr/fr/statistiques/fichier/3566477/base-excel-flux-mobilite-domicile-lieu-travail-2015.zip

### 1.1 Link dataset

arabesque requires loading at least one set of flow data : a .CSV link file (separator : comma) in long format.

You must also declare the 3 minimum fields required for flow mapping: those corresponding to the places of origin, the places of destination, and the flow values.

If the OD the matrix is temporal or categorical, you must also choose and aggregation method if necessary.

On the home page of arabesque ([arabesque](http://arabesque.ifsttar.fr/)) select at least a link flow dataset


and

**Application**
Chargement des données *SAGEO_RICardo_edges_small.csv*


### 1.2. Node dataset

If you have locationnal data associated to your OD links, you can load the corresponding nodes files by "**import Location**", else you can "**Preset Location**".

#### 1.2.1. **Import Location**

If selecting "**Import Location**", you have to load a GEOJSON file, then choose the nodes ID and their lat/long geographical coordinates

**Application**
Chargement des données *SAGEORICardonodes.csv*


#### 1.2.2. **Preset Location**

When selecting "**Preset Location**", you just have to choose the corresponding geonumerical nodes level, region and code (if available yet,otherwise you need to load your own node file).



After loading the links and nodes files,the application automatically performs an attribute join between the two files.

Links that do not have an origin or destination ID are automatically deleted, similarly for the nodes.

The complete list of removed is then proposed, only for viewing - so you must copy it if you want to keep the list


By clicking ok, you enter directly in the **arabesque** interface.

## 2. Présentation de l'interface

The interface automatically calculates indicators, for links and nodes; it also produces a first map with default parameters that can all be modified.

### Automatic addition of indicators
The data sets are automatically modified during their importation: **arabesque** calculates the following indicators which are available in CSV (see export and backup section):

**Links indicators :**
euclidian distance between origin and destination places

**Nodes indicators :**



## Automatic symbolization

The map made with Arabesque default settings is as the example.


To act or modify the map, three boards are available.

## 2.1. Panneau de gauche

La gestion des couches est réalisée sur la partie de gauche de l'interface. Elle composée de deux sous-parties:
-- Projections
-- Titre (ajout d'un)
-- Création et symbolisation de différents types de couches (*Add Layers*)

Gestion des couches :
manipulation et disposition, symbolisation
-- Liens
-- Noeuds
-- autres couches

## 2.2. Partie centrale de l'interface

La partie centrale correspond à la vue cartographique. Elle résulte du choix des couches à afficher et de leur symbolisation (réalisé sur le panneau de gauche) ainsi que du filtrage des valeurs des liens et des noeuds (réalisé sur le panneau de droite).

Elle présente en outre différents boutons permettant la mise en oeuvre d'actions primaires.

### 2.2.1. Actions primaires

 Icône permettant de revenir à la page d'accueil arabesque.ifsttar.fr pour commencer une nouvelle visualisation.

Boutons permettant de réaliser successivement des zooms avant et après de la vue - de la même façon qu'avec la molette de la souris.

 Bouton permettant de sauvegarder le projet pour pouvoir l'utiliser ultérieurement.

 Bouton visant à exporter la carte au format image (.PNG), en inclant les légendes et les sources des contributeurs pour les fonds externes tels que *NaturalEarth*, par exemple.

 Bouton entraînant le recentrage et l'affichage de l'emprise totale des flux - sans zoomer/dé zoomer ni paner.

 Bouton servant à exporter les données filtrées - celles qui sont visibles sur la carte - sous la forme d'un fichier liste au format .JSON.

 Bouton permettant d'afficher / masquer la légende.

 Bouton permettant de passer en mode d'affichage en plein écran (et fond noir)

 Bouton permettant d'ouvrir ou de fermer les panneaux situés de chaque coté de la carte.

### 2.2.2. Légende

Une légende est générée automatiquement pour chaque carte, elle reprend les éléments de symbolisation (taille, couleur et opacité) présents sur la carte pour symboliser les indicaters présentés. Ici, le volume des flux et le nombre de degrés des lieux.

## 2.3. Panneau de droite
**L'exploration et le filtrage** des données est effectuée sur la partie droite.

Elle permet d'agir sur n'importe laquelle des variables caractérisant les noeuds et/ou les liens et/ou la distance parcourue par les flux (variable calculée lors du chargement des données).

Les résultats de l'application d'un ou de plusieurs filtres sont proposés par défaut en tête du panneau.


# 3. Projection

Pour les données observées **à l'échelle mondiale ou régionale (sub-continentale)**, il est possible de changer la projection du fond de carte proposé ou de la vue affichée - pour les données locales, il est possible d'ajouter des tuiles vectorielles (voir section 5.5).

Pour cela, il faut soit sélectionner le système de projection dans une liste pré-établie, soit renseigner directement son code EPSG identifiant (*European Petroleum Survey Group*).

Exemple : World Mollweide
(EPSG Correspondant : 54009)


# 4. Ajout d'un titre

Il est possible d'ajouter un titre simple sur la vue principale.

# 5. Symbolisation et gestion des couches géographiques

Il est possible d'agir sur la symbolisation graphique des différentes couches dessinées en :
-- modifiant leur apparence ;
-- ajouter de nouvelles couches qui serviront d'habillage ;
-- gérant la disposition des différentes couches


## 5.1. Symbolisation des noeuds

La symbologie des noeuds consiste à paramétrer leur dessin, et à appliquer des variables visuelles permettant d'enrichir qualitativement la carte.

### 5.1.1. Couleur

**Couleur / Fixe** :
La teinte est identique pour tous les noeuds.


**Application sur les noeuds** : symbolisation des noeuds (barycentre des zones) avec une *forme* cercle de *taille* fixée et de teinte unique noire.


**Couleur / Variable** :
La teinte des noeuds ne sera pas identique pour tous, mais basée sur un dégradé de ton prédéfini. Le choix de la progression (divergente ou non) sera fonction du type de caractère (précisé dans le champs type).

Le choix de nuancer la teinte des noeuds est associé ici à un caractère (ici le nombre de degrés pondéré - *weighted degree*) dont on précise le type (quantitatif).

Idéalement, il est nécessaire de paramétrer simultanément la taille des noeuds, en utilisant le même caractère (ici le nombre de degrés pondéré - *weighted degree*) - sinon, les noeuds conserveront la même taille et le résultat de l'application d'une nuance sera peu visible.


### 5.1.2. Taille

**Taille / Fixe** :
La taille (surface) des noeuds est identique pour tous et fixée sur une valeur donnée.

**Taille / Variable**
La taille (surface) des noeuds est variable, selon une fonction (racine, racine carrée ou logarithmique) proportionelle à la valeur d'un caractère (quantitatif discret - de stock).

La correspondance entre les valeurs du caractère et leur symbolisation graphique est paramétrable grâce à l'application d'un *ratio*.


Le *ratio* est fixé par défaut à 0,02% de la plus grande dimension du rectangle d’encombrement maximal du jeu de données de flux.

### 5.1.3. Texte
Une étiquette, correspondant aux modalités d'un des champs du jeu de données sélectionné, peut être ajoutée aux noeuds, sa teinte et son opacité fixées.


### 5.1.4. Opacité
L'opacité consite à agir sur le degré de transparence d'une teinte.

**Opacité / Fixe** :
L'opacité de la teinte des noeuds est identique pour tous les noeuds, elle est paramétrable, entre 0 et 1.


**Opacité / Variable** :
L'opacité de la teinte des noeuds est variable, en fonction d'un caractère (ici le degré pondéré, *weighted degree*), selon une fonction (linéaire, carrée, racine carrée et logarithmique) paramétrable, dont il est possible de définir les valeurs minimum et maximum, respectivement 0.25 et 0,85, par défaut.


**Application sur les noeuds** : symbolisation des noeuds avec une *forme* cercle de *taille* variable selon une fonction linéaire, représentée avec une teinte noire nuancée avec une variation d'opacité

## 5.2. Symbolisation des liens

La symbologie des liens consiste à paramétrer leur dessin, et à appliquer des variables visuelles permettant d'enrichir qualitativement la carte.

Exemple: lien droits bilatéraux orientés, teinte noire unique

## 5.2.1. Géometrie

**Géométrie / Orientée**

La géométrie orientée prend en compte la direction des flux, si nécessaire.


**Géométrie / Non Orientée**

La géométrie orientée ne tient pas en compte de l'éventuelle direction des flux.

## 5.2.2 Type (de géométrie du lien)

Le *type* de la géométrie correspond à l'application de la (variable visuelle) forme du corps du lien, que celui-ci soit orienté ou non.


**Type / Droit : straight **
Le lien est rectilinéaire et orienté, grâce à une demi-tête de flèche

**Type / Droit sans crochet : straight no hook **
Le lien est rectilinéaire et orienté, il présente une pointe sans crochet

**Type / Triangle : triangle **
Le lien est rectilinéaire et prend la forme d'un triangle

**Type / courbe : curve**
Le lien est courbe et orienté, sa courbure est paramétrable.

**Type / Triangle courbe : triangle curve**
Le lien est courbe et prend la forme d'une goutte d'eau, sa courbure est paramétrable.

## 5.2.3. Flèche (*Arrow*)

La *flèche* de la géométrie du lien correspond à la (variable visuelle) forme de la tête du lien, lorsque celui-ci est orienté.

La courbure de cette tête est générée, selon l'algorithme de Chaikin qui permet de paramétrer sa hauteur et sa base, par rapport aux corps du lien.


**Arrow / Hauteur** (*Height curve*): La valeur de la hauteur de la tête est le pourcentage de la distance cartographique du lien (distance entre l'origine et la destination) utilisé pour définir la largeur (cartographique) maximale du lien - la largeur étant elle même fonction de la valeur du flux.

**Arrow / Hauteur** (*Base*) : La valeur de ([0,1]) est celle du centre de la courbe ; le point est identifié par l'indication d'un d'éloignement au nœud d'origine du lien.

## 5.2.4. Couleur

**Couleur / Fixe** :
La teinte des liens est identique pour tous.

**Couleur / Variable** :
La teinte des liens n'est pas identique pour tous, elle est basée sur un dégradé de ton prédéfini. Le choix de la progression (divergente ou non) sera fonction du type de caractère (précisé dans le champs type).

Le choix de nuancer la teinte des liens est associé ici à un caractère (pseudo) continu dont il est nécessaire de préciser le type (quantitatif).

Idéalement, il est nécessaire de paramétrer simultanément la *taille* des liens, en utilisant un caractère discret (ici le nombre de degrés pondéré - *weighted degree*) et leur couleur en utilisant un caractère continu (rapport ou taux) - sinon, les liens conserveront la même taille et le résultat de l'application d'une nuance sera peu visible.

### 5.3.5. Taille (*size*)



**Application sur les liens** : symbolisation des liens de forme triangle courbe avec une couleur variable, présentant une variation d'opacité

Paramètres :

Carte résultat :

-- Sommets placés sous les noeuds

-- Sommets placés sur les noeuds (voir section gestion des dispositions)

## 5.4. Ajout d'un fond géonumérique


Différents fonds de carte ou éléments d'habillage vectoriels, préchargés sont proposés. Leur sélection est réalisée à partir d'une liste.


La symbolisation de ce nouveau fond d'habillage peut être modifiée en paramétrant l'apparence du dessin de ses contours et fonds, de sa teinte et de son opacité.

Ex : choix d'ajouter une "bounding box" qui correspond à l'espace de définition de la carte, et symbolisation du fond en bleu.


Il est également possible d'importer un fond en indiquant son URL : 

**Applications sur la vue en cours**
-- Ajout d'une *bounding box*,symbolisation graphique et disposition en arrière-plan (voir section Gestion des dispositions).

-- Ajout de lignes *graticules_20*, et disposition au-dessus de la *bounding box* (voir section Gestion des dispositions).


-- Ajout d'une couche *land* (espaces continentaux), placée au-dessus des graticules


-- Variante, sans graticule, par modification de la teinte de la *bounding box*

## 5.5. Ajout de couches de tuiles

Pour les données observées à l'échelle locale, il est possible d'ajouter des couches tuiles - la mention des contributeurs sera alors insérée automatiquement sur la carte, en bas à droite.


Plusieurs tuiles sont proposées, elles sont triées par fournisseur


et par type de tuile (texte - Fond de carte)

### 5.3.2. Exemple de chargement de tuiles
1. Selectionner Carto_basemap dans **Type**
2. Selectionner Carto_Dark_NoLabel dans **tiles**
3. Cliquer sur 
4. Un fond de carte vient alors recouvrir la carte affichée sur la partie centrale, cachant alors les flux.
5. Il faut ensuite gérer la disposition des couches pour parfaire l'affichage.

### 5.3.3. Ajout de ses propres tuiles
Il est également possible d'ajouter ses propres tuiles *via* un géo serveur, en cliquant sur 

## 5.5. Import d'une couche .GEOJSON

Quelle que soit l'échelle (mondiale, régionale ou locale) il est possible d'ajouter un fond de carte vectoriel quelcoque, au format geojson.

Pour cela,il faut charger son ficher et le nommer.


Ensuite, il est possible de modifier son dessin, sa couleur de fond et de contour.

## 7. Gestion et disposition des couches

L'ajout de couches d'information contribue à masquer les couches initiales de noeuds et de liens ; les dernières couches ajoutées s'étant placées au premier plan.


## 7.1. Modifier la disposition des couches

Pour rendre les flux visibles, il convient de modifier la disposition des différentes couches, en changeant leur ordre - par glisser / déplacer (*drag & drop*).

1. Cliquer sur la couche ***link*** et la maintenir appuyée ;
2. Glisser / déplacer la couche ***link*** et la placer au premier plan ;
3. Relacher la couche ;
4. Répéter la même opération avec la couche ***node*** si nécessaire.


On observe ainsi que la couche des flux vient d'être mis au premier plan.

**Application sur la vue en cours**
Disposition actuelle des différentes couches


## 7.2. Gérer l'apparence des couches

Les vignettes correspondant aux différentes couches présentent des icônes permettant de gérer leur apparence.

 : Masquer une couche

 : Afficher (rendre visible) une couche

 : Supprimer une couche

 : Paramétrer une couche de liens

 : Modifier l'apparence d'une couche de liens

### 7.2.1 Paramétrer une couche de liens

L'apparence des couches de liens (forme, couleur, opacité, taille) peut être modifiée à deux moments : soit lors de l'import, ou de la création de la couche - ce qui entraînera alors la suppression de la couche actuelle - (voir section 5.2), soit lors de la gestion des couches affichées, en agissant sur les icônes : 

**Modifier le style des liens**
Le bouton  permet d'accéder à la fenêtre de paramétrage du style de la couche de liens.


**Modifier le style des flèches**

Le bouton  permet de modifier le style des flèches


# 8. Filtrage des couches numériques

Il est réalisé soit visuellement à l’aide d’une fenêtre de sélection sur un histogramme interactif à fenêtre coulissante (*slider*), soit de manière numérique (en indiquant un seuil).

La part d’information sélectionnée, les valeurs minimales et maximales sont indiquées automatiquement sur la figure. Pour les liens, la possibilité d’un filtrage selon la distance géodésique parcourue est en outre proposée.


**Application sur la vue en cours**
L'affichage des filtres par défaut est le suivant.


L'application précise littéralement les valeurs de filtrage :
-- la part en pourcentage de liens (figurés) représentée (ici 10% de l'ensemble des liens)
-- la part en pourcentage du total de l'information de flux (valeur) représentée (83,5%)
-- la part en pourcentage de l'ensemble des noeuds : 36,5%

>>***Commentaire*** : *84% de l'information de flux est échangée entre 36% des lieux qui représentent les 10% de liens les plus forts, en volume - seul un tiers des lieux est impliqué dans ces échanges.*

## 8.1 Filtrage numérique
Il est possible de modifier ces paramètres de filtrage, en agissant sur les données de flux (liens ou noeuds)


### 8.1.1. Modification des paramètres de filtrage sur le volume

-- Représentation de l'ensemble des échanges

-- Sélection des 25% des échanges les plus importants,soit 8% des noeuds et 0,6% des liens les plus forts


-- Sélection des 50% des échanges les plus importants,soit 14% des noeuds et 2% des liens les plus forts


### 8.1.2. Création d'un filtre sur les liens, selon la distance parcourue



-- Modification des paramètres de distance

Sélection des flux parcourant entre 4000 et 12000 kilomètres


-- Résultat
>> ***Commentaire*** : la sélection des flux commerciaux qui parcourent de l'ordre de 4000 à 12000 kilomètres de distance correspond aux flux commerciaux à moyenne distance, qui s'expriment principalement dans l'hémisphère nord..
Ces flux de moyenne distance représentent 34% du volume total de marchandises qui correspond à 25% des relations financières commerciales les plus importantes, qui s'expriment entre 4% des pays les plus riches.
On notera que seules l'Amérique du nord et des pays de l'Europe de l'ouest sont impliqués dans ces échanges - dont on rappelle qu'ils correspondent au cumul des valeurs observées sur l'ensemble de la période.


Courte distance seule (moins de 2000 km parcourus)


## 8.1.3. Double filtrage : volume et distance**

Pour appliquer un double filtrage, il suffit d'ajouter deux filtres différents sur les liens, puis de paramétrer chacun d'entre eux.

**Application sur la vue en cours **

-- Distance parcourue inférieure à 8000 km (moyenne à petite longue distance)
-- Volume total échangé supérieur à 47 millions (paramètre empirique, pris au hasard)

Distance inférieure à 8000 km
Volume supérieur à 47 millions



>> Commentaire : les échanges qui s'expriment à moyenne distance (moins de 8000 km environ) qui représentent plus de 48 millions de livres sterling échangés correspondent à 50% du total de ces interactions commerciales qui sont réalisées entre les 16% de noeuds les plus importants.

## 8.2. Filtrage temporel

Les données étant découpées dans le temps, il est possible de sélectionner une ou plusieurs dates à représenter. Les paramètres décrivant la part d'information représentée sont alors actualisés.

**Application sur la vue en cours**


-- Filtrage sur les noeuds, selon la weighted balance - changement de style


# 9. Export et sauvegarde

 Bouton permettant d'exporter une carte au format image (.PNG).

 Bouton permettant d'exporter la carte au format .ZIP.

Pour ouvrir une carte sauvegardée, il faut charger le fichier .ZIP de sauvegarde - et ne pas l'avoir modifié entre temps.

---

*arabesque* glossaire (english/french)
===

***arabesques* key terms and concepts**
in English and French
Définition des termes et notions clés de ***arabesque***, en anglais et en français

# A

**Aggregation function / Fonction d’agrégation** :
-- Attribute merge function (mean, minimum, maximum or median) of the links to be represented according to a variable, by default according to the sum function.
-- Fonction (moyenne, minimum, maximum ou médiane) de fusion attributaire des valeurs des liens à représenter selon une variable, par défaut selon la fonction somme.

# B

**Balance / Solde** :
-- Difference between the weights of the incoming (or outgoing) links per node
-- Différence marginale entre les poids du total des liens entrants (ou sortants)) par sommet.

**(Bilateral) balance / Volume bilatéral** :
-- difference between the weights of the links of a pair of nodes
-- différence entre les poids des liens d’un couple de sommets.

**Betweeness (centrality) / Centralité d'intermédiarité:**
-- Number of shortest paths passing through the nodes
-- Mesure du nombre de plus court chemins passant un sommet

# C

**Centroid (barycenter) / Barycentre :**
-- centre géométrique d’une unité spatiale surfacique qui servira le cas échéant, par défaut, de point d'origine ou de destination

# D

**Degree / degré :**
-- number of links pointant to the nodes
-- nombre de liens pointant vers le noeud

**(in/out) Degree / Degré (entrant/sortant) :**
-- number of links ingoing / outgoing to the nodes - for oriented networks
-- nombre de liens entrants (ou sortants) d'un noeud – pour les réseaux orientés

**Drawing / Dessiner :**
-- drawing resuling on the transformation of numerical values into graphic objects (point, linear or surface) possibly enriched by a graphic symbolization
-- dessin résultant de la transformation de valeurs numériques en objets graphiques (ponctuels, linéaires ou surfaciques) éventuellement enrichis par une symbolisation

# I

**ID (idenfiant) / ID** :
-- code identifiant d’une unité spatiale (nœud ou lien)

# L

**Layer / Couche :**
-- geographical layer
-- couche d'information géo numérique utile pour la représentation

**(base) Layer / Couche de base :**
-- couche d'information géo numérique servant de support à la représentation

**(custom) Layer / Couche d'habillage :**
-- couche d'information géo numérique servant de contextualisation (ou d'habillage) de la représentation

**Level / Niveau :**
-- échelon territorial correspondant au niveau découpage géographique (ex. niveau mondial), ou échelle géographique d’observation

**Link / Liens** :
-- liens (XiYi, Xj,Xj) mettant en relation un couple de nœuds.

# M

**Margin / Marge :**
-- Sum (or difference) calculated by rows line (or column) of the cells of an origin-destination matrix.
-- Somme (ou différence) calculée en ligne (ou en colonne) des cases d'une matrice origine-destination.

**Matrix / Matrice :**
-- cross tab...
-- tableau croisé décrivant la mise en relation de sommets.

# N

**Node / Nœuds (ou sommets):**
-- points (X,Y) correspondant à un lieu d’origine et/ou de destination

# P

**Projection (cartographic) / projection (cartographique) :**
-- System of geometrical transformations to represent the surface of a sphere on a plane. Used for cartographic representations.
-- Système de transformations géométriques permettant la représentation de la surface d'une sphère sur un plan, utilisé notamment en cartographie.

# S

**Symbolization / Symbolisation :**
-- Enrichment of the drawing of links and nodes, by the use of retinal variables (size, shape, colour and opacity, value, form and orientation).
-- Enrichissement du dessin des liens et des noeuds, par la mise en oeuvre de variables rétiniennes (taille, forme, couleur et opacité, valeur, forme et orientation).

**Skew symmetry / Asymétrie :**
-- rapport de la différence des liens entrants et sortants pondérés par le poids du sommet sur la somme des liens entrants et sortants pondérés par le poids du sommet

# T

**Tile (layer) / Tuile vectorielle (couche):**
-- Mosaic of geographical information (in vector or pixel mode) that can be used as the main background map.
-- Mosaïque d'information géographique (en mode vecteur ou pixel) pouvant servir de fond de carte principal.

# V

**Volume / Volume:**
-- Volume : somme marginale des poids des liens entrants et sortant d’un sommet.

**(Bilateral) volume / Volume bilatéral :**
-- sum of the weights of the links of a pair of nodes.
-- somme marginale des poids des liens d’un couple de noeuds.

# W

**Weight / Poids :**
-- valeur numérique non binaire affectée à un nœud ou à un lien.

**Weighted (degrees) / Degrés pondérés :**
-- Incoming (or outgoing) number of links per node adjusted by node weight.
-- Nombre de liens entrant (ou sortant) pondérés par le poids du sommet.

---

## arabesque ToDoList and FAQ

:::info
**Find this document incomplete?** Leave a comment!
:::

###### tags: `Templates` `Documentation` `tutorial` `arabesque` `gflowiz`