River Network Distance Computation and Applications

Reads river network shape files and computes network distances. Also included are a variety of computation and graphical tools designed for fisheries telemetry research, such as minimum home range, kernel density estimation, and clustering analysis using empirical k-functions with a bootstrap envelope. Tools are also provided for editing the river networks, meaning there is no reliance on external software.


River Network Distance Computation and Applications

The 'riverdist' package is intended as a free and readily-available resource for distance calculation along a river network. This package was written with fisheries research in mind, but could be applied to other fields. The 'riverdist' package builds upon the functionality of the 'sp' and 'rgdal' packages, which provide the utility of reading GIS shapefiles into the R environment. What 'riverdist' adds is the ability to treat a linear feature as a connected network, and to calculate travel routes and travel distances along that network.

Commonly-used functions

  • line2network() imports a river shapefile, and calculates topologies to create a connected river network.

  • cleanup() calls a sequence of editing functions on the resulting river network to facilitate performance. The editing functions are also available by themselves.

  • plot() when used with a river network object produces a simple map of the network, with segments labeled and differentiated by color or line type.

  • xy2segvert() converts a set of X-Y coordinates to river network coordinates by "snapping" each point to the nearest river vertex. pointshp2segvert() does the same, with the input being a point shapefile.

  • riverdistance(), riverdirection(), and upstream() return the network distance, the travel direction (upstream or downstream), and the directional (upstream) distance between two river locations, respectively. Options are included for different handling of locations that are flow-connected or flow-separate, as well as net directional distance when locations are flow-separate.

Several automated analyses are built in. In most cases, there is a direction or directional distance equivalent.

  • homerange() returns the minimum observed home range for each individual in a data set.
  • riverdistanceseq() and riverdistanceseqbysurvey() return different forms of matrices of pairwise network distances between observations of each individual in a dataset.
  • riverdistancemat() returns a matrix of network distances between all observations in a dataset.
  • riverdistancetofrom() returns a matrix of network distances between two datasets.
  • mouthdistbysurvey() returns a matrix of distances between each observation and the mouth of the river network, with rows corresponding to unique individual, and columns corresponding to unique survey.

Summaries and plots are also available at the dataset level, in addition to individuals, which is likely to be much more useful to analysis.

  • makeriverdensity() calculates a kernel density object which can be plotted with plot() to create a kernel density map. Depending on the usage of makeriverdensity(), this may be a sequence of maps.
  • kfunc() provides plotting of empirical k-functions for each survey event, giving evidence of clustering or dispersal behavior.
  • plotseq() produces a plot of a distance sequence such as that returned from mouthdistbysurvey() providing plots of overall distance or upriver position for each survey event.
  • matbysurveylist() produces a list of matrices of distances or upstream distances between all survey events, for each individual. This can be plotted using plotmatbysurveylist(), creating a summary plot for all individuals.


Version 0.15.0 of the 'riverdist' package is available on CRAN.

The development version is currently available on Github, and can be installed in R with the following code:




A major dependency of the 'riverdist' package is the 'rgdal' package, which allows importing shapefiles. For installation on a non-windows machine, please refer to the SystemRequirements given at https://cran.r-project.org/web/packages/rgdal/index.html


'riverdist' 0.15.0 (Jul 18, 2017)

Added capabilities

  • cleanup_verts() added, for editing of the vertices of individual segments

  • routelist() now returns all complete routes (and faster)

  • splitsegments() can now split a subset of segments at specified locations

  • connectsegs() can now connect vectors of segments

  • cleanup() improved

  • Better algorithm used for checkbraidedTF() - MUCH faster, and no longer hangs in a complex test case

  • detectroute(..., algorithm="Dijkstra") speeded up substantially

  • topologydots() speeded up

Bug fixes

  • Better algorithm used for checkbraidedTF() - MUCH faster, and no longer hangs in a complex test case

  • plot.rivernetwork() no longer errors when only one segment is visible in plotting window

'riverdist' 0.14.0 (Mar 31, 2017) - development version

Added capabilities

  • homerange() now creates homerange-class objects

  • Added plot.homerange(), homerangeoverlap() and plothomerangeoverlap(), which all accept homerange-class objects

  • Optimization in homerange(): speeded up by a factor of 10ish, depending on the dataset

  • Line color in an empty plot with plot.rivernetwork() now settable with argument linecol=

Bug fixes

  • mouthdist() accepts vectors of segment and vertex coordinates

  • segmentnum= and empty= in plot.rivernetwork() and others re-implemented

'riverdist' 0.13.1 (Feb 3, 2017)

Added capabilities

  • Including a scale bar in plot.riverdensity() with scalebar=T

Bug fixes

  • Producing plots in plot.riverdensity() in the correct order, if survey is a factor variable with levels in a different order than alphabetic

'riverdist' 0.13.0 (Dec 21, 2016)

Added capabilities

  • Making an empty river plot (using empty=TRUE)

  • Jittering riverpoints() using jitter argument

  • Optimization in riverpoints() and xy2segvert(): both were speeded up by a factor of 10

  • Optimization in plot.rivernetwork(): speeded up by a factor of 2

Bug fixes

  • Allowing vectors of pch and col in riverpoints()

'riverdist' 0.12.1 and 0.12.2 (Aug 11, 2016)

Bug fixes

  • A bug in the braiding check algorithm used in cleanup() was identified and fixed.

'riverdist' 0.12.0 (July 5, 2016)

Major changes

  • Distance calculation is much, much faster since the last CRAN release (0.11.0). Both the Dijkstra and segroutes algorithm run in about one hundredth the time that they previously did.

  • Additional components were added to the rivernetwork class, to aid in distance calculation speed. $cumuldist is a list of vectors of cumulative distances associated with each line segment, and $distlookup is a list of lookup tables. Distance calculation is now done using these components, which will need to be calculated for any saved river network objects.

Bug fixes

  • Bugs in the dissolve() and homerange() functions and segroutes algorithm were identified and fixed.

  • New connection types were added, to handle special cases in braided networks.

  • Error handling in line2network() was improved, and more complex networks can now be read in a manageable amount of time.

'riverdist' 0.11.0 (initial release June 1, 2016)

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


0.15.5 by Matt Tyers, 21 days ago


Report a bug at https://github.com/mbtyers/riverdist/issues

Browse source code at https://github.com/cran/riverdist

Authors: Matt Tyers [aut, cre]

Documentation:   PDF Manual  

Task views: Handling and Analyzing Spatio-Temporal Data

GPL-2 license

Imports rgdal, sp, methods

Suggests knitr, rmarkdown, testthat

See at CRAN