GRASS logo

NAME

Mass movement, Random walk, Raster, Routing

SYNOPSIS

r.randomwalk Version 1.2 (20170320)
r.randomwalk help
r.randomwalk [-abkmnpqsvx] prefix=string [cores=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 [sampling=integer] [retain=float] [functype=integer] [backfile=string] [cdffile=string] [zonalfile=string] [profile=float,...] [--verbose] [--quiet]

Flags:

-a
Average of impact probability
-b
Back-calculate observation
-k
Keep result GRASS raster maps
-m
Multiple model runs with random parameters
-n
Multiple model runs with random release
-p
Probabilities
-q
Scores
-s
Separate random walks for each model
-v
Validation and visualization of results
-x
Start routing from raster pixels
--verbose
Verbose module output
--quiet
Quiet module output

Parameters:

prefix=string
Prefix for output files and folders
[cores=integer]
Number of cores to be used
[cellsize=float]
Pixel size in metres
[aoicoords=float,...]
Set of coordinates delineating area of interest (N,S,E,W)
[aoimap=name]
Name of area of interest raster map
elevation=name
Name of elevation raster map
[releasefile=string]
Path to text file with information on the cases to be routed
[caserules=integer,integer,...]
Rules for associating models to case types
[releasemap=name]
Name of raster map representing the ids of the cases to be routed
[depositmap=name]
Name of observed deposition areas raster map
[impactmap=name]
Name of observed impact areas raster map
[probmap=name]
Name of raster map representing release probabilities of the cases to be routed
[scoremap=name]
Name of raster map representing release hazard indicator scores of the cases to be routed
[impactobjects=name]
Name of impact objects id raster map
[objectscores=string]
Path to file with scores of impact objects
models=string
Models to be used and related parameters
mparams=string
General parameters
[sampling=integer]
Parameter sampling
[retain=float]
Per cent of cases to be retained for validation
[functype=integer]
Type of probability density function of angle of reach
[backfile=string]
Path to back-calculation result file
[cdffile=string]
Path to cumulative probability densities for values of angle of reach
[zonalfile=string]
Path to text file with correction and error parameters for zonal release probability
[profile=float,...]
Coordinates of profile along path of movement

DESCRIPTION

General aspects

r.randomwalk is a flexible and multi-functional conceptual tool for backward- and forward-analyses of mass movement motion. 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 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.

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., 2015) whilst a number of test cases and applications is collected at http://www.randomwalk.org.

Software requirements

r.randomwalk was developed and tested on Ubuntu 12.04 LTS and 16.04LTS as well as on Red Hat 6.6 (Scientific Linux), but is expected to work in other LINUX environments, too. It relies on GRASS GIS 7, installation of r.randomwalk requires the grass-dev package. Visualization and validation of the model results (flag v) makes use of the R Project for Statistical Computing (recommended version: 3.0.2 or higher). The following packages of R are required in order to fully explore the functionalities offered by r.randomwalk: maptools, stats, sp, rgeos, rgdal, ROCR and raster. The code builds on Python 2.7 and C. The script grass7.install.sh provided with r.randomwalk can be used to automatically install all the software needed on fresh installations of Ubuntu 16.04LTS. The script has to be called from the terminal as superuser (requiring administrator rights): sudo sh grass7.install.sh.

Installation

As soon as all software requirements are fulfilled, the installation of r.randomwalk is straightforward and just requires a few more steps. Please note that you need administrator rights (access to sudo) and that some manual modifications of the installation script might be required.

Flags

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

Keep result GRASS raster maps (flag k)

Particularly with a very large number of model runs (flag m and parameter cores), a huge amount of GRASS raster maps is produced which are often not needed, but require a considerable amount of disk space. Without the flag k all result GRASS raster maps stored in the active mapset are deleted, with the flag they are kept.

Multiple model runs with random parameters (flag m)

