<figure><img src="image_23.png" /><figcaption>FIGURE 6.3 – Visualisation de la disposition des folios dans une source primaire</figcaption></figure>

La visualisation ici sert à embrasser d'un seul regard des informations qui ne pourraient être obtenues ailleurs que par un examen attentif des sources primaires. Néanmoins, cette forme de représentation visuelle ne pourra être tout à fait significative qu'une fois que seront intégrés les autres types de contenus des sources astronomiques – diagrammes et textes – à la base de DISHAS ; il sera alors possible aux chercheurs de déceler certains motifs structurels susceptibles d'apporter un nouvel éclairage sur les sources.

### 6.2.2 Représenter un milieu intellectuel : le cas de la carte historique

Les visualisations ponctuelles, employées pour les pages de notices, ne représentent qu'un seul enregistrement de la base, sont utiles pour résumer graphiquement une donnée. Elles apportent un éclairage complémentaire aux seules métadonnées, mais ne peuvent remplacer une observation méthodique du matériel documentaire. La visualisation numérique accède à son véritable potentiel, lorsqu'elle agrège un grand nombre de données pour en dresser une synthèse visuelle. Plus les corpus représentés sont importants, plus ce genre de visualisation trouve son intérêt, donnant à voir ainsi des informations qu'il serait extrêmement ardu à obtenir autrement.

#### Représentation spatiale et chronologique

La mise en évidence de milieux intellectuels est un enjeu de recherche central pour le projet DISHAS. Le concept de milieu intellectuel peut être fondamentalement décrit par l'articulation d'un lieu et d'une époque ; leur représentation conjointe a souvent fait l'objet de réflexion, tant dans une perspective historique que pour des emplois plus éclectiques<fnref n="16" />.

<footnote n="16">16. GoogleMaps propose par exemple une fonctionnalité de * timeline permettant d'explorer les trajets réalisés avec l'application. ; par ailleurs, la bibliothèque de visualisation en carte * Leaflet propose huit plugins pour la création de « carte temporelle », généralement pour figurer des itinéraires.</footnote>
De nombreux historiens se sont attachés à proposer des solutions pour résumer au sein d'une même forme graphique le temps et l'espace : on peut citer des initiatives aussi diverses que le *Chronological Chart of Ancient, Modern and Biblical History* de Sebastian C. Adams publié en 1871 qui mêle histoire profane et religieuse sur une période de près de 5000 ans<fnref n="17" /> ou encore que l'encyclopédie et atlas digital *TimeMaps* qui propose une série de cartes thématiques sur différentes époques de l'humanité.

Si la carte et la frise chronologique sont des moyens d'expression privilégiés de l'étude en SHS, leur articulation pose plusieurs problèmes, notamment dans une perspective de synchronicité. Bien souvent, le problème a été éludé en proposant une juxtaposition de cartes, chacune représentant une période définie<fnref n="18" />, ou en figurant à l'aide de symboles visuels (flèches, zones colorées, etc.) des mouvements ou événements particuliers<fnref n="19" />. L'irruption des techniques numériques dans le champ de la cartographie a ouvert les possibilités de visualisations : en laissant l'utilisateur interagir avec les variables à représenter, il est possible de construire des cartes sur mesure<fnref n="20" /> <fnref n="21" />, mettant au jour des relations entre les données qui n'auraient pu être prévues avant la conception de la visualisation.

## Réalisation d'une carte temporelle

Afin de représenter la diffusion des textes et la circulation des paramètres astronomiques, l'idée de construire une visualisation combinant carte et frise chronologique s'est donc rapidement imposée. La visualisation en carte a en outre l'avantage d'harmoniser les différentes granularités de description de la donnée : les entrées de la table *Place* « Paris » et « Collège de Sorbonne » apparaîtront ainsi côte à côte, bien qu'ils constituent deux enregistrements tout à fait disjoints dans la base de données. Toutefois, d'autres interrogations surgissent en parallèle, en particulier liées à la représentation d'entités placées sur un même lieu.

<footnote n="17">17. « Adams' Synchronological Chart », dans *David Rumsey Historical Map Collection*, URL : https://www.davidrumsey.com/luna/servlet/detail/RUMSEY~8~1~226099~5505934:Composite--Adams--Synchronological- (visité le 28/08/2019)</footnote>

<footnote n="18">18. Comme la plateforme *GeaCron* créée en collaboration avec l'Université Rey Juan Carlos (« World History Maps & Timelines », dans *GeaCron*, URL : http://geacron.com/home-en/ (visité le 19/08/2019)) ou l'atlas *TimeMaps*</footnote>

<footnote n="19">19. À l'instar des nombreuses cartes du Musée national de l'histoire de l'immigration : « Cartes », dans *Musée National de l'histoire de l'immigration*, URL : http://www.histoire-immigration.fr/questions-contemporaines/cartes (visité le 19/08/2019).</footnote>

<footnote n="20">20. À propos d'un projet pionner en la matière, l'atlas élaboré par Éric Guichard en 1999 : « L'atlas [...] permet à l'utilisateur de choisir tant les variables qu'il souhaite voir projetées sur la carte, que d'influer sur le mode de discrétisation des données. Il devient alors possible de générer une multitude de cartes, adaptées aux besoins du lecteur ou du chercheur, ce qui revient à créer un outil dont les fonctions ne sont pas reproductibles par un atlas papier, qu'il serait de toute façon impossible de publier. » M.L. Massot, « Dessiner les acteurs en humanités numériques : la recherche en dialogue »...</footnote>

<footnote n="21">21. Les cartes interactives créées par Étienne Côme pour visualiser les flux liés aux transports en communs sont très éclairantes à ce sujet : Etienne Côme, *Portfolio / Étienne Côme*, URL : https://www.comeetie.fr/#portfolio (visité le 18/08/2019).</footnote>
L'ajout de la dimension temporelle soulève en outre des questionnements spécifiques : comment figurer le temps sur une carte ? Est-il préférable de pouvoir sélectionner une période ou une date ponctuelle ? Comment symboliser des objets – sources primaires, paramètres – n'étant pas directement (ou parfois même aucunement) liés à un lieu ? Par quels moyens peut-on représenter des données temporelles et spatiales parfois imprécises, sans induire l'utilisateur en erreur ? La visualisation qui a été élaborée tente de répondre au mieux à ces interrogations.

Cette visualisation en carte temporelle a été conçue pour être polyvalente et s'adap-
ter à la représentation de différentes variables. Pour l'instant, elle a été implémentée sur
la page de notice des original items et sur la page d'accueil de la navigation historique.
Il est prévu qu'elle puisse servir à la présentation des paramètres astronomiques. Nous
prendrons pour sa description la version de la page *Historical navigation*.

La visualisation se divise en deux parties fonctionnant de manière synchrone : une
carte géographique sur le dessus où figure l'ensemble des œuvres et des manuscrits de la
base de données; sur le dessous, une carte de chaleur représente l'ensemble de la période
couverte par les entités de la base. Une barre de sélection comportant deux curseurs sert
de lien entre les deux cartes. La saturation de la couleur sur le dessous symbolise les
périodes les plus prolifiques; le jaune correspondant aux créations d'œuvres, le rouge aux
copies/éditions de sources primaires. Les repères sur la carte représentent quant à eux
les lieux de création et copie/édition de ces mêmes entités. Le rouge et le jaune gardent
les mêmes références, tandis que l'orange indique un mélange entre œuvres et sources.
Le diamètre des points quant à lui signale un plus ou moins grand nombre d'entités à
représenter. L'utilisateur peut, au survol sur ces points et sur les bandes de la carte de
chaleur, voir le nombre d'œuvres et de sources primaires correspondant au composant
concerné.

La première remarque qui doit être faite concerne la visualisation des sources pri-
maires. En effet, la source primaire n'est pas spatialisée dans la base de données, seul
l'*original item* est associé à un lieu. Dans la mesure où il est plus logique d'accéder à la
table astronomique par le biais de son contenant, il a été choisi de ne représenter sur cette
page que des sources primaires, bien que ce ne soient en réalité que des *original item* qui
apparaissent sur la carte<fnref n="22" />. Cela signifie qu'une source primaire dispose potentiellement
de plusieurs points sur la carte, dans le cas où elle n'aurait pas été produite à un unique
endroit.

Étant donné que cette visualisation a été pensée comme un portail, chaque repère sur
la carte est cliquable de façon à faire apparaître au-dessous de la visualisation des liens vers
les entités concernées. Il est également prévu de rendre cliquables les différentes zones de la
carte de chaleur, permettant ainsi d'accéder à la donnée par le biais chronologique comme

<footnote n="22">22. Pour la visualisation des paramètres astronomiques, le même procédé pourra être repris de manière à faire apparaître sur une carte les sets de paramètres associés à des *original items*.</footnote>
<figure><img src="image_24.png" /><figcaption>FIGURE 6.4 – Carte temporelle de la page *Historical navigation*</figcaption></figure>

spatial. Cependant, certaines entités ne sont associées à aucun lieu dans la base, mais elles doivent tout de même être rendues accessibles. Pour pallier cette difficulté, tous les enregistrements ne disposant pas d'information géographique ont été artificiellement situés aux coordonnées 0,0; une annotation sur la carte précise qu'il s'agit d'une « *Unknown place* » pour éviter toute confusion.

Lorsque l'utilisateur effectue une sélection grâce aux curseurs mis à sa disposition, les données affichées sur la carte sont mises à jour : le diamètre, la couleur et les informations au survol des points évoluent 23 en même temps qu'un agrandissement est effectué sur la frise au-dessous. En revanche, le zoom sur la carte n'entraîne pas d'actualisation de la carte de chaleur pour des raisons d'impossibilités liées à la technologie utilisée pour la visualisation 24.

Cette visualisation illustre les possibilités permises par la visualisation numérique. En représentant simultanément l'ensemble des données de la base, les corrélations entre elles sont rendues manifestes, alors qu'elles restaient auparavant inaccessibles. Différents choix éditoriaux ont été faits pour la figuration des données ; ils conditionnent la manière dont sont appréhendées les informations. Il est en ce sens du rôle du concepteur de tâcher

<footnote n="23">23. Pour le détail du code permettant ces modalités d'affichage, voir en annexes G.1.2.</footnote>

<footnote n="24">24. La bibliothèque JavaScript *AmCharts* ne dispose pas de moyen d'accéder aux informations relatives à la portion de carte affichée à l'écran de l'utilisateur.</footnote>
<figure><img src="image_25.png" /><figcaption>FIGURE 6.5 – Sélection d'une période sur la carte temporelle</figcaption></figure>

de biaiser le moins possible les représentations, pour permettre aux chercheurs de tirer
un maximum de profit de ce genre de réalisations numériques.

Ainsi, la mission de la plateforme publique vis-à-vis des chercheurs de DISHAS
constiste en grande partie à réveler les interactions contenues dans la base de données, au
travers de visualisations analytiques, comme de fonctionnalités permettant de réunir des
ensembles cohérents dans le corpus numérisé, à l'instar des modalités de recherche et de
l'ouverture des métadonnées au sein des notices. Si le back office propose des interfaces
fonctionnelles pour la gestion des données, le front office doit offrir des interfaces propres
à manifester leurs correspondances et interconnexions au sein de la base, dans le but
d'accompagner au mieux le travail de recherche.
# Chapitre 7

## Exposition des données brutes :
assurer la réutilisation du corpus
numérique

Les deux précédents chapitres se sont attachés à décrire comment présenter et mettre en relation les données au sein du *front office*. Si ces formes de médiatisation sont nécessaires pour donner du sens au corpus numérique, elles le rendent également univoque. En effet, ces modes d'exposition constituent un accès indirect à la donnée ; l'élaboration d'une plateforme en ligne offre en cela une vision réductrice de la donnée. Les ressources numériques, une fois incorporées à un discours qui les décrit et intégrées à une interface graphique, sont rendues en grande partie inutilisables. Dans une perspective de conformité avec les principes *FAIR*, un effort de médiation doit être fourni pour rendre accessible la donnée brute, de manière à permettre la réexploitation du corpus numérisé.

### 7.1 Accessibilité des données brutes

La plateforme de DISHAS a l'ambition de servir de portail de partage de données dans l'objectif de favoriser la pratique de l'open data en histoire de l'astronomie. La mise à disposition du matériau numérique non transformé offre au public la possibilité de réutiliser les ressources scientifiques : cette exposition des données peut s'opérer à plusieurs niveaux.

#### 7.1.1 Modalités d'accès à la donnée

##### Entrepôts de données pérennes

