---
title: 'Arabesque documentation template'
disqus: hackmd
---

**Arabesque documentation template**

## Table of Contents

[TOC]

## ToDoList
-- Preparer un guide / tutoriel, commencer par un cas simple d'utilisation d'un exemple de données fourni
-- Glossaire
-- Documenter le code, faire une liste des fonctions, ...
-- Ouvrir l'application / laisser la possibilité d'ajouter des fonctionnalités supplémentaires
-- Dépôt du code source, d'abord en mode privé puis en mode public.
-- Page de présentation à réaliser en amont du lancement de l'application
> *Version de test* : http://vlsstats.ifsttar.fr/gflowiz/

---
Présentation générale
---

Le projet gflowiz (geographic flow visualisation) est un projet innovant visant à créer l'application *Arabesques*, en tenant compte des informations collectées grâce à un inventaire des applications existantes dans le domaine et d’une enquête réalisée auprès de professionnels pour collecter les besoins en termes d’application web.

Une attention particulière est apportée aux composantes géographiques (gestion des fonds de carte), statistiques (import et exploration des données) et cartographiques (dessin, symbolisation et sémiologie graphique) de cette première version de l’application. L'objectif étant d’obtenir à un ensemble homogène et cohérent avec la littérature actuelle et les potentialités technologiques du moment.

*Arabesques* offre ainsi plusieurs possibilités tant dans les données en entrées qu’elle permet de charger et manipuler (matrices simples ou complexes), que dans les possibilités d'exploration (filtrage, d’agrégation) et de représentation (dessin et symbologie).

### 1. Composantes de l'application

*Arabesques* est une application web dédiée à la géo visualisation de données de flux et de réseaux spatiaux.

Les principales composantes proposées sont :
-- le chargement de données numériques et géographiques (csv, geojson) ;
-- le géocodage de données ;
-- le calcul (automatique) d'indicateur de base ;
-- l'exploration de données numériques (liens, noeuds) ;
-- le filtrage de données (liens, noeuds) en fonction d'une variable (au choix) ou de la distance parcourue
-- l'agrégation de données (liens, noeuds) ;
-- le dessin symbolisant des liens et/ou noeuds ;
-- la représentation cartographique des symboles ;
-- la conception d'une carte thématique

### 2. Données

Des fonds géonumériques sont proposés à titre complémentaire, à des fins d’habillage.

**Couches fournies :**
-- OpenStreetMap
-- NaturalEarthData
-- Stamen
-- CartoDB
-- Geofla
-- etc.

**Géocodage :**
En cas d’absence d’informations géographiques associées à un jeu de données statistique, il est possible de géocoder un fichier .CSV, .JSON ou GEOJSON sous réserve que ce dernier comporte a minima un identifiant d’unités spatiales valide. À défaut de cela, les noeuds correspondants seront supprimés lors d’une vérification de l’intégrité du fichier.