Multiple model runs are executed with parameters varied in a random or controlled manner (parameter sampling) between upper and lower boundaries 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 probmap or scoremap is given, the release probability (with the flag p) or release indicator score (with the flag q) is taken from the releasefile.

Parameters

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.

cores

When performing multiple model runs (flags m or n), the number of processors to be used is a mandatory input. E.g., cores=8 induces the 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.

IDTYPEVQPRISPRXRYRXSYS
37227350-99991-9999250222327860250336327522
441-999985004-9999261570338126261137337980

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:

IDTYPESCORE
223
514

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 or controlled variation (parameter sampling) for all parameters except model id and model type have to be defined instead of single values. For controlled sampling (sampling=0), a third value denoting the number of values to be tested has to be entered for each parameter. Also for one-at-a-time sampling (sampling= lower than 0), a third value has to be entered for each parameter, denoting its initial estimate. To avoid varying 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 or controlled variation (parameter sampling) have to be entered for all parameters instead of single values. For controlled sampling (sampling=0), a third value denoting the number of values to be tested has to be entered for each parameter. Also for one-at-a-time sampling (sampling= lower than 0), a third value has to be entered for each parameter, denoting its initial estimate. To avoid varying 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

sampling

This parameter is mandatory along with the flags m and n. With the flag m it defines the type of sampling of the parameters given by models and mparams: integer values larger than 0 = random sampling (the default; the value given denotes the number of model runs i.e., the sample size), 0 = controlled sampling, integer values smaller than 0 = one-at-a-time sampling (the value given, if multiplied by -1, denotes the number of model runs i.e., the sample size, for each parameter). With controlled or one-at-a-time sampling, the number of model runs is applied to generate a uniform distribution between the minimum and the maximum of each parameter which is varied. This means that the actual number of model runs is the product of the sample sizes associated to all the varied parameters. With the flag n, sampling has to be a positive integer number defining the number of random subsets of the area of interest the model is applied to.

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

Output

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 png 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 which are, however, only stored permanently with the flag k:

[prefix]_ifImpact frequencyAll modes
[prefix]_iiiImpact indicator indexm
[prefix]_piImpact probabilityp
[prefix]_picounterNumber of model runs affecting pixeln+p
[prefix]_pi_stdevStandard deviation of impact probabilitya+n+p
[prefix]_picComposite probabilityp+probmap
[prefix]_przZonal release probabilityp+probmap
[prefix]_probcorrCorrection function for zonal release probabilityp+probmap
[prefix]_arzArea of possible release zonep+probmap
[prefix]_prz_stdevStandard deviation of zonal release probabilityp+probmap
[prefix]_iisImpact indicator scoreq
[prefix]_ihisHazard indicator scoreq+scoremap
[prefix]_risRisk indicator scoreq+scoremap+impactobjects+objectscores[prefix]_velocityFlow velocityModel type 5

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:

Two additional text files, aucroc.txt and aucrocn.txt, are produced along with the ROC Plots. These files are stored directly in the working directory and display the prefix of the computation along with the corresponding value of AUCROC: in aucroc.txt, the value refers to the entire area of interest, while in aucrocn.txt, a normalized TN per cent value is used. These two files are not overwritten during the next execution of r.randomwalk. Instead, a new line is added each time r.randomwalk is run with the flag v. This facilitates the analysis of the AUCROC values in case of multiple executions of r.randomwalk.

REFERENCES

Mergili, M., Krenn, J., Chu, H.-J.: r.randomwalk v1, a multi-functional conceptual tool for mass movement routing. Geosci. Model Dev. 8, 4027-4043.

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.

AUTHORS AND SUPPORT

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.randomwalk.org

Last changed: March 20, 2017


Main index - raster index - Full index

© 2010-2017 The author, © 2010-2017 The BOKU University, Vienna, © 2017 The University of Vienna, © 2000-2017 The GRASS Development Team and © 1993-2017 The R Development Core Team