Merge branch '46-rename-function-griwrm-to-creategriwrm' into 'dev'

Resolve "Rename function GRiwrm to CreateGRiwrm"

Closes #46

See merge request !17

NAMESPACE

@@ -26,14 +26,13 @@ export(CheckColumnTypes)
 export(ConvertMeteoSD)
 export(CreateCalibOptions)
 export(CreateController)
+export(CreateGRiwrm)
 export(CreateInputsCrit)
 export(CreateInputsModel)
 export(CreateRunOptions)
 export(CreateSupervisor)
-export(GRiwrm)
 export(RunModel)
 export(createControl)
-export(getNodeRanking)
 import(airGR)
 importFrom(grDevices,rainbow)
 importFrom(graphics,matplot)

R/ConvertMeteoSD.R

 #' Convert meteorological data from basin scale to sub-basin scale
 #'
-#' @param x either a [GRiwrm] network description, a [character] id of a node, a [matrix] containing meteorological data
+#' @param x either a `GRiwrm` network description (See [CreateGRiwrm]), a [character] id of a node, a [matrix] containing meteorological data
 #' @param ... Parameters passed to the methods
 #'
 #' @return Either a [matrix] containing the converted meteorological data
@@ -22,7 +22,7 @@ ConvertMeteoSD.GRiwrm <- function(x, meteo, ...) {
   return(meteoOut)
 }
 
