Centre de recherche sur lenvironnement alpin (CREALP)

HydroPrepR

HydroPrepR - Manual v1.0

February 2015
For Software version 1.0.0.1

Approved for Public Release. Distribution Unlimited

Centre de recherche sur lenvironnement alpin (CREALP)

Authors:

Alain FOEHN CREALP

Javier GARCIA HERNANDEZ CREALP
Matthew MOY-DE-VITRY CREALP

Please refer this technical manual as:

Foehn, A., Garca Hernndez, J. and Moy-de-Vitry, M (2015). HydroPrepR Manual v1.0. CREALP Report, Switzerland.
Index
Chapter 1: Introduction ........................................................................................................................... 5
1.1 Installation procedure ............................................................................................................. 5
1.2 Change path to R Folder .................................................................. Erreur ! Signet non dfini.
Chapter 2: Polygon analysis..................................................................................................................... 7
Procedure ........................................................................................................................................ 7
Input data ........................................................................................................................................ 7
Output data ..................................................................................................................................... 7
Chapter 3: Elevation Bands Creator (EB Creator) .................................................................................... 8
EB Creator interface ........................................................................................................................ 8
Data requirements .......................................................................................................................... 8
Procedure ........................................................................................................................................ 9
Chapter 4: Data Spatialization ............................................................................................................... 10
Procedure ...................................................................................................................................... 10
Input data / settings ...................................................................................................................... 11
Output ........................................................................................................................................... 11
Procedure ...................................................................................................................................... 11
4.1 Interpolation methods .......................................................................................................... 12
Thiessen interpolation................................................................................................................... 12
Inverse distance weighting interpolation...................................................................................... 13
Kriging ............................................................................................................................................ 13
4.2 Elevation sampling ................................................................................................................ 14
Method .......................................................................................................................................... 14
4.3 Aggregation ........................................................................................................................... 15
Chapter 5: CSV Import ........................................................................................................................... 16
Procedure ...................................................................................................................................... 16
Input data / settings ...................................................................................................................... 16
Bibliography........................................................................................................................................... 18
Acknowledgments ................................................................................................................................. 19

HydroPrepR Manual Page 4/20

HydroPrepR

Chapter 1: Introduction
The HydroPrepR software is composed of different modules, listed in the left frame of the interface,
as presented in Figure 1.

List of modules

Check for new version Link to the R Folder

Figure 1 Interface of the HydroPrepR software

1.1 Installation procedure

Proceed as follows to install HydroPrepR on your computer:
Visit the CREALP website : http://www.crealp.ch
Go to Resources -> Software -> HydroPrepR
Click on Download page: HydroPrepR
Save the file, double-click on Setup.exe (in the Internet browser Downloads frame)
and follow the installation procedure.
Read and accept the Terms and conditions for use of HydroPrepR software.
Click on Install.

In order to use the different available tools, based on the open source and statistical
environment R, an R Distribution with predefined libraries is required. The link to the R
Folder has to be defined in the interface frame (bottom-right, see Figure 1).

HydroPrepR - Manual Page 5/20

HydroPrepR

The R Distribution can be downloaded on the same page as the HydroPrepR software.
Proper installation can be achieved using following steps:
Download the R Distribution for HydroPrepR (example: R-3.1.2-CREALP-v1.zip).
Unzip the R Distribution folder and move it to an adequate folder1.
When opening HydroPrepR for the first time, the message showed in Figure 2 will
appear. Accept the message and define the folder containing the R Distribution.

Figure 2 Change R Folder button

In the bottom-left part of the interface (Figure 1), the button allows to check if a new
version of the sorftware is available.
R is a language and environment for statistical computing and graphics (R Development Core
Team, 2008). Different applications have been developed in the R environment and have
been inserted in HydroPrepR in order to achieve different tasks, presented hereafter.

1
For example in C:\opt

HydroPrepR - Manual Page 6/20

HydroPrepR

Chapter 2: Polygon analysis

This module allows the user to compute the centres of gravity and the surface area of
catchments and subcatchments. The results of the analysis are saved in the shapefile as
additional attributes.

Figure 3 Polygon analysis module

Procedure
Define all required fields
Launch the calculation by double clicking on the button Create. At the end of the
running, you can find the generated files in the selected output directory.

