r.randomwalk - Conceptual tool for mass movement propagation
Mass movement, Random walk, Raster, Routing
r.randomwalk
r.randomwalk help
r.randomwalk [-abmnpqsvx] prefix=string [mult=integer,integer] [cellsize=float] [aoicoords=float,...][aoimap=name] elevation=name [releasefile=string] [caserules=integer,integer,...] [releasemap=name] [depositmap=name] [impactmap=name] [probmap=name] [scoremap=name] [impactobjects=name] [objectscores=string] models=string mparams=string [retain=float] [functype=integer] [backfile=string] [cdffile=string] [zonalfile=string] [profile=float,...] [--verbose] [--quiet]
Flags:
Parameters:
r.randomwalk is a flexible and multi-functional conceptual tool for backward- and forward-analyses of mass movement propagation. Mass points are routed from defined release pixels of one to many mass movements through a digital elevation model until a defined break criterion is reached. Lateral spreading is ensured by a constrained random walk approach. Compared to existing tools, the major innovative features of r.randomwalk are:
Further, impact indicator scores and probabilities can be combined with release indicator scores or probabilities. Risk indicator scores can be computed if possible objects at risk are given.
Note that it is strongly recommended to run r.randomwalk only in GRASS Locations where the length unit is metres (however, no projection has to be defined, generic XY coordinate systems work fine).
This document is mainly understood as a set of instructions how to operate r.randomwalk. The detailed scientific background will be outlined in forthcoming scientific publications (Mergili et al., submitted) whilst a number of test cases and applications is collected at http://www.mergili.at/randomwalk.html.
r.randomwalk was developed and tested on Ubuntu 12.04 LTS, but is expected to work in other LINUX environments, too. It builds on GRASS 7.0 which has to be installed from source. The code employs the Python (Version 2.7 or higher is recommended) and C programming languages. The validation and visualization of the model results (flag v) makes use of the R Project for Statistical Computing (recommended version: 3.2 or higher). The following packages of R have to be installed in order to fully explore the functionalities offered by r.randomwalk: sp, rgdal, raster and ROCR. These packages may depend on other packages not listed here.
The installation script provided along with r.randomwalk is expected to work for many GRASS source installations on UNIX systems. However, there might be installations where amendments to the script are required. Please note that you need sudo rights to install r.randomwalk.
Average of impact probability (flag a)
This flag is only available in combination with the flag p. In contrast to the default, where the maximum out of the impact probabilities of overlapping cases is used as the overall impact probability, the average out of the impact probabilities of overlapping cases is applied.
Back-calculate observations (flag b)
This mode is useful to explore the angle of reach and the maximum travel distance of observed mass movements. Instead of applying the break criteria set in the parameter models, each random walk stops when leaving the impact area of the case (parameter impactarea).
Multiple model runs with random parameters (flag m)
Multiple model runs are executed with randomized parameters given by models and mparams. The results are combined to an impact indicator score map. Further, input and output parameter tables suitable as input for the sensitivity analysis and parameter optimization tool AIMEC (Fischer, 2013) are created.
Multiple model runs with random release (flag n)
Multiple model runs are executed with random subsets of the releasefile or the releasemap. This flag is useful in combination with the flag p in order to clearly separate between a set of cases used for model development and another set employed for validation. Separate cumulative density functions are derived for each subset.
Probabilities (flag p)
An impact probability map - and, if release probabilities map (through the parameter probmap or in the releasefile) are given, also a composite probability map - is computed.
Scores (flag q)
An impact indicator score map - and, if release indicator scores (through the parameter scoremap or in the releasefile) are given, also a composite indicator score map - is computed.
Separate random walks for each model (flag s)
The parameters Lctrl, Lseg, Rmax, fbeta and fdir (see parameters models and mparams) are defined separately for each model. Activating this flag increases the flexibility of the analysis, but - as the random walks have to be run separately for each model - also the computational time.
Validation and visualization of model results (flag v)
ROC Plots are generated, evaluating the impact indicator index (flag m) or impact probability maps (flag p) against the observed deposition areas (parameter depositmap). Map layouts of the main results are produced. In the back-calculation mode (flag b), cumulative density plots are created. A table evaluating the prediction sucess of all model runs is generated with the flag m.
Start routing from raster pixels (flag x)
Random walks start from all raster pixels where releasemap>0 or, if a release probability map (parameter probmap, with the flag p) or a release indicator score map (parameter scoremap, with the flag q) is given, from all pixels in the area of interest. If a releasefile, but none of the parameters releasemap or probmap is given, the release probability or release indicator score are taken from the releasefile.
prefix
Mandatory prefix applied to all output files and folders. Any type of string can be used, but it is recommended to choose a combination of 3-6 characters to shortly describe the simulation.
mult
When performing multiple model runs (flags m or n), two comma-separated integer numbers have to be given. The first number indicates the number of model runs to be executed, the second number indicates the number of processors to be used. E.g., mult=100,8 starts 100 simulation runs, making use of 8 processors.
cellsize
Pixel size in metres to be used for the model. If the pixel size is not given, it is taken from the input elevation raster map (parameter elevation).
aoicoords
Series of four coordinates (N, S, E, W) delineating the bounding rectangle to applied for the analysis. If this parameter is not given, the bounding rectangle will be determined from the elevation raster map (parameter elevation).
aoimap
Name of integer input raster map of the area of interest to be considered in the model. All pixels with values > 0 are interpreted as part of the area of interest, all other pixels are excluded from the computation. If no area of interest map is given, all non-no data pixels of the elevation raster map (parameter elevation) are used. The bounding box defined by aoicoords applies in any case.
elevation
Name of input elevation raster map. The unit is metres.
releasefile
The relative path to the text file defining the cases to be routed is an optional input. Alternatively, the random walks may start from a releasemap (flag x), a release probability map (parameter probmap, flags p and x) or a release score map (parameter scoremap, flags q and x).
Each line of the case file characterizes on specific case by ten parameters, separated by tabulators:
This file requires a header line following the above naming conventions. The following example shows the possible content of a release file for two cases where the magnitudes are expressed by release volumes and release indicator scores are given.
| ID | TYPE | V | QP | RIS | PR | XR | YR | XS | YS |
| 37 | 2 | 27350 | -9999 | 1 | -9999 | 250222 | 327860 | 250336 | 327522 |
| 44 | 1 | -9999 | 8500 | 4 | -9999 | 261570 | 338126 | 261137 | 337980 |
caserules
This optional parameter defines which models (see parameter models) are applied to which types of cases (see parameter releasefile). For each type of cases, the integer value denoting the type is followed by as many comma-separated integers as models are given in the parameter models. 1 means that the corresponding model shall be applied to the case of the corresponding type, 0 means that this model shall not be used. For two models and two cases, the entry could look as follows:
caserules=1,0,1,2,1,1
If caserules is not given, all models are applied to all cases.
releasemap
Name of an optional input integer raster map defining the observed release area of each case. The pixel values have to correspond to the case id given in the releasefile. zero stands for no case. With the flag x, random walks are started from all pixels of all release areas. If a release probability map (parameter probmap, flags p and x) or a release score map (parameter scoremap, flag q) is provided, the releasemap is not used for the computation, but only for visualization (flag v).
depositmap
Name of an optional input integer raster map defining observed deposition area of each case. Positive pixel values define areas with an observed deposition, pixel values of zero define areas without observed deposition. This map is needed for validation and visualization only (flag v). For validation purposes it is recommended to set the part of the impact area (parameter impactmap) not defined as deposition area to no data.
impactmap
Name of an optional input integer raster map defining the observed impact area of each case. When used for back-calculation (flag b), the pixel values have to correspond to the case id given in the releasefile. zero stands for no case. When used for validation and/or visualization only (flag v), areas with observed impact should be indicated by positive values, areas with no observed impact by zero.
probmap
Name of optional input raster map of the pixel-based release probability Pr in the range 0-1, applicable with the flag p.
scoremap
Name of optional integer input raster map of the pixel-based release indicator score RIS in the range 0-6, applicable with the flag q.
impactobjects
Optional raster map where pixels coinciding with defined impact objects such as buildings take values larger than zero, and pixels not coinciding with such objects take values of zero.
objectscores
The relative path to the text file characterizing the objects denoted by impactobjects is an optional input. Each line of the file represents one object, characterized by the following parameters:
This file requires a header line the content of which, however, does not matter. The following example defines two objects:
| ID | TYPE | SCORE |
| 2 | 2 | 3 |
| 5 | 1 | 4 |
models
Without the flags m and s, five parameters are required for each model:
Given that two models shall be used, the input could look as follows:
models=1,3,1.9,0.16,0.83,2,1,11,-9999,-9999
In this case, the model with the id of 1 would use the model of type 3, which needs all three parameters a, b and c. The model with the ID of 2 would employ the model of type 1, which only needs the parameter a. Therefore the remaining two parameters are not used. It is recommended to set unused parameters to -9999.
Five types of models are available:
| Model type | Model equation | Example reference |
| 1 | omegaT = a | Zimmermann et al. (1997) for debris flows |
| 2 | log10(tan(omegaT))=a*log_10(V)+b | Scheidegger (1973) for rock avalanches |
| 3 | Lmax=a*V^b*Z^c | Rickenmann (1999) for debris flows |
| 4 | omegaT=a*Qp^b | Huggel (2004) for lake outburst floods |
| 5 | vT≤0 | Two-parameter friction model, Perla et al. (1980) |
omegaT = angle of reach, Lmax = maximum horizontal travel distance, Z = vertical distance of motion at termination, V = volume of motion, Qp = peak discharge, vT= velocity of motion at termination.
Five additional parameters are needed with the flag s:
Given that the same two models as in the above example shall be used, the input could look as follows:
models=1,3,1.9,0.16,0.83,5000,100,10,5,2,2,1,11,-9999,-9999,500,100,5,5,2
With the flag m, minima and maxima for constraining the randomization for all parameters except model id and model type have to be defined instead of single values. To avoid randomization of a specific parameter, identical values have to be entered for the minimum and the maximum:
models=1,3,1.6,2.2,0.06,0.26,0.63,1.03,5000,5000,100,100,10,10,5,5,2,2,2,1,7,15,-9999,-9999,-9999,-9999,500,500,100,100,5,5,5,5,2,2
mparams
With the flag s, only two comma-separated parameters have to be specified:
Without the flag s, also the five comma-separated parameters Lctrl, Lseg, Rmax, fbeta and fdir (see parameter models) have do be defined here, directly after log10(nwalks) and Lmin. This means that the same set of the parameters is applied to all models:
mparams=5,20,1000,100,10,5,2
With the flag m, minima and maxima for constraining the randomization have to be entered for all parameters instead of single values. To avoid randomization of a specific parameter, identical values have to be provided for the minimum and the maximum:
mparams=5,5,20,20,200,2000,100,100,10,20,5,5,2,2
retain
Optional floating point number defining the per cent of cases to be retained for validation (applicable with the flag n). The default is 20.
functype
Optional integer number defining the type of probability density function to be applied along with the flags b or n. 1 = Gaussian (the default), 2 = log-normal.
backfile
Relative path to a text file summarizing the back-calculation of the angle of reach and the maximum travel distance of observed mass movements. This file is produced automatically with the flag b and is a mandatory input with the flag n. The file has to consist of four columns. A header line is mandatory, the columns have to be named as follows:
cdffile
Relative path to a text file associating a cumulative probability density function to selected threshold levels of the angle of reach. This parameter is mandatory if the flag p is active whilst the flag n is inactive. The cdffile has to consist of two columns. A header line is mandatory, the columns have to be named as follows:
zonalfile
Relative path to a text file defining the seven parameters needed for computing the zonal release probability. zonalfile is mandatory if the parameter probmap is given in combination with the flag p. The file consists of a header and seven lines, each of them showing the parameter name in the first column and the parameter value in the second column.
profile
Main flow path, given by the coordinates of an unlimited number of points along the flow path, separated by commas in the following sequence: x of first point, y of first point, x of second point and so on (all in metres). Note that the sequence of points has to strictly follow the course of the path, starting at the top and ending at the bottom, without jumping forth and back.
Data structure
The names of all output raster maps, folders and files start with the prefix defined by the parameter prefix. r.randomwalk produces a set of output GRASS raster maps stored in the active mapset as well as a set of txt and tif files stored in subfolders of the folder [prefix]_results:
The subfolder [prefix]_plots, including its content, is produced only if the flag v (validation and visualization of model results) is active. The folder [prefix]_aimec is only produced with the flag m.
Active GRASS mapset
r.randomwalk produces the following output raster maps:
| [prefix]_if | Impact frequency | All modes |
| [prefix]_iii | Impact indicator index | m |
| [prefix]_pi | Impact probability | p |
| [prefix]_picounter | Number of model runs affecting pixel | n+p |
| [prefix]_pi_stdev | Standard deviation of impact probability | a+n+p |
| [prefix]_pic | Composite probability | p+probmap |
| [prefix]_prz | Zonal release probability | p+probmap |
| [prefix]_probcorr | Correction function for zonal release probability | p+probmap |
| [prefix]_arz | Area of possible release zone | p+probmap |
| [prefix]_prz_stdev | Standard deviation of zonal release probability | p+probmap |
| [prefix]_iis | Impact indicator score | q |
| [prefix]_ihis | Hazard indicator score | q+scoremap |
| [prefix]_ris | Risk indicator score | q+scoremap+impactobjects+objectscores |
Folder [prefix]_aimec
With the flag m, this folder contains the automatically generated input folders and files for the validation, parameter sensitivity analysis and optimization tool AIMEC. In order to enable applying this tool to the results produced by r.randomwalk, the content and structure of this folder should not be manipulated manually.
Folder [prefix]_ascii
The output raster maps are exported as ascii rasters in order to be accessible with other software packages. The naming scheme follows the one used for the GRASS raster maps.
Folder [prefix]_files
The following text files summarize the main parameters of the simulation:
Folder [prefix]_plots
The set of plots produced with r.randomwalk includes:
Mergili, M., Krenn, J., Chu, H.-J.: r.randomwalk v1.0, a multi-functional conceptual tool for mass movement routing. Geosci. Model Dev., submitted.
Fischer, J.-T.: A novel approach to evaluate and compare computational snow avalanche simulation. Nat. Haz. Earth Syst. Sci., 13, 1655-1667, 2013.
Zimmermann, M., Mani, P. and Gamma, P.: Murganggefahr und Klimaänderung - ein GIS basierter Ansatz. NFP 31 Schlussbericht, Hochschulverlag an der ETH, Zürich, 1997.
Scheidegger, A. E.: On the Prediction of the Reach and Velocity of Catastrophic Landslides. Rock Mech., 5, 231-236, 1973.
Rickenmann, D.: Empirical Relationships for Debris Flows. Nat. Haz., 19, 47-77, 1999.
Huggel, C.: Assessment of Glacial Hazards based on Remote Sensing and GIS Modeling. Dissertation at the University of Zurich, Schriftenreihe Physische Geographie Glaziologie und Geomorphodynamik, 2004.
Perla, R., Cheng, T. T. and McClung, D. M.: A Two-Parameter Model of Snow Avalanche Motion. J. Glaciol., 26, 197-207, 1980.
Author: Martin Mergili, University of Natural Resources and Life Sciences (BOKU), Vienna, Austria and University of Vienna, Austria
Contributors: Massimiliano Alvioli and Ivan Marchesini, CNR-IRPI Perugia
Funding: German Research Foundation DFG and Austrian Research Fund FWF
Project web site: http://www.mergili.at/randomwalk.html
Last changed: August 1, 2015
Main index - raster index - Full index
© 2010-2015 The author, © 2010-2015 The BOKU University, Vienna, © 2015 The University of Vienna, © 2000-2015 The GRASS Development Team and © 1993-2015 The R Development Core Team