Movatterモバイル変換

Type:	Package
Title:	Create Network Connections Based on Chess Moves
Version:	0.1
Description:	Provides functions to work with directed (asymmetric) and undirected (symmetric) spatial networks. It makes the creation of connectivity matrices easier, i.e. a binary matrix of dimension n x n, where n is the number of nodes (sampling units) indicating the presence (1) or the absence (0) of an edge (link) between pairs of nodes. Different network objects can be produced by 'chessboard': node list, neighbor list, edge list, connectivity matrix. It can also produce objects that will be used later in Moran's Eigenvector Maps (Dray et al. (2006) <doi:10.1016/j.ecolmodel.2006.02.015>) and Asymetric Eigenvector Maps (Blanchet et al. (2008) <doi:10.1016/j.ecolmodel.2008.04.001>), methods available in the package 'adespatial' (Dray et al. (2023)https://CRAN.R-project.org/package=adespatial). This work is part of the FRB-CESAB working group Bridgehttps://www.fondationbiodiversite.fr/en/the-frb-in-action/programs-and-projects/le-cesab/bridge/.
URL:	https://github.com/frbcesab/chessboard
BugReports:	https://github.com/frbcesab/chessboard/issues
License:	GPL-2 |GPL-3 [expanded from: GPL (≥ 2)]
Encoding:	UTF-8
Imports:	dplyr, ggplot2, magrittr, rlang, sf, tidyr
Suggests:	knitr, igraph, patchwork, rmarkdown, testthat (≥ 3.0.0)
RoxygenNote:	7.2.3
VignetteBuilder:	knitr
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2023-10-13 18:10:41 UTC; Nicolas
Author:	Nicolas Casajus [aut, cre, cph], Erica Rievrs Borges [aut], Eric Tabacchi [aut], Guillaume Fried [aut], Nicolas Mouquet [aut]
Maintainer:	Nicolas Casajus <nicolas.casajus@fondationbiodiversite.fr>
Repository:	CRAN
Date/Publication:	2023-10-14 08:00:02 UTC

chessboard: Create Network Connections Based on Chess Moves

Description

Provides functions to work with directed (asymmetric) and undirected (symmetric) spatial networks. It makes the creation of connectivity matrices easier, i.e. a binary matrix of dimension n x n, where n is the number of nodes (sampling units) indicating the presence (1) or the absence (0) of an edge (link) between pairs of nodes. Different network objects can be produced by 'chessboard': node list, neighbor list, edge list, connectivity matrix. It can also produce objects that will be used later in Moran's Eigenvector Maps (Dray et al. (2006)doi:10.1016/j.ecolmodel.2006.02.015) and Asymetric Eigenvector Maps (Blanchet et al. (2008)doi:10.1016/j.ecolmodel.2008.04.001), methods available in the package 'adespatial' (Dray et al. (2023)https://CRAN.R-project.org/package=adespatial). This work is part of the FRB-CESAB working group Bridgehttps://www.fondationbiodiversite.fr/en/the-frb-in-action/programs-and-projects/le-cesab/bridge/.

Author(s)

Maintainer: Nicolas Casajusnicolas.casajus@fondationbiodiversite.fr (ORCID) [copyright holder]

Authors:

• Erica Rievrs Borgeserica.rievrs@fondationbiodiversite.fr (ORCID)

• Eric Tabacchieric.tabacchi@univ-tlse3.fr (ORCID)

• Guillaume Friedguillaume.fried@anses.fr (ORCID)

• Nicolas Mouquetnicolas.mouquet@cnrs.fr (ORCID)

See Also

Useful links:

• https://github.com/frbcesab/chessboard

• Report bugs athttps://github.com/frbcesab/chessboard/issues

Pipe operator

Description

Seemagrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

The result of callingrhs(lhs).

Append several edge lists

Description

Appends several edge lists created bycreate_edge_list(). Merged edgeswill be ordered and duplicates will be removed.

Usage

append_edge_lists(...)

Arguments

Value

Adata.frame withn rows (wheren is the total number of edges)and the following two columns:

• from: the node label of one of the two endpoints of the edge

• to: the node label of the other endpoint of the edge

Examples

library("chessboard")# Two-dimensional sampling (only) ----sites_infos <- expand.grid("transect" = 1:3, "quadrat" = 1:5)nodes <- create_node_labels(data     = sites_infos,                             transect = "transect",                             quadrat  = "quadrat")edges_1 <- create_edge_list(nodes, method = "pawn", directed = TRUE)edges_2 <- create_edge_list(nodes, method = "bishop", directed = TRUE)edges <- append_edge_lists(edges_1, edges_2)

