ci: debug R CMD check

Refs #6

.Rbuildignore

 ^griwrm\.Rproj$
 ^\.Rproj\.user$
 ^LICENSE\.md$
+\.gitlab-ci\.yml

.gitignore

@@ -4,6 +4,7 @@
 
 # Man pages generated by Roxygen
 man/*.Rd
+/.vscode/
 
 ###############################################################################
 
@@ -52,3 +53,4 @@ vignettes/*.pdf
 # pkgdown site
 docs/
 
+inst/doc

.gitlab-ci.yml

@@ -2,7 +2,7 @@ default:
   tags: [docker]
   image: r-base:latest
   before_script:
-    - Rscript -e 'install.packages("remotes")'
+    - Rscript -e 'install.packages("remotes", "dplyr")'
     - Rscript -e 'remotes::install_gitlab("HYCAR-Hydro/airgr@sd", host = "gitlab.irstea.fr")'
     - R CMD build ../griwrm
 

DESCRIPTION

@@ -8,7 +8,7 @@ Authors@R:
            email = "david.dorchies@inrae.fr",
            comment = c(ORCID = "0000-0002-6595-7984"))
 Description: This R package aims to model water basin with a airGR based semi-distributive hydrology with the integration of human infrastructures and their management.
-License: LGPL (>= 2.1)
+License: AGPL-3
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)
@@ -16,8 +16,11 @@ RoxygenNote: 7.1.0
 Imports:
     dplyr,
     utils,
-    airGR (>= 1.6.1.11)
-Suggests: 
+    airGR (>= 1.6.1.11),
+    methods
+Suggests:
     knitr,
-    rmarkdown
+    rmarkdown,
+    lattice
 VignetteBuilder: knitr
+URL: https://gitlab.irstea.fr/in-wop/griwrm

R/CreateInputsModel.Griwrm.R

 #' Create InputsModel object for a GRIWRM network
 #'
-#' @param ginet
-#' @param girop
-#' @param gits
+#' @param x Ginet object describing the diagram of the semi-distributed model, see \code{[Ginet]}.
+#' @param girop Girop object giving the run-off model parameters, see \code{[Girop]}.
+#' @param gits Gits object giving the observation time series, see \code{[Gits]}.
+#' @param ... further arguments passed to \code{\link[airGR]{CreateInputsModel}}.
 #'
-#' @return
+#' @return GriwrmInputsModel object equivalent to airGR InputsModel object for a semi-distributed model (See \code{\link[airGR]{CreateInputsModel}})
 #' @export
-#'
-#' @examples
-CreateInputsModel.Griwrm <- function(ginet, girop, gits, verbose = TRUE) {
+CreateInputsModel.Griwrm <- function(x, girop, gits, ...) {
 
   InputsModel <- CreateEmptyGriwrmInputsModel()
 
-  for(id in getNodeRanking(ginet)) {
+  for(id in getNodeRanking(x)) {
     if(verbose) cat("CreateInputsModel.griwrm: Treating sub-basin", id, "...\n")
-    InputsModel[[id]] <- CreateOneGriwrmInputsModel(id, ginet, girop, gits)
+    InputsModel[[id]] <- CreateOneGriwrmInputsModel(id, x, girop, gits, ...)
   }
   return(InputsModel)
 }
@@ -22,9 +21,7 @@ CreateInputsModel.Griwrm <- function(ginet, girop, gits, verbose = TRUE) {
 
 #' Create an empty InputsModel object for GRIWRM nodes
 #'
-#' @return
-#'
-#' @examples
+#' @return \emph{GriwrmInputsModel} empty object
 CreateEmptyGriwrmInputsModel <- function() {
   InputsModel <- list()
   class(InputsModel) <- append(class(InputsModel), "GriwrmInputsModel")
@@ -34,14 +31,12 @@ CreateEmptyGriwrmInputsModel <- function() {
 
 #' Create one InputsModel for a GRIWRM node
 #'
-#' @param ginet
-#' @param girop
-#' @param gits
-#' @param id
-#'
-#' @return
+#' @param id string of the node identifier
+#' @param ginet See \code{[Ginet]}.
+#' @param girop See \code{[Girop]}.
+#' @param gits See \code{[Gits]}.
 #'
-#' @examples
+#' @return \emph{InputsModel} object for one.
 CreateOneGriwrmInputsModel <- function(id, ginet, girop, gits) {
   node <- ginet[ginet$id == id,]
   FUN_MOD <- girop$model[girop$id == id]

R/CreateInputsModel.R

-#' Create InputsModel object for either airGR or GRIWRM
+#' Create InputsModel object for either airGR or GR-IWRM
 #'
-#' @param x
-#' @param ...
+#' @param x First parameter determining which InputsModel object is created
+#' @param ... further arguments passed to or from other methods.
 #'
-#' @return
+#' @return InputsModel or GriwrmInputsObject object
 #' @export
-#'
-#' @examples
 CreateInputsModel <- function(x, ...) {
   UseMethod("CreateInputsModel", x)
 }

R/CreateInputsModel.default.R

 #' Wrapper for the airGR::CreateInputsModel function
 #'
-#' @param FUN_MOD
-#' @param DatesR
-#' @param Precip
-#' @param PrecipScale
-#' @param PotEvap
-#' @param TempMean
-#' @param TempMin
-#' @param TempMax
-#' @param ZInputs
-#' @param HypsoData
-#' @param NLayers
-#' @param QobsUpstr
-#' @param LengthHydro
-#' @param BasinAreas
-#' @param verbose
+#' @param x hydrological model function (e.g. \code{\link[airGR]{RunModel_GR4J}}, \code{\link[airGR]{RunModel_CemaNeigeGR4J}})
+#' @param ... further arguments passed to \code{\link[airGR]{CreateInputsModel}}.
 #'
-#' @return
+#' @return object of class \emph{InputsModel}, see \code{\link[airGR]{CreateInputsModel}} for details.
 #' @import airGR
 #' @export
+#' @seealso The original function in airGR package: \code{\link[airGR]{CreateInputsModel}}.
 #'
-#' @examples
-CreateInputsModel.default <- function(FUN_MOD,
-                                      DatesR,
-                                      Precip, PrecipScale = TRUE,
-                                      PotEvap = NULL,
-                                      TempMean = NULL, TempMin = NULL, TempMax = NULL,
-                                      ZInputs = NULL, HypsoData = NULL, NLayers = 5,
-                                      QobsUpstr = NULL, LengthHydro = NULL, BasinAreas = NULL,
-                                      verbose = TRUE) {
-  airGR::CreateInputsModel(FUN_MOD, DatesR, Precip, PrecipScale, PotEvap,
-                           TempMean, TempMin, TempMax, ZInputs, HypsoData, NLayers,
-                           QobsUpstr, LengthHydro, BasinAreas, verbose)
+CreateInputsModel.default <- function(x,
+                                      ...) {
+
+  airGR::CreateInputsModel(FUN_MOD = x, ...)
 }

R/CreateRunOptions.GriwrmInputsModel.R

-#' Title
+#' Create \emph{GriwrmRunOptions} object for running and calibrating model in GR-IWRM.
 #'
-#' @param InputsModel
-#' @param IndPeriod_WarmUp
-#' @param IndPeriod_Run
-#' @param IniStates
-#' @param IniResLevels
-#' @param Imax
-#' @param Outputs_Cal
-#' @param Outputs_Sim
-#' @param MeanAnSolidPrecip
-#' @param IsHyst
-#' @param warnings
-#' @param verbose
+#' @param InputsModel object of class \emph{GriwrmInputsModel}, see \code{\link{CreateInputsModel.Griwrm}} for details.
+#' @param ... further arguments passed to \code{\link[airGR]{CreateOptions}}.
 #'
-#' @return
+#' @return \emph{GriwrmRunOptions} object for running and calibrating model in GR-IWRM.
 #' @export
-#'
-#' @examples
-CreateRunOptions.GriwrmInputsModel <- function(InputsModel, IndPeriod_WarmUp = NULL, IndPeriod_Run,
-                                               IniStates = NULL, IniResLevels = NULL, Imax = NULL,
-                                               Outputs_Cal = NULL, Outputs_Sim = "all",
-                                               MeanAnSolidPrecip = NULL, IsHyst = FALSE,
-                                               warnings = TRUE, verbose = TRUE) {
+CreateRunOptions.GriwrmInputsModel <- function(InputsModels, ...) {
+
   RunOptions <- list()
   class(RunOptions) <- append(class(RunOptions), "GriwrmRunOptions")
-  for(InputsModelBasin in InputsModel) {
-    RunOptions[[InputsModelBasin$id]] <- CreateRunOptions(
-      InputsModel = InputsModelBasin,
-      IndPeriod_WarmUp = IndPeriod_WarmUp,
-      IndPeriod_Run = IndPeriod_Run,
-      IniStates = IniStates,
-      IniResLevels = IniResLevels,
-      Imax = Imax,
-      Outputs_Cal = Outputs_Cal,
-      Outputs_Sim = Outputs_Sim,
-      MeanAnSolidPrecip = MeanAnSolidPrecip,
-      IsHyst = IsHyst,
-      warnings = warnings,
-      verbose = verbose
-    )
+
+  for(InputsModelBasin in InputsModels) {
+    RunOptions[[InputsModelBasin$id]] <- CreateRunOptions(InputsModel = InputsModelBasin, ...)
   }
   return(RunOptions)
 }

R/CreateRunOptions.InputsModel.R

-#' Title
+#' Create \emph{RunOptions} object for airGR. See \code{\link[airGR]{CreateOptions}}.
 #'
-#' @param FUN_MOD
-#' @param InputsModel
-#' @param IndPeriod_WarmUp
-#' @param IndPeriod_Run
-#' @param IniStates
-#' @param IniResLevels
-#' @param Imax
-#' @param Outputs_Cal
-#' @param Outputs_Sim
-#' @param MeanAnSolidPrecip
-#' @param IsHyst
-#' @param warnings
-#' @param verbose
+#' @param InputsModel object of class \emph{InputsModel}, see \code{\link[airGR]{CreateInputsModel}} for details.
+#' @param ... further arguments passed to \code{\link[airGR]{CreateOptions}}.
 #'
-#' @return
+#' @return See \code{\link[airGR]{CreateOptions}}.
 #' @export
-#'
-#' @examples
-CreateRunOptions.InputsModel <- function(InputsModel,
-                                         IndPeriod_WarmUp = NULL, IndPeriod_Run,
-                                         IniStates = NULL, IniResLevels = NULL, Imax = NULL,
-                                         Outputs_Cal = NULL, Outputs_Sim = "all",
-                                         MeanAnSolidPrecip = NULL, IsHyst = FALSE,
-                                         warnings = TRUE, verbose = TRUE) {
+CreateRunOptions.InputsModel <- function(InputsModel, ...) {
+
   airGR::CreateRunOptions(FUN_MOD = InputsModel$FUN_MOD,
                           InputsModel = InputsModel,
-                          IndPeriod_WarmUp = IndPeriod_WarmUp,
-                          IndPeriod_Run = IndPeriod_Run,
-                          IniStates = IniStates,
-                          IniResLevels = IniResLevels,
-                          Imax = Imax,
-                          Outputs_Cal = Outputs_Cal,
-                          Outputs_Sim = Outputs_Sim,
-                          MeanAnSolidPrecip = MeanAnSolidPrecip,
-                          IsHyst = IsHyst,
-                          warnings = warnings,
-                          verbose = verbose)
+                          ...)
 }

R/CreateRunOptions.R

-#' Title
+#' Create \emph{RunOptions} object for airGR and GR-IWRM. See \code{\link[airGR]{CreateOptions}} and \code{[CreateOptions.GriwrmInputsModel]}.
 #'
-#' @param ...
-#' @param InputsModel
+#' @param InputsModel object of class \emph{InputsModel} (see \code{\link[airGR]{CreateInputsModel}}) or \emph{GriwrmInputsModel} (See \code{[CreateInputsModel.Griwrm]}).
+#' @param ... further arguments passed to or from other methods.
 #'
-#' @return
+#' @return Object of \emph{RunOptions} class family
 #' @export
-#'
-#' @examples
 CreateRunOptions <- function(InputsModel, ...) {
   UseMethod("CreateRunOptions", InputsModel)
 }

R/RunModel.GriwrmInputsModel.R

 #' Title
 #'
-#' @param ginet
-#' @param girop
-#' @param gits
-#' @param IndPeriod_Run
-#' @param IndPeriod_WarmUp
+#' @param InputsModel object of class \emph{GriwrmInputsModel}, see \code{[CreateInputsModel.Griwrm]} for details.
+#' @param RunOptions object of class \emph{GriwrmRunOptions}, see \code{[CreateRunOptions.Griwrm]} for details.
+#' @param girop Girop object giving the run-off model parameters, see \code{[Girop]}.
+#' @param verbose (optional) boolean indicating if the function is run in verbose mode or not, default = \code{TRUE}
+#' @param ... Mandatory for S3 method signature function compatibility with generic.
 #'
-#' @return
+#' @return \emph{GriwrmOutputsModel} object which is a list of \emph{OutputsModel} objects (See \code{\link[airGR]{RunModel}}) for each node of the semi-distributed model.
 #' @export
-#'
-#' @examples
-RunModel.GriwrmInputsModel <- function(InputsModel, RunOptions, girop, verbose = TRUE) {
+RunModel.GriwrmInputsModel <- function(InputsModel, RunOptions, girop, verbose = TRUE, ...) {
 
-  OutputsModels <- list()
+  OutputsModel <- list()
+  class(OutputsModel) <- append(class(OutputsModel), "GriwrmOutputsModel")
 
   for(IM in InputsModel) {
     if(verbose) cat("RunModel.GriwrmInputsModel: Treating sub-basin", IM$id, "...\n")
 
     # Update InputsModel$QobsUpstr with simulated upstream flows
-    if(length(IM$UpstreamNodes) > 0) {
-      for(i in 1:length(IM$UpstreamNodes)) {
-        QobsUpstr1 <- matrix(
-          c(
-            rep(0, length(RunOptions[[IM$id]]$IndPeriod_WarmUp)),
-            OutputsModels[[IM$UpstreamNodes[i]]]$Qsim
-          ), ncol = 1
-        )
-        if(i == 1) {
-          IM$QobsUpstr <- QobsUpstr1
-        } else {
-          IM$QobsUpstr <- cbind(IM$QobsUpstr, QobsUpstr1)
-        }
-      }
-    }
+    IM <- UpdateQsimUpstream(IM, OutputsModel)
 
     # Run the model for the sub-basin
-    OutputsModels[[IM$id]] <- RunModel(
+    OutputsModel[[IM$id]] <- RunModel(
       InputsModel = IM,
       RunOptions = RunOptions[[IM$id]],
       Param = unlist(girop$params[girop$id == IM$id])
     )
 
   }
-  return(OutputsModels)
+  return(OutputsModel)
 }

R/RunModel.InputsModel.R

@@ -7,9 +7,7 @@
 #'
 #' @return
 #' @export
-#'
-#' @examples
-RunModel.InputsModel <- function(InputsModel, RunOptions, Param, FUN_MOD = NULL) {
+RunModel.InputsModel <- function(InputsModel, RunOptions, Param, FUN_MOD = NULL, ...) {
   if(is.null(FUN_MOD)) {
     FUN_MOD <- InputsModel$FUN_MOD
   }

R/RunModel.R

 #' RunModel function for both airGR and GriwrmInputsModel object
 #'
-#' @param InputsModel
-#' @param ...
+#' @param InputsModel object of class \emph{InputsModel}, see \code{\link[airGR]{CreateInputsModel}} for details.
+#' @param ... further arguments passed to or from other methods.
 #'
 #' @return
 #' @export
-#'
-#' @examples
 RunModel <- function(InputsModel, ...) {
   UseMethod("RunModel", InputsModel)
 }

R/UpdateQsimUpstream.R

+#' Update InputsModel$QobsUpstr with simulated upstream flows provided by GriwrmOutputsModels object.
+#'
+#' @param InputsModel \emph{GriwrmInputsModel} object. See \code{[CreateInputsModel.Griwrm]}.
+#' @param OutputsModels \emph{GriwrmOutputsModel} object provided by \code{[RunModel.GriwrmInputsModel]}.
+#'
+#' @description This function is used by \code{\link{RunModel.GriwrmInputsModel}} and \code{\link{Calibration.GriwrmInputsModel}} in order to provide upstream simulated flows to a node.
+#'
+#' @return InputsModel object with updated QobsUpsr
+#'
+UpdateQsimUpstream <- function(InputsModel, OutputsModels) {
+  if(length(InputsModel$UpstreamNodes) > 0) {
+    for(i in 1:length(InputsModel$UpstreamNodes)) {
+      QobsUpstr1 <- matrix(
+        c(
+          rep(0, length(RunOptions[[InputsModel$id]]$IndPeriod_WarmUp)),
+          OutputsModels[[InputsModel$UpstreamNodes[i]]]$Qsim
+        ), ncol = 1
+      )
+      if(i == 1) {
+        InputsModel$QobsUpstr <- QobsUpstr1
+      } else {
+        InputsModel$QobsUpstr <- cbind(InputsModel$QobsUpstr, QobsUpstr1)
+      }
+    }
+  }
+  return(InputsModel)
+}

R/ginet.R

 #' Generate a network description containing all hydraulic nodes and the description
 #' of their connections
 #'
-#' @param db A tibble or a dataframe containing at least the id and the description of the connections
-#' @param cols
+#' @param db A tibble or a data frame containing at least columns with the id (column `id`), the id and the hydraulic distance to the node downstream (columns `down` and `length`) and a boolean determining whether the node is a rainfall run-off model or not (column `runoff`). The last downstream node should have fields `down` and `length` set to `NA`.
+#' @param cols named list or vector for matching columns of `db` parameter. By default, mandatory columns names are: `id`, `down`, `length`. But other names can be handled with a named list or vector containing items defined as `"required name" = "column name in db"`.
 #' @param keep_all Keep all column of `db` or keep only columns defined in `cols`
 #'
-#' @return
+#' @return `Ginet` class object containing the description of diagram of the semi-distributed catchment model
 #' @export
-#'
-#' @examples
 Ginet <- function(db, cols = list(id = "id", down = "down", length = "length", runoff = "runoff"), keep_all = FALSE) {
   colsDefault <- list(id = "id", down = "down", length = "length", runoff = "runoff")
   cols <- utils::modifyList(colsDefault, as.list(cols))
@@ -20,14 +18,12 @@ Ginet <- function(db, cols = list(id = "id", down = "down", length = "length", r
   db
 }
 
-#' Title
+#' Sort the nodes from upstream to downstream.
 #'
-#' @param ginet
+#' @param ginet See \code{[Ginet]}.
 #'
-#' @return
+#' @return vector with the ordered node names.
 #' @export
-#'
-#' @examples
 getNodeRanking <- function(ginet) {
   if(!is(ginet, "Ginet")) {
     stop("getNodeRanking: ginet argument should be of class Ginet")

R/girop.R

 #' Generate the list of run-off models and their parameters
 #'
-#' @param db dataframe containing at least the id and the area of the sub-basin
-#' @param cols
+#' @param db data frame containing at least the id the area and the model of the sub-basin.
+#' @param cols named list or vector for matching columns of `db` parameter. By default, mandatory columns names are: `id`, `area`, `model`. But other names can be handled with a named list or vector containing items defined as `"required name" = "column name in db"`.
 #' @param keep_all Keep all column of `db` or keep only columns defined in `cols`
 #'
-#' @return
+#' @return \emph{Girop} object.
 #' @export
-#'
-#' @examples
 Girop <- function(db, cols = c(id = "id", area = "area", model = "model", params = "params"), keep_all = FALSE) {
   colsDefault <- list(id = "id", area = "area", model = "model", params = "params")
   cols <- utils::modifyList(colsDefault, as.list(cols))

R/gits.R

 #' Title
 #'
-#' @param id
-#' @param ts
-#' @param cols
+#' @param id string of the id of the node
+#' @param ts numeric matrix or data frame containing 3 columns for precipitation, evaporation, and observed flow
+#' @param cols named list or vector used for matching the columns of ts with the required columns names which are "Precip", "PotEvap", and "Qobs".
 #'
-#' @return
+#' @return \emph{Gits} class object which is a list containing a `date` element (Vector of PosiXlt timestamps) and an element named the id of the node containing a dataframe with observed data.
 #' @export
-#'
-#' @examples
 Gits <- function(id, ts,
                  cols = list(date = "date", Precip = "Precip", PotEvap = "PotEvap", Qobs = "Qobs")) {
 
@@ -28,16 +26,15 @@ Gits <- function(id, ts,
   gitsOut
 }
 
-#' Title
+#' Merge two gits objects with identical date time series.
 #'
-#' @param x
-#' @param y
+#' @param x Gits object to merge (See [Gits]).
+#' @param y Gits object to merge (See [Gits]).
+#' @param ... For merge generic function compatibility.
 #'
-#' @return
+#' @return Gits object merged with one item `Date` and Items corresponding to each node.
 #' @export
-#'
-#' @examples
-merge.Gits <- function(x, y) {
+merge.Gits <- function(x, y, ...) {
   if(!is(y, "Gits")) {
     stop("A Gits class object can only be merged with a Gits class object")
   }

vignettes/V01_First_network.Rmd

 ---
 title: 'Tutorial: structuration of a semi-distributive GR model'
 author: "David Dorchies"
-date: "19 mai 2020"
-output: html_document
+vignette: >
+  %\VignetteIndexEntry{Tutorial: structuration of a semi-distributive GR model}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
 ---
 
 ```{r setup, include=FALSE}

vignettes/v02_First_run.Rmd

 ---
 title: "First run of the model"
 author: "David Dorchies"
-date: "20 mai 2020"
-output: html_document
+vignette: >
+  %\VignetteIndexEntry{First run of the model}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
 ---
 
 ```{r setup, include=FALSE}