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

MINISTÈRE
DE LA TRANSITION
ÉCOLOGIQUE
ET DE LA COHÉSION
DES TERRITOIRES

Liberté
Égalité
Fraternité

INRAE
la science pour la vie, l'humain, la terre

Programme MTECT (DGPR/SRNH) – INRAE 2023

Connaissance et prévention des risques naturels et hydrauliques

Ces travaux bénéficient du soutien du ministère chargé de la transition écologique et de la cohésion des territoires par décision attributive de subvention n° 210400292.

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

Action 2 - Prévision des inondations

HYDROM A2 : Analyse des détarages morphodynamiques

Auteur : Felipe MENDEZ-RIOS, Benjamin RENARD, Jérôme LE COZ, Michel LANG (INRAE, décembre 2023)

<figure><img src="image_3.png" /></figure>
# Table des matières

<table><tr><td>1. Introduction</td><td>1</td></tr><tr><td>2. Synthèse</td><td>1</td></tr><tr><td>3. Stations hydrométriques à courbes de tarage instables</td><td>2</td></tr><tr><td>3.1. État des lieux</td><td>2</td></tr><tr><td>3.2. Évolutions de l'outil de segmentation</td><td>2</td></tr><tr><td>3.2.1. Diagnostic de BayDERS version Matteo</td><td>2</td></tr><tr><td>3.2.2. Simplification du code BayDERS</td><td>3</td></tr><tr><td>3.2.3. Développement du package R : Rating Shift Happens</td><td>7</td></tr><tr><td>4. Conclusions</td><td>7</td></tr><tr><td>5. Perspectives</td><td>8</td></tr><tr><td>6. Références</td><td>8</td></tr><tr><td>7. Annexes</td><td>9</td></tr><tr><td>7.1. Présentation fichier Readme du package R</td><td>9</td></tr></table>

<figure><img src="image_4.png" /></figure>
# 1. Introduction

L'objectif de l'action est de poursuivre l'opérationnalisation des méthodes développées (BayDERS) lors de la thèse de Matteo DARIENZO (2021) pour la détection et l'estimation automatique des détarages provenant de processus morphodynamiques.

Cette action se concentre sur la gestion des stations hydrométriques à courbes de tarage en estimant les incertitudes liées non seulement aux paramètres de la courbe, mais aussi aux débits qu'elles permettent de calculer. La courbe de tarage est recalculée chaque fois qu'un détarage est détecté. C'est pourquoi une incertitude est également associée non seulement à l'instabilité du fond du lit, mais aussi au moment du détarage. Ces détarages peuvent être causés par les crues ou d'autres évènements générant des changements soudains des contrôles hydrauliques et notamment des propriétés géométriques de la section.

BayDERS propose une étude rétrospective de la station pour la détection effective de changements de la relation hauteur-débit, en utilisant deux types différents de méthodes basés sur les jaugeages et les récessions. Une dernière méthode applicable en temps réel est proposée pour la détection potentielle de détarages via l'analyse du transport des sédiments.

# 2. Synthèse

Suite aux essais de transfert opérationnel de 2022, les travaux de l'année 2023 se concentrent sur la refonte et la simplification de la méthode de segmentation à partir du cœur de calcul utilisant le package RBaM (RBaM package) qui sert d'assistance d'écriture des fichiers de configuration de BaM! au lieu d'essayer d'apporter des changements directement au code de BayDERS en raison de sa complexité.

Ainsi, il a été nécessaire de comprendre les différentes parties du code afin de repérer les fonctions fondamentales qui permettent d'effectuer la segmentation. Dans un premier temps, un simple recodage, en prenant comme base le code de BayDERS, a été fait pour séparer les différents types de segmentation. Ensuite, un exercice de détection de détarage d'une variable aléatoire a été proposé pour évaluer la capacité de l'outil de segmentation de base (Répertoire: Shifts_time_detection). Une fois validée l'extraction des fonctions fondamentales, elles ont été intégrées sous forme de package sous R (en cours de développement *Package : Rating Shift Happens version 0.1.0*) avec leur documentation correspondante, afin de bien expliquer l'objectif de chaque fonction, les variables utilisées, et de fournir au moins un exemple d'utilisation. A présent, trois fonctions sont disponibles: *segmentation engine*, *segmentation* et *recursive segmentation*.

Dans la même optique de transfert opérationnel, l'outil a été communiqué avec des partenaires (dont CNR, EDF), pour son utilisation et la coopération en vue de son développement. Ces travaux collaboratifs permettent d'évaluer la performance de l'outil lors de sa mise en pratique sur d'autres cas de test, tels que la Loire à Gien.

De plus, la version beta 3.0 de BaRatinAGE est en cours de test, avec certaines améliorations notables, notamment en ce qui concerne l'importation de jaugeages et de limnigrammes, ainsi que du côté de l'interface graphique. L'objectif principal de cette nouvelle version était le remplacement du moteur de calcul baratin.exe par bam.exe, ouvrant ainsi la possibilité d'intégrer à terme d'autres modèles disponibles tels que BayDERS et SPD.

1. Bilan 2023 sur BayDERS et RSH :

- Mise en évidence de la complexité du code actuel du BayDERS. Néanmoins, certaines corrections, suggestions et améliorations supplémentaires ont été implémentés pour la stabilisation du code

- Partielle séparation du code développé et maintenu par Matteo Darienzo

- Séparation de deux outils différents: BaRatin-SPD et BayDERS

- Développement en cours du package pour la segmentation d'une variable aléatoire. Résultats prometteurs étant donné la simplification de la méthode, ainsi que la fixation de certains paramètres sur la version officielle de BayDERS.

- Segmentation binaire ou à trois segments maximum par itération afin d'identifier le maximum de détarages, sans risque de sur segmentation.

- Critère de segmentation fixée à *Deviance Information Criterion* (DIC), car il est le plus adapté à la méthode bayésienne

<figure><img src="image_5.png" /></figure>
- Remplacement du moteur de calcul baratin.exe par bam.exe

- Communication de la méthode pour la transmission de l'information aux unités d'hydrométrie d'EDF et CNR pour informer sur les outils à disposition, ainsi que son utilisation en vue de recevoir des retours ou des avis opérationnels, contribuant ainsi à clarifier l'objectif de cette action

- Extraction des fonctions fondamentales pour la segmentation d'une variable aléatoire quelconque

- Utilisation du package RBaM pour faciliter l'écriture des fichiers de configuration

- Dans l'objectif de rendre l'outil opérationnel, le développement d'un package semble être une bonne solution en vue de sa diffusion ultérieure en lien avec BaRatinAGE 3.0.

## 2. Perspectives 2024 :

- Finalisation de la segmentation récursive des jaugeages avec actualisation de la courbe de tarage de référence (qui sert à calculer les résidus). Assimilation de modèle BaRatin lors de la segmentation

- Ajout de la segmentation récursive des hauteurs asymptotiques des récessions

- Couplage de l'analyse du résidu et de la hauteur asymptotique proposée dans BayDERS à notre outil de segmentation

- Préfiguration de l'intégration dans ou du couplage avec BaRatinAGE 3.0

- Evaluation d'un possible lien avec Jacinthe

- Création d'un document RMarkDown ou des vignettes pour l'explication et la prise en main du code

- Elargissement du transfert méthode et outils auprès des unités d'hydrométrie et coopération pour son développement : appel à volontaires via GDH

- Projet InterReg Alpine Space (soumis) sur transfert BaRatin et AutoSalt sur stations alpines avec détarages fréquents (avec DREAL PACA)

# 3. Stations hydrométriques à courbes de tarage instables

## 3.1. État des lieux

Au cours de l'année 2022, plusieurs cas d'étude ont été testés tels que : Le Sonnant au pont de Venon (collaboration avec Christophe ROUSSEAU, IGE), La Loire à Goudet, La Dunières à Sainte-Sigolène-Vaubarlet, Le Chapeauroux à Saint-Bonnet-de-Montauroux, L'Allier à Prades (collaboration avec David BESSON et Gautier CORDEAU de la DREAL Centre-Val de Loire), La Garonne à Lamagistère (collaboration avec Michel LANG, INRAE, la DREAL et EDF). Tous ces travaux ont permis de mener une étude de sensibilité des paramètres pour les différents types de segmentation proposés dans la thèse de Matteo Darienzo (2021) et l'outil BayDERS. Cela a conduit à la définition par défaut de certains paramètres des méthodes. Néanmoins, les conclusions ont montré qu'en raison de la complexité du code, il était préférable de travailler sur une nouvelle version beaucoup plus opérationnelle.

La thèse de Matteo Darienzo [3] propose trois types de segmentation basés sur les résidus des jaugeages à la courbe de tarage, les hauteurs asymptotiques des récessions et le transport solide. Ainsi, l'idée est de poursuivre le développement du nouvel outil en s'appuyant sur ces trois propositions.

