diff --git a/index.html b/index.html index 712fe12..6775e9f 100644 --- a/index.html +++ b/index.html @@ -3531,6 +3531,7 @@

Écriture des fonc @@ -3578,33 +3579,44 @@

Écriture des fonc -

Nous allons modifier notre fonction pour avoir le choix entre plusieurs fichiers à télécharger (par exemple la richesse spécifique des oiseaux OU celle des mammifères). Nous pouvons ajouter un paramètre à notre fonction. Le paramètre devra être renseigné à l’utilisation et sa valeur sera observée par le code de la fonction pour choisir quel fichier télécharger :

+

Nous allons éxecuter notre fonction. Il faut d’abord la rendre disponible à l’utilisation.

+

pour cela il suffit de sélectioner sa définition et de la charger dans la console ctrl + entrée.

+

Observez votre environnement, la fonction apparaît.

+

pour éxecuter la fonction il suffit de l’appeler dans la console :

-
download_sr <- function(taxon) {
-  
-  ## File name ----
-  if (taxon == "bird") filename <- "bird_SR_cells.csv"
-  if (taxon == "mamm") filename <- "mamm_SR_cells.csv"
-  
-  ## GitHub directory URL ----
-  url <- "https://raw.githubusercontent.com/pwilliams0/Biogeography_and_global_diversity/refs/heads/main/Data/"
-
-  ## Complete file url ----
-  file_url <- paste0(url, filename)
-  
-  ## Destination ---- 
-  dest_dir  <- "data"
-  dest_path <- file.path(dest_dir, filename)
-  
-  
-  ## Download file ----
-  utils::download.file(url      = file_url,
-                       destfile = dest_path,
-                       mode     = "wb")
-  
-  return(dest_path)
-  
-}
+
dl_bird_sr()
+
+

Plutôt que de créer une deuxième fonction pour les mammifères nous allons modifier notre fonction pour avoir le choix entre plusieurs fichiers à télécharger (par exemple la richesse spécifique des oiseaux OU celle des mammifères).

+

Nous pouvons ajouter un paramètre à notre fonction. Le paramètre devra être renseigné à l’utilisation et sa valeur sera observée par le code de la fonction pour choisir quel fichier télécharger :

+
+
download_sr <- function(taxon) {
+  
+  ## Inform about the data being dowloaded
+  message("# ---- Downloading data for taxon: ", taxon)
+  
+  ## File name ----
+  if (taxon == "bird") filename <- "bird_SR_cells.csv"
+  if (taxon == "mamm") filename <- "mamm_SR_cells.csv"
+  
+  ## GitHub directory URL ----
+  url <- "https://raw.githubusercontent.com/pwilliams0/Biogeography_and_global_diversity/refs/heads/main/Data/"
+
+  ## Complete file url ----
+  file_url <- paste0(url, filename)
+  
+  ## Destination ---- 
+  dest_dir  <- "data"
+  dest_path <- file.path(dest_dir, filename)
+  
+  
+  ## Download file ----
+  utils::download.file(url      = file_url,
+                       destfile = dest_path,
+                       mode     = "wb")
+  
+  return(dest_path)
+  
+}
@@ -3620,12 +3632,17 @@

Écriture des fonc

  • Le nom de la fonction à changé …

  • On utilise if () pour observer la valeur de taxon renseignée par l’utilisateur.

  • On utilise == pour tester l’égalité de 2 valeurs (!=, <, <=, >, >= pour les autres comapraisons)

    • -

  • On devra obligatoirement renseigner une valeur pour taxon lors de l’utilisation de la fonction. Sinon elle ne saura pas quel fichier télécharger : download_rs(taxon = "bird") ou download_rs(taxon = "mamm").

    • +

  • On devra obligatoirement renseigner une valeur pour taxon lors de l’utilisation de la fonction. Sinon elle ne saura pas quel fichier télécharger : download_sr(taxon = "bird") ou download_sr(taxon = "mamm").

  • Si on ne renseigne pas de valeur pour taxon ou si on reseigne une valeur différente de "bird" ou "mamm", alors la fonction échoue et renvoit un message d’erreur. C’est une bonne chose !

    • -

    Nous allons utliser notre fonction plus tard, patience …

    +

    Nous allons utiliser cette fonction plus tard, patience. En attendant nettoyons notre environnement car la bonne pratique est de charger les fonctions via un autre mécanisme que nous verrons plus tard.

    +
    +
    rm(dl_bird_sr)