Combine several connectivity matrices

Description

Combines different connectivity matrices by row names and column names byperforming a 2-dimensional full join. Missing edges are filled with0(default) orNA (argumentna_to_zero).

Usage

append_matrix(..., na_to_zero = TRUE)

Arguments

Value

A connectivity matrix of dimensions⁠n x n⁠, wheren is the totalnumber of unique nodes across all provided matrices.

Examples

mat1 <- matrix(rep(1, 9), nrow = 3)colnames(mat1) <- c("A", "B", "C")rownames(mat1) <- c("A", "B", "C")mat1mat2 <- matrix(rep(1, 9), nrow = 3)colnames(mat2) <- c("D", "E", "F")rownames(mat2) <- c("D", "E", "F")mat2mat3 <- matrix(rep(1, 9), nrow = 3)colnames(mat3) <- c("F", "G", "H")rownames(mat3) <- c("F", "G", "H")mat3append_matrix(mat1, mat2, mat3)append_matrix(mat1, mat2, mat3, na_to_zero = FALSE)

Find neighbors according to bishop movement

Description

For one node (argumentfocus), finds neighbors among a list of nodesaccording to the bishop movement.This movement is derived from the chess game. The bishop can move along thetwo diagonals.

The detection of neighbors using this method can only work withtwo-dimensional sampling (bothtransects andquadrats).For sampling of typetransects-only orquadrats-only,please use the functionsfool() orpawn(), respectively.

Usage

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

Arguments

Details

This function is internally called bycreate_edge_list() but it can bedirectly used to 1) understand the neighbors detection method, and 2) tocheck detected neighbors for one particular node (focus).

Value

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

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 <- bishop(nodes, focus)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)# Higher degree of neighborhood ----neighbors <- bishop(nodes, focus, degree = 3)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)  # Directed (default orientation) ----neighbors <- bishop(nodes, focus, degree = 3, directed = TRUE)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)  # Directed (reverse orientation) ----neighbors <- bishop(nodes, focus, degree = 3, directed = TRUE,                     reverse = TRUE)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)

Find neighbors according to bishop left movement

Description

For one node (argumentfocus), finds neighbors among a list of nodesaccording to the bishop left movement.This movement is derived from thebishop() method and can only move alongthe bottom-right to top-left diagonal.

The detection of neighbors using this method can only work withtwo-dimensional sampling (bothtransects andquadrats).For sampling of typetransects-only orquadrats-only,please use the functionsfool() orpawn(), respectively.

Usage

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

Arguments

Details

This function is internally called bycreate_edge_list() but it can bedirectly used to 1) understand the neighbors detection method, and 2) tocheck detected neighbors for one particular node (focus).

Value

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

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 <- bishop_left(nodes, focus)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)# Higher degree of neighborhood ----neighbors <- bishop_left(nodes, focus, degree = 3)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)  # Directed (default orientation) ----neighbors <- bishop_left(nodes, focus, degree = 3, directed = TRUE)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)  # Directed (reverse orientation) ----neighbors <- bishop_left(nodes, focus, degree = 3, directed = TRUE,                          reverse = TRUE)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)

Find neighbors according to bishop right movement

Description

For one node (argumentfocus), finds neighbors among a list of nodesaccording to the bishop right movement.This movement is derived from thebishop() method and can only move alongthe bottom-left to top-right diagonal.

The detection of neighbors using this method can only work withtwo-dimensional sampling (bothtransects andquadrats).For sampling of typetransects-only orquadrats-only,please use the functionsfool() orpawn(), respectively.

Usage

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

Arguments

Details

This function is internally called bycreate_edge_list() but it can bedirectly used to 1) understand the neighbors detection method, and 2) tocheck detected neighbors for one particular node (focus).

Value

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

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 <- bishop_right(nodes, focus)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)# Higher degree of neighborhood ----neighbors <- bishop_right(nodes, focus, degree = 3)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)  # Directed (default orientation) ----neighbors <- bishop_right(nodes, focus, degree = 3, directed = TRUE)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)  # Directed (reverse orientation) ----neighbors <- bishop_right(nodes, focus, degree = 3, directed = TRUE,                           reverse = TRUE)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)

Create a connectivity matrix from an edge list

Description

Converts an edge list to an connectivity matrix (also known as adjacencymatrix).

Usage