Input data
Shapefile: ESRI Shapefile of polygons in a projected Coordinate reference system
(CRS). Coordinates must be distance units, not angles.
Digital elevation data: (optional) used to compute the average elevation of each
polygon. There must be at least one data point in each polygon for the algorithm to
function correctly. If no elevation data is provided, an elevation of zero is used as
default. The elevation data must be in the same CRS as the shapefile.

Output data
The result of the process is a shapefile of polygons to which four attributes have been added
to each feature:
X,Y,Z: the coordinates of the centre of gravity of each polygon
Surface: the surface area of each polygon

HydroPrepR - Manual Page 7/20

HydroPrepR

Chapter 3: Elevation Bands Creator (EB Creator)

The Elevation Bands Creator tool allows the user to divide a shape representing a watershed
into a division of elevation bands. EB Creator produces a shape with the elevation bands and
a PDF file, but it also produces a parameter file with the necessary parameters for the
hydrological model.

EB Creator interface
To start EB Creator:
Click on the Elevation Bands Creator tab in the R Functions window (Figure 3). The EB
Creator is opened (Figure 4).

Outputs Launch
button

Inputs Comments related

to the execution

Figure 4 EB Creator window

Data requirements
The following data files are required:
DEM of the entire basin. The grid must be regular. Various formats can be read by EB
Creator.

HydroPrepR - Manual Page 8/20

HydroPrepR

Shapefile of the basin (optionally divided with polygons into sub-basins). Each
polygon must contain a unique id field name. Polygons can be multipart features,
e.g. divided into more than one entity with the same id.
Shapefile of the glaciers, if the basin contains glaciers (optional).

Procedure
Hereafter, the necessary steps to perform a division of a watershed into multiple elevation
bands are presented.
In R apps, click on the module tool EB Creator.
Choose the DEM pathname in the inputs frame (by writing it or by double clicking to
indicate the location).
Choose the watershed shapefile pathname in the inputs frame (by writing it or by
double clicking to indicate the location).
Select the attribute to be used as id in the shapefile.
Indicate if there are glaciers. If it is the case, choose the glaciers shape pathname in
the inputs frame (by writing it or by double clicking to indicate the location).
Indicate the path where you want the outputs to be produced (in the outputs frame)
Indicate the outputs you want to be produced.
Define the maximum altitude difference in an elevation band by modifying the DELTA
Z MAX value.
Launch the calculation by double clicking on the button Create. At the end of the
running, you can find the asked files in the outputs directory.
It is important to ensure that no accent is present in the file and path names. If this is not
the case, errors might be generated during the calculation.
Furthermore, if the shapefile is of particularly big size and depending on the memory
capacity of the computer, it might run out of memory.

HydroPrepR - Manual Page 9/20

HydroPrepR

Chapter 4: Data Spatialization

The data spatialization module (Figure 5) allows the user to generate a dataset of
interpolated stations that correspond to the topography of the users hydrological model.
Spatialization refers to two steps: interpolation and aggregation. Firstly, the time series of
precipitation, temperature, and / or evapotranspiration are estimated through interpolation
at each location of a grid of interpolation points. The interpolation points are automatically
positioned within the area of study defined by the shapefile of catchment polygons.
Then, if desired, the time series are aggregated by polygon: one average time series is
calculated for each polygon, based on the interpolation points contained in each polygon.
The average time series are each associated to a point at the centre of gravity of their
respective polygons.

Figure 5 Data spatialization module

Procedure
Define all required fields
Launch the calculation by double clicking on the button Create. At the end of the
running, you can find the generated files in the selected output directory.

HydroPrepR - Manual Page 10/20

HydroPrepR

Input data / settings