## 3.2. Évolutions de l'outil de segmentation

### 3.2.1. Diagnostic de BayDERS version Matteo

Une branche secondaire (Branche de développement) a été créée sur le dépôt GitHub de BayDERS pour les développements respectifs énumérés ci-dessus. Ils ont également été obtenus grâce aux retours et collaborations des partenaires d'EDF quant à leur utilisation, ainsi que des échanges avec Matteo Darienzo :

- Adaptation des exécutables pour n'en avoir qu'un seul, actuellement uniquement disponible pour Linux. Plusieurs exécutables sont encore nécessaires pour lancer l'outil sur les ordinateurs sous Windows

- Adoption du critère de segmentation à adopter au DIC, étant donné que c'est l'indicateur formalisé dans le cadre de l'inférence bayésienne et aucun test ne prouve qu'un des critères est plus performant que les autres

- Recommandation de réaliser une segmentation binaire ou d'opter pour un maximum de trois segments lors du processus de segmentation récursive. Cette mesure permet non seulement de réduire le temps de calcul, mais aussi de stabiliser la segmentation.

- Amélioration du processus d'extraction des récessions en se focalisant principalement sur la fin qui décrira la

<figure><img src="image_6.png" /></figure>
hauteur asymptotique

- La date de détarage est sélectionnée à partir de la distribution de la fonction de densité probabilité (pdf). Deux options sont disponibles, en fonction du pic de hauteur du limnigramme le plus élevée compris dans la pdf ou maximisant la pdf (pic le plus élevé). Néanmoins, il est nécessaire de réfléchir sur un critère permettant d'écarter les détarages liés à des pdf trop plates

- Recommandation de la mise en place d'une étude multivariée lors de la combinaison des résultats obtenus après les deux types segmentations (jaugeages et récession).

- Remarques formulées concernant l'utilisation de BayDERS dans le cadre d'analyse des crues millénales (Ticket BaM!)

- Conseil sur la gestion d'erreurs pour mieux comprendre les éventuels messages d'erreur

### 3.2.2. Simplification du code BayDERS

La dissociation des fonctions fondamentales nécessite une étude approfondie des modules. Pour ce faire, un exercice a été proposé (Figure 1), consistant à générer artificiellement douze jeux de données d'observations d'une variable aléatoire quelconque dans le temps. Chaque jeu de données synthétique est généré à partir d'une distribution normale à différents sauts (connus) de la moyenne de la variable aléatoire, ainsi que de l'écart-type. On connaît donc les distributions sous-jacents qui permettront de critiquer et juger l'outil. L'objectif était de développer un code de segmentation de base, sans encore intégrer la notion de courbe de tarage ou de récession pour évaluer la performance de la méthode.

<figure><img src="image_7.png" /><figcaption>Figure 1. Jeux de données synthétique avec leurs barres d'erreur de l'exercice de segmentation</figcaption></figure>

Dans ce rapport, les points les plus importants sont énumérés ci-dessous :

- Configuration de BaM :

- Utilisation de certaines fonctions du package RBaM :

- mcmcOptions : définition du nombre de cycles, d'adaptations et d'autres paramètres de la méthode

- mcmcCooking : précision du pourcentage de brûlage et d'affinage après estimation

- remnantErrorModel : définition de l'erreur structurelle, ainsi que ses paramètres

- parameter : définition des propriétés de l'information a priori des paramètres, notamment la distribution avec leurs paramètres, ainsi que le point de départ

- dataset : Regroupement dans un fichier l'information des observations avec leurs incertitudes

- xtraModellInfo : création d'un fichier supplémentaire afin de l'adapter au modèle souhaité

- model : sélection du modèle utilisé dans le catalogue de RBaM, ainsi que leurs propriétés, en l'occurrence, le modèle de segmentation

- BaM : fonction qui permet de lancer l'exécutable BaM.exe après avoir réglé tous les autres
fichiers de configuration. Si un argument n'est pas défini lors du paramétrage, la fonction prendra la configuration proposée par défaut

o Distribution a priori des paramètres : FlatPrior+ (non informative)

o Brûlage : 50% des résultats a posteriori

o Affinage : 10 (prendre 1 donnée toutes les 10)

o Distribution a priori de l'erreur structurelle : uniforme (0,100)

- Paramètres pour la segmentation :

o Critère de segmentation utilisé : DIC

o Segmentation : binaire

o Méthode de segmentation : maximum a posteriori (MAP)

o Nombre minimum d'observations pour segmenter : 1

o Temps minimal entre deux segmentations : 0

- Résultats :

o Segmentation récursive de l'observation de la variable aléatoire quelconque

o Estimation de la valeur la plus probable de la moyenne de la variable aléatoire pour chaque groupe homogène, ainsi que de son incertitude

o Estimation de la valeur la plus probable du temps de rupture entre deux groupes homogènes, ainsi que son incertitude

Pour cet exercice, une segmentation manuelle a été réalisée lu aveugle (Figure 2), permettant de mettre en évidence les avantages et inconvénients d'un outil automatisé en terme de temps de développement, précision et exactitude. La segmentation finale de l'outil s'affiche dans la

<figure><img src="image_8.png" /><figcaption>Figure 2. Segmentation manuelle par Jérôme Le Coz</figcaption></figure>
<figure><img src="image_9.png" /><figcaption>Figure 3. Segmentation par le code simplifié</figcaption></figure>

<figure><img src="image_10.png" /><figcaption>Figure 4. Vraie segmentation du jeu de données</figcaption></figure>

Un tableau récapitulatif est proposé ci-après :

<table><thead><tr><td>Data set</td><td>Segmentation manuelle</td><td>Segmentation automatique</td><td>Segmentation réelle</td><td>Détection des dates de détarages</td><td>Explications / Commentaires</td></tr></thead><tbody><tr><td>1</td><td>0</td><td>0</td><td>0</td><td>Excellent détection</td><td>Excellent performance</td></tr><tr><td>2</td><td>1</td><td>1</td><td>1</td><td>Excellent détection</td><td>Excellent performance</td></tr><tr><td>3</td><td>3</td><td>3</td><td>5</td><td>Bonne détection. Même résultats pour les deux types de segmentation proposées (manuelle,</td><td>Petit saut dans la moyenne de la variable aléatoire, rendant le détarage difficile à détecter. Néanmoins, si on regarde la</td></tr></tbody></table>
<table><caption>Tableau 1. Nombre de ruptures par type de segmentation avec une analyse sur les dates de détarages estimées et certaines explications ou commentaires sur la performance de la méthode</caption><thead><tr><th>Data set</th><th>Segmentation manuelle</th><th>Segmentation automatique</th><th>Segmentation réelle</th><th>Détection des dates de détarages</th><th>Explications / Commentaires</th></tr></thead><tbody><tr><td></td><td></td><td></td><td></td><td>automatique). Pas de détection du premier détarage (deux premières données). Pas de détection du 5ème période (segmentation réelle)</td><td>bande rouge (segmentation automatique), elle indique qu'il y a une incertitude dans l'estimation qui peut cacher un détarage potentiel ou jugé non trop important</td></tr><tr><td>4</td><td>4</td><td>5</td><td>9</td><td>La différence entre les segmentation proposées est la détection du premier détarage, qui n'est pas facile à détecter à l'œil nu</td><td>Le premier saut n'est pas facile à détecter, mais l'outil est capable de le détecter avec une forte incertitude quant à la date exacte du détarage. Les détarages non détectés s'expliquent par le faible saut de la moyenne</td></tr><tr><td>5</td><td>0</td><td>0</td><td>0</td><td>Excellent détection</td><td>Excellent performance</td></tr><tr><td>6</td><td>1</td><td>1</td><td>1</td><td>Excellent détection</td><td>Excellent performance</td></tr><tr><td>7</td><td>5</td><td>6</td><td>5</td><td>Excellent détection, mais la segmentation automatique propose un détarage supplémentaire (6ème période). Détarage clairs et facile à repérer</td><td>Très bonne performance de l'outil, mais dans le paramétrage de base, une rupture ne peut être détectée qu'avec une seule observation. Cela peut expliquer la détection d'un segment de plus que prévu, mais cela peut être facilement réglé dans le paramétrage de l'outil</td></tr><tr><td>8</td><td>4</td><td>5</td><td>10</td><td>Détection très variable. La segmentation manuelle n'a pas détecté les 4 premiers détarages, tandis que l'outil les a tous détectés. Cependant, à partir de ce moment, aucun détarage supplémentaire n'a été détecté, bien qu'il en existe 3 de plus</td><td>Très bonne performance de la première partie, détection presque parfaite. En revanche, la dernière partie n'est pas très performante, mais cela peut s'expliquer par la segmentation binaire utilisée pour ce cas. En effet, la pdf est susceptible d'être bimodale</td></tr><tr><td>9</td><td>0</td><td>0</td><td>0</td><td>Excellent détection</td><td>Excellent performance</td></tr><tr><td>10</td><td>1</td><td>1</td><td>1</td><td>Excellent détection</td><td>Excellent performance</td></tr><tr><td>11</td><td>4</td><td>5</td><td>5</td><td>Excellent détection</td><td>Excellent performance. L'outil a détecté tous les détarages, améliorant ainsi la proposition de détection de la segmentation manuelle. Toutefois, il faut aussi remarquer que les dates de détarages sont très incertaines</td></tr><tr><td>12</td><td>6</td><td>7</td><td>10</td><td>Bonne détection, saut pour les détarages avant environ t=6.</td><td>Premier détarage réel est presque impossible à détecter. Ensuite, l'outil détecte assez bien la plupart de détarages, avec quelques erreurs</td></tr></tbody></table>

