hydroVerification: Verification of a optimised model

In hydroMOPSO: Multi-Objective Calibration of Hydrological Models using MOPSO

Verification of a optimised model

Description

It takes the optimisation results of a model and reruns the simulations in a verification period. Only applicable when the results of the previous optimisation were done with fn=='hydromod' | fn=='hydromodInR'

Usage

hydroVerification(Results,
                  fn = NULL,
                  control = list(),
                  model.FUN = NULL,
                  model.FUN.args = list())

Arguments

Results	(list) List with hydroMOPSO optimisation results. The details of this input are explained in the value returned by hydroMOPSO function
fn	(function or character) Object with the name of a valid R function to be optimised (minimised or maximised). When the goal is to optimise just simple functions (problems not associated with models with input and output data), it is possible to specify the name of any function correctly defined by the user. Special cases occur when the user is working with models, declared as internal or external functions of R. In these last cases, fn='hydromod' specifies that the optimisation is applied to a model that can be invoked from R(tipically, an executable file that must be run from the system console), but is executed entirely outside of this environment. On the other hand, fn='hydromodInR' specifies that the optimisation is applied to a model that can be executed within the R environment. In detail: -) When fn!='hydromod' & fn!='hydromodInR', the first argument of fn has to be a vector of parameters over which optimisation is going to take place. It must return a vector with as many elements as objectives have been set in the function, and where each objective must be a scalar result. In this case, the algorithm uses the vector of values returned by fn as both model output and its corresponding set of optimised scalar results -) When fn=='hydromod' the algorithm will optimise the R-external model defined by model.FUN and model.args, which are used to extract the values simulated by the model and to compute its corresponding goodness-of-fit measures. -) When fn=='hydromodInR' the algorithm will optimise the R model defined by model.FUN and model.args, which are used to extract the values simulated by the model and to compute its corresponding goodness-of-fit measures. When fn=='hydromod' | fn=='hydromodInR', the function must return a list with two (2) specific elements, the first element of the list consists of the vector with as many elements as objectives have been established in the function, and where each objective must be a scalar result; the second element of the list corresponds to a matrix with the raw output data of the model that determines the scalar results of the objectives, for example time series of a hydrological model such as streamflow, evapotranspiration, soil moisture, among others. The matrix with the raw output data of the model must have as many columns as there are simulated variables being worked on in the optimisation, and this number of variables should not necessarily coincide with the number of objectives set. for example, flows could only be returned from a hydrological model to analyze three objectives.
control	(list) A list of control parameters. See ‘Details’
model.FUN	(character) (OPTIONAL) Used only when fn=='hydromod' | fn=='hydromodInR' A valid R function representing the model code to be optimised
model.FUN.args	(list) (OPTIONAL) Used only when fn=='hydromod' | fn=='hydromodInR' A list with the arguments to be passed to model.FUN

Value

(list)

ParticlesFull

(data.frame)
History of positions of each Pareto Front particles in all iterations. In this data.frame, the first column indicates the simulation number Sim, in ascending order from the first simulation (first iteration, phase 1) to the last simulation (last iteration, phase 2); then as many columns as objectives treated, being identified with the assigned name; and finally, as many columns as decision variables (parameters).

FilledPOF

(data.frame)
Filled Pareto front degraded in verification period. Keep in mind that strictly speaking this is not a Pareto Front since it is reached only by extending the solutions of the original front obtained by calibration to a verification period.

ParticlesFilledPOF

(data.frame)
Perticles from filled Pareto Front. In this data.frame, the first column indicates the simulation number Sim; then as many columns as objectives treated, being identified with the assigned name; and finally, as many columns as decision variables (parameters). Note that in the objective columns the original calibration values have been replaced by those of the filled Pareto front degraded in verification period.

ModelOut

(list)
Time series of the model output variables in verification period, for all solutions of the filled Pareto Front obtained in calibration period. This list has as many objects as output variables, and each one corresponds to an object of class zoo with as many columns as solutions of the filled Pareto Front.

ParticleBestCS

(data.frame)
Best compromise solution, i.e., the solution with the minimum Euclidean distance from the maximum values of each objective, in calibration period. data.frame with only one row and several columns: the first column indicates the simulation number Sim; then as many columns as objectives treated, being identified with the assigned name; and finally, as many columns as decision variables (parameters). Note that in the objective columns the original calibration values have been replaced by those obtained in the verification period.

ModelOutBestCS

(list)
Time series of the model output variables in verification period, just for the best compromise solution obtained in calibration period. This list has as many objects as output variables, and each one corresponds to an object of class zoo with a single time serie.

ParticleBestObjs

(list)
Solutions that minimise/maximise each of the objectives, obtained in calibration period. data.frame with only one row. In a first level, this list has as many objects as objectives involves in the optimisation, each one with a data.frame with only one row and several columns: the first column indicates the simulation number Sim; then as many columns as objectives treated, being identified with the assigned name; and finally, as many columns as decision variables (parameters). Note that in the objective columns the original calibration values have been replaced by those obtained in the verification period.

ModelOutBestObjs

(list)
Time series of the model output variables in verification period, for the maximisation/minimisation of each objective in calibration. In a first level, this list has as many objects as objectives involves in the optimisation and, in a second level, each one corresponds to a list with as many objects as output variables, each one corresponding to an object of class zoo with a single time serie.

AnalysisPeriod

(character)
String indicating the analysis period, in this case "verification".

DigitsDom

(numeric)
Number of decimal places used in dominance check. Fewer decimal places (say, 16, 8, or 4, for example) may be necessary to prevent the algorithm from resulting in solutions that are nearly the same.

ObjsNames

(data.frame)
Name of each of the objectives (Obj1, Obj2, ...).

MaxMin

(data.frame)
Specification on whether the objectives are maximised or minimised, must be in c("max", "min").

Obs

(list)
Observed values of each of the variables involved in the optimisation, but now of the verification period. Keep in mind that the same format indicated as mandatory input data Obs within the FUN function is maintained.

Dimensions

(data.frame)
Number of objectives and number of output variables involved in the optimisation.

NamesAndUnitsVars

(data.frame)
Name and unit of measure of the output variables involved in the optimisation (var1, var1_unit, var2, var2_unit, ...).

WarmUp

(data.frame)
Time series indicating the warm-up period used in the optimisation.

DatesCal

(data.frame)
Time series indicating the calibration period used in the optimisation.

Note

1) The intended workflow is that first you must have the results of the optimisation done with the hydroMOPSO function, which are then entered into this function (hydroVerification)

Author(s)

Rodrigo Marinao Rivas [e-mail], Mauricio Zambrano-Bigiarini, [e-mail]

See Also

hydroMOPSO

hydroMOPSO documentation built on April 26, 2023, 1:14 a.m.