+
+rm(download_sr)
    +
    @@ -3649,19 +3666,19 @@

    Documentation

    Pour ajouter une entête roxygen2 à une fonction existente utlisez le menu Code > Insert Roxygen Skeleton.

    Proposition de documentation (explorez)

    -
    #' Download Species Richness Data from Williams et al. 2024
-#'
-#' @param taxon (bird, mamm) the taxon for which data are downloaded
-#' 
-#' @return the path to the downloaded file
-#' @export
-#'
-download_sr <- function(taxon) { ... }
    +
    #' Download Species Richness Data from Williams et al. 2024
+#'
+#' @param taxon (bird, mamm) the taxon for which data are downloaded
+#' 
+#' @return the path to the downloaded file
+#' @export
+#'
+download_sr <- function(taxon) { ... }

    Optionnel : transpilez vos entêtes roxygen2 en fichiers .Rd, seuls fichiers acceptés par pour documenter des fonctions. Ces fichiers .Rd seront stockés dans le dossier man/.

    -
    ## Génération de la doc ----
-devtools::document()
    +
    ## Génération de la doc ----
+devtools::document()

    L’aide de votre fonction est maintenant accessible via ?nom_fonction.

    @@ -3682,14 +3699,14 @@

    Documentation

    Ajout des dépendances

    Nos fonctions contiennent une dépendance à un package externe : utils. Nous devons ajouter cette dépendance au fichier DESCRIPTION. Pour cela, nous allons utiliser la fonction usethis::use_package().

    -
    ## Ajout de dépendances ----
-usethis::use_package("utils")
    +
    ## Ajout de dépendances ----
+usethis::use_package("utils")

    Regardez le contenu du fichier DESCRIPTION. Par défaut, les packages requis sont listés sous le tag Imports. Ainsi, pour utiliser une fonction externe, il faudra l’appeler par package::fonction().

    Si vous remplacer le tag Imports par Depends (?usethis::use_package()), l’utilisation de la fonction devtools::load_all() (voir plus bas) aura le même effet qu’un library() et vous pourrez utiliser une fonction externe par fonction(). C’est pratique pour les packages comme ggplot2 qui demande de nombreux appels à leurs fonctions pour réaliser une tâche.

    -
    ## Ajout de dépendances ----
-usethis::use_package("ggplot2", type = "Depends")
    +
    ## Ajout de dépendances ----
+usethis::use_package("ggplot2", type = "Depends")
    @@ -3721,11 +3738,11 @@

    Chargement du projet<

    Après chaque modification d’une fonction , n’oubliez pas d’exécuter la fonction devtools::load_all().

    Essayez ces deux fonctions.

    -
    ## Installation des packages manquants ----
-devtools::install_deps()
-
-## Chargement des packages et fonctions R ----
-devtools::load_all()
    +
    ## Installation des packages manquants ----
+devtools::install_deps()
+
+## Chargement des packages et fonctions R ----
+devtools::load_all()
    @@ -3746,31 +3763,31 @@

    Appel aux fonctionsJusqu’à présent, nous n’avons fait que définir des fonctions , mais nous ne les avons pas exécutées. Nous allons créer notre premier script dans le dossier analyses/. Celui-ci aura pour objectif d’appeler les fonctions définies précédemment pour télécharger les données.

    Créez un nouveau script comme suit et éditez-le:

    -
    ## Ajout d'un script R ----
-utils::file.edit("analyses/download-data.R")
    +
    ## Ajout d'un script R ----
+utils::file.edit("analyses/download-data.R")

    Proposition de contenu

    -
    # Download project raw data
