Method new()
Create a new Node object. This is often used to create the root of a tree when creating a tree programmatically.
Usage
Node$new(name, check = c("check", "no-warn", "no-check"), ...)
Arguments
namethe name of the node to be created
check
Either
"check": if the name conformance should be checked and warnings should be printed in case of non-conformance (the default)
"no-warn": if the name conformance should be checked, but no warnings should be printed in case of non-conformance (if you expect non-conformance)
"no-check" or FALSE: if the name conformance should not be checked; use this if performance is critical. However, in case of non-conformance, expect cryptic follow-up errors
...
A name-value mapping of node attributes
Returns
A new `Node` object
Examples
node <- Node$new("mynode", x = 2, y = "value of y")
node$y
Method AddChild()
Creates a Node and adds it as the last sibling as a child to the Node on which this is called.
Usage
Node$AddChild(name, check = c("check", "no-warn", "no-check"), ...)
Arguments
namethe name of the node to be created
check
Either
"check": if the name conformance should be checked and warnings should be printed in case of non-conformance (the default)
"no-warn": if the name conformance should be checked, but no warnings should be printed in case of non-conformance (if you expect non-conformance)
"no-check" or FALSE: if the name conformance should not be checked; use this if performance is critical. However, in case of non-conformance, expect cryptic follow-up errors
...
A name-value mapping of node attributes
Returns
The new Node (invisibly)
Examples
root <- Node$new("myroot", myname = "I'm the root")
root$AddChild("child1", myname = "I'm the favorite child")
child2 <- root$AddChild("child2", myname = "I'm just another child")
child3 <- child2$AddChild("child3", myname = "Grandson of a root!")
print(root, "myname")
Method AddChildNode()
Adds a Node as a child to this node.
Usage
Node$AddChildNode(child)
Arguments
childThe child "Node" to add.
Returns
the child node added (this lets you chain calls)
Examples
root <- Node$new("myroot")
child <- Node$new("mychild")
root$AddChildNode(child)
Method AddSibling()
Creates a new Node called name and adds it after this Node as a sibling.
Usage
Node$AddSibling(name, check = c("check", "no-warn", "no-check"), ...)
Arguments
namethe name of the node to be created
check
Either
"check": if the name conformance should be checked and warnings should be printed in case of non-conformance (the default)
"no-warn": if the name conformance should be checked, but no warnings should be printed in case of non-conformance (if you expect non-conformance)
"no-check" or FALSE: if the name conformance should not be checked; use this if performance is critical. However, in case of non-conformance, expect cryptic follow-up errors
...
A name-value mapping of node attributes
Returns
the sibling node (this lets you chain calls)
Examples
#' root <- Node$new("myroot")
child <- root$AddChild("child1")
sibling <- child$AddSibling("sibling1")
Method AddSiblingNode()
Adds a Node after this Node, as a sibling.
Usage
Node$AddSiblingNode(sibling)
Arguments
siblingThe "Node" to add as a sibling.
Returns
the added sibling node (this lets you chain calls, as in the examples)
Examples
root <- Node$new("myroot")
child <- Node$new("mychild")
sibling <- Node$new("sibling")
root$AddChildNode(child)$AddSiblingNode(sibling)
Method RemoveChild()
Remove the child Node called name from a Node and returns it.
Usage
Node$RemoveChild(name)
Arguments
namethe name of the node to be created
Returns
the subtree spanned by the removed child.
Examples
node <- Node$new("myroot")$AddChild("mychild")$root
node$RemoveChild("mychild")
Method RemoveAttribute()
Removes attribute called name from this Node.
Usage
Node$RemoveAttribute(name, stopIfNotAvailable = TRUE)
Arguments
namethe name of the node to be created
stopIfNotAvailable
Gives an error if stopIfNotAvailable and the attribute does not exist.
Examples
node <- Node$new("mynode")
node$RemoveAttribute("age", stopIfNotAvailable = FALSE)
node$age <- 27
node$RemoveAttribute("age")
node
Method Sort()
Sort children of a Node or an entire data.tree structure
Usage
Node$Sort(attribute, ..., decreasing = FALSE, recursive = TRUE)
Arguments
attributedetermines what is collected. The attribute can be
a.) the name of a field or a property/active of each Node in the tree, e.g. acme$Get("p") or acme$Get("position")
b.) the name of a method of each Node in the tree, e.g. acme$Get("levelZeroBased"), where e.g. acme$levelZeroBased <- function() acme$level - 1
c.) a function, whose first argument must be a Node e.g. acme$Get(function(node) node$cost * node$p)
...
any parameters to be passed on the the attribute (in case it's a method or a
function)
decreasing
sort order
recursive
if TRUE, the method will be called recursively on the Node's children. This allows sorting an entire tree.
Details
You can sort with respect to any argument of the tree. But note that sorting has
side-effects, meaning that you modify the underlying, original data.tree object structure.
See also Sort for the equivalent function.
Returns
Returns the node on which Sort is called, invisibly. This can be useful to chain Node methods.
Examples
data(acme)
acme$Do(function(x) x$totalCost <- Aggregate(x, "cost", sum), traversal = "post-order")
Sort(acme, "totalCost", decreasing = FALSE)
print(acme, "totalCost")
Method Revert()
Reverts the sort order of a Node's children.
See also Revert for the equivalent function.
Usage
Node$Revert(recursive = TRUE)
Arguments
recursiveif TRUE, the method will be called recursively on the Node's children. This allows sorting an entire tree.
Returns
returns the Node invisibly (for chaining)
Method Prune()
Prunes a tree.
Pruning refers to removing entire subtrees. This function has side-effects, it modifies your data.tree structure!
See also Prune for the equivalent function.
Usage
Node$Prune(pruneFun)
Arguments
pruneFunallows providing a a prune criteria, i.e. a function taking a Node as an input, and returning TRUE or FALSE.
If the pruneFun returns FALSE for a Node, then the Node and its entire sub-tree will not be considered.
Returns
the number of nodes removed
Examples
data(acme)
acme$Do(function(x) x$cost <- Aggregate(x, "cost", sum))
Prune(acme, function(x) x$cost > 700000)
print(acme, "cost")
Method Climb()
Climb a tree from parent to children, by provided criteria.
Arguments
...an attribute-value pairlist to be searched. For brevity, you can also provide a character vector to search for names.
node
The root Node of the tree or subtree to climb
Details
This method lets you climb the tree, from crutch to crutch. On each Node, the
Climb finds the first child having attribute value equal to the the provided argument.
See also Climb and Navigate
Climb(node, ...)
Returns
the Node having path ..., or NULL if such a path does not exist
#the following are all equivalent
Climb(acme, 'IT', 'Outsource')
Climb(acme, name = 'IT', name = 'Outsource')
Climb(acme, 'IT')$Climb('Outsource')
Navigate(acme, path = "IT/Outsource")
Climb(acme, name = 'IT')
Climb(acme, position = c(2, 1))
#or, equivalent:
Climb(acme, position = 2, position = 1)
Climb(acme, name = "IT", cost = 250000)
tree <- CreateRegularTree(5, 2)
tree$Climb(c("1", "1"), position = c(2, 2))$path
Method Navigate()
Navigate to another node by relative path.
Usage
Node$Navigate(path)
Arguments
pathA string or a character vector describing the path to navigate
node
The starting Node to navigate
Details
The path is always relative to the Node. Navigation
to the parent is defined by .., whereas navigation to a child
is defined via the child's name.
If path is provided as a string, then the navigation steps are separated
by '/'.
See also Navigate and Climb
Examples
data(acme)
Navigate(acme$Research, "../IT/Outsource")
Navigate(acme$Research, c("..", "IT", "Outsource"))
Method Get()
Traverse a Tree and Collect Values
Usage
Node$Get(
attribute,
...,
traversal = c("pre-order", "post-order", "in-order", "level", "ancestor"),
pruneFun = NULL,
filterFun = NULL,
format = FALSE,
inheritFromAncestors = FALSE,
simplify = c(TRUE, FALSE, "array", "regular")
)
Arguments
attributedetermines what is collected. The attribute can be
a.) the name of a field or a property/active of each Node in the tree, e.g. acme$Get("p") or acme$Get("position")
b.) the name of a method of each Node in the tree, e.g. acme$Get("levelZeroBased"), where e.g. acme$levelZeroBased <- function() acme$level - 1
c.) a function, whose first argument must be a Node e.g. acme$Get(function(node) node$cost * node$p)
...
in case the attribute is a function or a method, the ellipsis is passed to it as additional arguments.
traversal
defines the traversal order to be used. This can be
- 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.
Read the data.tree vignette for a detailed explanation of these traversal orders.
pruneFun
allows providing a prune criteria, i.e. a function taking a Node as an input, and returning TRUE or FALSE.
If the pruneFun returns FALSE for a Node, then the Node and its entire sub-tree will not be considered.
filterFun
allows providing a a filter, i.e. a function taking a Node as an input, and returning TRUE or FALSE.
Note that if filter returns FALSE, then the node will be excluded from the result (but not the entire subtree).
format
if FALSE (the default), no formatting is being used. If TRUE, then the first formatter (if any) found along the ancestor path is being used for formatting
(see SetFormat). If format is a function, then the collected value is passed to that function, and the result is returned.
inheritFromAncestors
if TRUE, then the path above a Node is searched to get the attribute in case it is NULL.
simplify
same as sapply, i.e. TRUE, FALSE or "array". Additionally, you can specify "regular" if
each returned value is of length > 1, and equally named. See below for an example.
Details
The Get method is one of the most important ones of the data.tree package. It lets you traverse a tree
and collect values along the way. Alternatively, you can call a method or a function on each Node.
See also Get, Node, Set, Do, Traverse
Returns
a vector containing the atrributes collected during traversal, in traversal order. NULL is converted
to NA, such that length(Node$Get) == Node$totalCount
Examples
data(acme)
acme$Get("level")
acme$Get("totalCount")
acme$Get(function(node) node$cost * node$p,
filterFun = isLeaf)
#This is equivalent:
nodes <- Traverse(acme, filterFun = isLeaf)
Get(nodes, function(node) node$cost * node$p)
#simplify = "regular" will preserve names
acme$Get(function(x) c(position = x$position, level = x$level), simplify = "regular")
Method Do()
Executes a function on a set of nodes
Usage
Node$Do(
fun,
...,
traversal = c("pre-order", "post-order", "in-order", "level", "ancestor"),
pruneFun = NULL,
filterFun = NULL
)
Arguments
funthe function to execute. The function is expected to be either a Method, or to take a
Node as its first argument
...
A name-value mapping of node attributes
traversal
defines the traversal order to be used. This can be
- 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.
Read the data.tree vignette for a detailed explanation of these traversal orders.
pruneFun
allows providing a prune criteria, i.e. a function taking a Node as an input, and returning TRUE or FALSE.
If the pruneFun returns FALSE for a Node, then the Node and its entire sub-tree will not be considered.
filterFun
allows providing a a filter, i.e. a function taking a Node as an input, and returning TRUE or FALSE.
Note that if filter returns FALSE, then the node will be excluded from the result (but not the entire subtree).
Details
See also Node, Get, Set, Traverse
Examples
data(acme)
acme$Do(function(node) node$expectedCost <- node$p * node$cost)
print(acme, "expectedCost")
Method Set()
Traverse a Tree and Assign Values
Usage
Node$Set(
...,
traversal = c("pre-order", "post-order", "in-order", "level", "ancestor"),
pruneFun = NULL,
filterFun = NULL
)
Arguments
...each argument can be a vector of values to be assigned. Recycled.
traversal
defines the traversal order to be used. This can be
- 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.
Read the data.tree vignette for a detailed explanation of these traversal orders.
pruneFun
allows providing a prune criteria, i.e. a function taking a Node as an input, and returning TRUE or FALSE.
If the pruneFun returns FALSE for a Node, then the Node and its entire sub-tree will not be considered.
filterFun
allows providing a a filter, i.e. a function taking a Node as an input, and returning TRUE or FALSE.
Note that if filter returns FALSE, then the node will be excluded from the result (but not the entire subtree).
Details
The method takes one or more vectors as an argument. It traverses the tree, whereby the values are picked
from the vector. Also available as OO-style method on Node.
See also Node, Get, Do, Traverse
Returns
invisibly returns the nodes (useful for chaining)
Examples
data(acme)
acme$Set(departmentId = 1:acme$totalCount, openingHours = NULL, traversal = "post-order")
acme$Set(head = c("Jack Brown",
"Mona Moneyhead",
"Dr. Frank N. Stein",
"Eric Nerdahl"
),
filterFun = function(x) !x$isLeaf
)
print(acme, "departmentId", "head")
Method clone()
The objects of this class are cloneable with this method.
Usage
Node$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.