Shapefile of catchment polygons: ESRI polygon shapefile that defines the extent of
the interpolation grid as well as the boundaries of each polygon, if the results are
aggregated.
Dataset of measured time series: RS Dataset, from RS MINERVE (Foehn et al., 2015;
Garca et al., 2015), containing time series of precipitation, temperature, and/or
evapotranspiration (ETP).
Digital elevation data: georeferenced digital elevation information in a raster or
point format. The resolution of the elevation data must be denser than that of the
interpolation grid.
Start / End date: The user can reduce the time series by setting a minimum and
maximum date. If the date isnt changed, then the time series is not modified.
Interpolation grid cell size: A regular grid of interpolation points is automatically
generated within the extent defined by the shapefile. The grid cell size is the
minimum distance between interpolation points. It is recommended to use a value
that corresponds to the variations of the terrain. The interpolation computation time
is proportional to the square of the inverse of the grid cell size.
Interpolation method: For each sensor (precipitation, temperature, or ETP), a
different interpolation method can be used. The currently available methods are:
o Nearest neighbour
o Inverse distance weighting (exponents 1 or 2 available)
o Ordinary Kriging
o Universal Kriging, can only be used if elevation data is provided
Aggregation method: In order to reduce the size of the final dataset, the user can
choose to export only one interpolation station by polygon of the shapefile. In this
situation, the interpolation points contained in each polygon are aggregated by
averaging the data on each time step.
Interpolation station name: If desired, the aggregated stations can be given a name
from an attribute of the shapefile.

Output
The module generates an RS dataset that can be directly opened in the program
RS MINERVE.

Procedure
The procedure followed by the module is represented in Figure 6.

HydroPrepR - Manual Page 11/20

HydroPrepR

Create grid of If aggregation by polygon is activated: add an

interpolation additional interpolation point at the centre of gravity
points. of each polygon that contains no interpolation point.

If aggregation by polygon is For each time step and each sensor,

activated: calculate average time estimate measurement at interpolation
series from data in each polygon station with available data.

Export data as
an RS dataset.

Figure 6 Data spatialization procedure

4.1 Interpolation methods

Thiessen interpolation
Note: this method is also known under the names of Voronoi diagram.

This is the simplest interpolation method for meteorological data, and uses the nearest
available elevation data (ED) point as a reference, without performing any further
adjustment on the data. The interpolated data at each time step thus has polygonial
structure (Figure 7).

Figure 7 Thiessen interpolation of measurement points (green) on interpolation points (other colours)

Method
The code is optimised for the situation in which the interpolation needs to be repeated
numerous times with almost identical2 data configurations.
1. First, a lookup table is generated that lists for each interpolation point the nearest
measurement stations available, for the sensor of interest (P, T and ETP). The

2
Alterations can occur if measurement points are missing.

HydroPrepR - Manual Page 12/20

HydroPrepR

distance between points is estimated as the horizontal distance, without taking

elevation changes into account:

DS.1

Thanks to this lookup table, the distances only need to be calculated once.
2. The program then loops through each time step and fetches for each interpolation
point the data value from the reference measurement station, indicated by the first
element of the lookup table for that station.
3. In the situation where one of the data points is missing, data from the next nearest
measurement stations is used.

It can be expected that this method runs faster than other interpolation methods.

Inverse distance weighting interpolation

Note: Shephard interpolation is a special case of inverse distance weighting.

In this method, the weights are proportional to the inverse power of the distance between
measurement stations and interpolation points. The user can choose between a power of 1
and a power of 2.

Method
For this method, the idw function from the gstat package (Pebesma, 2004) for R (R Core
Team, 2014) was used. The weight of the jth measurement station for the ith
interpolation point is given by:

DS.2
th
Where is the 2D distance as defined in 0. The data estimation at the i interpolation point is:

DS.3

th
Where is the data measurement at the j measurement station.

When, for a given interpolation point, all measurement stations are relatively far away, the
estimated value at the interpolation point tends towards the global average.

Kriging
For this method, the autokrige function from the automap package (Hiemstra, 2008) for R (R
Core Team, 2014) was used. This function automatically estimates the variogram and then
calls the krige function from the gstat package (Pebesma, 2004) to do the actual kriging.

Ordinary Kriging method

Ordinary Kriging assumes that the random variable Z(s) to be estimated respects the model

HydroPrepR - Manual Page 13/20

HydroPrepR

DS.4
Where is an unknown constant. Documentation on kriging can be found in Cressie (1993).

Universal Kriging method

When the option remove trend with elevation data is activated, Universal Kriging is used
instead of Ordinary Kriging. The conceptual difference is that is assumed to be a
deterministic function (of the elevation) and not an unknown constant. See Matheron (1993)
for more details.
The option of kriging with trend removal for precipitation was removed because in
preliminary tests, the results proved unreliable (total volume about 3 times higher than for
other methods).

4.2 Elevation sampling

