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.

The model framework as used in the hydromad package

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

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:

  1. Install R if you do not have a recent version (the most recent release is recommended).
  2. Install required packages from within R:
    install.packages(c("zoo", "latticeExtra", "polynom", "car", "Hmisc","reshape"))
  3. Install hydromad
    install.packages("hydromad", repos="http://hydromad.catchment.org")
    To instead download the package manually see: Windows binary and source.
  4. 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

hydromad

Specify rainfall - runoff (hydrology) models.

Usage, Details, Examples

Source code

methods...

Standard methods for Hydromad model objects

Usage, Details, Examples

Source code

predict

Generate simulated time series from Hydromad model objects

Usage, Details, Examples

Source code

simulate

Simulate hydromad models by parameter sampling.

Usage, Details, Examples

One example:

simulate
levelplot(result ~ tw + f, sim1, cex = 2, panel = panel.levelplot.points, 
    main = "R Squared (of sq.rt. data) over parameter space") + 
    layer_(panel.2dsmoother(...))

Source code

runlist

Work with a set of model runs

Usage, Details, Examples

Source code

hydromad.options

User default settings for hydromad

Usage, Details, Examples

Source code

assessment

summary

Assess and summarise performance of Hydromad models

Usage, Details, Examples

Source code

hydromad.stats

Statistics for use in hydromad

Usage, Details, Examples

Source code

nseStat

Generalisation of Nash-Sutcliffe Efficiency (R Squared)

Usage, Details, Examples

Source code

nseVarTd

Time-delay corrected performance measure

Usage, Details, Examples

Source code

xyplot

Plot methods for Hydromad model objects

Usage, Details, Examples

One example:

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

Source code

xyplot.runlist

Plot results from a set of model runs

Usage, Details, Examples

One example:

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

Source code

qqmath

Plot methods for Hydromad model objects

Usage, Details, Examples

One example:

qqmath
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))

Source code

areModelsDominated

Are Models Dominated?

Usage, Details, Examples

Source code

paretoCatchments

Analysis using Pareto-filtering of model performance across simulation periods for multiple catchments

Usage, Details, Examples

Source code

calibration

buildTsObjective

Generate objective functions with aggregation, transformation and a reference model

Usage, Details, Examples

Source code

objFunVal

Calculate objective function value for a fitted model.

Usage, Details, Examples

Source code

fitBySampling

Fit a hydromad model by sampling the parameter space.

Usage, Details, Examples

Source code

fitByOptim

Fit a hydromad model using general optimisation algorithms.

Usage, Details, Examples

Source code

fitBySCE

Fit a hydromad model using the SCE (Shuffled Complex Evolution) algorithm.

Usage, Details, Examples

Source code

fitByDE

Fit a hydromad model using the DE (Differential Evolution) algorithm.

Usage, Details, Examples

Source code

fitByDream

Fit a hydromad model using the DREAM (DiffeRential Evolution Adaptive Metropolis) algorithm.

Usage, Details, Examples

Source code

fitByCMAES

Fit a hydromad model using CMA-ES (Covariance matrix adapting evolutionary strategy) from cmaes package

Usage, Details, Examples

Source code

fitByDDS

Fit a hydromad model using DDS (Dynamically Dimensioned Search) algorithm.

Usage, Details, Examples

Source code

fitByNsga2

Fit a hydromad model using the NSGA2 genetic algorithm from the mco package

Usage, Details, Examples

Source code

optimtrace

Extract objective function value series from optimisation results

Usage, Details, Examples

One example:

optimtrace
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....

Source code

defineFeasibleSet

Extract the feasible parameter sets meeting some criteria.

Usage, Details, Examples

One example:

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

Source code

discrete events

eventseq

Identify discrete events from time series and apply functions to them.

Usage, Details, Examples

One example:

eventseq
xyplot(x) + layer_(panel.xblocks(evp, col = c("grey90", 
    "grey80"), border = "grey80")) + layer(panel.xblocks(evq, 
    block.y = 0, vjust = 1, col = 1))

Source code

event.xyplot

Scatterplots with variables aggregated in event windows

Usage, Details, Examples

One example:

event.xyplot
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....

Source code

event.xyplot.hydromad

Visualise systematic model errors against covariates

Usage, Details, Examples

One example:

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

Source code

eventsExplorer

A graphical user interface for defining discrete events in time series

Usage, Details, Examples

Source code

soil moisture accounting

cmd

IHACRES Catchment Moisture Deficit (CMD) model

Usage, Details, Examples

Source code

cwi

IHACRES Catchment Wetness Index (CWI) model

Usage, Details, Examples

Source code

gr4j

