hymod.sim: Function to simulate/predict a river flow serie by applying...

In albertomontanari/hymodbluecat: An R-package for the hydrological model HyMOD with parameter optimisation and uncertainty assessment with the BLUECAT method in calibration and validation

Description

The function calls a Fortran subroutine to make the computation of the simulated river flows and applies at each time step the BLUECAT method for uncertainty estimation. It requires the libraries "devtools", "DescTools" and "DEoptim" if the optimisation routine DEoptim is used (see below).

Usage

hymod.sim<-function(param,area,tdelta,e,p,resultcalib=NULL,nstep=length(p),qinitial=0,bluecat=F,predsmodel="avg",empquant=F,siglev=0.2,m=100,m1=80,paramd=c(0.1,1,10,NA),lowparamd=c(0.001,0.001,0.001,0),upparamd=c(1,5,20,NA),NSeff=F,qoss=NULL,plot=F,cpptresh=0)

Arguments

param	Vector of the 5 Hymod parameters Cmax, beta, alpha, ks, kq. It can be taken from the output from hymod.par
area	The catchment contributing area given in square kilometers.
Tdelta	The model time step given in seconds.
e	Vector of potential evapotranspiration. It should have the same length as p.
p	Vector of mean areal rainfall. It should have the same length as e.
resultcalib	It is the output from hymod.sim. To be provided only if uncertainty estimation is requested, namely, if bluecat=T.
nestep	Number of simulation time steps. Default value is the length of the precipitation record p.
qinitial	Initial value of river flow. Default is zero.
bluecat	Logical variable to specify if uncertainty estimation is to be performed. Default is bluecat=F.
predsmodel	Character variable to specify if stochastic prediction is generated by the mean (predsmodel="avg") or the median (predsmodel="mdn") of the conditional distribution. Default is predsmodel="avg".
empquant	Logical variable to specify if empirical quantiles or robust estimation is to be used for estimating confidence limits. Default is robust estimation, namely, empquant=F.
siglev	Significance level for confidence limits estimation. Default is siglev=0.1
m	Parameter to determine the sample size of river flow neighbours to be used for estimating the probability distribution of true river flow conditioned to the simulated river flow. Default is m=100.
m1	Number of k-moments used to estimate the PBF distribution on the sample of mean stochastic prediction to make robust quantile estimation. Default is m1=80.
paramd	Initial parameter values for the PBF distribution fitting the sample of mean stochastic prediction to make robust quantile estimation. Default is paramd=c(0.1,1,10,NA).
lowparamd	Lower bound for the parameter values of the PBF distribution fitting the sample of mean stochastic prediction to make robust quantile estimation. Default is lowparamd=c(0.001,0.001,0.001,0).
upparamd	Upper bound for the parameter values of the PBF distribution fitting the sample of mean stochastic prediction to make robust quantile estimation. Default is upparamd=c(1,5,20,NA).
NSeff	Logical variable to specify if the routine should return efficiency (Nash and Sutcliffe, 1968) only for the simulation. Default value is eff=F. If eff=T efficiency only for the deterministic model prediction is returned as a single number.
qoss	Vector of observed river flow in cubic meters per second if available. It is not necessary for uncertainty estimation. If provided, it must have the same length as the vector or precipitation p.
plot	Logical value. Specifies if diagnostic is to be returned. Default is plot=F. If plot=T a scapperplot of observed versus simulated by the stochastic model river flows is returned along with its efficiency. The diagnostic plots are also returned, along with the percentage of observations lying outside the confidence bands.
cpptresh	Low flow threshold to draw the diagnostic plots and to compute percentage of points lying outside the confidence band. Default value is cpptresh=0, which means that zero values for the simulated river flow are not considered when drawing the plots and computing percentages.

Details

