---
title: "Getting started with RGraphSpace"
author: "Sysbiolab Team"
date: "`r Sys.Date()`"
bibliography: bibliography.bib
output: 
  html_document:
    theme: cerulean
    self_contained: yes
    toc: true
    toc_float: true
    toc_depth: 2
    css: custom.css
vignette: >
  %\VignetteIndexEntry{RGraphSpace: igraph to ggplot2 graphics}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE, purl=FALSE}
knitr::opts_chunk$set(
  echo = TRUE,
  collapse = TRUE,
  comment = "#>",
  fig.align = "center",
  fig.width = 7,
  fig.height = 5,
  out.width="90%"
  )
```

<br/>
**Package**: RGraphSpace `r packageVersion('RGraphSpace')`

```{r clipboard, echo=FALSE, results='asis'}
if (!identical(Sys.getenv("IN_PKGDOWN"), "true")) {
  cat('<script src="clipboard.js"></script>')
}
```

# Overview

*RGraphSpace* is an R package that generates *ggplot2* graphics [@Wickham2016] for *igraph* objects [@Nepusz2006] within a normalized coordinate space. This is particularly useful when graph elements must be spatially aligned with reference frames. For comprehensive documentation and use cases, see the [online tutorials](https://sysbiolab.github.io/RGraphSpace/).

# Quick start

To get started, we load a toy `igraph` and plot it.

```{r Load packages for quick start, eval=TRUE, message=FALSE}
#--- Load required packages
library("RGraphSpace")
library("igraph")
library("ggplot2")
```

```{r Quick start - 1, eval=TRUE, message=TRUE}
# Load the bundled toy igraph object
data("gtoy1", package = "RGraphSpace")

# The most direct call: pass an igraph to plotGraphSpace()
plotGraphSpace(gtoy1, node.labels = TRUE)
```

Next, we build this toy `igraph` from scratch to demonstrate the vertex and edge attributes that *RGraphSpace* parses automatically. This shows exactly what the package expects as input. We use `igraph`'s `make_star()` function with `V()` and `E()` to assign attributes.

*RGraphSpace* requires that every vertex carries `x`, `y`, and `name` attributes. If your graph has no pre-existing spatial coordinates, you can supply any *igraph* layout matrix directly via the `layout` argument of `GraphSpace()`, which assigns coordinates internally.

```{r Layout, eval=TRUE, message=FALSE}
# If your graph has no spatial coordinates, pass a layout directly:
set.seed(42)
GraphSpace(gtoy1, layout = igraph::layout_with_fr(gtoy1))
```

```{r Toy igraph - 1, eval=TRUE, message=TRUE}
# Make a 'toy' igraph with 5 nodes and 4 edges;
# ..either a directed or undirected graph
gtoy1 <- make_star(5, mode = "out")

# Check whether the graph is directed or not
is_directed(gtoy1)

# Check graph size
vcount(gtoy1)

ecount(gtoy1)

# Assign 'x' and 'y' coordinates to each vertex;
# ..this can be an arbitrary unit in (-Inf, +Inf)
V(gtoy1)$x <- c(0, 2, -2, -4, -8)
V(gtoy1)$y <- c(0, 0,  2, -4,  0)

# Assign a name to each vertex
V(gtoy1)$name <- paste0("n", 1:5)
```

```{r Toy igraph - 2, eval=TRUE, message=FALSE}
# Plot the reconstructed 'gtoy1' using RGraphSpace
plotGraphSpace(gtoy1, node.labels = TRUE)
```

# *RGraphSpace* attributes

Next, we list all vertex and edge attributes that can be passed to *RGraphSpace* methods.

## Vertex attributes

```{r Node attributes, eval=TRUE, message=FALSE}
# Node color (Hexadecimal or color name)
V(gtoy1)$nodeColor <- c("red", "#00ad39", "grey80", "lightblue", "cyan")

# Node transparency (in [0,1])
V(gtoy1)$nodeAlpha <- 1

# Node size (numeric in [0, 100], as '%' of the plot space)
V(gtoy1)$nodeSize <- c(8, 5, 5, 10, 5)

# Node shape (integer code between 0 and 25; see 'help(points)')
V(gtoy1)$nodeShape <- c(21, 22, 23, 24, 25)

# Node line width (as in 'lwd' standard graphics; see 'help(gpar)')
V(gtoy1)$nodeLineWidth <- 1

# Node line color (Hexadecimal or color name)
V(gtoy1)$nodeLineColor <- "grey20"

# Node labels ('NA' will omit the label)
V(gtoy1)$nodeLabel <- c("V1", "V2", "V3", "V4", NA)

# Node label size (in mm)
V(gtoy1)$nodeLabelSize <- 3

