# Functions for overlaying networks on shapefiles The function `vector_segments` and `assign_pa_to_segments` were written to facilitate the generation of plots (including ggplots) that overlay user defined digraphs (based on arc designations) on GIS shapefiles or other tightly packed cartesian coordinate structures. ```r vector_segments(sf.coords, node.coords, realign = TRUE, arcs, arc.symbol = " --> ", nneighbors = 40, remove.duplicates = FALSE) assign_pa_to_segments(input, n, arc.pa, datetime = NULL) ``` ## Arguments - `sf.coords`: A two column dataframe containing shapefile Cartesian coordinates (or other tightly packed Cartesian coordinates, see Examples). The first column should define `x` locations and the second column define `y` locations. - `node.coords`: A two column dataframe containing network node Cartesian coordinates, with the first column defining `x` location and the second column defining `y` location. The coordinates should use the same coordinate system as `sf.coords`, e.g., UTM easting and northing, longitude and latitude, etc. The `row.names` attribute should contain the correct node names (i.e., they should correspond to names used in the argument `arcs`. - `realign`: Logical. If `node.coords` do not exist in `sf.coords` should they be assigned to the closest location in `sf.coords`? The default option `realign = TRUE` is strongly reccomended, and may be set permenantly in later versions of `vector_segments`. - `arcs`: A character vector of arc names in the network. In particular, designations of nodes which serve arcs bounds, seperated by a user-defined `arc.symbol`. For example, to designate the arc $\overrightarrow{uv}$ using the `arc.symbol` `-->`, I would use: `u --> v`. Node names used to define arcs in the character vector should correspond to those in `row.names(node.coords)`. - `arc.symbol`: A symbol indicating the directional arc connecting two nodes. For example, to designate the arc $\overrightarrow{uv}$, the package **igraph** uses `u|v`, while **streamDAG** generally uses `u --> v`. - `nneighbors`: Number of nearest neighbor points to potentially consider as the next point in an evolving arc path. - `remove.duplicates`: Logical. For duplicate coordinates, should the second point be removed? - `input`: The first argument for `assign_pa_to_segments`. Ideally, the output from `vector_segments`. For example, let `output <- vector_segments(...)`, then `input = output`. - `n`: The number of repeated presence/absence timeframe observations for surface water contained in `arc.pa`. - `arc.pa`: An $n \times m$ matrix or dataframe of stream arc surface water presence/absence = $\{0, 1\}$ outcomes, where $n$ denotes the number of observed timeframes in which arcs were observed, and $m$ is the number of arcs. The `names` of the dataframe should correspond to those given in the `arcs` argument from `vector_segments`. - `datetime`: Optional `unique()` time classes corresping to rows in `arc.pa`. ## Details The function `vector_segments` assigns network arc designations (from the argument `arcs`) to shape file coordinates. The function `assign_pa_to_segments` presence/absence surface water designations to these arcs based on information from `arc.pa`. ## Returns The function `vector_segments` creates an object of class `network_to_sf`. It also returns a list with two components, with only the first being `visible`. - **df**: Is a dataframe with four columns: 1) `point` (referring an original `sf.coord` location), 2) `arc.label`, an assigned arc name for the location, 3) `x` the **x** coordinates, and 4) `y` the **x** coordinates. - **node.coords**: Is dataframe with the `node.coords` for stream arcs. These will have been potentially shifted, if `realign = TRUE`, hence their inclusion as function output. The function `assign_pa_to_segments` returns a dataframe that adds a stream/presence absence column to the to the `df` dataframe output from `vector_segments`, based on the argument `arc.pa` ## Author(s) Ken Aho ## Note The `assign_pa_to_segments` function will return a `warning` (but will try to run anyway) if `input` is not the output from `vector_segments`. ## See Also `spatial.plot` ## Examples ```r # Data sfx <- c(-3,0,1.5,2,2.9,4,5,6) sfy <- c(5,2,1.7,1.6,1.5,1.4,1.2,1) sf.coords <- data.frame(x = sfx, y = sfy) node.coords <- data.frame(x = c(-2.1,2,4,6), y = c(3.75,1.6,1.4,1)) row.names(node.coords) <- c("n1","n2","n3","n4") # must be consistent with arc names arc.pa <- data.frame(matrix(ncol = 3, data = c(1,1,1, 0,1,1, 1,1,1, 0,0,1), byrow = TRUE)) names(arc.pa) <- c("n1 --> n2", "n2 --> n3", "n3 --> n4") # Use of vector_segments vs <- vector_segments(sf.coords, node.coords, realign = TRUE, names(arc.pa)) vs # Plotting example plot(sf.coords, pch = 19, col = c(rep(1,4),rep(2,2),rep(3,2))) vsd <- vs$df fal <- as.factor(vsd$arc.label) lvls <- levels(fal) for(i in 1:nlevels(fal)){ temp <- vsd[fal == lvls[i],] lines(temp$x, temp$y, col = i) } vs4 <- assign_pa_to_segments(vs, 4, arc.pa) head(vs4) ```

vector_segments function