En France, plusieurs infrastructures s'attachent à accompagner les chercheurs dans l'exposition et la pérennisation des données de recherche. Le CINES (Centre Informatique
National de l'Enseignement Supérieur), établissement public placé sous la tutelle du Ministère de la Recherche et de l'Innovation, s'est fixé depuis sa création en 1999, une mission d'archivage des documents électroniques produits par la communauté scientifique. L'archivage pérenne concerne non seulement la gestion de l'obsolescence des formats et des environnements logiciels, mais également l'assurance de l'accessibilité des ressources<fnref n="1" />. De toute évidence, les missions de conservation et de communication sont complémentaires et doivent être envisagées ensemble, l'une n'ayant pas de sens sans l'autre. Le CINES instiste en particulier sur l'importance de la description des contenus numériques à l'aide de métadonnées : en effet, sans métadonnée, la finalité d'un document peut être perdue, celui-ci devenant ainsi rapidement inexploitable.

La TGIR Huma-Num est le second acteur majeur pour la valorisation des données de recherche, elle travaille par ailleurs en collaboration avec le CINES. Afin d'assurer un accès persistant et operable aux ressources numériques, Huma-Num a mis en œuvre un système d'exposition des données intitulé Nakala. Nakala est une base de données triplestore<fnref n="2" /> où peuvent être entreposés les corpus de recherche ; le SPARQL endpoint de Nakala permet de récupérer ces données numérisées, chacune étant signalée grâce à un identifiant pérenne, assurant leur trouvabilité dans le temps. Le recours aux standards du Web de données (lié à l'utilisation d'un triplestore), reposant sur des technologies et méthodes standardisées, permet de faciliter à la fois la récupération des données, mais aussi leur réutilisation. En effet, de nombreuses formes de valorisations s'appuient sur le format RDF, notamment le moissonnage des métadonnées par des services spécialisés comme Isidore ou Gallica, ou encore la réalisation de visualisation de données<fnref n="3" />.

## Exposition de données courantes

Cependant, cette forme d'exposition des données brutes implique l'établissement d'un corpus défini, exploitable en l'état. La base de données de DISHAS est encore sujette à de nombreuses modifications et le travail de numérisation des sources est encore loin d'être achevé. Il est donc nécessaire de trouver des voies d'exposition de cette donnée « intermédiaire » ; avant la pérennisation définitive du corpus dans Nakala, l'interface publique de DISHAS doit servir de plateforme de diffusion pour les données en train d'être façonnées par les chercheurs. L'application Web du projet ne se substitue pas à Nakala, leurs missions sont complémentaires et les développements prévus pour DISHAS se doivent de ne pas entrer en concurrence avec les services proposés par Huma-Num.

<footnote n="1">1. « L'archivage numérique pérenne n'est pas non plus l'ultime étape du stockage des données avant l'oubli ou la perte définitive » *Le concept d'archivage numérique pérenne / CINES*, URL : https://www.cines.fr/archivage/un-concept-des-problematiques/le-concept-darchivage-numerique-perenne/ (visité le 19/08/2019)</footnote>

<footnote n="2">2. Un triplestore est une base de données graphe utilisée pour le stockage et la récupération des triplets RDF ; le langage de requêtage d'un triplestore est le langage SPARQL (*SPARQL Protocol and RDF Query Language*).</footnote>

<footnote n="3">3. NAKALA par Huma-Num...</footnote>
Dans le but de donner un accès direct aux données de recherche, différentes fonctionnalités ont été implantées : Malcolm Hamelin, stagiaire du projet d'avril à juillet 2019, a été chargé de mettre en place une API ainsi que le moteur de recherche ElasticSearch sur la base de données <fnref n="4" />. L'API permet aux utilisateurs et aux machines de communiquer directement avec la base de données de DISHAS ; par le biais d'une interface en ligne de commandes, il est possible de récupérer, de modifier ou d'ajouter des données dans la base <fnref n="5" />. L'API est à destination principale des chercheurs, leur permettant d'intégrer massivement des données en contournant l'interface graphique : en effet, l'utilisation de l'API requiert un *token* d'identification, défendant au grand public de rentrer n'importe quelle donnée dans la base.

ElasticSearch en revanche, fonctionne sur un duplicat de la base de données ; il n'est donc pas possible d'ajouter des données à la base relationnelle par le biais d'ElasticSearch. Son utilisation principale concerne la récupération des données de DISHAS et leur exposition à un public plus large que la seule équipe de recherche du projet. En effet, la base d'ElasticSearch peut être interrogée à la manière d'une API, de façon à ouvrir l'accès aux données brutes de DISHAS à des utilisateurs extérieurs comme à d'autres plateforme en ligne. Les données récupérées par le biais de l'API et d'ElasticSearch sont encodées en JSON, format largement employé, facilitant ainsi leur réutilisation.

<figure><img src="image_26.png" /><figcaption>FIGURE 7.1 – Interaction entre la base de données de DISHAS, l'API et ElasticSearch</figcaption></figure>

<footnote n="4">4. Pour davantage de détails concernant l'implémentation, voir section 9.2.</footnote>

<footnote n="5">5. Quatre actions peuvent être effectuées par l'API. Ce sont les opérations CRUD (Create Read Update Delete), correspondant aux différentes façons d'interagir avec une base de données : ajout, modification, suppression et lecture de données.</footnote>
7.1.2 Fonctionnalités implémentées dans l'interface publique

La plateforme publique de DISHAS n'intègre pour l'instant que peu d'accès à la don-
née brute : seuls deux endroits du front office exposent une partie des données nécessaires
à leur constitution.

La barre latérale présente sur les pages de notice, comporte plusieurs icônes à la dis-
position de l'utilisateur. L'un d'entre eux permet le téléchargement en JSON de l'ensemble
des métadonnées affichées. Toutefois, il s'agit d'un objet qui a été formaté pour répondre
aux besoins de mise en forme imposés par le template de la barre latérale, il serait donc
difficile à un utilisateur d'exploiter véritablement ce matériau. Il est prévu de réviser cette
fonctionnalité.

L'interface de recherche quant à elle, repose sur la base de données d'ElasticSearch ;
lorsque l'utilisateur soumet une recherche plein-texte, une requête est expédiée au serveur
d'ElasticSearch 6. Les informations renvoyées par le serveur sont ensuite disposées dans
un tableau de résultats pour une présentation graphique satisfaisante ; cependant, un
bouton sous la barre de recherche propose à l'utilisateur de copier la requête envoyée
à ElasticSearch dans son presse-papier. En collant cette requête dans la barre d'adresse
d'un navigateur, la réponse en format JSON telle que renvoyée par le serveur est rendue
disponible.

Ces fonctionnalités restent relativement rudimentaires et peu documentées. De fu-
turs développements du front office devront s'attacher à rendre les données de recherche
davantage accessibles ; néanmoins, ce travail se concentra principalement sur la documen-
tation des outils déjà existants. En effet, il existe d'ores et déjà des interfaces tout à fait
fonctionnelles pour le requêtage de données, l'enjeu est avant tout d'expliquer au public
comment utiliser ces outils. Ainsi, il est possible d'imaginer que des tutoriels pour l'utili-
sation d'ElasticSearch puissent être intégrés aux pages publiques, sous forme de ressource
à télécharger ou de contenu à part entière. La question des exports des données devra éga-
lement être réfléchie plus avant, notamment vis-à-vis du choix des informations à extraire
et de leurs modélisation à l'intérieur d'une chaîne JSON.

7.2 Exposer les méthodes : documentation et main-
tien de code

La seule mise à disposition des données au public ne suffit pas à favoriser leur
réutilisation. En effet, les corpus numériques, isolés de leur contexte de production, sont
dénués de signification propre : pour promouvoir leur usage, il est important que les
concepteurs de la donnée et des outils qui l'accompagnent, fournissent des documents

<footnote n="6">6. Pour plus de précision sur les méthodes de requêtes asynchrones à ElasticSearch, voir section 9.2.2.</footnote>
explicitant leurs pratiques. Ce contenu est destiné aux utilisateurs extérieurs au projet, mais plus encore aux futurs et actuels développeurs de l'application de DISHAS. En outre, cette documentation doit s'appuyer sur du code de qualité, de manière à ne pas nécessiter de modifications majeures lors de la reprise du projet par une nouvelle équipe d'ingénieurs.

Les développements réalisés au cours de mon stage s'efforcent de respecter les bonnes pratiques énoncées ci-après, de multiples ajustements seront toutefois probablement nécessaires en vue de leur mise en production.

## 7.2.1 Lisibilité et documentation

### Intelligibilité du code

Une des premières exigences des développements pour la constitution d'applications solides et réutilisables concerne la lisibilité du code. L'indentation, la suppression des redondances ou l'utilisation de sucre syntaxique<fnref n="7" /> sont autant de moyens de rendre la lecture du code plus aisée. Pour le développement des interfaces de DISHAS, plusieurs relectures du code ont permis d'en alléger la structure et de retirer des pans entiers de procédures inutiles. Des noms de variables signifiants ont été choisis de manière attentive, dans le but de participer à l'intelligibilité du code. L'emploi de la bibliothèque jQuery enfin, disposant d'une syntaxe plus compréhensible que le JavaScript simple<fnref n="8" />, a en outre aidé à la clarté des développements, grâce aux nombreux raccourcis et méthodes intégrés à la bibliothèque.

```javascript
1 /* VANILLA JAVASCRIPT */
2 if (document.getElementById(" sidebar ").getAttribute("isOpen") === "false") {
3   document.getElementById(" toolbar "). classList.add("open toolbar");
4 }
```

```javascript
1 /* JQUERY */
2 if ($("# sidebar ").attr("isOpen") === "false") {
3   $("# toolbar ").addClass("open toolbar");
4 }
```

<caption>FIGURE 7.2 – Différence de syntaxe entre Javascript simple et jQuery</caption>

### Exhaustivité de la documentation

La documentation des développements est d'une importance capitale pour leur maintenance et leurs réemplois ultérieurs. Le code, par-delà la question de la lisibilité, requiert d'être explicité pour être rendu véritablement accessible, et par là même, réutilisable.

<footnote n="7">7. Méthode de clarification de la syntaxe programmatique à l'aide de raccourcis et tournures de code allégées.</footnote>

<footnote n="8">8. Aussi appelé JavaScript *vanilla*.</footnote>
La documentation doit s'insérer à différents niveaux du développement pour assurer des explications tant du point de vue de l'architecture globale de l'application, que des plus petits composants de la syntaxe programmatique.

```javascript
1 /* EXEMPLE D'EXPLICITATION DU CODE */
2 if ($("# sidebar").attr("isOpen") === "false") {
3 // Si la valeur de l'attribut "isOpen" de l'élément HTML avec pour identifiant " sidebar" est
4 // égale à "false"
5 $("# toolbar").addClass("open toolbar");
6 // alors ajouter la classe "open toolbar" à l'élément HTML avec pour identifiant " toolbar"
7 }
```

<caption>FIGURE 7.3 – Exemple de commentaires de code intralinéaires</caption>

Au cours de la conception du front office, des commentaires intralinéaires ont été ajoutés pour expliciter les passages les plus ardus du code. Chacune des fonctions élaborées a été en outre documentée : leur utilité, les arguments nécessaires à leur exécution et leur fonctionnement ont systématiquement été notifiés. Afin de garder des traces des différentes réalisations, chaque *commit*<fnref n="9" /> a été associé à un message détaillant précisément les modifications et ajouts effectués sur le code. Enfin, des notes plus extensives ont été rédigées à l'achèvement du travail, exposant avec précision la nature des développements et les instructions pour les reproduire au besoin<fnref n="10" />.

## 7.2.2 Gestion de bugs

Pour assurer une expérience positive liée à l'utilisation de la plateforme, les erreurs d'exécution du code doivent être évitées au maximum. Le chargement correct et rapide des pages, le bon fonctionnement des composants de l'interface ou encore le comportement approprié des différents modules sont des facteurs influençant non seulement l'expérience utilisateur, mais également l'exposition générale des données du projet. L'efficacité des interfaces est la conséquence directe de l'anticipation et la correction d'erreurs informa- tiques. Le maintien régulier du code est souvent un argument retenu par les développeurs pour attester de la stabilité d'un projet; la gestion des bugs doit donc faire partie inté- grante du processus de développement.

### Prévenir les erreurs

Plusieurs méthodes peuvent être mises en place pour anticiper la survenue d'erreurs. En premier lieu, l'utilisation de bibliothèques et d'infrastructures logicielles<fnref n="11" /> éprouvées

<footnote n="9">9. Sauvegarde d'un état d'avancement du travail.</footnote>

<footnote n="10">10. Ces documents sont reproduits aux annexes F, G et H.</footnote>

<footnote n="11">11. Aussi appelés *frameworks*. Un *framework* est un ensemble cohérent de composants logiciels servant de cadre à la conception d'une partie ou de la totalité d'une application.</footnote>
simplifie le travail de correction tout en assurant un environnement stable pour l'implé-
mentation de nouvelles fonctionnalités<fnref n="12" />. Elles garantissent que les différentes briques
logicielles constituant l'application bénéficient de mises à jour régulières, ou *a minima*
d'un support de la communauté de programmeurs utilisant le même outil.

Les modèles – ou *template* – aident également à la maintenabilité du code. Les modèles permettent d'appliquer des traitements similaires à un ensemble de pages partageant des structures communes. Contenant dans un seul fichier l'ensemble des propriétés de multiples interfaces, ils en assurent la cohérence mais facilitent également leurs modifications. De manière générale, la mutualisation du code allège le travail de développement et fournit un environnement de travail plus stable. La réunion de morceaux de code coherents au sein de fonctions enfin, simplifie leur réutilisation et participe à construire une application plus robuste. Tous ces éléments façonnent une logique globale pour la plateforme, qui prévient un maximum de dysfonctionnements programmatiques.

## Recettes fonctionnelles

La conduite de tests est également essentielle à la construction d'une application. Différentes méthodes permettent d'éprouver le fonctionnement du code : l'intégration continue, par exemple, consiste en la conduction de tests à chaque nouvelle version du code, de manière à repérer et corriger immédiatement les éventuelles régressions ou erreurs. Cette approche vise à réduire les problèmes d'intégration. Les tests unitaires quant à eux, permettent d'évaluer le bon fonctionnement d'une partie précise du code. Il est préconisé de les rédiger simultanément au code, de manière à les faire correspondre parfaitement et d'éviter ainsi la propagation d'erreur.

La mise en œuvre de telles procédures requiert de nombreuses heures de développement, et l'équipe technique chargée du projet DISHAS ne compte, à l'heure actuelle, que deux membres ; le déploiement systématique de tests n'a donc pas pu être encore intégré au processus de travail des ingénieurs. De manière à assurer la viabilité de l'application, l'équipe technique a en revanche recours aux recettes fonctionnelles. Les recettes fonctionnelles consistent à évaluer la conformité du produit fini avec le cahier des charges initial. Un ensemble de points est identifié ; une série de tests est définie pour chacun de ces points, afin de vérifier l'adéquation de leurs fonctionnements avec les spécifications originales. Par exemple, pour chaque contenu texte des interfaces, il sera testé si l'utilisation de caractères spéciaux ou d'alphabets étrangers ne corrompt pas l'affichage. Toutefois, ces vérifications ne sont pas encore automatisées et leur déploiement nécessite d'être optimisé dans le futur.

<footnote n="12">12. « As it has already been invented, and is not considered to have any operational flaws, an attempt to reinvent it would be pointless and add no value to the object, and would be a waste of time, diverting the investigator's resources from possibly more worthy goals. » « Reinventing the Wheel », dans *Wikipedia*, URL : https://en.wikipedia.org/wiki/Reinventing-the-wheel* (visité le 10/08/2019)</footnote>
L'exposition des données brutes et des méthodes permettant leur utilisation influe
sur la diffusion des sources scientifiques du projet. La description technique du corpus
numérique doit être mise en avant au sein de la plateforme publique, mais également à
l'intérieur même du code sur lequel elle s'appuie, sous la forme de documentation rigou-
reuse. Si le public susceptible d'être intéressé par cet aspect de la donnée ne constitue
qu'une part minoritaire des utilisateurs, l'importance de la communication sur les res-
sources numériques et sur leurs outils est capitale. En effet, cette forme de médiation
assure aux données de recherche un cycle de vie dépassant le simple cadre de DISHAS, en
préservant leur caractère polyvalent. La médiation des données brutes représente égale-
ment une valorisation du travail des ingénieurs et des chercheurs ; l'exposition du processus
d'élaboration de ces ressources participent à faire fructifier les réalisations numériques du
projet.
Troisième partie

Traitement technique de la donnée
et management des interactions
<figure><img src="image_27.png" /></figure>
# Chapitre 8

## Gestion de projet

### 8.1 Dialogue entre recherche et ingénierie

Le développement du projet DISHAS s'inscrit à de nombreux égards dans la pratique des humanités numériques ; son aboutissement est le fruit que d'un partenariat étroit entre équipe de recherche et équipe technique. De nombreux enjeux peuvent être soulevés par une telle collaboration : afin d'assurer le déroulement optimal des réalisations du projet, il est intéressant de comprendre quelles problématiques peuvent émerger du dialogue entre ingénieur et chercheur.

#### 8.1.1 Coopération dans le domaine des humanités numériques

La place des humanités numériques au sein de la communauté de recherche en sciences humaines a souvent été l'objet de débat. Le caractère protéiforme de leur pratique et la multiplicité de leurs applications rendent leur définition malaisée : cette difficulté à circonscrire les humanités numériques a parfois été l'origine d'incompréhension parmi les acteurs des SHS. Incompréhension notamment vis-à-vis du rôle des ingénieurs numériques au sein des projets de recherche : tantôt perçus comme des simples exécutants<fnref n="1" />, tantôt considérés comme ayant la solution à tout problème, le positionnement des ingénieurs

<footnote n="1">1. « La contribution des techniciens est rarement analysée en tant que telle (du point de vue d'une sociologie du travail scientifique), mais presque toujours en fonction de leur contribution aux processus de production des connaissances scientifiques (du point de vue d'une sociologie de la connaissance) » Florence Millerand, « La science en réseau », *Revue d'anthropologie des connaissances*, Vol. 6, n° 1-1 (25 avr. 2012), p. 163-190, URL : https://www.cairn.info/revue-anthropologie-des-connaissances-2012-1-page-163.htm (visité le 04/08/2019), p. 163</footnote>
peut ainsi être difficile à définir<fnref n="2" />. Ces facteurs tendent à rendre complexe l'établissement d'un dialogue fécond entre chercheur et « technicien »<fnref n="3" />.

Plutôt que de renforcer la dichotomie entre recherche et numérique, la mise en common des savoirs peut être le point de départ d'un enrichissement mutuel. D'une part, les chercheurs, en s'appropriant les techniques numériques, ouvrent l'horizon de leurs travaux scientifiques ; d'autre part, les ingénieurs élargissent le champ de leurs réalisations par l'ouverture aux sciences humaines. Une distinction étanche entre les domaines d'expertise nuit à l'émergence de profils mixtes, susceptibles de surmonter le cloisonnement disciplinaire et d'être vecteurs d'innovation.

L'ingénieur en humanités numériques, par son interdisciplinarité, est ainsi au centre du processus de recherche ; il doit à la fois comprendre les enjeux scientifiques, en même temps qu'évaluer les contraintes techniques. Les réalisations qu'il met en œuvre doivent, dans cette mesure, être le fruit d'une collaboration étroite avec le chercheur, qui doit appréhender de son côté les enjeux techniques sous-jacents<fnref n="4" />. Cette coopération permet de prévenir des choix techniques dommageables – lorsque les enjeux scientifiques ne sont pas bien explicités ou compris – comme d'éviter l'élaboration d'instruments qui finissent inutilisés – lorsque les chercheurs ne s'approprient pas les outils.

> Si le chercheur ou l'enseigneur-chercheur ont la responsabilité d'impulser et de porter des axes de recherche novateurs, en véritables initiateurs du dialogue entre discipline et technique, l'ingénieur est le dialogue en acte. En véritable traducteur, il transmet des techniques, des méthodes, mais aussi conçoit et expérimente de nouveaux outils et guide le chercheur dans ses découvertes. Il est à l'interface entre les humanités, l'informatique et le design, en dialogue constant entre disciplines et techniques. Il sert de pont entre l'idée du chercheur et l'innovation technique, la recherche et son application, son incarnation concrète.<fnref n="5" />

Le rôle de l'ingénieur numérique n'est donc pas tant celui d'un intermédiaire – mettant en œuvre des moyens pour répondre à une demande – que d'un médiateur, accom-

<footnote n="2">2. « In these digital times, IT tools are no longer an auxiliary science to history. Integrating them into the “established procedures” has got to be the major challenge facing the discipline in the coming years. » F. Heimburger et Émilien Ruiz, « Has the Historian’s Craft Gone Digital? Some Observations from France », *Diacronie. Studi di Storia Contemporanea* (, 10[ 2012), URL : http://journals.openedition.org/diacronie/2795 (visité le 04/08/2019), § 40</footnote>

<footnote n="3">3. « Le paysage universitaire français a en effet pour particularité d'être structuré sur une séparation radicale entre recherche d'un côté, et services de l'autre. Cette dichotomie se retrouve au niveau des individus avec un cloisonnement étanche entre différents corps de la fonction publique, et au niveau des structures avec l'opposition bien connue entre unités de recherche et unités de service. » M. Dacos et P. Mounier, *État des lieux et positionnement de la recherche française dans le contexte international...*, p. 44</footnote>

<footnote n="4">4. « En résumant ces différents éléments, on peut suggérer que l'enjeu pour les spécialistes en informatique est de parvenir à faire voir les limites qu'ils fixent aux possibilités d'action de l'équipe comme indépendantes de leurs propres capacités. » Pierre-Nicolas Oberhauser, « Des collaborations équivoques », *Revue d'anthropologie des connaissances*, Vol. 10, n° 4-4 (23 déc. 2016), p. 557-586, URL : https://www.cairn.info/revue-anthropologie-des-connaissances-2016-4-page-557.htm (visité le 04/08/2019), § 21</footnote>

<footnote n="5">5. M.L. Massot, « Dessiner les acteurs en humanités numériques : la recherche en dialogue »..., p. 3</footnote>
pagnant les pratiques scientifiques dans leurs mutations liées à l'apport des technologies numériques<fnref n="6" />. Dans cette perspective, l'ingénieur se doit de ne pas être un simple exécitant, mais aussi un acteur décisionnel, afin d'aider à définir quels développements seront les plus adaptés au travail du chercheur.

## 8.1.2 Processus de conception des interfaces

La conception des interfaces publiques de la plateforme de DISHAS est le fruit de nombreux allers-retours entre exigences scientifiques et contraintes techniques. À la suite d'un examen approfondi de la base de données et de nombreuses discussions à propos du corpus de recherche, une première ébauche des pages du front office a pu être dressée. Aucun cahier des charges préalable n'a orienté ou déterminé le choix des réalisations; au contraire, c'est l'appropriation progressive des enjeux scientifiques sous-tendant au projet, qui a présidé à l'élaboration de la plateforme publique. L'évolution graduelle des développements s'est ensuite opérée au travers de deux phases complémentaires, répétées de manière itérative : une phase projective de description détaillée des interfaces à réaliser, et une phase démonstrative de confrontation des interfaces (concrétisées ou anticipées) avec les membres de l'équipe pour ajuster les développements.

Les procédés exposés ci-après sont employés au sein de l'équipe de DISHAS dans le processus de production numérique. Ces méthodes visent à favoriser la communication entre les chercheurs et les ingénieurs pour qu'en émanent des interactions fructueuses. Elles ont été implantées au fur et à mesure de l'avancée du projet, dans le but d'éviter de cloisonner le travail des membres de chaque équipe. Les paragraphes suivants constituent un retour d'expérience concernant l'élaboration de l'interface publique.

### Séminaires numériques

Chaque mois est organisé au sein de l'Observatoire un séminaire d'équipe orienté DH (Digital Humanities) : ce séminaire est alternativement animé par les membres du pôle numérique de DISHAS et par des intervenants extérieurs. L'objet de ces séminaires varie, il s'agit autant d'exposer l'avancement de travaux de l'équipe d'ingénierie, que de présenter des instruments informatiques intéressants. À titre d'exemple, les quatre derniers séminaires ont porté sur : l'assistant bibliographique Zotero, les interfaces du front office<fnref n="7" />, les différentes applications de l'édition avec XML TEI et l'implémentation des outils d'ElasticSearch. Ces séminaires sont l'occasion de faire se rencontrer les chercheurs

<footnote n="6">6. « Loin d'être un simple développement technologique ayant un impact sur le processus de recherche et de visualisation des données en sciences humaines et sociales, les humanités numériques nous amènent à repenser le sens même de la recherche et, par conséquent, l'ensemble du modèle de production et de circulation du savoir à l'époque de l'édition numérique. » M. E. Sinatra et M. Vitali-Rosati, « Histoire des Humanités numériques »..., § 3</footnote>

<footnote n="7">7. Le document de présentation utilisé lors du séminaire est reproduit en annexe D.</footnote>
et les ingénieurs pour échanger à propos des réalisations numériques, mais aussi pour
accompagner une première prise en main de ces outils<fnref n="8" />.

L'ingénieur doit tâcher de concentrer la discussion sur les points qu'il estime être les plus pertinents. Certains aspects trop techniques peuvent ainsi être éludés, tandis que les points concernant la représentation de l'information peuvent être davantage développés. Ainsi, les échanges lors de la présentation du *front office* se sont notamment orientés sur le raffinement des visualisations de données : les suggestions de chacun ont été évaluées et débattues, tant du point de vue de leur faisabilité que de leur intérêt, aboutissant à l'élaboration d'interfaces plus riches. Certaines propositions vis-à-vis de l'architecture de l'information dans le parcours de navigation ont par ailleurs été entièrement repensées, donnant lieu par exemple à la fusion des pages concernant les éditions et de celles relatives aux modèles mathématiques. Il a été évoqué enfin, la part active que doivent prendre les chercheurs dans la conception de la plateforme publique, en particulier dans la rédaction de textes introductifs pour les différentes pages de la navigation<fnref n="9" />.

Spécifications fonctionnelles

L'établissement d'un document détaillant l'ensemble des développements planifiés a constitué une seconde phase dans le travail d'élaboration du *front office*. La définition écrite des réalisations prévues vise plusieurs objectifs. En premier lieu, l'évaluation globale des moyens à mettre en œuvre pour leur concrétisation, mais aussi la constitution d'un document maître auquel se référer. Ce document<fnref n="10" /> est un cahier des charges fonctionnel où est décrite en détail chaque page de la plateforme publique. Il se présente sous forme de tableau où chaque rangée correspond à une page de l'interface, chaque colonne concernant quant à elle un aspect précis de cette page :

— une première colonne présente l'interface de manière générale : son objectif, son architecture globale avec la description de ses différents composants ainsi qu'éventuellement des interrogations vis-à-vis de sa conception;

— une deuxième colonne expose l'ensemble des données qui seront récupérées de la base pour l'affichage, en particulier pour les métadonnées requises dans les pages de notices;

<footnote n="8">8. « La conclusion à en tirer est que les chercheurs doivent d'abord connaître les logiciels développés pour eux, pas nécessairement qu'ils sachent programmer. Des logiciels puissants existent, il n'est pas toujours nécessaire de réinventer la roue. L'ignorance informatique des historiens doit être évitée, mais il est nécessaire de disposer d'une bonne culture informatique, autorisant un bon apprentissage des logiciels. » F. Clavert, F. Heimburger et A. Berra, « L'historien programmeur ? »..., § 21</footnote>

<footnote n="9">9. « Nous abordons la question de la planification des tâches à accomplir et des objectifs à atteindre dans le cadre du projet, en montrant comment les efforts de coordination déployés par les chercheurs s'appuient de manière décisive sur les informations transmises par les spécialistes en informatique. » P.N. Oberhauser, « Des collaborations équivoques »..., § 5</footnote>

<footnote n="10">10. Ce document, réalisé durant le premier mois de mon stage, a été reproduit en annexe E.</footnote>
— une troisième colonne s'attache à expliciter précisément la visualisation de donnée apparaissant sur la page (si tel est le cas), tant dans son aspect visuel que dans ses enjeux intellectuels;

— une quatrième colonne concerne les données nécessaires à la constitution de cette visualisation;

— une cinquième colonne dresse la liste de tous les liens de redirection présents à l'intérieur de la page, composant ainsi le réseau dans lequel elle s'inscrit;

— une dernière colonne détaille les corpus de données qui pourront être établit à partir de cette page. Cette partie concerne essentiellement les pages de notice, et fait référence aux « loupes » disposées sur la barre latérale de métadonnées<fnref n="11" />.

Ce document, en plus d'aider au cours du développement de la plateforme, fournit un support pour les remarques potentielles des chercheurs; il doit donc s'efforcer de viser l'exhaustivité des descriptions, énoncées dans un style le plus limpide possible. Il constitue ainsi un socle commun sur lequel peut s'appuyer le dialogue entre utilisateurs et concepteurs. En s'assurant en amont que le projet numérique est en adéquation avec les attentes de l'équipe de recherche, il est possible mettre de côté les réalisations inutiles et d'identifier celles auxquelles il faut accorder la priorité.

Le cahier des charges fonctionnel, ainsi que les différentes étapes d'avancement des interfaces ont pu être présentés et discutés lors de rencontres DH plus informelles entre le chef du projet de recherche, Matthieu Husson, et la cheffe de projet numérique, Galla Topalian. Ces réunions, organisées hebdomadairement, permettent d'ajuster les demandes des chercheurs par rapport aux contraintes techniques; si la conception de l'interface d'édition de table revêtait par exemple d'une utilité immédiate plus importante, il a été décidé de se concentrer dans un premier temps sur les pages de « navigation historique » car la réalisation de visualisation de tables exigeait des compétences techniques plus ap-profondies<fnref n="12" />.

## 8.2 Organisation du travail intra-équipe

### 8.2.1 Instruments de gestion du travail

Au cours des mois d'avril à août 2019, l'équipe technique du projet DISHAS a compté quatre membres chargés du développement de différentes parties de la plateforme en ligne. Galla Topalian, cheffe du pôle numérique, accompagne le projet depuis trois ans : elle a conçu la part la plus importante de la plateforme, en particulier l'ensemble des interfaces du back office pour l'insertion de données. Antonin Penon s'est occupé de la réalisation

<footnote n="11">11. Leur fonctonnement est décrit plus en détail à la section 6.1.1.</footnote>

<footnote n="12">12. En particulier par rapport à la complexité de l'encodage des tables astronomiques dans la base de données.</footnote>
de DTI, outil dédié à la saisie de table, qui a été intégré aux pages administrateur. Mal-
colm Hamelin s'est quant à lui consacré à la création d'une API et à l'implémentation
d'ElasticSearch sur la base de données de DISHAS. Enfin, le développement des interfaces
du front office a constitué l'essentiel de mon travail.

Gestionnaire de versions

Afin de superviser l'avancement de ces différentes tâches, plusieurs logiciels sont uti-
lisés au sein de l'équipe. En premier lieu, l'outil de versionning Git, qui est indispensable
à tout travail de développement informatique à plusieurs. Les gestionnaires de versions
comme Git permettent de sauvegarder différents états d'avancement d'un dossier, de ma-
nière à pouvoir rappeler la version antérieure d'un fichier en cas de problème. Git assiste
également dans le travail en groupe grâce à la création de « branches ». Une branche est
un état parallèle du dossier de travail; chaque collaborateur peut ainsi effectuer des mo-
difications sur sa propre version du dossier, sans entrer en concurrence avec le travail des
autres. Git prend ensuite en charge la fusion, lorsqu'il faut intégrer les développements
d'une branche à la version-maître de l'application (branche master). Une description de
la branche dédiée aux interfaces du front office est disponible en annexe G.

Git fonctionne de manière complémentaire avec les services Web que sont GitHub et GitLab : ils permettent d'héberger en ligne les dossiers gérés à l'aide de Git, tout en proposant de multiples fonctionnalités additionnelles destinées à la collaboration, comme le suivi de bugs, la gestion des tâches ou encore la création de Wiki <fnref n="13" />. Le système des tickets permet par exemple de consigner les suggestions, comme de notifier la survenue d'erreurs ou encore de soulever des interrogations relatives à un point particulier du développement. Ces tickets peuvent ensuite être assignés à un membre du projet ; ainsi, lorsque des questionnements sont intervenus lors de l'élaboration des visualisations de données, un ticket a pu être créé afin d'en rapporter le contenu à Matthieu Husson à l'occasion d'une réunion DH.

Le Wiki du projet a aussi été largement utilisé, principalement dans un objectif de
documentation. Y sont consignées à la fois les instructions pour l'installation de l'appli-
cation DISHAS sur un serveur, mais aussi la description de l'arborescence des dossiers ou
encore l'explication du fonctionnement des différentes réalisations numériques. Ces docu-
ments visent à faciliter la reprise des développements de DISHAS par une autre équipe
d'ingénieurs, issue d'un projet de recherche partenaire.

Supervision du travail

D'autres outils plus spécifiquement dédiés au management de projet sont utilisés
par les membres de l'équipe technique. L'instrument de gestion de projet en ligne Trello

<footnote n="13">13. Application Web collaborative dont le contenu est rédigé et modifié par les internautes autorisés.</footnote>
est par exemple employé pour visualiser de manière synthétique l'avancement du travail.
Chaque tâche y est identifiée par une « carte » et catégorisée selon son état d'avancement.
L'ensemble des cartes des membres de l'équipe sont figurées concomitamment, permettant
de suivre simultanément la progression des différentes réalisations. Cet outil est également
utile pour lister au fur et à mesure les éléments nécessaires à la collaboration entre deux
ingénieurs ; cela a particulièrement été utile lors de la prise en main des fonctionnalités
d'ElasticSearch pour leur utilisation dans le front office. Trello a alors permis par exemple
d'aider à formaliser des requêtes dans le langage spécifique d'ElasticSearch.

Ces instruments participent à optimiser le travail des ingénieurs numériques en éta-
blissant de bonnes pratiques dans le processus de réalisation<fnref n="14" />. La gestion efficace de
chaque étape de développement est capitale pour mener à bien un projet numérique
ayant vocation à être pérenne. L'utilisation d'outil de management de projet permet de
garder un historique de la progression des développements, simplifiant les échanges entre
les collaborateurs et contribuant à l'établissement de méthodes durables.

8.2.2 Méthodes de développement

Le développement des interfaces publiques s'est fait au travers de phases de travail
individuel, comme de phases de programmation en binôme. La programmation en binôme
– aussi appelé *peer coding* – et la revue de code à plusieurs a permis d'améliorer sensiblement la qualité du code. Cette pratique a donné l'occasion à la cheffe de projet numérique de suivre les développements effectués au fur et à mesure des mois de stage, donnant ainsi la possibilité de proposer des optimisations, ainsi que de suggérer des solutions déjà implémentées dans l'application. Par exemple, pour la génération de tableaux de résultats sur la page de recherche, le recours à une classe PHP déjà utilisée dans certaines pages de la plateforme a largement participé à accroître la robustesse des développements <fnref n="15" />.

La revue du travail en binôme donne également l'opportunité d'expliquer la dé-
marche logique sous-jacente à un morceau de code, de manière à en révéler les incohé-
rences et les maladresses. Le fait d'explicitier le processus programmatique à voix haute
permet souvent d'y déceler des redondances et ainsi d'éliminer les passages inutiles. En
outre, cette pratique comporte une forte dimension pédagogique : en identifiant des so-
lutions pour pallier à certaines faiblesses, il est possible d'améliorer très efficacement la
qualité de son code. Cette forme de coopération rend possible de conserver une cohérence
dans les développements applicatifs tout en renforçant fiabilité de l'application.

<footnote n="14">14. « Mailing lists, collaborative writing tools, blogs and wikis are only a small number of the tools which make collaborative work easier. They encourage methodological exchange and collective procedures. »
F. Heimburger et É. Ruiz, « Has the Historian's Craft Gone Digital?... », § 32</footnote>

<footnote n="15">15. Pour le détail de l'utilisation de cette classe, voir en annexe G.3.1.</footnote>
<figure><img src="image_28.png" /></figure>
# Chapitre 9

## Environnement technique

### 9.1 Architecture de l'application Web

#### 9.1.1 Modèle-Vue-Contrôleur

À l'instar de nombreuses applications Web, la plateforme en ligne de DISHAS est structurée selon le schéma MVC (Model-View-Controller). Ce motif d'architecture logicielle se divise en trois types de modules gérant différentes parties de l'application. Pour synthétiser les interactions entre ces trois composants de manière schématique ; le modèle s'occupe de traiter la donnée de la base, le contrôleur manipule cette donnée et la renvoie à la vue, vue qui la met ensuite en forme visuellement dans un *template*.

<figure><img src="image_29.png" /><figcaption>FIGURE 9.1 – Fonctionnement simplifié de l'architecture logicielle MVC</figcaption></figure>
## Présentation du *framework*.phpony

L'application Web de DISHAS a été élaborée grâce au *framework* MVC.phpony, dans sa version 3.4..phpony est une infrastructure logicielle pour la création de sites internet en PHP. Le langage de programmation PHP est largement répandu dans le domaine du développement Web; il est donc bien connu des directions de systèmes d'information, ce qui facilite la maintenance des projets utilisant ce langage. Il existe de multiples *frameworks* PHP et.phpony est l'un de ceux proposant le plus de fonctionnalités. Il est d'ailleurs le socle sur lequel se fondent d'autres *frameworks* à l'instar de Laravel, lui aussi communément utilisé..phpony compose un environnement de travail cohérent, utilisé pour de larges applications à l'instar de Dailymotion; sa robustesse est également un atout pour les projets plus réduits comme DISHAS, dans la mesure où il offre une grande fiabilité, en même temps qu'une importante adaptabilité. La documentation et la communauté soutenant cet outil en font un instrument robuste pour la conception d'une application Web ayant vocation à être pérenne.

## Structure de l'application

L'arborescence des fichiers contenant le code nécessaire à l'exécution de l'application se divise en différentes branches, chacune chargée du fonctionnement d'un module précis. Il ne sera évoqué ici qu'un petit nombre de ces principaux composants.

Dans le dossier *Entity* sont reproduites les tables de la base de données : pour chacune d'entre elles, une classe reprenant chacun des champs de la table est définie. Un enregistrement de la base sera ainsi transformé en objet PHP utilisable dans le code; à cet objet seront associées des méthodes spécifiques, afin de manipuler les propriétés qui lui sont associées. Pour récupérer le titre d'une entrée de la table *Work*, on pourra par exemple employer la méthode `dessTitle()` ; pour définir la valeur de la propriété *title* de cet objet, on utilisera en revanche la méthode `题目Title()`. Le dossier *Repository* quant à lui, définit pour chacune des entités des méthodes supplémentaires, davantage complexes, faisant jouer le rapport entre les données; par exemple, l'entité *Work* y dispose d'une méthode `getPrimarySources()` qui a pour but de récupérer toutes les sources primaires issues d'une œuvre.

Le dossier *Controller* réunit quant à lui tous les contrôleurs, sortes de chefs d'orchestre de l'application. Les contrôleurs sont des fonctions qui agrègent les données nécessaires à la constitution d'une vue pour les transmettre au fichier de *template*. Si l'on a par exemple besoin du titre et des sources primaires reliés à une œuvre au sein d'une page de l'interface, on stockera la valeur des deux méthodes évoquées précédemment à l'intérieur de variables; ces variables seront ensuite ajoutées à la valeur de retour de la fonction, de manière à les faire parvenir aux fichiers de vues.
## Gestion des vues
Le développement *front end* – portant sur ce que l’utilisateur voit à l’écran (utilisant notamment les langages HTML, CSS et JavaScript<fnref n="1" />) – concerne la partie « vue » de l’architecture MVC. La conception des interfaces publiques de DISHAS s’est donc concentrée en grande partie sur l’élaboration de *templates* pour l’affichage des pages. Symfony dispose du moteur de *templates* Twig, qui s’intègre directement dans le code d’une page HTML. Twig sert notamment à transmettre les données définies dans la partie « modèle » de l’application au code qui sera envoyé au navigateur.

Pour afficher par exemple le titre d'une œuvre sur une page de notice, l'information contenue dans la base de données doit d'abord être transposée en objet PHP grâce au fichier d'entité définissant les caractéristiques d'une œuvre. L'information est ensuite récupérée par le contrôleur dédié aux pages de notices d'œuvre, puis transmise à la vue par le biais de Twig<fnref n="2" />.

<figure><img src="image_30.png" /><figcaption>FIGURE 9.2 – Étapes pour l’affichage d’une donnée de la base au sein d’une page Web</figcaption></figure>

## Stockage et récupération des données

L’application de DISHAS s’appuie sur une base de données relationnelle : cela signifie que les informations utilisées par la plateforme sont stockées à l’intérieur de tables, connectées entre elles par des relations définies à l’aide de cardinalités<fnref n="3" />. Pour accéder aux données, l’application doit utiliser un intermédiaire logiciel que l’on nomme ORM (Object-Relational Mapping). L’ORM de Symfony est appelé Doctrine; il permet de faire le lien entre les tables de la base de données et les classes du programme applicatif. Son rôle consiste donc à synchroniser les enregistrements de la base avec les objets PHP de l’application.

Les fonctionnalités de Doctrine permettent d’interroger et récupérer de manière simple les données de la base. En convertissant en objets les données issues de la base

<footnote n="1">1. De manière générale, le langage HTML définit la structure d'une page Web, le CSS son apparence graphique et JavaScript le comportement interactif des composants de la page.</footnote>

<footnote n="2">2. Les passages Twig dans le *template* HTML sont repérables par leur balisage à l'aide d'accolades : `{{ }}`.</footnote>

<footnote n="3">3. La cardinalité désigne le nombre minimum et maximum de possibilités de relation entre deux entités. Par exemple, un *original item* ne peut être contenu que dans une source primaire. Une source primaire en revanche peut contenir plusieurs *original items*. La cardinalité entre ces deux entités est donc de 1 à n.</footnote>
relationnelle, l'ORM modifie la morphologie de l'information de manière à la rendre compatible avec la logique des langages orientés objet comme PHP. Néanmoins, Doctrine constitue en cela une couche logicielle supplémentaire qui peut nuire aux performances générales de l'application.

### 9.1.2 Le paradigme client/serveur

De nombreux systèmes informatiques reposent sur l'architecture client/serveur. Dans le cas des applications Web, elle désigne le mode de communication entre deux programmes : le client est un programme qui envoie des requêtes et le serveur est un programme qui répond à ces requêtes. Dans une plateforme en ligne, le serveur est la machine qui envoie les pages apparaissant sur le navigateur de la machine client.

#### Distinction *back end*/*front end*

Cette bipartition dans le fonctionnement de l'application fait écho à la distinction entre développement *back end* et développement *front end*. Le *back end* fait référence à la partie du code – rédigée en PHP dans le cas de DISHAS – qui n'est pas visible à l'utilisateur. Le *front end* en revanche représente la partie qui aura une influence directe sur ce qui est affiché sur l'écran du navigateur : les langages utilisés dans le *front* sont HTML, CSS et JavaScript.

Cette distinction se retrouve également dans la manière dont sont exécutés les différents langages utilisés dans la plateforme. L'intégralité du code écrit en PHP est traité par le serveur, alors que le HTML, CSS et JavaScript sont interprétés par le navigateur sur l'ordinateur du client. Dans le cas des *templates*, la partieTwig est exécutée par le serveur, tandis que le reste est à la charge de la machine client. Il existe ainsi différentes méthodes pour le traitement de la donnée : une même information pourra manipulée et formattée à l'intérieur du PHP, comme au sein du JavaScript.

Ces méthodes de traitement de la donnée ont chacune leurs implications. En premier lieu, la puissance de calcul du serveur est généralement plus importante que celle du client ; cela signifie que des procédures programmatiques lourdes sont effectuées plus rapidement si elles sont rédigées en PHP. Il est ainsi préférable de circonscrire au maximum l'utilisation de JavaScript pour traiter les ressources numériques. Par exemple, si une interface a besoin d'un jeu de données formatté de manière spécifique, il est conseillé de le mettre en forme dans le *back end*, plutôt que de transmettre des données brutes au *front end* pour ensuite les agencer de manière adéquate. Ainsi, pour remplir le *template* de barre latérale de métadonnées, une méthode propre à chaque entité a été définie dans les *repositories* afin de générer des tableaux associatifs<fnref n="4" /> contenant les métadonnées d'un enregistrement.

<footnote n="4">4. Un tableau associatif en PHP est une manière d'organiser la donnée, où chaque valeur est associée à une clef. Ce format est comparable aux objets JavaScript ou aux dictionnaires Python.
Exemple : `$manuscrit = ["cote" => "Latin 14420", "folios" => 32, "langue" => "latin"]`.</footnote>
## Contraintes du développement *front*

Toutefois, il n'est pas toujours possible de traiter les ressources numériques au sein du *back end* de l'application. En effet, lors de l'utilisation d'ensembles de données importants au sein d'une même interface, il est parfois préférable d'avoir recours à des méthodes de programmation asynchrone<fnref n="5" /> au sein du *front end*, de façon à réduire les durées de chargement à l'ouverture de la pageβ. En effet, JavaScript permet de récupérer certaines informations du serveur, sans entraver l'exécution du reste du code, de manière à éviter de soumettre l'utilisateur à d'importants temps d'attente.

Ce procédé est nommé *Ajax* (*Asynchronous JavaScript and XML*) : le principe consiste à envoyer une requête au serveur, indépendamment du chargement de la page. Le code asynchrone est exécuté comme tâche de fond, sans occasionner de temps de la-tence lié à l'actualisation entière de la page. Cette technique est employée notamment pour charger de façon incrémentale un fil d'actualité, ou encore pour suggérer des termes d'autocomplétion dans un champ de saisie<fnref n="6" /> : cela permet de fluidifier la navigation, de manière à rendre transparent le processus de requêtage de données. La méthode Ajax est notamment employée dans le *front office* pour récupérer les données nécessaires à la com-position de la carte chronologique : cette technique permet d'afficher certains éléments de la page avant que l'intégralité de la visualisation ne soit constituée.

Ces formes d'optimisation du code sont nécessaires à considérer dans le processus de développement des interfaces, en particulier pour les visualisations de données qui sont très coûteuses en termes de puissance de calcul. Le code *front end* étant interprété par l'ordinateur du client, la rapidité d'exécution du programme dépend de la puissance de sa machine, ainsi que des capacités de compilation de son navigateur. S'il n'existe plus de sensibles différences entre les navigateurs Web, il subsiste quelques variations concernant certaines fonctionnalités implémentées par les langages *front*.

La structure de l'application ainsi que l'architecture client/serveur conditionnent la manière dont est traitée l'information. Ainsi, pour assurer aux internautes une expérience de navigation agréable au sein du *front office*, les problématiques de vitesse de chargement doivent influencer directement la manière dont sont pensés les développements. S'il est préférable d'effectuer la manipulation de données dans la partie *back end* de la plateforme, il est cependant nécessaire de savoir repenser les méthodes de requêtage et de gestion des données, afin d'offrir aux utilisateurs des interfaces optimales et ergonomiques.

<footnote n="5">5. L'exécution du code est généralement linéaire, chaque ligne étant traitée l'une après l'autre. Dans le cas de l'asynchrone, la portion de code concernée est placée dans une file d'attente et n'est exécutée qu'une fois le reste du code effectué.</footnote>

<footnote n="6">6. La suggestion de termes se fondant sur une liste de mots accessible depuis une base distante.</footnote>
## 9.2 Implémentation d'ElasticSearch

### 9.2.1 Présentation d'ElasticSearch

#### Fonctionnement d'ElasticSearch

ElasticSearch est un logiciel libre <fnref n="7" /> servant à l'indexation et la recherche de données; il s'appuie sur une base de données **NOSQL** (Not Only SQL) ainsi que sur le moteur de recherche Lucene <fnref n="8" />. Les bases de données **NOSQL** se définissent en opposition aux bases relationnelles, elles recouvrent des formes aussi diverses que les bases graphes <fnref n="9" /> ou les bases orientées documents <fnref n="10" />. La base ElasticSearch s'organise autour d'un système complexe de clusters et de nœuds très flexible, pouvant s'adapter à toute sorte de donnée. Ce type d'architecture a l'avantage d'être résilient, performant et de bien supporter la montée en charge. Les données insérées et récupérées de la base ElasticSearch sont au format JSON, elles ne sont en revanche pas stockées ainsi.

La base de données d'ElasticSearch est le support de son moteur de recherche. Les fonctionnalités proposées par ElasticSearch permettent à la fois d'y extraire un grand nombre de résultats à l'aide de requêtes imprécises, comme d'effectuer des recherches extrêmement détaillées, grâce à des possibilités de filtres extensives, tout cela avec une grande rapidité. Le moteur d'ElasticSearch est également fortement orienté texte, les résultats de recherche étant classés selon leur pertinence vis-à-vis des mots-clefs renseignés par l'utilisateur. La vitesse de requêtage ainsi que les fonctionnalités de recherche avancées sont deux atouts qui ont amené l'équipe technique de DISHAS à implémenter cette solution en complément de l'API. L'API a vocation à servir principalement à interagir avec la base de données relationnelle sans passer par l'interface graphique, tandis qu'ElasticSearch doit être utile à l'extraction d'importants ensembles de données et à la construction de requêtes complexes. ElasticSearch constitue en cela un élément essentiel de l'exposition des données de la base de DISHAS.

L'implantation d'un serveur ElasticSearch est relativement aisée, la principale difficulté de l'implémentation de cet outil réside dans la constitution du *mapping* définissant l'architecture conceptuelle de la base. Cette étape permet de transposer les données de la base relationnelle à l'intérieur de la base **NOSQL** d'ElasticSearch; elle a été facilitée par l'utilisation de l'extension.php FOSElasticaBundle. Certaines tables de la base n'ont pas été reproduites dans le *mapping* d'ElasticSearch, seules les données intéressantes pour les chercheurs ont été intégrées.

<footnote n="7">7. ElasticSearch est un logiciel *open source* sous licence libre Apache.</footnote>

<footnote n="8">8. Lucene est un moteur de recherche modulable spécialisé dans la recherche textuelle</footnote>

<footnote n="9">9. Pour le stockage de triplets RDF notamment.</footnote>

<footnote n="10">10. À l'instar des bases de données constituées de documents au format XML ou JSON.</footnote>
## Visualiser et explorer avec Kibana

L'implantation d'ElasticSearch sur une base de données donne en outre accès aux différents outils de la suite Elastic. Kibana est l'un de ces outils : il permet de créer par le biais d'une interface graphique des visualisations sur mesure, à partir des données indexées dans ElasticSearch. Les fonctionnalités de Kibana peuvent être étendues par l'ajout de plug-ins, permettant l'utilisation de divers procédés d'analyse sur les données ainsi que de multiples types de visualisations. Certains des modules de Kibana sont par ailleurs payants, à l'instar de l'extension Graph développée par Elastic, qui permet de représenter les relations entre les enregistrements de la base sous forme de graphe.

Kibana a été originellement créé pour composer des tableaux de bord, aidant les administrateurs d'une application à visualiser les logs<sup>11</sup>. S'il est possible de partager les visualisations réalisées avec Kibana et de les intégrer dans un fichier HTML, elles ne sont pas conçues pour être diffusées sur une plateforme publique. Pour le projet DISHAS, il a ainsi été décidé que l'accès à Kibana serait réservé aux chercheurs, de manière à leur permettre de créer des représentations graphiques sur mesure des données qu'ils souhaitent voir interagir.

### 9.2.2 Utilisation dans le front office

Les fonctionnalités de recherche proposées par ElasticSearch ont été largement utilisées au cours de l'élaboration des interfaces du front office. La mise au jour des interactions entre les données étant au cœur de l'architecture de la plateforme publique, les modalités de recherche d'ElasticSearch ont permis de tisser des liens entre les ressources de manière plus efficace et précise que les méthodes de requêtage offertes par l'ORM Doctrine. ElasticSearch est ainsi utilisé à la fois dans la partie *back end* de l'application, au sein du PHP, mais également dans la partie *front end* par le biais de méthodes de requêtage asynchrone.

#### Requêtage en *back end*

La barre latérale de métadonnées présente sur les pages d'enregistrements dispose d'un système de « loupes » qui rattache chaque notice aux enregistrements connexes de la base. Si une œuvre a par exemple été créée par Jean de Lignières, l'icône de loupe permet à l'utilisateur d'avoir accès à toutes les œuvres créées par le même auteur. Ainsi, pour chaque champ de la barre latérale est associée une requête à la base de données correspondant à l'ensemble des entités partageant la même caractéristique.

Pour chaque entité de la base qui dispose d'une page de notice, a été définie une méthode spécifique permettant de générer les données à afficher dans cette barre latérale<sup>12</sup>.

<footnote n="11">11. Les logs sont des fichiers d'historiques des événements.</footnote>

<footnote n="12">12. Cette méthode est décrite plus en détail à l'annexe G.2.</footnote>
Cette méthode définit non seulement les métadonnées d'un enregistrement mais également les requêtes qui seront envoyées à ElasticSearch. Les requêtes faites à ElasticSearch sont formulées en JSON, toutefois, cette technologie évolue rapidement et la syntaxe des requêtes est modifiée régulièrement. Afin d'aider à l'élaboration de ces requêtes et d'assurer une compatibilité accrue au cours du temps, il a été décidé d'utiliser le client PHP Elastica qui permet faire le lien avec le serveur ElasticSearch dans le *back end*. Elastica permet de formuler à l'aide d'une classe PHP des requêtes qui seront ensuite traduites en JSON.

Les requêtes à élaborer pour la constitution des barres de métadonnées conservent souvent des structures similaires et il aurait été redondant de reproduire systématiquement des procédures semblables pour chaque requête. Il a donc été décidé de créer une extension de la classe *Query* d'Elastica afin de systématiser la rédaction de requêtes.

Par exemple, voici la formulation d'une requête au format JSON pour récupérer dans la base ElasticSearch tous les *original item* élaborés entre 1450 et 1500, suivi de son équivalent, formulé à l'aide du client Elastica :

<figure><img src="image_31.png" /><figcaption>FIGURE 9.3 – Formulation dans le langage de requête d'ElasticSearch</figcaption></figure>

<figure><img src="image_32.png" /><figcaption>FIGURE 9.4 – Formulation dans le langage de requête du client PHP Elastica</figcaption></figure>
Avec l'extension de la classe Query, il est possible de créer la même requête en une ligne (newTimeQuery(1450, 1500)) de manière à alléger le code et faciliter la maintenance. Ces requêtes sont ensuite insérées dans le tableau associatif servant à générer la barre latérale des pages de notices. Lors du clic sur une icône de loupe, la requête est envoyée à la page de recherche par le biais du contrôleur.

## Chargement asynchrone des données

Le moteur de recherche ElasticSearch est employé pour deux utilisations distinctes dans la partie *front end* de l'application : pour la visualisation en carte ainsi que pour la page de recherche.

Toutes requêtes qui transitent par la page de recherche sont envoyées en Ajax à ElasticSearch. L'utilisation de méthodes asynchrones pour la récupération de résultats est particulièrement adaptée, dans la mesure où elles permettent d'effectuer plusieurs requêtes les unes à la suite des autres, sans nécessiter de réactualisation de la page.

<figure><img src="image_33.png" /><figcaption>FIGURE 9.5 – Processus de requête asynchrone à ElasticSearch pour la page de recherche</figcaption></figure>

Le processus d'exécution d'une recherche suit toujours les mêmes étapes. Deux types de requêtes peuvent advenir ; soit la requête est envoyée depuis une page de notice, soit elle est formulée à partir des termes renseignés dans la barre de recherche. La requête est ensuite envoyée à ElasticSearch ; le résultat reçu est alors formaté de manière à apparaître au sein d'un tableau de résultats. Cette méthode permet de conserver un temps d'attente minimal pour la réception de résultat, tout en profitant des fonctionnalités avancées de recherche du moteur ElasticSearch. Cependant, seule la recherche plein-texte a été pour l'instant mise en place dans l'interface de recherche, il est prévu toutefois d'y ajouter la possibilité d'utiliser des filtres.

L'utilisation d'ElasticSearch pour la visualisation de carte chronologique répond à d'autres motivations. Cette visualisation en effet rassemble de nombreuses données, puisqu'elle vise à représenter tous les enregistrements d'œuvres et de sources primaires de la base. Le chargement de l'ensemble de ces données par l'intermédiaire de l'ORM Doctrine
est supérieur à l'utilisation d'ElasticSearch. Il est toutefois difficile d'estimer exactement
le gain de temps occasionné, dans la mesure où l'exécution du code asynchrone est pos-
térieure au chargement de la page. De plus, la base de données de DISHAS reste pour
l'instant assez réduite et les temps de requêtage restent courts. Néanmoins, pour la même
quantité de résultats, le recours à ElasticSearch divise quasiment par deux le temps de
chargement de la page (de 46,44 ms à 24,33 ms <fnref n="13" />).

Ainsi, l'utilisation d'ElasticSearch est complémentaire au requêtage de la base de données par un ORM ; si elle induit parfois la nécessité de traiter la donnée dans la partie *front end* de l'application, elle offre des avantages de performance et participe à alléger les interfaces pour des visualisations plus fluides. ElasticSearch est également un outil indispensable pour explorer les données dans le détail, afin de permettre aux utilisateurs de réunir des données qu'il aurait été difficile de connecter en utilisant des langages de requêtes plus élémentaires <fnref n="14" />.

<footnote n="13">13. Ces résultats ont été obtenus grâce au moniteur de performance de sffony.</footnote>

<footnote n="14">14. ElasticSearch permet notamment d'effectuer des recherches de distance par rapport à point par-
ticulier, par exemple pour retrancher tous les enregistrements créés dans un rayon de 100km. Reproduire
le même résultat à l'aide d'un ORM ou du langage SQL est bien plus complexe.</footnote>
# Chapitre 10

## De la conception à l'implémentation
des visualisations

### 10.1 Technologies de visualisation de données

#### 10.1.1 Choix du moyen de réalisation

Les visualisations de données sont une partie centrale de la plateforme publique : elles constituent un moyen d'expression flexible et modulable pour exposer les données de recherche du projet DISHAS. De nombreuses technologies numériques permettent de réaliser des visualisations, cependant elles ne sont pas toutes adaptées aux mêmes types d'application, et n'exigent pas le même niveaux de compétence en programmation.

#### Logiciels de visualisations

Il existe une grande variété de logiciels permettant de composer des visualisations de données directement au sein d'une interface graphique. Ils n'exigent aucune connaissance préalable, si ce n'est une compréhension minimale des données à traiter. Les logiciels comme Excel, Tableau ou les plateformes comme Palladio et Kibana permettent à des utilisateurs novices de concevoir des visualisations riches et diversifiées. Néanmoins, les possibilités de configuration sont réduites aux fonctionnalités admises dans le logiciel, restreignant ainsi la variété des réalisations potentielles. En outre, ce genre d'outil n'est pas toujours adapté à la publication sur le Web : s'il est souvent possible d'insérer ce type de visualisations à l'intérieur du code HTML, il peut subsister des difficultés d'affichage. Dans le cas de Kibana notamment, l'intégration de visualisations à l'intérieur d'une page publique peut entraîner des failles de sécurité; en ce qui concerne Tableau, toutes les réalisations sont conservées sur le serveur de l'application, occasionnant parfois des délais de chargement supplémentaires.
Les logiciels de visualisations sont particulièrement indiqués pour aider des chercheurs à concevoir des graphiques sur mesure : pour des utilisateurs connaissant bien leur corpus de données, ces outils offrent des ressources intéressantes pour formuler graphiquement des hypothèses de recherche. En revanche, ces instruments ne sont souvent pas conçus pour être employés sur un site internet. Leur utilisation est à privilégier pour la création de visualisations ponctuelles, indépendantes d'une interface Web.

## Visualisation de données avec R

R est un langage de programmation statistique avec lequel il est possible de générer des visualisations de données. Il est extrêmement modulable et permet aux développeurs de créer une multitude de graphiques, grâce aux nombreuses extensions qui y être peuvent ajoutées. C'est un outil particulièrement employé dans le monde académique, notamment car il permet de manipuler les données à l'aide de fonctions statistiques et mathématiques avancées. Il est souvent utilisé en parallèle du langage de programmation Python, qui offre également des possibilités de visualisations et d'analyses statistiques extensives, grâce à des bibliothèques comme MatPlotLib ou encore Seaborn. Si R est plus généralement utilisé pour analyser des jeux de données en CSV, il existe des packages pour parser du JSON, de l'XML ou encore des fichiers de tableurs.

R n'est pas réputé pour être un langage difficile d'appréhension au premier abord, toutefois il semble que certains types de diagrammes nécessitent une connaissance accrue du langage pour être réalisés. En outre, R est plutôt dédié à la conception de graphiques statiques; les bibliothèques additionnelles qui proposent d'ajouter de l'interactivité utilisent généralement JavaScript pour les éléments dynamiques<fnref n="1" />.

## Bibliothèques JavaScript

En ce sens, il semble plus indiqué de n'avoir recours qu'à JavaScript pour créer les visualisations de données dans le front office. Il existe un grand nombre de bibliothèques JavaScript spécialement dédiées à l'intégration de visualisations de données aux pages Web. Ces bibliothèques disposent toutes de spécificités; certaines sont extrêmement versatiles et polyvalentes – à l'instar de D3.js ou Chart.js<fnref n="2" /> – tandis que d'autres sont spécialisées dans un unique type de graphique – comme Leaflet pour les cartes ou Chartist pour les diagrammes simples. La richesse d'une bibliothèque JavaScript est souvent corrélée à la difficulté de son apprentissage; en outre, plus les visualisations à réaliser sont complexes, plus une connaissance approfondie de la bibliothèque est nécessaire.

Il existe des bibliothèques JavaScript adaptées à tous les usages; si cette richesse est profitable, elle rend le choix d'une technologie particulièrement ardu. Plusieurs questions

<footnote n="1">1. Notamment pour bibliothèques Plotly, DT et Shiny qui intègrent toutes des fonctionnalités d'interactivité à l'aide de JavaScript.</footnote>

<footnote n="2">2. D3.js et Charts.js sont à la tête du marché des visualisations sur le Web d'après ??.</footnote>
sont donc à considérer : quels types de visualisations sont prévus ? Quelle est la taille du jeu de données à traiter ? Quel environnement de développement est utilisé au sein du projet<fnref n="3" /> ? L'application doit-elle être disponible en version mobile ? Les fonctionnalités de la bibliothèque sont-elles bien supportées par les différents navigateurs ? Quel degré de personnalisation de l'interface est nécessaire ? Chacune des réponses à ces interrogations conditionne le choix d'une bibliothèque.

## 10.1.2 Choix d'une bibliothèque JavaScript

### Critères de choix

Ainsi, le choix d'une bibliothèque JavaScript doit prendre en compte de nombreux paramètres. En premier lieu, le régime de tarification est important à considérer : en effet, le projet DISHAS ne bénéficie pas de financements suffisants pour payer la licence d'une bibliothèque JavaScript ; or, si la plupart proposent une partie de leurs fonctionnalités gratuitement, il existe souvent certaines conditions d'utilisation payantes. Il faut donc veiller à sélectionner une bibliothèque qui accepte les usages prévus pour le *front office* de la plateforme.

Un second critère essentiel de choix concerne la documentation et la communauté liées à une technologie. En effet, une bibliothèque extrêmement efficace et flexible ne peut être utilisée au maximum de son potentiel, s'il n'existe pas d'exemple ou de documentation auxquels se référer pour l'utiliser. La communauté de développeurs peut également être de grand secours ; une question relative à une bibliothèque largement utilisée sera résolue très rapidement sur des sites comme StackOverflow. Un bon indicateur de la vivacité d'une communauté peut être trouvé sur les *repositories* GitHub des différentes technologies : le nombres d'étoiles<fnref n="4" /> et la date du dernier *commit* peuvent être ainsi révélateurs du dynamisme d'un projet.

Un autre élément à considérer est évidemment les fonctionnalités offertes par une bibliothèque. La recherche de technologies de visualisations de données s'est fait ultérieurement à l'élaboration des graphiques à implémenter dans le *front office* : ainsi, il était important que la bibliothèque choisie comporte une grande variété de visualisations, notamment des visualisations en carte. La flexibilité de la bibliothèque est particulièrement importante dans la mesure où DISHAS est un projet aux effectifs réduits et que l'utilisation de grand nombre de dépendances augmente la difficulté à maintenir l'application. En outre, la partie *back office* de la plateforme disposait déjà de visualisations ; le choix d'une technologie s'est donc fait de manière à complémenter les bibliothèques préalablement implémentées dans l'application.

<footnote n="3">3. L'emploi de *frameworks* comme React ou Angular peuvent conditionner le choix vers des bibliothèques compatibles.</footnote>

<footnote n="4">4. Les étoiles indiquent sur GitHub le nombre d'utilisateurs ayant mis en favori un projet en particulier.</footnote>
La bibliothèque de visualisations pour DISHAS devait donc être à la fois robuste, versatile et fortement personnalisable. Une première sélection de bibliothèques a donc été effectuée en fonction des critères énoncés ci-dessus pour être mise à l'épreuve. Cinq bibliothèques<fnref n="5" /> ont été testées dans la réalisation du graphique envisagé pour la notice d'œuvre : il s'agit d'un graphique en colonnes relativement simple, idéal pour une première évaluation des possibilités d'une bibliothèque. Cette expérimentation a permis de déceler certaines différences de modélisations des données, ainsi que les avantages et inconvénients de ces technologies. Par exemple, D3.js est une bibliothèque remarquablement développée, ce qui rend sa première appréhension particulièrement difficile. Par ailleurs, Chart.js s'appuie sur l'élément HTML canvas, là où les autres bibliothèques emploient l'élément **svg** : cette différence a une influence sur la rapidité de chargement d'une visualisation. En effet, les bibliothèques utilisant le format SVG (*Scalable Vector Graphics*) offrent davantage de flexibilité, car chaque élément du graphique correspond à un nœud unique du DOM (*Document Object Model*)<fnref n="6" /> qu'il est possible de configurer. En revanche cela signifie également que plus nombreuses seront les données à afficher, plus le temps de chargement sera important ; l'élément **canvas a contrario** est traité comme un assemblage de pixel par le navigateur, et donc est comparable à une simple image en termes de chargement.

## Présentation de AmCharts

La bibliothèque AmCharts a finalement été retenue pour le développement des interfaces publiques, en premier lieu pour la variété des visualisations qu'elle propose : AmCharts offre plus de quinze types de graphiques différents, comprenant notamment des cartes, alors que ces dernières font généralement l'objet de bibliothèques spécialisées. Amcharts est une bibliothèque utilisée par de grandes entreprises, comme Amazon, Apple ou la NASA ; cela garantit la fiabilité de cette technologie, ce qui est important pour un projet comme DISHAS. Son utilisation est gratuite à condition de conserver le logo d'AmCharts dans le coin inférieur des visualisations de données.

<figure><img src="image_34.png" /><figcaption>FIGURE 10.1 – Logo de la bibliothèque JavaScript AmCharts</figcaption></figure>

<footnote n="5">5. Il s'agit des bibliothèques Chart.js, D3.js, Google graphs, ApexCharts et AmCharts.</footnote>

<footnote n="6">6. Le DOM correspond à l'architecture en arbre d'un document HTML.</footnote>
Amcharts dispose en outre d'une impressionnante documentation et de très nombreux exemples de visualisations, ce à quoi s'ajoute un blog où sont régulièrement postées des astuces pour la confection de graphiques complexes et modulables. Un avantage de cette bibliothèque réside dans la possibilité de configurer tous les éléments d'une visualisation, de manière à s'adapter au plus près des envies des concepteurs. Elle propose par ailleurs de nombreuses fonctionnalités pour concevoir des visualisations interactives et dynamiques, que l'utilisateur peut manipuler. Pour une première approche de la bibliothèque Amcharts, un tutoriel succinct a été mis à disposition à l'annexe H ; des fichiers HTML simplifiés, reproduisant les visualisations déployées dans le front office, ont été également ajoutés aux appendices documentaires du mémoire.

## 10.2 Constitution d'une visualisation

### 10.2.1 Dialogue entre conception et réalisation

La constitution d'une visualisation consiste souvent en un travail itératif, où phases d'élaboration et de développement se répètent jusqu'à obtenir à une forme graphique satisfaisante. La visualisation permet de révéler des informations sur les données qui n'étaient pas prises en compte au départ, donnant lieu parfois à des incohérences ou des incompatibilités graphiques ; il est donc souvent nécessaire d'effectuer de multiples aller-retours entre réflexion et réalisation, pour parvenir à la visualisation la plus pertinente.

Le diagramme en barre prévu initialement pour la page de notice des sources primaires a particulièrement évolué entre sa forme liminaire et son aspect final. Cette visualisation a initialement été conçue en miroir de la notice d'œuvres : l'enjeu était d'y représenter chaque original item contenu dans une source primaire, classé en fonction de l'œuvre dont il est tiré. À la suite de discussions avec les chercheurs du projet au cours d'un séminaire DH, il a été décidé d'intégrer une composante de foliation au graphique, pour proposer deux modes de visualisation : un présentant la quantité d'original items par œuvre et un autre montrant leur disposition au sein de la source primaire. Une seconde version de la visualisation a donc été réalisée ; il est alors apparu que plusieurs original items pouvaient être accolés les uns aux autres sur une même page. Sur la visualisation, les éléments représentant les original items étaient ainsi superposés les uns sur les autres sans qu'il soit possible de les distinguer. Une seconde étape de programmation a donc été mise en œuvre, pour faire en sorte de distinguer les items situés sur les mêmes folios.

C'est alors sur la visualisation représentant la quantité accumulée de folios – montrant les original item juxtaposés les uns aux autres – que se sont portées les réflexions : n'est-il pas trompeur de figurer comme étant un nombre total de folios, ce qui est en réalité l'accumulation des folios de chaque original item pris indépendamment ? En effet, cette configuration peut donner l'impression qu'une œuvre compose la majeure partie
<figure><img src="image_35.png" /><figcaption>FIGURE 10.2 – Évolution de la visualisation pour la page de notice de sources primaires</figcaption></figure>

d'une source primaire, alors qu'elle comptabilise moins de pages qu'une autre. Plusieurs
solutions ont été envisagées pour pallier à cet effet : ne représenter par exemple que le
pourcentage d'original item par œuvre, ou encore signifier par différentes épaisseurs la
proportion prise par l'item au sein du folio. Il a finalement été décidé de conserver une
visualisation avec des original items accolés les uns aux autres 7, car elle permet d'évaluer
la quantité de tables issues de chaque œuvre, ce qui est aussi significatif qu'un nombre de
folios. En outre, un diagramme circulaire a été ajouté au sein de la barre latérale afin de
représenter la part véritable de chaque œuvre au sein d'une source. Il reste cependant des
interrogations vis-à-vis de cette visualisation, notamment la question du mélange entre
folio et page (dans le cas de manuscrits recomposés) qui a pour l'instant été éludée 8.

10.2.2 Anticiper les obstacles à la visualisation

Il existe donc de nombreux paramètres qu'il n'est pas toujours possible de connaître
préalablement, mais qu'il faut essayer de prendre en compte, pour assurer l'adéquation
de la représentation graphique avec la donnée à figurer. La base de données sur laquelle
s'est appuyée le travail d'élaboration des interfaces est encore profondément lacunaire, et
comporte de plus de nombreuses données de test, n'ayant aucune véracité scientifique;
en outre, si la base ne sera ensuite alimentée qu'avec des données contrôlées, il subsistera
inévitablement des variations dans la description des enregistrements. Toutes ces compo-
santes sont à anticiper pour proposer des visualisations flexibles, susceptibles de conserver
leur pertinence, malgré une incertitude vis-à-vis de la donnée.

Données lacunaires

Le premier élément auquel une interface modulable doit faire face est l'inconsistance
des données. L'absence d'une donnée peut être envisagée de deux manières différentes dans
une visualisation : soit ne pas faire figurer l'information manquante, soit la représenter,
mais en la distinguant des autres. Dans les pages de notice, il est fréquent qu'un enregist-
trement ne dispose pas de toutes les métadonnées qui puissent lui être associées ; il est

<footnote n="7">7. En plus d'une visualisation des *original items* répartis tels que dans la source primaire.</footnote>

<footnote n="8">8. Il semble qu'une telle configuration sera rarement rencontrée; pour l'instant, les deux systèmes de pagination sont traités de manière quasi équivalente.</footnote>
important de discerner parmi les informations qui font défaut, celles qui sont signifiantes, de celles accessoires. Par exemple, au sein de la barre de métadonnées, certains champs sont éludés s'ils ne sont pas renseignés, alors que d'autres sont conservés pour souligner l'absence de l'information <fnref n="9" />. Par ailleurs, cette absence peut être le signe que l'information n'a simplement pas été renseignée par l'administrateur, ou qu'il n'est pas possible de la donner dans la mesure où le document originel ne permet pas de statuer. Ainsi, l'absence de donnée est un point délicat qu'il n'est pas possible de résumer aisément au sein d'une visualisation ; chaque métadonnée doit être traitée différemment.

Les visualisations de données de la plateforme publique servent, dans la plupart des cas, de portails vers les autres pages de l'interface publique : la carte chronologique par exemple est le seul moyen d'accès – mis à part l'interface de recherche – aux notices d'œuvres et de sources primaires. Chacune de ces entités doit donc figurer sur la carte, quand bien même elle ne serait pas associée à un lieu en particulier. Ainsi, toutes les données qui ne sont pas situées géographiquement ont été arbitrairement placées aux coordonnées 0,0.

De la même manière, il n'est pas exigé dans le modèle de données de préciser les pages d'un *original item*, ce qui met en cause la visualisation de la notice de sources primaires. Pour remédier à ce problème, il a été décidé d'obliger les utilisateurs à remplir ce champ au moment de la soumission du formulaire pour l'insertion d'un nouvel item. Des valeurs par défaut peuvent être renseignées si l'information est véritablement manquante. Il s'agit d'inciter les chercheurs à décrire le plus exhaustivement les données qu'ils ajoutent à la base ; en revanche, il ne faut pas que les visualisations prévalent sur l'exigence scientifique. C'est pourquoi chacune de ces décisions doit être attentivement évaluée en compagnie de l'équipe de recherche, de manière à encourager l'utilisation de la plateforme en proposant des visualisations éclairantes, mais en contraignant le moins possible la pratique des chercheurs.

## Données trop abondantes

Si les données lacunaires peuvent poser problème, l'abondance des données peut également susciter des difficultés. La superposition des éléments graphiques et la concentration des informations peuvent en effet rendre illisible une visualisation. Certaines fonctionnalités et formes visuelles cependant permettent d'éviter ces écueils, en atténuant la complexité des données ; les cartes proportionnelles (*treemap*) et les diagrammes circulaires notamment, figurent de manière facilement appréhendable de grandes diversités d'information en minimisant la part des données en faible proportion. Les modalités de zoom donnent également l'occasion à l'utilisateur de cadrer la visualisation à l'échelle qu'il trouve la plus cohérente.

<footnote n="9">9. Ce point est discuté en détail en annexes G.2.1.</footnote>
Cependant, la principale difficulté de l'abondance de données à visualiser est avant tout la lenteur de chargement qui peut en être occasionnée. L'utilisation d'une bibliothèque JavaScript pour réaliser les cartes et les diagrammes du front office induit que le code sera exécuté sur l'ordinateur du client : la puissance de la machine et l'efficacité du navigateur étant inconnus, il est nécessaire d'alléger au maximum la partie programmative du front end. Les méthodes de chargement asynchrone ou incrémental (lazy loading) permettent notamment de répartir les passages les plus coûteux en puissance de calcul, en échelonnant le chargement des composants à afficher. Il faut en effet distinguer la vitesse de chargement d'une page Web, de sa vitesse d'affichage : la première est une mesure technique, tandis que la seconde est liée à la perception de l'utilisateur. Une page peut être affichée rapidement sans que son chargement soit terminé, offrant ainsi une expérience utilisateur jugée satisfaisante<fnref n="10" />. D'autres procédés ont vocation a être intégrés au front office pour fluidifier encore davantage la vitesse d'exécution des scripts, notamment le regroupement des données en clusters, moins coûteux à traiter par le navigateur. Toutefois, les ajustements programmatiques qui ont été implémentés pour l'instant restent limités, du fait de mes compétences techniques encore modestes.

Pour évaluer les performances des pages publiques, le *bundle* de symfony appelé Fixtures a été utilisé. Cette extension permet d'ajouter de grandes quantités de données à la base, afin de tester la réaction des interfaces. La carte chronologique a été le principal objet de cette évaluation, dans la mesure où il s'agit de la visualisation agrégeant le plus de données : cela a permis d'identifier certains points à simplifier<fnref n="11" />, mais également de ne constater aucun problème majeur. Les navigateurs en outre, disposent d'outils intégrés permettant d'estimer les passages du code exigeant le plus de performance, rendant ainsi possible de caractériser les passages du script à améliorer.

L'efficacité et la vitesse d'affichage des pages publiques de DISHAS ne constitue pas uniquement des ajustements superficiels ; ces éléments sont d'une importance capitale si l'on veut inciter les chercheurs à utiliser les outils de la plateforme. L'augmentation de la performance des navigateurs a engendré un nouveau paradigme pour le développement d'applications ; ce qui pouvait être téléchargé et installé est aujourd'hui plus volontiers en ligne, accessible sur n'importe quel poste d'ordinateur. Les applications en ligne deviennent de plus en plus sophistiquées, habituant ainsi les utilisateurs à des interfaces complexes, chargeant de manière quasi instantanée. Si le *front office* de DISHAS n'offre que des outils laborieux à manipuler, les utilisateurs seront d'autant plus prompts à se désintéresser de la plateforme. La vitesse d'un site Web participe donc à l'exposition des données et doit être prise en considération, au même titre que l'ergonomie générale des

<footnote n="10">10. La vitesse d'affichage est par ailleurs prise en compte dans le système de classement des moteurs de recherche.</footnote>

<footnote n="11">11. Le niveau de description de la carte de chaleur en particulier, de manière à passer d'une granularité à l'année à des tranches temporelles d'une décennie.</footnote>
interfaces.

Que ce soit pour gérer l'abondance ou l'insuffisance des données, la flexibilité des visualisations aide à manier des ressources dont la forme est imprévisible. Le modèle de données induit un nombre fini de possibilités concernant le format des enregistrements de la base ; le rôle du concepteur des interfaces est de veiller à trouver un mode d'affichage pour chacune de ces éventualités, de manière à prévenir les incompatibilités techniques ainsi que les aberrations graphiques. Dans la mesure où la structure de la base de données est encore amenée à évoluer, il sera néanmoins nécessaire de revoir l'agencement des pages du front office<fnref n="12" />, même si la structure de la plateforme publique a été pensée pour admettre des évolutions.

## 10.2.3 Limites de la visualisation

S'il est un moyen d'appréhender aisément des informations complexes, le format graphique qu'offrent les visualisations de données peut également induire en erreur. Parfois la donnée en elle-même est ambiguë et il n'existe pas de forme visuelle adaptée; parfois la représentation graphique véhicule des concepts qui ne sont pas en adéquation avec le contenu.

### Incertitude relative à la donnée

Le premier élément pouvant aboutir à une visualisation trompeuse est relatif à la forme des données sur lesquelles elle s'appuie : qu'il s'agisse de l'aspect lacunaire de certaines informations ou de l'accumulation des données, il existe de nombreux prédicats qui peuvent biaiser une visualisation dans son ensemble. Par ailleurs, plus une visualisation résume une importante quantité de données, plus elle est susceptible de transmettre une impression d'exhaustivité; cependant, la base de données ne reflètera jamais que les documents sur lesquels des chercheurs ont porté leur attention. Le contexte de présentation d'une visualisation peut aider à dissiper cette équivoque, en faisant en sorte d'exposer les données en tant qu'enregistrement d'une base, et non comme représentation objective de la réalité historique.

Si les visualisations de notices ont une dimension plus exacte du fait de leur particularité, il subsiste des incertitudes quant à la représentation de certaines données. Dans le cas par exemple d'une source primaire qui mêlerait deux types de pagination – folio et page – essayer de représenter les deux formes de contenu sur la même échelle<fnref n="13" /> serait fautif : en effet, ce genre de configuration est généralement signe d'un ouvrage hétérogène

<footnote n="12">12. Notamment pour l'aspect responsive des interfaces, dimension qui n'a pas été encore abordée au sein de la plateforme DISHAS.</footnote>

<footnote n="13">13. En convertissant les folios en pages par exemple.</footnote>
composé de parties indépendantes. Faire figurer côte à côte ces différentes parties est donc souvent erroné. Il n'est pourtant pas possible de présumer de la disposition des feuillets d'un ouvrage, en conséquence, une visualisation de données générique ne pourra jamais être tout à fait adéquate. L'idéal serait de pouvoir s'appuyer sur la pagination d'une re-production numérique, il n'existe cependant pas de numérisation de tous les documents à intégrer à la base, rendant le travail de conception des interfaces d'autant plus délicat.

## Représentations biaisées

La seconde difficulté dans l'élaboration d'une visualisation pertinente réside dans l'aspect graphique à choisir pour représenter la donnée. L'échelle, la couleur, la forme ou encore l'interaction des différents éléments, véhiculent des informations à l'utilisateur. Chacun de ces composants doit être choisi avec soin, car il influence l'appréciation des données présentées. Par exemple, la simple flucuation de l'échelle peut induire des conclusions tout à fait contrastées sur une même donnée; une graduation resserrée amplifie les phénomènes de variation, l'inverse les atténue.

<figure><img src="image_36.png" /><figcaption>FIGURE 10.3 – Conséquences visuelles du changement d'échelle d'une visualisation</figcaption></figure>

Au sein du *front office*, plusieurs visualisations ont soulevé des questionnements relatifs à la représentation idéale des informations. Par exemple, comment figurer le chevauchement des *original items* au sein d'une même page : par transparence ? par un système de rayures colorées ? Il a finalement été décidé de superposer horizontalement les blocs d'*original item* de manière à pouvoir cliquer indépendamment dessus. Néanmoins, il existe de multiples manières d'exprimer visuellement cette information ; le concepteur des interfaces doit s'efforcer de trouver celle qui est la plus adaptée, tout en restant réalisable.

La visualisation de la page de navigation historique a également été problématique : si l'utilisation d'une carte a semblé évident, le choix d'un mode de représentation de la temporalité a été l'objet d'interrogations. La frise chronologique devait faire figurer la quantité d'œuvres et de sources primaires créées par période; dans un premier temps, un diagramme linéaire a été choisi. Cependant, les dates de création encodées dans la base indiquent en réalité une période de conception probable : une œuvre conçue entre 1400 et 1450 correspond sur un diagramme linéaire, à un plateau d'un demi siècle. Or, l'utilisateur peut comprendre de cette mise en forme qu'une œuvre a été créée toutes les années entre
1400 et 1450, ce qui est contradictoire avec la donnée de départ. C'est pourquoi, il a été jugé préférable de suggérer ces variations grâce à une carte de chaleur, où la saturation retranscrit plus justement la fluctuation dans le rythme de production.

Chacun des aspects d'une visualisation, dans la mesure où il peut être vecteur de renseignement sur la donnée, doit être choisi avec soin. Depuis le choix d'une technologie pour réaliser des diagrammes, jusqu'à la formulation des libellés, l'élaboration de visualisation mobilise de multiples modalités de médiation, à chaque étape de son processus. De plus, les données de recherche induisent un degré d'exigence scientifique supplémentaire à la conception de graphiques pour les représenter : l'élaboration des pages de la plateforme publique de DISHAS a ainsi tenté de valoriser aux mieux les ressources numériques par différents d'expression, autant visuel que conceptuel.
<figure><img src="image_37.png" /></figure>
Conclusion

Ce mémoire s'est attaché à décrire le travail réalisé au cours du stage que j'ai ef-
fectué au sein de l'équipe de recherche de DISHAS, à l'Observatoire de Paris. La mission
qui m'avait été confiée consistait en l'élaboration de l'interface publique de l'application
Web du projet : il était important pour l'équipe de DISHAS de disposer d'une plateforme
ouverte, qui participe à valoriser les données produites dans le cadre du projet, tout en
restant accessible à des publics variés. Les réflexions qui ont accompagné mon travail se
sont concentrées sur les différentes modalités de médiation numérique par lesquelles il est
possible de présenter un corpus de recherche. Mes réalisations se sont attachées à fournir
des solutions à chaque étape de conception de la plateforme, tant au niveau du parcours
de navigation, que de l'interactivité des interfaces ou encore de l'agencement des visuali-
sations de données.

Le processus de création de la plateforme publique du projet DISHAS s'est déroulé
en plusieurs phases successives. Une première phase d'analyse du contexte a permis d'ap-
préhender le cadre dans lequel s'inscrivait ce travail. Une seconde phase de réflexion a été
consacrée aux différents modes de médiation qu'il est possible d'appliquer à un corpus de
données scientifiques. Enfin, une phase de réalisation technique a été l'occasion de déve-
lopper certaines des interfaces de la plateforme.

La première partie de ce mémoire porte donc sur le contexte de création des données
à valoriser, de manière à mieux appréhender les besoins qui peuvent émaner de la nature
de ces ressources. La variété des approches scientifiques des équipes associées au projet
permet notamment de comprendre la diversité des modes d'utilisation du matériel docu-
mentaire : il est ainsi possible d'en déduire des exigences vis-à-vis des instruments infor-
matiques à développer. La nature du corpus et les procédés de sa numérisation constituent
également des axes de réflexion privilégiés, car la base de données compose véritablement
le socle sur lequel peut se construire la plateforme en ligne.

En second lieu se pose la question de la mise en forme de ces données. Dans cette
optique, trois modes de médiation des ressources numériques ont été établis comme ob-
jectifs de l'interface publique : la présentation du corpus, l'accompagnement du travail de
recherche et l'exposition des données brutes. La présentation des ressources numériques
vise à les rendre explicites tout en introduisant les utilisateurs aux enjeux scientifiques qui sous-tendent le projet. L'accompagnement du travail de recherche consiste quant à lui à fournir des instruments pour assister les chercheurs dans leurs investigations du corpus numérique. L'exposition des données brutes enfin, a pour ambition d'aider ceux qui vou-draient exploiter ces ressources : elle vise à rendre accessible non seulement les données, mais également la documentation qui leur est associée.

Enfin, la description technique des différents composants de l'interface publique permet d'exposer les moyens mis en œuvre pour réaliser cette médiation de données. Ces instruments comprennent à la fois des infrastructures logicielles fiables, permettant d'assurer le fonctionnement global de la plateforme, mais aussi des modes de stockage et requêtage alternatifs de la donnée, ou encore le recours à des bibliothèques front end, pour la création d'interfaces sur mesure. Par ailleurs, le travail technique réside également dans l'établissement de bonnes pratiques, à la fois pour la gestion des développements program-matiques, mais également pour assurer le dialogue entre recherche et ingénierie.

Au sein de la conception de la plateforme publique, le travail de médiation consiste donc à dresser une passerelle entre la base de données et l'utilisateur, en mobilisant à la fois une appréhension fine du corpus de recherche, une compréhension des attentes des différents publics ainsi que des connaissances des technologies numériques. L'interface pu-blique doit proposer un discours sur la donnée qui réponde à des questions de recherche, en mettant en œuvre différents principes de médiation à l'aide de procédés informatiques. La plateforme de DISHAS vise à exposer la donnée de manière conforme aux principes FAIR, de manière à participer à un écosystème ayant pour but la valorisation des ressources numériques.

L'élaboration des interfaces du front office n'est cependant pas achevée et il subsiste encore de nombreuses formes d'expression la donnée à explorer. Le projet DISHAS n'en est par ailleurs qu'à son commencement et il n'est pas encore possible d'évaluer avec précision l'adéquation des développements avec la pratique des utilisateurs. Ainsi, de nombreuses perspectives se dessinent quant à l'évolution des modes de valorisation du corpus de recherche ; l'accroissement de la base de données va être notamment la première étape vers la constitution de contenus inédits, en particulier car elle va être l'occasion de voir émerger de nouvelles hypothèses de recherche.
Annexes
<figure><img src="image_38.png" /></figure>
# Annexe A

## Base de données du projet

Ce schéma, réalisé avec *MySQL Workbench*, exclut les tables ne concernant pas la description du corpus de recherche, c'est-à-dire les tables structurelles comme celles liées à la gestion des utilisateurs.
<figure><img src="image_39.png" /><figcaption>FIGURE A.1 – Schéma de la base de données réalisé avec MySQL Workbench</figcaption></figure>
# Annexe B

## Glossaire

### B.1 Astronomical object

An astronomical object is a celestial entity associated with some natural phenomena. In DISHAS, astronomical objects are used as a way to classify astronomical tables in broader categories.

### B.2 Astronomical parameter set

A parameter set is a set of astronomical quantities that describes tables at the level of astronomical theories. A parameter set can be shared by several tables across different traditions. Broadly speaking, there are two kinds of parameters :

- explicit parameters that are directly read off the table, e.g., the maximum value(s);

- implicit parameters that need to be retrieved from the table content computationally, e.g., solar eccentricity.

In some cases, these explicit or implicit parameters are only significant in groups; whereas in other instances, parameters can be independently significant. Parameters are a central tool in delineating and connecting astronomical traditions and analysing the mathematical and astronomical content of the tables. A parameter-set is only linked to an intellectual author through an edited text because a single parameter-set can be shared by many different sources.

### B.3 Edited text

An edited text is a production credited to a contemporary intellectual author or historian. It documents one specific table, text, or diagram. This document can be from a previous edited source or a new edition created using the web interface of DISHAS.
An edited text can have various edition-types including an edition of a specific original text, a recomputation, a new production based on multiple sources, etc. An essential goal of the database is to make editions of astronomical tables that are accessible and comparable. In achieving this, edited texts, as classified in various edition-types, help identify mathematical and astronomical parameters, examine and develop critical and computational tools for creating new editions, and provide a centralised resource for studying astronomical tables from different traditions.

We collect general information about the edition, e.g., the title, the date of creation, etc., to record the metadata associated with it. This, along with the other information associated with the edited text, helps us unify and create standards for comparison in our database. We collect secondary source information for bibliographic accuracy and catalogue reference.

## B.4 Historical actor

Historical actors are individuals or collectives related to the items or works stored in the database. They include author, copyist, owners, dedicatee, etc. associated to the materials of the original item. Within the framework and scope of our database, we collect certain information related to the historical actors, namely, their name, their flourit, and their location, to enable us to create a standardised lists of actors.

With the additional (and highly recommended) Virtual International Authority File (VIAF) number recorded, the database makes it possible to align names added at a latter stage with a larger, normalised, authority register of person names. We collect information about the actors in order to build prosopographic data.

## B.5 Intellectual author

An intellectual author is a contemporary historian who has produced an edition that is stored in the database. This historian could be different to the person entering the data into the database. For example, in certain instances, a scholar (user) may be entering the data from an edition created by another historian (from, perhaps, an unpublished collection). The intellectual author in this case is the creator-historian and not the scholar (user).

Collecting information about intellectual authors validates the factual reliability of the database. This effort helps preserve the work of previous generation of historians as a way to foster and encourage further studies. The information collected about intellectual authors helps identify modern scholarship of the edition entered in the database.
## B.6 Journal

In academic publishing, a scientific journal is a periodical publication intended to further the progress of science, usually by reporting new research.

## B.7 Library

A library is a present-day or last-known location where the primary source is situated. The knowledge of the physical location of the library where the primary source is held is important for establishing the reliability of the database as a research resource. Facilitated with assistance tools like ISNI, entering the library information helps the database register and identify the correct library. For other libraries (not on ISNI records), a new entry helps create a record of its existence in the database for subsequent use.

## B.8 Mathematical parameter

There are two kind of mathematical parameters :

- A table is said to be “displaced” when a constant value is added to its arguments or/and its entry. The value of these added constant are the first kind of mathematical parameters.

- A table can also be “shifted”. This happens when the ordering of the arguments and/or entry is modified according to a permutation cycle. The number of shifts in the permutation cycle is the second type of mathematical parameters.

The main purpose of identifying mathematical parameters is to compare displaced and/or shifted tables with those which are not displaced or shifted. We note that both kinds of tables may rely on the same set of astronomical parameters. Mathematical parameters can be shared by different sources. Additionally, shift and displacement are peculiar kinds of mathematical techniques linked to the manipulation of table sets and as such are worthy of investigation in their own right.

## B.9 Original text

An original item is a table, text, or diagram as it appears in a given primary source. In instances where the actual state of the item is the result of several distinctive production acts, e.g., an extra column added to a table by a later actor, each differing state is a specific item. A scholar (user) may input these instances as separate original items. In the current stage of development of DISHAS, only tables are considered; texts and diagram will be included at a later stage. The original item, as it appears in the primary source, is the
fundamental unit of the database. Hence, elementary units are individual tables, diagrams, or texts that are actually witnessed in specific primary sources. This level of granularity is central to make DISHAS an efficient tool for mathematical analysis and critical editing.

We collect material information about the original item to allow source criticism. These include the date and the place of production, the title of the work, the manuscript shelfmark, etc.

## B.10 Place

The definition of a place depends on the object to which it relates. For an original item, it refers to the place of production. For an author, it refers to his main place of activity where his work can be (approximately or accurately) geo-localised. For a work, the place refers to the original place of conception. This information is important to understand the diffusion and circulation of items in various works and traditions.

Collecting information about the place, including, in some instances, its latitude and longitude, helps us represent the locations on a map. This visual representation can become an important tool for textual analysis and circulation studies.

## B.11 Primary source

A primary source is a manuscript or an early printed edition in which the original item is found. It is essential for the reliability of DISHAS that it provide accurate identification of its primary sources. Additionally, having accurate information about primary sources in the database can prove to be an important tool to study the history of modern collections in astral sciences.

Information about the primary source helps us identify the physical institution or library that holds the primary source. This identification allows scholars to locate the original source for further investigation.

## B.12 Secondary source

A secondary source is a book, an article, a chapter, etc. that indicate a contemporary edition, or a survey of the table. Any edited document in the database can only be linked to a single secondary source for brevity. Information about secondary sources provides a reliable and tractable resource for further studies. This information will help current and future scholars use the database for their research.
## B.13 Table content

The table content is the collection of numerical values in the edited text. The relation between these numerical values and those attested in the original item(s) associated with the edited text depends on the edition-type selected. We understand edited text as the type of work done by the intellectual author responsible of its creation.

Comparing numerical contents of various tables and building new computational and analytic tools is central to the aim of DISHAS. In order to achieve this, a minimum level of standardisation in the layout of tables and the format of recorded numbers is necessary. However, it is equally important to allow a certain level of flexibility to reflect the practices of historical actors faithfully. Hence, there are several possibilities about table layout, table types, and types of numbers. The choices of an intellectual author are carefully documented to ensure a meaningful comparison between the table contents of various edited texts. We collect information about the table contents in order to structure the contents for displaying purposes. The astronomical parameters are linked to the edited texts (and not to the original text) because a given parameter set is always attributed to a table by an intellectual author after analyses.

## B.14 Table type

Table are classified in different types. These different types correspond to the specific steps in astronomical computations as organised by historical actors. In modern terms, these types correspond to distinct mathematical functions which express a portion of an underlying astronomical theory.

## B.15 Type of edition

Three types of edition are defined in DISHAS

### Type-A : Edition Numerically consistent table

The first stage involves the rendition of the individual table (taken from individual MSS of the same work) from its diplomatic transcription onto a more numerical consistent form, i.e., a numerical format free of any data integrity errors. The following is a list; albeit not an exhaustive one, of the different types of strategies employed in creating a numerically consistent table.

1. The first stage involves the rendition of the individual table (taken from individual MSS of the same work) from its diplomatic transcription onto a more numerical consistent form, i.e., a numerical format free of any data integrity errors. The fol-
lowing is a list; albeit not an exhaustive one, of the different types of strategies employed in creating a numerically consistent table.

2. Numerical parsing on a local and global scale to keep regularity, e.g., correcting a number to maintain simple mathematical regularity. It should be noted here that this inspection is merely observational and not computational.

3. Using pattern recognition and visual inspection to correct numbers for constancy, uniformity, and accuracy (in reproduction).

4. Noting all numerical changes, e.g., instances where ambiguous, dubious, or inconsistent numbers are altered, alternatives or originals are duly noted as comments.

Note: Any ancillary material (paratext, scribal error marks and corrections, change in handwriting, etc.) is NOT included in this table: these remain features that are to be noted in the TEI version of the table.

## Type-B : Edition Numerical Reproduced Table

The second stage involves employing the different individual tables (belonging to the same work, but taken from different MSS) and forming an EDITION table. This process can be defined based on a few different strategies :

1. Any eclectic, stemmatic, or copy-text method (in general, any philological method) of comparing the different 'witness' tables (from Part A) and establishing a critical 'base' numerical table, with all variants duly noted in comments. These comments effectively make the apparatus criticus.

2. Any mathematical method (from Part C) of establishing a critical 'base' numerical table and then employing tables (from Part A) to note the variants.

3. Any combination of the two strategies above.

4. Additionally, any previously 'critically' edited table (from a set of extant or non-existing manuscripts) belonging to the same table-type and work (as set in Part A) can also be stored in Part B here. In such cases, it is important to note any relation, if applicable, of this previous work to the different tables in Part A. Failing this, a common reference to the work and table-type becomes minimally necessary.

Several different 'critical editions' (based on different editorial strategies) of the same table may be stored in this stage; all of which, are identified with the correct relational structure to the tables in parts A and C.

## Type-C : Edition Numerically Recomputed Table(s)

The third stage involves the recomputed tables – corresponding to each individual table in Part A – that are stored relationally in the SQL database. These tables are generated based on the following possible strategies :
1. A modern mathematical recomputation of the table based on (a) choice of appropriate parameter, (b) mathematical equations governing the underlying function tabulated, (c) selection of a suitable generative or iterative algorithm.

2. A historically congruous mathematical algorithm based on editorial decisions. These tables are generated by a modern scholar based on his or her own understanding of the mathematical apparatus presumably intended to have been used by the original author in his time. These tables form a collection of our modern efforts to reconstruct numerical tables within its historical context.

3. Any other derivatives or combinations of mathematical procedures, algorithms, iterative techniques, rounding schemes, etc. used to generate the numerical entries of the table form separate mathematical tables that are also stored in this part.

## B.16 Work

An astronomical work is a distinct intellectual creation consisting of tables, texts, or diagrams. It is often identified by a title or incipit and attributed to a given historical actor. Its content and organisation may vary depending on the particular primary source.

We can analyse the different attestations of a given work as original items rather than individual works are the fundamental unit of *DISHAS*. For instance, one can identify a core set of tables around which various satellites tables, texts, or diagrams may be presented depending on the primary source. With this design, the geographical and chronological evolution of these dynamical sets of original items can be analysed and studied. This ability is essential when it comes to critical editing a work. Additionally, the choice of an original item as the fundamental unit also allows to analyse the intellectual composition of a given manuscript. This is an important step in understanding how manuscript shape intellectual traditions.

A work needs to be identified by a current title or incipit. When possible supplementary information like place, dates, authors or translator is very useful for studying the circulation of the work.
<figure><img src="image_40.png" /></figure>
# Annexe C

## Captures d'écrans de l'interface administrateur

<figure><img src="image_41.png" /><figcaption>FIGURE C.1 – Page d'accueil de l'interface administrateur</figcaption></figure>
<figure><img src="image_42.png" /><figcaption>FIGURE C.2 – Page de liste des enregistrements des éditions de tables astronomiques</figcaption></figure>

<figure><img src="image_43.png" /><figcaption>FIGURE C.3 – Page de liste des enregistrements des original items</figcaption></figure>
<figure><img src="image_44.png" /><figcaption>FIGURE C.4 – Interface de saisie numérique de tables</figcaption></figure>
<figure><img src="image_45.png" /></figure>
# Annexe D

## Présentation du front office

Document de présentation utilisé lors du séminaire numérique de l'équipe de DIS-HAS du 13 mai 2019, en présence de l'équipe de recherche. Certaines diapositives ont été retirées du document pour éviter la redondance de l'information. Cette présentation visait à exposer les propositions de développements concernant les parties de l'interface utilisateur.
# Purpose of the front office

- Expose the platform data

- Publish tables

- Present the project

- Provide pedagogic content

- Be an attractive showcase

Conceptors of
DISHAS

Amateurs

Librarians

Researchers

Teachers / Students

<figure><img src="image_46.png" /></figure>
# Aim of the visualizations

- Explore DISHAS's **data** in its specificity

- Aggregate a lot of data : **quantitative analysis**

- Illustrate the **context of production** of the tables

- Approach the subject in an **interactive way**

- Discover unexpected **correlations** between data

- Provide **course materials**

# Granularity of visualizations

<figure><img src="image_47.png" /></figure>

## Project

Global visualization
of all the data

Ex: graph of the
entire database

<figure><img src="image_48.png" /></figure>

<figure><img src="image_49.png" /></figure>

## List

Visualization
of an **entity** of
the database

Ex: map of the
places of conceptions
of all the works

<figure><img src="image_50.png" /></figure>

<figure><img src="image_51.png" /></figure>

## Record

Visualization of
a **single record**

Ex: a column chart to
represent the manuscript
originated from a work

<figure><img src="image_52.png" /></figure>
## Entire Database

<figure><img src="image_53.png" /></figure>

# Graph of the database

### PURPOSES

- Better understanding the conceptual model of the database

- Discover unexpected correlations between records

- Be an attractive showcase for the project

## Entire Database

<figure><img src="image_54.png" /></figure>

# Schema + graph

<figure><img src="image_55.png" /></figure>

Example

Tools: Sigma js, cytoscape, Gephi, Kibana
* Astronomical object
* Table type
* Formula definition

<figure><img src="image_56.png" /></figure>

# Discover table models

## PURPOSES

- Provide editorialized scientific content for the platform

- Give access to the tables via an astronomical logic

- First milestones of a virtual exhibition on medieval astronomy

* Astronomical object
* Table type
* Formula definition

<figure><img src="image_57.png" /></figure>

# Discover table models

<figure><img src="image_58.png" /></figure>

Link to the tables that use this model
<figure><img src="image_59.png" /></figure>

<figure><img src="image_60.png" /><figcaption>Clickable schema
of the geocentric
model</figcaption></figure>

<figure><img src="image_61.png" /></figure>

Example of an animated schema

Astronomical
object

Extensive
iconography

<figure><img src="image_62.png" /><figcaption>Eclipse</figcaption></figure>

<figure><img src="image_63.png" /><figcaption>Moon</figcaption></figure>

<figure><img src="image_64.png" /><figcaption>Mars</figcaption></figure>

<figure><img src="image_65.png" /><figcaption>Trigonometrical</figcaption></figure>

<figure><img src="image_66.png" /><figcaption>Spherical</figcaption></figure>

<figure><img src="image_67.png" /><figcaption>Sun</figcaption></figure>

<figure><img src="image_68.png" /></figure>
<figure><img src="image_69.png" /><figcaption>Table
edition</figcaption></figure>

<figure><img src="image_70.png" /><figcaption>Historical
sources</figcaption></figure>
<figure><img src="image_71.png" /></figure>

Work

Original

item

# Historical sources

<figure><img src="image_72.png" /></figure>

## PURPOSES

- Focus on the creation context of the tables

- Illustrate the circulation of knowledge

- Show places and periods of intellectual profusion

- Give access to the records of work and primary source
Work
Original
item

<figure><img src="image_73.png" /></figure>

Density of works
created at this
location

<figure><img src="image_74.png" /></figure>

Density of
original items
created at this
location

Cursor to set a
time period

Work

<figure><img src="image_75.png" /></figure>

General
informations

<figure><img src="image_76.png" /></figure>

Link to the list of
works sharing
the same
characteristics

<figure><img src="image_77.png" /></figure>

<figure><img src="image_78.png" /></figure>

Work

GENERAL INFORMATION

Tabule Magne

Incipit

Multiplicis
philosophie

Creator

John of
ligneres ⚙️
(1290-1350)

Date of
conception

1325 ⚙️

Place of
conception

Paris, France

<figure><img src="image_79.png" /></figure>

Manuscript :
Gonville and
Caerus College
MS 110
1350-1450

Manuscript :
Latin 10264
1400-1500

Manuscript :
Bav. Pal Lat.
1367
1400-1500

Manuscript :
Bav. Pal Lat.
1374
1407

Manuscript :
Bav. Pal Lat.
1412
1453-1454

<figure><img src="image_80.png" /></figure>

For more information on these tables, click on the chart elements

Visualisation
of the
primary
sources and
original
items
originated
from the work

Example
Primary
source

<figure><img src="image_81.png" /></figure>

General
informations

<figure><img src="image_82.png" /></figure>

Primary source

Manuscript — Gonville and Caius College, MS 110

<figure><img src="image_83.png" /></figure>

Link to the list of
**primary sources**
sharing the same
characteristics

Example

Visualisation of
the **work** and
**original items**
present in the
primary source

Original
item

<figure><img src="image_84.png" /></figure>

Place of
creation of the
**work** of the
original item

<figure><img src="image_85.png" /></figure>

Place of
creation of
the **original**
**item**

Place of
curation of the
**manuscript**
containing the
original item
Edited text
Table
content

# Table editions

<figure><img src="image_86.png" /></figure>

## PURPOSES

- Give an overall view of the edited content of the platform

- Show tendencies in type of table / astronomical parameter

- Give access to the records of table edition

Edited text
Table
content

# Admin side

<figure><img src="image_87.png" /></figure>

<figure><img src="image_88.png" /></figure>
<figure><img src="image_89.png" /><figcaption>## Treemap

**Edited text**
**Table**
**content**</figcaption></figure>

<figure><img src="image_90.png" /></figure>
## Edited text
Table
content

Column :
country or
period

<figure><img src="image_91.png" /></figure>

2.8

2.6

2.5

Astronomical
object

2.9

2.7

2.5

2.4

2.2

2.1

0...0.0

0...0.0

0...0.0

<figure><img src="image_92.png" /></figure>

# Table edition

<figure><img src="image_93.png" /></figure>

## Historical Context

(edition type A
and B)

- related work

- related manuscript

- etc.

## Mathematical Context

- astronomical
parameter set

- table type

- etc.

## Editorial Context

- sources of the
edition

- intellectual author

- edition type

## Table content

- View of the table

- Critical apparatus

- Comments
Edited text

## Historical context

<figure><img src="image_94.png" /></figure>

<figure><img src="image_95.png" /></figure>

Edited text
Table
content

## Mathematical context

<figure><img src="image_96.png" /></figure>

<figure><img src="image_97.png" /></figure>
## Editorial context

<figure><img src="image_98.png" /></figure>

<figure><img src="image_99.png" /></figure>

## Table content

<figure><img src="image_100.png" /></figure>

## Table content

<figure><img src="image_101.png" /></figure>

Metadata of the cell that was clicked

Location 8 - 7

Variants :

- Ms 1 : 12

- Ms 2 : 13

- Ep 3 : 11

Comment :

« blah blah blah »

Link to modify the table in DTI
## Exposing the data : technical choices

### Three way to query the database

SQL queries

<figure><img src="image_102.png" /></figure>

Doctrine ORM

+ ease of use
- low performance

<figure><img src="image_103.png" /></figure>

Elasticsearch API

+ speed of execution
- under development

<figure><img src="image_104.png" /></figure>
# Technologies for visualization

## Visualization Software

- graphic interface

- no loading time

- static views

- not very customizable

<figure><img src="image_105.png" /></figure>

## Javascript libraries

- great diversity available

- no control over updates & backward compatibility

JS

## Kibana

- graphic interface

- easy installation with elastic search

- not designed for public visualizations

<figure><img src="image_106.png" /></figure>

# Choice of a javascript library

<figure><img src="image_107.png" /></figure>

- Versatile library: chart, map, animated graph

- A lot of documentation available

- Interesting features: zoom, exports, etc.

- Easy implementation and handling

- Pricing: free on given conditions
<figure><img src="image_108.png" /></figure>
# Annexe E

## Cahier des charges fonctionnel des visualisations pour l'interface utilisateur

Ce document est un cahier des charges fonctionnel où sont décrites en détail toutes les interfaces de la plateforme publique; chaque rangée correspond à une page de la plateforme, chaque colonne concernant quant à elle un aspect précis de cette page :

- une première colonne présente l'interface de manière générale : son objectif, son architecture globale avec la description de ses différents composants ainsi qu'éventuellement des interrogations vis-à-vis de sa conception;

- une deuxième colonne expose l'ensemble des données qui seront récupérées de la base pour l'affichage, en particulier pour les métadonnées requises dans les pages de notices;

- une troisième colonne s'attache à expliciter précisément la visualisation de donnée apparaissant sur la page (si tel est le cas), tant dans son aspect visuel que dans ses enjeux intellectuels;

- une quatrième colonne concerne les données nécessaires à la constitution de cette visualisation;

- une cinquième colonne dresse la liste de tous les liens de redirection présents à l'intérieur de la page, composant ainsi le réseau dans lequel elle s'inscrit;

- une dernière colonne détaille les corpus de données qui pourront être établit à partir de cette page. Cette partie concerne essentiellement les pages de notice, et fait référence aux « loupes » disposées sur la barre latérale de métadonnées.
<table><thead><tr><th>DESCRIPTION DE LA PAGE</th><th>MÉTADONNÉES A AFFICHER</th><th>VISUALISATION DE DONNÉES</th><th>MÉTADONNÉES DE LA VISUALISATION</th><th>LIENS ET REDIRECTION</th><th>PAGE RECHERCHE AVEC LISTES D'ENTITÉS</th></tr></thead><tbody><tr><td><strong>BLOC 1</strong><br><strong>Éléments :</strong><br>- Bannière: logo + phrase résumant le projet très succédant (type: plateforme de recherche en astronomie médiévale)<br>- Barre de navigation: Logo (accueil), Découvrir (historical navigation + astronomical navigation), Recherche, À propos, Back office<br><br>Court paragraphe d'introduction au projet (lien pour en savoir plus à propos) dans une bannière pour le mettre en avant<br>- Accès aux parties Historical navigation / Astronomical navigation + paragraphe de présentation des deux parcours de découverte de la donnée + mention du glossaire<br>- Accès à DTI + paragraphe de présentation de Foutil<br>- Accès à la visualisation en graphe de la base de données + paragraphe de présentation<br>- footer: projets partenaires + RGPD<br><br><strong>Enjeux :</strong><br>- Faire comprendre de quoi le projet retourne<br>- Guider l'utilisateur dans son parcours dans le site<br>- Constituer une entrée en matière attractive</td><td></td><td><strong>Métadonnées affichées :</strong><br>Selon la facilité d'accès aux pages d'œuvre (BLOC 3) et de source primaire (BLOC 4) grâce à la visualisation, il sera nécessaire ou non d'afficher une liste d'enregistrements en plus de la visualisation. Si tel est le cas (il est possible de penser à une liste se mettant à jour en fonction des données affichées sur la visualisation). On peut imaginer également pouvoir filter les données affichées sur la visualisation grâce à un système de case à cocher au sein des listes d'enregistrements)</td><td><strong>VISU 2</strong><br><strong>Enjeux :</strong><br>Mettre en valeur le contexte de production des œuvres et d'enfigurer la dispersion géographique<br><br><strong>Visualisation de données :</strong><br>Carte des original items et des œuvres conçue comme un point d'entrée aux pages d'enregistrements d'œuvres et de sources primaires: chaque œuvre sera représentée par un point sur la carte correspondant à son lieu de conception. Si de nombreuses œuvres sont placées au même endroit, les points seront regroupés pour constituer des points plus ou moins gros pour signifier la densité: au zoom, les différents enregistrements apparaîtront distingués. À chaque point sera de plus assigné une période de temps: des curseurs pourront permettre de déterminer une période de temps pour laquelle on souhaite configurer l'affichage des enregistrements. La même chose sera faite pour les données d'original item avec leur lieu de rédaction ou d'édition.<br><br><strong>Problème :</strong> si la visualisation est pensée comme un point d'accès, il faut que chacun des enregistrements représentés soit accessible, or, si deux œuvres sont placées exactement au même endroit, la question se pose de l'affichage différencié des ces données.</td><td><strong>Données de la visualisation :</strong><br><strong>WORK (all records)</strong><br>- id = title / small incipit<br>- tpq + taq<br>- PLACE = placeName + lat + long<br><br><strong>ORIGINAL TEXT (all records)</strong><br>- id<br>- tpq + taq<br>- PLACE = placeName + lat + long<br>- PRIM SOURCE = id + shelfmark / primTitle</td><td><strong>Liens vers autres pages</strong><br><strong>BLOC 3 :</strong> Au clic sur un point représentant une œuvre, redirection vers la page de l'œuvre correspondante.<br><strong>BLOC 4 :</strong> Les points représentant un original item redirigent vers la page de la source primaire qui le content.<br><strong>BLOC 6 :</strong> Astronomical navigation<br><strong>BLOC 12 :</strong> Lien vers la recherche facétée</td><td><strong>Listes</strong><br>Liste de toutes les œuvres<br>Liste de toutes les sources primaires</td></tr><tr><td><strong>BLOC 2</strong><br><strong>Enjeux :</strong><br>- Point d'accès aux données d'enregistrements<br>- Présentation des données de la base dans leur aspect historique<br>- Representer de manière simple des corrélations complexes entre les données<br><br><strong>Description de la page :</strong><br>Point d'entrée aux enregistrements d'œuvres et de sources primaires. Page constituant un portail historique vers la donnée: il s'agit de contextualiser la donnée historique dans son milieu et de présenter les interdépendances et causalités entre les entités de la base de manière claire.<br><br><strong>Page conçue comme un pendant du BLOC 6, constituant une approche davantage astronomique de la donnée</strong><br><br><strong>Problème :</strong> données de la base qui peuvent tendre à constituer une visualisation biaisée: rappel que les données présentes ne sont pas vouées à être exhaustives et qu'elles sont probablement trompeusement représentatives.</td><td><strong>Métadonnées affichées :</strong><br><strong>WORK (all records)</strong><br>- id + title / small incipit<br>- tpq + taq<br>- HIST ACTOR (array) - actorName<br><br><strong>PRIMARY SOURCE (all records)</strong><br>- id<br>- shelfmark + LIBRARY = name / primTitle<br>- tpq + taq</td><td></td><td></td><td></td></tr><tr><td><strong>BLOC 3</strong><br><strong>Enjeux :</strong><br>- Mise en avant des métadonnées<br>- Montrer les liens avec les entités issues de cette œuvre (original item, primary source et edited text)<br>- Situer le contexte de création de l'œuvre<br><br><strong>Description de la page :</strong><br>Notice de métadonnées pour l'entité œuvre: il s'agit de présenter et contextualiser le plus complètement, car l'entité work a censément la primaute par rapport à toutes les autres entités de la base: il faut donc souligner cette parenté intellectuelle. De plus, il faut rappeler le contexte de production d'une œuvre en suggérant le milieu qui a entouré la création de cette œuvre et évoquant la tradition dans laquelle elle s'inscrit.<br><br><strong>Question :</strong><br>Est-ce nécessaire de fournir une visualisation en carte de l'œuvre pour figurer la répartition géographique des témoins et sources primaires ?<br><br>Possibilité soit de donner un accès à une visualisation en carte sur une page extérieure ou une visualisation plus développée pour la page Original item</td><td><strong>Métadonnées affichées :</strong><br><strong>WORK (single record)</strong><br>- id + title + titleOriginalChar<br>- incipit + incipitOriginalChar<br>- tpq + taq<br>- translator + creator(s):<br>- HIST ACTOR = id + name + tpq + taq + viaf<br>- PLACE = id + placeName<br>- createdBy = FOS USER - username<br><br><strong>ORIGINAL ITEM (array)</strong><br>(originalItem.work = current work)<br>- LANGUAGE (array) - languageName<br>- SCRIPT (array) - scriptName<br><br><strong>DEFINITION (single record)</strong><br>(id = 26)<br>- longDefinition<br>- userInterfaceColor</td><td><strong>VISU 3</strong><br><strong>Enjeux :</strong><br>Visualisation qui met en avant la compléteur de l'œuvre dans les différentes sources primaires et donne un aperçu du contenu scientifique de celle-ci.<br><br><strong>Description de la visualisation :</strong><br>Visualisation en colonnes proche de la VISU 4 où chaque colonne représente une source primaire contenant l'œuvre en question. Chaque colonne est ensuite subdivisée en cellules représentant les original items issus de l'œuvre contenue dans la présente source primaire. C'est-à-dire que ne sont pas affichés les original items dans ces sources qui ne sont pas issus de l'œuvre.<br><br>La hauteur d'une cellule est déterminée par l'importance en terme de page de chaque item. En outre, la couleur d'une cellule correspond à l'objet astronomique de la table: une légende sur le côté indique la signification de ces différentes couleurs.<br><br>L'ordre des colonnes est chronologique. Chaque élément de la visualisation est cliquable et donne accès à la page de l'élément concerné. Enfin, il est possible de zoomer dans la visualisation pour accéder à plus de détail.<br><br>Au dessous de ce graphique, il est possible d'ajouter une frise chronologique où seront figuré les sources primaires ou témoins. (En outre, pour témoinner de la diffusion de l'œuvre dans différentes traditions, une visualisation en diagramme circulaire des langues peut être envisagée: se pose la question en revanche du statut des œuvres qui ne sont qu'une traduction, ce qui faussera la visualisation).</td><td><strong>VISU 4</strong><br>(originalItem.primSource = those primary sources)<br>- shelfmark<br>- LIBRARY = libraryName<br>- primType<br>- ORIGINAL ITEM (array) = tpq + taq</td><td><strong>Données de la visualisation :</strong><br><strong>ORIGINAL ITEM (array)</strong><br>(originalItem.work = current work)<br>- id = originalTextTitle<br>- tpq + taq<br><br><strong>TABLE TYPE = ASTRONOMICAL OBJECT</strong><br>pageMin + pageMax = nombre de pages<br>- PRIMARY SOURCE = id<br>(- LANGUAGE = languageName)<br><br><strong>PRIMARY SOURCE (array)</strong><br>(originalItem.primSource = those primary sources)<br>- shelfmark<br>- LIBRARY = libraryName<br>- primType<br>- ORIGINAL ITEM (array) = tpq + taq</td><td><strong>Liens vers autres pages</strong><br><strong>BLOC 4 :</strong> au clic sur le label des colonnes, redirection vers la notice de la source primaire désignée<br><strong>BLOC 5 :</strong> au clic sur les cellules, redirection vers la notice de l'original item concerné<br><strong>BLOC 2 :</strong> Historical navigation<br><strong>BLOC 6 :</strong> au clic sur un élément de la légende, redirection vers une page de présentation de l'objet astronomique correspondant<br><br><strong>Sites extérieurs</strong><br>- VIAF: lien vers la notice de la personne en question lorsqu'un identifiant est renseigné</td><td><strong>Listes</strong><br>(Œuvres du même auteur<br>Éditions (publiques) de cette œuvre<br>- Œuvres conçues dans la même époquegraphique (± 1 long, ± 2 lat)<br>- Œuvres conçues dans la même période temporelle (± 50 tpq, ± 50 taq)<br><br><strong>Question :</strong> Si l'œuvre représentée est une traduction, la date donnée par l'utilisateur est-elle celle de la conception ou de la traduction ?<br>Déterminer une période de temps autour de cette date est-il encore pertinent?</td></tr></tbody></table>
<figure><img src="image_109.png" /></figure>

ASTRAVINGOAMTICANL

<figure><img src="image_110.png" /></figure>

<figure><img src="image_111.png" /></figure>

BLOC 6

Enjeux :

- Proposer un point d'entrée « astronomique » vers les éditions, les modèles de tables et autres téléscriptes.

- Fournir les textes explicatifs d'introduction aux concepts centraux du projet (qu'est-ce qu'une table ? Modèle / canon ?) Idéalement, présentation des différents « objets astronomiques »

- Illustrer l'imbrication des concepts d'objet astronomique, de type de table, de modèles

- Figurer tous les objets astronomiques de la base

- Donner à voir des représentations médiévales astronomiques

- Rappeler la diversité des traditions et conceptions de l'astronomie

Description de la page :

La page est pensée comme pouvant être une introduction à l'astronomie médiévale ainsi qu'un pendant au BLOC 2 décrivant les données dans leur versant historique. Présence de textes d'introduction aux notions centrales du projet élaborés par des chercheurs avec des « disclaimer » pour expliquer la variété des différentes traditions.

La page n'affiche au départ que les différentes images d'objets astronomiques provenant de cultures vanées : lorsqu'un objet est sélectionné par l'utilisateur, s'affiche en dessous une série de boutons représentant les différents type de table associés à cet objet. En cliquant sur un type de table en particulier, une liste des éditions, sets de paramètres et modèles liés à ce type de table s'affiche en dessous.

Afin de pouvoir opérer une redirection vers la page où un objet astronomique est déjà sélectionné (lorsque l'utilisateur clique sur la légende des VISU 3 et 4), il faut prévoir une URL ou l'objet astronomique est renseigné en argument de l'URL.

BLOC 7

Enjeux :

- Expliquer les modèles sous-jacents aux calculs modernes des tables

- Fournir du contenu scientifique éditorialisé pour la plateforme

- Constituer les premières pierres d'une exposition virtuelle

Description de la page :

La définition des modèles dans la base de données est déjà stylisée et plus ou moins mise en page : il s'agit donc juste de présenter de manière claire et esthétique les différents éléments qui composent la définition du modèle.

Affichage des schémas et formules.

BLOC 8
TABLE CONTENT

Enjeux :

- (tous les onglets) Présenter les différents aspects inhérents à la nature des éditions de tables

- Constituer une édition de table citable dans un article

- Proposer des outils pertinents de visualisations d'apparait critique

Description de la page :

La visualisation de la table éditée prend l'essentiel de la page : un écart sur le côté permet d'afficher les métadonnées de celle-ci, notamment les métadonnées associées à une cellule précisément en cas de clic de l'utilisateur)

La visualisation donne accès également à DTI afin de pouvoir modifier la table présentée. Des fonctionnalités d'exports peuvent être proposées, notamment en format LaTeX et JSON (découpage des exports entre table, commentaires et métadonnées?).

En cas de plusieurs tables édités (cas des Mean motions), un dropdown pourraient permettre l'affichage des tables une à une.

Chacun des autres aspects de la notice sont présent dans des onglets séparés

Métadonnées affichées :

ASTRONOMICAL OBJECT (all records)

- id + objectName

TABLE TYPE (all records)

- id + table伪TypeName + astronomicalObjectid

EDITED TEXT (all records)

- id + smallEDITedTextTitle

- type

- tableTypeId

- HISTORIAN → firstName + lastName

- date

- public

(Pour les types A : ORIGINAL ITEM → WORK → title)

TABLE CONTENT (all records)

- id + editedTextId

- PARAMETER SET → id

FORMULA DEFINITION (all records)

- id + name

- tableTypeId

PARAMETER VALUE (all records)

- id + parameterSetId

- typeOfNumber

- valueOriginalBase

- valueFloat

Questions :

Est-ce qu'il est pertinent d'afficher des données historiques en tant que paramètre dans la liste des éditions (pour filtrer) sachant que les éditions de type B font référence à plusieurs sources primaires voire même plusieurs œuvres, et que les éditions de type C à aucune de ces entités ?

Est-il possible d'afficher le modèle associé à un contenu de table ? Sinon, doit-on implémenter cette fonctionnalité ?

Métadonnées affichées :

FORMULA DEFINITION (single record)

- id + name

- imageld

- explanation

- modern definition

- bibliography

- parameterExplanation

- argNumber

- latexFormula

formulaJSON : < $\$_p$ > pour récupérer l'id de l'enregistrement de la table parameterFormat

- PARAMETER FORMAT → id + parameterName

- TABLE TYPE → id + table伪TypeName

- ASTRONOMICAL OBJECT → id + name

- authorid : HISTORIAN : id + lastName + first Name

- createdBy : FOS USER → id + username

Métadonnées affichées :

TABLE CONTENT (single record)

- tableTypeId

- argumentName

- public

- editedTextId

- valueOriginal

- jsonOriginal

- etc.

- createdBy : FOS USER → id + username

VISU 8

Enjeux :

- Illustrer avec une iconographie variée les différents objets astronomiques tels que représentés dans les cultures et traditions présentes sur la base.

Description de la visualisation :

Plutôt qu'une série de boutons pour sélectionner un objet astronomique, des images issues de reproductions de manuscrits ou incunables pourraient donner un aperçu de la diversité représentée sur la plateforme.

Liens vers autres pages
BLOC 7 : Modèle de tables
BLOC 2 : Historical navigation
BLOC 8 : Table edition
BLOC 13 : Lien vers la recherche facétée
BLOC 12 : Lien vers la carte des sets de paramètres

Liens vers autres pages

BLOC 7 : Modèle de tables

BLOC 2 : Historical navigation

BLOC 8 : Table edition

BLOC 13 : Lien vers la recherche facétée

BLOC 12 : Lien vers la carte des sets de paramètres

Listes

- Liste des astronomical objects

- Liste des table types

- Liste des Edited texts qui sont publics
- Liste des Formula definition

Liens vers autres pages

BLOC 8 : Table content lie

BLOC 6 : Astronomical navigation

Listes

- Editions qui reposent sur ce modèle

- Modèles liés au même type de table

VISU 8

Enjeux :

- Figurer l'apparat critique de manière intuitive et claire d'utilisation

- Proposer quelques fonctionnalités pour rendre la lecture de la table plus aisée

Description de la visualisation :

La table est représentée dans un tableau (présence ou non d'une grille extérieure permettant de localiser une case comme pourrait le faire un document excel) où les valeurs et arguments sont représentés : ajout d'un coloration plus ou moins intense (heat map) en fonction du nombre de variantes présentes dans telle ou telle cellule.

Un contour de couleur ou autre système de signalement peut quant à lui représenter la présence d'un commentaire.

Un panel sur le côté de la table permet d'afficher à la fois les commentaires et l'apparat critique lié à la case qui a été cliquée. On peut penser à la possibilité d'afficher également l'intégralité des variantes et des commentaires (alors nécessité de localisation des cases grâce à une grille) : les valeurs pour la case sélectionnée pourraient apparaître en surbrillance.

La question subsiste de l'affichage d'un graphique pour représenter graphiquement la table : toutefois, cette fonctionnalité serait de toute manière présente dans DTI

Données de la visualisation : TABLE CONTENT (single record)

- tableTypeId

- argumentName

- public

- editedTextId

- valueOriginal

- jsonOriginal

- etc.

- createdBy : FOS USER → id + username

Liens vers autres pages

BLOC 6 : Astronomical navigation

BLOC 8/11 : Notice de l'édition d'une table

BLOC 5 : original items de la présente édition

Listes

- Editions du même type de table
BLOC 9
HISTORICAL CONTEXT
Enjeux :

- Illustrer la provenance de l'édition

- Donner des indications sur la tradition intellectuelle dans laquelle s'inscrit l'œuvre dont la table édité est trée

Description de la page :

Page de présentation de toutes les métadonnées historiques liées à une édition, c'est-à-dire les témoins, sources primaires et œuvre et leurs métadonnées.

Métadonnées affichées :
EDITED TEXT (single record)
id + editedTextTitle

ORIGINAL TEXT (array)

id + originalTextTitle

- tpq + taq

- comment

- PRIMARY SOURCE → id + primType + shelfmark + LIBRARY
  (→ name + city) + primTitle + primEditor

- WORK → id + title/incipit + tpq + taq + HIST ACTOR (→
  actorName + tpq + taq) + PLACE (→ id + placeName)

- PLACE → id + placeName

- HIST ACTOR → actorName + tpq + taq

- SCRIPT → scriptName

- LANGUAGE → languageName

VISU 9
Enjeux :
- Figurer la provenance historique et géographique de l'édition.

Description de la visualisation :

Visualisation proche de la VISU 5 : carte des original items édités, de l'œuvre associée et des bibliothèques de conservation de ces items.

Données de la visualisation :
EDITED TEXT (single record)
id

ORIGINAL TEXT (array)

(editedText, originalItem = those original items)

- id + originalTextTitle

- tpq + taq

- PLACE → id + placeName + lat + long

PRIMARY SOURCE (array)

(original, primarySource = those primary sources)

- id + primType + shelfmark

- LIBRARY → name + city

WORK (single record)

(original, work = this work)

- id + title/incipit + tpq + taq

- PLACE → id + placeName + lat + long

Liens vers autres pages
BLOC 6 : Astronomical navigation
BLOC 8/11 : Notice de l'édition d'une table

BLOC 5 : original items édités

BLOC 2 : Historical navigation

BLOC 3 : œuvre

BLOC 4 : source primaire

Listes
- Listes des éditions du même manuscrit

- Liste des éditions du même work

- Liste des éditions du même original item

- Liste des éditions issue de l'œuvre du même acteur historique

BLOC 10
MATHEMATICAL CONTEXT
Enjeux :

- Expliciter ce qu'est un parameter set et un parameter format
- Exposer les éléments qui peuvent influencer le calcul d'une table

Description de la page :

Page de présentation des paramètres associés à une table : les paramètres astronomiques (qui pourraient constituer un encart séparé pour souligner leur caractère fondamental, accompagné de définitions du glossaire, etc.) et les paramètres mathématiques (shift, displacement).

Il faut ménager un espace pour l'intégration future des paramètres « contextuels » lies à la date et au lieu pour lesquels la table est computée.

Questions : comment formaliser la notation d'un paramètre mathématique ?

Métadonnées affichées :
TABLE CONTENT (single record)
id + TABLE TYPE → id + tableType + ASTRO OBJECT → id + name

mathematicalParameterId

entryTypeOfNumberId, argument1TypeOfNumberId, ... : TYPE
OF NUMBER → id + typeName + typeDefinition

entryNumberUnitId, argument1NumberUnitId, ... : NUMBER

- UNIT → id + unit

- FORMULA DEFINITION → id + name + latexFormula

- FOS USER → id + username

- PARAMETER SET (array) → id

MATHEMATICAL PARAMETER (single record)

- id + argNumber + entryShift

- typeOfParameter

- argument1DisplacementOriginalBase

- entryDisplacementOriginalBase

- argument1Shift, argument2Shift, ...

PARAMETER VALUE (array)

(parameterValue, parameterSetId)

- id + valueOriginalBase

- TYPE OF NUMBER → typeName

- PARAMETER FORMAT → id + parameterUnitId +

parameterName

CALENDAR (single record)

- id + name + monthList

- ERA → id + name + epoch

DEFINITION (single record)

(id = 23)

- longDefinition

- userInterfaceColor

VISU 10
Enjeux :
- Donner un schéma récapitulatif des paramètres de la tables

Description de la visualisation :

Deux types de visualisations peuvent être envisagées : soit une visualisation en carte à la manière de la VISU 12 (ne mettant en scène que le set de paramètres de la table éditée), soit une visualisation synthétisant tous les paramètres avec leur type de nombre et leur métadonnées respectives, ce qui pourrait entraîner des redondances avec les données affichées sur la partie notice.

La visualisation pourrait constituer l'encart concernant les paramètres astronomiques : c'est-à-dire à la fois le parameter set, les parameter values associées et leurs parameter formats liés.

Il pourrait y avoir autant d'encarts que de sets de paramètres associés à l'édition : leur contenu serait calqué sur la mise en page dans le back office (elle-même reflétant le formulaire pour rentrer un parameter set). Des couleurs et définitions pourraient être ajoutées pour clarifier et rappeler le code couleur pour les objets astronomiques repris dans le front office.

Données de la visualisation :
TABLE CONTENT (single record)
- PARAMETER SET (array) → id +

tableTypeId

TABLE TYPE (single record)

- id + tableTypeName

- ASTRONOMICAL OBJECT → id + name

PARAMETER VALUE (array)

(parameterValue, parameterSetId
= tableContent, parameterSetId)

- id + valueOriginalBase

- TYPE OF NUMBER → typeName

- PARAMETER FORMAT → id +
  parameterUnitId + parameterName +
  parameterDefinitionId + formulaDefinitionId

Liens vers autres pages
BLOC 6 : Astronomical navigation
BLOC 8/11 : Notice de l'édition d'une table

BLOC 5 : original items édités

Listes
- Editions partageant le même set de paramètres (redirection vers la VISU 12)

- Liste des éditions du même type de table

- Liste des éditions du même type de table

- Liste des éditions utilisant le même paramètre mathématique

- Liste d'édition utilisant le même type de nombre

BLOC 11
EDITORIAL CONTEXT
Enjeux :

- Exposer les métadonnées de l'édition

Description de la page :

Page de présentation de l'auteur, du type de l'édition, des sources, etc.

Question : pourquoi un historien peut-il être lié à une ou plusieurs sources secondaires ?

Métadonnées affichées :
EDITED TEXT (single record)
id + date + editedTextTitle + type + created

- public

- comment + onlineResource + pageRange

- secondarySourceId

- HISTORIAN → id + firstName + lastName
  createdBy : FOS USER → id + username

SECONDARY SOURCE (single record)

id + secType + secTitle + secIdentifier + secPubDate

secPageRange + secPublisher + secVolume

- secOnlineIdentifier

- journalId + collectiveBookId : JOURNAL → journalTitle

DEFINITION (single record)

(id = 3)

- longDefinition

- userInterfaceColor

VISU 11
Enjeux :
- Montrer les différentes sources de la présente édition

Description de la visualisation :

La visualisation reprendrait la le graphe des sources de l'édition disponible dans la partie admin pour les notices des Edited text. La présente édition se trouve au milieu du graphe, point vers lequel pointent des fléches partant des différentes sources des édition : ainsi une édition de type B sera liée à tous les original items et éditions sur lesquelles elle s'appuie, qui elles-mêmes seront liées aux original items desquels sont trés la transcription.

Des différences de coloris pourront indiquer le type d'édition dont il est question, de la même manière, il est possible de rendre les différents éléments cliquables, permettant la redirection vers les notices des items concernés (pose la question de la révélation des liens entre les objets et du déplacement des différents éléments).

Données de la visualisation :
EDITED TEXT (single record)
id + smallEditedTextTitle + type + date

- HISTORIAN → id + firstName + LastName

- EDITED TEXT → (même métadonnées)

- originalTextId

ORIGINAL ITEM (array)

(originalTextId = editedText, originalTextId)

- id + tpq-taq + smallTextTitle

- WORK → id + title/incipit + historicalActorId

HISTORICAL ACTOR (array)

(historicalActorId
= originalText, work, historicalActorId)
- actorName + tpq + taq

Liens vers autres pages
BLOC 8/11 : Notice de l'édition d'une table

BLOC 6 : Astronomical navigation

BLOC 5 : original items édités

Listes
- listes des éditions d'un des mêmes original items

- Liste des éditions du même auteur intellectuel

- Liste des éditions du même auteur intellectuel

- Liste des éditions provenant du même journal
<table><tr><td rowspan="10">D<br>A<br>T<br>A<br>B<br>A<br>S<br>E</td><td rowspan="10">G<br>R<br>A<br>P<br>H</td><td>BLOC 14</td><td><strong>Enjeux :</strong><br>- Figurer le modèle conceptuel de la base de donnée<br>- Révéler des corrélations entre les entités de la base<br>- Constituer une vitrine pour le projet</td><td><strong>VISU 14</strong><br><br><strong>Enjeux :</strong><br>- Donner à voir la structure de la base de donnée<br>- Mieux comprendre le modèle conceptuel sous-jacent prévu pour accueillir les tables</td><td><strong>Données de la visualisation :</strong></td><td><strong>Liens vers autres pages</strong><br>- Liens vers les notices d'enregistrements ou les pages de recherche concernant une entité en particulier</td></tr><tr><td><strong>Description de la page :</strong><br>La visualisation, pour des questions de lisibilité et de compréhension, doit être accompagnée d'un schéma.<br>Ce schéma peut être pensé comme suffisamment explicite et placé comme image de fond de la visualisation en grâpe, soit peut être présenté en prélude à la visualisation et assorti d'une texte explicatif ou d'animations aidant à la compréhension du modèle de donnée.<br>Des pictogrammes pourront être réalisés pour apporter un support visuel à la compréhension, notamment au sein du grâpe pour figurer les différentes entités.</td><td colspan="4"></td></tr><tr><td><strong>Description de la visualisation :</strong><br>La visualisation en grâpe est composée de points représentant les enregistrements, et de lignes reliant les enregistrements, symbolisant ainsi les liens entre les données dans la base.<br>Les points peuvent soit correspondre à un seul enregistrement, soit symboliser l'ensemble des enregistrements d'une entité (alors la taille du point sera relative à nombre d'enregistrements).<br>De la même manière, il peut être choisi de ne représenter que les entités principales de la base de données ou alors de tout représenter.</td><td colspan="4"></td></tr><tr><td><strong>Questions :</strong><br>Quelles informations faut-il faire figurer ? Doit-on faire apparaître un label pour chaque enregistrement (visible au survol ?) ?<br>Comment mettre en avant les liens entre entités (en cliquant sur un point pour révéler les lignes de relations ?) ?</td><td colspan="4"></td></tr><tr><td><strong>Outils :</strong> Gephi, Kibana, Sigma</td><td colspan="4"></td></tr><tr><td>BLOC 15</td><td><strong>Pages :</strong><br>- About : texte introductif + liens vers sites de projets pour les actualités<br>- Team : Partenaires + contact<br>- Resources : Glossaire + bibliographie + téléchargements</td><td><strong>Métadonnées affichées :</strong><br>GLOSSAIRE<br><strong>DEFINITION (all records)</strong><br>- objectUserInterfaceName<br>- longDefinition<br>- userInterfaceColor</td><td></td><td></td></tr><tr><td><strong>Enjeux :</strong><br>- Fournir toute la documentation parallèle au projet<br>- Accueillir les documents ayant trait au projet sans avoir d'espaces dédiés à leur présentation<br>- Constituer une interface de contact pour les contributeurs du projet</td><td><strong>ASTRONOMICAL OBJECT (all records)</strong><br>- id + name<br>=> affichage des couleurs</td><td><strong>DOWNLOADS</strong><br><strong>PDF FILE (all records)</strong><br>-文件Name + userFileName</td><td></td><td></td></tr><tr><td rowspan="2">D<br>T<br>I</td><td>BLOC 16</td><td><strong>Enjeux :</strong><br>- Fournir un outil sur mesure pour la saisie de table<br>- Faciliter la saisie, le calcul, la production automatisée d'apparat critique, la transposition dans différents systèmes numéraux</td><td></td><td></td><td></td></tr><tr><td></td><td></td><td></td><td></td><td></td></tr></table>
<figure><img src="image_112.png" /></figure>
# Annexe F

## Exemples de requêtes avec
ElasticSearch

### F.1 ElasticSearch query language

ElasticSearch has its own query language, more documentation can be found here

#### F.1.1 Anatomy of a query

In most cases, an ElasticSearch query is composed of :

- a **header** defining :

- which **method** is to be used : `GET`, `POST`, etc.

- which **index** (i.e. which entity of the database written in `snake_case`) is going to be queried. Not necessary if all indexes will be queried.

- what **type** of search is to be made (`_search` most of the time)

- a **body** defining (among other things) :

- the **fields** that are going to appear in the results (`_source`)

- the **filters** that are going to narrow the number of results matching those filters (`query`)

- different properties of the results (size of the results, index from which to begin, etc.)

**Tips & tricks** The body of a query needs to be a correctly formatted JSON string, even using single quotes instead of double is considered to be an error. The `dev tools` tab in Kibana interface offers help for automatic indentation and autocompletion features that can be very handy.
## F.1.2 Get all records

To get all the records of the entire database:

1. `GET _search`

To retrieve all records from an index (primary source in this case):

1. `GET primary_source/_search`

Which is equivalent to:

1. `GET primary_source/_search`
2. `{`
3. "query": {
4. "match_all": {}
5. }
6. }

## F.1.3 Simple matching query

### Exact term match

All the works that contain the string "tabule" in their title.

Note that the case of the letters doesn't matter, it will match "Tabule" as well. In addition to that, in this configuration, a sub-string will not match the same as the entire string ("tabu" will not match "tabule"); the string is treated as a complete word.

1. `GET work/_search`
2. `{`
3. "query": {
4. "match": {
5. "title": "tabule"
6. }
7. }
8. }

All the original items that are associated with a primary source that is kept in the library that have 2 as id.

1. `GET original_text/_search`
2. `{`
3. "query": {
4. "match": {
5. "primary_source.library.id": "2"
6. }
7 }

8 }

## Multiple terms match

All original items that have in their title either the word “solis”, either the word “lune”.

In this configuration, each string separated by a space is treated individually and the operator used to connect them is **OR**. In other words, the more you put terms, the more you will match original items.

1 GET original_text/_search

2 {

3 "query": {

4 "match": {

5 "original_text_title": "solis lune"

6 }

7 }

8 }

To get a response where each terms given are independently going to filter the result (same kind of behavior as a Google query), you need to specifies the operator to be **AND**.

1 GET original_text/_search

2 {

3 "query": {

4 "match": {

5 "original_text_title": {

6 "query": "lune solis",

7 "operator": "AND"

8 }

9 }

10 }

11 }

## F.1.4 Adding some margin of error

**Fuzziness** The fuzziness allows a certain amount of inaccuracy to be accepted.

All library that approximately have the string “natonale” in their name.

1 {

2 "query": {

3 "match": {

4 "library_name": {

5 "query": "natonale",

6 "fuzziness": "auto"
```json
{
    }
}
```

You can set the fuzziness to 1 or more but the `auto` settings allows a number of letters that do not match, proportional to the length of the term to be searched.

## Full text search on an index

To allow search on every field of an entity, the query has to be set to `multi_match`.

All edited texts that have approximately the string “lune” in one of them fields.

```json
{
    "query": {
        "multi_match": {
            "query": "lune",
            "fuzziness": "auto"
        }
    }
}
```

As is, those kind of requests are deprecated because no fields are specified : ElasticSearch encourages to list the fields you want the query to be executed on. The `fields` allows to reduce noise in the results and to take less time.

All primary sources that match approximately the strings “vatican” and “latin” in the list of fields specified.

```json
{
    "query": {
        "multi_match": {
            "query": "vatican latin",
            "fuzziness": "auto",
            "operator": "and",
            "fields": [
                "shelfmark",
                "digital_identifier",
                "kibana_name",
                "tpq.keywork",
                "taq.keywork",
                "prim_type",
                "library.kibana_name",
                "original_text5.kibana_name",
                "original_text5.table_type.kibana_name",
                "original_text5 place.kibana_name",
                "original_text5.historical_actor.kibana_name",
                "original_text5.script.script_name",
                "original_text5.Language.Language_name"
            ]
        }
    }
}
```
22
23 }
24 }
25 }

Notice that on the fields `tpq` and `taq` that are typed as integer, a string query cannot be performed. In order to query those fields as well, you must add `.keyword` after the field name : it corresponds to the field but typed as a string.

**Wildcards** To find some more documentation for wildcard queries, click here.

### F.1.5 Defining the source

If you are not interested in all the metadata (i.e. the content of the fields) associated with the entity you want to query, it is possible to set a list of fields that are going to appear in the response.

Only the shelfmark, and the library name of all primary sources that are a manuscript

1. `GET primary_source/_search`
2. `{`
3. "_source": [
4. "shelfmark",
5. "library.library_name"
6. ],
7. "query": {
8. "match": {
9. "prim_type": "ms"
10. }
11. }
12. }

Note that if a record in the result do not have some information you asked for (let's say, the primary source isn't associated with a library, thus doesn't have a `library.libray_name`), the result object will not have the key for this precise field. Instead of looking like that :

1. "_source": {
2. "library": {
3. "library_name": "Vatican Library"
4. },
5. "shelfmark": "Vat. Pal. Lat. 1376"
6. }

It will look like :
```json
{
    "_source": {
        "shelfmark": "Vat. Pal. Lat. 1376"
    }
}
```

## F.1.6 Special queries

### Range queries

Range queries can be made on fields that are numbers (even if the field is typed as a string but contains integer) in the Kibana interface, but does seem to only work on integer/float/date typed field when using `api`.

All the primary source that have an edition date between 1400 and 1500

```json
{
    "query": {
        "range": {
            "date": {
                "gte": 1400, // greater than
                "lte": 1500 // less than
            }
        }
    }
}
```

If you want to make a range query on a date typed field (fields that end with `_date`, you can use some ElasticSearch tools for date math (those as well, seems to cause problem when used with `api`):

All original items that have been created between 1000 years before today and 25 years after 1500

```json
{
    "query": {
        "bool": {
            "must": [
                {
                    "range": {
                        "tpq_date": {
                            "gte": "now-1000y"
                        }
                    }
                },
                {
                    "range": {
                        "taq_date": {
                            "lte": "1500-01-01||+25y"
                        }
                    }
                }
            ]
        }
    }
}
```
17 } 18 } 19 } 20 ] 21 } 22 } 23 }

