ReadPlot_out: Reading/Plotting the 'Model_out.txt' output file of hydroPSO

In hzambran/hydroPSO: Particle Swarm Optimisation, with Focus on Environmental Models

Reading/Plotting the 'Model_out.txt' output file of hydroPSO

Description

This function reads the values of the objective function/model output for each particle and iteration with optional plot

Usage

read_out(file="Model_out.txt", modelout.cols=NULL, nsim=NULL, obs, MinMax=NULL, 
     beh.thr=NA,verbose=TRUE,plot=TRUE,ptype=c("corr","ts","ecdf","quant2ecdf"), 
     ftype="dm", FUN=mean, weights=NULL, byrow=TRUE,
     quantiles.desired= c(0.05,0.5,0.95), 
     quantiles.labels= c("Q5", "Q50", "Q95"), main=NULL, ylab="Probability", 
     col="blue", leg.cex=1.2, leg.pos="bottomright", 
     cex.axis=1.2, cex.main=1.2, cex.lab=1.2, do.png=FALSE, png.width=1500, 
     png.height=900, png.res=90, png.fname="ModelOut_vs_Obs.png")
plot_out(sim, obs, dates=NULL, ptype=c("corr","ts","ecdf","quant2ecdf"), 
     MinMax=NULL, ftype="o", FUN=mean, verbose=TRUE, weights=NULL, byrow=TRUE, 
     quantiles.desired= c(0.05,0.5,0.95), quantiles.labels=c("Q5","Q50","Q95"), 
     main=NULL, ylab="Probability", col="blue", leg.cex=1.2, 
     leg.pos="bottomright", cex.axis=1.2, cex.main=1.2, cex.lab=1.2, 
     do.png=FALSE, png.width=1500, png.height=900, png.res=90, 
     png.fname="ModelOut_vs_Obs.png")

Arguments

