Forest

Tutorial

2.4 Node positioning¶

Forest positions the nodes by a recursive bottom-up algorithm which, for every non-terminal node, computes the positions of the node’s children relative to their parent. By default, all the children will be aligned horizontally some distance down from their parent: the “normal” tree grows down. More generally, however, the direction of growth can change from node to node; this is controlled by option grow=⟨direction⟩.¹ The system computes and stores the positions of children using a coordinate system dependent on the parent, called an ls-coordinate system: the origin is the parent’s anchor; l-axis is in the direction of growth in the parent; s-axis is orthogonal to the l-axis (positive side in the counter-clockwise direction from \(l\)-axis); l stands for level, s for sibling. The example shows the ls-coordinate system for a node with grow=45.²

The l-coordinate of children is (almost) completely under your control, i.e. you set what is often called the level distance by yourself. Simply set option l to change the distance of a node from its parent.³ More precisely, l, and the related option s, control the distance between the (node) anchors of a node and its parent. The anchor of a node can be changed using option anchor: by default, nodes are anchored at their base; see [Tantau 2007, §16.5.1].) In the example below, positions of the anchors are shown by dots: observe that anchors of nodes with the same l are aligned and that the distances between the anchors of the children and the parent are as specified in the code.⁴

Positioning the chilren in the s-dimension is the job and raison d’etre of the package. As a first approximation: the children are positioned so that the distance between them is at least the value of option s sep (s-separation), which defaults to double PGF’s inner_xsep (and this is 0.3333em by default). As you can see from the example above, s-separation is the distance between the borders of the nodes, not their anchors!

A fuller story is that s sep does not control the s-distance between two siblings, but rather the distance between the subtrees rooted in the siblings. When the green and the yellow child of the white node are s-positioned in the example below, the horizontal distance between the green and the yellow subtree is computed. It can be seen with the naked eye that the closest nodes of the subtrees are the TP and the DP with a red border. Thus, the children of the root CP (top green DP and top yellow TP) are positioned so that the horizontal distance between the red-bordered TP and DP equals s sep.

Note that Forest computes the same distances between nodes regardless of whether the nodes are filled or not, or whether their border is drawn or not. Filling the node or drawing its border does not change its size. You can change the size by adjusting TikZ’s inner_sep and outer_sep [Tantau 2007, §16.2.2], as shown below:

(This looks ugly!) Observe that having increased outer sep makes the edges stop touching borders of the nodes. By (PGF’s) default, the outer sep is exactly half of the border line width, so that the edges start and finish precisely at the border.

Let’s play a bit and change the l of the root of the yellow subtree. Below, we set the vertical distance of the yellow TP to its parent to 3 cm: and the yellow submarine sinks diagonally … Now, the closest nodes are the higher yellow DP and the green VP.

Note that the yellow and green nodes are not vertically aligned anymore. The positioning algorithm has no problem with that. But you, as a user, might have, so here’s a neat trick. (This only works in the “normal” circumstances, which are easier to see than describe.)

We have changed DP’s l’s value via “augmented assignment” known from many programming languages: above, we have used l*=3 to triple l’s value; we could have also said l+=5mm or l-=5mm to increase or decrease its value by 5 mm, respectively. This mechanism works for every numeric and dimensional option in Forest.

Let’s now play with option s sep.

Surprised? You shouldn’t be. The value of s sep at a given node controls the s-distance between the subtrees rooted in the children of that node! It has no influence over the internal geometry of these subtrees. In the above example, we have set s_sep=0 only for the root node, so the green and the yellow subtree are touching, although internally, their nodes are not. Let’s play a bit more. In the following example, we set the s sep to: \(0\) at the last branching level (level 3; the root is level 0), to 2 mm at level 2, to 4 mm at level 1 and to 6 mm at level 0.

As we go up the tree, the nodes “spread.” At the lowest level, V and DP are touching. In the third level, the s sep of level 2 applies, so DP and V’ are 2 mm apart. At the second level we have two pairs of nodes, D and NP, and T and TP: they are 4 mm apart. Finally, at level 1, the s sep of level 0 applies, so the green and yellow DP are 6 mm apart. (Note that D and NP are at level 2, not 4! Level is a matter of structure, not geometry.)

