spatial_morphers: Morph spatial networks into a different structure

In luukvdmeer/sfnetworks: Tidy Geospatial Networks

Morph spatial networks into a different structure

Description

Spatial morphers form spatial add-ons to the set of morphers provided by tidygraph. These functions change the existing structure of the network.

Usage

to_spatial_contracted(
  x,
  ...,
  simplify = TRUE,
  compute_centroids = TRUE,
  attribute_summary = "ignore",
  summarise_attributes = deprecated(),
  store_original_data = FALSE
)

to_spatial_directed(x)

to_spatial_explicit(x, ...)

to_spatial_implicit(x)

to_spatial_mixed(x, directed)

to_spatial_neighborhood(x, node, threshold, weights = edge_length(), ...)

to_spatial_reversed(x, protect = NULL)

to_spatial_shortest_paths(x, ...)

to_spatial_simple(
  x,
  remove_multiple = TRUE,
  remove_loops = TRUE,
  attribute_summary = "first",
  summarise_attributes = deprecated(),
  store_original_data = FALSE
)

to_spatial_smooth(
  x,
  protect = NULL,
  require_equal = NULL,
  attribute_summary = "ignore",
  summarise_attributes = deprecated(),
  store_original_data = FALSE
)

to_spatial_subdivision(x, protect = NULL, all = FALSE, merge = TRUE)

to_spatial_subset(x, ..., subset_by = NULL)

to_spatial_transformed(x, ...)

to_spatial_unique(x, attribute_summary = "ignore", store_original_data = FALSE)

Arguments

x	An object of class sfnetwork.
...	Arguments to be passed on to other functions. See the description of each morpher for details.
simplify	Should the network be simplified after contraction? Defaults to TRUE. This means that multiple edges and loop edges will be removed. Multiple edges are introduced by contraction when there are several connections between the same groups of nodes. Loop edges are introduced by contraction when there are connections within a group. Note however that setting this to TRUE also removes multiple edges and loop edges that already existed before contraction.
compute_centroids	Should the new geometry of each contracted group of nodes be the centroid of all group members? Defaults to TRUE. If set to FALSE, the geometry of the first node in each group will be used instead, which requires considerably less computing time.
attribute_summary	Whenever groups of nodes or edges are merged into a single feature during morphing, how should their attributes be summarized? There are several options, see igraph-attribute-combination for details.
summarise_attributes	Deprecated, use attribute_summary instead.
store_original_data	Whenever groups of nodes or edges are merged into a single feature during morphing, should the data of the original features be stored as an attribute of the new feature, in a column named .orig_data. This is in line with the design principles of tidygraph. Defaults to FALSE.
directed	Which edges should be directed? Evaluated by evaluate_edge_query.
node	The node for which the neighborhood will be calculated. Evaluated by evaluate_node_query. When multiple nodes are given, only the first one is used.
threshold	The threshold cost to be used. Only nodes reachable within this threshold cost from the reference node will be included in the neighborhood. Should be a numeric value in the same units as the given edge weights. Alternatively, units can be specified explicitly by providing a units object. Multiple threshold values may be given, which will result in mutliple neigborhoods being returned.
weights	The edge weights to be used for travel cost computation. Evaluated by evaluate_weight_spec. The default is edge_length, which computes the geographic lengths of the edges.
protect	Nodes or edges to be protected from being changed in structure. Evaluated by evaluate_node_query in the case of nodes and by evaluate_edge_query in the case of edges. Defaults to NULL, meaning that no features are protected.
remove_multiple	Should multiple edges be merged into one. Defaults to TRUE.
remove_loops	Should loop edges be removed. Defaults to TRUE.
require_equal	Which attributes of its incident edges should be equal in order for a pseudo node to be removed? Evaluated as a dplyr_tidy_select argument. Defaults to NULL, meaning that attribute equality is not considered for pseudo node removal.
all	Should edges be subdivided at all their interior points? If set to FALSE, edges are only subdivided at those interior points that share their location with any other interior or boundary point (a node) in the edges table. Defaults to FALSE. By default sfnetworks rounds coordinates to 12 decimal places to determine spatial equality. You can influence this behavior by explicitly setting the precision of the network using st_set_precision.
merge	Should multiple subdivision points at the same location be merged into a single node, and should subdivision points at the same location as an existing node be merged into that node? Defaults to TRUE. If set to FALSE, each subdivision point is added separately as a new node to the network. By default sfnetworks rounds coordinates to 12 decimal places to determine spatial equality. You can influence this behavior by explicitly setting the precision of the network using st_set_precision.
subset_by	Whether to create subgraphs based on nodes or edges.

Details

Morphers are not meant to be called directly. Instead, they should be called inside the morph verb to change the network structure temporarily. Depending on the chosen morpher, this results in a list of one or more network objects. Single elements of that list can be extracted directly as a new network by calling the morpher inside the convert verb instead, to make the changes lasting rather than temporary.

It also possible to create your own morphers. See the documentation of morph for the requirements for custom morphers.

Value

Either a morphed_sfnetwork, which is a list of one or more sfnetwork objects, or a morphed_tbl_graph, which is a list of one or more tbl_graph objects. See the description of each morpher for details.

