m.swim.subbasins.py - GRASS GIS manual

NAME

m.swim.subbasins.py - Soil and Water Integrated Model (SWIM) subbasin preprocessor

KEYWORDS

SYNOPSIS

m.swim.subbasins.py

m.swim.subbasins.py --help

m.swim.subbasins.py [-dglskv] elevation=name stations=name streamthresh=km2 [upthresh=float] [lothresh=km2] [upthreshcolumn=name] [depression=name] [accumulation=string] [drainage=string] [streams=string] [subbasins=string] [catchments=string] [catchmentprefix=string] [stations_snapped=string] [slopesteepness=string] [slopelength=string] [streamcarve=vector] [predefined=string] [rwatershedflags=string] [rwatershedmemory=integer MB] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-d: don't process DEM (accumulation, drainage, streams must exist)
-g: Create regular grid subbasins interpreting upthresh as the grid size.
-l: Create regular lonlat grid subbasins interpreting upthresh as the grid size.
-s: Just print statistics of subbasins, --o must be set
-k: Keep intermediat files (include __ in names)
-v: Show version and change/install date of this module and grass.
--overwrite: Allow output files to overwrite existing files
--help: Print usage summary
--verbose: Verbose module output
--quiet: Quiet module output
--ui: Force launching GUI dialog

Parameters:

elevation=name [required]: Elevation raster (hole-filled)
stations=name [required]: Station point vector; Will be snapped to the nearest stream
streamthresh=km2 [required]: Drainage area of smallest stream in km2 (influences station snapping); Stations will be snapped to these streams, ie. should not be smaller than the smallest catchment.
upthresh=float: Upper subbasin threshold (in sq km,mostly underestimated); ignored if upthreshcolumn is given, mostly underestimated; Default: 100
lothresh=km2: Lower threshold of subbasin size in sq km (default 5% of upper)
upthreshcolumn=name: Column with upper subbasin threshold in stations vector
depression=name: Raster map of known real depressions in or around catchment (only if not -d)
accumulation=string: Name of accumlation map to be created (or existing if -d); Default: accumulation
drainage=string: Name of drainge map to be created (or existing if -d); Default: drainage
streams=string: Name of streams vector to be created (or existing if -d); Default: streams
subbasins=string: Name of resulting subbasin vector and raster map; Default: subbasins
catchments=string: Name of resulting vector and raster of all stations catchments; Default: catchments
catchmentprefix=string: Prefix of individual catchment vector for each station; Default: catchment_
stations_snapped=string: Stations as snapped to streams plus some additional info in the table; Default: stations_snapped
slopesteepness=string: USLE slopesteepness from r.watershed, useful for m.swim.substats; Default: slopesteepness
slopelength=string: USLE slope length from r.watershed, useful for m.swim.substats; Default: slopelength
streamcarve=vector: Existing river network to be carved into the elevation raster
predefined=string: Raster of predefined units to include in the subbasin map
rwatershedflags=string: Flags parsed to r.watershed, check r.watershed --help; Default: s
rwatershedmemory=integer MB: Limits memory usage of r.watershed in MB (slower)

DESCRIPTION

The m.swim.subbasins module provides flexible interface to the r.watershed module allowing the delineation of subbasins within a specified subbasin size range, constraining them to any amount gauging stations as well as including predefined subbasins and the production of rich ancillary maps and subbasin information (provided in the subbasins vector table). The module works in two steps:

It first calculates the accumulation, drainage and streams for the entire region. This step can be skipped by setting the -d flag to save time when recalculating the subbasins, but the accumulation, drainage and streams raster must exist in that case. This step also outputs the slope steepness and slope length rasters needed for the m.swim.substats module (names given by default).
Then it calculates the catchments and subbasins for each station given in stations, cleans the subbasin maps and produces the additional subbasin information and outputs the subbasin statistics to stdout.

Subbasin size thresholds

The upper subbasin size threshold given either for all catchments in upthresh or for each station's catchment individually by reading the station's column given in upthreshcolumn is a soft limit, i.e. it may exceed this and should be more considered a mean subbasin size, as it is mostly underestimated (see the r.watershed manual for more details). The lothresh argument, however, is a hard lower limit, i.e. no subbasins smaller than this should exist in the resultant subbasin map.

NOTES

Although this module has been tested, it is still in beta mode and hasn't been extensively error coded. Please report unexplained errors to the author (see below).

EXAMPLE

Setting up a SWIM project in the North Carolina (basic) testing location:

Create a new mapset and set region:

g.mapset -c mapset=subbasins
g.region rast=elevation@PERMANENT

Stations

Create a stations point vector map:

echo "x|y|name|subbsize
640579|215607|outlet|0.1
640388|216617|headwater|0.05" > stations.dat
v.in.ascii input=stations.dat out=stations x=1 y=2 columns='x int, y int, name varchar(20), subbsize double' skip=1

Subbasins

Make simple subbasins (default output arguments):

m.swim.subbasins elevation=elevation@PERMANENT stations=stations upthresh=0.1 subbasins=subbasins

In addition to the subbasins vector and raster map, this also produces catchment raster and vector maps, accumulation, drainage, streams, slopesteepness and slopelength rasters (as needed by the subsequent m.swim.* modules) by default.
Subbasins with varying subbasin thresholds and defined lower threshold:

m.swim.subbasins elevation=elevation@PERMANENT stations=stations upthreshcolumn=subbsize lothresh=0.001 subbasins=subbasins

AUTHORS

Michel Wortmann, Potsdam Institute for Climate Impact Research (wortmann@pik-potsdam.de)

Last updated (docs/code): Mon Dec 2 15:41:04 2019 +0100 / Wed Jan 19 23:04:38 2022 +0000