introduction
hydromad is an R package (i.e. a software package for the R statistical computing environment). It provides a modelling framework for environmental hydrology: water balance accounting and flow routing in spatially aggregated catchments. It supports simulation, estimation, assessment and visualisation of flow response to time series of rainfall and other drivers.
A minimal unit hydrograph framework is used, where areal rainfall is passed through a soil moisture accounting (SMA) model to estimate effective rainfall; this is then passed through a routing model to estimate streamflow. Included are several implementations of models consistent with this framework, notably the IHACRES CWI and CMD soil moisture accounting models, and unit hydrograph transfer functions for the routing.
This site serves as a reference for the R functions and datasets in the package. A gentler introduction can be found in the vignette hydromad tutorial and the paper An open software environment for hydrological model assessment and development (both included in the package). You can also look at the source code for the paper.
The package is maintained by Joseph Guillaume. The modelling approach is based on work by Tony Jakeman and Barry Croke at The Australian National University.
For more information, see
- installation instructions
- hydromad users group (questions and discussion).
- hydromad github repository (source code and bugs)
installation
The hydromad package is currently not available from CRAN. Eventually it should be on CRAN but there are unresolved issues of incomplete documentation and references to the unreleased dream package.
The steps required for installation are:
- Install R if you do not have a recent version (the most recent release is recommended).
- Install required packages from within R:
install.packages(c("zoo", "latticeExtra", "polynom", "car", "Hmisc","reshape")) - Install hydromad
install.packages("hydromad", repos="http://hydromad.catchment.org")
To instead download the package manually see: Windows binary and source. - Optionally install other packages required for certain functions:
install.packages("DEoptim")
install.packages("dream", repos="http://hydromad.catchment.org")
Once it is installed, get started with
library(package = "hydromad")
help("hydromad")
Please direct questions and discussion to the hydromad users group.
modelling framework
predict
Generate simulated time series from Hydromad model objects
simulate
Simulate hydromad models by parameter sampling.
One example:
levelplot(result ~ tw + f, sim1, cex = 2, panel = panel.levelplot.points,
main = "R Squared (of sq.rt. data) over parameter space") +
layer_(panel.2dsmoother(...))
assessment
nseStat
Generalisation of Nash-Sutcliffe Efficiency (R Squared)
xyplot
Plot methods for Hydromad model objects
One example:
xyplot.hydromad(mod, with.P = TRUE)
xyplot.runlist
Plot results from a set of model runs
One example:
xyplot.hydromad.runlist(mods, superpose = TRUE)
qqmath
Plot methods for Hydromad model objects
One example:
xyplot(residuals(mod)) + layer(panel.tskernel(...,
width = 90, c = 2, col = 1)) + layer(panel.tskernel(...,
width = 180, c = 2, col = 1, lwd = 2)) + layer(panel.tskernel(...,
width = 360, c = 2, lwd = 2))
paretoCatchments
Analysis using Pareto-filtering of model performance across simulation periods for multiple catchments
calibration
buildTsObjective
Generate objective functions with aggregation, transformation and a reference model
objFunVal
Calculate objective function value for a fitted model.
fitBySampling
Fit a hydromad model by sampling the parameter space.
fitByOptim
Fit a hydromad model using general optimisation algorithms.
fitBySCE
Fit a hydromad model using the SCE (Shuffled Complex Evolution) algorithm.
fitByDE
Fit a hydromad model using the DE (Differential Evolution) algorithm.
fitByDream
Fit a hydromad model using the DREAM (DiffeRential Evolution Adaptive Metropolis) algorithm.
fitByCMAES
Fit a hydromad model using CMA-ES (Covariance matrix adapting evolutionary strategy) from cmaes package
fitByDDS
Fit a hydromad model using DDS (Dynamically Dimensioned Search) algorithm.
fitByNsga2
Fit a hydromad model using the NSGA2 genetic algorithm from the mco package
optimtrace
Extract objective function value series from optimisation results
One example:
xyplot(do.call("merge", traces), superpose = TRUE,
sub = "method = "Nelder-Mead"", xlab = "Fn. evaluations",
ylab = "Objective value", auto.key = list(corner = c(1,
0))) + xyplot(do.call("merge", tracesraw),
superpose = TRUE....
defineFeasibleSet
Extract the feasible parameter sets meeting some criteria.
One example:
xyplot.hydromad(feas, feasible.bounds = TRUE, cut = 3)
discrete events
eventseq
Identify discrete events from time series and apply functions to them.
One example:
xyplot(x) + layer_(panel.xblocks(evp, col = c("grey90",
"grey80"), border = "grey80")) + layer(panel.xblocks(evq,
block.y = 0, vjust = 1, col = 1))
event.xyplot
Scatterplots with variables aggregated in event windows
One example:
event.xyplot.formula(e(Q, sum)/e(P, sum) ~ e(P, sum) +
e(P, max) + e(lag(Q, -1), first), data = Canning,
events = ev, scales = list(y = list(log = TRUE)),
yscale.components = yscale.components.fractions,
ylab = "event runoff ratio....
event.xyplot.hydromad
Visualise systematic model errors against covariates
One example:
event.xyplot.hydromad(mod, events = ev)
eventsExplorer
A graphical user interface for defining discrete events in time series
soil moisture accounting
dbm
Typical initial model used in Data-Based Mechanistic modelling.
routing
lambda
Transfer function with two exponential components and variable partitioning
leakyExpStore
Exponential store with zero flows and thresholded loss
expuh3s
Exponential components transfer function models with layered slowflow stores
routing fitting
armax.ls.fit
Estimate transfer function models by Least Squares.
armax.sriv.fit
Estimate transfer function models by Simple Refined Instrumental Variables method.
armax.inverse.fit
Estimate transfer function models by Inverse Filtering.
armax.inverse.sim
Invert transfer function models to estimate input series.
One example:
xyplot.zoo(x = cbind(observed = x$Q, slow_component = xsq$Xs),
superpose = TRUE)
tryModelOrders
Compare calibrations with different transfer function (ARMA) orders for routing.
estimateDelayFrac
Estimate the dead time between input and output, with a fractional component (redistribution of the input)
utilities
rollccf
Rolling cross-correlation at given lags.
One example:
xyplot.rollccf(foo)
evalPars
Utility functions to evaluate a model for a matrix of parameters
datasets
BinghamTrib
Rainfall and streamflow for Bingham River Trib at Ernies Catchment.
One example:
xyplot.zoo(x = BinghamTrib)
Canning
Rainfall, streamflow and potential evaporation data for Canning River at Scenic Drive.
One example:
xyplot.zoo(x = Canning)
Cotter
Rainfall and streamflow for Cotter River at Gingera.
One example:
xyplot.zoo(x = Cotter)
Murrindindi
Rainfall and streamflow for Murrindindi River at Murrindindi above Colwells.
One example:
xyplot.zoo(x = Murrindindi)
Queanbeyan
Rainfall and streamflow for Queanbeyan River at Tinderry.
One example:
xyplot.zoo(x = Queanbeyan)
SalmonBrook
Rainfall and streamflow for Salmon Brook at Salmon Catchment.
One example:
xyplot.zoo(x = SalmonBrook)
Wye
Rainfall and streamflow for Wye at Cefn Brwyn.
One example:
xyplot.zoo(x = Wye)
HydroTestData
A simple simulated dataset for use in testing hydrological models.
One example:
xyplot.zoo(x = HydroTestData)
index
| areModelsDominated | Are Models Dominated? |
| armax | ARMAX Transfer Function models |
| armax.inverse.fit | Estimate transfer function models by Inverse Filtering. |
| armax.inverse.sim | Invert transfer function models to estimate input series. |
| armax.ls.fit | Estimate transfer function models by Least Squares. |
| armax.sriv.fit | Estimate transfer function models by Simple Refined Instrumental Variables method. |
| awbm | Australian Water Balance Model (AWBM) |
| BinghamTrib | Rainfall and streamflow for Bingham River Trib at Ernies Catchment. |
| bucket | Single-bucket Soil Moisture Accounting models |
| buildTsObjective | Generate objective functions with aggregation, transformation and a reference model |
| Canning | Rainfall, streamflow and potential evaporation data for Canning River at Scenic Drive. |
| cmd | IHACRES Catchment Moisture Deficit (CMD) model |
| convertFlow | Convert between units of flow volume |
| Cotter | Rainfall and streamflow for Cotter River at Gingera. |
| cwi | IHACRES Catchment Wetness Index (CWI) model |
| dbm | Typical initial model used in Data-Based Mechanistic modelling. |
| deconvolution.uh | Unit Hydrograph using deconvolution |
| defineFeasibleSet | Extract the feasible parameter sets meeting some criteria. |
| estimateDelay | Estimate the dead time between input and output |
| estimateDelayFrac | Estimate the dead time between input and output, with a fractional component (redistribution of the input) |
| evalPars | Utility functions to evaluate a model for a matrix of parameters |
| event.xyplot | Scatterplots with variables aggregated in event windows |
| event.xyplot.hydromad | Visualise systematic model errors against covariates |
| eventseq | Identify discrete events from time series and apply functions to them. |
| eventsExplorer | A graphical user interface for defining discrete events in time series |
| expuh | Exponential components transfer function models |
| expuh3s | Exponential components transfer function models with layered slowflow stores |
| fitByCMAES | Fit a hydromad model using CMA-ES (Covariance matrix adapting evolutionary strategy) from cmaes package |
| fitByDDS | Fit a hydromad model using DDS (Dynamically Dimensioned Search) algorithm. |
| fitByDE | Fit a hydromad model using the DE (Differential Evolution) algorithm. |
| fitByDream | Fit a hydromad model using the DREAM (DiffeRential Evolution Adaptive Metropolis) algorithm. |
| fitByNsga2 | Fit a hydromad model using the NSGA2 genetic algorithm from the mco package |
| fitByOptim | Fit a hydromad model using general optimisation algorithms. |
| fitBySampling | Fit a hydromad model by sampling the parameter space. |
| fitBySCE | Fit a hydromad model using the SCE (Shuffled Complex Evolution) algorithm. |
| gr4j | GR4J rainfall runoff model |
| gr4j.transformpar | Transform GR4J parameters |
| hydromad | Specify rainfall - runoff (hydrology) models. |
| hydromad.options | User default settings for hydromad |
| hydromad.stats | Statistics for use in hydromad |
| HydroTestData | A simple simulated dataset for use in testing hydrological models. |
| intensity | Runoff as rainfall to a power |
| lambda | Transfer function with two exponential components and variable partitioning |
| leakyExpStore | Exponential store with zero flows and thresholded loss |
| methods... | Standard methods for Hydromad model objects |
| Murrindindi | Rainfall and streamflow for Murrindindi River at Murrindindi above Colwells. |
| nseStat | Generalisation of Nash-Sutcliffe Efficiency (R Squared) |
| nseVarTd | Time-delay corrected performance measure |
| objFunVal | Calculate objective function value for a fitted model. |
| observed | Observed data values |
| optimtrace | Extract objective function value series from optimisation results |
| parameterSets | Generate parameter sets |
| paretoCatchments | Analysis using Pareto-filtering of model performance across simulation periods for multiple catchments |
| powuh | Power law transfer function models |
| predict | Generate simulated time series from Hydromad model objects |
| qqmath | Plot methods for Hydromad model objects |
| Queanbeyan | Rainfall and streamflow for Queanbeyan River at Tinderry. |
| rollccf | Rolling cross-correlation at given lags. |
| rotatedSampling | Sample within rotated feasible parameter space |
| runlist | Work with a set of model runs |
| runoffratio | Simple time-varying runoff proportion |
| sacramento | Sacramento Soil Moisture Accounting model |
| SalmonBrook | Rainfall and streamflow for Salmon Brook at Salmon Catchment. |
| scalar | Simple constant runoff proportion |
| SCEoptim | Shuffled Complex Evolution (SCE) optimisation. |
| simulate | Simulate hydromad models by parameter sampling. |
| snow | Simple degree day factor snow model |
| summary | Assess and summarise performance of Hydromad models |
| tryModelOrders | Compare calibrations with different transfer function (ARMA) orders for routing. |
| Wye | Rainfall and streamflow for Wye at Cefn Brwyn. |
| xyplot | Plot methods for Hydromad model objects |
| xyplot.runlist | Plot results from a set of model runs |