Skip to content
R package for downscaling off-the-shelf runoff products to explicit river network.
R Fortran C
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
R
data
docs hydrostreamer 0.4.0 Apr 8, 2019
inst/extdata
man
src hydrostreamer 0.4.0 Apr 8, 2019
vignettes hydrostreamer 0.4.0 Apr 8, 2019
.Rbuildignore hydrostreamer 0.4.0 Apr 8, 2019
.gitignore 3.2 passing R CMD check Jan 9, 2019
DESCRIPTION
LICENSE GitHub readme.md Apr 7, 2018
NAMESPACE
News.md Update news.md, delete extra stuff Apr 8, 2019
README.md
dev_script.R
hydrostreamer.Rproj
sticker.png

README.md

hydrostreamer 0.4.0

DOI

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:

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:

  1. Convert the runoff timeseries to a HSgrid object,
  2. Compute weights for each river segment,
  3. Downscale runoff, and
  4. 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

  1. 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)
  2. 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
  3. 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)

Copyright (c) 2018 Marko K. Kallio

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.

You can’t perform that action at this time.