Metadata-Version: 2.4
Name: fdup
Version: 0.1.1
Summary: Flow direction upscaling toolkit (DMM, NSA, COTAT)
Author-email: Mikhail Uzhegov <uzhegovmv@my.msu.ru>
License-Expression: GPL-3.0-or-later
Project-URL: Source, https://github.com/sasjabs/fdup
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.3
Requires-Dist: numba>=0.55.0
Requires-Dist: rasterio>=1.3.0
Dynamic: license-file

# 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](https://doi.org/10.1029/2001WR000726)
- **NSA** (Network Scaling Algorithm) by [Fekete et al., 2001](https://doi.org/10.1029/2001WR900024)
- **COTAT** (Cell Outlet Tracing with an Area Threshold) by [Reed, 2003](https://doi.org/10.1029/2003WR001989)

## Installation

From PyPI:

```bash
pip install fdup
```

From the repository root:

```bash
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

```python
# 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:

```bash
fdup --help
```

#### DMM

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

#### NSA

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

#### COTAT

```bash
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](https://pro.arcgis.com/en/pro-app/3.4/tool-reference/spatial-analyst/how-flow-direction-works.htm) 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`
