OPTIONS

-z

Creates zero-value background instead of NULL. For some reason (like map algebra calculation) zero-valued background may be required. This flag produces zero-filled background instead of null (default).

-c

By default r.stream.basins uses streams category as basin category. In some cases - for example if stream map is product of map algebra and separete streams may not have unique values this option will create new category sequence for each basin (do not work in vector point mode)

-l

By default r.stream.basins create basins for all unique streams. This option delinate basins only for last streams ignoring upstreams (do not work in vector point mode).

stream

Stream network: name of input stream map on which ordering will be performed produced by r.watershed or r.stream.extract. Because streams network produced by r.watershed and r.stream.extract may slighty differ in detail it is required to use both stream and direction map produced by the same module. Stream background shall have NULL value or zero value. Background values of NULL are by default produced by r.watershed and r.stream.extract. If not 0 or NULL use r.mapcalc to set background values to null.

cats

Stream categories to delineate basins for: All categories which are not in stream map are ignored. It can be used with stream network created by r.watershed, r.stream.extract or r.stream.order. For r.stream.order use category of order for which basins must be created. For example to delineate only basins for order two use cats=2. If you need unique category for every basin use -c flag.

dir

Flow direction: name of input direction map produced by r.watershed or r.stream.extract. If r.stream.extract output map is used, it only has non-NULL values in places where streams occur. NULL (nodata) cells are ignored, zero and negative values are valid direction data if they vary from -8 to 8 (CCW from East in steps of 45 degrees). Direction map shall be of type CELL values. Region resolution and map resoultion must be the same. Also stream network map must have the same resolution. It is checked by default. If resolutions differ the module informs about it and stops. Region boundary and maps boundary may be differ but it may lead to unexpected results.

coors

East and north coordinates for basin outlet. It can delinate only one basin using that option. This option simply copies funcionality of r.water.outlet.

points

Vector file containing basins outlet as vector points. Only point's categories are used to prepare basins. Table attached to it is ignored. Every point shall have his own unique category. In that mode flags -l and -c are ignored

OUTPUTS

The module produces one raster map with basins acording user's rules

DESCRIPTION

Module r.stream.basins is prepared to delineate basins and subasins according user rules. Module is prepared to delineate unrestricted number of basins in one step. It can delineate basins with three methods:

• Using coordinates: his option simply copies funcionality of r.water.outlet.
• Using vector points: it allow to mannually point outlets with any method
• Using streams (most advanced) it allow on lots of modifications. See examples for more details.

The most recommended method require two maps: direction and streams. In spite of in stream map we can store information required to proper delineation, we can also enumarate stream categories for which basins are to be created (cats option). Module is prepared to work with output data of r.watershed, r.stream.extract, r.stream.order also with modification done by r.recalss and r.mapcalc. r.stream.basin can delineate basins according outlets marked by raster streams, and polygons, vector points and numerical coordinates. If outlets are marked by points or coordinates it delineate basins which cells contribute to that points, if outlets are marked by streams it delineate cells which contribute to the last (downstream) cell of the every stream. If outlets are marked by polygon it delineate cells contributing to most downstream cell of the polygon. If polygon covers more outlets than of one basins it will create collective basin for all outlets with common category.

NOTES

To receive good results outlets markers created by user shall overlapping with streams. On the other way basins could results with very small area. Input maps must be in CELL format (default output of r.watershed, r.stream.order and r.stream.extract)

Module can work only if direction map, stream map and region map has same settings. It is also required that stream map and direction map come from the same source. For lots of reason this limitation probably cannot be omitted. this means if stream map comes from r.stream.extract also direction map from r.stream.extract must be used. If stream network was generated with MFD method also MFD direction map must be used. Nowadays f direction map comes from r.stream.extract must be patched by direction map from r.watershed. (with r.patch).

EXAMPLES

To delineate all basins with categories of streams:

r.stream.basins dir=dirs stream=streams basins=bas_basins_elem

To determine major and minor basins in area, definied by outlets, ignoring subbasins use - l flag. That flag ignores all nodes and uses only real outlets (in most cases that on map border):

r.stream.basins -l dir=dirs stream=streams basins=bas_basins_last

r.stream.basins dir=dirs coors=639936.623832,216939.836449

To delinaeate one or more particular basins defined by given streams, stream map must be re-classed first, to leave only desired streams:

r.reclass input=streams cats=42 output=sel_streams_1 
r.reclass input=streams cats=42,252,188 output=sel_streams_1 

Or alternatevely:

echo '42=42
* = NULL' > tmp #for one output

echo '42 = 42
252 = 252
188 = 188
* = NULL' >tmp #for multiple outputs

r.reclass input=streams output=sel_streams_1 

Do delineate basins of particular order we must use the following procedure:

r.stream.basins -lc dir=dirs stream=strahler cats=2 basins=bas_basin_strahler_2

Or alternatevely:

echo '2 = 2
* = NULL' > tmp
r.reclass input=ord_strahler output=sel_strahler_2 < tmp
r.stream.basins -c dir=dirs 
stream=sel_strahler_2 basins=bas_basin_strahler_2

The usage of polygons as outlets markers is very useful when exact stream course cannot be cleary determined before running analysis, but the area of its occurrence can be determined (mostly in iterative simulations) Example uses r.circle but can be substituted by any polygon created for example with v.digit:

r.circle -b output=circle coordinate=639936.623832,216939.836449 max=200
r.stream.basins -c dir=dirs stream=circle basins=bas_simul

To determine areas of contribution to streams of particular order use as streams the result of ordering:

r.stream.basins dir=dirs stream=ord_strahler basins=bas_basin_strahler

Determination of areas of potential source of pollution. The example will be done for lake marked with FULL_HYDR 8056 in North Carolina sample dataset. The lake shall be extracted and converted to binary raster map.

v.extract -d input=lakes@PERMANENT output=lake8056 type=area layer=1 'where=FULL_HYDRO = 8056' new=-1 
v.to.rast input=lake8056 output=lake8056 use=val type=area layer=1 value=1
r.stream.basins dir=dirs stream=lake8056 basins=bas_basin_lake

See also tutorial: http://grass.OSGeo.org/wiki/R.stream.*

SEE ALSO

AUTHOR

Last changed: $Date$