---
title: "Getting started with RGraphSpace"
author: "Sysbiolab - Bioinformatics and Systems Biology Laboratory"
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
  )
```

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

# Overview

*RGraphSpace* is an R package that generates *ggplot2* graphics for *igraph* objects [@Nepusz2006], scaling nodes and edges to a unit space. The package implements new *ggplot2* geometric prototypes [@Wickham2016], optimized for representing large networks. This enables extensive customization of aesthetics and visual style, including colors, shapes, and line types. For extended documentation and use cases, see the [online tutorials](https://sysbiolab.github.io/RGraphSpace/).

# Quick start

This section will create a toy `igraph` object to demonstrate the basic *RGraphSpace* workflow. The input data is configured manually to ensure that users can easily view the basic graph attributes. We will use the igraph's `make_star()` function to create a simple star-like graph and then the `V()` and `E()` functions to set attributes for vertices and edges, respectively. *RGraphSpace* will require that all vertices have `x`, `y`, and `name` attributes.

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

```{r Toy igraph - 1, eval=TRUE, message=FALSE, results=FALSE}
# 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)
## [1] TRUE

# Check graph size
vcount(gtoy1)
## [1] 5
ecount(gtoy1)
## [1] 4

# 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, out.width="100%"}
# Plot the 'gtoy1' using standard R graphics
plot(gtoy1)
```

```{r Toy igraph - 3, eval=TRUE, message=FALSE, out.width="80%"}
# Plot the 'gtoy1' using RGraphSpace
plotGraphSpace(gtoy1, add.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 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 color (Hexadecimal or color name)
V(gtoy1)$nodeColor <- c("red", "#00ad39", "grey80", "lightblue", "cyan")

# 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 labels)
V(gtoy1)$nodeLabel <- c("V1", "V2", "V3", "V4", NA)

# Node label size (in pts)
V(gtoy1)$nodeLabelSize <- 8

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

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

## 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 width (as in 'lwd' standard graphics; see 'help(gpar)')
E(gtoy1)$edgeLineWidth <- 0.8

# Edge color (Hexadecimal or color name)
E(gtoy1)$edgeLineColor <- c("red","green","blue","black")

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

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

## 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 = "<-|", 
E(gtoy1)$arrowType <- 1
# Note: in undirected graphs, this attribute overrides 
# the edge's orientation in the edge list
```

... and plot the updated `igraph` object. The most straightforward call simply passes an `igraph` directly to the wrapper `plotGraphSpace()` function.
 
```{r A shortcut for RGraphSpace, eval=TRUE, message=FALSE, out.width="80%"}
# Plot the updated 'gtoy1' using RGraphSpace
plotGraphSpace(gtoy1, add.labels = TRUE)
```

```{r, eval=FALSE, message=FALSE, echo=FALSE, include=FALSE, purl=FALSE}
# p <- plotGraphSpace(gtoy1, add.labels = TRUE)
# ggsave(filename = "./vignettes/cards/building_gspace.png", height=4, width=4,
#   units="in", device="png", dpi=200, plot = p)
```


# Passing graphs to *geoms*

Alternatively, the `igraph` object can be transformed into a `GraphSpace` container and passed to the underlying `geoms`:

```{r Using geoms, eval=TRUE, message=FALSE, out.width="80%"}
gs <- GraphSpace(gtoy1)
gs <- normalizeGraphSpace(gs)
ggplot(gs) + 
  geom_edgespace() +
  geom_nodespace() +
  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