DiagrammeR v0.9.2

0

Monthly downloads

0th

Percentile

Graph/Network Visualization

Graph and network visualization using tabular data.

Readme

Travis-CI Build Status codecov.io

With the DiagrammeR package you can create, modify, analyze, and visualize network graph diagrams. The output can be incorporated into RMarkdown documents, integrated with Shiny web apps, converted to other graph formats, or exported as PNG, PDF, or SVG files.

It's possible to make the above graph diagram using a combination of DiagrammeR functions strung together with the magrittr %>% pipe:

library(DiagrammeR)

create_random_graph(
  n = 140, m = 100,
  directed = FALSE,
  set_seed = 23) %>%
  join_node_attrs(
    df = get_s_connected_cmpts(.)) %>%
  join_node_attrs(
    df = get_degree_total(.)) %>%
  colorize_node_attrs(
    node_attr_from = sc_component,
    node_attr_to = fillcolor,
    alpha = 80) %>%
  rescale_node_attrs(
    node_attr_from = total_degree,
    to_lower_bound = 0.2,
    to_upper_bound = 1.5,
      node_attr_to = height) %>%
  select_nodes_by_id(
    nodes = get_articulation_points(.)) %>%
  set_node_attrs_ws(
    node_attr = peripheries,
    value = 2) %>%
  set_node_attrs_ws(
    node_attr = penwidth,
    value = 3) %>%
  clear_selection() %>%
  set_node_attr_to_display(
    attr = NULL) %>%
  render_graph()

DiagrammeR's graph functions allow you to create graph objects, modify those graphs, get information from the graphs, create a series of graphs, and do many other useful things.

This functionality makes it possible to generate a network graph with data available in tabular datasets. Two specialized data frames contain node data and attributes (node data frames) and edges with associated edge attributes (edge data frames). Because the attributes are always kept alongside the node and edge definitions (within the graph object itself), we can easily work with them and specify styling attributes to differentiate nodes and edges by size, color, shape, opacity, length, and more.

A Network Graph Example

Let's create a property graph that pertains to contributors to three software projects. This graph has nodes representing people and projects. The attributes name, age, join_date, email, follower_count, following_count, and starred_count are specific to the person nodes while the project, start_date, stars, and language attributes apply to the project nodes. The edges represent the relationships between the people and the project.

The example graph file repository.dgr is available in the extdata/example_graphs_dgr/ directory in the DiagrammeR package (currently, only for the Github version). We can load it into memory by using the open_graph() function, with system.file() to provide the location of the file within the package.

library(DiagrammeR)

# Load in a the small repository graph
graph <-
  open_graph(
    system.file(
      "extdata/example_graphs_dgr/repository.dgr",
      package = "DiagrammeR"))

We can always view the property graph with the render_graph() function.

render_graph(graph, layout = "kk")

Now that the graph is set up, you can create queries with magrittr pipelines to get specific answers from the graph.

Get the average age of all the contributors. Select all nodes of type person (not project). Each node of that type has non-NA age attribute, so, get that attribute as a vector with get_node_attrs_ws() and then calculate the mean with R's mean() function.

graph %>% 
  select_nodes(
    conditions = type == "person") %>%
  get_node_attrs_ws(
    node_attr = age) %>%
  mean()
#> [1] 33.6

We can get the total number of commits to all projects. We know that all edges contain the numerical commits attribute, so, select all edges (select_edges() by itself selects all edges in the graph). After that, get a numeric vector of commits values and then get its sum() (all commits to all projects).

graph %>% 
  select_edges() %>%
  get_edge_attrs_ws(
    edge_attr = commits) %>%
  sum()
#> [1] 5182