-#
-# This script will download bird and mammal species richness data and the global grid
-# from Williams et al. 2024. The files will be stored in `data/`.
-# 
-# All functions used in the script have been developed for this project
-# and can be found in the folder R/.
-#
-# Jane Doe <jane.doe@mail.me>
-
-## Download SR data ----
-
-### birds
-download_sr("bird")
-
-### mammals
-download_sr("mamm")
-
-## Download the global grid ----
-dl_grid_cells()
    +
    # Download project raw data
+#
+# This script will download bird and mammal species richness data and the global grid
+# from Williams et al. 2024. The files will be stored in `data/`.
+# 
+# All functions used in the script have been developed for this project
+# and can be found in the folder R/.
+#
+# Jane Doe <jane.doe@mail.me>
+
+## Download SR data ----
+
+### birds
+download_sr("bird")
+
+### mammals
+download_sr("mamm")
+
+## Download the global grid ----
+dl_grid_cells()
    @@ -3778,26 +3795,26 @@

    Ajout d’un make.R

    Afin d’automatiser notre projet, nous allons créer un script à la racine du projet. Nous l’appelerons, par convention, make.R. Celui-ci aura deux objectifs : 1) mettre en place le projet et 2) exécuter le projet. L’idée est de n’exécuter que ce script.

    Créez un fichier make.R à la racine du projet, placez-y une entête informative (le nom du compendium, le nom du fichier, votre email). Placez-y aussi les appels à devtools::install_deps() pour installer les dépendences et devtools::load_all() pour charger les fonctions que vous avez écrites.

    -
    ## Ajout du make ----
-utils::file.edit("make.R")
    +
    ## Ajout du make ----
+utils::file.edit("make.R")

    Contenu du make.R :

    -
    ############################################################
-# Basic Compendium
-# francois.guilhaumon@ird.fr
-# make.R
-############################################################
-
-# create directories ----
-reps <- c("data", "analyses", "R", "outputs", "references")
-lapply(reps, dir.create, showWarnings = FALSE)
-
-# install the project dependencies listed in DESCRIPTION ----
-devtools::install_deps()
-
-# load the project functions ----
-devtools::load_all()
    +
    ############################################################
+# Basic Compendium
+# francois.guilhaumon@ird.fr
+# make.R
+############################################################
+
+# create directories ----
+reps <- c("data", "analyses", "R", "outputs", "references")
+lapply(reps, dir.create, showWarnings = FALSE)
+
+# install the project dependencies listed in DESCRIPTION ----
+devtools::install_deps()
+
+# load the project functions ----
+devtools::load_all()
    @@ -3814,20 +3831,20 @@

    Ajout d’un make.R

    Finalement, ajoutez une ligne dans le fichier make.R qui permettra d’exécuter le script analyses/download-data.R. Utilisez la fonction source() pour cela.

    -
    ############################################################
-# Basic Compendium
-# francois.guilhaumon@ird.fr
-# make.R
-############################################################
-
-# install the project dependencies listed in DESCRIPTION ----
-devtools::install_deps()
-
-# load the project functions ----
-devtools::load_all()
-
-# download the project data ----
-source("analyses/download-data.R")
    +
    ############################################################
+# Basic Compendium
+# francois.guilhaumon@ird.fr
+# make.R
+############################################################
+
+# install the project dependencies listed in DESCRIPTION ----
+devtools::install_deps()
+
+# load the project functions ----
+devtools::load_all()
+
+# download the project data ----
+source("analyses/download-data.R")

    Pour charger le projet et lancer les analyses, il suffit d’exécuter ce fichier make.R.

    @@ -3849,8 +3866,8 @@

    Ajout d’un README

    Un jour, sûrement, vous verrez comment envoyer ce projet sur GitHub. Pour l’instant, nous allons légèrement anticiper et ajouter un README à notre compendium. Ce sera la vitrine du projet. Les rôles d’un README sont : 1) de présenter le projet, 2) d’expliquer son contenu, et 3) d’expliquer comment l’installer et l’utiliser.

    Pour cela, vous allez ajouter un README.md (fichier Markdown) à la racine de votre projet.

    -
    ## Ajout d'un README ----
-utils::file.edit("README.md")
    +
    ## Ajout d'un README ----
