Skip to contents

Get stream segment neighbours

Source: R/get_segment_neighbours.R
get_segment_neighbours.Rd

For each input stream segment, the function reports those upstream, downstream, or up-and downstream segments that are connected to the input segment(s) within a specified neighbour order, with the option to summarize attributes across these segments. Note that the stream segment and sub-catchment IDs are identical, and for consistency, we use the term "subc_id". The input graph can be created with read_geopackage() and get_catchment_graph().

This function can be used to obtain the neighbour stream segments / sub-catchments for spatially explicit models or for spatial prioritization analyses (e.g. Marxan/Gurobi). By selecting a wider radius, the spatial dependency of the neighbouring segments / sub-catchments can be increased.

Usage

get_segment_neighbours(
  g,
  subc_id = NULL,
  var_layer = NULL,
  stat = NULL,
  attach_only = FALSE,
  order = 5,
  mode = "in",
  n_cores = 1,
  max_size = 1500
)

Arguments

g

igraph object. A directed graph.

subc_id

numeric vector of the input sub-catchment IDs (=stream segment IDs) for which to search the connected segments.

var_layer

character vector. One or more attributes (variable layers) of the input graph that should be reported for each output segment_id ("to_stream"). Optional. Default is NULL.

stat

one of the functions mean, median, min, max, sd (without quotes). Aggregates (or summarizes) the variables for the neighbourhood of each input segment (e.g., the average land cover in the next five upstream segments or sub-catchments). Default is NULL.

attach_only

logical. If TRUE, the selected variables will be only attached to each segment without any further aggregation. Default is FALSE.

order

numeric. The neighbouring order as in igraph::ego. Order = 1 would be immediate neighbours of the input sub-catchment IDs, order = 2 would be the order 1 plus the immediate neighbours of those sub-catchment IDs in order 1, and so on.

mode

character. One of "in", "out", or "all". "in" returns only upstream neighbouring segments, "out" returns only the downstream segments, and "all" returns both.

n_cores

numeric. Number of cores used for parallelisation in the case of multiple stream segments / outlets. Default is 1. Note that the parallelisation process requires copying the data to each core. In case the graph is very large, and many segments are used as an input, setting n_cores to a higher value can speed up the computation. This comes however at the cost of possible RAM limitations and even slower processing since the large data will be copied to each core. Hence consider testing first with n_cores = 1. Optional.

max_size

numeric. Specifies the maximum size of the data passed to the parallel back-end in MB. Default is 1500 (1.5 GB). Consider a higher value for large study areas (more than one 20°x20° tile). Optional.

Value

A data.table indicating the connected segments (stream | to_stream), or a data.table that summarizes the attributes of those neighbours contributing to each segment.

#' @note Currently the attributes are not provided for the outlet (the selected subc_id segment). If the attributes are also needed for the outlet subc_id, then the next downstream sub_id can be selected (enlarge the study area) using e.g. get_catchment_graph().

References

Csardi G, Nepusz T: The igraph software package for complex network research, InterJournal, Complex Systems 1695. 2006. https://igraph.org

See also

read_geopackage() and get_catchment_graph.() to create the input graph.

Author

Sami Domisch

Examples

# Download test data into the temporary R folder
# or define a different directory
my_directory <- tempdir()
download_test_data(my_directory)

# Load the stream network as graph
my_graph <- read_geopackage(gpkg= paste0(my_directory,
                                         "/hydrography90m_test_data",
                                         "/order_vect_59.gpkg"),
                            import_as = "graph")

# Subset the graph and get a smaller catchment
my_graph <- get_catchment_graph(g = my_graph, subc_id = 513866048, mode = "in",
                                outlet = FALSE, as_graph = TRUE, n_cores = 1)


# Get a vector of all segment IDs
library(igraph)
subc_id <- as_ids(V(my_graph))


# Get all (up-and downstream) directly adjacent neighbours of each segment
get_segment_neighbours(g = my_graph, subc_id = subc_id,
                       order = 1, mode = "all")

# Get the upstream segment neighbours in the 5th order
# and report the length and source elevation
# for the neighbours of each input segment
get_segment_neighbours(g = my_graph, subc_id = subc_id,
                       order = 5, mode = "in", n_cores = 1,
                       var_layer = c("length", "source_elev"),
                       attach_only = TRUE)

# Get the downstream segment neighbours in the 5th order
# and calculate the median length and source elevation
# across the neighbours of each input segment
get_segment_neighbours(g = my_graph, subc_id = subc_id,
                       order = 2, mode ="out", n_cores = 1,
                       var_layer = c("length", "source_elev"),
                       stat = median)

# Get the up-and downstream segment neighbours in the 5th order
# and report the median length and source elevation
# for the neighbours of each input segment
get_segment_neighbours(g = my_graph, subc_id = subc_id, order = 2,
                       mode = "all", n_cores = 1,
                       var_layer = c("length", "source_elev"),
                       stat = mean, attach_only = TRUE)