Single out the one known as Josh and get his total number of commits as a maintainer and as a contributor. Start by selecting the Josh node with select_nodes(conditions = name == "Josh"). In this graph, we know that all people have an edge to a project and that edge can be of the relationship (rel) type of contributor or maintainer. We can migrate our selection from nodes to outbound edges with trav_out_edges() (and we won't provide a condition, just all the outgoing edges from Josh will be selected). Now we have a selection of 2 edges. Get that vector of commits values with get_edge_attrs_ws() and then calculate the sum(). This is the total number of commits.

graph %>% 
  select_nodes(
    conditions = name == "Josh") %>%
  trav_out_edge() %>%
  get_edge_attrs_ws(
    edge_attr = commits) %>%
  sum()
#> [1] 227

Get the total number of commits from Louisa, just from the maintainer role though. In this case we'll supply a condition in trav_out_edge(). This acts as a filter for the traversal and this means that the selection will be applied to only those edges where the condition is met. Although there is only a single value, we'll still use sum() after get_edge_attrs_ws() (a good practice because we may not know the vector length, especially in big graphs).

graph %>% 
  select_nodes(
    conditions = name == "Louisa") %>%
  trav_out_edge(
    conditions = rel == "maintainer") %>%
  get_edge_attrs_ws(
    edge_attr = commits) %>%
  sum()
#> [1] 236

How do we do something more complex, like, get the names of people in graph above age 32? First, select all person nodes with select_nodes(conditions = type == "person"). Then, follow up with another select_nodes() call specifying age > 32. Importantly, have set_op = "intersect" (giving us the intersection of both selections).

Now that we have the starting selection of nodes we want, we need to get all values of these nodes' name attribute as a character vector. We do this with the get_node_attrs_ws() function. After getting that vector, sort the names alphabetically with the R function sort(). Because we get a named vector, we can use unname() to not show us the names of each vector component.

graph %>% 
  select_nodes(
    conditions = type == "person") %>%
  select_nodes(
    conditions = age > 32,
    set_op = "intersect") %>%
  get_node_attrs_ws(
    node_attr = name) %>%
  sort() %>%
  unname()
#> [1] "Jack"   "Jon"    "Kim"    "Roger"  "Sheryl"

That supercalc project is progressing quite nicely. Let's get the total number of commits from all people to that most interesting project. Start by selecting that project's node and work backwards. Traverse to the edges leading to it with trav_in_edge(). Those edges are from committers and they all contain the commits attribute with numerical values. Get a vector of commits and then get the sum (there are 1676 commits).

graph %>% 
  select_nodes(
    conditions = project == "supercalc") %>%
  trav_in_edge() %>%
  get_edge_attrs_ws(
    edge_attr = commits) %>%
  sum()
#> [1] 1676

Kim is now a contributor to the stringbuildeR project and has made 15 new commits to that project. We can modify the graph to reflect this.

First, add an edge with add_edge(). Note that add_edge() usually relies on node IDs in from and to when creating the new edge. This is almost always inconvenient so we can instead use node labels (we know they are unique in this graph) to compose the edge, setting use_labels = TRUE.

The rel value in add_edge() was set to contributor -- in a property graph we always have values set for all node type and edge rel attributes. We will set another attribute for this edge (commits) by first selecting the edge (it was the last edge made, so we can use select_last_edges_created()), then, use set_edge_attrs_ws() and provide the attribute/value pair. Finally, clear the active selections with clear_selection(). The graph is now changed, have a look.

graph <- 
  graph %>%
  add_edge(
    from = "Kim",
    to = "stringbuildeR",
    rel = "contributor") %>%
  select_last_edges_created() %>%
  set_edge_attrs_ws(
    edge_attr = commits,
    value = 15) %>%
  clear_selection()

render_graph(graph, layout = "kk")

Get all email addresses for contributors (but not maintainers) of the randomizer and supercalc88 projects. With trav_in_edge() we just want the contributer edges/commits. Once on those edges, hop back unconditionally to the people from which the edges originate with trav_out_node(). Get the email values from those selected individuals as a sorted character vector.

graph %>% 
  select_nodes(
    conditions = 
      project == "randomizer" | 
      project == "supercalc") %>%
  trav_in_edge(
    conditions = rel == "contributor") %>%
  trav_out_node() %>%
  get_node_attrs_ws(
    node_attr = email) %>%
  sort() %>%
  unname()
#> [1] "j_2000@ultramail.io"      "josh_ch@megamail.kn"     
#> [3] "kim_3251323@ohhh.ai"      "lhe99@mailing-fun.com"   
#> [5] "roger_that@whalemail.net" "the_simone@a-q-w-o.net"  
#> [7] "the_will@graphymail.com"

Which people have committed to more than one project? This is a matter of node degree. We know that people have edges outward and projects and edges inward. Thus, anybody having an outdegree (number of edges outward) greater than 1 has committed to more than one project. Globally, select nodes with that condition using select_nodes_by_degree("outdeg > 1"). Once getting the name attribute values from that node selection, we can provide a sorted character vector of names.

graph %>%
  select_nodes_by_degree(
    expressions = "outdeg > 1") %>%
  get_node_attrs_ws(
    node_attr = name) %>%
  sort() %>%
  unname()
#> [1] "Josh"   "Kim"    "Louisa"

Installation

DiagrammeR is used in an R environment. If you don't have an R installation, it can be obtained from the Comprehensive R Archive Network (CRAN).

You can install the development version of DiagrammeR from GitHub using the devtools package.

devtools::install_github("rich-iannone/DiagrammeR")

Or, get it from CRAN.

install.packages("DiagrammeR")

If you encounter a bug, have usage questions, or want to share ideas to make this package better, feel free to file an issue.

Code of Conduct

Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

License

MIT © Richard Iannone

Functions in DiagrammeR

Name Description
add_edge Add an edge between nodes in a graph object
add_edge_clone Add a clone of an existing edge to the graph
add_edge_df Add edges from an edge data frame to an existing graph object
add_edges_from_table Add edges and attributes to graph from a table
add_edges_w_string Add one or more edges using a text string
add_forward_edges_ws Add new edges with identical definitions as with a selection of edges
add_balanced_tree Add a balanced tree to the graph
add_cycle Add a cycle of nodes to the graph
DiagrammeR R + mermaid.js
DiagrammeROutput Widget output function for use in Shiny
add_gnp_graph Add a G(n, p) Erdos-Renyi graph
add_graph_action Add a graph action for execution at every transform
add_node Add a node to an existing graph object
add_node_df Add nodes from a node data frame to an existing graph object
add_n_nodes Add one or several unconnected nodes to the graph
add_n_nodes_ws Add a multiple of new nodes with edges to or from one or more selected nodes
add_pa_graph Add a preferential attachment graph
add_path Add a path of nodes to the graph
colorize_edge_attrs Apply colors based on edge attribute values
colorize_node_attrs Apply colors based on node attribute values
add_mathjax Add MathJax-formatted equation text
add_n_node_clones Add one or several clones of an existing node to the graph
add_nodes_from_df_cols Add nodes from distinct values in data frame columns
add_nodes_from_table Add nodes and attributes to graph from a table
add_full_graph Add a fully connected graph
add_global_graph_attrs Add one or more global graph attributes
add_star Add a star of nodes to the graph
cache_edge_attrs Cache edge attributes in the graph
cache_edge_attrs_ws Cache edge attributes (based on a selection of edges) in the graph
count_automorphisms Get the number of automorphisms in the graph
count_mutual_node_pairs Get the number of mutally-connected node pairs
create_edge_df Create an edge data frame
add_grid_2d Add a 2D grid of nodes to the graph
add_grid_3d Add a 3D grid of nodes to the graph
add_prism Add a prism of nodes to the graph
add_reverse_edges_ws Add new edges in the opposite directions of a selection of edges
create_graph Create a graph object
drop_node_attrs Drop a node attribute column
edge_count Get count of all edges or edges with distinct relationship types
cache_node_attrs_ws Cache node attributes (based on a selection of nodes) in the graph
cache_node_count_ws Cache a count of nodes (available in a selection) in the graph
combine_ndfs Combine multiple node data frames
copy_edge_attrs Copy an edge attribute column and set the name
cache_edge_count_ws Cache a count of edges (available in a selection) in the graph
cache_node_attrs Cache node attributes in the graph
count_unconnected_node_pairs Get the number of unconnected node pairs
get_adhesion Get graph adhesion
get_agg_degree_in Get an aggregate value from the indegree of nodes
get_closeness Get closeness centrality values
get_closeness_vitality Get closeness vitality
get_cmty_walktrap Get community membership using the Walktrap method
add_to_series Add graph object to a graph series object
clear_global_graph_attrs Clear any global graph attributes that are set
clear_selection Clear a selection of nodes or edges in a graph
combine_edfs Combine multiple edge data frames into a single edge data frame
combine_graphs Combine two graphs into a single graph
copy_node_attrs Copy a node attribute column and set the name
count_asymmetric_node_pairs Get the number of asymmetrically-connected node pairs
delete_edge Delete an edge from an existing graph object
delete_edges_ws Delete all selected edges in an edge selection
create_complement_graph Create a complement of a graph
create_node_df Create a node data frame
create_random_graph Create a randomized graph
get_common_nbrs Get all common neighbors between two or more nodes
get_edge_attrs_ws Get edge attribute values
get_edge_count_w_multiedge Get count of edge definitions where multiple edges occur
get_graph_actions Get information on any available graph actions
get_graph_from_series Get a graph available in a series
create_series Create a graph series object
create_subgraph_ws Create a subgraph using node/edge selection
do_dfs Use the depth-first search (dfs) algorithm
drop_edge_attrs Drop an edge attribute column
delete_node Delete a node from an existing graph object
delete_nodes_ws Delete all selected nodes in a node selection
export_graph Export a graph to various file formats
from_adj_matrix Create a graph using an adjacency matrix
get_articulation_points Get articulation points
from_igraph Convert an igraph graph to a DiagrammeR one
generate_dot Generate DOT code using a graph object
get_authority_centrality Get the authority scores for nodes in the graph
get_betweenness Get betweenness centrality scores
get_constraint Get constraint scores for one or more graph nodes
get_leverage_centrality Get leverage centrality
get_max_eccentricity Get the maximum graph eccentricity
get_node_attrs Get node attribute values
get_reciprocity Get the graph reciprocity
edge_info Get detailed information on edges
edge_present Determine whether a specified edge is present
edge_rel Create, read, update, delete, or report status of an edge relationship
export_csv Export a graph to CSV files
get_node_attrs_ws Get node attribute values from a selection of nodes
get_attr_dfs Get data frames bound to node attributes
get_cmty_l_eigenvec Get community membership by leading eigenvector
get_cmty_louvain Get community membership by Louvain optimization
get_eccentricity Get node eccentricities
get_edge_attrs Get edge attribute values
get_bridging Get bridging scores
get_cache Get a cached vector from a graph object
get_degree_distribution Get total degree distribution data for a graph
get_degree_histogram Get histogram data for a graph's degree frequency
get_degree_in Get indegree values for all nodes
get_s_connected_cmpts Get nodes within strongly connected components
image_icon Icons and their download locations
import_graph Import a graph from various graph formats
mermaid R + mermaid.js
mutate_edge_attrs Mutate a set of edge attribute values
get_degree_out Get outdegree values for all nodes
get_graph_time Get the graph date-time or timezone
get_jaccard_similarity Get Jaccard similarity coefficient scores
get_multiedge_count Get the count of multiple edges in the graph
get_nbrs Get all neighbors of one or more nodes
get_predecessors Get node IDs for predecessor nodes to the specified node
get_radiality Get radiality centrality scores
get_selection Get the current selection available in a graph object
get_similar_nbrs Get neighboring nodes based on node attribute similarity
is_graph_directed Is the graph a directed graph?
is_graph_empty Is the graph empty?
mutate_edge_attrs_ws Mutate edge attribute values for a selection of edges
mutate_node_attrs Mutate a set of node attribute values
node_type Create, read, update, delete, or report status of a node type definition
nudge_node_positions_ws Move layout positions of a selection of nodes
open_graph Read a graph or graph series from disk
%>% The magrittr pipe
recode_node_attrs Recode a set of node attribute values
remove_from_series Remove a graph from a graph series
select_last_edges_created Select the last set of edges created in a graph
get_coreness Get coreness values for graph nodes
get_edge_df Get an edge data frame from a graph
get_edge_ids Get a vector of edge ID values
get_edges Get node IDs associated with edges
get_eigen_centrality Get the eigen centrality for nodes in the graph
get_mean_distance Get the mean distance
get_min_cut_between Get the minimum cut between source and sink nodes
get_paths Get paths from a specified node in a directed graph
renderDiagrammeR Widget render function for use in Shiny
renderGrViz Widget render function for use in Shiny
rev_edge_dir Reverse the direction of all edges in a graph
rev_edge_dir_ws Reverse the direction of selected edges in a graph
series_info Get information on a graph series
get_periphery Get nodes that form the graph periphery
get_successors Get node IDs for successor nodes to the specified node
get_w_connected_cmpts Get all nodes associated with connected components
invert_selection Invert selection of nodes or edges in a graph
get_girth Get graph girth
get_global_graph_attrs Get global graph attributes
get_last_edges_created Get the last set of edges created in a graph
select_last_nodes_created Select the last set of nodes created in a graph
select_nodes_by_id Select nodes in a graph by ID values
select_nodes_in_neighborhood Select nodes based on a walk distance from a specified node
set_graph_time Set graph date-time and timezone
set_graph_undirected Convert graph to an undirected graph
set_cache Cache a vector in the graph
set_global_graph_attrs Set global graph attributes
set_graph_name Set graph name
trav_both_edge Traverse from one or more selected nodes onto adjacent edges
is_edge_loop Is the edge a loop edge?
is_property_graph Is the graph a property graph?
join_edge_attrs Join new edge attribute values using a data frame
node_info Get detailed information on nodes
node_present Determine whether a specified node is present
trav_in Traverse from one or more selected nodes onto adjacent, inward nodes
trigger_graph_actions Trigger the execution of a series of graph actions
visnetwork Render graph with visNetwork
get_last_nodes_created Get the last set of nodes created in a graph
get_node_df Get a node data frame from a graph
get_node_ids Get a vector of node ID values
grViz R + viz.js
render_graph Render the graph in various formats
render_graph_from_series Render a graph available in a series
select_edges_by_edge_id Select edges in a graph using edge ID values
select_edges_by_node_id Select edges in a graph using node ID values
set_edge_attrs Set edge attributes
set_edge_attrs_ws Set edge attributes with an edge selection
set_node_attr_to_display Set the node attribute values to be rendered
set_node_attr_w_fcn Set node attribute values with a graph function
trav_out Traverse from one or more selected nodes onto adjacent, outward nodes
trav_out_edge Traverse from one or more selected nodes onto adjacent, outward edges
trav_in_edge Traverse from one or more selected nodes onto adjacent, inward edges
trav_in_node Traverse from one or more selected edges onto adjacent, inward nodes
delete_global_graph_attrs Delete one of the global graph attributes stored within a graph object
delete_graph_actions Delete one or more graph actions stored within a graph object
display_metagraph Display a property graph's underlying model
do_bfs Use the breadth-first search (bfs) algorithm
get_agg_degree_out Get an aggregate value from the outdegree of nodes
grVizOutput Widget output function for use in Shiny
is_edge_mutual Is the edge mutual with another edge?
is_graph_simple Is the graph a simple graph?
is_graph_weighted Is the graph a weighted graph?
get_agg_degree_total Get an aggregate value from the total degree of nodes
get_all_connected_nodes Get all nodes connected to a specified node
get_alpha_centrality Get the alpha centrality for nodes in the graph
get_cmty_edge_btwns Get community membership by edge betweenness
get_cmty_fast_greedy Get community membership by modularity optimization
is_edge_multiple Is the edge a multiple edge?
get_degree_total Get total degree values for all nodes
get_dice_similarity Get Dice similarity coefficient scores
get_graph_log Get the graph log information
get_graph_name Get graph name
get_min_eccentricity Get the minimum graph eccentricity
get_min_spanning_tree Get a minimum spanning tree subgraph
get_non_nbrs Get non-neighbors of a node in a graph
get_pagerank Get the PageRank values for nodes in the graph
graph_count Count graphs in a graph series object
graph_info Get metrics for a graph
print.dgr_graph Print the graph to the terminal
recode_edge_attrs Recode a set of edge attribute values
reorder_graph_actions Trigger the execution of a series of graph actions
replace_in_spec Razor-like template for diagram specification
rescale_edge_attrs Rescale numeric edge attribute values
rescale_node_attrs Rescale numeric node attribute values
set_df_as_edge_attr Set a data frame as an edge attribute
set_df_as_node_attr Set a data frame as a node attribute
set_node_position Apply a layout position to a single node
subset_series Subset a graph series object
is_graph_connected Is the graph a connected graph?
is_graph_dag Is the graph a directed acyclic graph?
join_node_attrs Join new node attribute values using a data frame
layout_nodes_w_string Layout nodes using a text-based schematic
mutate_node_attrs_ws Mutate node attribute values for a selection of nodes
node_count Get count of all nodes or certain types of nodes
rename_edge_attrs Rename an edge attribute
rename_node_attrs Rename a node attribute
save_graph Save a graph or graph series to disk
select_edges Select edges in a graph
select_nodes Select nodes in a graph
to_igraph Convert a DiagrammeR graph to an igraph one
trav_both Traverse from one or more selected nodes onto neighboring nodes
select_nodes_by_degree Select nodes in the graph based on their degree values
set_node_attrs Set node attributes
set_node_attrs_ws Set node attributes with a node selection
trav_out_node Traverse from one or more selected edges onto adjacent, outward nodes
trav_reverse_edge Traverse to any reverse edges
x11_hex X11 colors and hexadecimal color values
No Results!

Last month downloads

Details

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/DiagrammeR)](http://www.rdocumentation.org/packages/DiagrammeR)