ReadResults: Reading the output files of a optimised model

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

Reading the output files of a optimised model

Description

Read results saved on disk from an optimization with hydroMOPSO. This feature only applies when fn is in c("hydromod", "hydromodInR")

Usage

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

Arguments

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

Details

The control argument is a list that can supply any of the following components:

drty.in

(character)
(OPTIONAL) Used only when fn='hydromod'
Name of the directory storing the input files required for PSO, i.e. ‘ParamRanges.txt’ and ‘ParamFiles.txt’.

drty.out

(character)
Path to the directory storing the output files generated by hydroMOPSO.

digits

(numeric)
(OPTIONAL) Used only when write2disk=TRUE
Number of significant digits used for writing the output files with scientific notation.

digits.dom

(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.
By default digits.dom=Inf, which basically means numbers are not rounded

write2disk

(logical)
Indicates if the output files will be written to the disk.
By default write2disk=TRUE

verbose

(logical)
Indicates if progress messages are to be printed.
By default verbose=TRUE

REPORT

(integer)
(OPTIONAL) Used only when verbose=TRUE
The frequency of report messages printed to the screen.
By default REPORT=10

parallel

(character)
Indicates how to parallelise ‘hydroMOPSO’ (to be precise, only the evaluation of the objective function fn is parallelised). Valid values are:
-)none: no parallelisation is made (this is the default value)
-)parallel: parallel computations for network clusters or machines with multiple cores or CPUs. A ‘FORK’ cluster is created with the makeForkCluster function. When fn.name='hydromod' the evaluation of the objective function fn is done with the clusterApply function of the parallel package. When fn.name != 'hydromod' the evaluation of the objective function fn is done with the parRapply function of the parallel package.
-)parallelWin: parallel computations for network clusters or machines with multiple cores or CPUs (this is the only parallel implementation that works on Windows machines). A ‘PSOCK’ cluster is created with the makeCluster function. When fn.name='hydromod' the evaluation of the objective function fn is done with the clusterApply function of the parallel package. When fn.name != 'hydromod' the evaluation of the objective function fn is done with the parRapply function of the parallel package.

par.nnodes

(numeric)
(OPTIONAL) Used only when parallel!='none'
Indicates the number of cores/CPUs to be used in the local multi-core machine, or the number of nodes to be used in the network cluster.
By default par.nnodes is set to the amount of cores detected by the function detectCores() (parallel package)

par.pkgs

(character)
(OPTIONAL) Used only when parallel='parallelWin'
List of package names (as characters) that need to be loaded on each node for allowing the objective function fn to be evaluated.

Value

(list)

MOPSOResults

(list)
Particle repository history of all iterations (both phases of NMPSO), detailing:

- ParetoFront (data.frame)
History of objectives values of each Pareto Front particles in all iterations (both phases). In this data.frame, the first column indicates the iteration Iter; the second column the phase Phase (1 or 2); and the following columns are as many as objectives treated, being identified with the assigned name.
- Particles_ParetoFront (data.frame)
History of positions of each Pareto Front particles in all iterations (both phases). In this data.frame, the first column indicates the iteration Iter; the second column the phase Phase (1 or 2); then as many columns as objectives treated, being identified with the assigned name; and finally, as many columns as decision variables (parameters).
- MaxMin (data.frame)
Specification on whether the objectives are maximised or minimised.
- ObjsNames (data.frame)
Name of each of the objectives (Obj1, Obj2, ...).

hydroDetails

(list)
(ONLY ADDED WHEN fn=='hydromod' | fn=='hydromodInR')
Details about the modeling involved in optimisation:

- 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, ...).
- Obs (list)
Observed values of each of the variables involved in the optimisation, keeping in mind that the same format indicated as mandatory input data Obs within the FUN function is maintained.
- 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.

hydroResults

(list)
(ONLY ADDED WHEN fn=='hydromod' | fn=='hydromodInR')
Post-processed results about the modeling involved in optimisation:

- 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, built from evaluating the dominance of the solutions of all the iterations performed in the optimisation. To prevent the filled Pareto Front from having too many solutions, the parameters and objective values are rounded according to input DigitsDom (number of decimal places). 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.
- 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).
- ModelOut (list)
Time series of the model output variables, for all solutions of the filled Pareto Front. 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. 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).
- ModelOutBestCS (list)
Time series of the model output variables, just for the best compromise solution. 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. 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).
- ModelOutBestObjs (list)
Time series of the model output variables, for the maximisation/minimisation of each objective. 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 "calibration".
- 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, keeping 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, having saved the results to disk (write2disk=TRUE in hydroMOPSO)
2) Based on the previous point, the user must ensure that the input arguments fn, control, model.FUN and model.FUN.args that are entered in the hydroMOPSO and ReadResults functions must be EXACTLY THE SAME

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.