Mutate MTG

Adds new variables to an MTG. New variables overwrite existing variables of the same name.

mutate_mtg(
  data,
  ...,
  .scale = NULL,
  .symbol = NULL,
  .traversal = c("pre-order", "post-order", "in-order", "level", "ancestor"),
  .pruneFun = NULL
)

Arguments

data	A mtg, as returned by read_mtg().
...	Name-value pairs of expressions, each with length 1. To access a variable from the mtg, use node$var instead of var. The name of each argument will be the name of a new variable, and the value will be its corresponding value. New variables overwrite existing variables of the same name. The arguments in ... are automatically quoted and evaluated in the context of the mtg. They support unquoting and splicing. See the chapter about metaprogramming in the book "Advanced R" from H. Wickham for an introduction to these concepts.
.scale	An integer vector of the .scale to apply the functions over (i.e. the SCALE from the MTG classes). This argument is used to apply a filter on the node modification.
.symbol	A character vector of the .symbol to apply the functions over (i.e. the SYMBOL from the MTG classes). This argument is used to apply a filter on the node modification.
.traversal	any of 'pre-order' (the default), 'post-order', 'in-order', 'level', 'ancestor', or a custom function (see details)
.pruneFun	allows providing a a prune criteria, i.e. a function taking a Node as an input, and returning TRUE or FALSE. If pruneFun returns FALSE for a Node, then the Node and its entire sub-tree will not be considered.

Value

The MTG invisibly. It is returned for piping purposes only, but it is modified in-place inside de function.

Details

The .traversal and .pruneFun arguments are passed to data.tree::Traverse. From its documentation: the traversal order is as follows:

pre-order

Go to first child, then to its first child, etc.

post-order

Go to the first branch's leaf, then to its siblings, and work your way back to the root

in-order

Go to the first branch's leaf, then to its parent, and only then to the leaf's sibling

level

Collect root, then level 2, then level 3, etc.

ancestor

Take a node, then the node's parent, then that node's parent in turn, etc. This ignores the pruneFun

function

You can also provide a function, whose sole parameter is a Node object. The function is expected to return the node's next node, a list of the node's next nodes, or NULL.

Note

The function was designed to be used as for dplyr::mutate(), so it uses non-standard evaluation (NSE). It also returns the mtg so it can be used with pipes.

See also

data.tree Do

Examples

# Import the MTG:
filepath= system.file("extdata", "simple_plant.mtg", package = "XploRer")
MTG = read_mtg(filepath)
#> Warning: the condition has length > 1 and only the first element will be used
#> Warning: the condition has length > 1 and only the first element will be used
#> Warning: the condition has length > 1 and only the first element will be used
#> Warning: the condition has length > 1 and only the first element will be used

# And mutate it by adding two new variables, Length2 and Length3:
mutate_mtg(MTG, Length2 = node$Length + 2, Length3 = node$Length2 * 2)

# note two things here:
# 1/ We use "node$" to access the values of a variable inside the mtg;
# 2/ Length3 uses the results of Length2 before it even exist. This is because
# The variables are constructed sequentially.

# We can also use pipes:
if (FALSE) {
read_mtg(filepath)%>%
  mutate_mtg(Length2 = node$Length + 2)%>%
  autoplot(.)
}

# Or even function:
mutate_mtg(MTG, Length_parent = parent("Length"))

# And more complex associations. Here is an example were we need the sum of
# the section_surface of children of each node:
mutate_mtg(MTG, section_surface = pi * ((node$Width / 2)^2),
           s_surf_child_sum = sum(children("section_surface"),na.rm=TRUE))


data.tree::ToDataFrameTree(MTG,"Length","Length2","Length3",
"Length_parent","section_surface","s_surf_child_sum")
#>                    levelName Length Length2 Length3 Length_parent
#> 1 node_1                         NA      NA      NA            NA
#> 2  °--node_2                     NA      NA      NA            NA
#> 3      °--node_3                 NA      NA      NA            NA
#> 4          °--node_4              4       6      12            NA
#> 5              ¦--node_5         10      12      24             4
#> 6              °--node_6          6       8      16             4
#> 7                  °--node_7     12      14      28             6
#>   section_surface s_surf_child_sum
#> 1              NA                0
#> 2              NA                0
#> 3              NA                0
#> 4       0.7853982                0
#> 5      28.2743339                0
#> 6              NA                0
#> 7      38.4845100                0