ReadPlot_particles: Reading/Plotting the 'Particles.txt' output file
In hydroPSO: Particle Swarm Optimisation, with Focus on Environmental Models

Description Usage Arguments Value Author(s) See Also Examples

The function read_particles reads the ‘Particles.txt’ output file, which stores all the parameter sets tested during the optimisation along with their corresponding goodness-of-fit values

The function plot_particles takes the parameter sets and their corresponding goodness-of-fit value, read by read_particles, and produces the following plots:
1) Dotty plots
2) Histograms
3) Boxplots
4) Correlation matrix (optional)
5) Empirical CDFs
6) Parameter values vs Number of Model Evaluations
7) (pseudo) 3D dotty plots

read_particles(file="Particles.txt", verbose=TRUE, plot=TRUE,
     gof.name="GoF", MinMax=NULL, beh.thr=NA, beh.col="red", beh.lty=1, 
     beh.lwd=2, nrows="auto", col="black", ylab=gof.name, main=NULL, 
     pch=19, cex=0.5, cex.main=1.5, cex.axis=1.5, cex.lab=1.5, 
     
     breaks="Scott", freq=TRUE, do.pairs=FALSE, 
     dp3D.names="auto", GOFcuts="auto", 
     colorRamp= colorRampPalette(c("darkred", "red", "orange", "yellow", 
     "green", "darkgreen", "cyan")), alpha=1, points.cex=0.7,
     legend.pos="topleft", do.png=FALSE, png.width=1500, 
     png.height=900, png.res=90, 
     dotty.png.fname="Params_DottyPlots.png", 
     hist.png.fname="Params_Histograms.png",
     bxp.png.fname="Params_Boxplots.png",
     ecdf.png.fname="Params_ECDFs.png", 
     runs.png.fname="Params_ValuesPerRun.png",
     dp3d.png.fname="Params_dp3d.png", 
     pairs.png.fname="Params_Pairs.png")
           
plot_particles(params, gofs, gof.name="GoF", MinMax=NULL, beh.thr=NA,  
     beh.col="red", beh.lty=1, beh.lwd=2, nrows="auto", col="black",  
     ylab=gof.name, main=NULL, pch=19, cex=0.5, cex.main=1.5,  
     cex.axis=1.5, cex.lab=1.5,
     
     breaks="Scott", freq=TRUE, do.pairs=FALSE,                          
     weights=NULL, byrow=FALSE, leg.cex=1.5, 
     dp3D.names="auto", GOFcuts="auto", 
     colorRamp= colorRampPalette(c("darkred", "red", "orange", "yellow", 
     "green", "darkgreen", "cyan")), alpha=1, points.cex=0.7, 
     legend.pos="topleft", verbose=TRUE,  
     do.png=FALSE, png.width=1500, png.height=900, png.res=90, 
     dotty.png.fname="Params_DottyPlots.png", 
     hist.png.fname="Params_Histograms.png",
     bxp.png.fname="Params_Boxplots.png",
     ecdf.png.fname="Params_ECDFs.png", 
     runs.png.fname="Params_ValuesPerRun.png",
     dp3d.png.fname="Params_dp3d.png", 
     pairs.png.fname="Params_Pairs.png")
     
read_velocities(file="Velocities.txt", ... )

