1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/layout_nodes_w_string.R
3\name{layout_nodes_w_string}
4\alias{layout_nodes_w_string}
5\title{Layout nodes using a text-based schematic}
6\usage{
7layout_nodes_w_string(
8  graph,
9  layout,
10  nodes,
11  sort = NULL,
12  width = 8,
13  height = 8,
14  ll = c(0, 0)
15)
16}
17\arguments{
18\item{graph}{A graph object of class \code{dgr_graph}.}
19
20\item{layout}{A layout character string that provides a schematic for the
21layout. This consists of a rectangular collection of \code{-} characters (for no
22node placement), and numbers from \code{1} to \code{9} (representing different
23groupings of nodes, further described in the \code{nodes} argument).}
24
25\item{nodes}{A named vector of the form: \code{c("1" = "[node_attr]:[value]", ...)}. The LHS corresponds to the numbers used in the \code{layout} schematic.
26The RHS provides a shorthand for the node attribute and a value for
27grouping together nodes (separated by a colon). For instance, with
28\code{"type:a"} in the RHS (and \code{"1"} in the LHS) we would target all nodes with
29a \code{type} attribute equal to \code{a} for positioning in the graph as described
30by the \code{1}s in the \code{layout}.}
31
32\item{sort}{An optional sorting method to apply to the collection of nodes
33before assigning positional information. Like \code{nodes}, this is a named
34vector of the form: \code{c("1" = "[node_attr]:asc|desc", ...)}. The \code{node_attr}
35in this case should be different than that used in \code{nodes}. Ideally, this
36node attribute should have unique values. Choose either \code{asc} or \code{desc}
37right of the colon for ascending or descending sorts.}
38
39\item{width}{The width of the \code{layout} diagram.}
40
41\item{height}{The height of the \code{layout} diagram.}
42
43\item{ll}{A vector describing the the lower-left coordinates of the \code{layout}}
44}
45\value{
46A graph object of class \code{dgr_graph}.
47}
48\description{
49Layout one or several groups of nodes using a text-based schematic. The
50option is available to apply sorting to each of the groups.
51}
52\examples{
53# Create a graph with unique labels and
54# several node `type` groupings
55graph <-
56  create_graph() \%>\%
57  add_node(type = "a", label = "a") \%>\%
58  add_node(type = "a", label = "b") \%>\%
59  add_node(type = "b", label = "c") \%>\%
60  add_node(type = "b", label = "d") \%>\%
61  add_node(type = "b", label = "e") \%>\%
62  add_node(type = "c", label = "f") \%>\%
63  add_node(type = "c", label = "g")
64
65# Define a 'layout' for groups of nodes
66# using a text string (dashes are empty
67# grid cells, numbers--representing
68# ad-hoc groupings--correspond to
69# individual nodes); here, define a layout
70# with 3 groups of nodes
71layout <-
72"
731--------
741--------
75---222---
76--------3
77--------3
78"
79
80# Use the `layout` along with what nodes
81# the numbers correspond to in the graph
82# with the `nodes` named vectors; the
83# optional `sort` vector describes how
84# we should sort the collection of node
85# before adding position information
86graph <-
87  graph \%>\%
88  layout_nodes_w_string(
89    layout = layout,
90    nodes = c("1" = "type:a",
91              "2" = "type:b",
92              "3" = "type:c"),
93    sort = c("1" = "label:asc",
94             "2" = "label:desc",
95             "3" = "label:desc"))
96
97# Show the graph's node data frame
98# to confirm that `x` and `y` values
99# were added to each of the nodes
100graph \%>\% get_node_df()
101}
102\seealso{
103Other Node creation and removal:
104\code{\link{add_n_node_clones}()},
105\code{\link{add_n_nodes_ws}()},
106\code{\link{add_n_nodes}()},
107\code{\link{add_node_clones_ws}()},
108\code{\link{add_node_df}()},
109\code{\link{add_nodes_from_df_cols}()},
110\code{\link{add_nodes_from_table}()},
111\code{\link{add_node}()},
112\code{\link{colorize_node_attrs}()},
113\code{\link{copy_node_attrs}()},
114\code{\link{create_node_df}()},
115\code{\link{delete_nodes_ws}()},
116\code{\link{delete_node}()},
117\code{\link{drop_node_attrs}()},
118\code{\link{join_node_attrs}()},
119\code{\link{mutate_node_attrs_ws}()},
120\code{\link{mutate_node_attrs}()},
121\code{\link{node_data}()},
122\code{\link{recode_node_attrs}()},
123\code{\link{rename_node_attrs}()},
124\code{\link{rescale_node_attrs}()},
125\code{\link{set_node_attr_to_display}()},
126\code{\link{set_node_attr_w_fcn}()},
127\code{\link{set_node_attrs_ws}()},
128\code{\link{set_node_attrs}()},
129\code{\link{set_node_position}()}
130}
131\concept{Node creation and removal}
132