Graph Series

There may be situations where multiple graphs are required for analysis. A convenient means to work with several graphs is with the graph series object, which serializes graph objects. The time and sequence properties of the contained graphs can be used for subsetting. Scripts can be added to the series object and get triggered at will, allowing for things such as data collection and creation of multiple graphs within the series.

Graph Series Basics

The following example demonstrates how to create a series object with an existing graph object using the create_series() and add_to_series() functions. Since we'd likely want to be able to remove graphs from a series, the remove_from_series() function will be used. The use of count_graphs() and series_info() allows us to get information about the graph series object: count_graphs() returns a simple count of graph objects are present in a graph series, and series_info() yields a data frame with basic information about each graph object present in the graph series.

###
# Create and manipulate a graph series
###

library(DiagrammeR)
library(magrittr)

# Create three different graphs
graph_1 <-
  create_graph() %>%
    add_node(1) %>%
    add_node(2) %>%
    add_node(3) %>%
    add_edge(1, 3) %>%
    add_edge(1, 2) %>%
    add_edge(2, 3)

graph_2 <-
  graph_1 %>%
    add_node(4) %>%
    add_edge(4, 3)

graph_3 <-
  graph_2 %>%
    add_node(5) %>%
    add_edge(5, 2)

# Create an empty graph series
series <- create_series(series_type = "sequential")

# Confirm that the series is empty
length(series$graphs)
#> [1] 0

# Add graphs to the graph series
series <- graph_1 %>% add_to_series(series)
series <- graph_2 %>% add_to_series(series)
series <- graph_3 %>% add_to_series(series)

# Count the number of graphs in the series
length(series$graphs)
#> [1] 3

# Remove 2 graphs from graph series
series <-
  remove_from_series(
  graph_series = series, index = 2)
series <-
  remove_from_series(
  graph_series = series, index = "last")

# Count the number of graphs in the series
length(series$graphs)
#> [1] 1

Getting a Subset of a Series

With the subset_series() function you can create a graph series object that contains a subset of graphs. This is useful if you collect and process data into temporal graphs and you'd like to conduct an analysis over some time frame (e.g., graphs generated from collected data on weekdays vs. those graphs using data on weekend days). The subset_series() function works well with both sequential and temporal graph series types.

###
# Subset a graph series by time and by sequence
###

library("DiagrammeR")
library("magrittr")

# Create three graphs with the time attributes set
graph_time_1 <-
  create_graph(
    graph_name = "graph_with_time_1",
    graph_time = "2015-03-25 03:00",
    graph_tz = "GMT") %>%
  add_node(1) %>%
  add_node(2) %>%
  add_node(3) %>%
  add_edge(1, 3) %>%
  add_edge(1, 2) %>%
  add_edge(2, 3)

graph_time_2 <-
  create_graph(
    graph_name = "graph_with_time_2",
    graph_time = "2015-03-26 03:00",
    graph_tz = "GMT") %>%
  add_node(4) %>%
  add_node(5) %>%
  add_node(6) %>%
  add_edge(4, 6) %>%
  add_edge(4, 5) %>%
  add_edge(5, 6)

graph_time_3 <-
  create_graph(
    graph_name = "graph_with_time_3",
    graph_time = "2015-03-27 15:00",
    graph_tz = "GMT") %>%
  add_node(7) %>%
  add_node(8) %>%
  add_node(9) %>%
  add_edge(7, 9) %>%
  add_edge(7, 8) %>%
  add_edge(8, 9)

# Create an empty graph series
series_temporal <-
  create_series(series_type = "temporal")

# Add graphs to the graph series (each graph is added,
# by default, to the end of the series)
series_temporal <-
  graph_time_1 %>%
  add_to_series(series_temporal)

series_temporal <-
  graph_time_2 %>%
  add_to_series(series_temporal)

series_temporal <-
  graph_time_3 %>%
  add_to_series(series_temporal)

# Subset the graph series by retaining a graph in by
# its cardinality (in this case, graph `2` in the
# series will be retained)
series_sequence_subset <-
  subset_series(
    graph_series = series_temporal,
    by = "number",
    values = 2)

# Count the number of graphs in the series
length(series_sequence_subset)
#> [1] 1

# Subset graph series by date-time (the two supplied
# date-time strings in `values` serve as the lower and
# upper time bounds for graphs to retain in the subset)
series_time_subset <-
  subset_series(
    graph_series = series_temporal,
    by = "time",
    values = c("2015-03-25 12:00",
               "2015-03-26 12:00"),
    tz = "GMT")

# Count the number of graphs in this series
length(series_time_subset)
#> [1] 1

Series Scripts


Rendering a Specific Graph in a Series


Inspection Functions for a Graph Series