Author: B. Thieurmel - DataStorm
Date: 2018-06-14

# Introduction to visNetwork

#### B. Thieurmel - DataStorm

#### 2018-06-14

visNetwork is a R package for network visualization, using vis.js javascript library (http://visjs.org). All the remarks and bugs returns are welcome on github : https://github.com/datastorm-open/visNetwork.

## Minimal example

visNetwork needs at least two informations :

- a nodes data.frame, with id column
- a edges data.frame, with from and to columns

    require(visNetwork, quietly = TRUE)
    # minimal example
    nodes <- data.frame(id = 1:3)
    edges <- data.frame(from = c(1,2), to = c(1,3))
    visNetwork(nodes, edges, width = "100%")

## Find help

Besides the help R functions, a vignette is available, and you can access and read the full javascript API :

    visDocumentation()
    vignette("Introduction-to-visNetwork") # with CRAN version
    # shiny ?
    shiny::runApp(system.file("shiny", package = "visNetwork"))

Or visit our online help page : http://datastorm-open.github.io/visNetwork/.

## Simple individual nodes and edges customization

- Adding more variables on nodes data.frame. See visNodes for available options.

    nodes <- data.frame(id = 1:10,
                        label = paste("Node", 1:10),                                 # add labels on nodes
                        group = c("GrA", "GrB"),                                     # add groups on nodes
                        value = 1:10,                                                # size adding value
                        shape = c("square", "triangle", "box", "circle", "dot", "star",
                        "ellipse", "database", "text", "diamond"),                   # control shape of nodes
                        title = paste0("<p><b>", 1:10,"</b><br>Node !</p>"),         # tooltip (html or character)
                        color = c("darkred", "grey", "orange", "darkblue", "purple"),# color
                        shadow = c(FALSE, TRUE, FALSE, TRUE, TRUE))                  # shadow

    head(nodes)

    ##   id  label group value    shape                     title    color shadow
    ## 1  1 Node 1   GrA     1   square <p><b>1</b><br>Node !</p>  darkred  FALSE
    ## 2  2 Node 2   GrB     2 triangle <p><b>2</b><br>Node !</p>     grey   TRUE
    ## 3  3 Node 3   GrA     3      box <p><b>3</b><br>Node !</p>   orange  FALSE
    ## 4  4 Node 4   GrB     4   circle <p><b>4</b><br>Node !</p> darkblue   TRUE
    ## 5  5 Node 5   GrA     5      dot <p><b>5</b><br>Node !</p>   purple   TRUE
    ## 6  6 Node 6   GrB     6     star <p><b>6</b><br>Node !</p>  darkred  FALSE

- Adding more variables on edges data.frame. See visEdges for available options.

    edges <- data.frame(from = sample(1:10, 8), to = sample(1:10, 8),
                        label = paste("Edge", 1:8),                                 # add labels on edges
                        length = c(100,500),                                        # length
                        arrows = c("to", "from", "middle", "middle;to"),            # arrows
                        dashes = c(TRUE, FALSE),                                    # dashes
                        title = paste("Edge", 1:8),                                 # tooltip (html or character)
                        smooth = c(FALSE, TRUE),                                    # smooth
                        shadow = c(FALSE, TRUE, FALSE, TRUE))                       # shadow
    head(edges)

    ##   from to  label length    arrows dashes  title smooth shadow
    ## 1    6  2 Edge 1    100        to   TRUE Edge 1  FALSE  FALSE
    ## 2    2  6 Edge 2    500      from  FALSE Edge 2   TRUE   TRUE
    ## 3    8  5 Edge 3    100    middle   TRUE Edge 3  FALSE  FALSE
    ## 4    7  4 Edge 4    500 middle;to  FALSE Edge 4   TRUE   TRUE
    ## 5    4  7 Edge 5    100        to   TRUE Edge 5  FALSE  FALSE
    ## 6    9  3 Edge 6    500      from  FALSE Edge 6   TRUE   TRUE

    visNetwork(nodes, edges, width = "100%")

## Global nodes/edges configuration

- Set global options for nodes and edges using visNodes and visEdges, and use options per group using visGroups.

    nodes <- data.frame(id = 1:5, group = c(rep("A", 2), rep("B", 3)))
    edges <- data.frame(from = c(2,5,3,3), to = c(1,2,4,2))

    visNetwork(nodes, edges, width = "100%") %>%
      visNodes(shape = "square") %>%                        # square for all nodes
      visEdges(arrows ="to") %>%                            # arrow "to" for all edges
      visGroups(groupname = "A", color = "darkblue") %>%    # darkblue for group "A"
      visGroups(groupname = "B", color = "red")             # red for group "B"

# Network configuration

Configuration options are available in visOptions, visInteraction, visLayout, visHierarchicalLayout, visPhysics :

## Example Data

    nb <- 10
    nodes <- data.frame(id = 1:nb, label = paste("Label", 1:nb),
     group = sample(LETTERS[1:3], nb, replace = TRUE), value = 1:nb,
     title = paste0("<p>", 1:nb,"<br>Tooltip !</p>"), stringsAsFactors = FALSE)

    edges <- data.frame(from = trunc(runif(nb)*(nb-1))+1,
     to = trunc(runif(nb)*(nb-1))+1,
     value = rnorm(nb, 10), label = paste("Edge", 1:nb),
     title = paste0("<p>", 1:nb,"<br>Edge Tooltip !</p>"))

## Add legend

New feature in visNetwork_0.1.2 : you can now add more custom legend on nodes / edges ! Default on groups (like in previous versions) :

    visNetwork(nodes, edges, width = "100%") %>% visLegend()

Or passing data :

    visNetwork(nodes, edges, width = "100%") %>%
      visLegend(useGroups = FALSE, addNodes = data.frame(label = "Nodes", shape = "circle"),
                addEdges = data.frame(label = "link", color = "black"))

## Highlight nearest

You can highlight nearest nodes and edges clicking on a node with highlightNearest option :

    visNetwork(nodes, edges, width = "100%") %>%
      visOptions(highlightNearest = TRUE)

It’s now possible to control the degree of depth (visNetwork >= 0.1.2) :

    visNetwork(nodes, edges, width = "100%") %>%
      visOptions(highlightNearest = list(enabled =TRUE, degree = 2))

## Select by node id

You can also select nodes by id/label with a list with nodesIdSelection :

    visNetwork(nodes, edges, width = "100%") %>%
      visOptions(highlightNearest = TRUE, nodesIdSelection = TRUE)

## Select by a column

New feature in visNetwork_0.1.2 : select some nodes by the values of a column using selectedBy option :

    # can be the column you want
    nodes$sel <- sample(c("sel1", "sel2"), nrow(nodes), replace = TRUE)
    visNetwork(nodes, edges, width = "100%") %>%
     visOptions(selectedBy = "sel")

## Directed Network

    visNetwork(nodes, edges, width = "100%") %>%
      visEdges(arrows = 'from')

## Custom navigation

vis.js propose some navigation tools :

    visNetwork(nodes, edges, width = "100%") %>%
      visInteraction(navigationButtons = TRUE)

## Data Manipulation

And some data manipulation tools :

    visNetwork(nodes, edges, width = "100%") %>%
      visOptions(manipulation = TRUE)

## Hierarchical Layout

You can use and control hierarchical layout with visHierarchicalLayout and visLayout :

    nodes <- data.frame(id = 1:7)

    edges <- data.frame(
      from = c(1,2,2,2,3,3),
      to = c(2,3,4,5,6,7)
    )

    visNetwork(nodes, edges, width = "100%") %>%
      visEdges(arrows = "from") %>%
      visHierarchicalLayout()

    # same as   visLayout(hierarchical = TRUE)

    visNetwork(nodes, edges, width = "100%") %>%
      visEdges(arrows = "from") %>%
      visHierarchicalLayout(direction = "LR")

## Freeze network

    visNetwork(nodes, edges, width = "100%") %>%
      visInteraction(dragNodes = FALSE, dragView = FALSE, zoomView = FALSE)

## Use font awesome icons in your network

You can use Font Awesome icons using groups or nodes options. Font Awesome library (http://fortawesome.github.io/Font-Awesome/) is not part of dependencies. use addFontAwesome() if needed.

    nodes <- data.frame(id = 1:3, group = c("B", "A", "B"))
    edges <- data.frame(from = c(1,2), to = c(2,3))

    visNetwork(nodes, edges, width = "100%") %>%
      visGroups(groupname = "A", shape = "icon", icon = list(code = "f0c0", size = 75)) %>%
      visGroups(groupname = "B", shape = "icon", icon = list(code = "f007", color = "red")) %>%
      visLegend() %>%
      addFontAwesome()

# Additional features

## Visualize rpart object

New visTree function allows to visualize and customize a rpart classification and regression tree. Have a look to visTreeEditor to edity and get back network, or to visTreeModuleServer to use custom tree module in R.

    library(rpart)
    # Complex tree
    data("solder")
    res <- rpart(Opening~., data = solder, control = rpart.control(cp = 0.00005))
    visTree(res, height = "800px", nodesPopSize = TRUE, minNodeSize = 10, maxNodeSize = 30)

## Use in Shiny

With visNetworkOutput and renderVisNetwork. Using with shiny, and enabled options nodesIdSelection, you can access to new input with current selection value. Morevoer, you can do a lot of things with visNetworkProxy

    output$mynetwork <- renderVisNetwork({... visOptions(nodesIdSelection = TRUE)}) # created input$mynetwork_selected

And with selectedBy, new input input$mynetwork_selectedBy.

## Physics, tooltip, events,

You can also control :

- physics of network : visPhysics
- events : visEvents

## Export

    network <- visNetwork(nodes, edges, width = "100%")
    visSave(network, file = "network.html")

## Use DOT language data

    visNetwork(dot = 'dinetwork {1 -> 1 -> 2; 2 -> 3; 2 -- 4; 2 -> 1 }', width = "100%")

## Use gephi json export file

    # don't run here
    visNetwork(gephi = 'WorldCup2014.json')