Find neighbors according to pawn movement

For one node (argument focus), finds neighbors among a list of nodes according to the fool movement. This movement is orthogonal to the fool() function. The pawn can only move vertically, i.e. through a transect.

The detection of neighbors using the fool method can work with two-dimensional sampling (both transects and quadrats) and one-dimensional sampling of type quadrats-only. For sampling of type transects-only, please use the function fool().

pawn(nodes, focus, degree = 1, directed = FALSE, reverse = FALSE, self = FALSE)

Arguments

nodes: a data.frame with (at least) the following three columns: node, transect, and quadrats. Must be the output of the function create_node_labels().
focus: an character of length 1. The node label for which the neighbors must be found. Must exist in the nodes object.
degree: an integer of length 1. The maximum number of neighbors to search for.
directed: a logical of length 1. If FALSE (default), search for neighbors in all directions (undirected network). Otherwise, the network will be considered as directed according to the orientations of the network. The default orientation follows the order of node labels in both axes.
reverse: a logical of length 1. If TRUE, change the default orientation of the network. This argument is ignored if directed = FALSE. See examples for further detail.
self: a logical of length 1. If TRUE, a node can be its own neighbor. Default is FALSE.

Value

A subset of the nodes (data.frame) where each row is a neighbor of the focal node.

Details

This function is internally called by create_edge_list() but it can be directly used to 1) understand the neighbors detection method, and 2) to check detected neighbors for one particular node (focus).

Examples

library("chessboard")

# Two-dimensional sampling (only) ----
sites_infos <- expand.grid("transect" = 1:9, "quadrat" = 1:9)

nodes <- create_node_labels(data     = sites_infos, 
                            transect = "transect", 
                            quadrat  = "quadrat")

focus     <- "5-5"

# Default settings ----
neighbors <- pawn(nodes, focus)
gg_chessboard(nodes) +
  geom_node(nodes, focus) +
  geom_neighbors(nodes, neighbors)


# Higher degree of neighborhood ----
neighbors <- pawn(nodes, focus, degree = 3)
gg_chessboard(nodes) +
  geom_node(nodes, focus) +
  geom_neighbors(nodes, neighbors)

  
# Directed (default orientation) ----
neighbors <- pawn(nodes, focus, degree = 3, directed = TRUE)
gg_chessboard(nodes) +
  geom_node(nodes, focus) +
  geom_neighbors(nodes, neighbors)

  
# Directed (reverse orientation) ----
neighbors <- pawn(nodes, focus, degree = 3, directed = TRUE, reverse = TRUE)
gg_chessboard(nodes) +
  geom_node(nodes, focus) +
  geom_neighbors(nodes, neighbors)