connectivity_matrix(  edges,  lower = TRUE,  upper = TRUE,  diag = TRUE,  na_to_zero = TRUE)

Arguments

Value

A connectivity matrix of dimensions⁠n x n⁠, wheren is the numberof nodes.

Examples

# Import Adour sites ----path_to_file <- system.file("extdata", "adour_survey_sampling.csv",                             package = "chessboard")adour_sites  <- read.csv(path_to_file)# Select first location ----adour_sites <- adour_sites[adour_sites$"location" == 1, ]# Create node labels ----adour_nodes <- create_node_labels(data     = adour_sites,                                   location = "location",                                   transect = "transect",                                   quadrat = "quadrat")# Find edges with 1 degree of neighborhood (pawn method) ----adour_edges <- create_edge_list(adour_nodes, method = "pawn",                                 directed = TRUE)# Get connectivity matrix ----connectivity_matrix(adour_edges)# Get connectivity matrix ----connectivity_matrix(adour_edges, na_to_zero = FALSE)

Create an edge list

Description

Creates a list of edges (links) between nodes (sampling units) based on thedetection of neighbors and according to three neighborhood rules:

1. Degree of neighborhood (argumentdegree): the number of adjacentnodes that will be used to createdirect edges. Ifdegree = 1,only nodes directly adjacent to the focal node will be considered asneighbors.

2. Orientation of neighborhood (argumentmethod): can neighbors bedetecting horizontally and/or vertically and/or diagonally? The packagechessboard implements all possible orientations derived from the chessgame.

3. Direction of neighborhood (argumentsdirected andreverse): doesthe sampling design has a direction? If so (directed = TRUE), the networkwill be considered asdirected and the direction will follow the orderof node labels in both axes (except ifreverse = TRUE).

It's important to note that, even the packagechessboard is designed todeal with spatial networks, this function does not explicitly use spatialcoordinates to detect neighbors. Instead it uses thenode labels. Thefunctioncreate_node_labels() must be used before this function to createnode labels.

Usage

create_edge_list(  nodes,  method,  degree = 1,  directed = FALSE,  reverse = FALSE,  self = FALSE)

Arguments

Value

Adata.frame withn rows (wheren is the number of edges) andthe following two columns:

• from: the node label of one of the two endpoints of the edge

• to: the node label of the other endpoint of the edge

Examples

library("chessboard")# Two-dimensional sampling (only) ----sites_infos <- expand.grid("transect" = 1:3, "quadrat" = 1:5)nodes <- create_node_labels(data     = sites_infos,                             transect = "transect",                             quadrat  = "quadrat")edges <- create_edge_list(nodes, method = "pawn", directed = TRUE)edgesedges <- create_edge_list(nodes, method = "bishop", directed = TRUE)edges

Create unique node labels

Description

Creates unique node (sampling units) labels in directed (or undirected)spatial (or not) networks.

It's important to note that, even the packagechessboard is designed todeal with spatial networks, it does not explicitly use spatial coordinates.Every functions of the package will use thenode labels.

To work, the packagechessboard requires that the sampling has twodimensions:one from bottom to top (calledquadrats), and one from left to right(calledtransects). If the sampling has been conducted along one singledimension (transects orquadrats), this function will create afictitious label for the missing dimension.In other words, the packagechessboard can work with sampling designs suchas regular grids (two dimensions), transects (one dimension), and quadrats(one dimension).

In addition, the package can also deal with multiple locations. In thatcase, users will need to use the argumentlocation.

The node labels will be of the form:1-2, where1 is the identifier ofthe transect (created by the function if missing), and2, the identifierof the quadrat (created by the function if missing).

Usage

create_node_labels(data, location, transect, quadrat)

Arguments

Value

Adata.frame with at least the four following columns:

• node, the node label

• location, the identifier of the location

• transect, the identifier of the transect

• quadrat, the identifier of the quadratOther columns present in the original dataset will also be added.

Examples

library("chessboard")# Two-dimensional sampling ----sites_infos <- expand.grid("transect" = 1:3, "quadrat" = 1:5)sites_infosnodes <- create_node_labels(data     = sites_infos,                             transect = "transect",                             quadrat  = "quadrat")nodesgg_chessboard(nodes)# One-dimensional sampling (only transects) ----transects_only <- data.frame("transect" = 1:5)nodes <- create_node_labels(transects_only,                            transect = "transect")nodesgg_chessboard(nodes)# One-dimensional sampling (only quadrats) ----quadrats_only <- data.frame("quadrat" = 1:5)nodes <- create_node_labels(quadrats_only,                            quadrat = "quadrat")nodesgg_chessboard(nodes)

