descendants: Get descendants values
In VEZY/XploRer: Read, Write, Plot and Analyze MTG (Mutli-Scale Tree Graph) Files

Description Usage Arguments Details Value Examples

Get attribute values from the descendants (acropetal).

descendants(
  attribute,
  node = NULL,
  scale = NULL,
  symbol = NULL,
  link = NULL,
  continue = TRUE,
  self = FALSE,
  filter_fun = NULL,
  recursivity_level = NULL
)

`attribute`	Any node attribute (as a character)
`node`	The MTG node
`scale`	An integer vector for filtering descendant by their `.scale` (i.e. the SCALE from the MTG classes).
`symbol`	A character vector for filtering the names of the descendant `.symbol` (i.e. the SYMBOL column from the MTG classes).
`link`	A character vector for filtering the `.link` with the descendant
`continue`	Boolean. If `TRUE`, the function returns all nodes that are not filtered. If `FALSE`, stop at the first node that is filtered out.
`self`	Return the value of the current node (`TRUE`), or the ancestors only (`FALSE`, the default)
`filter_fun`	Any filtering function taking a node as input, e.g. `data.tree::isLeaf()`
`recursivity_level`	The maximum number of recursions allowed (considering filters). E.g. to get only the children, `recursivity_level = 1`, if children + their children: `recursivity_level = 2`. If `NULL` (the default), the function returns all values from the node to the root.

This function is mainly intended to be used with mutate_mtg(). In this case, the node argument can be left empty (or you can put node = node equivalently).

The attribute values from the descendant(s) of the node

filepath= system.file("extdata", "tree1h.mtg", package = "XploRer")
MTG = read_mtg(filepath)
node_8 = extract_node(MTG,"node_8")
# getting all descendants of node_8
descendants(attribute = "length", node = node_8)

# getting all descendants of node_8, but only the nodes with symbol "S":
descendants(attribute = "length", node = node_8, symbol = "S")

# getting all descendants of node_8, but only the nodes with symbol "S", and not
# recursively, i.e. we stop the search for a child if it is filtered out (we don't
# go to its own children)
descendants(attribute = "length", node = node_8, symbol = "S",
                       continue = FALSE)

# getting the children of node_8 (and not below):
descendants(attribute = "length", node = node_8, recursivity_level = 1)
# getting the children of node_8 and their children:
descendants(attribute = "length", node = node_8, recursivity_level = 2)
# getting the children of node_8 and their children, and filter for "S":
descendants(attribute = "length", node = node_8, symbol = "S", recursivity_level = 2)
# The function returns until node_12 because node_10 is not an "S" and is then filtered out
# which makes node_12 two levels below node.

# To get the descendants of a node but only for the nodes following it, not
# branching (e.g. for an axis):
descendants(attribute = "length", node = node_8, symbol = "S",
                       link = c("/","<"), continue = FALSE)

# To get the values for the leaves (i.e. the terminal node) only:
descendants(attribute = "length", node = node_8, filter_fun = data.tree::isLeaf)
# Note: prefer using leaves() instead as it takes scales into account.

# Length were observed at the "S" scale (S = segment of an axis between two branches),
# but we need the length at the axis scale, to do so:
mutate_mtg(MTG,
           axis_length = sum(descendants(attribute = "length", symbol = "S",
                                                   link = c("/","<"), continue = FALSE)),
           .symbol = "A")