Visualization tools"
In chessboard: Create Network Connections Based on Chess Moves

knitr::opts_chunk$set(collapse  = TRUE,
                      comment   = "#>",
                      out.width = "50%",
                      dpi       = 96,
                      fig.align = "center")

The package chessboard provides some plotting functions to:

visualize data on a chessboard
visualize matrices
visualize data on a map

All these functions have been implemented using the ggplot2 package, meaning that they are highly customizable.

# Setup ----
library("chessboard")
library("ggplot2")

To illustrate these plotting functions, let's import the data provided by chessboard (see the Get started vignette for a full description).

# Location of the data ----
path_to_file <- system.file("extdata", "adour_survey_sampling.csv", 
                            package = "chessboard")

# Read the data ----
sampling  <- read.csv(path_to_file)

head(sampling)

For the purpose of this vignette, let's subset the first location.

# Subset location 1 ----
sampling <- sampling[sampling$"location" == 1, ]

sampling

The sampling is a grid of dimensions 3 transects x 5 quadrats.

When working with chessboard, the first step is to create node labels with the function create_node_labels().

# Create node labels ----
nodes <- create_node_labels(data     = sampling,
                            location = "location",
                            transect = "transect", 
                            quadrat  = "quadrat")

nodes

Visualizing chessboard

gg_chessboard

The first plotting function to use is gg_chessboard(): it will plot the (spatial) sampling as a chessboard, i.e. two-dimension grid where the x-axis is the transect and the y-axis is the quadrat.

# Plot the sampling as a chessboard ----
gg_chessboard(nodes)

geom_node

On this chessboard, we can locate one specific node using the function geom_node().

# Locate one node ----
gg_chessboard(nodes) +
  geom_node(nodes, focus = "2-3")

We can call the function geom_node() several times to emphase various nodes.

# Locate various nodes ----
gg_chessboard(nodes) +
  geom_node(nodes, focus = "2-3") +
  geom_node(nodes, focus = "1-5") +
  geom_node(nodes, focus = "3-1")

geom_neighbors

As mentioned in the Get started vignette, we can test the neighbors detection of a specific node by using the functions pawn(), fool(), rook(), etc.

Let's apply the function rook() on the node 2-3.

# Neighbors detection ----
nb_rook <- rook(nodes, focus = "2-3")

nb_rook

Let's visualize these neighbors on a chessboard by using the function geom_neighbors().

# Locate neighbors ----
gg_chessboard(nodes) +
  geom_node(nodes, focus = "2-3") +
  geom_neighbors(nodes, neighbors = nb_rook)

geom_edges

Instead of plotting the neighbors, we can directly plot the edges using the function geom_edges(). This function has the advantage to show the direction of the edges.

# Locate neighbors ----
gg_chessboard(nodes) +
  geom_edges(nodes, focus = "2-3", neighbors = nb_rook) +
  geom_node(nodes, focus = "2-3")

Now let's call the function bishop() to create a second edge list.

# Neighbors detection ----
nb_bishop <- bishop(nodes, focus = "2-3")

nb_bishop

As for the function geom_node(), we can call the functions geom_edges() and geom_neighbors() several times.

# Locate neighbors ----
gg_chessboard(nodes) +
  geom_edges(nodes, focus = "2-3", neighbors = nb_rook) +
  geom_edges(nodes, focus = "2-3", neighbors = nb_bishop) +
  geom_neighbors(nodes, neighbors = nb_rook) +
  geom_neighbors(nodes, neighbors = nb_bishop) +
  geom_node(nodes, focus = "2-3")

Plotting matrices

These two previous moves (rook and bishop) combined together are equivalent to the queen. For the rest of the vignette let's create the edge list using the queen move.

# Edges list ----
edges <- create_edge_list(nodes, method = "queen")

head(edges)

From this edge list, we can build the associated connectivity matrix with the function connectivity_matrix().

# Connectivity matrix ----
mat <- connectivity_matrix(edges)

mat

A better way to visualize any kind of matrices, is to call the function gg_matrix().

# Visualize matrix ----
gg_matrix(mat)

Mapping edges

Now, let's go back into a spatial world. First let's convert our sampling into an sf object.

# Convert sampling to sf object ----
nodes_sf <- sf::st_as_sf(nodes, 
                         coords = c("longitude", "latitude"),
                         crs = "epsg:2154")

nodes_sf

To convert our edge list into a spatial object, we can use the function edges_to_sf().

# Convert edges to sf object ----
edges_sf <- edges_to_sf(edges, nodes_sf)

edges_sf

The result is a collection of LINESTRINGS, i.e. a collection of spatial lines where each line is an edge defined in the coordinate system (CRS) of the sampling.

Let's use ggplot2 and sf to map the nodes and the edges.

# Map of nodes and edges ----
ggplot() +
  geom_sf(data = edges_sf) +
  geom_sf(data = nodes_sf, size = 12) +
  theme_light()

Finally, let's add the node labels on this map.

# Map of nodes and edges ----
ggplot() +
  geom_sf(data = edges_sf) +
  geom_sf(data = nodes_sf, size = 12) +
  geom_sf_text(data = nodes_sf, aes(label = node), 
               color = "white", fontface = "bold",
               family = "mono") +
  theme_light()