As you have probably noticed, this example also demostrated that we can compute the value of an option using an (arbitrarily complex) formula. This is thanks to PGF’s module pgfmath. Forest provides an interface to pgfmath by defining pgfmath functions for every node option, and some other information, like the level we have used above, the number of children n children, the sequential number of the child n, etc. For details, see §3.18.

The final separation parameter is l sep. It determines the minimal separation of a node from its descendants. It the value of l is too small, then all the children (and thus their subtrees) are pushed away from the parent (by increasing their ls), so that the distance between the node’s and each child’s subtree boundary is at least l sep. The initial l can be too small for two reasons: either some child is too high, or the parent is too deep. The first problem is easier to see: we force the situation using a bottom-aligned multiline node. (Multiline nodes can be easily created using \\ as a line-separator. However, you must first specify the horizontal alignment using option align (see §3.7.1). Bottom vertical alignment is achieved by setting base=bottom; the default, unlike in TikZ, is base=top).

The defaults for l and l sep are set so that they “cooperate.” What this means and why it is necessary is a complex issue explained in §2.4.1, which you will hopefully never have to read … You might be out of luck, however. What if you needed to decrease the level distance? And nothing happened, like below on the left? Or, what if you used lots of parenthesis in your nodes? And got a strange vertical misalignment, like below on the right? Then rest assured that these (at least) are features not bugs and read §2.4.1.

2.4.1 The defaults, or the hairy details of vertical alignment¶

In this section we discuss the default values of options controlling the l-alignment of the nodes. The defaults are set with top-down trees in mind, so l-alignment is actually vertical alignment. There are two desired effects of the defaults. First, the spacing between the nodes of a tree should adjust to the current font size. Second, the nodes of a given level should be vertically aligned (at the base), if possible.

Let us start with the base alignment: TikZ’s default is to anchor the nodes at their center, while Forest, given the usual content of nodes in linguistic representations, rather anchors them at the base [Tantau 2007, §16.5.1]. The difference is particularly clear for a “phonological” representation:

The following example shows that the vertical distance between nodes depends on the current font size.

Furthermore, the distance between nodes also depends on the value of PGF’s inner_sep (which also depends on the font size by default: it equals 0.3333 em).

\[\index{l sep}=\mbox{height}(\mbox{strut})+\mbox{\texttt{inner ysep}}\]

The default value of s sep depends on inner_xsep: more precisely, it equals double inner_xsep).

Now a hairy detail: the formula for the default l.

\[\index{option>l}=\index{l sep}+2\cdot\mbox{\texttt{outer ysep}}+\mbox{total height}(\mbox{`dj'})\]

To understand what this is all about we must first explain why it is necessary to set the default l at all? Wouldn’t it be enough to simply set l sep (leaving l at 0)? The problem is that not all letters have the same height and depth. A tree where the vertical position of the nodes would be controlled solely by (a constant) l sep could result in a ragged tree (although the height of the child–parent edges would be constant).

The vertical misalignment of Adj in the right tree is a consequence of the fact that letter j is the only letter with non-zero depth in the tree. Since only l sep (which is constant throughout the tree) controls the vertical positioning, Adj, child of AdjP, is pushed lower than the other nodes on level 2. If the content of the nodes is variable enough (various heights and depths), the cumulative effect can be quite strong, see the right tree of example (29).

Setting only a default l sep thus does not work well enough in general. The same is true for the reverse possibility, setting a default l (and leaving l sep at 0). In the example below, the depth of the multiline node (anchored at the top line) is such that the child–parent edges are just too short if the level distance is kept constant. Sometimes, misalignment is much preferred …

Thus, the idea is to make l and l sep work as a team: l prevents misalignments, if possible, while l sep determines the minimal vertical distance between levels. Each of the two options deals with a certain kind of a “deviant” node, i.e. a node which is too high or too deep, or a node which is not high or deep enough, so we need to postulate what a standard node is, and synchronize them so that their effect on standard nodes is the same.

By default, Forest sets the standard node to be a node containing letters d and j. Linguistic representations consist mainly of letters, and in the TeX’s default Computer Modern font, d is the highest letter (not character!), and j the deepest, so this decision guarantees that trees containing only letters will look nice. If the tree contains many parentheses, like the right tree of example (29), the default will of course fail and the standard node needs to be modified. But for many applications, including nodes with indices, the default works.

The standard node can be changed using macro \ forestStandardNode; see 3.19.