The user can provide elevation data that is necessary for certain interpolation methods
(currently only the Universal kriging method). The elevation data (ED) is used to estimate the
elevation at each interpolation point before the interpolation takes place. Because both the
elevation data and the interpolation points are spatial points, the program uses a Gaussian
sampling method to estimate the local elevation. The method aims to account for the fact
that each interpolation point actually represents an area.

Method
This method relies on a Gaussian filter to estimate the local elevation of a point. The
computation steps at each interpolation point are:
1. Calculate distance of ED points to the current interpolation point.
2. Calculate a weight for each ED point based on its distance. For this, a normal
distribution function with standard deviation equal to twice the interpolation grid cell
size is used. The weighting function used is:

DS.5

th th
Where is the weight of the j ED point for the i interpolation point, is the Euclidean distance
in 2D space between those two points, and is the minimum distance between interpolation points.

3. Do a weigted sum of the elevations of the ED to find an estimation of the elevation

at the current interpolation point:

DS.6

As shown in the figures below, the use of a Gaussian filter smoothens the elevation
estimation in comparison to block sampling, where the elevation is estimated by averaging
DE data within a rectangular block around each interpolation point, thus introducing a
strong sampling effect.

HydroPrepR - Manual Page 14/20

HydroPrepR

Figure 8 Elevation estimation by block sampling Figure 9 Elevation estimation with a gaussian filter

Because the weighting function uses a standard deviation that is independent from the resolution of
the DE data, the method will not work if DE points are much sparser than interpolation points:
indeed, the weights rapidly fall to zero for all DE points further than from the interpolation
point.

4.3 Aggregation
Once the measured time series are interpolated at each interpolation point, the data is
aggregated: one time series is computed for each catchment. Each aggregated time series is
computed by averaging the data of all interpolation points situated within the boundaries of
each catchment (Figure 10). Each aggregated time series is associated to an interpolated
station located at the center of gravity of the corresponding polygon.

Figure 10 Mean aggregation of the interpolated temperature, by polygon. (left: interpolated data, right:
aggregation of interpolated data)

HydroPrepR - Manual Page 15/20

HydroPrepR

Chapter 5: CSV Import

The CSV import module (Figure 11) allows the user to automatically generate an RS dataset
(dataset format for RS MINERVE software) with several stations and sensors from a CSV file,
thereby increasing processing speed and reducing the chance of errors occurring.

Figure 11 CSV import module

Procedure
Define all required fields
Launch the calculation by double clicking on the button Create. At the end of the
running, you can find the generated files in the selected output directory.

Input data / settings

Coordinate file: CSV file containing the names and coordinates of the measurement
stations. The following columns must be given:
o STATION: A string of alphanumeric characters (no spaces) that uniquely
identify each station.
o X: The X coordinate of the station
o Y: The Y coordinate of the station
o Z: The Z coordinate of the station
Data file: CSV file containing the time series of each station. Each time series is
represented by a single column in the table. The column name must be a
combination of the station abbreviation (STATION) like that in the coordinate file,

HydroPrepR - Manual Page 16/20

HydroPrepR

and either P, T, or ETP to indicate which sensor is represented by the time series,
separated by a colon (:) (Figure 12).
Column separator: The CSV files can use any character except a column to indicate
column breaks.
Data format: For each of P, T, and ETP, the user can select both the unit and the
interpolation mode that should be used when the data is interpreted in RS MINERVE.

Figure 12 Format of CSV file for importation to dataset

HydroPrepR - Manual Page 17/20

Bibliography

Bibliography

Foehn, A., Garca Hernndez, J., Claude, A., Roquier, B., Boillat, J.-L. and Paredes Arquiola, J.
(2015). RS MINERVE Users manual v1.17. RS MINERVE Group, Switzerland.

Garca Hernndez, J., Paredes Arquiola, J., Foehn, A., Claude, A., Roquier, B. and Boillat, J.-L.
(2015). RS MINERVE Technical manual v 1.12. RS MINERVE Group, Switzerland.

Hiemstra, P.H., Pebesma, E.J., Twenhofel, C.J.W. and G.B.M. Heuvelink, (2008). Real-time
automatic interpolation of ambient gamma dose rates from the Dutch Radioactivity
Monitoring Network. Computers & Geosciences, accepted for publication.