-#' @param griwrm [GRiwrm] object describing the semi-distributive network
+#' @param griwrm `GRiwrm` object describing the semi-distributive network (See [CreateGRiwrm])
 #' @export
 #' @rdname ConvertMeteoSD
 ConvertMeteoSD.character <- function(x, griwrm, meteo, ...) {

R/GRiwrm.R → R/CreateGRiwrm.R

@@ -4,20 +4,29 @@
 #' @details `db` is a [data.frame] which at least contains in its columns:
 #'
 #'  * a node identifier (column `id`),
-#'  * the identifier and the hydraulic distance to the downstream node ([character] columns `down` and [numeric] columns `length` in meters). The last downstream node should have fields `down` and `length` set to `NA`,
+#'  * the identifier and the hydraulic distance to the downstream node ([character] columns `down` and [numeric] columns `length` in km). The last downstream node should have fields `down` and `length` set to `NA`,
 #'  * the area of the basin ([numeric] column `area` in km^2^)
-#'  * the hydrological model to use if so ([character] column `model`).
+#'  * the hydrological model to use if so ([character] column `model`) ([NA] for using observed flow instead of a run-off model output)
 #'
 #' @param db a [data.frame] containing the description of the network (See details)
 #' @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 `GRiwrm` class object containing the description of the semi-distributed model network
+#' @return An object of class `GRiwrm` describing the airGR semi-distributed model network.
+#'
+#' It's a [data.frame] with each line corresponding to a location on the river network and with the following columns:
+#'  * `id` ([character]): node identifier
+#'  * `down` ([character]): the identifier of the node downstream of the current node ([NA] for the most downstream node)
+#'  * `length` ([numeric]): the hydraulic distance to the downstream node in km ([NA] for the most downstream node)
+#'  * `area` ([numeric]): the total area of the basin starting from the current node location in km^2^
+#'  * `model` ([character]): the hydrological model to use if so ([NA] for using observed flow instead of a run-off model output)
+#'
+#' @aliases GRiwrm
 #' @export
 #' @examples
-#' #################################################################
-#' # Run the `airGRRunModel_Lag` example in the GRiwrm fashion way #
-#' #################################################################
+#' ###################################################################
+#' # Run the `airGR::RunModel_Lag` example in the GRiwrm fashion way #
+#' ###################################################################
 #'
 #' # Run airGR RunModel_Lag example for harvesting necessary data
 #' library(airGR)
@@ -34,10 +43,10 @@
 #'                  stringsAsFactors = FALSE)
 #'
 #' # Create GRiwrm object from the data.frame
-#' griwrm <- GRiwrm(db)
+#' griwrm <- CreateGRiwrm(db)
 #' str(griwrm)
 #'
-GRiwrm <- function(db,
+CreateGRiwrm <- function(db,
                    cols = list(
                      id = "id",
                      down = "down",
@@ -102,10 +111,9 @@ CheckColumnTypes <- function(df, coltypes) {
 
 #' Sort the nodes from upstream to downstream.
 #'
-#' @param griwrm See \code{[GRiwrm]}.
+#' @param griwrm See [CreateGRiwrm]
 #'
 #' @return vector with the ordered node names.
-#' @export
 getNodeRanking <- function(griwrm) {
   if (!inherits(griwrm, "GRiwrm")) {
     stop("getNodeRanking: griwrm argument should be of class GRiwrm")

R/CreateInputsModel.GRiwrm.R

 #' Create InputsModel object for a **airGRiwrm** network
 #'
-#' @param x GRiwrm object describing the diagram of the semi-distributed model, see \code{[GRiwrm]}.
-#' @param DatesR Vector of POSIXt observation time steps.
-#' @param Precip Matrix or data frame of numeric containing precipitation in mm. Column names correspond to node IDs.
-#' @param PotEvap Matrix or data frame of numeric containing potential evaporation in mm. Column names correspond to node IDs.
-#' @param Qobs Matrix or data frame of numeric containing potential observed flow in mm. Column names correspond to node IDs.
-#' @param ... further arguments passed to [airGR::CreateInputsModel].
+#' @param x GRiwrm object describing the diagram of the semi-distributed model (See [CreateGRiwrm])
+#' @param DatesR Vector of POSIXt observation time steps
+#' @param Precip Matrix or data frame of numeric containing precipitation in mm. Column names correspond to node IDs
+#' @param PotEvap Matrix or data frame of numeric containing potential evaporation in mm. Column names correspond to node IDs
+#' @param Qobs Matrix or data frame of numeric containing potential observed flow in mm. Column names correspond to node IDs
+#' @param ... further arguments passed to [airGR::CreateInputsModel]
 #'
 #' @return GRiwrmInputsModel object equivalent to **airGR** InputsModel object for a semi-distributed model (See [airGR::CreateInputsModel])
 #' @export
@@ -29,7 +29,7 @@
 #'                  stringsAsFactors = FALSE)
 #'
 #' # Create GRiwrm object from the data.frame
-#' griwrm <- GRiwrm(db)
+#' griwrm <- CreateGRiwrm(db)
 #' str(griwrm)
 #'
 #' # Formatting observations for the hydrological models
@@ -71,7 +71,7 @@ CreateInputsModel.GRiwrm <- function(x, DatesR, Precip, PotEvap, Qobs, ...) {
 
 #' Create an empty InputsModel object for **airGRiwrm** nodes
 #'
-#' @param griwrm a `GRiwrm` object (See [GRiwrm])
+#' @param griwrm a `GRiwrm` object (See [CreateGRiwrm])
 #'
 #' @return \emph{GRiwrmInputsModel} empty object
 CreateEmptyGRiwrmInputsModel <- function(griwrm) {
@@ -85,11 +85,11 @@ CreateEmptyGRiwrmInputsModel <- function(griwrm) {
 #' Create one InputsModel for a **airGRiwrm** node
 #'
 #' @param id string of the node identifier
-#' @param griwrm See \code{[GRiwrm]}.
-#' @param DatesR vector of dates required to create the GR model and CemaNeige module inputs.
-#' @param Precip time series of potential evapotranspiration (catchment average) (mm/time step).
-#' @param PotEvap time series of potential evapotranspiration (catchment average) (mm/time step).
-#' @param Qobs Matrix or data frame of numeric containing observed flow (mm/time step). Column names correspond to node IDs.
+#' @param griwrm See [CreateGRiwrm])
+#' @param DatesR vector of dates required to create the GR model and CemaNeige module inputs
+#' @param Precip time series of potential evapotranspiration (catchment average) (mm/time step)
+#' @param PotEvap time series of potential evapotranspiration (catchment average) (mm/time step)
+#' @param Qobs Matrix or data frame of numeric containing observed flow (mm/time step). Column names correspond to node IDs
 ##'
 #' @return \emph{InputsModel} object for one.
 CreateOneGRiwrmInputsModel <- function(id, griwrm, DatesR, Precip, PotEvap, Qobs) {

R/CreateSupervisor.R

@@ -11,7 +11,7 @@
 #' nodes <- Severn$BasinsInfo[, c("gauge_id", "downstream_id", "distance_downstream", "area")]
 #' nodes$distance_downstream <- nodes$distance_downstream * 1000 # Conversion km -> m
 #' nodes$model <- "RunModel_GR4J"
-#' griwrm <- GRiwrm(nodes,
+#' griwrm <- CreateGRiwrm(nodes,
 #'                  list(id = "gauge_id",
 #'                       down = "downstream_id",
 #'                       length = "distance_downstream"))

R/RunModel.GRiwrmInputsModel.R

@@ -27,7 +27,7 @@
 #'                  stringsAsFactors = FALSE)
 #'
 #' # Create GRiwrm object from the data.frame
-#' griwrm <- GRiwrm(db)
+#' griwrm <- CreateGRiwrm(db)
 #' str(griwrm)
 #'
 #' # Formatting observations for the hydrological models

R/plot.GRiwrm.R

 #' Display a diagram representing the network structure of a GRiwrm object
 #'
-#' @param x a GRiwrm object to display (See [GRiwrm])
+#' @param x a GRiwrm object to display (See [CreateGRiwrm])
 #' @param display if `TRUE` displays the diagram with [DiagrammeR::mermaid], return the mermaid code otherwise
 #' @param orientation a [character] describing the orientation of the graph. Possible values are "LR" (left-right), "RL" (right-left), "TB" (top-bottom), or "BT" (bottom-top). "LR" by default
 #' @param width The width of the resulting graphic in pixels (See [DiagrammeR::mermaid])

R/plot.GRiwrmOutputsModel.R

@@ -3,7 +3,7 @@
 #' @param x object of class *GRiwrmOutputsModel*, see [RunModel.GRiwrmInputsModel]
 #' @param Qobs (optional) [numeric] [matrix] time series of observed flow
 #'        (for the same time steps than simulated) (mm/time step) with one column
-#'        by hydrological model output named with the node Id (See [GRiwrm])
+#'        by hydrological model output named with the node Id (See [CreateGRiwrm])
 #' @param ... Further arguments for [airGR::plot.OutputsModel] and [plot]
 #'
 #' @return [list] of plots

R/utils.R

@@ -110,7 +110,7 @@ checkRunModelParameters <- function(InputsModel, RunOptions, Param) {
 }
 
 
-#' Create a data.frame with simulated flows at each nodes of the [GRiwrm] object
+#' Create a data.frame with simulated flows at each nodes of the GRiwrm object
 #'
 #' @details
 #' This function can only be called inside [RunModel.GRiwrmInputsModel] or [RunModel.Supervisor]

man/CheckColumnTypes.Rd

 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/GRiwrm.R
+% Please edit documentation in R/CreateGRiwrm.R
 \name{CheckColumnTypes}
 \alias{CheckColumnTypes}
 \title{Check the column types of a \link{data.frame}}

man/ConvertMeteoSD.Rd

@@ -16,13 +16,13 @@ ConvertMeteoSD(x, ...)
 \method{ConvertMeteoSD}{matrix}(x, areas, temperature = FALSE, ...)
 }
 \arguments{
-\item{x}{either a \link{GRiwrm} network description, a \link{character} id of a node, a \link{matrix} containing meteorological data}
+\item{x}{either a \code{GRiwrm} network description (See \link{CreateGRiwrm}), a \link{character} id of a node, a \link{matrix} containing meteorological data}
 
 \item{...}{Parameters passed to the methods}
 
 \item{meteo}{\link{matrix} or \link{data.frame} containing meteorological data. Its \link{colnames} should be equal to the IDof the basins}
 
-\item{griwrm}{\link{GRiwrm} object describing the semi-distributive network}
+\item{griwrm}{\code{GRiwrm} object describing the semi-distributive network (See \link{CreateGRiwrm})}
 
 \item{areas}{\link{numeric} vector with the total area of the basin followed by the areas of the upstream basins in km^2^}
 

man/CreateEmptyGRiwrmInputsModel.Rd

@@ -7,7 +7,7 @@
 CreateEmptyGRiwrmInputsModel(griwrm)
 }
 \arguments{
-\item{griwrm}{a \code{GRiwrm} object (See \link{GRiwrm})}
+\item{griwrm}{a \code{GRiwrm} object (See \link{CreateGRiwrm})}
 }
 \value{
 \emph{GRiwrmInputsModel} empty object

man/GRiwrm.Rd → man/CreateGRiwrm.Rd

 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/GRiwrm.R
-\name{GRiwrm}
+% Please edit documentation in R/CreateGRiwrm.R
+\name{CreateGRiwrm}
+\alias{CreateGRiwrm}
 \alias{GRiwrm}
 \title{Generate a network description containing all hydraulic nodes and the description
 of their connections}
 \usage{
-GRiwrm(
+CreateGRiwrm(
   db,
   cols = list(id = "id", down = "down", length = "length", model = "model", area =
     "area"),
@@ -20,7 +21,16 @@ GRiwrm(
 \item{keep_all}{keep all column of \code{db} or keep only columns defined in \code{cols}}
 }
 \value{
-\code{GRiwrm} class object containing the description of the semi-distributed model network
+An object of class \code{GRiwrm} describing the airGR semi-distributed model network.
+
+It's a \link{data.frame} with each line corresponding to a location on the river network and with the following columns:
+\itemize{
+\item \code{id} (\link{character}): node identifier
+\item \code{down} (\link{character}): the identifier of the node downstream of the current node (\link{NA} for the most downstream node)
+\item \code{length} (\link{numeric}): the hydraulic distance to the downstream node in km (\link{NA} for the most downstream node)
+\item \code{area} (\link{numeric}): the total area of the basin starting from the current node location in km^2^
+\item \code{model} (\link{character}): the hydrological model to use if so (\link{NA} for using observed flow instead of a run-off model output)
+}
 }
 \description{
 Generate a network description containing all hydraulic nodes and the description
@@ -30,15 +40,15 @@ of their connections
 \code{db} is a \link{data.frame} which at least contains in its columns:
 \itemize{
 \item a node identifier (column \code{id}),
-\item the identifier and the hydraulic distance to the downstream node (\link{character} columns \code{down} and \link{numeric} columns \code{length} in meters). The last downstream node should have fields \code{down} and \code{length} set to \code{NA},
+\item the identifier and the hydraulic distance to the downstream node (\link{character} columns \code{down} and \link{numeric} columns \code{length} in km). The last downstream node should have fields \code{down} and \code{length} set to \code{NA},
 \item the area of the basin (\link{numeric} column \code{area} in km^2^)
-\item the hydrological model to use if so (\link{character} column \code{model}).
+\item the hydrological model to use if so (\link{character} column \code{model}) (\link{NA} for using observed flow instead of a run-off model output)
 }
 }
 \examples{
-#################################################################
-# Run the `airGRRunModel_Lag` example in the GRiwrm fashion way #
-#################################################################
+###################################################################
+# Run the `airGR::RunModel_Lag` example in the GRiwrm fashion way #
+###################################################################
 
 # Run airGR RunModel_Lag example for harvesting necessary data
 library(airGR)
@@ -55,7 +65,7 @@ db <- data.frame(id = c("Reservoir", "GaugingDown"),
                  stringsAsFactors = FALSE)
 
 # Create GRiwrm object from the data.frame
-griwrm <- GRiwrm(db)
+griwrm <- CreateGRiwrm(db)
 str(griwrm)
 
 }

man/CreateInputsModel.GRiwrm.Rd

@@ -7,17 +7,17 @@
 \method{CreateInputsModel}{GRiwrm}(x, DatesR, Precip, PotEvap, Qobs, ...)
 }
 \arguments{
-\item{x}{GRiwrm object describing the diagram of the semi-distributed model, see \code{[GRiwrm]}.}
+\item{x}{GRiwrm object describing the diagram of the semi-distributed model (See \link{CreateGRiwrm})}
 
-\item{DatesR}{Vector of POSIXt observation time steps.}
+\item{DatesR}{Vector of POSIXt observation time steps}
 
-\item{Precip}{Matrix or data frame of numeric containing precipitation in mm. Column names correspond to node IDs.}
+\item{Precip}{Matrix or data frame of numeric containing precipitation in mm. Column names correspond to node IDs}
 
-\item{PotEvap}{Matrix or data frame of numeric containing potential evaporation in mm. Column names correspond to node IDs.}
+\item{PotEvap}{Matrix or data frame of numeric containing potential evaporation in mm. Column names correspond to node IDs}
 
-\item{Qobs}{Matrix or data frame of numeric containing potential observed flow in mm. Column names correspond to node IDs.}
+\item{Qobs}{Matrix or data frame of numeric containing potential observed flow in mm. Column names correspond to node IDs}
 
-\item{...}{further arguments passed to \link[airGR:CreateInputsModel]{airGR::CreateInputsModel}.}
+\item{...}{further arguments passed to \link[airGR:CreateInputsModel]{airGR::CreateInputsModel}}
 }
 \value{
 GRiwrmInputsModel object equivalent to \strong{airGR} InputsModel object for a semi-distributed model (See \link[airGR:CreateInputsModel]{airGR::CreateInputsModel})
@@ -45,7 +45,7 @@ db <- data.frame(id = c("Reservoir", "GaugingDown"),
                  stringsAsFactors = FALSE)
 
 # Create GRiwrm object from the data.frame
-griwrm <- GRiwrm(db)
+griwrm <- CreateGRiwrm(db)
 str(griwrm)
 
 # Formatting observations for the hydrological models

man/CreateOneGRiwrmInputsModel.Rd

@@ -9,15 +9,15 @@ CreateOneGRiwrmInputsModel(id, griwrm, DatesR, Precip, PotEvap, Qobs)
 \arguments{
 \item{id}{string of the node identifier}
 
-\item{griwrm}{See \code{[GRiwrm]}.}
+\item{griwrm}{See \link{CreateGRiwrm})}
 
-\item{DatesR}{vector of dates required to create the GR model and CemaNeige module inputs.}
+\item{DatesR}{vector of dates required to create the GR model and CemaNeige module inputs}
 
-\item{Precip}{time series of potential evapotranspiration (catchment average) (mm/time step).}
+\item{Precip}{time series of potential evapotranspiration (catchment average) (mm/time step)}
 
-\item{PotEvap}{time series of potential evapotranspiration (catchment average) (mm/time step).}
+\item{PotEvap}{time series of potential evapotranspiration (catchment average) (mm/time step)}
 
-\item{Qobs}{Matrix or data frame of numeric containing observed flow (mm/time step). Column names correspond to node IDs.}
+\item{Qobs}{Matrix or data frame of numeric containing observed flow (mm/time step). Column names correspond to node IDs}
 }
 \value{
 \emph{InputsModel} object for one.

man/CreateRunOptions.GRiwrmInputsModel.Rd

@@ -37,7 +37,7 @@ db <- data.frame(id = c("Reservoir", "GaugingDown"),
                  stringsAsFactors = FALSE)
 
 # Create GRiwrm object from the data.frame
-griwrm <- GRiwrm(db)
+griwrm <- CreateGRiwrm(db)
 str(griwrm)
 
 # Formatting observations for the hydrological models

man/CreateSupervisor.Rd

@@ -22,7 +22,7 @@ data(Severn)
 nodes <- Severn$BasinsInfo[, c("gauge_id", "downstream_id", "distance_downstream", "area")]
 nodes$distance_downstream <- nodes$distance_downstream * 1000 # Conversion km -> m
 nodes$model <- "RunModel_GR4J"
-griwrm <- GRiwrm(nodes,
+griwrm <- CreateGRiwrm(nodes,
                  list(id = "gauge_id",
                       down = "downstream_id",
                       length = "distance_downstream"))

man/OutputsModelQsim.Rd

@@ -2,7 +2,7 @@
 % Please edit documentation in R/utils.R
 \name{OutputsModelQsim}
 \alias{OutputsModelQsim}
-\title{Create a data.frame with simulated flows at each nodes of the \link{GRiwrm} object}
+\title{Create a data.frame with simulated flows at each nodes of the GRiwrm object}
 \usage{
 OutputsModelQsim(InputsModel, OutputsModel, IndPeriod_Run)
 }
@@ -21,7 +21,7 @@ a \link{data.frame} containing the simulated flows (in m3/time step) structured
 }
 }
 \description{
-Create a data.frame with simulated flows at each nodes of the \link{GRiwrm} object
+Create a data.frame with simulated flows at each nodes of the GRiwrm object
 }
 \details{
 This function can only be called inside \link{RunModel.GRiwrmInputsModel} or \link{RunModel.Supervisor}

man/RunModel.GRiwrmInputsModel.Rd

@@ -41,7 +41,7 @@ db <- data.frame(id = c("Reservoir", "GaugingDown"),
                  stringsAsFactors = FALSE)
 
 # Create GRiwrm object from the data.frame
-griwrm <- GRiwrm(db)
+griwrm <- CreateGRiwrm(db)
 str(griwrm)
 
 # Formatting observations for the hydrological models

man/getNodeRanking.Rd

 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/GRiwrm.R
+% Please edit documentation in R/CreateGRiwrm.R
 \name{getNodeRanking}
 \alias{getNodeRanking}
 \title{Sort the nodes from upstream to downstream.}
@@ -7,7 +7,7 @@
 getNodeRanking(griwrm)
 }
 \arguments{
-\item{griwrm}{See \code{[GRiwrm]}.}
+\item{griwrm}{See \link{CreateGRiwrm}}
 }
 \value{
 vector with the ordered node names.