1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/trav_in_node.R
3\name{trav_in_node}
4\alias{trav_in_node}
5\title{Traverse from one or more selected edges onto adjacent, inward nodes}
6\usage{
7trav_in_node(
8  graph,
9  conditions = NULL,
10  copy_attrs_from = NULL,
11  copy_attrs_as = NULL,
12  agg = "sum"
13)
14}
15\arguments{
16\item{graph}{A graph object of class \code{dgr_graph}.}
17
18\item{conditions}{An option to use filtering conditions for the traversal.}
19
20\item{copy_attrs_from}{Providing an edge attribute name will copy those edge
21attribute values to the traversed nodes. If the edge attribute already
22exists, the values will be merged to the traversed nodes; otherwise, a new
23node attribute will be created.}
24
25\item{copy_attrs_as}{If an edge attribute name is provided in
26\code{copy_attrs_from}, this option will allow the copied attribute values to be
27written under a different node attribute name. If the attribute name
28provided in \code{copy_attrs_as} does not exist in the graph's ndf, the new node
29attribute will be created with the chosen name.}
30
31\item{agg}{If an edge attribute is provided to \code{copy_attrs_from}, then an
32aggregation function is required since there may be cases where multiple
33edge attribute values will be passed onto the traversed node(s). To pass
34only a single value, the following aggregation functions can be used:
35\code{sum}, \code{min}, \code{max}, \code{mean}, or \code{median}.}
36}
37\value{
38A graph object of class \code{dgr_graph}.
39}
40\description{
41From a graph object of class \code{dgr_graph} with an active selection of edges
42move with the edge direction to connected nodes, replacing the current edges
43in the selection with those nodes traversed to. An optional filter by node
44attribute can limit the set of nodes traversed to.
45}
46\details{
47This traversal function makes use of an active selection of edges. After the
48traversal, depending on the traversal conditions, there will either be a
49selection of nodes or no selection at all.
50
51Selections of edges can be performed using the following selection
52(\verb{select_*()}) functions: \code{\link[=select_edges]{select_edges()}}, \code{\link[=select_last_edges_created]{select_last_edges_created()}},
53\code{\link[=select_edges_by_edge_id]{select_edges_by_edge_id()}}, or \code{\link[=select_edges_by_node_id]{select_edges_by_node_id()}}.
54
55Selections of edges can also be performed using the following traversal
56(\verb{trav_*()}) functions: \code{\link[=trav_out_edge]{trav_out_edge()}}, \code{\link[=trav_in_edge]{trav_in_edge()}},
57\code{\link[=trav_both_edge]{trav_both_edge()}}, or \code{\link[=trav_reverse_edge]{trav_reverse_edge()}}.
58}
59\examples{
60# Set a seed
61suppressWarnings(RNGversion("3.5.0"))
62set.seed(23)
63
64# Create a simple graph
65graph <-
66  create_graph() \%>\%
67  add_n_nodes(
68    n = 2,
69    type = "a",
70    label = c("asd", "iekd")) \%>\%
71  add_n_nodes(
72    n = 3,
73    type = "b",
74    label = c("idj", "edl", "ohd")) \%>\%
75  add_edges_w_string(
76    edges = "1->2 1->3 2->4 2->5 3->5",
77    rel = c(NA, "A", "B", "C", "D"))
78
79# Create a data frame with node ID values
80# representing the graph edges (with `from`
81# and `to` columns), and, a set of numeric values
82df_edges <-
83  data.frame(
84    from = c(1, 1, 2, 2, 3),
85    to = c(2, 3, 4, 5, 5),
86    values = round(rnorm(5, 5), 2))
87
88# Create a data frame with node ID values
89# representing the graph nodes (with the `id`
90# columns), and, a set of numeric values
91df_nodes <-
92  data.frame(
93    id = 1:5,
94    values = round(rnorm(5, 7), 2))
95
96# Join the data frame to the graph's internal
97# edge data frame (edf)
98graph <-
99  graph \%>\%
100  join_edge_attrs(df = df_edges) \%>\%
101  join_node_attrs(df = df_nodes)
102
103# Show the graph's internal node data frame
104graph \%>\% get_node_df()
105
106# Show the graph's internal edge data frame
107graph \%>\% get_edge_df()
108
109# Perform a simple traversal from the
110# edge `1`->`3` to the attached node
111# in the direction of the edge; here, no
112# conditions are placed on the nodes
113# traversed to
114graph \%>\%
115  select_edges(
116    from = 1,
117    to = 3) \%>\%
118  trav_in_node() \%>\%
119  get_selection()
120
121# Traverse from edges `2`->`5` and
122# `3`->`5` to the attached node along
123# the direction of the edge; both
124# traversals lead to the same node
125graph \%>\%
126  select_edges(
127    from = 2,
128    to = 5) \%>\%
129  select_edges(
130    from = 3,
131    to = 5) \%>\%
132  trav_in_node() \%>\%
133  get_selection()
134
135# Traverse from the edge `1`->`3`
136# to the attached node where the edge
137# is incoming, this time filtering
138# numeric values greater than `5.0` for
139# the `values` node attribute
140graph \%>\%
141  select_edges(
142    from = 1,
143    to = 3) \%>\%
144  trav_in_node(
145    conditions = values > 5.0) \%>\%
146  get_selection()
147
148# Traverse from the edge `1`->`3`
149# to the attached node where the edge
150# is incoming, this time filtering
151# numeric values less than `5.0` for
152# the `values` node attribute (the
153# condition is not met so the original
154# selection of edge `1` -> `3` remains)
155graph \%>\%
156  select_edges(
157    from = 1,
158    to = 3) \%>\%
159  trav_in_node(
160    conditions = values < 5.0) \%>\%
161  get_selection()
162
163# Traverse from the edge `1`->`2` to
164# the node `2` using multiple conditions
165# with a single-length vector
166graph \%>\%
167  select_edges(
168    from = 1,
169    to = 2) \%>\%
170  trav_in_node(
171    conditions =
172      grepl(".*d$", label) |
173      values < 6.0) \%>\%
174  get_selection()
175
176# Create another simple graph to demonstrate
177# copying of edge attribute values to traversed
178# nodes
179graph <-
180  create_graph() \%>\%
181  add_node() \%>\%
182  select_nodes() \%>\%
183  add_n_nodes_ws(
184    n = 2,
185    direction = "to") \%>\%
186  clear_selection() \%>\%
187  select_nodes_by_id(nodes = 2) \%>\%
188  set_node_attrs_ws(
189    node_attr = value,
190    value = 8) \%>\%
191  clear_selection() \%>\%
192  select_edges_by_edge_id(edges = 1) \%>\%
193  set_edge_attrs_ws(
194    edge_attr = value,
195    value = 5) \%>\%
196  clear_selection() \%>\%
197  select_edges_by_edge_id(edges = 2) \%>\%
198  set_edge_attrs_ws(
199    edge_attr = value,
200    value = 5) \%>\%
201  clear_selection() \%>\%
202  select_edges()
203
204# Show the graph's internal edge data frame
205graph \%>\% get_edge_df()
206
207# Show the graph's internal node data frame
208graph \%>\% get_node_df()
209
210# Perform a traversal from the edges to
211# the central node (`1`) while also applying
212# the edge attribute `value` to the node (in
213# this case summing the `value` of 5 from
214# both edges before adding as a node attribute)
215graph <-
216  graph \%>\%
217  trav_in_node(
218    copy_attrs_from = value,
219    agg = "sum")
220
221# Show the graph's internal node data frame
222# after this change
223graph \%>\% get_node_df()
224
225}
226