Compute the pairwise Euclidean distance

Description

Computes the Euclidean distance between two nodes using the functionsf::st_distance(). If the CRS is not a Cartesian system, the Great Circledistance will be used instead.

Usage

distance_euclidean(sites, ...)

Arguments

Value

A three-columndata.frame with:

• from, the first node

• to, the second node

• weight, the Euclidean distance between the two nodes

Examples

# Import Adour sites ----path_to_file <- system.file("extdata", "adour_survey_sampling.csv",                             package = "chessboard")adour_sites <- read.csv(path_to_file)# Select the 15 first sites ----adour_sites <- adour_sites[1:15, ]# Create node labels ----adour_sites <- create_node_labels(adour_sites,                                   location = "location",                                   transect = "transect",                                   quadrat  = "quadrat")# Convert sites to sf object (POINTS) ----adour_sites <- sf::st_as_sf(adour_sites, coords = c("longitude", "latitude"),                            crs = "epsg:2154")# Compute distances between pairs of sites ----weights <- distance_euclidean(adour_sites)head(weights)

Convert edge list to spatial object

Description

Converts an edge list to ansf spatial object of typeLINESTRING withone row per edge.

Usage

edges_to_sf(edges, sites)

Arguments

Value

Ansf spatial object of typeLINESTRING where the number of rowscorrespond to the number of edges.

Examples

# Import Adour sites ----path_to_file <- system.file("extdata", "adour_survey_sampling.csv",                             package = "chessboard")adour_sites  <- read.csv(path_to_file)# Select first location ----adour_sites <- adour_sites[adour_sites$"location" == 1, ]# Create node labels ----adour_nodes <- create_node_labels(data     = adour_sites,                                   location = "location",                                   transect = "transect",                                   quadrat = "quadrat")# Find edges with 1 degree of neighborhood (pawn method) ----adour_edges <- create_edge_list(adour_nodes, method = "pawn",                                 directed = TRUE)# Convert sites to spatial POINT ----adour_sites_sf <- sf::st_as_sf(adour_nodes, coords = 5:6, crs = "epsg:2154")# Convert edges to spatial LINESTRING ----edges_sf <- edges_to_sf(adour_edges, adour_sites_sf)head(edges_sf)# Visualization ----plot(sf::st_geometry(adour_sites_sf), pch = 19)plot(sf::st_geometry(edges_sf), add = TRUE)# Find edges with 1 degree of neighborhood (pawn and bishop methods) ----adour_edges_1 <- create_edge_list(adour_nodes, method = "pawn",                                   directed = TRUE)adour_edges_2 <- create_edge_list(adour_nodes, method = "bishop",                                   directed = TRUE)# Append edges ----adour_edges <- append_edge_lists(adour_edges_1, adour_edges_2)# Convert sites to spatial POINT ----adour_sites_sf <- sf::st_as_sf(adour_nodes, coords = 5:6, crs = "epsg:2154")# Convert edges to spatial LINESTRING ----edges_sf <- edges_to_sf(adour_edges, adour_sites_sf)head(edges_sf)# Visualization ----plot(sf::st_geometry(adour_sites_sf), pch = 19)plot(sf::st_geometry(edges_sf), add = TRUE)

Create an edges weights matrix

Description

Creates an edges weights matrix from the output ofdistance_euclidean().

Usage

edges_weights_matrix(distances, lower = TRUE, upper = TRUE, diag = TRUE)

Arguments

Value

An edges weightsmatrix of dimensions⁠n x n⁠, wheren is thenumber of nodes (sites).

Examples

# Import Adour sites ----path_to_file <- system.file("extdata", "adour_survey_sampling.csv",                             package = "chessboard")adour_sites <- read.csv(path_to_file)# Select the 15 first sites ----adour_sites <- adour_sites[1:15, ]# Create node labels ----adour_sites <- create_node_labels(adour_sites,                                   location = "location",                                   transect = "transect",                                   quadrat  = "quadrat")# Convert sites to sf object (POINTS) ----adour_sites_sf <- sf::st_as_sf(adour_sites,                                coords = c("longitude", "latitude"),                               crs = "epsg:2154")# Compute distances between pairs of sites along the Adour river ----adour_dists <- distance_euclidean(adour_sites_sf)# Create Edges weights matrix ----edges_weights_matrix(adour_dists)# Create Edges weights matrix (with options) ----edges_weights_matrix(adour_dists, lower = FALSE)edges_weights_matrix(adour_dists, upper = FALSE)edges_weights_matrix(adour_dists, diag = FALSE)

