r.hydro.hbv.basins - GRASS manual

NAME

r.hydro.hbv.basins - Delineates lumped sub-basins from a DEM and outlet points, and writes area/forest-field-fraction/station-elevation-difference physiography (plus, optionally, HBV parameter bounds) directly into the basins vector's attribute table for r.hydro.hbv.

KEYWORDS

raster, hydrology, HBV, watershed

SYNOPSIS

r.hydro.hbv.basins

r.hydro.hbv.basins --help

r.hydro.hbv.basins elevation=name outlets=name [id_column=name] threshold=integer snap_radius=integer basins=name basins_vector=name [landcover=name] [forest_cats=integer[,integer,...]] [ffo=float] [ffi=float] [precip_station_elevation=float] [temp_station_elevation=float] [et_station_elevation=float] [parameters_template=name] hru_bands=integer [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

--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:

elevation=name [required]: Input DEM; the current region (g.region) must already match it
outlets=name [required]: Name of input vector map; Vector points map, one point per basin outlet/station
id_column=name: Attribute column in outlets holding the basin identifier (copied into basins_vector's basin_id column); Default: id
threshold=integer [required]: Minimum flow accumulation (cells) for r.watershed basin delineation; Default: 1000
snap_radius=integer [required]: Maximum distance (cells) to snap outlet points onto the derived stream network; Default: 3
basins=name [required]: Name for output delineated basins raster map
basins_vector=name [required]: Name for output delineated basins vector map; its attribute table is r.hydro.hbv's parameters input
landcover=name: Land-cover raster used to derive forest/field fraction per basin; omit to use uniform ffo/ffi instead
forest_cats=integer[,integer,...]: Land-cover category values considered "forest" (required if landcover is given)
ffo=float: Uniform forest fraction applied to every basin when landcover is not given; Default: 0.0
ffi=float: Uniform field fraction applied to every basin when landcover is not given; Default: 1.0
precip_station_elevation=float: Elevation of the precipitation station/grid reference point (elevation map units); omit to skip the correction term (dep=0)
temp_station_elevation=float: Elevation of the temperature station/grid reference point; omit to skip the correction term (det=0)
et_station_elevation=float: Elevation of the evapotranspiration station/grid reference point; omit to skip the correction term (dee=0)
parameters_template=name: CSV of HBV parameter sampling bounds (16 rows: fc,beta,lp,alpha,kf,ks,perc,cflux low/high), either 1 column (broadcast to every basin) or one column per delineated basin; written into basins_vector's fc_lo/fc_hi/... columns
hru_bands=integer [required]: Number of elevation-band HRUs per basin (1 = today's lumped, one-unit-per-basin behavior); Default: 1

DESCRIPTION
OUTPUTS
EXAMPLE
SEE ALSO
AUTHOR

DESCRIPTION

r.hydro.hbv.basins replaces the pysheds-based external Python preprocessing used to prepare lumped-basin inputs for r.hydro.hbv (originally written for the Plumergat DICRIM flood-risk study) with GRASS-native raster analysis:

Sub-basins are delineated from a DEM and a set of outlet points using r.watershed (drainage direction and stream network), r.stream.snap (snapping outlets onto the modelled stream network) and r.stream.basins (tracing each outlet's contributing area). All outlets are delineated in one pass; the resulting raster's categories are the outlet points' own vector categories.
With hru_bands > 1 (default 1 = no splitting), each basin is further split into that many equal-interval elevation bands (from its own min/max elevation), each band becoming its own HRU with category basin_category * 100 + band_index.
The basins (or HRU) raster is vectorized with r.to.vect -v (vector category = raster category, not discovery order -- important, since the zonal stats below are keyed by raster category).
Per-basin (or per-HRU) physiography is derived by zonal statistics: area via r.stats -a, mean elevation via r.univar zones=, forest/field fraction via a basins x land-cover cross-tabulation (r.stats with two inputs), and elevation-difference correction terms (dep/det/dee, in units of 100 m) as (station_elevation - mean_elevation) / 100 for each of the precipitation/temperature/evapotranspiration reference stations, when their elevations are supplied. These, plus (optionally) HBV parameter sampling bounds from parameters_template, are written directly into basins_vector's attribute table via v.db.addcolumn/db.execute -- no CSV files are produced.

The current region (set beforehand with g.region) must already match the elevation raster's extent and resolution -- this module does not change the region itself.

OUTPUTS

basins_vector's attribute table gains, per row (one row per basin, or per HRU when hru_bands > 1):

basin_id: from the outlets attribute column id_column -- the parent basin's identifier, repeated across an HRU group.
band_index (only when hru_bands > 1): 1-based elevation band number within its parent basin.
area_km2, ffo, ffi, dep, det, dee: the physiography r.hydro.hbv expects (rows 16-21 of its parameters input), computed within that basin/HRU only.
fc_lo/fc_hi/.../cflux_lo/cflux_hi (only when parameters_template is given): the 8 HBV parameters' sampling bounds (rows 0-15) -- these aren't derivable from a DEM, so parameters_template must be supplied externally, either as 1 column (broadcast to every basin, and to every HRU within a basin) or one column per delineated basin.

basins is the delineated basins (or HRU) raster, for inspection or as input to r.hydro.hbv.forcing's zonal climate reduction.

Any outlet that fails to produce a delineated basin (too close to another outlet, off the DEM, or below the accumulation threshold) is dropped with a warning, rather than aborting the whole run.

EXAMPLE

Lumped (one row per basin):

g.region raster=dem_1m
r.hydro.hbv.basins elevation=dem_1m outlets=shyreg_outlets id_column=ID \
  threshold=1000 landcover=landcover forest_cats=1,2,3 \
  precip_station_elevation=45 temp_station_elevation=45 \
  et_station_elevation=45 \
  parameters_template=hbv_param_bounds_16row.csv \
  basins=plumergat_basins basins_vector=plumergat_basins_v

r.hydro.hbv dataset=custom basins_vector=plumergat_basins_v \
  precipitation=precip.csv temperature=temp.csv \
  evapotranspiration=evap.csv eta_observed=etobs.csv \
  discharge_observed=dischargeobs.csv ... output=out/

Semi-distributed (3 elevation-band HRUs per basin):

r.hydro.hbv.basins elevation=dem_1m outlets=shyreg_outlets id_column=ID \
  threshold=1000 hru_bands=3 \
  parameters_template=hbv_param_bounds_16row.csv \
  basins=plumergat_basins basins_vector=plumergat_basins_v

AUTHOR

Yann Chemin

SOURCE CODE

Available at: r.hydro.hbv.basins source code (history)

Accessed: Monday Jul 27 12:29:26 2026