Plusieurs possibilités de géocodage sont proposées pour différents niveaux territoriaux généraux, tels que les codes ISO3 et UNEP pour les pays, régions ou sous-régions du monde ; les identifiants du découpage européen NUTS 1,2,3 ; les codes postaux ou INSEE pour les différents découpages français ; les identifiants de territoires spéciaux, comme le Grand Paris, le *Greater London* notamment. (Les données sont en cours d'intégration, donc de nombreux géocodages sont manquants)

### 3. Filtrage

#### 3.1. Filtrage numérique
Le filtrage numérique s’applique aux données quantitatives de stock (absolues) ou de taux (relatives, continues ou pseudo-continues). 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.

#### 3.2. Filtrage temporel
Les possibilités de filtrage des matrices temporelles ne sont actuellement disponibles que pour les liens. Elles portent sur le choix d’une date ou d’une période, sous une forme numérique ou graphique (*slider*). Trois formats de date sont disponibles (chaîne, horaire, horodatage).

#### 3.3. Filtrage catégoriel
Le filtrage catégoriel s’applique aux données qualitatives disponibles dans les jeux de données de nœuds et/ou de liens.

Trois possibilités sont proposées graphiquement et numériquement :
– **Sélection de plusieurs modalités** : l’utilisateur choisit une ou plusieurs des modalités de variables qualitatives disponibles (par exemple, les préfectures et sous-préfectures s’il dispose d’une variable spécifiant le profil administratif des villes françaises) ou le type de liens (par exemple, import ou export pour des données d’échanges
commerciaux).
– **Sélection d’une modalité unique** : l’utilisateur choisit une seule modalité de variable (pour les nœuds : par exemple, les flux au départ et à destination de Clermont-Ferrand pour des données de mobilité ; les flux de type import pour des données commerciales).
– **Sélection par suppression d’une variable unique** : l’utilisateur choisit une ou plusieurs variables portant sur les nœuds et les liens à supprimer. Si la suppression sélection porte sur des nœuds, tous les liens correspondants (par exemple, la région Ile-de-France pour une analyse à l’échelle nationale) sont supprimés.

### 4. Transformations cartographiques

#### 4.1. (re)Projections cartographiques

Possibilités de changement de projection cartographiques

La Liste des projections disponibles est la suivante :

### 5. Agrégations / fusions cartographiques

Des fonctions d’agrégation attributaires, relatives à la gestion des hyper matrices ou graphes multiplexes, sont proposées pour réduire le nombre de figurés à représenter - ne pas représenter, par exemple, les n liens qui correspondent aux n dates disponibles.

Par défaut, c’est la fonction somme qui est appliquée au chargement des données, en l’absence de précision.
**--> Il faudrait expliquer ici clairement avec un exemple.**

L’utilisateur peut toutefois choisir d’appliquer une fonction moyenne, minimum, maximum ou médiane calculée sur l’ensemble des matrices ou des graphes fournis. Il est également possible de choisir une seule date ou bien d’agréger les données, selon une fonction donnée, sur une période ou pour des catégories.
Cette fonction est importante, car elle définit par défaut l’intensité des teintes et l’opacité des figurés correspondants (voir information géographique).

---
## Glossaire
---
Definition of 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*

Licence : CC-BY-SA.

### 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 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 : 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 : echelon territorial correspondant au niveau découpage géographique (ex. niveau mondial), ou échelle géographique d’observation*

### L :

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

## FAQ

> **CSV format file import**
-- The import of the .csv files is in Anglo-Saxon format, presenting the dot (.) as a decimal separator
-- L'import de tableaux en .csv est au format anglo-saxon, présentant le point (.), comme séparateur de décimales

> **Saving an Arabesque project / *Sauver un projet Arabesque***
-- The .ZIP archive allowing the saving of a project (map, graphics, and data) for later use in *Arabesque*, must not be modified or opened.
-- L'archive .ZIP permettant la sauvegarde d'un projet (carte, graphiques, et données) pour une utilisation ultérieure dans *Arabesque*, ne doit pas être modifié, ni ouvert.

> **Minimum conditions of use / *Conditions minimales d'utilisation* :**
-- The application only works if your computer is connected to the Internet. Similarly, the use of external vector tiles (OSM, etc.) is only possible if the corresponding server is in working order
-- L'application ne fonctionne que si votre ordinateur est connecté à Internet. De même que l'utilisation de tuile vectorielles externes (OSM, etc.) n'est possible que si le serveur correspondant est en état de marche

> **Web optimization / *Optimisation web* :**
-- *Arabesque* is configured to work correctly on *Firefox* and *Google Chrome*.
-- *Arabesque* est configurée pour fonctionner correctement sur *Firefox* et *Google Chrome*.**

## Beta-testeurs
**Qui ? :**
°demande envoyée, attente de réponse

-- ***Cartographie, conception :*** Olivier Pissoat ([e-mail]), Anne-Christine Bronner ([e-mail]), Nicolas Lambert ([e-mail])
-- ***Géomatique*** : Julie Pierson ([e-mail]) , Matthieu Rajerison ([e-mail]),
-- ***Statistiques*** :
-- ***Informatique*** : Christophe Hurter ([e-mail])
-- ***Enseignement, pédagogie*** : Matthieu Merlet ([e-mail]), Cyrille Chopin ([e-mail]), Antonine Ribardiere ([e-mail])
-- ***Thématique mobilités / migrations*** : Jean-François Valette ([e-mail]), Frédéric Piantoni ([e-mail]), Olivier Clochard ([e-mail])

**Questions :**

> **Import / export :**
-- Avez-vous pu charger vos propres données (liens et/ou nœuds) ?
-- Avez-vous pu exporter un résultat adapté à votre besoin ?
-- si non, que vous manque t-il ?

> **Prise en main :**
> -- Toutes les fonctionalités sont-elles facilement accesibles et compréhensibles?
-- Avez-vous rencontré des problèmes de prise en main de l'application ?
-- Si oui, quels sont-ils ?
-- Quelles sont les fonctionalités complémentaires dont vous pourriez avoir besoin ?

> **Fonctionnalités de dessin et cartographie :**
-- Les fonctionnalités de dessin et de conception d'ensemble (ajout d'éléments d'habillage, de couches contextuelle supplémentaires) vous paraissent-elles suffisantes ? Si non, qu'auriez-vous aimé trouver ?
-- Les fonctionnalités d'action sur la symbolisation des liens, des noeuds en fonction des données vous paraissent-elles suffisantes ? Si non, qu'auriez-vous aimé trouver ?

> **Fonctionnalités d'exploration :**
-- Les fonctionnalités d'exploration des données, en vue de leur filtrage vous conviennent-elles ? Si non, qu'auriez-vous aimé trouver ?

> **Documentation :**
-- Quels éléments vous semblent devoir être documentés en priorité ?

> **Ergonomie, fluidité, vitesse d'éxécution :**
-- Que pensez-vous de la vitesse d'utilisation ?
-- L'application est-elle plus rapide / moins rapide / suffisament rapide par rapport à ce à quoi vous auriez pu en attendre ?

> **Suggestions :**
-- Inscrivez ici ce que vous pensez devoir être ajouté, supprimé, modifié pour une version ultérieure

## Appendix and FAQ

:::info
**Find this document incomplete?** Leave us your comment!
:::

###### tags: `Templates` `Documentation`