GR4J rainfall runoff model

Usage, Details, Examples

Source code

awbm

Australian Water Balance Model (AWBM)

Usage, Details, Examples

Source code

bucket

Single-bucket Soil Moisture Accounting models

Usage, Details, Examples

Source code

sacramento

Sacramento Soil Moisture Accounting model

Usage, Details, Examples

Source code

snow

Simple degree day factor snow model

Usage, Details, Examples

Source code

scalar

Simple constant runoff proportion

Usage, Details, Examples

Source code

intensity

Runoff as rainfall to a power

Usage, Details, Examples

Source code

runoffratio

Simple time-varying runoff proportion

Usage, Details, Examples

Source code

dbm

Typical initial model used in Data-Based Mechanistic modelling.

Usage, Details, Examples

Source code

routing

armax

ARMAX Transfer Function models

Usage, Details, Examples

Source code

expuh

Exponential components transfer function models

Usage, Details, Examples

Source code

lambda

Transfer function with two exponential components and variable partitioning

Usage, Details, Examples

Source code

powuh

Power law transfer function models

Usage, Details, Examples

Source code

leakyExpStore

Exponential store with zero flows and thresholded loss

Usage, Details, Examples

Source code

expuh3s

Exponential components transfer function models with layered slowflow stores

Usage, Details, Examples

Source code

routing fitting

armax.ls.fit

Estimate transfer function models by Least Squares.

Usage, Details, Examples

Source code

armax.sriv.fit

Estimate transfer function models by Simple Refined Instrumental Variables method.

Usage, Details, Examples

Source code

armax.inverse.fit

Estimate transfer function models by Inverse Filtering.

Usage, Details, Examples

Source code

armax.inverse.sim

Invert transfer function models to estimate input series.

Usage, Details, Examples

One example:

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

Source code

tryModelOrders

Compare calibrations with different transfer function (ARMA) orders for routing.

Usage, Details, Examples

Source code

estimateDelay

Estimate the dead time between input and output

Usage, Details, Examples

Source code

estimateDelayFrac

Estimate the dead time between input and output, with a fractional component (redistribution of the input)

Usage, Details, Examples

Source code

deconvolution.uh

Unit Hydrograph using deconvolution

Usage, Details, Examples

Source code

utilities

convertFlow

Convert between units of flow volume

Usage, Details, Examples

Source code

rollccf

Rolling cross-correlation at given lags.

Usage, Details, Examples

One example:

rollccf
xyplot.rollccf(foo)

Source code

parameterSets

Generate parameter sets

Usage, Details, Examples

Source code

evalPars

Utility functions to evaluate a model for a matrix of parameters

Usage, Details, Examples

Source code

rotatedSampling

Sample within rotated feasible parameter space

Usage, Details, Examples

Source code

gr4j.transformpar

Transform GR4J parameters

Usage, Details, Examples

Source code

observed

Observed data values

Usage, Details, Examples

Source code

SCEoptim

Shuffled Complex Evolution (SCE) optimisation.

Usage, Details, Examples

Source code

datasets

BinghamTrib

Rainfall and streamflow for Bingham River Trib at Ernies Catchment.

Usage, Details, Examples

One example:

BinghamTrib
xyplot.zoo(x = BinghamTrib)

Source code

Canning

Rainfall, streamflow and potential evaporation data for Canning River at Scenic Drive.

Usage, Details, Examples

One example:

Canning
xyplot.zoo(x = Canning)

Source code

Cotter

Rainfall and streamflow for Cotter River at Gingera.

Usage, Details, Examples

One example:

Cotter
xyplot.zoo(x = Cotter)

Source code

Murrindindi

Rainfall and streamflow for Murrindindi River at Murrindindi above Colwells.

Usage, Details, Examples

One example:

Murrindindi
xyplot.zoo(x = Murrindindi)

Source code

Queanbeyan

Rainfall and streamflow for Queanbeyan River at Tinderry.

Usage, Details, Examples

One example:

Queanbeyan
xyplot.zoo(x = Queanbeyan)

Source code

SalmonBrook

Rainfall and streamflow for Salmon Brook at Salmon Catchment.

Usage, Details, Examples

One example:

SalmonBrook
xyplot.zoo(x = SalmonBrook)

Source code

Wye

Rainfall and streamflow for Wye at Cefn Brwyn.

Usage, Details, Examples

One example:

Wye
xyplot.zoo(x = Wye)

Source code

HydroTestData

A simple simulated dataset for use in testing hydrological models.

Usage, Details, Examples

One example:

HydroTestData
xyplot.zoo(x = HydroTestData)

Source code

index