En résumé, le code développé permet de segmenter des observations d'une variable quelconque avec une information a
priori peu informative, tout en aboutissant à des segmentations performantes. Les temps de calcul sont acceptables, de l'ordre de 8 secondes par itération, ce qui donne environ 1 minute et 40 secondes pour le cas avec le plus grand nombre de segments estimés. Néanmoins, certaines pistes d'amélioration ont été identifiées pour la suite comme le nombre minimum de données dans un segment, cela permet d'éviter de sur-segmentation. De plus, il est important d'évaluer une segmentation binaire et une segmentation à 3 segments, car la distribution sous-jacente peut être bimodale. Autrement dit, il est assez probable deux dates de détarages au lieu de prendre seulement une et faire le calcul puisque l'estimation sera différente.

Par ailleurs, il est important de trouver une méthode généralisable pour le choix des a priori sur les distributions non seulement des paramètres comme le temps de détarage et le résidu (horizontale noire Figure 3), mais aussi de l'erreur structurelle, ou simplement de les fixer à une distribution non informative et de les gérer à travers d'autres paramètres propre à la segmentation, tels que le nombre minimal des données lors d'une segmentation.

### 3.2.3. Développement du package R : Rating Shift Happens

Suite à la simplification du code, il est nécessaire d'extraire et d'écrire les fonctions fondamentales du processus de segmentation dans un format de package R pour une utilisation ultérieure. Afin de documenter les développements effectués au fil du temps, les résultats sont présentés sous format RMarkDown. Ces dernières contiennent les descriptions des arguments des fonctions disponibles, ainsi qu'un ou plusieurs exemples illustrant leur utilisation. Le package R est ouvert, de libre accès, documenté et disponible sur GitHub : https://github.com/Felipemendezrios/RatingShiftHappens.

<figure><img src="image_11.png" /><figcaption>Figure 5. Segmentation d'une variable aléatoire utilisant le package Rating Shift Happens</figcaption></figure>

## 4. Conclusions

Grâces aux échanges avec Matteo Darienzo et des partenaires, certaines améliorations ont été effectuées au code de BayDERS dans le but de la stabilisation du code. Par exemple, la gestion de message d'erreur selon l'état de l'art, mise en question de la limitation à deux ou trois segments par itération et justification de l'utilisation du DIC comme critère référent lors de la segmentation. Un point important à remarquer est la séparation de BaRatin-SPD de BayDERS, car ces sont deux approches complémentaires, mais BayDERS n'est pas complétement stable et BaRatin-SPD n'est pas généralisable. C'est pourquoi il faut attaquer le problème séparément.

Etant donné que la plupart de temps a été consacré au développement d'un nouvel outil, un seul cas test a été étudié à la Loire, Gien au vieux pont. Ce travail a été réalisé par Guillaume Bodart et Thomas Morlot (DTG-EDF) en collaboration avec Michel Lang et Felipe Mendez-Rios (INRAE).

Développement en cours du package en R qui permet d'avoir un suivi des fonctions fondamentales utilisées lors de la segmentation proposée par Matteo Darienzo. En effet, la procédure de segmentation se résume à trois fonctions, décrivant si le nombre de segments est connu, inconnu ou s'il s'agit d'une segmentation récursive.

À ce stade, la détection, la visualisation et l'estimation de ruptures entre des groupes homogènes, ainsi que de leurs incertitudes sont disponibles. Une documentation détaillée est également fournie pour expliquer chacune des fonctions ainsi que leur syntaxe. De plus, au moins un exemple est proposé afin d'aider l'utilisateur à mieux comprendre l'utilisation du package (annexes 7.1). En résumé, l'objectif principal de cette année a été atteint, avec une méthode simplifiée pour la segmentation automatique d'une variable aléatoire qui donne de résultats performants.
# 5. Perspectives

