Build graph/network structures using functions for stepwise addition and deletion of nodes and edges. Work with data available in tables for bulk addition of nodes, edges, and associated metadata. Use graph selections and traversals to apply changes to specific nodes or edges. A wide selection of graph algorithms allow for the analysis of graphs. Visualize the graphs and take advantage of any aesthetic properties assigned to nodes and edges.
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.
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 graphgraph <- 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] "[email protected]" "[email protected]" #> [3] "[email protected]" "[email protected]" #> [5] "[email protected]" "[email protected]" #> [7] "[email protected]"
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"
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.
Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
MIT © Richard Iannone
Added the helper functions node_aes()
, node_data()
, edge_aes()
, and edge_data()
to facilitate the binding of node and edge aesthetic and data attribute values; several functions now have namesake arguments that accept these functions' output.
Information about the graph is now displayed in the console when the graph object is called
Error messages are now more helpful and try to provide pointers for the more common errors
Added functions to generate 2D and 3D grid graphs (add_grid_2d()
and add_grid_3d()
)
Added _ws
(with selection) variants of the mutate_[node/edge]_attrs()
functions for mutating node or edge attributes for only those nodes/edges in an active selection
Incorporated an edges
argument into the select_edges()
function in order to filter the selection of edges to a set of edge ID values
Reduced the dependency on R to version >= 3.2.0
Added functions to generate 2D and 3D grid graphs (add_grid_2d()
and add_grid_3d()
)
Added _ws
(with selection) variants of the mutate_[node/edge]_attrs()
functions for mutating node or edge attributes for only those nodes/edges in an active selection
Incorporated an edges
argument into the select_edges()
function in order to filter the selection of edges to a set of edge ID values
Reduced the dependency on R to version >= 3.2.0
Simplified many functions internally
Added a default print method for graph objects
Allowed use of bare node or edge attribute names in many functions
Implemented graph actions as a means to run one or more functions at every graph transformation step; for example, this can be used to automatically update a node attribute such as betweenness
whenever modifications to the graph are made (e.g., adding nodes, removing edges, etc.)
Data frames can be set as node or edge attributes with the set_df_as_node_attr()
and set_df_as_edge_attr()
functions; the get_attr_dfs()
function allows for retrieval of stored data frame data
Added two new graph-generating functions (add_gnp_graph()
, add_pa_graph()
, and create_complement_graph()
)
Added functions to clone existing nodes and edges (add_n_node_clones()
and add_edge_clone()
)
Added several count_*
functions (count_asymmetric_node_pairs()
, count_automorphisms()
, etc.)
Added new functions to obtain graph properties (get_adhesion()
, get_girth()
, get_reciprocity()
, etc.)
Added several is_*
functions for graph and edge properties (e.g., is_edge_loop()
, is_graph_dag()
, etc.)
The mutate_node_attrs()
and mutate_edge_attrs()
functions now have simpler and more powerful interfaces for mutating node and edge attributes
Graphs can be easily saved to disk (and read from disk) using the save_graph()
and open_graph()
functions
Modified basic structure of node and edge data frames such that ID values are automatically set as integer values
Just as nodes do, edges now have edge ID values (they can be obtained using get_edge_ids()
and they can be used directly in the select_edges_by_edge_id()
function)
When created, a graph object automatically generates a graph ID and graph name (which can be modified using set_graph_name()
)
So long as node label
values are unique, they may now be used to compose edges using the add_edge()
function with use_labels = TRUE
Quickly and flexibly add color to nodes and edges using the colorize_node_attrs()
and colorize_edge_attrs()
functions
Added functions to selectively modify existing node and edge attributes: copy_[node/edge]_attrs()
, drop_[node/edge]_attrs()
, mutate_[node/edge]_attrs()
, recode_[node/edge]_attrs()
, rename_[node/edge]_attrs()
, and rescale_[node/edge]_attrs()
.
New node and edge attributes can now be easily added to a graph via a data frame using the join_node_attrs()
and join_edge_attrs()
functions
Several graph generators are available for quickly adding graph primitives to a graph object (add_balanced_tree()
, add_cycle()
, add_full_graph()
, add_path()
, add_prism()
, and add_star()
)
All traversal functions can now migrate numeric node or edge attribute values to the traversed edges (e.g., trav_out_edge()
, trav_in_node()
) by providing an attribute name to copy_attrs_from
; for those traversal functions where nodes or edges may receive multiple values, one can specify an aggregation type in their agg
argument (e.g,. trav_in_node()
, trav_both_edge()
)
Multiple conditions can be specified for all traversal types and for the select_nodes()
and select_edges()
functions, plus, they are much easier to write
Added the mk_cond()
helper function for creating conditions for any of the traversal functions (trav_...()
), and, the select_nodes()
and select_edges()
functions; this helper allows for easier composition of selection/traversal conditions using variables and/or function calls
With a selection of edges one can now use select_rev_edges_ws()
to transform that selection to that of the selected edges' reverse edges (where available); the option is there to add the reverse edges to the edge selection or to simply replace the current selection
Caching attributes for later use has been made simpler with a collection of cache_...()
functions (or, set the cache explicitly using set_cache()
); get the graph's cache using the get_cache()
function
Added functions to allow for layout control of nodes (set_node_position()
, layout_nodes_w_string()
, nudge_node_positions()
)
Added functions to convert DiagrammeR graphs to igraph graphs and vice versa (to_igraph()
, from_igraph()
)
Now you can create a graph from an adjacency matrix (from_adj_matrix()
)
Added functions to get community membership with a variety of algorithms: get_cmty_edge_btwns()
, get_cmty_fast_greedy()
, get_cmty_l_eigenvec()
, get_cmty_louvain()
, and get_cmty_walktrap()
.
Added functions to determine similarity coefficient scores for graph nodes: get_dice_similarity()
and get_dice_similarity()
.
Constraint scores for nodes can now be determined using the get_constraint()
function
Functions for getting information on nodes neighbors have been added: get_nbrs()
, get_non_nbrs()
, get_similar_nbrs()
.
Groups of nodes that are weakly or strongly connected components can be determined using the get_w_connected_cmpts()
and get_s_connected_cmpts()
functions
Get articulation points (i.e., nodes that, when removed, disconnect the graph) with the get_articulation_points()
function
Obtain centrality measures for graph nodes using the get_closeness()
and get_betweenness()
functions
Get the minimum-spanning tree subgraph from a graph with weighted edges using the get_min_spanning_tree()
function
The edge direction may be reversed for an entire graph (rev_edge_dir()
) or for part of a graph using an edge selection (rev_edge_dir_ws()
)
Depth-first search and breadth-first search algorithms are available in the do_dfs()
and do_bfs()
functions
Degree data for plots can now be easily obtained using the get_degree_distribution()
and get_degree_histogram()
functions
Global graph attributes are now more easily modifiable using a set of functions for this purpose: add_global_graph_attrs()
, clear_global_graph_attrs()
, delete_global_graph_attrs()
, get_global_graph_attrs()
, set_global_graph_attrs()
Added option to display different text labels on nodes via the display
node attribute; this is easily set with the set_node_attr_to_display()
function
Rewrote many graph functions (e.g. traversals) so that they are faster for very large graphs
A log of all graph functions that directly modify the graph is now part of the graph object (graph$graph_log
)
Added functionality to automatically generate graph backups at every graph modification; this is in the form of RDS files deposited in a subdirectory (name is based on the graph ID) of the working directory; the option (write_backups
, set to FALSE
by default) is available in all functions that initialize a graph object (create_graph()
, create_random_graph()
, from_igraph()
, from_adj_matrix()
)
Revised many graph functions so they work better together
Added many testthat tests to maintain the quality of the graph functions
Added functions create_random_graph()
, import_graph()
, combine_graphs()
, country_graph()
and select_graph_from_series()
Added support for visNetwork graphs as a rendering option with render_graph()
Renamed functions graphviz_graph()
and graphviz_render()
to create_graph()
and render_graph()
, respectively
Removed function graphviz_export()
(exporting now handled with render_graph()
)
Added several new functions to inspect, analyze, and modify graphs: display_graph_object()
, node_info()
, edge_info()
, node_present()
, edge_present()
, get_nodes()
, get_edges()
, get_predecessors()
, get_successors()
, node_count()
, edge_count()
, is_graph_empty()
, is_graph_directed()
, add_node()
, add_edges()
, delete_node()
, delete_edge()
, node_type()
, edge_relationship()
, create_series()
, add_to_series()
, remove_from_series()
, graph_count()
, subset_series()
, trigger_script()
, render_graph_from_series()
, and series_info()
Added several functions to work with graphs: create_nodes()
, create_edges()
, combine_nodes()
, combine_edges()
, scale_nodes()
, scale_edges()
, get_nodes()
, node_info()
, graphviz_graph()
, graphviz_render()
, and graphviz_export()
Removed the graphviz_nodes_edges_df()
and graphviz_single_df()
functions
Added support for subgraphs and Gantt charts in mermaid diagrams
Added function graphviz_nodes_edges_df()
for generating Graphviz DOT code that defines nodes and edges (and their attributes) from data in two data frames: one for nodes, the other for the edge operations
Added function graphviz_single_df()
for generating Graphviz DOT code from a single data frame
Incorporated the new substitution operators @_{...}
or @^{...}
in grViz
statements for subscripting and superscripting, respectively
Added support for substitution in Graphviz graph specifications
Added support for Graphviz diagrams in the Shiny app
Initial release
Incorporated into the htmlwidgets framework
Added basic shiny app