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.

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.

  • 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.12.2 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.13.0

  • 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

  • Allowing vectors of pch and col in riverpoints()

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

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

'riverdist' 0.12.0 (July 5, 2016)

  • 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.

  • 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.0 by Matt Tyers, 6 months ago


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

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

Authors: Matt Tyers [aut, cre]

Documentation:   PDF Manual  

GPL-2 license

Imports rgdal, sp, methods

Suggests knitr, rmarkdown, testthat

See at CRAN