ggraph v2.0.3


Monthly downloads



An Implementation of Grammar of Graphics for Graphs and Networks

The grammar of graphics as implemented in ggplot2 is a poor fit for graph and network visualizations due to its reliance on tabular data input. ggraph is an extension of the ggplot2 API tailored to graph visualizations and provides the same flexible approach to building up plots layer by layer.



Travis-CI Build
Status AppVeyor Build
Status CRAN\_Release\_Badge CRAN\_Download\_Badge

/dʒiː.dʒɪˈrɑːf/ (or g-giraffe)

A grammar of graphics for relational data

ggraph is an extension of ggplot2 aimed at supporting relational data structures such as networks, graphs, and trees. While it builds upon the foundation of ggplot2 and its API it comes with its own self-contained set of geoms, facets, etc., as well as adding the concept of layouts to the grammar.

An example

#> Loading required package: ggplot2
#> Attaching package: 'tidygraph'
#> The following object is masked from 'package:stats':
#>     filter

# Create graph of highschool friendships
graph <- as_tbl_graph(highschool) %>% 
    mutate(Popularity = centrality_degree(mode = 'in'))

# plot using ggraph
ggraph(graph, layout = 'kk') + 
    geom_edge_fan(aes(alpha = stat(index)), show.legend = FALSE) + 
    geom_node_point(aes(size = Popularity)) + 
    facet_edges(~year) + 
    theme_graph(foreground = 'steelblue', fg_text_colour = 'white')

The core concepts

ggraph builds upon three core concepts that are quite easy to understand:

  1. The Layout defines how nodes are placed on the plot, that is, it is a conversion of the relational structure into an x and y value for each node in the graph. ggraph has access to all layout functions available in igraph and furthermore provides a large selection of its own, such as hive plots, treemaps, and circle packing.
  2. The Nodes are the connected entities in the relational structure. These can be plotted using the geom_node_*() family of geoms. Some node geoms make more sense for certain layouts, e.g. geom_node_tile() for treemaps and icicle plots, while others are more general purpose, e.g. geom_node_point().
  3. The Edges are the connections between the entities in the relational structure. These can be visualized using the geom_edge_*() family of geoms that contain a lot of different edge types for different scenarios. Sometimes the edges are implied by the layout (e.g. with treemaps) and need not be plotted, but often some sort of line is warranted.

All of the tree concepts have been discussed in detail in dedicated blog posts that are also available as vignettes in the package. Please refer to these for more information.

Note: The linked blog posts are based on ggraph v1. After ggraph v1.1 the underlying implementation was moved to tidygraph and cleaned up, but this resulted in some breaking changes in the process. Therefore the vignette versions are generally recommended as they have been updated.

Supported data types

There are many different ways to store and work with relational data in R. ggraph is built upon tidygraph and the large swath of data structures it supports are thus natively supported in ggraph. In order to get a data type supported by ggraph, simply provide an as_tbl_graph method for it.


ggraph is available through CRAN and can be installed with install.packages('ggraph'). The package is under active development though and the latest set of features can be obtained by installing from this repository using devtools


ggraph is not the only package to provide some sort of support for relational data in ggplot2, though I’m fairly certain that it is the most ambitious. ggdendro provides support for dendrogram and hclust objects through conversion of the structures into line segments that can then be plotted with geom_segment(). ggtree provides more extensive support for all things tree-related, though it lacks some of the layouts and edge types that ggraph offers (it has other features that ggraph lacks though). For more standard hairball network plots ggnetwork, geomnet, and GGally all provide some functionality though none of them are as extensive in scope as ggraph.

Code of Conduct

Please note that the ‘ggraph’ project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

Functions in ggraph