Functions

• to_spatial_contracted(): Combine groups of nodes into a single node per group. ... is forwarded to group_by to create the groups. The centroid of such a group will be used by default as geometry of the contracted node. If edges are spatially explicit, edge geometries are updated accordingly such that the valid spatial network structure is preserved. Returns a morphed_sfnetwork containing a single element of class sfnetwork.

• to_spatial_directed(): Make a network directed in the direction given by the linestring geometries of the edges. Differs from to_directed, which makes a network directed based on the node indices given in the from and to columns. In undirected networks these indices may not correspond with the endpoints of the linestring geometries. Returns a morphed_sfnetwork containing a single element of class sfnetwork. This morpher requires edges to be spatially explicit. If not, use to_directed.

• to_spatial_explicit(): Create linestring geometries between source and target nodes of edges. If the edges data can be directly converted to an object of class sf using st_as_sf, extra arguments can be provided as ... and will be forwarded to st_as_sf internally. Otherwise, straight lines will be drawn between the source and target node of each edge. Returns a morphed_sfnetwork containing a single element of class sfnetwork.

• to_spatial_implicit(): Drop edge geometries from the network. Returns a morphed_sfnetwork containing a single element of class sfnetwork.

• to_spatial_mixed(): Construct a mixed network in which some edges are directed, and some are undirected. In practice this is implemented as a directed network in which those edges that are meant to be undirected are duplicated and reversed. Returns a morphed_sfnetwork containing a single element of class sfnetwork.

• to_spatial_neighborhood(): Limit a network to the spatial neighborhood of a specific node. ... is forwarded to st_network_cost to compute the travel cost from the specified node to all other nodes in the network. Returns a morphed_sfnetwork that may contain multiple elements of class sfnetwork, depending on the number of given thresholds. When unmorphing only the first instance of both the node and edge data will be used, as the the same node and/or edge can be present in multiple neighborhoods.

• to_spatial_reversed(): Reverse the direction of edges. Returns a morphed_sfnetwork containing a single element of class sfnetwork.

• to_spatial_shortest_paths(): Limit a network to those nodes and edges that are part of the shortest path between two nodes. ... is evaluated in the same manner as st_network_paths. Returns a morphed_sfnetwork that may contain multiple elements of class sfnetwork, depending on the number of requested paths. When unmorphing only the first instance of both the node and edge data will be used, as the the same node and/or edge can be present in multiple paths.

• to_spatial_simple(): Construct a simple version of the network. A simple network is defined as a network without loop edges and multiple edges. A loop edge is an edge that starts and ends at the same node. Multiple edges are different edges between the same node pair. When merging them into a single edge, the geometry of the first edge is preserved. The order of the edges can be influenced by calling arrange before simplifying. Returns a morphed_sfnetwork containing a single element of class sfnetwork.

• to_spatial_smooth(): Construct a smoothed version of the network by iteratively removing pseudo nodes, while preserving the connectivity of the network. In the case of directed networks, pseudo nodes are those nodes that have only one incoming and one outgoing edge. In undirected networks, pseudo nodes are those nodes that have two incident edges. Equality of attribute values among the two edges can be defined as an additional requirement by setting the require_equal parameter. Connectivity of the network is preserved by concatenating the incident edges of each removed pseudo node. Returns a morphed_sfnetwork containing a single element of class sfnetwork.

• to_spatial_subdivision(): Construct a subdivision of the network by subdividing edges at interior points. Subdividing means that a new node is added on an edge, and the edge is split in two at that location. Interior points are those points that shape a linestring geometry feature but are not endpoints of it. Returns a morphed_sfnetwork containing a single element of class sfnetwork. This morpher requires edges to be spatially explicit.

• to_spatial_subset(): Subset the network by applying a spatial filter, i.e. a filter on the geometry column based on a spatial predicate. ... is evaluated in the same manner as st_filter. Returns a morphed_sfnetwork containing a single element of class sfnetwork. For filters on an attribute column, use to_subgraph.

• to_spatial_transformed(): Transform the geospatial coordinates of the network into a different coordinate reference system. ... is evaluated in the same manner as st_transform. Returns a morphed_sfnetwork containing a single element of class sfnetwork.

• to_spatial_unique(): Merge nodes with equal geometries into a single node. Returns a morphed_sfnetwork containing a single element of class sfnetwork. By default sfnetworks rounds coordinates to 12 decimal places to determine spatial equality. You can influence this behavior by explicitly setting the precision of the network using st_set_precision.

Examples

library(sf, quietly = TRUE)
library(tidygraph, quietly = TRUE)

net = as_sfnetwork(roxel, directed = FALSE) |>
  st_transform(3035)

# Temporary changes with morph and unmorph.
net |>
 activate(edges) |>
 morph(to_spatial_shortest_paths, from = 1, to = 10) |>
 mutate(in_paths = TRUE) |>
 unmorph()

# Lasting changes with convert.
net |>
 activate(edges) |>
 convert(to_spatial_shortest_paths, from = 1, to = 10)

luukvdmeer/sfnetworks documentation built on Nov. 21, 2024, 4:54 a.m.