r.accumulate-iterative.html

<h2>DESCRIPTION</h2>

<em>r.accumulate-iterative</em> calculates weighted flow accumulation, stream networks,
and the longest flow path using a flow direction map.

<h2>NOTES</h2>

<h3>Flow accumulation</h3>

Unlike <em>r.watershed</em>, <em>r.accumulate-iterative</em> does not require the
elevation data to calculate weighted flow accumulation.  Instead, this module
only uses a flow direction map to trace and accumulate the amount of flow
draining through and including each cell.

<p>With <b>-n</b> flag, the module will count the number of upstream cells plus
one and convert it to the negative if any upstream cells are likely to receive
flow from outside the computational region (flow direction edges). Negative
values identify cells with likely underestimates because not all upstream cells
were accounted for. Since raster map <b>weight</b> may contain negative flow
weights, <b>-n</b> flag is not compatible with <b>weight</b> option.  Running
the module twice with and without <b>-n</b> flag and <b>weight</b> option may
be useful in this specific case.

<p>The module recognizes two different formats of the flow direction map:
<div align="center">
<img src="r_accumulate_formats.png" alt="degree">
</div>

<p>Since the module does not use elevation data (i.e., slope), flow
accumulation is calculated by single flow direction (SFD) routing and may not
be comparable to the result from multiple flow direction (MFD) routing.

<p>The module requires flow accumulation for any output, so it will internally
accumulate flows every time it runs unless <b>input_accumulation</b> option is
provided to save computational time by not repeating this process.  In this
case, it is important to use flow accumulation consistent with the flow
direction map (e.g., <b>accumulation</b> output from this module).

<h3>Stream network delineation</h3>

With <b>stream</b> and <b>threshold</b> options, the module will delineate
stream networks with the minimum flow accumulation for stream generation. A
<b>weight</b> input map may be used with <b>threshold</b>. Delineated stream
lines are split at confluences.

<p>With <b>-c</b> flag, stream lines are delineated across confluences and may
overlap with other stream lines that share the same downstream outlet.

<p>With <b>input_subaccumulation</b> option, streams will be delineated as if
there are no incoming flows from upstream subwatersheds defined by
subaccumulation. This option is useful when you want to delineate streams
completely contained inside a subwatershed without considering the main channel
coming from outside the subwatershed (e.g., surface runoff within
subwatersheds).

<h3>Longest flow path calculation</h3>

With <b>longest_flow_path</b> option, the module will create a longest flow
path vector map for outlet points specified by <b>coordinates</b> and/or
<b>outlet</b> with <b>outlet_layer</b> option. By default, longest flow paths
will be created as if there were subwatersheds at the outlets by calculating
the subaccumulation map. Downstream longest flow paths will never traverse
through upstream outlets. With <b>-a</b> flag, longest flow paths will be
created in an accumulated manner resulting in an overlap between downstream and
upstream longest flow paths.

<p>You can assign unique IDs to longest flow paths using <b>id</b> (with
<b>coordinates</b>) and/or <b>outlet_id_column</b> (with <b>outlet</b>).
Assigning IDs also requires <b>id_column</b> option to specify the output
column name for the IDs in the <b>longest_flow_path</b> vector map. The
<b>outlet_id_column</b> specifies a column in the <b>outlet</b> vector map that
contains unique IDs to be copied over to the <b>id_column</b> column in the
output map. This column must be of integer type.

<h2>EXAMPLES</h2>

These examples use the North Carolina sample dataset.

<h3>Flow accumulation</h3>

<p>Calculate flow accumulation using <em>r.watershed</em> and
<em>r.accumulate-iterative</em>:
<div class="code"><pre>
# set computational region
g.region raster=elevation -p

# calculate positive flow accumulation and drainage directions using r.watershed
# for comparison, use -s (SFD)
r.watershed elevation=elevation accumulation=flow_accum drainage=drain_directions -s -a

# calculate flow accumulation using r.accumulate-iterative
r.accumulate-iterative direction=drain_directions accumulation=flow_accum_new

