Commit b28c8d6f authored by Dorchies David's avatar Dorchies David
Browse files

doc: review documentation for CRAN

- All remarks #43 (comment 40117) taken into account
- fix bugs in vignettes after fc016f26

Refs #43, #52
parent 31d09df1
......@@ -22,7 +22,6 @@ S3method(plot,GRiwrm)
S3method(plot,GRiwrmOutputsModel)
S3method(plot,Qm3s)
export(Calibration)
export(CheckColumnTypes)
export(ConvertMeteoSD)
export(CreateCalibOptions)
export(CreateController)
......@@ -32,7 +31,6 @@ export(CreateInputsModel)
export(CreateRunOptions)
export(CreateSupervisor)
export(RunModel)
export(createControl)
import(airGR)
importFrom(grDevices,rainbow)
importFrom(graphics,matplot)
......
#' Calibration of a semi-distributed precipitation-runoff model
#'
#' @param InputsModel object of class \emph{GRiwrmInputsModel}, see [CreateInputsModel.GRiwrm] for details
#' @param RunOptions object of class \emph{GRiwrmRunOptions}, see [CreateRunOptions.GRiwrmInputsModel] for details
#' @param InputsCrit object of class \emph{GRiwrmInputsCrit}, see [CreateInputsCrit.GRiwrmInputsModel] for details
#' @param CalibOptions object of class \emph{GRiwrmCalibOptions}, see [CreateCalibOptions.GRiwrmInputsModel] for details
#' @param useUpstreamQsim boolean describing if simulated (\code{TRUE}) or observed (\code{FALSE}) flows are used for calibration. Default is \code{TRUE}
#' @param ... further arguments passed to [airGR::Calibration].
#'
#' @return [list] of [airGR::Calibration] outputs for each node of the semi-distributed model.
#' @rdname Calibration
#' @export
Calibration.GRiwrmInputsModel <- function(InputsModel,
RunOptions,
......
#' Wrapper to [airGR::Calibration] for one sub-basin.
#'
#' @inherit airGR::Calibration
#' @param ... Further arguments for compatibility with S3 method
#' @rdname Calibration
#' @export
Calibration.InputsModel <- function(InputsModel, ...) {
airGR::Calibration(InputsModel, FUN_MOD = InputsModel$FUN_MOD, ...)
......
#' Calibration of either a **airGR** model or a **airGRiwrm** semi-distributed model
#' Calibration of the parameters of one catchment or a network of sub-catchments
#'
#' @param InputsModel the class of the first parameter determines which calibration algorithm is used
#' @param ... further arguments passed to or from other methods.
#' Calibration algorithm that optimises the error criterion selected as objective function using the provided functions.
#'
#' @return \emph{OutputsCalib} or \emph{GRiwrmOutputsCalib} object
#' This function can be used either for a catchment (with an \emph{InputsModel} object) or for a network (with a \emph{GRiwrmInputsModel} object)
#'
#' @param InputsModel \[object of class \emph{InputsModel} or \emph{GRwirmInputsModel}\] see [CreateInputsModel]
#' @param RunOptions \[object of class \emph{RunOptions} or \emph{GRiwrmRunOptions}\] see [CreateRunOptions]
#' @param InputsCrit \[object of class \emph{InputsCrit} or \emph{GRiwrmInputsCrit}\] see [CreateInputsCrit]
#' @param CalibOptions \[object of class \emph{CalibOptions} or \emph{GRiwrmCalibOptions}\] see [CreateCalibOptions] for details
#' @param ... further arguments passed to [airGR::Calibration], see details
#'
#' @details Argument classes should be consistent to the usage:
#' - a `InputsModel` argument of class \emph{InputsModel} must be followed by a `RunOptions` argument of class \emph{RunOptions}, a `InputsCrit` argument of class \emph{InputsCrit} and a `CalibOptions` of class \emph{CalibOptions}
#' - - a `InputsModel` argument of class \emph{GRiwrmInputsModel} must be followed by a `RunOptions` argument of class \emph{GRiwrmRunOptions}, a `InputsCrit` argument of class \emph{GRiwrmInputsCrit} and a `CalibOptions` of class \emph{GRiwrmCalibOptions}
#'
#' See the vignettes for examples.
#'
#' @return Depending on the class of `InputsModel` argument (respectively `InputsModel` and `GRiwrmInputsModel` object), the returned value is respectively:
#' - a `InputsCrit` object (See [airGR::CreateInputsCrit])
#' - a `GRiwrmInputsCrit` object which is a [list] of `InputsCrit` object with one item per modelled sub-catchment
#'
#' @rdname Calibration
#' @export
Calibration <- function(InputsModel, ...) {
UseMethod("Calibration", InputsModel)
......
#' Title
#'
#' @param InputsModel object of class \emph{GRiwrmInputsModel}, see [CreateInputsModel.GRiwrm] for details.
#' @param ... further arguments passed to [airGR::CreateCalibOptions].
#'
#' @return \emph{GRiwrmCalibOptions} object.
#' @rdname CreateCalibOptions
#' @export
CreateCalibOptions.GRiwrmInputsModel <- function(InputsModel, ...) {
......
#' Wrapper to [airGR::CreateCalibOptions] for one sub-basin.
#'
#' @param InputsModel object of class \emph{InputsModel}. See [airGR::CreateInputsModel] for details
#' @param ... Arguments passed to [airGR::CreateCalibOptions]
#' @rdname CreateCalibOptions
#' @export
CreateCalibOptions.InputsModel <- function(InputsModel,
...) {
......
#' Creation of the CalibOptions object either for \emph{InputsModel} or for \emph{GRwirmInputsModel} objects
#' Creation of the CalibOptions object
#'
#' This function can be used either for a catchment (with an \emph{InputsModel} object) or for a network (with a \emph{GRiwrmInputsModel} object)
#'
#' @param InputsModel object of class \emph{InputsModel} or \emph{GRwirmInputsModel}. See [CreateInputsModel] for details
#' @param ... further arguments passed to or from other methods
#' @param ... arguments passed to [airGR::CreateCalibOptions], see details
#'
#' @details See [airGR::CreateCalibOptions] documentation for a complete list of arguments.
#'
#' With a \emph{GRwirmInputsModel} object, all arguments are applied on each sub-catchments of the network.
#'
#' @return Depending on the class of `InputsModel` argument (respectively `InputsModel` and `GRiwrmInputsModel` object), the returned value is respectively:
#' - a `CalibOptions` object (See [airGR::CreateCalibOptions])
#' - a `GRiwrmCalibOptions` object which is a [list] of `CalibOptions` object with one item per modelled sub-catchment
#'
#' @return [list] Either a `CalibOptions` or a `GRiwrmCalibOptions` object
#' @rdname CreateCalibOptions
#' @export
CreateCalibOptions <- function(InputsModel, ...) {
UseMethod("CreateCalibOptions", InputsModel)
......
......@@ -11,11 +11,19 @@
#'
#' @param supervisor `Supervisor` object, see [CreateSupervisor]
#' @param ctrl.id [character] id of the controller (see Details)
#' @param Y [character] location of the controlled and/or measured variables in the model. See [createControl]
#' @param U [character] location of the command variables in the model. See [createControl]
#' @param Y [character] location of the controlled and/or measured variables in the model.
#' @param U [character] location of the command variables in the model.
#' @param FUN [function] controller logic which calculates `U` from `Y` (see Details)
#'
#' @return `Controller`
#' @return a `Controller` object which is a list with the following items:
#' - `id` [character]: the controller identifier
#' - `U` [matrix]: the list of controls for command variables with each column being the location of the variables and the rows being
#' the values of the variable for the current time steps (empty by default)
#' - `Unames` [character]: location of the command variables
#' - `Y` [matrix]: the lists of controls for controlled variables with each column being the location of the variables and the rows being
#' the values of the variable for the current time steps (empty by default)
#' - `Ynames` [character]: location of the controlled variables
#' - `FUN` [function]: controller logic which calculates `U` from `Y`
#' @export
#'
#' @examples
......@@ -33,9 +41,9 @@ CreateController <- function(supervisor, ctrl.id, Y, U, FUN){
ctrlr <- list(
id = ctrl.id,
U = createControl(U),
U = CreateControl(U),
Unames = U,
Y = createControl(Y),
Y = CreateControl(Y),
Ynames = Y,
FUN = FUN
)
......@@ -57,12 +65,12 @@ CreateController <- function(supervisor, ctrl.id, Y, U, FUN){
#'
#' @return [matrix] with each column being the location of the variables and the rows being
#' the values of the variable for the current time steps (empty by default)
#' @export
#' @noRd
#'
#' @examples
#' # For pointing the discharge at the oulet of basins "54095" and "54002"
#' createControl(c("54095", "54002"))
createControl <- function(locations) {
#' CreateControl(c("54095", "54002"))
CreateControl <- function(locations) {
if(!is.character(locations)) {
stop("Parameter `locations` should be character")
}
......
......@@ -84,13 +84,13 @@ CreateGRiwrm <- function(db,
#' @param coltypes named [list] with the name of the columns to check as key and the required type as value
#'
#' @return [NULL] or error message if a wrong type is detected
#' @export
#' @examples
#' CheckColumnTypes(
#' data.frame(string = c("A"), numeric = c(1), stringsAsFactors = FALSE),
#' list(string = "character", numeric = "double")
#' )
#'
#' @noRd
CheckColumnTypes <- function(df, coltypes) {
lapply(names(df), function(x) {
if (typeof(df[[x]]) != coltypes[[x]]) {
......@@ -112,6 +112,7 @@ CheckColumnTypes <- function(df, coltypes) {
#' @param griwrm \[object of class `GRiwrm`\] see [CreateGRiwrm] for details
#'
#' @return [numeric] ordered node names
#' @noRd
getNodeRanking <- function(griwrm) {
if (!inherits(griwrm, "GRiwrm")) {
stop("getNodeRanking: griwrm argument should be of class GRiwrm")
......
#' Creation of the \emph{GRiwrmInputsCrit} object for the **airGRiwrm** ErrorCrit functions.
#'
#' This function does the same operations as [airGR::CreateInputsCrit] for all sub-basins of the GRiwrm model. It creates the InputsCrit object required to the ErrorCrit_ functions but for the **airGRiwrm** package. This function is used to define whether the user wants to calculate a single criterion, multiple criteria at the same time, or a composite criterion, which averages several criteria.
#'
#' @param InputsModel \[object of class \emph{GRiwrmInputsModel}\] see [CreateInputsModel.GRiwrm] for details
#' @param FUN_CRIT \[function (atomic or list)\] error criterion function (e.g. [airGR::ErrorCrit_RMSE], [airGR::ErrorCrit_NSE])
#' @param RunOptions \[object of class \emph{GRiwrmRunOptions}\] see [CreateRunOptions.GRiwrmInputsModel] for details
#' @param Obs [matrix] or [data.frame] series of observed flows. Column names must correspond to nodes ID
#' @param ... further arguments passed to [airGR::CreateInputsCrit]
#'
#' @return [list] Object of class \emph{GRiwrmInputsCrit} containing `airGR::InputsCrit` objects (See [airGR::CreateInputsCrit])
#' @rdname CreateInputsCrit
#' @export
CreateInputsCrit.GRiwrmInputsModel <- function(InputsModel,
FUN_CRIT = airGR::ErrorCrit_NSE,
......
#' Wrapper to [airGR::CreateInputsCrit] for one sub-basin.
#'
#' @inherit airGR::CreateInputsCrit
#' @param ... Further arguments for compatibility with S3 method
#' @rdname CreateInputsCrit
#' @export
CreateInputsCrit.InputsModel <- function(InputsModel,
FUN_CRIT,
......
#' Creation of the InputsCrit object required to the ErrorCrit functions
#'
#' Creation of the InputsCrit object required to the ErrorCrit functions either for \emph{InputsModel} or for \emph{GRwirmInputsModel} objects
#' Creation of the InputsCrit object required to the `ErrorCrit` functions
#'
#' @param InputsModel InputsModel for **airGRiwrm** (See \code{[CreateInputsModel.GRiwrmInputsModel]}) or **airGR** (See [airGR::CreateInputsModel])
#' @param ... further arguments passed to or from other methods.
#' This function can be used either for a catchment (with an \emph{InputsModel} object) or for a network (with a \emph{GRiwrmInputsModel} object)
#'
#' @return Either a `InputsCrit` or a `GRiwrmInputsCrit` object
#' @param InputsModel object of class \emph{InputsModel} or \emph{GRwirmInputsModel}. See [CreateInputsModel]
#' @param FUN_CRIT \[function (atomic or list)\] error criterion function (e.g. [airGR::ErrorCrit_RMSE], [airGR::ErrorCrit_NSE])
#' @param RunOptions object of class \emph{RunOptions} or \emph{GRiwrmRunOptions}, see [CreateRunOptions]
#' @param Obs [numeric], [matrix] or [data.frame] series of observed flows, see details
#' @param ... arguments passed to [airGR::CreateInputsCrit], see details
#'
#' @details See [airGR::CreateInputsCrit] documentation for a complete list of arguments.
#'
#' `Obs` argument is equivalent to the same argument in [airGR::CreateInputsCrit] except that it must a [matrix] or a [data.frame] if `InputsModel` is a \emph{GRiwrmInputsModel} object. Then, each column of the [matrix] or [data.frame] represents the observations of one of the simulated node with the name of the columns representing the id of each node.
#'
#' With a \emph{GRwirmInputsModel} object, all arguments are applied on each sub-catchments of the network.
#'
#' @return Depending on the class of `InputsModel` argument (respectively `InputsModel` and `GRiwrmInputsModel` object), the returned value is respectively:
#' - a `InputsCrit` object (See [airGR::CreateInputsCrit])
#' - a `GRiwrmInputsCrit` object which is a [list] of `InputsCrit` object with one item per modelled sub-catchment
#'
#' @rdname CreateInputsCrit
#' @export
CreateInputsCrit <- function(InputsModel, ...) {
UseMethod("CreateInputsCrit", InputsModel)
......
......@@ -18,7 +18,7 @@
#'
#' See [airGR::CreateInputsModel] documentation for details concerning each input.
#'
#' @return GRiwrmInputsModel object equivalent to **airGR** InputsModel object for a semi-distributed model (See [airGR::CreateInputsModel])
#' @return A \emph{GRiwrmInputsModel} object which is a list of \emph{InputsModel} objects created by [airGR::CreateInputsModel] with one item per modelled sub-catchment.
#' @export
#' @examples
#' ##################################################################
......
#' Creation of the \emph{GRiwrmRunOptions} object for running and calibrating a model in **airGRiwrm**.
#'
#' @param InputsModel \[object of class \emph{GRiwrmInputsModel}\] see [CreateInputsModel.GRiwrm] for details
#' @param ... further arguments passed to [airGR::CreateRunOptions]
#'
#' @return [list] object of class \emph{GRiwrmRunOptions} containing a \emph{RunOptions} (See [airGR::CreateRunoptions]) object by hydrological node
#' @rdname CreateRunOptions
#' @export
#' @inherit RunModel.GRiwrmInputsModel return examples
#'
CreateRunOptions.GRiwrmInputsModel <- function(InputsModel, ...) {
RunOptions <- list()
......
#' Wrapper for [airGR::CreateRunOptions] for one sub-basin
#'
#' @param InputsModel \[object of class \emph{InputsModel}\] see [airGR::CreateInputsModel] for details
#' @param ... Arguments passed to [airGR::CreateRunOptions]
#' @rdname CreateRunOptions
#' @export
CreateRunOptions.InputsModel <- function(InputsModel, ...) {
......
#' Creation of the \emph{RunOptions} object for either **airGR** or **airGRiwrm**.
#' Creation of the CalibOptions object
#'
#' See [airGR::CreateRunOptions] and [CreateRunOptions.GRiwrmInputsModel] for usage
#' This function can be used either for a catchment (with an \emph{InputsModel} object) or for a network (with a \emph{GRiwrmInputsModel} object)
#'
#' @param InputsModel \[object of class \emph{InputsModel} (see [airGR::CreateInputsModel]) or \emph{GRiwrmInputsModel} (See [CreateInputsModel.GRiwrm])\]
#' @param ... further arguments passed to or from other methods
#' @param InputsModel object of class \emph{InputsModel} or \emph{GRwirmInputsModel}. See [CreateInputsModel] for details
#' @param ... arguments passed to [airGR::CreateRunOptions], see details
#'
#' @return Object of \emph{RunOptions} class family
#' @details See [airGR::CreateRunOptions] documentation for a complete list of arguments.
#'
#' With a \emph{GRwirmInputsModel} object, all arguments are applied on each sub-catchments of the network.
#'
#' @return Depending on the class of `InputsModel` argument (respectively `InputsModel` and `GRiwrmInputsModel` object), the returned value is respectively:
#' - a `RunOptions` object (See [airGR::CreateRunOptions])
#' - a `GRiwrmRunOptions` object which is a [list] of `RunOptions` object with one item per modelled sub-catchment
#'
#' @rdname CreateRunOptions
#' @export
#' @inherit RunModel.GRiwrmInputsModel return examples
CreateRunOptions <- function(InputsModel, ...) {
UseMethod("CreateRunOptions", InputsModel)
}
......@@ -3,7 +3,12 @@
#' @param InputsModel \[object of type `GRiwrmInputsModel`\] inputs of the model
#' @param TimeStep [numeric] number of time steps between each supervision
#'
#' @return `Supervisor` object
#' @return A `Supervisor` object which is an [environment] containing all the necessary variables to run a supervised simulation, such as:
#' - `DatesR` [POSIXct]: vector of date from `InputsModel`
#' - `InputsModel`: a copy of `InputsModel` provided by [CreateInputsModel.GRiwrm]
#' - `griwrm`: a copy of `griwrm` provided by [CreateGRiwrm]
#' - `Controllers` [list]: list of the controllers used in the supervised simulation (See [CreateController])
#' - some internal state variables updated during simulation (`ts.index`, `ts.previous`, `ts.date`, `ts.index0`, `controller.id`)
#' @export
#'
#' @examples
......
......@@ -3,7 +3,7 @@
#' @param x \[object of class \emph{GRiwrmInputsModel}\] see [CreateInputsModel.GRiwrm] for details
#' @param RunOptions \[object of class \emph{GRiwrmRunOptions}\] see [CreateRunOptions.GRiwrmInputsModel] for details
#' @param Param [list] parameter values. The list item names are the IDs of the sub-basins. Each item is a [numeric] [vector]
#' @param ... Mandatory for S3 method signature function compatibility with generic.
#' @param ... Further arguments for compatibility with S3 methods
#'
#' @return [[list] of class \emph{GRiwrmOutputsModel}] list of \emph{OutputsModel} objects (See \[airGR::RunModel]) for each node of the semi-distributed model
#' @export
......
#' Wrapper for [airGR::RunModel] for one sub-basin
#'
#' @inherit airGR::RunModel
#' @inheritParams airGR::RunModel
#' @param x \[object of class \emph{InputsModel}\] see [airGR::CreateInputsModel] for details
#' @param ... Further arguments for compatibility with S3 method
#' @param ... Further arguments for compatibility with S3 methods
#'
#' @export
RunModel.InputsModel <- function(x, RunOptions, Param, FUN_MOD = NULL, ...) {
if(is.null(FUN_MOD)) {
......
......@@ -3,7 +3,7 @@
#' @param x \[object of class `Supervisor`\] see [CreateSupervisor] for details
#' @param RunOptions \[object of class \emph{GRiwrmRunOptions}\] see \code{[CreateRunOptions.GRiwrm]} for details
#' @param Param [list] parameter values. The list item names are the IDs of the sub-basins. Each item is a vector of numerical parameters
#' @param ... Mandatory for S3 method signature function compatibility with generic
#' @param ... Further arguments for compatibility with S3 methods
#'
#' @return \emph{GRiwrmOutputsModel} object which is a list of \emph{OutputsModel} objects (See [airGR::RunModel]) for each node of the semi-distributed model
#' @export
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment