Skip to content

r.slopeunits.optimize

Optimize inputs for slope units

r.slopeunits.optimize [-s] demmap=name [plainsmap=name] basin=name slumap=name [slumapclean=name] thresh=float rf=integer maxiteration=integer cleansize=float cvmin=min,max areamin=min,max epsilonx=float epsilony=float outdir=name [convergence=integer] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.slopeunits.optimize demmap=name basin=name slumap=su_tmp thresh=0.0 rf=0 maxiteration=0 cleansize=25000 cvmin=0.05,0.25 areamin=50000.0,200000.0 epsilonx=0.01 epsilony=50000 outdir=outdir

grass.script.run_command("r.slopeunits.optimize", demmap, plainsmap=None, basin, slumap="su_tmp", slumapclean="su_tmp_cl", thresh, rf, maxiteration, cleansize=25000, cvmin="0.05,0.25", areamin="50000.0,200000.0", epsilonx=0.01, epsilony=50000, outdir="outdir", convergence=5, flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.run_command("r.slopeunits.optimize", demmap="name", basin="name", slumap="su_tmp", thresh=0.0, rf=0, maxiteration=0, cleansize=25000, cvmin=0.05,0.25, areamin=50000.0,200000.0, epsilonx=0.01, epsilony=50000, outdir="outdir")

grass.tools.Tools.r_slopeunits_optimize(demmap, plainsmap=None, basin, slumap="su_tmp", slumapclean="su_tmp_cl", thresh, rf, maxiteration, cleansize=25000, cvmin="0.05,0.25", areamin="50000.0,200000.0", epsilonx=0.01, epsilony=50000, outdir="outdir", convergence=5, flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.r_slopeunits_optimize(demmap="name", basin="name", slumap="su_tmp", thresh=0.0, rf=0, maxiteration=0, cleansize=25000, cvmin=0.05,0.25, areamin=50000.0,200000.0, epsilonx=0.01, epsilony=50000, outdir="outdir")

This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.

Parameters

demmap=name [required]
    Input digital elevation model
plainsmap=name
    Input raster map of alluvial plains
basin=name [required]
    Name of input vector map
    Input basin passed to r.slopeunits.metrics
slumap=name [required]
    Slope Units layer (the main output of r.slopeunits.create)
    Default: su_tmp
slumapclean=name
    Slope Units layer, cleaned (the main output of r.slopeunits.clean)
    Default: su_tmp_cl
thresh=float [required]
    Initial threshold (m^2)
rf=integer [required]
    Factor used to iterativelly reduce initial threshold
maxiteration=integer [required]
    maximum number of iteration to do before stopped
cleansize=float [required]
    Slope Units size to be removed
    Default: 25000
cvmin=min,max [required]
    Start search with these initial minimum and maximum values of the circular variance (0.0-1.0) below which the slope unit is not further segmented
    Default: 0.05,0.25
areamin=min,max [required]
    Start search with these initial minimum and maximum values of the area (m^2) below which the slope unit is not further segmented
    Default: 50000.0,200000.0
epsilonx=float [required]
    Stop loop when difference of cvmin limits is lesser than this value
    Default: 0.01
epsilony=float [required]
    Stop loop when difference of areamin limits is lesser than this value
    Default: 50000
outdir=name [required]
    Output directory for intermediate results for all cvmin and areamin values and final results. Default folder "outdir" in current working directory.
    Default: outdir
convergence=integer
    Convergence factor for MFD in r.watershed (1-10)
    1 = most diverging flow, 10 = most converging flow. Recommended: 5
    Default: 5
-s
    SFD (D8) flow in r.watershed (default is MFD)
    SFD: single flow direction, MFD: multiple flow direction
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

demmap : str, required
    Input digital elevation model
    Used as: input, raster, name
plainsmap : str, optional
    Input raster map of alluvial plains
    Used as: input, raster, name
basin : str, required
    Name of input vector map
    Input basin passed to r.slopeunits.metrics
    Used as: input, vector, name
slumap : str, required
    Slope Units layer (the main output of r.slopeunits.create)
    Used as: output, raster, name
    Default: su_tmp
slumapclean : str, optional
    Slope Units layer, cleaned (the main output of r.slopeunits.clean)
    Used as: output, raster, name
    Default: su_tmp_cl
thresh : float, required
    Initial threshold (m^2)
rf : int, required
    Factor used to iterativelly reduce initial threshold
maxiteration : int, required
    maximum number of iteration to do before stopped
cleansize : float, required
    Slope Units size to be removed
    Default: 25000
cvmin : tuple[float, float] | list[float] | str, required
    Start search with these initial minimum and maximum values of the circular variance (0.0-1.0) below which the slope unit is not further segmented
    Used as: min,max
    Default: 0.05,0.25
areamin : tuple[float, float] | list[float] | str, required
    Start search with these initial minimum and maximum values of the area (m^2) below which the slope unit is not further segmented
    Used as: min,max
    Default: 50000.0,200000.0
epsilonx : float, required
    Stop loop when difference of cvmin limits is lesser than this value
    Default: 0.01
epsilony : float, required
    Stop loop when difference of areamin limits is lesser than this value
    Default: 50000
outdir : str, required
    Output directory for intermediate results for all cvmin and areamin values and final results. Default folder "outdir" in current working directory.
    Used as: input, dir, name
    Default: outdir
convergence : int, optional
    Convergence factor for MFD in r.watershed (1-10)
    1 = most diverging flow, 10 = most converging flow. Recommended: 5
    Default: 5
flags : str, optional
    Allowed values: s
    s
        SFD (D8) flow in r.watershed (default is MFD)
        SFD: single flow direction, MFD: multiple flow direction
overwrite : bool, optional
    Allow output files to overwrite existing files
    Default: None
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

demmap : str | np.ndarray, required
    Input digital elevation model
    Used as: input, raster, name
plainsmap : str | np.ndarray, optional
    Input raster map of alluvial plains
    Used as: input, raster, name
basin : str, required
    Name of input vector map
    Input basin passed to r.slopeunits.metrics
    Used as: input, vector, name
slumap : str | type(np.ndarray) | type(np.array) | type(gs.array.array), required
    Slope Units layer (the main output of r.slopeunits.create)
    Used as: output, raster, name
    Default: su_tmp
slumapclean : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Slope Units layer, cleaned (the main output of r.slopeunits.clean)
    Used as: output, raster, name
    Default: su_tmp_cl
thresh : float, required
    Initial threshold (m^2)
rf : int, required
    Factor used to iterativelly reduce initial threshold
maxiteration : int, required
    maximum number of iteration to do before stopped
cleansize : float, required
    Slope Units size to be removed
    Default: 25000
cvmin : tuple[float, float] | list[float] | str, required
    Start search with these initial minimum and maximum values of the circular variance (0.0-1.0) below which the slope unit is not further segmented
    Used as: min,max
    Default: 0.05,0.25
areamin : tuple[float, float] | list[float] | str, required
    Start search with these initial minimum and maximum values of the area (m^2) below which the slope unit is not further segmented
    Used as: min,max
    Default: 50000.0,200000.0
epsilonx : float, required
    Stop loop when difference of cvmin limits is lesser than this value
    Default: 0.01
epsilony : float, required
    Stop loop when difference of areamin limits is lesser than this value
    Default: 50000
outdir : str, required
    Output directory for intermediate results for all cvmin and areamin values and final results. Default folder "outdir" in current working directory.
    Used as: input, dir, name
    Default: outdir
convergence : int, optional
    Convergence factor for MFD in r.watershed (1-10)
    1 = most diverging flow, 10 = most converging flow. Recommended: 5
    Default: 5
flags : str, optional
    Allowed values: s
    s
        SFD (D8) flow in r.watershed (default is MFD)
        SFD: single flow direction, MFD: multiple flow direction
overwrite : bool, optional
    Allow output files to overwrite existing files
    Default: None
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

Returns:

result : grass.tools.support.ToolResult | np.ndarray | tuple[np.ndarray] | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned. If an array type (e.g., np.ndarray) is used for one of the raster outputs, the result will be an array and will have the shape corresponding to the computational region. If an array type is used for more than one raster output, the result will be a tuple of arrays.

DESCRIPTION

r.slopeunits.optimize determines optimal input values for slope units:

  • "areamin" - Minimum area (m^2) below which the slope unit is not further segmented
  • "cvmin" - Minimum value of the circular variance (0.0-1.0) below which the slope unit is not further segmented

It calls r.slopeunits.create, r.slopeunits.clean, and r.slopeunits.metrics iteratively. Output is a file opt.txt with optimal values in either specified folder or in folder output/" in the current working directory. Also files calcd.dat and current.txt are created with all determined and examined values and the four latest examined values (combination of areamin`` and ``cvmin`` minimum and maximum) and ``center``, respectively.

EXAMPLE

r.slopeunits.optimize \
    basin=basin_chk \
    demmap=dem_italia_isolegrandi@su_test \
    plainsmap=flat \
    thresh=250000 \
    rf=2 \
    maxiteration=50 \
    cleansize=25000

REFERENCES

  • Alvioli, M., Marchesini, I., Reichenbach, P., Rossi, M., Ardizzone, F., Fiorucci, F., and Guzzetti, F. (2016): Automatic delineation of geomorphological slope units with r.slopeunits v1.0 and their optimization for landslide susceptibility modeling, Geosci. Model Dev., 9, 3975-3991. DOI:10.5194/gmd-9-3975-2016
  • Alvioli, M., Guzzetti, F., & Marchesini, I. (2020): Parameter-free delineation of slope units and terrain subdivision of Italy. Geomorphology, 358, 107124. DOI:10.1016/j.geomorph.2020.107124

SEE ALSO

r.slopeunits.create, r.slopeunits.clean, r.slopeunits.metrics

AUTHORS

Main authors: Ivan Marchesini, Massimiliano Alvioli, CNR-IRPI
Carmen Tawalika (translation to python, refactoring), mundialis

SOURCE CODE

Available at: r.slopeunits.optimize source code (history)
Latest change: Wednesday May 07 16:16:50 2025 in commit 8af96b6