Upstream Distance Matrix between Two Datasets

Returns a matrix of upstream distances between each river location in two datasets, with one expressed as rows and the other expressed as columns.

upstreamtofrom(seg1, vert1, seg2, vert2, rivers, logical1 = NULL,
  logical2 = NULL, ID1 = NULL, ID2 = NULL, net = FALSE,
  flowconnected = FALSE, stopiferror = TRUE, algorithm = NULL)

Arguments

seg1	First vector of river locations (segment component). These are expressed as rows in the output matrix.
vert1	First vector of river locations (vertex component). These are expressed as rows in the output matrix.
seg2	Second vector of river locations (segment component). These are expressed as columns in the output matrix.
vert2	Second vector of river locations (vertex component). These are expressed as columns in the output matrix.
rivers	The river network object to use.
logical1	A boolean vector that can be used for subsetting. If used, upstreamtofrom will only return upstream distances in which a specified condition is met for the first dataset.
logical2	A boolean vector that can be used for subsetting. If used, upstreamtofrom will only return upstream distances in which a specified condition is met for the second dataset.
ID1	a vector of observation IDs for the first dataset that will be used as row names in the output matrix.
ID2	a vector of observation IDs for the second dataset that will be used as column names in the output matrix.
net	Whether to calculate net upstream distance (TRUE) or signed total distance (FALSE). See upstream.
flowconnected	If TRUE, only returns distance if the input segments are flow-connected. Defaults to 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, the function will return NA in the appropriate entry. 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

A matrix of upstream distances (numeric) with rows and columns labeled by corresponding values of ID. See upstream for additional information.

Note

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

See also

upstream

Examples

data(Gulk)

streamlocs.seg <- c(1,8,11)
streamlocs.vert <- c(50,70,90)
streamlocs.ID <- c("A","B","C")

fish.seg <- c(1,4,9,12,14)
fish.vert <- c(10,11,12,13,14)
fish.ID <- c("fish1","fish2","fish3","fish4","fish5")

Gulk <- setmouth(seg=1, vert=1, rivers=Gulk)

upstreamtofrom(seg1=streamlocs.seg, vert1=streamlocs.vert,
  seg2=fish.seg, vert2=fish.vert, rivers=Gulk,
  ID1=streamlocs.ID, ID2=fish.ID)
#>         fish1     fish2       fish3       fish4     fish5
#> A   -4105.139  72198.64  124793.107  128391.882 154556.11
#> B -146707.264 -71633.09 -124227.552 -127826.327 153990.55
#> C -137953.569 -61649.79   -9711.364   -6831.302  20707.68

logi1 <- streamlocs.ID=="B" | streamlocs.ID=="C"
logi2 <- fish.ID!="fish3"

upstreamtofrom(seg1=streamlocs.seg, vert1=streamlocs.vert,
  seg2=fish.seg, vert2=fish.vert, rivers=Gulk, logical1=logi1,
  logical2=logi2, ID1=streamlocs.ID, ID2=fish.ID)
#>       fish1     fish2       fish4     fish5
#> B -146707.3 -71633.09 -127826.327 153990.55
#> C -137953.6 -61649.79   -6831.302  20707.68