Traverse from one or more selected nodes onto adjacent, inward edges

From a graph object of class dgr_graph move to incoming edges from a selection of one or more selected nodes, thereby creating a selection of edges. An optional filter by edge attribute can limit the set of edges traversed to.

This traversal function makes use of an active selection of nodes. After the traversal, depending on the traversal conditions, there will either be a selection of edges or no selection at all.

Selections of nodes can be performed using the following node selection (select_*()) functions: select_nodes(), select_last_nodes_created(), select_nodes_by_degree(), select_nodes_by_id(), or select_nodes_in_neighborhood().

Selections of nodes can also be performed using the following traversal (trav_*()) functions: trav_out(), trav_in(), trav_both(), trav_out_node(), trav_in_node(), trav_out_until(), or trav_in_until().

Usage

trav_in_edge(
  graph,
  conditions = NULL,
  copy_attrs_from = NULL,
  copy_attrs_as = NULL
)

Arguments

graph: A graph object of class dgr_graph.
conditions: An option to use filtering conditions for the traversal.
copy_attrs_from: Providing a node attribute name will copy those node attribute values to the traversed edges. If the edge attribute already exists, the values will be merged to the traversed edges; otherwise, a new edge attribute will be created.
copy_attrs_as: If a node attribute name is provided in copy_attrs_from, this option will allow the copied attribute values to be written under a different edge attribute name. If the attribute name provided in copy_attrs_as does not exist in the graph's edf, the new edge attribute will be created with the chosen name.

Value

A graph object of class dgr_graph.

Examples

# Set a seed
suppressWarnings(RNGversion("3.5.0"))
set.seed(23)

# Create a simple graph
graph <-
  create_graph() %>%
  add_n_nodes(
    n = 2,
    type = "a",
    label = c("asd", "iekd")) %>%
  add_n_nodes(
    n = 3,
    type = "b",
    label = c("idj", "edl", "ohd")) %>%
  add_edges_w_string(
    edges = "1->2 1->3 2->4 2->5 3->5",
    rel = c(NA, "A", "B", "C", "D"))

# Create a data frame with node ID
# values representing the graph edges
# (with `from` and `to` columns), and,
# a set of numeric values
df <-
  data.frame(
    from = c(1, 1, 2, 2, 3),
    to = c(2, 3, 4, 5, 5),
    values = round(rnorm(5, 5), 2))

# Join the data frame to the graph's
# internal edge data frame (edf)
graph <-
  graph %>%
  join_edge_attrs(df = df)

# Show the graph's internal edge data frame
graph %>% get_edge_df()
#>   id from to  rel values
#> 1  1    1  2 <NA>   6.00
#> 2  2    1  3    A   6.11
#> 3  3    2  4    B   4.72
#> 4  4    2  5    C   6.02
#> 5  5    3  5    D   5.05

# Perform a simple traversal from
# nodes to inbound edges with no
# conditions on the nodes
# traversed to
graph %>%
  select_nodes_by_id(nodes = 2) %>%
  trav_in_edge() %>%
  get_selection()
#> [1] 1

# Traverse from node `2` to any
# inbound edges, filtering to
# those edges that have NA values
# for the `rel` edge attribute
graph %>%
  select_nodes_by_id(nodes = 2) %>%
  trav_in_edge(
    conditions = is.na(rel)) %>%
  get_selection()
#> [1] 1

# Traverse from node `2` to any
# inbound edges, filtering to those
# edges that do not have NA values
# for the `rel` edge attribute
# (since there are no allowed
# traversals, the selection of node
# `2` is retained)
graph %>%
  select_nodes_by_id(nodes = 2) %>%
  trav_in_edge(
    conditions = !is.na(rel)) %>%
  get_selection()
#> [1] 2

# Traverse from node `5` to any
# inbound edges, filtering to those
# edges that have numeric values
# greater than `5.5` for the `rel`
# edge attribute
graph %>%
  select_nodes_by_id(nodes = 5) %>%
  trav_in_edge(
    conditions = values > 5.5) %>%
  get_selection()
#> [1] 4

# Traverse from node `5` to any
# inbound edges, filtering to those
# edges that have values equal to
# `D` for the `rel` edge attribute
graph %>%
  select_nodes_by_id(nodes = 5) %>%
  trav_in_edge(
    conditions = rel == "D") %>%
  get_selection()
#> [1] 5

# Traverse from node `5` to any
# inbound edges, filtering to those
# edges that have values in the set
# `C` and `D` for the `rel` edge
# attribute
graph %>%
  select_nodes_by_id(nodes = 5) %>%
  trav_in_edge(
    conditions = rel %in% c("C", "D")) %>%
  get_selection()
#> [1] 4 5

# Traverse from node `5` to any
# inbound edges, and use multiple
# conditions for the traversal
graph %>%
  select_nodes_by_id(nodes = 5) %>%
  trav_in_edge(
    conditions =
      rel %in% c("C", "D") &
      values > 5.5) %>%
  get_selection()
#> [1] 4

# Traverse from node `5` to any
# inbound edges, and use multiple
# conditions with a single-length
# vector
graph %>%
  select_nodes_by_id(nodes = 5) %>%
  trav_in_edge(
    conditions =
      rel %in% c("D", "E") |
      values > 5.5) %>%
  get_selection()
#> [1] 4 5

# Traverse from node `5` to any
# inbound edges, and use a regular
# expression as a filtering condition
graph %>%
  select_nodes_by_id(nodes = 5) %>%
  trav_in_edge(
    conditions = grepl("C|D", rel)) %>%
  get_selection()
#> [1] 4 5

# Show the graph's internal ndf
graph %>% get_node_df()
#>   id type label
#> 1  1    a   asd
#> 2  2    a  iekd
#> 3  3    b   idj
#> 4  4    b   edl
#> 5  5    b   ohd

# Show the graph's internal edf
graph %>% get_edge_df()
#>   id from to  rel values
#> 1  1    1  2 <NA>   6.00
#> 2  2    1  3    A   6.11
#> 3  3    2  4    B   4.72
#> 4  4    2  5    C   6.02
#> 5  5    3  5    D   5.05

# Perform a traversal from all
# nodes to their incoming edges and,
# while doing so, copy the `label`
# node attribute to any of the nodes'
# incoming edges
graph <-
  graph %>%
  select_nodes() %>%
  trav_in_edge(
    copy_attrs_from = label)

# Show the graph's internal edge
# data frame after this change
graph %>% get_edge_df()
#>   id from to  rel label values
#> 1  1    1  2 <NA>  iekd   6.00
#> 2  2    1  3    A   idj   6.11
#> 3  3    2  4    B   edl   4.72
#> 4  4    2  5    C   ohd   6.02
#> 5  5    3  5    D   ohd   5.05