From 50ff5d1146a5b9d095eb80be1022413c9c0a2b05 Mon Sep 17 00:00:00 2001
From: David Dorchies <david.dorchies@inrae.fr>
Date: Wed, 2 Apr 2025 13:54:07 +0200
Subject: [PATCH] docs: add Get started with hydrological indicators

Refs #3
---
 DESCRIPTION               |  4 +++
 vignettes/.gitignore      |  2 ++
 vignettes/seinebasin3.Rmd | 76 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 82 insertions(+)
 create mode 100644 vignettes/.gitignore
 create mode 100644 vignettes/seinebasin3.Rmd

diff --git a/DESCRIPTION b/DESCRIPTION
index 2da2ad5..2daafbf 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -20,3 +20,7 @@ Depends:
     airGRccia
 remotes:
     git::https://forgemia.inra.fr/airgriwrm/airgrccia.git
+Suggests: 
+    knitr,
+    rmarkdown
+VignetteBuilder: knitr
diff --git a/vignettes/.gitignore b/vignettes/.gitignore
new file mode 100644
index 0000000..097b241
--- /dev/null
+++ b/vignettes/.gitignore
@@ -0,0 +1,2 @@
+*.html
+*.R
diff --git a/vignettes/seinebasin3.Rmd b/vignettes/seinebasin3.Rmd
new file mode 100644
index 0000000..720a6a7
--- /dev/null
+++ b/vignettes/seinebasin3.Rmd
@@ -0,0 +1,76 @@
+---
+title: "seinebasin3"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{seinebasin3}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+```{r setup}
+library(tidyverse)
+library(seinebasin3)
+```
+
+Cette vignette est un exemple d'utilisation du package *seinebasin3* pour le
+calcul des indicateurs hydrologiques sur les débits naturalisés modélisés par
+le modèle seinebasin2.
+
+## Chargement des données
+
+Les données de référence sont directement téléchargées depuis la base de données
+IN-WOP à partir d'un lien de téléchargement public
+
+```{r}
+#| out.width = "100%"
+# Définition du lien de téléchargement du fichier
+url <-
+  "https://nextcloud.inrae.fr/s/adinzGa3AmLEXnZ/download?path=%2F03-naturalised_flows%2Fv2.0%2Fhistorical%2Fdata&files=ts_Qsim.tsv"
+# Chargement direct du tableau en mémoire
+Qsim <- readr::read_tsv(url)
+# Affichage des premières lignes du tableau
+head(Qsim)
+```
+
+Réduisons le nombre de stations étudiées en ne sélectionnant que les colonnes 
+qui nous intéressent:
+
+```{r}
+Qsim <- Qsim[, c("DatesR", "H5920010", "H4340010")]
+```
+
+On peut alors visualiser les chroniques de débit simulées sur les stations:
+
+```{r}
+#| out.width = "100%"
+# Plot du débit sur une sélection de stations
+TSstudio::ts_plot(Qsim[, c("DatesR", "H5920010", "H4340010")], slider = TRUE)
+```
+
+## Calcul des indicateurs
+
+Le package *seinebasin3* charge automatiquement les fonctions du package *airGRccia*
+qui contient les fonctions de calcul des indicateurs hydrologiques.
+
+La documentation de ces fonctions est disponible [sur le site de documentation du
+package *airGRccia*](https://airgriwrm.pages.mia.inra.fr/airgrccia/reference).
+Le nom de ces fonctions ont le préfixe `calc` (exemple: `calcQMNA5`).
+
+La fonction `calcQindicators` permet de calculer directement une série 
+d'indicateurs hydrologiques:
+
+```{r}
+# Calcul des indicateurs hydrologiques
+# Le colonne des dates doit être au format POSIXct ou POSIXlt
+Qsim$DatesR <- as.POSIXct(Qsim$DatesR)
+indicators <- calcQindicators(Qsim)
+indicators
+```
+
-- 
GitLab