En 2024, l'objectif principal est l'intégration de la segmentation des jaugeages avec une mise à jour de la courbe de tarage de référence, fondamentale pour le calcul des résidus, lors du processus de la segmentation récursive. Cette démarche correspond à la segmentation par jaugeages proposée par BayDERS.

De plus, il est accordé une importance à la segmentation récursive des hauteurs asymptotiques des récessions, conformément à une autre méthode dans BayDERS, se basant exclusivement sur le limnigramme. Tous ces travaux viendront accompagnés par leur documentation respective pour faciliter la compréhension et la manipulation du code.

Il est aussi envisagé de préfigurer l'intégration ou le couplage de l'outil avec BaRatinAGE 3.0, dans le but de le rendre opérationnel. BaRatinAGE est déjà utilisé dans certaines unités d'hydrométrie. Dans cette même perspective, il est aussi possible de réfléchir d'un possible lien avec Jacinthe.

Par ailleurs, on poursuit des collaborations avec des partenaires pour obtenir des retours d'expérience et de répondre aux besoins opérationnels.

# 6. Références

[1] Benjamin, R. (2017). BaM! (Bayesian Modeling): Un code de calcul pour l'estimation d'un modèle quelconque et son utilisation en prédiction. irstea, pp.90. hal-02606929

[2] Benjamin, R., Le Coz, J., Blanquart, B., Bonnifait, L., (2015). Statistiques avancées pour le calcul d'incertitudes en hydrologie. Applications à la prédétermination et à l'hydrométrie. France, pp.116. hal-02602443

[3] Darienzo, M. (2021). Detection and estimation of stage-discharge rating shifts for retrospective and real-time streamflow quantification. Hydrology. Université Grenoble Alpes, 2021. English. NNT:2021GRALU006 tel-03211343f

[4] Darienzo, M. (2021). Gestion en temps réel des stations hydrométriques à courbes de tarage instables (Action HYDROM A2-INRAE 2021). Rapport technique convencion SCHAPI/INRAE, 75 pages.

[5] Lang, M. Le Coz, J., Mendez-Rios, F. (2022). Expertise sur l'évaluation du débit de crue millenal sur la Garonne à Lamagistère. Phase 1: critique de données de débit de crue. Rapport technique SCHAPI/EDF/INRAE, 74 pages, novembre.

[6] Mansanarez, V. (2016). Non-unique stage-discharge relations: Bayesian analysis of complex rating curves and their uncertainties. PhD Thesis, Grenoble Alps University.

[7] Wickham, H. Bryan, J (2023). R Packages. Organize, test, document, and share your code. Second edition. O'Reilly Media, Inc. Online version. ISBN: 9781098134945

[8] Yihui, X. Allaire, J.J. Grolemund, G. R Markdown: The Definitive Guide. 15 may 2023.
# 7. Annexes

## 7.1. Présentation fichier Readme du package R

### Rating Shift Happens

### Documentation

Felipe MENDEZ and Benjamin RENARD (INRAE, RiverLy and RECOVER).

December 2023

### 1. Introduction

The goal of RatingShiftHappens package is to create a tools package for detecting, visualizing and estimating rating shifts. This package was derived from BayDERS developed by Darienzo in 2021.

This documentation provides the description of several functions available to the segmentation process.

Three fundamental functions are available so far:

1. segmentation.engine

2. segmentation

3. recursive.segmentation

### 2. Installation

You can install the development version of RatingShiftHappens from GitHub using the following command. Please note that the RBaM package is also required to run this package.

```R
# Before first use, install Rating Shift Happens and RBaM packages one
s and for all, following these commands:
```

```R
# devtools::install_github("Felipemendezrios/RatingShiftHappens")
```

```R
# devtools::install_github('BaM-tools/RBaM')
```

```R
library(RatingShiftHappens)
```

Functions will be explained more precisely below along with an example.

### Segmentation procedure for a **known** given number of segments

This basic example demonstrates the segmentation of annual maximum stages (H, m) for the Rhone River at Beaucaire, France, along with the associated uncertainties expressed as standard deviations (uH), divided into two groups. More information about the data set, please refer to the documentation available in ?RhoneRiver.