# copy color table
r.colors map=flow_accum_new raster=flow_accum

# check difference betwen flow_accum and flow_accum_new
r.mapcalc expression="accum_diff=if(flow_accum-flow_accum_new, flow_accum-flow_accum_new, null())"
</pre></div>

<img src="r_accumulate_nc_example.png">

<p>For some reaon, there are slight differences between the two output maps.

<p><img src="r_watershed_nc_example.png">

<p>The yellow and purple cells show the difference raster map
(<i>accum_diff</i>). The red arrows and numbers represent drainage directions
(<i>drain_directions</i>) and flow accumulation (<i>flow_accum</i> from
<em>r.watershed</em>), respectively. Note that some cells close to headwater
cells are assigned 1 even if they are located downstream of other cells.

<p><img src="r_accumulate_nc_comparison.png">

<p>For comparison, these numbers show the new flow accumulation
(<i>flow_accum_new</i> from <em>r.accumulate-iterative</em>). The same cells are properly
accumulated from the headwater cells.

<h3>Stream network delineation</h3>

<p>Calculate flow accumulation and delineate stream networks at once:
<div class="code"><pre>
# set computational region
g.region raster=elevation -p

# calculate positive flow accumulation and drainage directions using r.watershed
# for comparison, use -s (SFD)
r.watershed elevation=elevation accumulation=flow_accum drainage=drain_directions -s -a

# use r.accumulate-iterative to create flow_accum_new and streams_new at once
r.accumulate-iterative direction=drain_directions accumulation=flow_accum_new threshold=50000 \
    stream=streams_new

# or delineate stream networks only without creating an accumulation map
r.accumulate-iterative direction=drain_directions threshold=50000 stream=streams_new_only

# use r.stream.extract, elevation, and flow_accum to delineate stream networks
r.stream.extract elevation=elevation accumulation=flow_accum threshold=50000 \
    stream_vector=streams_extract direction=drain_directions_extract
</pre></div>

<img src="r_accumulate_nc_stream_example.png">

<p>In this example, <em>r.accumulate-iterative</em> and <em>r.stream.extract</em>
produced slightly different stream networks where the flow turns 90 degrees or
there are multiple downstream cells with the same elevation. The following
figure shows an example where the <i>streams</i> (red from
<em>r.stream.extract</em>) and <i>streams_new</i> (blue from
<em>r.accumulate-iterative</em>) vector maps present different stream paths. The numbers
show cell elevations (<i>elevation</i> map), and the yellow
(<i>drain_directions</i> map) and green (<i>drain_directions_2</i> map) arrows
represent flow directions generated by <em>r.watershed</em> with <b>-s</b> flag
and <em>r.stream.extract</em>, respectively. Note that the two flow direction
maps are different.

<p><img src="r_accumulate_nc_stream_comparison.png">

<h3>Longest flow path calculation</h3>

<p>Create the longest flow path for one outlet:
<div class="code"><pre>
# set computational region
g.region raster=elevation -p

# calculate drainage directions using r.watershed
r.watershed elevation=elevation drainage=drain_directions -s -a

# delineate watershed
r.water.outlet input=drain_directions output=basin coordinates=642455,222614

# calculate longest flow path
r.accumulate-iterative direction=drain_directions lfp=lfp coordinates=642455,222614
</pre></div>

<img src="r_accumulate_nc_lfp_example_single.png">

<p>Note that there can be more than one longest flow path when multiple paths
have the same flow length. In fact, the above example produces two lines with
the same length.

<p><img src="r_accumulate_nc_lfp_example_single_warning.png">

<p>There are different ways to calculate multiple longest flow paths in one run:
<div class="code"><pre>
# set computational region
g.region raster=elevation -p

# calculate drainage directions using r.watershed
r.watershed elevation=elevation drainage=drain_directions -s -a

# calculate longest flow paths at two outlets
r.accumulate-iterative direction=drain_directions lfp=lfp coordinates=642455,222614,642314,222734