## Geo-distance queries

The fields named `location` holds information that is treated as geo point by Elasticsearch: `geo_distance` queries can be executed on them.

All works that have been conceived around 100km from 48 of latitude and 2 of longitude. **NB**: in this syntax, `longitude` comes before `latitude`.

1 GET work/_search 2 { 3 "query": { 4 "geo_distance": { 5 "distance": "100km", 6 "place.location": [2,48] 7 } 8 } 9 }

The same query can be formulated more explicitly with this syntax :

1 GET work/_search 2 { 3 "query": { 4 "geo_distance": { 5 "distance": "100km", 6 "place.location": { 7 "lat" : 48, 8 "lon" : 2 9 } 10 } 11 } 12 }

## F.1.7 Combining multiple clauses

Every filter you want to combine to build a query can be added with this kind of structure :

1 { 2 "query": {
<table><tr><td>3</td><td>"bool": {</td></tr><tr><td>4</td><td>"must": [</td></tr><tr><td>5</td><td>{</td></tr><tr><td>6</td><td>// filter one</td></tr><tr><td>7</td><td>,</td></tr><tr><td>8</td><td>{</td></tr><tr><td>9</td><td>// filter two</td></tr><tr><td>10</td><td>}</td></tr><tr><td>11</td><td>]</td></tr><tr><td>12</td><td>}</td></tr><tr><td>13</td><td>}</td></tr><tr><td>14</td><td>}</td></tr></table>

## Putting all together

The shelfmarks of all early printed primary sources that contains an original item that were created near Paris (lat : 48, long : 2).

```json
{
  "GET original_text/_search": {
    "_source": [
      "primary_source.shelfmark"
    ],
    "query": {
      "bool": {
        "must": [
          {
            "geo_distance": {
              "distance": "100km",
              "place.location": [2,48]
            }
          },
          {
            "match": {
              "primary_source.prim_type": "ep"
            }
          }
        ]
      }
    }
  }
}
```
# Annexe G

## Description des développements
réalisés pendant le stage

The “Segolene-front-office” branch mostly concerns the historical part of the navigation in the front office. Several modules where developped :

- Data visualisations;

- Sidebar for metadata;

- Search interface;

- Bread crumbs;

- Related table editions.

NB : the presented functions are here often simplified for demonstration purposes comparing to the way they are integrated into the code.

### G.1 Data visualisation

#### G.1.1 Visualisation description

Three different visualisations were developped for the historical navigation with the AmCharts library :

- **Column chart** : visualisation for the work record page. Each column represents a primary source divided in original items (the cells) which colors are determined by their astronomical object; the visualisation allows to show completeness and content of the sources derived from a intellectual work.
<figure><img src="image_113.png" /><figcaption>FIGURE G.1 – Column chart for work visualisation</figcaption></figure>

- Bar chart : visualisation for the primary source record page. Each bar represents a work that is contained in the primary source, each bar being divided in original items originated from the work. A select allows two switch between two states of the visualisation : one where all pages of the items are added together, one where they are disposed accordingly to their position in the source. The visualisation thus can show the composite aspect of some primary sources.

<figure><img src="image_114.png" /><figcaption>FIGURE G.2 – Bar chart for primary source visualisation : original items stacked</figcaption></figure>
<figure><img src="image_115.png" /><figcaption>FIGURE G.3 – Bar chart for primary source visualisation : original items spread out</figcaption></figure>

— **Historical map** : visualisation for the original item records, the historical navigation and more to come. The map displays points that represent the place of creation of works (in yellow), primary sources/original items (in red) and combination of both (in orange). A heatmap underneath represents the time axis and show what period were more prolific : the scrollbar allows the user to select a time period so that only the items created during the timerange are shown.

<figure><img src="image_116.png" /><figcaption>FIGURE G.4 – Map for historical navigation</figcaption></figure>
## G.1.2 Function explanation

### Historical map

This function is triggered when the user change the range selected by the scrollbar. What it does is that each time the start and the end grips of the scrollbar are both outside (by being under or above it) of the `tpq` and `tap` dates of an item, the item is not shown on the map. When the grips are not both outside, the size, color, tooltip of the map point are set accordingly to the items that were created in the timerange selected.

```javascript
scrollbarX.events.on("rangechanged", function () {
  let cursorMin = scrollbarX_range.start;
  let cursorMax = scrollbarX_range.end;

  // Conversion of the min and max range value into date
  let dateMinRange = parseInt((cursorMin / yearRange) + startBar);
  let dateMaxRange = IntegerParse((cursorMax / yearRange) + startBar);

  // Show the timerange selected
  scrollbarX.startGrip toolTipText = `${dateMinRange}`;
  scrollbarX.endGrip toolTipText = `${dateMaxRange}`;
  timeframeLabel.text = `${dateMinRange} - ${dateMaxRange}`;

  i = 0;
  // for each place in mapData
  for (let index in mapData) {
    // defining appearance of the circle localised on the place
    let place = mapData[index];
    let opacity = 0; // if no item is to be displayed, opacity to 0
    let countW = 0; // count of the number of works to be displayed : color and radius of the circle
    let countPS = 0; // count of the number of primary sources to be displayed : color and radius
    let number = 0;

    for (let j = place.items.length - 1; j >= 0; j--) {
      let dateMin = (place.items[j].from - startBar) * yearRange;
      let dateMax = (place.items[j].to - startBar) * yearRange;
      if (!((cursorMin > dateMax && cursorMax > dateMax) || (cursorMin < dateMin && cursorMax < dateMin)))
        // when the two cursors are not both outside of the time frame selected
        // either by being under or above it
      {
        number++;
        opacity = 0.8; // set the opacity in order to not be transparent
        if (place.items[j].entity === "work") {
          countW += 1; // add one to the count of works
        } else {
          countPS += 1;
        }
      }
    }
  }

  let Wtootltip = countW != 0 ? "[bold]Work [/] \ n " + countW + " record(s)" : "";
  let PStootltip = countPS != 0 ? "[bold]Primary source [/] \ n " + countPS + " record(s)" : "";
```
```javascript
let tooltip = "[font-size:18px]" + place.place + "[/]\n" + Wtootltip + PStootltip;
number = number !== 0 ? number * 100 : 100;

placeMarker[i].fillOpacity = opacity;
placeMarker[i].radius = Math.log(number);
placeMarker[i].tipText = tooltip;
i++;
}
```

## Bar chart

This function is triggered when the user selects one or another option. If the option is “page disposition”, the height and displacement of the cell are determined in relation to the number of items in the same bound as theirs. In other words, the more items there are on the same pages, the thinner and the more deported from the center will be the cell representing one item.

```javascript
function selectView(select) {
  if (select === "spread") {
    chart.data = spreadOutSet; // make the chart use the "spread out" data set
    let numberOfWorks = Object.keys(worksBounds).length;
    let heightWork = 292/ numberOfWorks; // height of the horizontal part dedicated to one work
    let heightBar = 225/ numberOfWorks; // height of the bar in itself

    for (let work of Object.keys(worksBounds)) {
      bounds = worksBounds[work];
      for (key of Object.keys bounds) {
        i = 0;
        let bound = bounds[key];
        let numberOfOrigItems = bound.origItems.length;
        for (let id of bound.origItems) {
          let heightItem = heightWork/ numberOfOrigItems;
          // setting the height of the cell
          series[id].columns.template_height = heightItem;
          // configuring the displacement of the cell comparing to the center
          if (heightItem !== heightWork) {
            series[id].columns.template.dy = -(heightBar/2) + (heightItem * i);
          }
          i++;
        }
      }
    }
  }
  else if (select === "stack") {
    chart.data = stackedSet; // make the chart use the "stacked" data set
    for (id of ids) {
      series[id].columns.template.dy = 0;
      series[id].columns.template_height = am4core.percentage(80);
    }
  }
}
```
After creating an object detailing how the different items are disposed in the primary source (`workBounds` = `"workTitle1" : [{bound : [min, max], origItems : [id1, id2]}, {bound : [min, max], origItems : [id3]}], "workTitle2" : [...]}), some items being on the same pages, each series of the chart (i.e. each cell) is individually styled according to how the items are disposed.

## G.2 Sidebar of metadata

The sidebar is a template that is integrated to the record pages of work, primary source and original item. The template is filled with an associative array filled with metadata of the record that is being displayed : this associative array is built thanks to the `getMetadataTable()` method located in each repository of the concerned entities.

<figure><img src="image_117.png" /><figcaption>FIGURE G.5 – Metadata display in the sidebar</figcaption></figure>

### G.2.1 Data structure

The data produced by the `getMetadataTable()` method is always structured the same way in order to correctly generate the sidebar using the template `sideMetadata.html twig`.

1. `$metadata = ["entity" => $entityName // index name that will be used to construct an Elastisearch query`
```json
{
    "title" => $title, // text to display in the upper part of the sidebar
    (" subtitle ") => $ subtitle), // facultative
    "field name" => ["values" => ["text to display"],
                    "search" => ["json" => ["query to send to ElasticSearch"],
                                    "hover" => "text to display when hovering the magnifier"],
                    "title" => ["title of the query"]],
    "other field" => ["values" => [["html" => "text to display", // when text must be a
                                         link
                                           "id" => "id of the entity for the link",
                                           "path" => "path name to construct link"]],
                    "search" => ["json" => [],// no magnifier when this array is empty
                                     "hover" => ""],
                    "title" => []]
};
```

Each key of the array (except for the key `entity`) corresponds to a field that is going to appear in the sidebar. The upper part of the sidebar is filled with the keys `"title"` and `" subtitle "` (not required), and for the part in the white insert, each key constitutes the text that is going to appear as field name.

To each of these keys is attached an associative array defining how the metadata related to these fields are going to be displayed. Each key referes to something specific :

- **values**: the text in `html` that is going to appear next to the field name. In the array associated to this key, can be added an array if the text is going to be a link :

- **html**: text to display

- **id**: id of the entity in order to build the link

- **path**: path of the page to redirect to

- **search**: data used for generating the magnifier (i.e. redirecting to the search page for more related items). To this key is attached an other associative array :

- **json**: query in the DSL language of ElasticSearch. Not all the query is needed, only the `query` part. The `source`, `size`, etc are generated after that.

- **hover**: text that is going to appear when hovering the magnifier, which is a description of the query

- **title**: title of the query that will appear in the result page

The keys `values`, `json` and `title` are associated to an array because some fields can have several values to display, for instance is a work has multiple creators. For example, if a primary source is written in two different scripts, the metadata associated to the "script field" will look like this :

```json
{
    ["scripts" =>
        ["values" =>
            [
                {"<span class='mainContent'>Latin</span>",
                "<span class='mainContent'>Gothic</span>
            ],
            "search" =>
```
```json
 6
 7
 8
 9
10
11
12
13
14
]
```

## String formatting

The text that is going to be displayed is formatted thanks to the `toPublicString` and `toPublicTitle` methods :

- `toPublicString` is used when the information will be displayed as metadata (i.e. in the record page of an original item, the name of the work of this item will be formatted with this method);

- `toPublicTitle` is used when the information will be displayed as main content (i.e. in the record page of a work, the name of the work will be formatted with this method).

The `getTpaq()` methods returns for each entity associated with a `tpq` and a `taq` date, a correctly formatted date, for example :

- if `tpq = 1245`, and `taq = 1325` `==>` "1245-1325"

- if `tpq = 1325`, and `taq = 1325` `==>` "1325"

## Managing missing information

If an information is missing, (for example, if the current entity doesn't have place associated with it), several layout options are available :

- `textbfNot showing the field at all`: the key for this field must not appear in the array of metadata, or the array associated to the `values` key must be lefted empty.

```php
1 // the field translator must appear only if there is one
2 if ($work->getTranslator()) {
3 $metadata["translator"] = $metadataTable;
4 $metadata["translator"]["values"][] = $work->getTranslator()->toPublicString();
5 }
```

- **Showing the field with a string indicating the missing information**: in the array associated to the `values` key, a string can be set when there is no information available for the current field. It must be encapsulated in a `<span class="noInfo">&lt;/span&gt;</span>` tag.
## G.2.2 Sidebar template

The sidebar is opened with a click on a toolbar icon, and closed when clicked outside the sidebar. The javascript allows to switch between two states that are defined in the public CSS stylesheet : when opened, the classes `open toolbar` and `open sidebar` are added to the element of the sidebar in order to appear on the page.

```javascript
1 $(document).ready(function() {
2   // open the sidebar on a toolbar item
3   $( '.AACRy' ).click(function() {
4     let id = $(this).attr('id');

5   $("# sidebar").attr("isOpen", "true");
6
7   switch Sidebar();
8
9   let sideContent = "side-" + id;
10
11   $( '.backgroundSidebar' ).hide();
12
13   $( ' #'+sideContent ).show();
14
});

// close the sidebar when clicked outside the side bar
15
16
17 $(document).click(function (e) {
18   let thatTarget = $(event.target);
19
20   // if the clicked target is not a child of sidebar AND sidebar is open
21   if (!thatTarget closest( # sidebar' ).length && $("# sidebar").attr(' "true"')
22   {
23     $("# sidebar").attr(" "false"');
24     switch Sidebar();
25   }
26 }
27 );

28
29
30
31
32
```

## G.3 Search interface

The search page serves for now two purposes :

- allowing the user to perform full-text queries, only on the entities **work**, **primary source** and **original item**,

- displaying the related items when clicking on a magnifier in the sidebar of an entity record.
The queries are performed on the Elasticsearch database through an AJAX call :
TODO when launching in production, the requested server (from `localhost` to `dis
has.obspm`) will change. The variable to be modified to make this change is located in the
`myElasticSearch.js`:

1 function generateUrl (query="", index="", from = 0, size = 10000, server="localhost:9200", http = "http") { ... }

The retrieved results from this call are then formatted to be displayed in a Table
thanks to the TAMASListTableTemplate objects. Those templated are defined with the
getPublicObjectList() in the entity repositories.

G.3.1 Data structure : TAMASListTableTemplate

The objects of the class `TAMASListTableTemplate` defines for each field (i.e. column) of an entity, how the information is going to be presented inside the ` table`. For instance, the template of a work title will defined that the text is going to be in *italic*, redirect to the page of the concerned work and that the string "Unknown title" will be displayed if the information is missing.

The getPublicObjectList() is defined as follows :

1 public function getPublicObjectList()
2 {
3 $fieldList = [
4 new TAMASListTableTemplate(
5 'name of the key where the information in the array of result will be located'
6
7 'Column title for this field',
8 ['class' => 'array of CSS classes to style the text'],
9 'path' => 'defined if a the text is a link',
10 'id' => 'name of the key where the id in the results is located'],
11 'unknown' => 'text to display if the information is missing',
12 'fields needed to display this field, correspond to the `_sources` in a
13 ElasticSearch query'
14 )];
15
16 return $fieldList;
17 }
18

Each column needs its template, each entity combining between 5 and 10 templates.
A template object can be defined with a certain number of properties :

- **Name**: provides the location in an array where ` table` will find the information to display

- **Title**: corresponds to the column label associated with the information

- **Properties**: defines how the cell content will be formatted :
- **class** (will surround the text in a `<span class="__"/></span>`):

- **list**: to indicate that multiple values can be displayed in the same cell

- **number**: in order to align the text to the right

- **title-italic**: to style the text of the cell in italic

- **path + id**:

- **path**: routing path to generate a link

- **id**: location of the id in the result object

- **Source**: defines which fields will appear in the elasticsearch response corresponding to the fields that are added to the array associated with the key "source" in the query (multiple fields can be added for a single column with "+")

```javascript
1 // Field "Work" of an original item defining how the work titles will appear
2 new TAMASListTableTemplate(
3   'work',
4   'Work',
5   ['class' => ['title-italic'], 'path' => 'tamas_astro_viewWork', 'id' => 'work.id'],
6   '', // ifOnly is not used in the public interface
7   'work.default_title+work.id'
8 )
```

### G.3.2 Specific functions

The functions and variables used to create the search interface are located in several files:

- `publicResult.html`: twig template for the result page

- `myElasticSearch.js`: functions to build queries, to retrieve data from response or generate URL

- `myTable.js`: functions related to DataTables

- `mainJavascript`: utility functions

The main functions help:

- to retrieve results from ElasticSearch

```javascript
1 /**
2 * This function takes a response from an Ajax call to elasticsearch
3 * and returns an array containing all the results of this query
4 *
5 * @param queryResponse: object
6 * @return {Array}
7 */
8 function retrieveResults.queryResponse() {
9   if (typeof queryResponse.hits.hits != 'undefined') {
```
```javascript
let data = queryResponse.hits.hits; // data is an array of results, but only the value of the key "_source" is needed
let results = [];

$.each(data, function (key, value) {
  results.push(value._source);
});

return results;
}
```

— to format those results (using the properties defined in the TAMASListTableTemplate)

```javascript
1 /**
2 * to either return the information associated with a field
3 * or return a tag indicating missing information
4 * The properties will defined how the cell content is formatted.
5 *
6 * @param text : result values to display inside an array (even if there is only 1 value)
7 * @param properties : object defined in the template object list (getPublicObjectList)
8 * @param result : object containing the results send by Elasticsearch
9 * @returns string
10 */
11 function textDisplay (text, properties=[], result={}) {
12 let classes = "";
13 if (isDefined propertie s.class)) { // putting all classes in the same string
14 for (let i = 0; i < properties.class.length; i++) {
15 let classname = properties.class[i];
16 classes = classes + classname;
17 classes = i < properties.class.length ? classes + " " : "";
18 }
19 }
20
21 if (isDefined(text)) {
22 if (isDefined propertie s.path)) {
23 let id = [selectNodeOfObject (properties.id, result)];
24 // selectNodeOfObject will select the id in the result if there is only one id to
find,
25 // unlike when the cell is supposed to contain a list
26 if (isDefined (properties.class) && properties.class.include s("list")) {
27 // if the cell is supposed to contain a list of links
28 // the "text" array looks like : ["text, id, "text", id, ...]
29 let texts = [];
30 id = [];
31 for (let j = 0; j < text.length; j += 2) {
32 texts.push(text[j]);
33 id.push(text[j+1]);
34 }
35 text = texts; // now it looks like ["text", "text", ...]
36 }
37 let linkText = [];
38 for (i = 0; i < text.length; i++) {
39 linkText.push (<a href="${generateRoute (properties.path, id[i])}">${text[i]}<
a>");
```
```javascript
}

text = linkText;
}

let cellContent = "";
let cellSummary = "";
for (i = 0; i < text.length; i++) {
    if (i === 0) {
        cellContent = classes !== "" ? '<span class="${classes}"><${text[i]}></span>' : '<${text[i]}>';
    } else {
        cellSummary = cellSummary + '<span class="${classes}"><${text[i]}></span>';
        cellSummary = i < text.length ? cellSummary + "<br/" : "";
    }
}

if (text.length > 1) { // if there is multiple data to display, put it in a summary
    let Nrecord = text.length > 2 ? "s" : "";
    let summary = '<summary class="mainContent">
        ${text.length-1} <span style="font-variant: small-caps">&gt;more record${Nrecord}</span>
        <span style="font-size: 10px">&gt;</span>
        &lt;/summary&gt;
    </summary>';
    cellContent = '<${cellContent}&lt;details&gt;${summary}${cellSummary}&lt;/details&gt>';
}

return cellContent;
} else { // if the key doesn't exist in the array of results => missing information
    if (isDefined propertie s .unknown)) {
        return '<span class='noInfo'>${properties .unknown}</span>';
    }
    return "<span class='noInfo'>No information provided</span>";
}

}
```

— to display those results in a ** table

```javascript
1 /**
2 * This function generates an entire Datatable of results retrieved from a query to elasticsearch
3 * on the given index for the filters given as parameter query
4 *
5 * it generates by default a query of a size 10000, from 0
6 *
7 * @param index string : label of an entity (ex : "primary_source")
8 * @param query object : the filters of the query (ex: {"match"{"id":"5"}})
9 * => the value associated with the key "query" in the query language of elasticsearch
10 * @param queryTitle string : title detailing the query in natural language (EX => "All original items kept in the British Library")
11 * @param queryTerm string : terms used to filter the results
12 * @param from int : the number of results from which the query starts
13 * @param size int : number of results wanted in the response
14 * @param generateHeader bool : defines if the header is generated or not
15 * @return url : url of the query
16 */
17 function generateResultTable (index, query, queryTitle="", queryTerm="", from=0, size=10000,
    generateHeader=true) {
```