## 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

## simulate

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

## xyplot

One example:

xyplot.hydromad(mod, with.P = TRUE)

## xyplot.runlist

One example:

xyplot.hydromad.runlist(mods, superpose = TRUE)

## qqmath

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

# calibration

## buildTsObjective

## objFunVal

## fitBySampling

## fitByOptim

## fitBySCE

## fitByDE

## fitByDream

## fitByCMAES

## fitByDDS

## fitByNsga2

## optimtrace

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

One example:

xyplot.hydromad(feas, feasible.bounds = TRUE, cut = 3)

# discrete events

## eventseq

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

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

One example:

event.xyplot.hydromad(mod, events = ev)

## eventsExplorer

# soil moisture accounting

## dbm

# routing

## lambda

## leakyExpStore

## expuh3s

# routing fitting

## armax.ls.fit

## armax.sriv.fit

## armax.inverse.fit

## armax.inverse.sim

One example:

xyplot.zoo(x = cbind(observed = x$Q, slow_component = xsq$Xs), superpose = TRUE)

## tryModelOrders

## estimateDelayFrac

# utilities

## rollccf

One example:

xyplot.rollccf(foo)

## evalPars

# datasets

## BinghamTrib

One example:

xyplot.zoo(x = BinghamTrib)

## Canning

One example:

xyplot.zoo(x = Canning)

## Cotter

One example:

xyplot.zoo(x = Cotter)

## Murrindindi

One example:

xyplot.zoo(x = Murrindindi)

## Queanbeyan

One example:

xyplot.zoo(x = Queanbeyan)

## SalmonBrook

One example:

xyplot.zoo(x = SalmonBrook)

## Wye

One example:

xyplot.zoo(x = Wye)

## HydroTestData

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 |