`file`	character, name (including path) of the output file with the position and fitness value of each particle and for each iteration
`params`	data.frame whose rows represent the values of different parameter sets
`gofs`	OPTIONAL. numeric with the values of goodness-of-fit values for each parameter in `params` (in the same order!)
`verbose`	logical, if TRUE, progress messages are printed
`plot`	logical, indicates if the following figures has to be produced: dotty plots, histograms, empirical CDFs, Parameter Values Against Number of Model Evaluations, and 3D dotty plots of Parameter Values
`gof.name`	character, name to be given to the goodness-of-fit values in all the plots
`MinMax`	OPTIONAL. character, indicates if the optimum value in `params` corresponds to the minimum or maximum of the the objective function. Only used to identify the optimum in the plot Valid values are in: `c('min', 'max')`
`beh.thr`	numeric, used for selecting only the behavioural parameter sets, i.e. those with a goodness-of-fit value greater/less than or equal to `beh.thr`, depending on the value of `MinMax` By default `beh.thr=NA` and all the parameter sets are considered for the subsequent anlysis
`beh.col`	OPTIONAL. Only used when `plot=TRUE` character, colour for drawing a horizontal line for separating behavioural from non behavioural parameter sets
`beh.lty`	OPTIONAL. Only used when `plot=TRUE` numeric, line type for drawing a horizontal line for separating behavioural from non behavioural parameter sets
`beh.lwd`	OPTIONAL. Only used when `plot=TRUE` numeric, width for drawing a horizontal line for separating behavioural from non behavioural parameter sets
`nrows`	OPTIONAL. Only used when `plot=TRUE` numeric, number of rows to be used in the plotting window If `nrows`is set to `auto`, the number of rows is automatically computed depending on the number of columns of `params`
`col`	OPTIONAL. Only used when `plot=TRUE` character, colour for drawing the points of the dotty plots
`ylab`	OPTIONAL. Only used when `plot=TRUE` character, label for the 'y' axis
`main`	OPTIONAL. Only used when `plot=TRUE` character, title for the plot
`pch`	OPTIONAL. Only used when `plot=TRUE` numeric, type of symbol to be used for drawing the points of the dotty plots (e.g., 1: white circle)
`cex`	OPTIONAL. Only used when `plot=TRUE` numeric, values controlling the size of text and points with respect to the default
`cex.main`	OPTIONAL. Only used when `plot=TRUE` numeric, magnification for main titles relative to the current setting of `cex`
`cex.axis`	OPTIONAL. Only used when `plot=TRUE` numeric, magnification for axis annotation relative to the current setting of `cex`
`cex.lab`	OPTIONAL. Only used when `plot=TRUE` numeric, magnification for x and y labels relative to the current setting of `cex`
`...`	OPTIONAL. Only used when `plot=TRUE` further arguments passed to the plot command or from other methods
`breaks`	OPTIONAL. Only used when `plot=TRUE` breaks for plotting the histograms of the parameter sets. See `hist`
`freq`	OPTIONAL. Only used when `plot=TRUE` logical, if TRUE, the histogram graphic is a representation of frequencies, the counts component of the result; if FALSE, probability densities, component density, are plotted (so that the histogram has a total area of one). Defaults to TRUE if and only if breaks are equidistant (and probability is not specified). See `hist`
`do.pairs`	OPTIONAL. Only used when `plot=TRUE` logical, indicates whether a correlation matrix among parameters has to be plotted. If the number of parameter sets tried during the optimisation is large, it may require some time.
`weights`	OPTIONAL. Only used when `plot=TRUE` numeric vector, values of the weights to be used for computing the empirical CDFs. See `params2ecdf`
`byrow`	OPTIONAL. Only used when `plot=TRUE` logical, indicates whether the computations have to be made for each column or for each row of `params`. See `params2ecdf`
`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
`dp3D.names`	character, name of all the parameters (usually only the most sensitive ones) that will be used for plotting pseudo-3D plots If `dp3D.names='auto'` half the number of parameters in `file` are chosen randomly for plotting. See `plot_NparOF`
`GOFcuts`	numeric, specifies at which values of the objective function `gof.name` the colours of the plot have to change. See `plot_NparOF`
`colorRamp`	R function defining the colour ramp to be used for colouring the pseudo-3D dotty plots of Parameter Values, OR character representing those colours. See `plot_NparOF`
`alpha`	numeric between 0 and 1 representing the transparency level to apply to the colors of the pseudo-3D dotty plots. See `plot_NparOF`
`points.cex`	size of the points to be plotted
`legend.pos`	not used yet ...
`do.png`	logical, indicates if the plot with the convergence measures 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`

`dotty.png.fname`	OPTIONAL. Only used when `do.png=TRUE` character, filename used to store the PNG file with the dotty plots of the parameter values
`hist.png.fname`	OPTIONAL. Only used when `do.png=TRUE` character, filename used to store the PNG file with the histograms of the parameter values
`bxp.png.fname`	OPTIONAL. Only used when `do.png=TRUE` character, filename used to store the PNG file with the boxplots of the parameter values
`ecdf.png.fname`	OPTIONAL. Only used when `do.png=TRUE` character, filename used to store the PNG file with the empirical CDFs of the parameter values
`runs.png.fname`	OPTIONAL. Only used when `do.png=TRUE` character, filename used to store the PNG file with the parameter values vs the number of model evaluations
`dp3d.png.fname`	OPTIONAL. Only used when `do.png=TRUE` character, filename used to store the PNG file with the pseudo-3D plots of all the parameters defined in `dp3D.names`
`pairs.png.fname`	OPTIONAL. Only used when `do.png=TRUE` character, filename used to store the PNG file with the correlation matrix among the parameters and goodness-of-fit values in `params` and `gofs`. See `plot_params` and `hydropairs`

read_particles returns a list with four elements:

`part.params`	numeric or matrix/data.frame with the parameter values for each particle and iteration
`part.gofs`	numeric vector with the goodness-of-fit value for each particle and iteration
`best.param`	numeric with the parameter values of the best particle. In order to be computed, the user has to provide a valid value for `MinMax`
`best.gof`	numeric with the best godness-of-fit value among all the particles. In order to be computed, the user has to provide a valid value for `MinMax`

Mauricio Zambrano-Bigiarini, mzb.devel@gmail.com

read_results, plot_results, read_params, plot_params

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

# Number of dimensions to be optimised
D <- 4

# 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, write2disk=TRUE, plot=TRUE)  )   

# reading the 'Particles.txt' output file of hydroPSO, and plotting dotty plots, 
# histograms, eCDFs, ...
setwd("PSO.out")
particles <- read_particles()

# reading only the particles in 'Particles.txt' with a goodness-of-fit value
# lower than 'beh.thr'
particles <- read_particles(beh.thr=1000, MinMax="min")

## End(Not run)