Matheron, G, (1993). The Theory of Regionalized Variables and Its Applications. cole
national suprieure des mines, 211p.

Pebesma, E.J., (2004). Multivariable geostatistics in S: the gstat package. Computers &
Geosciences 30, 683-691.

R Development Core Team (2008). R: A language and environment for statistical computing.
R Foundation for Statistical Computing, Vienna, Austria. ISBN 3-900051-07-0,
URL http://www.R-project.org

HydroPrepR - Manual Page 18/20

Acknowledgments

Acknowledgments

HydroPrepR is developed by the research center CREALP with the collaboration of the
Universitat Politcnica de Valncia and the Hydro10 Association.
We would like to thank sincerely these organizations for their support.

In addition, we would like to express our gratitude to the people who have personally
contributed to the improvement of the program and its documentation, in particular:
Stphane Micheloud1, Nestor Lerma2, Alex Dionisio-Calado1 and Samuel Alesina1.

Our gratitude also goes to the developers of all the complementary3 R packages used in
HydroPrepR, listed hereafter.

Packages Authors and contributors

automap Paul Hiemstra
Alina Beygelzimer, Sham Kakadet and John Langford, Sunil Arya and David
FNN
Mount, Shengqiao Li
R Core Team, Roger Bivand, Vincent J. Carey Saikat DebRoy, Stephen Eglen,
foreign Rajarshi Guha, Nicholas Lewin-Koh, Mark Myatt, Ben Pfaff, Brian Quistorff,
Frank Warmerdam, Stephen Weigand, Free Software Foundation Inc.
gstat Edzer Pebesma, Benedikt Graeler
Intervals Richard Bourgon
lattice Deepayan Sarkar
latticeExtra Deepayan Sarkar, Felix Andrews
Roger Bivand, Nicholas Lewin-Koh, Edzer Pebesm, Eric Archer, Adrian
Baddeley, Hans-Jrg Bibiko, Steven Brey, Jonathan Callahan, German
Carrillo, Stphane Dray, David Forrest, Michael Friendly, Patrick Giraudoux,
maptools Duncan Golicher, Virgilio Gmez Rubio, Patrick Hausmann, Karl Ove
Hufthammer, Thomas Jagger, Sebastian Luque, Don MacQueen, Andrew
Niccolai, Edzer Pebesma, Oscar Perpin Lamigueiro, Tom Short, Greg
Snow, Ben Stabler, Murray Stokely, Rolf Turner
plyr Hadley Wickham
Robert J. Hijmans, Jacob van Etten, Matteo Mattiuzzi, Michael Sumner,
raster Jonathan A. Greenberg, Oscar Perpinan Lamigueiro, Andrew Bevan, Etienne
B. Racine, Ashton Shortridge

1
Centre de recherche sur lenvironnement alpin - CREALP
2
Universitat Politcnica de Valncia - UPV
3
The list excludes the following fundamental R packages: base, datasets, graphics, grDevices, grid, methods,
stats, utils.

HydroPrepR - Manual Page 19/20

Acknowledgments

RColorBrewer Erich Neuwirth

Dirk Eddelbuettel, Romain Francois, JJ Allaire, Kevin Ushey, Douglas Bates,
Rcpp
and John Chambers
reshape Hadley Wickham
reshape2 Hadley Wickham
Roger Bivand, Tim Keitt, Barry Rowlingson, Edzer Pebesma, Michael
rgdal
Sumner, Robert Hijmans, Even Rouault
rgeos Roger Bivand, Colin Rundel, Edzer Pebesma, Karl Ove Hufthammer
RSAGA Alexander Brenning
shapefiles Ben Stabler
Edzer Pebesma, Roger Bivand, Barry Rowlingson, Virgilio Gomez-Rubio,
sp
Robert Hijmans
spacetime Edzer Pebesma, Benedikt Graeler, Tom Gottfried, Robert J. Hijmans
stringr Hadley Wickham
XML Duncan Temple Lang

HydroPrepR - Manual Page 20/20

 HydroPrepR

CREALP - Centre de recherche sur l'environnement alpin

Rue de l'Industrie 45
CH-1951 Sion
Tl. +41 (0) 27 607 11 80
Fax +41 (0) 27 607 11 94
crealp@crealp.vs.ch