Create an edges weights vector

Description

Creates an edges weights vector that can be used inaem() of the packageadespatial. Resulting edges weights equal to 0 will be replaced by⁠4 x max(w)⁠, wheremax(w) is the maximal weight in the matrix.

Usage

edges_weights_vector(x, y)

Arguments

Value

An edges weightsvector.

Examples

# Import Adour sites ----path_to_file <- system.file("extdata", "adour_survey_sampling.csv",                             package = "chessboard")adour_sites <- read.csv(path_to_file)# Select the 15 first sites ----adour_sites <- adour_sites[1:15, ]# Create node labels ----adour_sites <- create_node_labels(adour_sites,                                   location = "location",                                   transect = "transect",                                   quadrat  = "quadrat")# Convert sites to sf object (POINTS) ----adour_sites_sf <- sf::st_as_sf(adour_sites,                                coords = c("longitude", "latitude"),                               crs = "epsg:2154")# Create edges based on the pawn move (directed network) ----adour_edges <- create_edge_list(adour_sites, method = "pawn",                                 directed = TRUE)# Create nodes-by-edges matrix ----adour_matrix <- nodes_by_edges_matrix(adour_edges)# Compute Euclidean distances between pairs of sites ----adour_dists <- distance_euclidean(adour_sites_sf)# Create Edges weights vector ----edges_weights_vector(adour_matrix, adour_dists)

Find neighbors according to fool movement

Description

For one node (argumentfocus), finds neighbors among a list of nodesaccording to the fool movement.This movement is derived from the chess game. The fool can only movehorizontally, i.e. through aquadrat.

The detection of neighbors using the fool method can work withtwo-dimensional sampling (bothtransects andquadrats) andone-dimensional sampling of typetransects-only.For sampling of typequadrats-only, please use the functionpawn().

Usage

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

Arguments

Details

This function is internally called bycreate_edge_list() but it can bedirectly used to 1) understand the neighbors detection method, and 2) tocheck detected neighbors for one particular node (focus).

Value

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

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 <- fool(nodes, focus)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)# Higher degree of neighborhood ----neighbors <- fool(nodes, focus, degree = 3)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)  # Directed (default orientation) ----neighbors <- fool(nodes, focus, degree = 3, directed = TRUE)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)  # Directed (reverse orientation) ----neighbors <- fool(nodes, focus, degree = 3, directed = TRUE, reverse = TRUE)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)

Link neighbors by arrow on a chessboard

Description

Links neighbors (cells) on a chessboard plotted withgg_chessboard().

Usage

geom_edges(nodes, focus, neighbors)

Arguments

Value

Ageom_segment that must be added to aggplot2 object.

Examples

library("chessboard")sites_infos <- expand.grid("transect" = 1:9, "quadrat" = 1:9)nodes <- create_node_labels(data     = sites_infos,                             transect = "transect",                             quadrat  = "quadrat")focus <- "5-5"neighbors <- wizard(nodes, focus = focus, degree = 4, directed = FALSE,                     reverse = TRUE)gg_chessboard(nodes) +  geom_neighbors(nodes, neighbors) +  geom_edges(nodes, focus, neighbors) +  geom_node(nodes, focus)

Highlight neighbors on a chessboard

Description

Highlights neighbors (cells) on a chessboard plotted withgg_chessboard().

Usage

geom_neighbors(nodes, neighbors)

Arguments

Value

Ageom_point that must be added to aggplot2 object.

Examples

library("chessboard")# Two-dimensional sampling ----sites_infos <- expand.grid("transect" = 1:3, "quadrat" = 1:5)nodes <- create_node_labels(data     = sites_infos,                             transect = "transect",                             quadrat  = "quadrat")neighbors <- pawn(nodes, focus = "2-3")gg_chessboard(nodes) +  geom_node(nodes, "2-3") +  geom_neighbors(nodes, neighbors)

Highlight a node on a chessboard

Description

Highlights a node (cell) on a chessboard plotted withgg_chessboard().

Usage

geom_node(nodes, focus)

Arguments

Value

A list of twogeom_point that must be added to aggplot2 object.

Examples

