hydrostreamer 0.4.0

hydrostreamer is an R package to downscale distributed runoff data products by spatial relationship between the areal unit in runoff data, and an explicitly represented river network.

hydrostreamer has featured in a number of conference presentations:

EGU 2018: Kallio et al, Spatial allocation of low resolution runoff model outputs to high resolution stream network
AGU 2018: Kallio et al, Generating improved estimates of streamflow using model averaging of downscaled runoff products under uncertainty
AGU 2018: Virkki et al, The value of open-source river discharge estimation in the water governance context of the 3S river basin in Southeast Asia
EGU 2019: Nauditt et al, Evaluating drought risk in data scarce tropical catchments
A research paper is currently under preparation.

In practise the downscaling occurs by dividing the value of runoff to all those river segments intersecting the areal unit (of runoff) using a numerical attribute for weighting. These attributes can be, for instance, length of the intersecting river segment, Strahler number, or area of the segment-specific catchment.

Downscaling in hydrostreamer can be done either using river segment lines, or by their catchment areas. This is an example in case of a gridded runoff product, but the areal units can be arbitrarily shaped

Installing

hydrostreamer is not yet on CRAN, so to install, use devtools::install_github() in RStudio. You should have R version higher than 3.4.0 for the package to work properly.

Note that while hydrostreamer is already a useful package, it is under development and may change without prior notice.

# devtools::install_github("mkkallio/hydrostreamer")

Basic usage

hydrostreamer workflow occurs in four steps:

Convert the runoff timeseries to a HSgrid object,
Compute weights for each river segment,
Downscale runoff, and
Apply river routing.

Minimum data requirement is a distributed runoff timeseries, either as polygons or in a raster format, and a river network. Alternatively, river network can be derived from a Digital Elevation Model (DEM).

First, load example data to R:

library(raster)

## Loading required package: sp

library(hydrostreamer)

## Loading required package: sf

## Linking to GEOS 3.6.1, GDAL 2.2.3, PROJ 4.9.3

library(lubridate)

## 
## Attaching package: 'lubridate'

## The following object is masked from 'package:base':
## 
##     date

data(example_rivers)
data(example_basins)
runoff <- brick(system.file("extdata", "runoff.tif", package = "hydrostreamer"))

1. Convert raster timeseries to a HSgrid

The first step in hydrostreamer is converting runoff into a HSgrid object. For a runoff input in a raster format, use raster_to_HSgrid() function. For input we need the raster, starting date of the timeseries and the granularity of input timesteps.

HSgrid <- raster_to_HSgrid(runoff, 
                         date = ymd("1980-01-01"), 
                         timestep = "month", 
                         aoi = st_union(basins),
                         names = "LORA")

2. Compute weights for each river segment

Next, we weight the river segments within each segment, so that the weights of segments within a polygon add to 1. In hydrostreamer this can be done by

Catchment area of each river segment by
1. user provided catchments
2. drainage direction delineated basins (for river networks derived from them)
3. Medial axis delineated basins (Voronoi Diagram created from the river network)
River segment properties
1. divide runoff equally to all intersecting segments
2. use stream order to weight the segments
3. use segment length for weighting
4. user provided attributes
More complex downscaling

Here, we use river segment specific catchment areas, which are provided in the example data. For information on the other options, see help(compute_HSweights).

weights <- compute_HSweights(HSgrid, 
                             river, 
                             "area",
                             basins = basins,
                             aoi = st_union(basins), 
                             riverID = "SEGMENT_ID")

3. Downscale runoff

With the weights computed, we can assign specific runoff to each river segment. This means that we disaggregate the low resolution runoff into its components - the river segments.

downscaled_runoff <- downscale_runoff(weights)

4. Apply river routing

The last step is to accumulate flow downstream. The previous step only assigned the grid cell value to the streams. However, often we want to know the discharge at certain points of the river to create a timeseries.

hydrostreamer currently (v. 0.2.0) only implements the simplest possible river routing, instantaneous flow, by adding all runoff to every segment downstream, at each timestep. This is an overly simple scheme, and there are plans to add more sophisticated river routing algorithms to the package.

streamflow <- accumulate_runoff(downscaled_runoff)

These functions are pipable

The function usage has been developed so that they are all pipable.

streamflow <- raster_to_HSgrid(runoff, 
                         date=ymd("1980-01-01"), 
                         timestep="month", 
                         aoi=st_union(basins),
                         names="LORA") %>%
    compute_HSweights(river,
                      "area",
                      aoi=st_union(basins),
                      basins = basins,
                      riverID = "SEGMENT_ID") %>%
    downscale_runoff() %>%
    accumulate_runoff()

Exporting

hydrostreamer includes also a useful function to export the results to a GeoPackage, which can be viewed in any GIS software (such as ArcGIS, QGIS). We can also write the discharge (or runoff) as a table.

HSwrite(streamflow, "downscaled_streamflow.gpkg")

## Writing layer `downscaled_streamflow' to data source `downscaled_streamflow.gpkg' using driver `GPKG'
## features:       41
## fields:         6
## geometry type:  Line String

HSwrite(streamflow, "downscaled_streamflow.csv", what = "discharge")

## Loading required namespace: readr

License

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

sankarbsubramani/hydrostreamer