r.flowaccumulation - GRASS GIS manual

Note: This document is for an older version of GRASS GIS that will be discontinued soon. You should upgrade, and read the current manual page.

NAME

r.flowaccumulation - Calculates flow accumulation from a flow direction raster map using the Memory-Efficient Flow Accumulation (MEFA) parallel algorithm by Cho (2023).

KEYWORDS

raster, hydrology, accumulation

SYNOPSIS

r.flowaccumulation

r.flowaccumulation --help

r.flowaccumulation [-omzZn] input=name format=string [weight=name] output=name type=string [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-o: Check overflow and exit if it occurs
-m: Use less memory
-z: Initialize to zero and nullify it later
-Z: Initialize to and leave zero instead of nullifying it
-n: Treat null weight as zero
--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:

input=name [required]: Name of input direction raster map
format=string [required]: Format of input direction raster map; Options: auto, degree, 45degree, power2; Default: auto; auto: auto-detect direction format; degree: degrees CCW from East; 45degree: degrees CCW from East divided by 45 (e.g. r.watershed); power2: powers of 2 CW from East (e.g., r.terraflow, ArcGIS)
weight=name: Name of input weight raster map
output=name [required]: Name for output flow accumulation raster map
type=string [required]: Type of raster map to be created; Storage type for resultant raster map; Options: CELL, FCELL, DCELL; Default: CELL; CELL: Integer; FCELL: Single precision floating point; DCELL: Double precision floating point

DESCRIPTION
NOTES
EXAMPLES
SEE ALSO
REFERENCES
AUTHOR

DESCRIPTION

r.flowaccumulation calculates flow accumulation from a flow direction raster map using the Memory-Efficient Flow Accumulation (MEFA) parallel algorithm by Cho (2023).

Unlike r.watershed, but just like r.accumulate, r.flowaccumulation does not require elevation data to calculate flow accumulation. Instead, this module only uses a flow direction raster map to trace and accumulate the amount of flow draining through and including each cell.

The module recognizes three different formats of flow directions:

Because it does not use elevation data (e.g., 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.

By default, the module allows cell values to overflow the maximum value of the specified output type to avoid excessive checks. With the -o flag, it prints a fatal error and exits if an overflow occurs.

The module uses extra memory to store an intermediate output matrix and it is generally faster than with the -m flag because intermediate results need not be calculated repeatedly. On heavy swapping, however, computation can be faster with the -m flag because of reduced memory allocation. With this flag, intermediate results are calculated as needed and never stored in memory.

Cells in the output matrix are initialized to null and need not be nullified after computation. With the -z flag, they are initialized to zero and those outside flow accumulation are nullified later. With this flag, it can be faster on heavy swapping because of less write operations for nullifying remaining zero cells outside flow accumulation, compared to null-initialization of the entire region without this flag. However, when there is not much swapping (e.g., data fit in the physical memory), the -z flag can be slower with additional zero-comparison operations. The -Z flag is similar to the -z flag, but zero cells are not nullified and are saved in the output map.

Weighted flow accumulation can be computed using the weight option. When this option is given, the data type for flow accumulation is automatically promoted to that of the weight map if the type option is not explicitly given, but one can choose to use a different data type if needed (e.g., FCELL for CELL weights, DCELL for FCELL weights). However, CELL cannot be used for FCELL or DCELL weighting to maintain floating-point precision. Similarly, FCELL cannot be used for DCELL weighting. The data type will be promoted in these cases, ignoring the user request. The -o, -z, and -Z flags cannot be used with the weight option.

EXAMPLES

These examples use the North Carolina sample dataset.

Calculate flow accumulation using r.watershed and r.flowaccumulation:

# set computational region
g.region -p raster=elevation

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

# calculate flow accumulation using r.flowaccumulation
r.flowaccumulation input=drain_directions output=flow_accum_new

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

# check difference between flow_accum and flow_accum_new
r.mapcalc expression="flow_accum_diff=if(flow_accum-flow_accum_new, flow_accum-flow_accum_new, null())"

There are slight differences between the two output maps. The yellow and purple cells show the difference raster map (flow_accum_diff). The red arrows and numbers represent drainage directions (drain_directions) and flow accumulation by r.watershed (flow_accum), respectively. Note that some cells close to headwater cells are assigned 1 even though they are located downstream of other cells.

For comparison, these numbers show the new flow accumulation by r.flowaccumulation (flow_accum_new). The same cells are properly accumulated from the headwater cells.

REFERENCES

Huidae Cho, July 2023. Memory-Efficient Flow Accumulation Using a Look-Around Approach and Its OpenMP Parallelization. Environmental Modelling & Software 167, 105771. doi:10.1016/j.envsoft.2023.105771.

AUTHOR

Huidae Cho, New Mexico State University

SOURCE CODE

Available at: r.flowaccumulation source code (history)

Latest change: Monday Jun 24 13:07:24 2024 in commit: 71dbc88614ccda943c73db28f3531855610f6146