# Node label color (Hexadecimal or color name)
V(gtoy1)$nodeLabelColor <- "black"
```

## Edge attributes

Given a list of edges, *RGraphSpace* represents only one edge for each pair of connected vertices. If there are multiple edges connecting the same node pair, it will display the attributes of the first occurrence in the data.

```{r Edge attributes - 1, eval=TRUE, message=FALSE}
# Edge color (Hexadecimal or color name)
E(gtoy1)$edgeColor <- c("red","green","blue","black")

# Edge transparency (in [0,1])
E(gtoy1)$edgeAlpha <- 1

# Edge line width (as in 'lwd' standard graphics; see 'help(gpar)')
E(gtoy1)$edgeLineWidth <- 0.8

# Edge line type (as in 'lty' standard graphics; see 'help(gpar)')
E(gtoy1)$edgeLineType <- c("solid", "11", "dashed", "2124")
```

Note: `edgeLineColor` is deprecated as of version 1.4.3 and replaced by `edgeColor`.

## Arrowhead attributes

**Arrowhead in directed graphs**: By default, an arrow will be drawn for each edge according to its left-to-right orientation in the edge list (*e.g.* `A -> B`). If there are mutual connections, the package will recode the mutual edges to represent a bidirectional flow.

```{r Edge attributes - 2, eval=TRUE, message=FALSE}
# Arrowhead types in directed graphs
## Integer or character code:
## 0 = "---", 1 = "-->", -1 = "--|"
E(gtoy1)$arrowType <- 1
``` 

**Arrowhead in undirected graphs**: By default, no arrow will be drawn for undirected graphs. However, arrowheads may be assigned according to the coding below.

```{r Edge attributes - 3, eval=TRUE, message=FALSE}
# Arrowhead types in undirected graphs
## Integer or character code:
##  0 = "---"
##  1 = "-->",  2 = "<--",  3 = "<->",  4 = "|->"
## -1 = "--|", -2 = "|--", -3 = "|-|", -4 = "<-|"
gtoy1_undir <- igraph::as_undirected(gtoy1, edge.attr.comb = "first")
E(gtoy1_undir)$arrowType <- 1
# Note: in undirected graphs, this attribute overrides
# the edge's orientation in the edge list and adds arrowheads
# to edges that would otherwise be drawn without any
```

... and plot the fully attributed `gtoy1` object.
 
```{r A shortcut for RGraphSpace, eval=TRUE, message=FALSE}
# Plot the fully attributed 'gtoy1'
plotGraphSpace(gtoy1, node.labels = TRUE)
```

```{r, eval=FALSE, message=FALSE, echo=FALSE, include=FALSE, purl=FALSE}
# V(gtoy1)$nodeLabel <- c("V1", "V2", "V3", "V4", "V5")
# save(gtoy1, file = "./data/gtoy1.RData")
# tools::resaveRdaFiles(paths = "./data/gtoy1.RData")
```

# Passing graphs to *geoms*

Alternatively, an `igraph` can be converted to a `GraphSpace` object and passed directly to *ggplot2* geoms. This gives full access to the *ggplot2* layer system for combining graph elements with other plot types.

```{r Using geoms - 1, eval=TRUE, message=TRUE}
# Load the toy graph used in the previous example
data("gtoy1", package = "RGraphSpace")

# Create a GraphSpace object
gs <- GraphSpace(gtoy1)

# Normalize the coordinates
gs <- normalizeGraphSpace(gs)

gs
```

`normalizeGraphSpace()` maps all vertex coordinates to a `[0, 1]` unit interval and computes the per-node clipping offsets that allow `geom_edgespace()` to terminate edges precisely at node boundaries. This step is handled automatically when you use `plotGraphSpace()`, but must be called explicitly when building a plot layer by layer.

```{r Using geoms - 2, eval=TRUE, message=FALSE}
# Build a layered ggplot2 graph
# geom_edgespace() draws edges; geom_nodespace() draws nodes
# aes(label = nodeLabel) maps the 'nodeLabel' vertex attribute to node labels
ggplot(gs) + 
  geom_edgespace() + 
  geom_nodespace(aes(label = nodeLabel)) + 
  theme_gspace_coords(is_norm = TRUE)
```

# Online tutorials

For detailed integration with the *ggplot2* ecosystem, see the online documentation available at:

* https://sysbiolab.github.io/RGraphSpace/

# Other examples

Vignettes illustrating how *RGraphSpace* can be used in combination with *PathwaySpace* to project network signals.

* https://sysbiolab.github.io/PathwaySpace/

# Citation

If you use *RGraphSpace*, please cite:

* Sysbiolab Team. "RGraphSpace: A lightweight interface between igraph and ggplot2 graphics." R package, 2023. Doi: 10.32614/CRAN.package.RGraphSpace

# Session information
```{r label='Session information', eval=TRUE, echo=FALSE}
sessionInfo()
```


# References