library("chessboard")# Two-dimensional sampling ----sites_infos <- expand.grid("transect" = 1:3, "quadrat" = 1:5)nodes <- create_node_labels(data     = sites_infos,                             transect = "transect",                             quadrat  = "quadrat")gg_chessboard(nodes) +  geom_node(nodes, "2-3")# One-dimensional sampling (only transects) ----sites_infos <- data.frame("transect" = 1:5)nodes <- create_node_labels(data     = sites_infos,                             transect = "transect")gg_chessboard(nodes) +  geom_node(nodes, "3-1")

Get the list of nodes

Description

Retrieves the node list by selecting and ordering the columnnode of theoutput of the functioncreate_node_labels().

Usage

get_node_list(nodes)

Arguments

Value

A vector of node labels.

Examples

library("chessboard")# Two-dimensional sampling (only) ----sites_infos <- expand.grid("transect" = 1:3, "quadrat" = 1:5)nodes <- create_node_labels(data     = sites_infos,                             transect = "transect",                             quadrat  = "quadrat")get_node_list(nodes)

Plot a sampling as a chessboard

Description

Plots a sampling as a chessboard of dimensionst xq, witht, the number of transects, andq, the number of quadrats.

Usage

gg_chessboard(nodes, xlab = "Transect", ylab = "Quadrat")

Arguments

Value

Aggplot2 object.

Examples

library("chessboard")# Two-dimensional sampling ----sites_infos <- expand.grid("transect" = 1:3, "quadrat" = 1:5)nodes <- create_node_labels(data     = sites_infos,                             transect = "transect",                             quadrat  = "quadrat")gg_chessboard(nodes)# One-dimensional sampling (only transects) ----sites_infos <- data.frame("transect" = 1:5)nodes <- create_node_labels(data     = sites_infos,                             transect = "transect")gg_chessboard(nodes)# One-dimensional sampling (only quadrats) ----sites_infos <- data.frame("quadrat" = 1:5)nodes <- create_node_labels(data    = sites_infos,                             quadrat = "quadrat")gg_chessboard(nodes)

Plot a connectivity or a nodes-by-edges matrix

Description

Plots an connectivity or a nodes-by-edges matrix.

Usage

gg_matrix(x, title)

Arguments

Value

Aggplot2 object.

Examples

library("chessboard")# Import Adour sites ----path_to_file <- system.file("extdata", "adour_survey_sampling.csv",                             package = "chessboard")adour_sites  <- read.csv(path_to_file)# Select first location ----#adour_sites <- adour_sites[adour_sites$"location" == 1, ]# Create node labels ----adour_nodes <- create_node_labels(data     = adour_sites,                                   location = "location",                                   transect = "transect",                                   quadrat = "quadrat")# Find edges with 1 degree of neighborhood (queen method) ----adour_edges <- create_edge_list(adour_nodes, method = "queen",                                 directed = FALSE)# Get connectivity matrix ----adour_con_matrix <- connectivity_matrix(adour_edges)# Visualize matrix ----gg_matrix(adour_con_matrix, title = "Connectivity matrix") +  ggplot2::theme(axis.text = ggplot2::element_text(size = 6))

Find neighbors according to knight movement

Description

For one node (argumentfocus), finds neighbors among a list of nodesaccording to the knight movement.This movement is derived from the chess game. The knight is the differencebetween thewizard() and thequeen().

The detection of neighbors using this method can only work withtwo-dimensional sampling (bothtransects andquadrats).For sampling of typetransects-only orquadrats-only,please use the functionsfool() orpawn(), respectively.

Usage

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

Arguments

Details

This function is internally called bycreate_edge_list() but it can bedirectly used to 1) understand the neighbors detection method, and 2) tocheck detected neighbors for one particular node (focus).

Value

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

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 <- knight(nodes, focus, degree = 2)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)# Higher degree of neighborhood ----neighbors <- knight(nodes, focus, degree = 3)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)  # Directed (default orientation) ----neighbors <- knight(nodes, focus, degree = 3, directed = TRUE)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)  # Directed (reverse orientation) ----neighbors <- knight(nodes, focus, degree = 3, directed = TRUE,                     reverse = TRUE)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)

Find neighbors according to knight left movement

Description

For one node (argumentfocus), finds neighbors among a list of nodesaccording to the knight left movement.This movement is derived from theknight() method.

The detection of neighbors using this method can only work withtwo-dimensional sampling (bothtransects andquadrats).For sampling of typetransects-only orquadrats-only,please use the functionsfool() orpawn(), respectively.

Usage

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

Arguments

Details

This function is internally called bycreate_edge_list() but it can bedirectly used to 1) understand the neighbors detection method, and 2) tocheck detected neighbors for one particular node (focus).

