From 87c1aa9178f90577f9a6fb347861c1bababe38cd Mon Sep 17 00:00:00 2001
From: David Dorchies <david.dorchies@inrae.fr>
Date: Wed, 2 Apr 2025 12:08:19 +0200
Subject: [PATCH] docs(README): add example of getDataPath usage
Refs #3
---
README.Rmd | 124 +++++++++++++++++++++++++++++
README.md | 226 ++++++++++++++++++++++++++++++++++++-----------------
2 files changed, 279 insertions(+), 71 deletions(-)
create mode 100644 README.Rmd
diff --git a/README.Rmd b/README.Rmd
new file mode 100644
index 0000000..f347c47
--- /dev/null
+++ b/README.Rmd
@@ -0,0 +1,124 @@
+---
+output: github_document
+---
+
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+ collapse = TRUE,
+ comment = "#>",
+ fig.path = "man/figures/README-",
+ out.width = "100%"
+)
+```
+
+# seinebasin3
+
+<!-- badges: start -->
+<!-- badges: end -->
+
+# seinebasin3
+
+Ce package R contient le code source du modèle SeineBasin3 et ses analyses.
+
+Le modèle seinebasin3 est réalisée par Artelia et Inrae dans le cadre de l'étude
+commandité par l'EPTB Seine Grands Lacs intitulée "Constitution d’une hydrologie
+de référence sur le bassin amont de la Seine".
+
+## Clonage et installation du package pour le développement
+
+### Prérequis
+
+Avoir *GIT* installé sur votre ordinateur.
+
+### Clonage du dépôt GIT
+
+Vous devez être un utilisateur connu de
+[https://forgemia.inra.fr/](https://forgemia.inra.fr/) et être membre du projet
+[seinbasin3](https://forgemia.inra.fr/sgl-hydro-ref/seinebasin3) ou de son
+groupe.
+Commencez par [créer un jeton d'accès personnel (PAT)](https://mycloudjourney.
+medium.com/gitlab-tokens-194c803de73f) avec des permissions de lecture et
+d'écriture sur le dépôt (`read_repository` et `write_repository`) dans *Gitlab*.
+
+- Dans la console *git bash*, tapez :
+
+```bash
+git clone https://<votre-nom-utilisateur>:<votre-pat>@forgemia.inra.fr/sgl-hydro-ref/seinebasin3.git
+```
+
+> Cela clonera le dépôt dans le dossier courant (par défaut, dans votre dossier
+personnel).
+> Vous pourrez déplacer ce dossier où vous le souhaitez après sa création.
+
+### Installation du package et ses dépendances
+
+- Ouvrez le fichier projet `seinebasin3.Rproj` avec Rstudio.
+- Installez les dépendances du package *seinebasin3* avec ce script :
+
+```r
+source("dev/update_packages.R")
+```
+
+- Installez le package lui-même
+
+> Cela peut être fait en cliquant sur le bouton "Installer" situé dans
+> 'onglet "Build" de Rstudio.
+> Mais cela peut aussi être fait en tapant :
+
+```r
+# install.packages("devtools") # Si pas déjà installé
+devtools::install()
+```
+
+### Utilisation du package
+
+Pour charger les fonctions du package dans l'environnement R, taper:
+
+```r
+library(seinbasin3)
+```
+
+Pour afficher la page de documentation du package dans l'aide de Rstudio:
+
+```r
+help(package = "seinebasin3")
+```
+
+## Utilisation des données partagées sur OneDrive
+
+### Configuration du dossier synchronisé localement
+
+Les données de travail se trouvent dans un dossier OneDrive partagé qui doit être
+synchronisé localement.
+Le chemin vers ce dossier de données est défini dans le fichier `config.yml` à la racine du
+package selon l'exemple suivant :
+
+```yml
+default:
+ data:
+ mode: local
+ local: C:/Mes Documents/OneDrive/ARTELIA/Hydrologie Seine amont - 0_Données
+ write_results: false
+```
+
+Le chemin du dossier `local:` doit être adapté à l'emplacement de votre dossier
+de données et les antislashs `\` doivent être remplacés par des slashs `/`.
+
+### Accès aux données OneDrive dans le code
+
+La fonction `getDataPath()` permet de récupérer le chemin du dossier de données.
+Voici un exemple de lecture des données AquiFR:
+
+```{r}
+# Chargement de la librairie seinebasin3
+library(seinebasin3)
+# Récupération du chemin local des données
+path_AquiFR <- getDataPath("2_BaseDeDonneesQnat_PIREN_et_Aqui-FR/Aqui-FR-Qnat_1852_2008_Seine.csv")
+path_AquiFR
+
+# Lecture des données au format CSV
+tsAquiFR <- readr::read_delim(path_AquiFR, delim = ";")
+head(tsAquiFR)
+```
diff --git a/README.md b/README.md
index d9fdbf8..a870dc0 100644
--- a/README.md
+++ b/README.md
@@ -1,71 +1,155 @@
-# seinebasin3
-
-Ce package R contient le code source du modèle SeineBasin3 et ses analyses.
-
-Le modèle seinebasin3 est réalisée par Artelia et Inrae dans le cadre de l'étude
-commandité par l'EPTB Seine Grands Lacs intitulée "Constitution d’une hydrologie
-de référence sur le bassin amont de la Seine".
-
-## Clonage et installation du package pour le développement
-
-### Prérequis
-
-Avoir *GIT* installé sur votre ordinateur.
-
-### Clonage du dépôt GIT
-
-Vous devez être un utilisateur connu de
-[https://forgemia.inra.fr/](https://forgemia.inra.fr/) et être membre du projet
-[seinbasin3](https://forgemia.inra.fr/sgl-hydro-ref/seinebasin3) ou de son
-groupe.
-Commencez par [créer un jeton d'accès personnel (PAT)](https://mycloudjourney.
-medium.com/gitlab-tokens-194c803de73f) avec des permissions de lecture et
-d'écriture sur le dépôt (`read_repository` et `write_repository`) dans *Gitlab*.
-
-- Dans la console *git bash*, tapez :
-
-```bash
-git clone https://<votre-nom-utilisateur>:<votre-pat>@forgemia.inra.fr/sgl-hydro-ref/seinebasin3.git
-```
-
-> Cela clonera le dépôt dans le dossier courant (par défaut, dans votre dossier
-personnel).
-> Vous pourrez déplacer ce dossier où vous le souhaitez après sa création.
-
-### Installation du package et ses dépendances
-
-- Ouvrez le fichier projet `seinebasin3.Rproj` avec Rstudio.
-- Installez les dépendances du package *seinebasin3* avec ce script :
-
-```r
-source("dev/update_packages.R")
-```
-
-- Installez le package lui-même
-
-> Cela peut être fait en cliquant sur le bouton "Installer" situé dans
-> 'onglet "Build" de Rstudio.
-> Mais cela peut aussi être fait en tapant :
-
-```r
-# install.packages("devtools") # Si pas déjà installé
-devtools::install()
-```
-
-## Configuration du dossier de données
-
-Les données de travail se trouvent dans un dossier OneDrive partagé qui doit être
-synchronisé localement.
-Le chemin vers ce dossier de données est défini dans le fichier `config.yml` à la racine du
-package selon l'exemple suivant :
-
-```yml
-default:
- data:
- mode: local
- local: C:/Mes Documents/OneDrive/ARTELIA/Hydrologie Seine amont - 0_Données
- write_results: false
-```
-
-Le chemin du dossier `local:` doit être adapté à l'emplacement de votre dossier
-de données et les antislashs `\` doivent être remplacés par des slashs `/`.
+
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+
+# seinebasin3
+
+<!-- badges: start -->
+<!-- badges: end -->
+
+# seinebasin3
+
+Ce package R contient le code source du modèle SeineBasin3 et ses
+analyses.
+
+Le modèle seinebasin3 est réalisée par Artelia et Inrae dans le cadre de
+l’étude commandité par l’EPTB Seine Grands Lacs intitulée “Constitution
+d’une hydrologie de référence sur le bassin amont de la Seineâ€.
+
+## Clonage et installation du package pour le développement
+
+### Prérequis
+
+Avoir *GIT* installé sur votre ordinateur.
+
+### Clonage du dépôt GIT
+
+Vous devez être un utilisateur connu de <https://forgemia.inra.fr/> et
+être membre du projet
+[seinbasin3](https://forgemia.inra.fr/sgl-hydro-ref/seinebasin3) ou de
+son groupe. Commencez par [créer un jeton d’accès personnel
+(PAT)](https://mycloudjourney.%20medium.com/gitlab-tokens-194c803de73f)
+avec des permissions de lecture et d’écriture sur le dépôt
+(`read_repository` et `write_repository`) dans *Gitlab*.
+
+- Dans la console *git bash*, tapez :
+
+``` bash
+git clone https://<votre-nom-utilisateur>:<votre-pat>@forgemia.inra.fr/sgl-hydro-ref/seinebasin3.git
+```
+
+> Cela clonera le dépôt dans le dossier courant (par défaut, dans votre
+> dossier personnel). Vous pourrez déplacer ce dossier où vous le
+> souhaitez après sa création.
+
+### Installation du package et ses dépendances
+
+- Ouvrez le fichier projet `seinebasin3.Rproj` avec Rstudio.
+- Installez les dépendances du package *seinebasin3* avec ce script :
+
+``` r
+source("dev/update_packages.R")
+```
+
+- Installez le package lui-même
+
+> Cela peut être fait en cliquant sur le bouton “Installer†situé dans
+> ’onglet “Build†de Rstudio. Mais cela peut aussi être fait en tapant :
+
+``` r
+# install.packages("devtools") # Si pas déjà installé
+devtools::install()
+```
+
+### Utilisation du package
+
+Pour charger les fonctions du package dans l’environnement R, taper:
+
+``` r
+library(seinbasin3)
+```
+
+Pour afficher la page de documentation du package dans l’aide de
+Rstudio:
+
+``` r
+help(package = "seinebasin3")
+```
+
+## Utilisation des données partagées sur OneDrive
+
+### Configuration du dossier synchronisé localement
+
+Les données de travail se trouvent dans un dossier OneDrive partagé qui
+doit être synchronisé localement. Le chemin vers ce dossier de données
+est défini dans le fichier `config.yml` à la racine du package selon
+l’exemple suivant :
+
+``` yml
+default:
+ data:
+ mode: local
+ local: C:/Mes Documents/OneDrive/ARTELIA/Hydrologie Seine amont - 0_Données
+ write_results: false
+```
+
+Le chemin du dossier `local:` doit être adapté à l’emplacement de votre
+dossier de données et les antislashs `\` doivent être remplacés par des
+slashs `/`.
+
+### Accès aux données OneDrive dans le code
+
+La fonction `getDataPath()` permet de récupérer le chemin du dossier de
+données. Voici un exemple de lecture des données AquiFR:
+
+``` r
+# Chargement de la librairie seinebasin3
+library(seinebasin3)
+#> Le chargement a nécessité le package : airGRccia
+#> Le chargement a nécessité le package : airGRiwrm
+#> Le chargement a nécessité le package : airGR
+#> Warning: le package 'airGR' a été compilé avec la version R 4.4.0
+#>
+#> Attachement du package : 'airGRiwrm'
+#> Les objets suivants sont masqués depuis 'package:airGR':
+#>
+#> Calibration, CreateCalibOptions, CreateInputsCrit,
+#> CreateInputsModel, CreateRunOptions, RunModel
+#>
+#> Attachement du package : 'seinebasin3'
+#> Les objets suivants sont masqués depuis 'package:airGRccia':
+#>
+#> getDataPath, loadConfig
+# Récupération du chemin local des données
+path_AquiFR <- getDataPath("2_BaseDeDonneesQnat_PIREN_et_Aqui-FR/Aqui-FR-Qnat_1852_2008_Seine.csv")
+#> Read user configuration from: C:/DocDD/Inrae/2025 Artelia BDD Hydro EPTB SGL/04-src/seinebasin3/config_seinebasin3.yml
+path_AquiFR
+#> [1] "C:/DocDD/OneDrive/ARTELIA/Hydrologie Seine amont - 0_Données/2_BaseDeDonneesQnat_PIREN_et_Aqui-FR/Aqui-FR-Qnat_1852_2008_Seine.csv"
+
+# Lecture des données au format CSV
+tsAquiFR <- readr::read_delim(path_AquiFR, delim = ";")
+#> Rows: 57342 Columns: 36
+#> ── Column specification ────────────────────────────────────────────────────────
+#> Delimiter: ";"
+#> dbl (35): H0100010, H0100020, H0321030, H0400010, H0400020, H1051020, H1122...
+#> date (1): date
+#>
+#> ℹ Use `spec()` to retrieve the full column specification for this data.
+#> ℹ Specify the column types or set `show_col_types = FALSE` to quiet this message.
+head(tsAquiFR)
+#> # A tibble: 6 × 36
+#> date H0100010 H0100020 H0321030 H0400010 H0400020 H1051020 H1122020
+#> <date> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl>
+#> 1 1852-01-01 1.54 1.16 1.42 3.96 3.58 1.71 1.99
+#> 2 1852-01-02 1.73 1.76 1.49 7.16 7.2 2.94 2.13
+#> 3 1852-01-03 1.87 2.93 2.21 7.77 7.66 3.03 2.4
+#> 4 1852-01-04 1.57 3.07 2.36 8.99 9.1 3.06 1.95
+#> 5 1852-01-05 1.25 2.81 1.76 7.89 8.15 2.44 1.57
+#> 6 1852-01-06 1.09 2.25 1.34 6.63 6.87 2.14 1.6
+#> # ℹ 28 more variables: H1201010 <dbl>, H1231010 <dbl>, H1501010 <dbl>,
+#> # H1700010 <dbl>, H1940020 <dbl>, H2051021 <dbl>, H2081020 <dbl>,
+#> # H2182010 <dbl>, H2501040 <dbl>, H2622010 <dbl>, H3621010 <dbl>,
+#> # H3930020 <dbl>, H4042010 <dbl>, H4332030 <dbl>, H4340020 <dbl>,
+#> # H5011020 <dbl>, H5031020 <dbl>, H5071010 <dbl>, H5071040 <dbl>,
+#> # H5071050 <dbl>, H5083050 <dbl>, H5172010 <dbl>, H5321010 <dbl>,
+#> # H5752040 <dbl>, H5841025 <dbl>, H5841070 <dbl>, H5920010 <dbl>, …
+```
--
GitLab