r.slope.stability - The slope stability model - Version: 1.3 - 20170512 (12 May 2017)
raster, slope stability
r.slope.stability [-acdilmpstvz] prefix=string [cellsize=string] [adm=string,string,...] [elldens=string] [elevation=name] [soilclass=name] [gwdepth=name] [observed=name] [slopeunits=name] [dxl=name] [dyl=name] [numlayers=string[,string,...]] [depthmaps=name[,name,...]] [depthvals=string[,string,...]] [depthstats=string,string,...] [prelayers=string] [classlayers=string[,string,...]] [maxlayers=string] [geotech=string,string,...] [seepage=string] [ellips=string,string,...] [sampling=string,string,...] [segsize=string] [nsegs=string] [tilesx=string] [tilesy=string] [overlap=string] [ncores=string] [--verbose] [--quiet]
r.slope.stability is designed for physically-based slope stability analysis of large areas (up to hundreds of square kilometres). It offers three modes of physically-based slope stability simulation. Two of them build on large numbers of randomly located and dimensioned slip surfaces, ellipsoidal or truncated in shape, one uses the infinite slope stability model. Flags are used to determine which of the modes is executed. In principle, r.slope.stability uses an elevation raster map and a system of soil classes and layers. Each soil class or layer is associated with geometric and geotechnical parameters. The mode of simulation is closely associated with the way how the soil classes and layers are organized in space. For the ellipsoid-based modes, it can be chosen whether to consider only the ellipsoid bottom or also the bottom of layers intersecting the ellipsoid. It is further possible to test only one ellipsoid with defined parameters.
A modified version of the Hovland (1977) model is used to compute the safety factor for each ellipsoid. The model works for dry or fully saturated soil and can deal with slope-parallel and layer-parallel seepage. The geotechnical details of the model are outlined in Mergili et al. (2014b).
Alternatively to the factor of safety, the model can be used to compute the slope failure probability. In this mode the program, for each ellipsoid, samples a user-defined number of values of cohesion, angle of internal friction and - optionally - truncated depth. Using probability density functions, a probability of slope failure in the range 0-1 is derived for each ellipsoid and, consequently, for each pixel (Mergili et al. (2014a)).
r.slope.stability further offers the possibility for exploiting the advantages of multi-core computers (reducing computing time; Mergili et al., 2014a)) and allows choosing inhowfar to use the GRASS Segment Library. It contains comprehensive functionalities for the empirical confirmation of the model results against a landslide inventory and for the visualization of the results.
Please note that the application of r.slope.stability requires the availability of detailed geotechnical data. Simulations with unreliable data will provide invalid output. Also with detailed and carefully investigated data, the huge variability of geotechnical and geohydraulic parameters in space leads to a considerable degree of uncertainties reflected also in the model results. Given the fact that slope stability is a critical topic where the dissemination of incorrect information may lead to severe unwanted consequences, the interpretation of the model results requires extreme care and a high level of experience. The output maps are by no means hazard or risk maps, but only susceptibility maps highlighting those areas where the occurrence of landslides could be more likely than in others. The authors strictly refuse any legal or moral responsibility for any type of negative consequences emanating from the use of the r.slope.stability software.
r.slope.stability was developed and tested on Ubuntu 12.04 LTS and 16.04LTS, but is expected to work in other LINUX environments, too. It relies on GRASS GIS 7, installation of r.slope.stability requires the grass-dev and grass-doc packages. Visualization and empirical confirmation 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.slope.stability: fmsb, stats (pre-installed), sp, raster, rgdal, and ROCR. The code builds on Python 2.7 and C. The script grass7.install.sh provided with r.slope.stability 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.
As soon as all software requirements are fulfilled, the installation of r.slope.stability 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.
Additional output rasters (flag a)
If this flag is not specified, only the factor of safety or the slope failure probability (flag p) is provided as output raster. Reducing the number of output raster maps may be useful particularly for parallel processing (flag m with large numbers of tiles. If the flag is specified, several more output raster maps are produced (see section Output). This flag is disregarded with the flag i and is currently not recommended with the flag p.
Soil class mode (flag c)
The study area is horizontally split into a number of soil classes. Each soil class is associated with a defined number of layers (the number of layers may be different for different soil classes), carrying information on depth and geotechnical parameters. The soil class-based mode is suitable for relatively simple geological conditions (few layers with more or less regular depth) or relatively shallow potential landslides. A large number of randomized ellipsoidal or truncated slip surfaces is tested.
Infinite slope stability mode (flag i)
Soil classes and layers are discretized in the same way as for the soil class mode. The infinite slope stability model is a very simple, purely pixel-based approach suitable only for shallow slope stability.
Layer mode (flag l)
A number of geological layers is defined by a set of raster maps of layer bottom depth. The number of the layers may be large (>50) and their geometry may be irregular. Not all of the layers have to extend over the entire study area, they may reach the terrain surface or disappear in the depth. Each of the layers is assigned to a soil class associated with geotechnical parameters. A large number of randomized ellipsoidal or - typically - truncated slip surfaces is tested.
The soil class and layer modes may alternatively be run for one single ellipsoid with exactly defined parameters.
Please note that only one of the flags c, i and l may be specified. Specifying two or three of them will result in an error message. The remaining flags can be combined almost arbitrarily, even though some combinations are automatically disabled.
Documentation (flag d)
A summary file is written, containing the geometric parameters and factors of safety of each ellipsoid tested. Each line of the file corresponds to one ellipsoid. Please note that the summary file can get very large in case a large number of ellipsoids is tested. With multi-core processing (flag m), one summary file is written for each tile.
Multi-core processing (flag m)
The study area is split into a defined number of tiles (parameters tilesx, tilesy and overlap). Slope stability is computed separately from each tile, making use of multiple cores, if available (parameter ncores). Finally, the results from all tiles are put together. This strategy helps to reduce computing time particularly in case of large study areas.
Slope failure probability (flag p)
Slope failure probability is assigned to each pixel in addition to a factor of safety (see parameters geotech, depthstats and sampling and section Output). Samples of the geotechnical parameters and, optionally, truncated depth, are considered for each ellipsoid.
Excessive use of GRASS Segment Library (flag s)
The GRASS segment library enables the efficient storage of large rasters. It can deal with much larger datasets than arrays, however at a reduced performance. r.slope.stability makes use of the segment library by default, but also uses arrays. Providing the flag s suppresses the use of arrays, applying the segment library more extensively instead. This is particularly useful in case that the maximum extent of the largest possible ellipsoid is very large, compared to the raster cell size (parameter cellsize), when the simulation fails otherwise.
Truncation of ellipsoids (flag t)
Not only the ellipsoid bottom is considered as possible slip surface, but also the bottom of layers, if it is above the ellipsoid bottom. This possibly results in multiple factors of safety for one slip surface. All of them are given in the summary file (if the flag d is specified), the lowest safety factor and the associated slip surface are considered for the output maps.
Empirical confirmation and visualization (flag v)
A number of evaluation procedures is carried out with the model results, requiring a map of observed landslides (parameter observed). These results are visualized by diagram plots. Further, map layouts of the main output raster maps are produced.
Test mode for multi-core processing (flag z)
The results from the tiles are not put together, saving computing time when testing model performance. This flag is only relevant in combination with multi-core processing (flag m).
Please consult the section Output for a detailed description of the output of r.slope.stability.
Prefix for the output files and folders. Any type of string can be used, but it is recommended to choose a combination of approx. 3-8 characters characterizing the simulation the output is associated with.
Raster cell size in metres to be used for the simulation.
Bounding box of detailed output maps (with flag v). The coordinates (in metres) have to be entered separated by commas in the following sequence: north, south, west, east. If the parameter is not specified, no detailed output maps are produced.
The ellipsoid density stands for the average number of ellipsoids touching each raster cell. Due to the randomized simulation process it is an approximate value which is used to determine the number of ellipsoids to be tested. The ellipsoid density should be large enough to cover all possible situations so that the area with a factor of safety smaller than 1 remains constant also when testing further ellipsoids. The evolution plot (see section Output) indicates whether this criterion has been fulfilled or whether the simulation has to be repeated with a higher ellipsoid density. The ellipsoid density required to fulfill this criterion depends on the specific situation, but typically exceeds values of 2000.
If a value of 0 is specified, only one single ellipsoid is tested (see also parameter ellips).
Raster map of observed landslides, required for empirical confirmation of the results (some functions associated with the flag v). Raster cells with observed landslides have to be assigned the value of 1, cells with no observed landslides the value 0. Here, it is important to differentiate between 0 and no data cells.
Elevation raster map in metres.
Soil class raster map. Each soil class has to be represented by an integer number. It is required to use consecutive numbers starting from 1: if the study area is split into four soil classes, it is obligatory to use numbers 1,2,3 and 4 and not, e.g., 1, 3, 6 and 8. Pixels with 0 are treated as no data. In the layer mode (flag l), the soil classes specified in the soil class map are used for those pixels where no layer is specified.
Depth of groundwater table raster map in metres.
Map of slope units for the study area, useful for empirical confirmation (flag v). Each slope unit has to be represented by a unique positive integer value. 0 is treated as no data.
Average slope of all the layers in x direction, expressed as ratio. This raster map is required in the layer mode (flag l) when the parameter seepage is set to 2 (layer-parallel seepage). If, in this case, dxl is not specified, it is computed automatically, slightly increasing the computing time.
Average slope of all the layers in y direction, expressed as ratio. This raster map is required in the layer mode (flag l) when the parameter seepage is set to 2 (layer-parallel seepage). If, in this case, dyl is not specified, it is computed automatically, slightly increasing the computing time.
In the soil class mode (flag c) and the infinite slope stability mode (flag i), the number of layers has to be specified for each soil class, separated by commas. For a study area with six soil classes, each of them with two layers, the input would look as follows:
In the soil class mode (flag c) and the infinite slope stability mode (flag i), the depth of each layer can be specified using a raster map containing the depth of the layer bottom in metres. The names of the maps, one for each layer, have to be separated by commas. The input for a three-layer study area could look as follows:
In the soil class mode (flag c) and the infinite slope stability mode (flag i), depthvals can be specified alternatively to depthmaps (one of the two parameters is required). Here, the depth of the bottom of each layer of each soil class has to be specified in metres. Input has to start with the first (top) layer of soil class 1, followed by the second layer of soil class 1 etc. When the input for soil class 1 is completed, the same procedure follows for soil class 2, 3 and so on. The input for a study area with four soil classes, each with two layers with bottom depths of 2 and 10 m, would look as follows:
This parameter may be specified in the soil class or infinite slope stability modes (flags c or i) in combination with the flag p, in order to sample not only multiple values of the the geotechnical parameters, but also of truncated depth. It consists in a series of four comma-separated values: average, standard deviation, minimum and maximum truncated depth, which will most commonly coincide with the depth of soil or regolith. These values are needed for construction a probability density function of depth and to constrain sampling (see parameter sampling).
In the layer mode (flag l), the prefix for the names of the layer bottom depth maps has to be specified. This means that the maps for all layers have to be named consistently with of the prefix and the number of the layer.
In the layer mode (flag l), the soil class for each layer has to be specified, separated by commas. For a study area with five layers and four soil classes, the input could look as follows:
In the layer mode (flag l), the maximum number of layers relevant for a single ellipsoid cannot be determined analytically at the start. However, this parameter is important for dimensioning of arrays needed for the simulation. If the value is too large, memory is used unnecessarily. If the value is too small, the simulation does not yield valid results. Usually, the number specified will be a first guess and, if it is inappropriate, the simulation has to be repeated (the real maximum number of layers is printed at the end of the simulation). If maxlayers is not specified, the value is automatically set to four times the maximum number of layers for one raster cell.
For computing the factor of safety, four parameters are required for each soil class or layer:
Technically, any soil water content can be entered. However, as r.slope.stability cannot deal with partial saturation, it is highly recommended to specify either 0 (for dry soil) or the saturated water content (for saturated soil). Note that, in the case the parameter gwdepth is provided, the soil above the groundwater table is considered dry, overruling the soil water content given for the respective soil class and layer.
In the soil class mode (flag c) or the infinite slope stability mode (flag i), the four comma-separated parameters in the sequence given above are preceded by the number of the soil class and the number of the layer. Input has to start with the first (top) layer of soil class 1, followed by the second layer of soil class 1 etc. When the input for soil class 1 is completed, the same procedure follows for soil classes 2, 3 and so on. Given that we have two soil classes with two layers each, the input could look as follows:
In the layer mode (flag l), the four comma-separated parameters in the sequence given above are preceded by the number of the soil class. Input has to start with soil class 1, followed by soil class 2, 3 and so on. The parameters are then automatically assigned to the layers, based on the soil class given for each layer (parameter classlayers. Given that we have three soil classes, the input could look as follows:
For computing the slope failure probability (flag p), six additional comma-separated parameters have to be defined for each soil class and layer in the following sequence after θs:
The original value (which would be used for the factor of safety) is taken as average for building the probability density functions. The minima and maxima of the parameters determine the constraints for looping over a range of values. The sampling strategy is defined by the parameter sampling.
r.slope.stability can work with three assumptions of seepage direction
Typically, r.slope.stability makes use of a large number of randomized ellipsoids (flags c or l). The following parameters determine how the randomization is constrained. They have to be entered in the specified sequence, separated by commas:
Most applications - particularly those testing a large number of ellipsoids - will build on randomized center coordinates and with ellipsoids aligned to the slope. However, specifying the coordinates, aspect and slope is useful for testing one single ellipsoid (parameter elldens=0).
The slope failure probability (flag p) is derived by computing the factor of safety for a number of combinations of c', φ' and, optionally, truncated depth. The higher the number of combinations yielding a factor of safety smaller than 1, the higher the slope failure probability. The parameter values are sampled according to the constraints and statistical properties defined by the parameters geotech and depthstats. The sammpling strategy is defined by seven comma separated integer numbers:
Size of one segment (GRASS Segment Library). If not specified, the value is set to 16.
Number of segments to be held in memory (GRASS Segment Library). If not specified, the value is set to 16.
Number of tiles in x direction, required for multi-core processing (flag m). Any positive integer number is valid in principle. However, tiles should not be too small ( they should have several times the extent of the largest possible ellipsoid, parameter ellips).
Number of tiles in y direction, required for multi-core processing (flag m). Any positive integer number is valid in principle. However, tiles should not be too small ( they should have several times the extent of the largest possible ellipsoid, parameter ellips).
Overlap between tiles (multi-core processing, flag m) in order to ensure full coverage by the largest possible ellipsoid (parameter ellips). The overlap is also used for empirical confirmation (flag v) in order to exclude lateral areas not fully covered by the computation.
Number of cores to use for multi-core processing (flag m).
The names of all output raster maps, folders and files start with the prefix defined by the parameter prefix. r.slope.stability 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 folders [prefix]_hmaps, [prefix]_maps and [prefix]_plots including their content as well as part of the content of the folder [prefix]_files are produced only with the flag v (empirical confirmation and and visualization). If the flag was not specified, the output can be procuced afterwards by the command
r.slope.stability -v prefix=[prefix]
This step is only possible if the output raster maps still exist in the active GRASS mapset and the directory [prefix]_results has remained unchanged since the original computation. However, advanced users may manually adapt the content of the text file [prefix]_documentation.txt.
Active GRASS mapset
r.slope.stability produces the following output raster maps (if the flag a is not specified, only the factor of safety or the slope failure probability is provided as output raster map):
The following text files summarize the main parameters of the simulation or are needed for the construction of the plots in the folder [prefix]_plots:
Colour layouts of the output raster maps are produced both for the entire study area ([prefix]_map_[content].tif) and, if specified, for the extent given by the parameter adm ([prefix]_dmap_[content].tif), where [content] stands for the content of the map and follows the same scheme as for the GRASS raster maps. If a raster map of observed landslides was specified (parameter observed), the landslide boundaries are displayed as lines as well as the extent used for the empirical confirmation of the results. A hillshade derived from the elevation raster map is shown as background.
The content is largely identical to the content of the folder [prefix]_hmaps, but no hillshades are shown as background. Even though provided in colour, these maps are also suitable for presentation in shades of gray.
All plots are provided in colours, but are also well readable when converted to shades of gray:
The output raster maps are exported as geotiff images in order to be accessible with other software packages. The naming scheme follows the one used for the GRASS raster maps: [prefix]_[content].tif, where [content] stands for the content of the map.
Hovland, H.J. (1977): Three-dimensional slope stability analysis method. Journal of the Geotechnical Engineering Division. Proceedings of the American Society of Civil Engineers 103(GT9), 971-986.
Mergili, M., Marchesini, I., Alvioli, M., Metz, M., Schneider-Muntau, B., Rossi, M., Guzzetti, F. (2014a): A strategy for GIS-based 3D slope stability modelling over large areas. Geoscientific Model Development 7, 2969-2982. Access article
Mergili, M., Marchesini, I., Rossi, M., Guzzetti, F., Fellin, W. (2014b): Spatially distributed three-dimensional slope stability modelling in a raster GIS. Geomorphology 206, 178-195. Access article
Martin Mergili, University of Natural Resources and Life Sciences (BOKU) and University of Vienna, Vienna, Austria
Ivan Marchesini and Massimiliano Alvioli, CNR-IRPI, Perugia, Italy
The support of Wolfgang Fellin, Fausto Guzzetti, Markus Metz, and Mauro Rossi is acknowledged.
Last changed: May 12, 2017.
© 2010-2017 The authors, © 2010-2017 BOKU University, Vienna, © 2015-2017 University of Vienna, © 2012-2017 CNR-IRPI, © 2000-2017 GRASS Development Team and © 1993-2017 R Development Core Team