```R
# Run segmentation engine function at two segments
res=segmentation.engine(obs=RhoneRiver$H, time=RhoneRiver$Year, u=RhoneRiver$uH, nS=2)
```
## Data information

```
knitr::kable(head(res$summary,
align = 'c',row.names = F)
```

<table><thead><tr><th>time</th><th>obs</th><th>u</th><th>I95_lower</th><th>I95_upper</th><th>period</th></tr></thead><tbody><tr><td>1816</td><td>5.69</td><td>0.4500</td><td>4.808016</td><td>6.571984</td><td>1</td></tr><tr><td>1817</td><td>4.56</td><td>0.4075</td><td>3.761315</td><td>5.358685</td><td>1</td></tr><tr><td>1818</td><td>4.72</td><td>0.4300</td><td>3.877216</td><td>5.562785</td><td>1</td></tr><tr><td>1819</td><td>5.08</td><td>0.4125</td><td>4.271515</td><td>5.888485</td><td>1</td></tr><tr><td>1820</td><td>5.12</td><td>0.4925</td><td>4.154718</td><td>6.085282</td><td>1</td></tr><tr><td>1821</td><td>5.40</td><td>0.3900</td><td>4.635614</td><td>6.164386</td><td>1</td></tr></tbody></table>

## Shift information

```
knitr::kable(head(res$summary$shift),
align = 'c',row.names = F)
```

<table><thead><tr><th>tau</th><th>I95_lower</th><th>I95_upper</th></tr></thead><tbody><tr><td>1969.12</td><td>1967.09</td><td>1971.35</td></tr></tbody></table>

## Plot segmentation

```
plotSegmentation(res$summary)
```

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

For more advanced details :

MCMC sampling demonstrate all combinations of parameters estimated.

```
knitr::kable(head(res$mcmc),align = 'c')
```

<table><thead><tr><th>mu1</th><th>mu2</th><th>tau1</th><th>structural_sd</th><th>LogPost</th></tr></thead><tbody><tr><td>5.20155</td><td>7.83626</td><td>1967.03</td><td>1.07363</td><td>-309.191</td></tr></tbody></table>
<table><thead><tr><th>mu1</th><th>mu2</th><th>tau1</th><th>structural_sd</th><th>LogPost</th></tr></thead><tbody><tr><td>5.33280</td><td>7.87847</td><td>1970.18</td><td>1.10196</td><td>-307.813</td></tr><tr><td>5.33280</td><td>7.82841</td><td>1970.42</td><td>1.00044</td><td>-309.262</td></tr><tr><td>5.34227</td><td>8.03573</td><td>1967.69</td><td>1.09610</td><td>-309.200</td></tr><tr><td>5.52388</td><td>7.24338</td><td>1967.76</td><td>1.14877</td><td>-314.065</td></tr><tr><td>5.24600</td><td>7.32321</td><td>1969.19</td><td>1.14107</td><td>-311.731</td></tr></tbody></table>

A few functions are provided with the RBaM package to explore MCMC samples.

```
# Trace plot for each parameter, useful to assess convergence.
plots=RBaM::tracePlot(res$mcmc)
gridExtra::grid.arrange(grobs=plots, ncol=3)
```

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

```
# Density plot for each parameter
plots=RBaM::densityPlot(res$mcmc)
gridExtra::grid.arrange(grobs=plots, ncol=3)
```

<figure><img src="image_14.png" /></figure>
In this example, the focus will be on exploring the uncertainty associated with the first shift time.

```r
Shift=data.frame(time res$mcmc$tau1)
ggplot2::ggplot(Shift, ggplot2::aes(x=time))+
  ggplot2::geom_histogram(ggplot2::aes(y=density..), col=1, fill='white', bins=80)+
  ggplot2::labs(title='Histogram with density of first shift')+
  ggplot2::themeBW()+
  ggplot2::theme plot.title = ggplot2::element_text(hjust = 0.5))+
  ggplot2::geom_density(col=4, lwd=1, fill=4, alpha=0.25)
```

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

## Segmentation procedure for an *unknown* number of segments

This is a basic example, which shows you how to segment the same dataset with an *unknown* number of segments:

```r
# Run segmentation engine function at two segments
res=segmentation(obs=RhoneRiver$H, time=RhoneRiver$Year, u=RhoneRiver$uH, nSmax=3)

# Get Lower DIC value and optimal number of segments (to define optimal solution)
DIC.df = data.frame(nS=c(1:3), DIC=c(res$results[[1]]$DIC, res$results[[2]]$DIC, res$results[[3]]$DIC))
nSopt

ggplot2::ggplot(DIC.df, ggplot2::aes(x=nS, y=DIC, col=factor(nS)))+
  ggplot2::geom_point(size=3, show.legend = F)+
  ggplot2::geom_segment(ggplot2::aes(x=nSopt, y=min(DIC)*1.03, xend=nSopt, yend=min(DIC)*1.005),
    arrow=ggplot2::arrow(length=ggplot2::unit(0.5, 'cm'))),
```
```r
ggplot2::themeBW()
```

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

### Data information

```r
knitr::kable(head(res$results[[nSopt]]$summaryquo, align = 'c', row.names = F))
```

| time | obs | u | l95_lower | l95_upper | period |
|---|---|---|---|---|---|
| 1816 | 5.69 | 0.4500 | 4.808016 | 6.571984 | 1 |
| 1817 | 4.56 | 0.4075 | 3.761315 | 5.358685 | 1 |
| 1818 | 4.72 | 0.4300 | 3.877216 | 5.562785 | 1 |
| 1819 | 5.08 | 0.4125 | 4.271515 | 5.888485 | 1 |
| 1820 | 5.12 | 0.4925 | 4.154718 | 6.085282 | 1 |
| 1821 | 5.40 | 0.3900 | 4.635614 | 6.164386 | 1 |

### Shift information

```r
knitr::kable(head(res$results[[nSopt]]$summaryshift, align = 'c', row.names = F))
```

| tau | l95_lower | l95_upper |
|---|---|---|
| 1969.12 | 1967.09 | 1971.35 |

### Plot segmentation

```r
plotSegmentation(res$summary)
```
<figure><img src="image_17.png" /></figure>

Recursive segmentation procedure for an **unknown** number of segments

This is a basic example, which shows you how to segment the data set with an **unknown** number of segments using a recursive process:

```r
# Apply recursive segmentation
results=recursive-segmentation(obs=RhoneRiver$H, time=RhoneRiver$Year,
                           u=RhoneRiver$uH, nSmax=3)
```

```r
# Data information
knitr::kable(head(results$summary氧),
align = 'c', row.names = F)
```

<table><thead><tr><th>time</th><th>obs</th><th>u</th><th>I95_lower</th><th>I95_upper</th><th>period</th></tr></thead><tbody><tr><td>1816</td><td>5.69</td><td>0.4500</td><td>4.808016</td><td>6.571984</td><td>1</td></tr><tr><td>1817</td><td>4.56</td><td>0.4075</td><td>3.761315</td><td>5.358685</td><td>1</td></tr><tr><td>1818</td><td>4.72</td><td>0.4300</td><td>3.877216</td><td>5.562785</td><td>1</td></tr><tr><td>1819</td><td>5.08</td><td>0.4125</td><td>4.271515</td><td>5.888485</td><td>1</td></tr><tr><td>1820</td><td>5.12</td><td>0.4925</td><td>4.154718</td><td>6.085282</td><td>1</td></tr><tr><td>1821</td><td>5.40</td><td>0.3900</td><td>4.635614</td><td>6.164386</td><td>1</td></tr></tbody></table>

```r
# Shift information
knitr::kable(head(results$summaryshift),
align = 'c', row.names = F)
```

<table><thead><tr><th>tau</th><th>I95_lower</th><th>I95_upper</th></tr></thead><tbody><tr><td>1969.12</td><td>1967.09</td><td>1971.35</td></tr></tbody></table>
# Have a look at recursion tree

results$tree

#> indx level parent nS

#> 1 1 1 0 2

#> 2 2 2 1 1

#> 3 3 2 1 1

# Visualize tree structure

plotTree(results$tree)

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

# Plot segmentation

plotSegmentation(summary=results$summary)

<figure><img src="image_19.png" /></figure>
<figure><img src="image_20.png" /></figure>

Centre siège Antony-Paris
Direction de l'Appui aux Politiques Publiques
1, rue Pierre-Gilles de Gennes
CS 10030
92761 Antony Cedex
Tél. : +33 (0)1 40 96 61 21

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

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

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

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

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

Rejoignez-nous sur :

www.inrae.fr

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

MINISTÈRE
DE LA TRANSITION
ÉCOLOGIQUE
ET DE LA COHÉSION
DES TERRITOIRES

Liberté
Égalité
Fraternité

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

RÉPUBLIQUE
FRANÇAISE

Liberté
Égalité
Fraternité

INRAE