file	character, name (including path) of the output file with the values of the model / objective function for each particle and iteration
modelout.cols	numeric, column number in file that store the outputs that have to be read/plotted, without counting the first three that correspond to iteration, particle and goodness-of-fit value. If modelout.cols=NULL, all the columns in will be read, but the first three that contains the iteration number, the particle number and the corresponding goodness-of-fit.
nsim	OPTIONAL. number simulated equivalent values of the model / objective function to be compared against observations. It is only useful when the model to be calibrated returns NA instead of the simulated values for some parameter set(s) (e.g., MODFLOW). It is used to force read_out to read the columns 4 up to 4+nsim-1 of file
sim	numeric or zoo vector, simulated equivalent values of the model / objective function to be compared against observations
obs	OPTIONAL. numeric or zoo vector, observations to be compared against the best simulated value. If obs is not provided, its values are read from the output ‘Observations.txt’ file in the results directory (by default ‘PSO.out’)
dates	OPTIONAL. character or Date object used to assign time stamps to each element of sim and obs. If sim and/or obs already have a time stamp, it is over-written by dates It must have the same length of sim and obs numeric or zoo vectors
MinMax	OPTIONAL. character, indicates whether the optimum value corresponds to the minimum or maximum of the the objective function. It is used to filter out model outputs with a non-acceptable performance Valid values are in: c('min', 'max')
beh.thr	OPTIONAL. numeric, used for selecting only the behavioural parameter sets, i.e. those with a goodness-of-fit value larger/lower than beh.th, depending on the value of MinMax It is used for drawing a horizontal line used for separating behavioural from non behavioural parameter sets
verbose	logical, if TRUE, progress messages are printed
plot	logical, indicates if a plot with the convergence measures has to be produced
ptype	character, type of plot. Valid values are: -) corr: Scatterplot between the observed values and its best simulated counterpart -) ts: Only possible for observed values of zoo type. A graphical comparison between observed values and its best simulated counterpart along time. It requires the hydroGOF package. See ggof -) ecdf: Empirical CDFs computed and plotted for each column of sim -) quant2ecdf: For each model output corresponding to a different parameter set (in rows or columns of sim, according to the value of byrow), different quantiles are computed (as many as indicated in quantiles.desired, and then Empirical CDFs are computed and plotted for each one of the previous quantiles)
ftype	OPTIONAL. Only used when plot=TRUE and ptype=="ts".See ggof
FUN	OPTIONAL. Only used when plot=TRUE and ptype=="ts".See ggof
weights	numeric vector, values of the weights to be used for computing the quantiles. See quant2ecdf Omitting the weights argument or specifying NULL or a zero-length vector will result in the usual un-weighted estimates
byrow	logical, indicates whether the computations have to be made for each column or for each row of x. See quant2ecdf When the simulated equivalents are stored in columns, byrow must be TRUE When the simulated equivalents are stored in rows, byrow must be FALSE
quantiles.desired	numeric vector, quantiles to be computed for model outputs. Default values are c(.025, .5, .975) ( => 2.5%, 50%, 97.5% ). See quant2ecdf
quantiles.labels	OPTIONAL. Only used when plot=TRUE character vector, names to quantiles.desired. Default value is c("Q5", "Q50", "Q95"). See quant2ecdf
main	OPTIONAL. Only used when plot=TRUE title for the plot
ylab	OPTIONAL. Only used when plot=TRUE title for the y axis. See plot
col	OPTIONAL. Only used when plot=TRUE specification for the default plotting colour. See par
leg.cex	OPTIONAL. Only used when plot=TRUE character expansion factor *relative* to current 'par("cex")'. Used for text, and provides the default for 'pt.cex' and 'title.cex' Default value = 1.2
leg.pos	OPTIONAL. Only used when plot=TRUE keyword to be used to position the legend. See legend
cex.axis	OPTIONAL. Only used when plot=TRUE numeric, magnification to be used for the axis annotation relative to 'cex'. See par
cex.main	OPTIONAL. Only used when plot=TRUE numeric, representing the magnification to be used for main titles relative to the current setting of cex
cex.lab	OPTIONAL. Only used when plot=TRUE numeric, representing the magnification to be used for x and y labels relative to the current setting of 'cex'. See par
do.png	logical, indicates if the plot with the comparison between model outputs and observations has to be saved into a PNG file instead of the screen device
png.width	OPTIONAL. Only used when do.png=TRUE numeric, width of the device. See png
png.height	OPTIONAL. Only used when do.png=TRUE numeric, height of the device. See png
png.res	OPTIONAL. Only used when do.png=TRUE numeric, nominal resolution in ppi which will be recorded in the PNG file, if a positive integer of the device. See png
png.fname	OPTIONAL. Only used when do.png=TRUE character, name of the output PNG file. See png

Value

list with three elements:

model.values	matrix/data.frame (or numeric) with the values of the model / objective function for each particle and iteration
model.gofs	numeric vector with the goodness-of-fit value for each row (or value) in ‘model.values’
model.best	numeric with the best model / objective function value. In order to be computed, the user has to provide a valid value for MinMax
model.obs	numeric with the observed values used during the optimisation. See obs

Author(s)

Mauricio Zambrano-Bigiarini, [e-mail]

See Also

read_results, plot_results, quant2ecdf

Examples

## Not run: 
# Setting the user home directory as working directory
setwd("~")

# Number of dimensions to be optimised
D <- 5

# Boundaries of the search space (Sphere test function)
lower <- rep(-100, D)
upper <- rep(100, D)

# Setting the seed
set.seed(100)

# Runing PSO with the 'Sphere' test function, writting the results to text files
hydroPSO(fn=sphere, lower=lower, upper=upper,
        control=list(maxit=100, topology="gbest", write2disk=TRUE, plot=TRUE)  
        )

# Reading the convergence measures got by running hydroPSO
setwd("PSO.out")
read_out(MinMax="min") # each particle in a different pannel

## End(Not run)

hzambran/hydroPSO documentation built on Feb. 3, 2024, 4:39 p.m.