SSN objectR/ssn_get_stream_distmat.R
ssn_get_stream_distmat.RdExtracts the stream network distance matrices for the
observation or prediction data from an SSN object.
ssn_get_stream_distmat(x, name = "obs")An SSN object
Internal name of the dataset in the object
x. For observed values, this will always be "obs", the
default. To get a stream network distance matrix for a
prediction data set, the name of the dataset must be given, in
quotes.
A list of asymmetric downstream only
stream distance matrices, by network.
The internal name for observed data in objects of class
SSN is "obs" and it is the default. If another name
is specified, it must represent a prediction data set in the
SSN object. For SSN
objects, these names are obtained using the call names(x$preds).
Note that these are not traditional symmetric distance
matrices. First, distances in an SSN object represent stream
distance, or hydrologic distance, which is the distance between two
locations when movement is restricted to the branching stream
network. Another important difference is the distance matrices for
SSN objects contain the downstream only stream
distance between two locations, making them asymmetric. This
asymmetry provides a way to store two types of spatial
relationships based on stream distance:
Flow-connected: Water flows from an upstream site to a downstream site.
Flow-unconnected: Two sites reside on the same stream network, but do not share flow.
For example, if two sites are flow-connected the downstream distance from the upstream site to the downstream site is > 0, while the downstream distance between the downstream site and the upstream site = 0. For flow-unconnected sites, the downstream distance represents the distance from each site to the closest downstream junction and will be > 0 in both directions. Direction is preserved, with columns representing the FROM site and rows representing the TO site. Row and column names correspond to the unique point identifier "pid" for each site. From this matrix, it is also possible to get total stream distance (downstream + upstream) between any two sites on the same network (see examples for additional details).
Stream distances are only calculated within a network and so the
asymmetric matrices are also stored by network. For observation
data, a single square matrix of distances is returned for each
network, with the names based on the netID value (e.g. "dist.net1",
"dist.net2", etc.). However, two distance matrices ("a" and "b")
are required to store the downstream only distance between observed
and prediction sites. The label "a" represents the downstream
stream distance from prediction sites to observation
sites, and the label "b" represents the distance from
observation sites to predictions sites. Thus, the list of
prediction matrices are labeled "dist.net1.a" for the downstream
only distance from prediction sites in the columns, to observation
sites in the rows, for the first network. A prediction matrix
labeled "dist.net1.b" contains downstream distances from
observation sites in the columns to prediction sites in the
rows, for the first network. The downstream only distance matrices
for observations and predictions will be rectangular, unless the
number of observation and prediction locations are equal. If the
argument amongPreds = TRUE was used in the function
ssn_create_distmat, then the distance between prediction sites
themselves is also returned, using the same labelling convention as
for among observation sites. That is, the matrices for each network
will be labeled "dist.net1", "dist.net2", etc., for the first and
second network, etc.
Ver Hoef, J.M. and Peterson, E.E. (2010) A moving average approach to spatial statistical models of stream networks. The Journal of the American Statistical Association, 105(489), 22--24
## For this example only, copy MiddleFork04.ssn directory to R's
## temporary directory
copy_lsn_to_temp()
## Create an SSN object with prediction sites
mf04p <- ssn_import(paste0(tempdir(), "/MiddleFork04.ssn"),
predpts = "pred1km", overwrite = TRUE
)
## Create distance matrices for obs x obs, obs x preds, and preds x
## preds
if (FALSE) {
ssn_create_distmat(mf04p,
predpts = "pred1km", among_predpts = TRUE,
overwrite = TRUE
)
}
## Check names of prediction datasets
names(mf04p$preds)
#> [1] "pred1km"
## Get list of stream distance matrices for observations
dist_obs <- ssn_get_stream_distmat(mf04p)
## Display structure of list and names of the matrices
str(dist_obs)
#> List of 2
#> $ dist.net1: num [1:13, 1:13] 0 0 0 13385 12603 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:13] "1" "2" "3" "4" ...
#> .. ..$ : chr [1:13] "1" "2" "3" "4" ...
#> $ dist.net2: num [1:32, 1:32] 0 0 0 0 0 0 0 0 0 0 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:32] "14" "15" "16" "17" ...
#> .. ..$ : chr [1:32] "14" "15" "16" "17" ...
names(dist_obs)
#> [1] "dist.net1" "dist.net2"
## Look at first 5 rows and columns in asymmetric
## downstream only distance matrix for netID == 1
dist_obs$dist.net1[1:5, 1:5]
#> 1 2 3 4 5
#> 1 0.00 1962.99 2499.7602 0 0.0000
#> 2 0.00 0.00 536.7699 0 0.0000
#> 3 0.00 0.00 0.0000 0 0.0000
#> 4 13385.26 15348.25 15885.0187 0 782.3198
#> 5 12602.94 14565.93 15102.6989 0 0.0000
## Create symmetric total stream distance matrix between
## observations
strdist_2 <- dist_obs$dist.net2 + t(dist_obs$dist.net2)
strdist_2[5:10, 5:10]
#> 18 19 20 21 22 23
#> 18 0.000 1018.962 2105.652 2345.758 3738.746 2979.006
#> 19 1018.962 0.000 1086.690 1326.796 2719.784 3997.968
#> 20 2105.652 1086.690 0.000 240.106 1633.094 5084.658
#> 21 2345.758 1326.796 240.106 0.000 1392.988 5324.764
#> 22 3738.746 2719.784 1633.094 1392.988 0.000 6717.751
#> 23 2979.006 3997.968 5084.658 5324.764 6717.751 0.000
## Get maximum downstream only distance between
## observations on netID == 2
a.mat <- pmax(dist_obs$dist.net2, t(dist_obs$dist.net2))
a.mat[5:10, 5:10]
#> 18 19 20 21 22 23
#> 18 0.000 1018.962 2105.652 2345.758 3738.746 2605.143
#> 19 1018.962 0.000 1086.690 1326.796 2719.784 3624.106
#> 20 2105.652 1086.690 0.000 240.106 1633.094 4710.795
#> 21 2345.758 1326.796 240.106 0.000 1392.988 4950.901
#> 22 3738.746 2719.784 1633.094 1392.988 0.000 6343.889
#> 23 2605.143 3624.106 4710.795 4950.901 6343.889 0.000
## Get minimum downstream only distance between observations. If
## minimum distance == 0, sites are flow-connected
b.mat <- pmin(dist_obs$dist.net2, t(dist_obs$dist.net2))
b.mat[5:10, 5:10]
#> 18 19 20 21 22 23
#> 18 0.0000 0.0000 0.0000 0.0000 0.0000 373.8622
#> 19 0.0000 0.0000 0.0000 0.0000 0.0000 373.8622
#> 20 0.0000 0.0000 0.0000 0.0000 0.0000 373.8622
#> 21 0.0000 0.0000 0.0000 0.0000 0.0000 373.8622
#> 22 0.0000 0.0000 0.0000 0.0000 0.0000 373.8622
#> 23 373.8622 373.8622 373.8622 373.8622 373.8622 0.0000
## Get distance matrices for pred1km
dist_pred1km <- ssn_get_stream_distmat(mf04p, name = "pred1km")
str(dist_pred1km)
#> List of 6
#> $ dist.net1 : num [1:57, 1:57] 0 1000 2000 0 0 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:57] "46" "47" "48" "49" ...
#> .. ..$ : chr [1:57] "46" "47" "48" "49" ...
#> $ dist.net1.a: num [1:13, 1:57] 2163 200 0 15548 14766 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:13] "1" "2" "3" "4" ...
#> .. ..$ : chr [1:57] "46" "47" "48" "49" ...
#> $ dist.net1.b: num [1:57, 1:13] 0 0 0 0 0 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:57] "46" "47" "48" "49" ...
#> .. ..$ : chr [1:13] "1" "2" "3" "4" ...
#> $ dist.net2 : num [1:118, 1:118] 0 0 0 0 0 0 0 0 0 0 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:118] "74" "75" "76" "77" ...
#> .. ..$ : chr [1:118] "74" "75" "76" "77" ...
#> $ dist.net2.a: num [1:32, 1:118] 0 0 0 0 0 0 0 0 0 0 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:32] "14" "15" "16" "17" ...
#> .. ..$ : chr [1:118] "74" "75" "76" "77" ...
#> $ dist.net2.b: num [1:118, 1:32] 2638 0 0 0 0 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:118] "74" "75" "76" "77" ...
#> .. ..$ : chr [1:32] "14" "15" "16" "17" ...
names(dist_pred1km)
#> [1] "dist.net1" "dist.net1.a" "dist.net1.b" "dist.net2" "dist.net2.a"
#> [6] "dist.net2.b"
## Look at first 5 rows and columns of downstream only distances
## FROM prediction sites TO observed sites on netID == 1
dist_pred1km$dist.net1.a[1:5, 1:5]
#> 46 47 48 49 50
#> 1 2163.0690 1163.069 163.069 5497.956 4497.956
#> 2 200.0786 0.000 0.000 3534.965 2534.965
#> 3 0.0000 0.000 0.000 2998.196 1998.196
#> 4 15548.3275 14548.328 13548.328 18883.214 17883.214
#> 5 14766.0077 13766.008 12766.008 18100.894 17100.894
## Look at downstream only stream distances among prediction
## sites in pred1km on netID == 1. This is useful for block
## prediction
dist_pred1km$dist.net1[1:5, 1:5]
#> 46 47 48 49 50
#> 46 0 0 0 3334.887 2334.887
#> 47 1000 0 0 4334.887 3334.887
#> 48 2000 1000 0 5334.887 4334.887
#> 49 0 0 0 0.000 0.000
#> 50 0 0 0 1000.000 0.000