HyMod is a five-parameter conceptual rainfall-runoff model that was introduced by Boyle (2000). The model is based on the probability-distributed soil storage capacity principle introduced by Moore (1985). In HyMod, the rainfall-runoff process is represented through a nonlinear tank connected with three identical linear tanks in parallel representing one routing component and another single linear tank representing a second routing component. The model requires the optimization of five parameters: Cmax (the maximum storage capacity within the watershed), beta (the degree of spatial variability of the soil moisture capacity within the watershed), alpha (a factor for partitioning the flow between two series of tanks) and the two residence time parameters of quick-flow and slow-flow tanks, kq and ks respectively. The input data consist of precipitation and potential evapotranspiration at the given time scale. Uncertainty for the HyMod simulation is estimated by applying BLUECAT, "A Brisk Local Uncertainty Estimator for Hydrologic Simulations and Predictions", introduced by Koutsoyiannis and Montanari (2021). BLUECAT estimates the lower and upper confidence limits of the HyMod simulation for a given confidence level. Goodness of fit testing for BLUECAT is performed by plotting a scatterplot of observed river flow against the mean stochastic simulation obtained with BLUECAT along with the related confidence limits, by plotting the Coverage Probability Plot and computing the Prediction Technical Performance indexes as in Koutsoyiannis and Montanari (2021).

Value

If eff=T a single numerical correspoding to the Nash-Sutcliffe (1968) efficiency is returned if qoss is given (otherwise an error is reported). If eff=F and bluecat=F a list with the following items is returned:

outputlist$q_slow	Slow flow component simulated by HyMod.
outputlist$q_quick	Quick flow component simulated by HyMod.
outputlist$q_tot	River flow simulated by HyMod.
outputlist$medpred	River flow obtained as mean stochastic simulation.
outputlist$infpred	Lower confidence limit obtained with BLUECAT.
outputlist$suppred	Upper confidence limit obtained with BLUECAT.
effdmodel	The Nash Sutcliffe efficiency of the simulation by the deterministic model. This is returned only if qoss is given.

If eff=F and bluecat=T a list with the following items is returned:

outputlist$q_slow	Slow flow component simulated by HyMod.
outputlist$q_quick	Quick flow component simulated by HyMod.
outputlist$q_tot	River flow simulated by HyMod.
effsmodel	The Nash Sutcliffe efficiency of the simulation given by the mean stochastic prediction. This is returned only if qoss is given.

Author(s)

Demetris Koutsoyiannis and Alberto Montanari, email: [e-mail].

References

Boyle, D.P., (2000), Multicriteria calibration of hydrological models, Ph.D. dissertation, Dep. of Hydrol. and Water Resour., Univ of Arizona, Tucson.

Koutsoyiannis, D. and Montanari, A. (2021), Bluecat: A Brisk Local Uncertainty Estimator for Hydrologic Simulations and Predictions, submitted manuscript, 2021.

Moore, R.J., (1985), The probability-distributed principle and runoff production at point and basin scale, Hydrol. Sci. J., 30(2), 273-297.

Nash, J. E., and Sutcliffe, J. V., (1970), River flow forecasting through conceptual models part I – A discussion of principles, J. Hydrol., 10, 282–290, doi: 10.1016/0022-1694(70)90255-6. 

Examples

## Load data
data(arnosubbiano)

## Model parameterisation with hymod.par
pr1=hymod.par(c(100,1,0.5,200,0.5),area=752,tdelta=86400,e=arnosubbiano[,3][1:7305],p=arnosubbiano[,2][1:7305],nstep=length(arnosubbiano[,2][1:7305]),qoss=arnosubbiano[,4][1:7305],qinitial=15,lower=c(10,0.1,0.1,0.1,0.1),upper=c(800,10,0.9,1000,100),opt="DEoptim",lambdaln=0.0001)

## Run BLUECAT to perform simulation in calibration mode
pr2=hymod.sim(pr1$optim$bestmem,area=752,tdelta=86400,e=arnosubbiano[,3][1:7305],p=arnosubbiano[,2][1:7305],qinitial=15,qoss=arnosubbiano[,4][1:7305],resultcalib=pr1,bluecat=T,empquant=F,plot=T,m=100,predsmodel="mdn")
## Run BLUECAT to perform simulation in validation mode
pr3=hymod.sim(pr1$optim$bestmem,area=752,tdelta=86400,e=arnosubbiano[,3][7306:8036],p=arnosubbiano[,2][7306:8036],qinitial=15,qoss=arnosubbiano[,4][7306:8036],resultcalib=pr1,bluecat=T,empquant=F,plot=T,m=100,predsmodel="mdn")

albertomontanari/hymodbluecat documentation built on Jan. 20, 2022, 10:42 p.m.