m.swim.routing.py - GRASS GIS manual

NAME

m.swim.routing.py - Soil and Water Integrated Model (SWIM) preprocessor: routing

KEYWORDS

SYNOPSIS

m.swim.routing.py

m.swim.routing.py --help

m.swim.routing.py [-rkv] subbasins=name accumulation=name drainage=name [routingnet=name] [mainstreams=name] [outlets=name] [inlets=name] [figpath=path/myproj.fig] [fromto=from,to[,from,to,...]] [minmainstreams=float] [rivercourse=subbasinID[,subbasinID,...]] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-r: Only remake routing network, mainstreams and .fig file (eg. after manual editing, outlets and inlets needed!)
-k: Keep intermediate files (those named *__*)
-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:

subbasins=name [required]: Subbasin vector, nextID and inletID will be uploaded to table
accumulation=name [required]: CELL/integer accumulation raster, e.g. m.swim.subbasins; Default: accumulation
drainage=name [required]: CELL/integer drainage raster, e.g. m.swim.subbasins; Default: drainage
routingnet=name: Vector of routing network to be created; Default: routingnetwork
mainstreams=name: Main streams vector and raster to be created (routingnet needed); Default: mainstreams
outlets=name: Outlets point vector; Default: subbasinoutlets
inlets=name: Inlets point vector; Default: subbasininlets
figpath=path/myproj.fig: path to the .fig file
fromto=from,to[,from,to,...]: Force routing manually (pairs of subbasinID,nextID, is slow)
minmainstreams=float: Minimal drainage area headwater mainstreams, km2.; All headwater subbasins below this area (or if not given) have a single cell mainstream.
rivercourse=subbasinID[,subbasinID,...]: SubbasinID(s) to calculate river course for (to column: 'course_$id'); Uploads cumulative mainChannelLength for all subbasins in column: course_subbasinID

DESCRIPTION

The m.swim.routing module computes the routing structure for a given subbasin vector and accumulation raster map that are produced by m.swim.subbasins or r.watershed. A column named 'nextID' denoting the next downstream subbasin IDs is uploaded to the subbasin table which is then used to produce the SWIM routing (.fig) file. In addition, the module produces a routing network vector map, a mainstream vector and raster map, subbasin outlet and inlet point vector maps (all map have default output names or can be set) and it uploads an additional column to the subbasin table named 'inletID' mapping the subbasin to an appropriate inlet. The additional output is mainly useful for visualising the routing structure, while the mainstream raster map is needed for the subsequent m.swim.substats module.

Verifying the routing structure

Although the module can produce both the 'nextID' column and the SWIM routing file in one execution, the recommended work flow is to first produce the routing structure (from-to subbasin IDs) and the additional maps, then (visually) examine the results using the created routingnetwork and possibly make manual adjustments, and only then write the SWIM routing file with the -r flag set (see examples). If the subbasin map was produced with the same accumulation map and in the same resolution/region, then the routing structure is expected to be exact and reflecting the river network as shown in the mainstreams map. The routing network vector visualises the routing and either just shows the connections between the outlets and inlets (default) or the lines from centroids to the outlet and inlet using the -c flag. Although the routing can be manually changed by either changing the subbasin IDs in the nextID column of the subbasin vector or by using the fromto argument, it is recommended to make sure the same accumulation map was used to produce the subbasins or to 'burn' a more accurate river network into the DEM and then remake the accumulation map using r.watershed (!with the -s flag!).

NOTES

It is highly recommended to use the same accumulation map as was used to produce the subbasin map (in the same resolution and grass region)!!! If this condition is not met, inexact routing and multiple outlet subbasins are highly likely.
If you have not produced the accumulation raster with m.swim.subbasin, make sure it has the data type CELL and has no minus values in the catchment of interest. The best way to ensure thatis to run:

r.mapcalc exp="accumulation_correct=if(accumulation_incorrect > 0,int(accumulation_incorrect), null())"

If you are using predefined subbasins that are split over multiple parts (they really should't, but assuming you have a valid reason for it), the routingnet can not be created and the argument must be set to none (routingnet=''). This does not affect the .fig file. 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 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.

Routing

Calculate the routing structure, routing network and mainstreams (the output defaults are: mainstreams=mainstreams, routingnet=routingnetwork, outlets=subbasinoutlets, inlets=subbasininlets; which can also be set explicitly):

m.swim.routing subbasins=subbasins accumulation=accumulation

Or set the -c flag to include the centroids in the routing network:

m.swim.routing -c subbasins=subbasins accumulation=accumulation

Check routing structure and write SWIM routing file (the --o overwrite is necessary as the mainstreams are recreated):

m.swim.routing -r subbasins=subbasins figpath=mypro.fig --o

Both these steps can also be executed at once (but may result in an error if the there are too many outlets):

m.swim.routing subbasins=subbasins accumulation=accumulation figpath=mypro.fig

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