areModelsDominatedAre Models Dominated?
armaxARMAX Transfer Function models
armax.inverse.fitEstimate transfer function models by Inverse Filtering.
armax.inverse.simInvert transfer function models to estimate input series.
armax.ls.fitEstimate transfer function models by Least Squares.
armax.sriv.fitEstimate transfer function models by Simple Refined Instrumental Variables method.
awbmAustralian Water Balance Model (AWBM)
BinghamTribRainfall and streamflow for Bingham River Trib at Ernies Catchment.
bucketSingle-bucket Soil Moisture Accounting models
buildTsObjectiveGenerate objective functions with aggregation, transformation and a reference model
CanningRainfall, streamflow and potential evaporation data for Canning River at Scenic Drive.
cmdIHACRES Catchment Moisture Deficit (CMD) model
convertFlowConvert between units of flow volume
CotterRainfall and streamflow for Cotter River at Gingera.
cwiIHACRES Catchment Wetness Index (CWI) model
dbmTypical initial model used in Data-Based Mechanistic modelling.
deconvolution.uhUnit Hydrograph using deconvolution
defineFeasibleSetExtract the feasible parameter sets meeting some criteria.
estimateDelayEstimate the dead time between input and output
estimateDelayFracEstimate the dead time between input and output, with a fractional component (redistribution of the input)
evalParsUtility functions to evaluate a model for a matrix of parameters
event.xyplotScatterplots with variables aggregated in event windows
event.xyplot.hydromadVisualise systematic model errors against covariates
eventseqIdentify discrete events from time series and apply functions to them.
eventsExplorerA graphical user interface for defining discrete events in time series
expuhExponential components transfer function models
expuh3sExponential components transfer function models with layered slowflow stores
fitByCMAESFit a hydromad model using CMA-ES (Covariance matrix adapting evolutionary strategy) from cmaes package
fitByDDSFit a hydromad model using DDS (Dynamically Dimensioned Search) algorithm.
fitByDEFit a hydromad model using the DE (Differential Evolution) algorithm.
fitByDreamFit a hydromad model using the DREAM (DiffeRential Evolution Adaptive Metropolis) algorithm.
fitByNsga2Fit a hydromad model using the NSGA2 genetic algorithm from the mco package
fitByOptimFit a hydromad model using general optimisation algorithms.
fitBySamplingFit a hydromad model by sampling the parameter space.
fitBySCEFit a hydromad model using the SCE (Shuffled Complex Evolution) algorithm.
gr4jGR4J rainfall runoff model
gr4j.transformparTransform GR4J parameters
hydromadSpecify rainfall - runoff (hydrology) models.
hydromad.optionsUser default settings for hydromad
hydromad.statsStatistics for use in hydromad
HydroTestDataA simple simulated dataset for use in testing hydrological models.
intensityRunoff as rainfall to a power
lambdaTransfer function with two exponential components and variable partitioning
leakyExpStoreExponential store with zero flows and thresholded loss
methods...Standard methods for Hydromad model objects
MurrindindiRainfall and streamflow for Murrindindi River at Murrindindi above Colwells.
nseStatGeneralisation of Nash-Sutcliffe Efficiency (R Squared)
nseVarTdTime-delay corrected performance measure
objFunValCalculate objective function value for a fitted model.
observedObserved data values
optimtraceExtract objective function value series from optimisation results
parameterSetsGenerate parameter sets
paretoCatchmentsAnalysis using Pareto-filtering of model performance across simulation periods for multiple catchments
powuhPower law transfer function models
predictGenerate simulated time series from Hydromad model objects
qqmathPlot methods for Hydromad model objects
QueanbeyanRainfall and streamflow for Queanbeyan River at Tinderry.
rollccfRolling cross-correlation at given lags.
rotatedSamplingSample within rotated feasible parameter space
runlistWork with a set of model runs
runoffratioSimple time-varying runoff proportion
sacramentoSacramento Soil Moisture Accounting model
SalmonBrookRainfall and streamflow for Salmon Brook at Salmon Catchment.
scalarSimple constant runoff proportion
SCEoptimShuffled Complex Evolution (SCE) optimisation.
simulateSimulate hydromad models by parameter sampling.
snowSimple degree day factor snow model
summaryAssess and summarise performance of Hydromad models
tryModelOrdersCompare calibrations with different transfer function (ARMA) orders for routing.
WyeRainfall and streamflow for Wye at Cefn Brwyn.
xyplotPlot methods for Hydromad model objects
xyplot.runlistPlot results from a set of model runs
hydromad version 0.9-18 on R version 2.15.0 (at 2013-05-27)
web dev by felix andrews