# Introduction to visNetwork

#### B. Thieurmel - DataKnowledge

#### 2016-01-31

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/DataKnowledge/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://dataknowledge.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    1  9 Edge 1    100        to   TRUE Edge 1  FALSE  FALSE
    ## 2    2  5 Edge 2    500      from  FALSE Edge 2   TRUE   TRUE
    ## 3    5  6 Edge 3    100    middle   TRUE Edge 3  FALSE  FALSE
    ## 4    9  8 Edge 4    500 middle;to  FALSE Edge 4   TRUE   TRUE
    ## 5    4  2 Edge 5    100        to   TRUE Edge 5  FALSE  FALSE
    ## 6    7  7 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(arrow ="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 :

## 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 :

    # on "authorised" column
    visNetwork(nodes, edges, width = "100%") %>%
     visOptions(selectedBy = "group")

    # or new column
    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(arrow = '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 :

    visNetwork(nodes, edges, width = "100%") %>% visEdges(arrow = "from") %>%
      visHierarchicalLayout() # same as   visLayout(hierarchical = TRUE)

    visNetwork(nodes, edges, width = "100%") %>% visEdges(arrow = "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

## Clustering

Some first (experimental) functions are available :

- visClusteringByColor
- visClusteringByConnection
- visClusteringByHubsize
- visClusteringByGroup
- visClusteringOutliers

You can open clusters by double-clicking, and re-cluster with button.

    nodes <- data.frame(id = 1:10, label = paste("Label", 1:10),
       group = sample(c("A", "B"), 10, replace = TRUE))

    edges <- data.frame(from = c(2,5,10), to = c(1,2,10))

    visNetwork(nodes, edges, legend = TRUE, width = "100%") %>%
       visGroups(groupname = "A", color = "red", shape = "square") %>%
       visGroups(groupname = "B", color = "yellow", shape = "triangle") %>%
       visClusteringByColor(colors = c("red")) %>%
       visClusteringByGroup(groups = c("B"))

    ## Warning in visNetwork(nodes, edges, legend = TRUE, width = "100%"):
    ## 'legend' and 'legend.width' are deprecated (visNetwork >= 0.1.2). Please
    ## now prefer use visLegend function.

## Use in Shiny

With visNetworkOutput and renderVisNetwork. Using with shiny, and enabled options nodesIdSelection, you can access to new input with current selection value :

    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%")
    htmlwidgets::saveWidget(network, "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')