# calculate longest flow paths at two outlets and assign IDs
r.accumulate-iterative direction=drain_directions lfp=lfp_w_id coordinates=642455,222614,642314,222734 \
    id=1,2 id_column=lfp_id

# calculate longest flow paths at all points in the outlets map
r.accumulate-iterative direction=drain_directions lfp=lfp_at_outlets outlet=outlets

# calculate longest flow paths at all points in the outlets map and assign IDs using a column \
# in this map
r.accumulate-iterative direction=drain_directions lfp=lfp_at_outlets_w_id outlet=outlets \
    id_column=lfp_id outlet_id_column=outlet_id

# calculate longest flow paths at given coordinates and all points in the outlets map and \
# assign IDs
r.accumulate-iterative direction=drain_directions lfp=lfp_multi_w_id \
    coordinates=642455,222614,642314,222734 \
    outlet=outlets id=1,2 id_column=lfp_id outlet_id_column=outlet_id
</pre></div>

<p><img src="r_accumulate_nc_lfp_example_multiple.png">

<p>Calculate the longest flow paths for subwatersheds:
<div class="code"><pre>
# set computational region
g.region raster=elevation -p

# calculate drainage directions using r.watershed
r.watershed elevation=elevation drainage=drain_directions -s -a

# get nsres
eval `r.info -g map=elevation`

# delineate streams using a threshold
r.accumulate-iterative direction=drain_directions threshold=50000 stream=streams

# populate stream lengths
v.db.addtable map=streams
v.to.db map=streams option=length columns=length

# create points along the streams starting from downstream
v.to.points -r input=streams output=stream_points dmax=$nsres

# find outlets (downstream-most less nsres points)
cats=`db.select -c sql="select stream_points_2.cat from stream_points_2 \
    inner join stream_points_1 on stream_points_1.cat = stream_points_2.lcat \
    where length-along &gt; 0.5*$nsres and length-along &lt; 1.5*$nsres"`
cats=`echo $cats | tr " " ,`
v.extract input=stream_points layer=2 cats=$cats output=stream_outlets

# create the longest flow paths for all outlets
r.accumulate-iterative direction=drain_directions lfp=lfp id_column=id \
    outlet=stream_outlets outlet_layer=2 outlet_id_column=lcat

# delineate subwatersheds
i=1
coors=`v.report -c map=stream_outlets layer=2 option=coor | awk -F'|' '{printf "%s,%s\n", $4, $5}'`
for coor in $coors; do
    r.water.outlet --o input=drain_directions output=tmp coordinates=$coor
    r.mapcalc expression="subwatershed_$i=if(isnull(tmp),0,1&lt;&lt;($i-1))"
    i=`expr $i + 1`
done

# patch subwatersheds
subwatersheds=`g.list type=rast pattern=subwatershed_* sep=+`
r.mapcalc express="subwatersheds=if($subwatersheds,$subwatersheds,null())"

# convert subwatersheds to vector
r.to.vect input=subwatersheds type=area output=subwatersheds

# delete subwatershed rasters
g.remove -f type=rast pattern=subwatershed*
</pre></div>

<img src="r_accumulate_nc_lfp_example_subwatersheds.png">

<h2>SEE ALSO</h2>

<em>
<a href="r.watershed.html">r.watershed</a>,
<a href="r.stream.extract.html">r.stream.extract</a>,
<a href="r.stream.distance.html">r.stream.distance</a>
</em>

<br><a href="https://idea.isnew.info/how-to-delineate-stream-networks-in-grass-gis.html">How to delineate stream networks in GRASS GIS</a>
<br><a href="https://idea.isnew.info/how-to-calculate-the-longest-flow-path-in-grass-gis.html">How to calculate the longest flow path in GRASS GIS</a>

<h2>AUTHOR</h2>

<a href="mailto:grass4u@gmail com">Huidae Cho</a>

<!--
<p>
<i>Last changed: $Date$</i>
-->