Value

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

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 <- knight_left(nodes, focus, degree = 2)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)# Higher degree of neighborhood ----neighbors <- knight_left(nodes, focus, degree = 3)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)  # Directed (default orientation) ----neighbors <- knight_left(nodes, focus, degree = 3, directed = TRUE)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)  # Directed (reverse orientation) ----neighbors <- knight_left(nodes, focus, degree = 3, directed = TRUE,                          reverse = TRUE)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)

Find neighbors according to knight right movement

Description

For one node (argumentfocus), finds neighbors among a list of nodesaccording to the knight right movement.This movement is derived from theknight() method.

The detection of neighbors using this method can only work withtwo-dimensional sampling (bothtransects andquadrats).For sampling of typetransects-only orquadrats-only,please use the functionsfool() orpawn(), respectively.

Usage

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

Arguments

Details

This function is internally called bycreate_edge_list() but it can bedirectly used to 1) understand the neighbors detection method, and 2) tocheck detected neighbors for one particular node (focus).

Value

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

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 <- knight_right(nodes, focus, degree = 2)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)# Higher degree of neighborhood ----neighbors <- knight_right(nodes, focus, degree = 3)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)  # Directed (default orientation) ----neighbors <- knight_right(nodes, focus, degree = 3, directed = TRUE)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)  # Directed (reverse orientation) ----neighbors <- knight_right(nodes, focus, degree = 3, directed = TRUE,                           reverse = TRUE)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)

Convert an connectivity matrix to an edge list

Description

Converts a connectivity matrix to an edge list. This function allows tocreate the same edge list as the one obtained withcreate_edge_list().

Usage

matrix_to_edge_list(x, all = FALSE)

Arguments

Value

Adata.frame with two (or three) columns:

• from: label of one of the two nodes of the edge

• to: label of the other node of the edge

• edge: 0 (no edge) or 1 (edge). This column is returned only ifall = TRUE.

Examples

library("chessboard")# Two-dimensional sampling ----sites_infos <- expand.grid("transect" = 1:3, "quadrat" = 1:5)sites_infosnodes <- create_node_labels(data     = sites_infos,                             transect = "transect",                             quadrat  = "quadrat")edges <- create_edge_list(nodes, method = "pawn", directed = TRUE)conn_matrix <- connectivity_matrix(edges)# Convert back to edge list ----new_edges <- matrix_to_edge_list(conn_matrix)new_edges# Check ----identical(edges, new_edges)

Create a nodes-by-edges matrix

Description

Creates a nodes-by-edges matrix that will be used byaem() of the packageadespatial. This function creates the same output asaem.build.binary()of the packageadespatial but works in a different way: it's only based onnode labels (not on coordinates). Also, this function adds labels to nodesand edges.

Usage

nodes_by_edges_matrix(edges)

Arguments

Value

A list of two elements:

• se.mat: the nodes-by-edges matrix of dimensions⁠n x k⁠, wheren isthe number of nodes andk the number of edges (including the edgebetween the fictitious origin and the first site);

• edges: adata.frame of edge list.

Examples

library("chessboard")# Two-dimensional sampling ----sites_infos <- expand.grid("transect" = 1:3, "quadrat" = 1:5)sites_infosnodes <- create_node_labels(data     = sites_infos,                             transect = "transect",                             quadrat  = "quadrat")edges <- create_edge_list(nodes, method = "pawn", directed = TRUE)# Create nodes-by-edges matrix ----nodes_by_edges_matrix(edges)

Find neighbors according to pawn movement

Description

For one node (argumentfocus), finds neighbors among a list of nodesaccording to the fool movement.This movement is orthogonal to thefool() function. The pawn can only movevertically, i.e. through atransect.

The detection of neighbors using the fool method can work withtwo-dimensional sampling (bothtransects andquadrats) andone-dimensional sampling of typequadrats-only.For sampling of typetransects-only, please use the functionfool().

Usage

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

Arguments

Details

This function is internally called bycreate_edge_list() but it can bedirectly used to 1) understand the neighbors detection method, and 2) tocheck detected neighbors for one particular node (focus).

Value

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

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)

Find neighbors according to queen movement

Description

For one node (argumentfocus), finds neighbors among a list of nodesaccording to the queen movement.This movement is derived from the chess game. The queen is a combination ofthebishop() and therook() and can find neighbors horizontally,vertically, and diagonally.

The detection of neighbors using this method can only work withtwo-dimensional sampling (bothtransects andquadrats).For sampling of typetransects-only orquadrats-only,please use the functionsfool() orpawn(), respectively.