+utils::file.edit("README.md")
    
 # Basic Compendium
diff --git a/index.qmd b/index.qmd
index b779d55..5fe1936 100644
--- a/index.qmd
+++ b/index.qmd
@@ -309,7 +309,9 @@ utils::download.file(url      = source_url,
 
 - Ici nous déclarons le nom du fichier une seule fois et nous nous en servons pour créer l'url de la source des données `source_url` puis le chemin de destination du téléchargement `dest_path`.
 
-- Notez l'utilisation de `paste0()` pour l'url et de `file.path` pour le chemin. 
+- Notez l'utilisation de `paste0()` pour l'url et de `file.path` pour le chemin.
+
+- Notez les commentaires et les indentations pour faciliter la lecture du code.
 
 :::
 
@@ -356,7 +358,25 @@ dl_bird_sr <- function() {
 
 :::
 
-Nous allons modifier notre fonction pour avoir le choix entre plusieurs fichiers à télécharger (par exemple la richesse spécifique des oiseaux OU celle des mammifères). Nous pouvons ajouter un *paramètre* à notre fonction. Le paramètre devra être renseigné à l'utilisation et sa valeur sera observée par le code de la fonction pour choisir quel fichier télécharger :
+Nous allons éxecuter notre fonction. Il faut d'abord la rendre disponible à l'utilisation.
+
+{{< fa hand-point-right >}} pour cela il suffit de sélectioner sa définition et de la charger dans la console `ctrl + entrée`.
+
+{{< fa hand-point-right >}} Observez votre environnement, la fonction apparaît.
+
+pour éxecuter la fonction il suffit de l'appeler dans la console :
+
+```{r}
+#| echo: true
+#| eval: false
+
+dl_bird_sr()
+
+```
+
+Plutôt que de créer une deuxième fonction pour les mammifères nous allons modifier notre fonction pour avoir le choix entre plusieurs fichiers à télécharger (par exemple la richesse spécifique des oiseaux OU celle des mammifères).
+
+{{< fa bulb >}} Nous pouvons ajouter un *paramètre* à notre fonction. Le paramètre devra être renseigné à l'utilisation et sa valeur sera observée par le code de la fonction pour choisir quel fichier télécharger :
 
 
 ```{r}
@@ -365,6 +385,9 @@ Nous allons modifier notre fonction pour avoir le choix entre plusieurs fichiers
 
 download_sr <- function(taxon) {
   
+  ## Inform about the data being dowloaded
+  message("# ---- Downloading data for taxon: ", taxon)
+  
   ## File name ----
   if (taxon == "bird") filename <- "bird_SR_cells.csv"
   if (taxon == "mamm") filename <- "mamm_SR_cells.csv"
@@ -398,15 +421,25 @@ download_sr <- function(taxon) {
 
 - On utilise `==` pour tester l'égalité de 2 valeurs (`!=`, `<`, `<=`, `>`, `>=` pour les autres comapraisons)
 
-- On devra obligatoirement renseigner une valeur pour `taxon` lors de l'utilisation de la fonction. Sinon elle ne saura pas quel fichier télécharger : `download_rs(taxon = "bird")` ou `download_rs(taxon = "mamm")`.
+- On devra obligatoirement renseigner une valeur pour `taxon` lors de l'utilisation de la fonction. Sinon elle ne saura pas quel fichier télécharger : `download_sr(taxon = "bird")` ou `download_sr(taxon = "mamm")`.
 
 - Si on ne renseigne pas de valeur pour `taxon` ou si on reseigne une valeur différente de `"bird"` ou `"mamm"`, alors la fonction échoue et renvoit un message d'erreur. C'est une bonne chose !
 
 :::
 
-Nous allons utliser notre fonction plus tard, patience ...
+Nous allons utiliser cette fonction plus tard, patience. En attendant nettoyons notre environnement car la bonne pratique est de charger les fonctions via un autre mécanisme que nous verrons plus tard.
 
 
+```{r}
+#| echo: true
+#| eval: false
+
+rm(dl_bird_sr)
+
+rm(download_sr)
+
+```
+
 ::: {.callout-tip}
 ## Bonne pratique