Name Description
flare The class hierarchy of the flare visualization library
geom_axis_hive Draw rectangular bars and labels on hive axes
autograph Quickplot wrapper for networks
facet_graph Create a grid of small multiples by node and/or edge attributes
geom_edge_bend Draw edges as diagonals
geom_conn_bundle Create hierarchical edge bundles between node connections
facet_nodes Create small multiples based on node attributes
geom_edge_density Show edges as a density map
facet_edges Create small multiples based on edge attributes
geom_edge_arc Draw edges as Arcs
geom_edge_diagonal Draw edges as diagonals
geom_edge_loop Draw edges as diagonals
geom_edge_link Draw edges as straight lines between nodes
geom_edge_elbow Draw edges as elbows
geom_edge_parallel Draw multi edges as parallel lines
geom_edge_point Draw edges as glyphs
get_con Create a connection extractor function
get_edges Create edge extractor function
geom_node_range Show nodes as a line spanning a horizontal range
geom_node_point Show nodes as points
geom_node_tile Draw the rectangles in a treemap
guide_edge_direction Edge direction guide
geom_node_text Annotate nodes with text
geom_edge_hive Draw edges in hive plots
geom_edge_fan Draw edges as curves of different curvature
layout_tbl_graph_circlepack Calculate nodes as circles packed within their parent circle
ggraph-package ggraph: An Implementation of Grammar of Graphics for Graphs and Networks
ggraph Create a ggraph plot
layout_tbl_graph_focus Place nodes in circles based on distance to a specific node
geom_edge_span Draw edges as vertical spans
geom_node_arc_bar Show nodes as thick arcs
highschool Friendship among high school boys
geom_edge_tile Draw edges as glyphs
geom_node_circle Show nodes as circles
get_nodes Create a node extractor function
guide_train.edge_colourbar Helper methods for guides
reexports Objects exported from other packages
qgraph Deprecated autograph predecessor
layout_tbl_graph_dendrogram Apply a dendrogram layout to layout_tbl_graph
StatFilter ggraph extensions to ggplot2
layout_tbl_graph_auto Automatically pick a layout based on graph type
geometry Define simple shapes for line capping
scale_type.geometry Define default scale type for geometry
geom_node_voronoi Show nodes as voronoi tiles
layout_tbl_graph_linear Place nodes on a line or circle
layout_tbl_graph_igraph Use igraph layout algorithms for layout_tbl_graph
layout_tbl_graph_stress Place nodes using stress majorisation
layout_tbl_graph_unrooted Create an unrooted layout using equal-angle or equal-daylight
layout_tbl_graph_treemap Calculate nodes as rectangles subdividing that of their parent
internal_extractors Internal data extractors
theme_graph A theme tuned for graph visualizations
layout_tbl_graph_hive Place nodes in a Hive Plot layout
layout_tbl_graph_manual Manually specify a layout for layout_tbl_graph
layout_to_table Convert a layout to a table
scale_edge_size Edge size scales
scale_edge_shape Edge shape scales
layout_tbl_graph_matrix Place nodes on a diagonal
node_angle Get the angle of nodes and edges
whigs Membership network of American Whigs
pack_circles Pack circles together
layout_tbl_graph_eigen Place nodes according to their eigenvalues
layout_tbl_graph_fabric Create a fabric layout
guide_edge_colourbar Colourbar legend for edges
layout_tbl_graph_partition Calculate nodes as areas dividing their parent
layout_tbl_graph_backbone Place node to emphasize group structure
layout_tbl_graph_centrality Place nodes in circles according to centrality measure
makeContent.cappedpathgrob Dynamic capping of paths
layout_tbl_graph_pmds Place nodes based on a multidimensional scaling of a set of pivot nodes
scale_edge_fill Edge fill scales
scale_label_size Edge label size scales
scale_edge_linetype Edge linetype scales
scale_edge_width Edge width scales
makeContent.textalong Text angled according to line
scale_edge_alpha Edge alpha scales
scale_edge_colour Edge colour scales
No Results!

Vignettes of ggraph

No Results!

Last month downloads


Type Package
License MIT + file LICENSE
Encoding UTF-8
LazyData TRUE
LinkingTo Rcpp
RoxygenNote 7.0.2
VignetteBuilder knitr
NeedsCompilation yes
Packaged 2020-05-20 19:18:24 UTC; thomas
Repository CRAN
Date/Publication 2020-05-20 20:20:02 UTC

Include our badge in your README