Usage

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

Arguments

Details

This function is internally called bycreate_edge_list() but it can bedirectly used to 1) understand the neighbors detection method, and 2) tocheck detected neighbors for one particular node (focus).

Value

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

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 <- queen(nodes, focus)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)# Higher degree of neighborhood ----neighbors <- queen(nodes, focus, degree = 3)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)  # Directed (default orientation) ----neighbors <- queen(nodes, focus, degree = 3, directed = TRUE)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)  # Directed (reverse orientation) ----neighbors <- queen(nodes, focus, degree = 3, directed = TRUE, reverse = TRUE)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)

Find neighbors according to rook movement

Description

For one node (argumentfocus), finds neighbors among a list of nodesaccording to the rook movement.This movement is derived from the chess game. The rook can move horizontallyand vertically. It's a combination of thepawn() and thefool()functions.

The detection of neighbors using this method can only work withtwo-dimensional sampling (bothtransects andquadrats).For sampling of typetransects-only orquadrats-only,please use the functionsfool() orpawn(), respectively.

Usage

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

Arguments

Details

This function is internally called bycreate_edge_list() but it can bedirectly used to 1) understand the neighbors detection method, and 2) tocheck detected neighbors for one particular node (focus).

Value

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

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 <- rook(nodes, focus)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)# Higher degree of neighborhood ----neighbors <- rook(nodes, focus, degree = 3)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)  # Directed (default orientation) ----neighbors <- rook(nodes, focus, degree = 3, directed = TRUE)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)  # Directed (reverse orientation) ----neighbors <- rook(nodes, focus, degree = 3, directed = TRUE, reverse = TRUE)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)

Create a spatial weights matrix

Description

Creates a spatial weights matrix by multiplying an adjacency (connectivity)matrix (seeconnectivity_matrix()) and an edges weights matrix (seeedges_weights_matrix()). Resulting spatial weights equal to 0 will bereplaced by⁠4 x max(w)⁠, wheremax(w) is the maximal weight in thematrix.

Usage

spatial_weights_matrix(x, y)

Arguments

Value

A spatial weightsmatrix of dimensions⁠n x n⁠, wheren is thenumber of nodes (sites).

Examples

# Import Adour sites ----path_to_file <- system.file("extdata", "adour_survey_sampling.csv",                             package = "chessboard")adour_sites <- read.csv(path_to_file)# Select the 15 first sites ----adour_sites <- adour_sites[1:15, ]# Create node labels ----adour_sites <- create_node_labels(adour_sites,                                   location = "location",                                   transect = "transect",                                   quadrat  = "quadrat")# Create edges based on the pawn move (directed network) ----adour_edges <- create_edge_list(adour_sites, method = "pawn",                                 directed = TRUE)# Get connectivity matrix ----adour_adjacency <- connectivity_matrix(adour_edges)# Convert sites to sf object (POINTS) ----adour_sites_sf <- sf::st_as_sf(adour_sites,                                coords = c("longitude", "latitude"),                               crs = "epsg:2154")# Compute distances between pairs of sites along the Adour river ----adour_dists <- distance_euclidean(adour_sites_sf)# Create Edges weights matrix ----adour_weights <- edges_weights_matrix(adour_dists)# Create Spatial weights matrix ----spatial_weights_matrix(adour_adjacency, adour_weights)

Find neighbors according to wizard movement

Description

For one node (argumentfocus), finds neighbors among a list of nodesaccording to the wizard movement.This movement is a combination of thequeen() and theknight() piecesfrom the chess game and can move in all directions.

The detection of neighbors using this method can only work withtwo-dimensional sampling (bothtransects andquadrats).For sampling of typetransects-only orquadrats-only,please use the functionsfool() orpawn(), respectively.

Usage

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

Arguments

Details

This function is internally called bycreate_edge_list() but it can bedirectly used to 1) understand the neighbors detection method, and 2) tocheck detected neighbors for one particular node (focus).

Value

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

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 <- wizard(nodes, focus)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)# Higher degree of neighborhood ----neighbors <- wizard(nodes, focus, degree = 3)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)  # Directed (default orientation) ----neighbors <- wizard(nodes, focus, degree = 3, directed = TRUE)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)  # Directed (reverse orientation) ----neighbors <- wizard(nodes, focus, degree = 3, directed = TRUE,                     reverse = TRUE)gg_chessboard(nodes) +  geom_node(nodes, focus) +  geom_neighbors(nodes, neighbors)