riverdistance {riverdist}

River Distance

Description

Calculates the total river network distance between two points on the river network, given in river locations (segment and vertex).

Usage

riverdistance(
  startseg = NULL,
  endseg = NULL,
  startvert,
  endvert,
  rivers,
  path = NULL,
  map = FALSE,
  add = FALSE,
  stopiferror = TRUE,
  algorithm = NULL
)

Arguments

startseg

Segment number of the start of the route

endseg

Segment number of the end of the route

startvert

Vertex number of the start of the route

endvert

Vertex number of the end of the route

rivers

The river network object to use

path

(optional) The vector-format route of segment numbers can also be supplied instead of the starting and ending segments.

map

Whether or not to draw a sanity-check map, showing the calculated route in entirety. Defaults to FALSE.

add

If map==TRUE, whether to add the route drawing to an existing plot (add=TRUE) or produce a new plot (add=FALSE).

stopiferror

Whether or not to exit with an error if a route cannot be found. If this is set to FALSE and a route cannot be found, riverdistance() will return NA. Defaults to TRUE. See detectroute.

algorithm

Which route detection algorithm to use ("Dijkstra", "sequential", or "segroutes"). If left as NULL (the default), the function will automatically make a selection. See detectroute for more details.

Value

Total route distance, in the units of the coordinate system used (this will likely be meters).

Note

If a distance lookup table ($distlookup) is present in the river network object, accepting NULL will bypass route detection and return distance automatically, the fastest algorithm of all. This is done automatically in buildsegroutes, but can be called directly using buildlookup.

Building routes from the river mouth to each river network segment and/or distance lookup tables will greatly reduce computation time (see buildsegroutes).

Author(s)

Matt Tyers

Examples

data(Gulk)
riverdistance(startseg=6, endseg=14, startvert=100, endvert=200, rivers=Gulk)
riverdistance(startvert=100, endvert=200, path=c(6,3,4,10,11,14), rivers=Gulk)
riverdistance(startseg=6, endseg=14, startvert=100, endvert=200, rivers=Gulk, map=TRUE)
      
# speed comparison: 

data(abstreams)

tstart <- Sys.time()
riverdistance(startseg=120, startvert=10, endseg=131, endvert=10, rivers=abstreams, 
              algorithm="sequential")
Sys.time()- tstart

tstart <- Sys.time()
riverdistance(startseg=120, startvert=10, endseg=131, endvert=10, rivers=abstreams, 
              algorithm="Dijkstra")
Sys.time()- tstart

tstart <- Sys.time()
riverdistance(startseg=120, startvert=10, endseg=131, endvert=10, rivers=abstreams)

# Note: it is not necessary to specify the algorithm here: the distance function
# will automatically select the fastest algorithm unless otherwise specified.
Sys.time()- tstart