fdup 0.1.1

Flow direction upscaling toolkit (DMM, NSA, COTAT)

fdup

fdup is a Python toolkit containing algorithms for upscaling D8 flow direction grids.

Currently implemented algorithms

• DMM (Double Maximum Method) by Olivera et al., 2002
• NSA (Network Scaling Algorithm) by Fekete et al., 2001
• COTAT (Cell Outlet Tracing with an Area Threshold) by Reed, 2003

Installation

From PyPI:

pip install fdup

From the repository root:

git clone https://github.com/sasjabs/fdup
cd fdup
pip install .

Requirements:

• Python >=3.10
• numpy >= 1.21.3
• numba >= 0.55.0
• rasterio >= 1.3.0

Python API usage

# Import call can take 10-15s since all @njit functions are compiled at import time
from fdup.upscalers import DMM, NSA, COTAT

# DMM
dmm = DMM()
dmm.load_flowacc("flowacc.tif")
dmm.upscale(k=20)
dmm.save("out_dmm.tif")

# NSA
nsa = NSA()
nsa.load_flowacc("flowacc.tif")
nsa.upscale(k=20)
nsa.save("out_nsa.tif")

# COTAT
cotat = COTAT()
cotat.load_flowdir("flowdir.tif")
cotat.load_flowacc("flowacc.tif")
cotat.upscale(k=20, area_threshold=10)
cotat.save("out_cotat.tif")

CLI

Besides Python API, fdup features a command-line interface:

fdup --help

DMM

fdup dmm --flowacc flowacc.tif -o out_dmm.tif -k 20

NSA

fdup nsa --flowacc flowacc.tif -o out_nsa.tif -k 20

COTAT

fdup cotat --flowdir flowdir.tif --flowacc flowacc.tif -o out_cotat.tif -k 20 --area-threshold 10

Note: fdup command is only accessible if Python environment with fdup package installed is activated

I/O

• --flowdir: input fine-resolution D8 flow direction raster file (for COTAT only).
• --flowacc: input fine-resolution flow accumulation raster file derived from flow direction raster.
• -o --output: path to output upscaled flow direction file.

Parameters

• -k: positive integer scaling factor for resulting grid. Output grid cells will be k times larger than input ones. Note: for DMM, k should be an even number.

• --area-threshold: drainage area (flow accumulation) increase threshold (for COTAT only). Defines when to stop tracing original fine-resolution flow directions: with larger values of threshold the algorithm tends to more often prefer diagonal flow directions (SE, SW, NW, NE) over orthogonal ones (E, S, W, N).

Input data conventions

The tool works with ESRI-style D8 flow direction encoding for input as well as output flow directions.

For input flow accumulation, the supported data types are uint32, float32, float64/double