Numerous additional parameters can be supplied. For example, by default vtree produces a horizontal tree (that is, a tree that grows from left to right). To generate a vertical tree, specify horiz=FALSE.
Mini tutorial
To display a variable tree for a single variable, say Severity, use the following command:
Next, consider a vertical variable tree with two variables, Severity and Sex. A less colorful display with more spacing can be requested by specifying plain=TRUE:
Percentages
By default, “valid percentages” are shown, i.e. the denominator is the total number of non-missing values. In the case of Severity, there are 6 missing values, so the denominator is 46 - 6 , or 40. There are 19 Mild cases, and 19/40 = 0.475 so the percentage shown is 48%. No percentage is shown in the NA node since missing values are not included in the denominator.
If you prefer that the denominator represent the complete set of observations (including any missing values), specify vp=FALSE. With this setting, a percentage will be shown in each of the nodes, including any NA nodes.
If you don’t wish to see percentages, specify showpct=FALSE, and if you don’t wish to see counts, specify showcount=FALSE.
Displaying a legend and hiding node labels
To display a legend, specify showlegend=TRUE. Next to each level of the tree, the variable name is displayed together with color discs and the values they correspond to. For each of the values, overall (marginal) counts are shown, together with percentages.
When the legend is shown, the node labels become redundant, since the colors identify the values of the variables (although the labels may aid readability). If you prefer, you can hide the node labels, by specifying shownodelabels=FALSE:
The legend shows how colors are assigned to the different values of each variable, and additionally provides marginal (that is, overall) counts and percentages for each variable. Since Severity is the first variable in the tree—i.e., it is not nested within another variable— the marginal counts and percentages for Severity are identical to those displayed in the nodes. In contrast, for Sex, the marginal counts and percentages are different from what is shown in the nodes because the nodes for Sex are nested with levels of Severity.
(Unfortunately the NA circle in the legend is oddly sized and positioned due to an issue with the corresponding unicode symbols.)
Putting node labels on the same line as the counts and percentages
When a variable tree is large, it can be difficult to display it in a readable way. One approach that helps is to display the tree horizontally and also to put the node labels on the same line as the counts and percentage by specifying sameline=TRUE. For example, the following results in nodes with single-lines labels such as Moderate, 16 (40%), etc.:
Hiding variable names
By default, next to each level of the tree, vtree shows the variable name. These can be removed by specifying showvarnames=FALSE.
Text wrapping
By default, vtree wraps text onto the next line whenever a space occurs after at least 20 characters. This can be adjusted, for example, to 15 characters, by specifying splitwidth=15. To disable line splitting, specify splitwidth=Inf. Text wrapping in the legend is controlled independently. To set the splitting in the legend to 8 characters, specify lsplitwidth=8. Also note that in the legend, text wrapping can take place not only at spaces, but also at any of the following characters: . - + _ = /
This concludes the mini-tutorial. vtree has many more features, described in the following sections.
Pruning
When a variable tree gets too big, or you are only interested in certain parts of the tree, it may be useful to remove some nodes along with their descendants. This is known as pruning. For convenience, vtree provides several different ways to prune a tree, described below.
The prune parameter
Suppose you don’t want the tree to include individuals whose disease is Mild or Moderate. Specifying prune=list(Severity=c("Mild","Moderate")) removes those nodes, and all of their descendants:
In general, the argument of the prune parameter is a list with an element named for each variable you wish to prune. In the example above, the list has a single element, named Severity. In turn, that element is a vector c("Mild","Moderate") indicating the values of Severity to prune.
Caution: Once a variable tree has been pruned, it is no longer complete. This can sometimes be confusing since not all observations are represented at certain levels of the tree. It is particularly important to avoid pruning missing value nodes, since this makes it hard to interpret “valid” percentages (i.e. percentages calculated using the number of non-missing observations as denominator).
The keep parameter
Sometimes it is more convenient to specify which nodes should be retained rather than which ones should be discarded. The keep parameter is used for this purpose, and can thus be considered the complement of the prune parameter.
For example, to retain only the Moderate Severity node:
Missing value nodes and the keep parameter
It is important to note how the keep parameter functions when missing values are present. Consider a variable tree for the Severity variable, shown on the left with so-called “valid” percentages. These are percentages calculated using the number of non-missing observations as denominator (which is the default, specified by vp=TRUE). On the right is the same tree, but with percentages calculated using the total number of observations as the denominator.
Suppose we use keep to retain only the Moderate node.
Note that in the tree on the left (which uses valid percentages), the NA node is retained. This is done so that the percentage of Moderate cases can be interpreted.. (There are 16 Moderate cases, and a total of 40 non-missing cases, which is 40%.)
On the right, the NA node has been removed, because the denominator (46) doesn’t depend on the number of missing values.
The prunebelow parameter
A disadvantage of the prune parameter is that in the resulting tree, the counts shown in child nodes may not add up to the counts shown in the parent node. For example in the variable tree above, of a total of 46 patients, 5 have Severe disease and Severity is unknown for 6. One might wonder what happened to the other 35 patients.
A solution to this problem is to retain the specified nodes, but to prune below them (i.e. to prune their descendants). In the present example, this means that the Mild and Moderate nodes will be shown, but not their descendants. The prunebelow parameter is used to do this, and its argument has the same form as for the prune parameter.
The follow parameter
The complement of the prunebelow function is the follow function. Instead of specifying which nodes should be pruned below, this allows you to specify which nodes should be “followed” (that is, not pruned below).
The prunesmaller parameter
As a variable tree grows it can become difficult to see the forest for the tree. For example, consider the following variable tree:
One solution is to prune nodes that contain small numbers of observations. For example if you want to only see nodes with at least 3 observations, you can specify prunesmaller=3, as in this example:
As with the keep parameter, when vp=TRUE (which is the default, and means that valid percentages are shown), nodes represent missing values will not be pruned. (As noted in the section on the keep parameter, this is because percentages are confusing when missing values are not shown.) When vp=FALSE, missing nodes will be pruned (if they are small enough).
Text and text formatting
Graphviz, the open source graph visualization software that vtree is built on, supports a variety of text formatting (including boldface, colors, etc.). This is used in vtree to control formatting of text such as node labels.
Markdown-style codes for text formatting
By default, the vtree package uses markdown-style codes for text formatting.
\n means insert a line break\n*l means make the preceding line left-justified and insert a line break*...* means display text in italics**...** means display text in bold^...^ means display text in superscript (using 10 point font)~...~ means display text in subscript (using 10 point font)%%red ...%% means display text in red (or whichever color is specified)
HTML-like codes for text formatting
As an alternative, if you specify HTMLtext=TRUE you can use “HTML-like labels” (implemented in Graphviz), including:
<BR/> means insert a line break<BR ALIGN='LEFT'/> means make the preceding line left-justified and insert a line break<I> ... </I> means display text in italics<B> ... </B> means display text in bold<SUP> ... </SUP> means display text in superscript, but note that the font size does not change<SUB> ... </SUB> means display text in subscript but again note that the font size does not change<FONT POINT-SIZE='10'> ... </FONT> means set font to 10 point<FONT FACE='Times-Roman'> ... </FONT> means set font to Times-Roman<FONT COLOR='red'> ... </FONT> means set font to red
See https://www.graphviz.org/doc/info/shapes.html#html for more details.
Adding text to nodes using the text parameter
Suppose you wish to add the italicized text “Excluding new diagnoses” to any Mild nodes in the tree. The parameter text lets you add text to nodes. It is specified as a list with an element named for each variable. In the example below the list has one element, named Severity. That element in turn is a vector c(Mild="\n*Excluding\nnew diagnoses*") indicating that the Mild node should include additional text using Markdown-style formatting (i.e. there is a linebreak and the asterisks around the text indicate that it should be displayed in italics):
Targeted text using the ttext parameter
In the example above, suppose that new diagnoses are only excluded from Mild cases in Group B. But the text parameter is used to add text to all Mild nodes. Thus, in situations like this, the text parameter is not sufficient. Instead, you can use the ttext parameter to target exactly which nodes should have the specified text.
The ttext parameter requires that you specify the full path from the root of the tree to the node in question, along with the text in question. The ttext parameter is specified as a list so that multiple targeted text strings can be specified at once. For example:
vtree(FakeData,"Group Severity",horiz=FALSE,showvarnames=FALSE,
ttext=list(
c(Group="B",Severity="Mild",text="\n*Excluding\nnew diagnoses*"),
c(Group="A",text="\nSweden"),
c(Group="B",text="\nNorway")))
Specification of variables
For convenience, vtree allows you to specify variable names (separated by whitespace) in a single character string. If, however, any of the variable names have internal spaces, the variable names must be specified as a vector of character strings.
Additionally, there are several modifiers that can be used to change the way variables are represented in a tree.
prefix is.na:
If an individual variable name is preceded by is.na:, that variable will be replaced by a missing value indicator in the variable tree. (This differs from the check.is.na parameter, described later, which is used to replace all of the specified variables with missing value indicators.)
prefixes stem: and rc:
In datasets exported from REDCap, checkboxes are represented using multiple variables. The stem: prefix makes it easier to work with them. This is described in the section on REDCap checkboxes later in this vignette.
prefix tri:
The tri: prefix is useful for identifying values of a numeric variable that are extreme compared to the other values in a node. Note: Unlike other variable specifications, which take effect at the level of the entire data frame, the tri: prefix takes effect within each node.
The effect of this variable specification is to trichotomize the values of a numeric variable, i.e. to divide them into three groups:
“mid”: values within plus or minus 1.5×IQR of the median,
“high”: values more than 1.5×IQR above the median,
“low”: values more than 1.5×IQR below the median.
suffix *
Specifying Ind* matches all variable names that start with Ind. In FakeData these are Ind1, Ind2, and Ind3.
The * suffix matches all variable names
suffix #
Specifying Ind# matches all variable names that start with Ind and end with a numeric digit, namely Ind1, Ind2, and Ind3. (In this particular case, this is the same result as using Ind*).
specification variable=value
When a variable takes on a large number of different values, the resulting variable tree will very large. One solution is to prune the tree, for example by keeping just the node corresponding to one value of a particular variable. An alternative is to specify the value of the variable that is of primary interest and vtree will dichotomize the variable at that value. For example if Severity=Mild is specified, the Severity variable will be dichotomized between Mild and Not Mild.
specifications variable<value, variable>value
These two specifications are used to dichotomize a numeric variable, splitting above and below a specified value. This can be useful for identifying subsets with extreme values.
Displaying summary statistics in nodes
It is often useful to display information about other variables (apart from those that define the tree) in the nodes of a variable tree. This is particularly useful for numeric variables, which generally cannot be used to build the tree since they have too many distinct values. For example, we might wish to display the mean age for individuals in each node. Or we might wish to list the ID numbers of the individuals in each node. The summary argument can be used to flexibly specify additional information to display.
A simple example
The argument of the summary parameter is a character string with the following structure:
It starts with the name of the variable for which a summary is desired. (We’ll see later that variable specifications and expressions can also be used, as long as they do not contain any spaces.)
Next there is a space.
The remainder of the string specifies what to display, with text as well as special codes to indicate the type of summary desired and to control which nodes display the summary, etc.
For example %mean% indicates that the mean of the specified variable should be shown. Thus to display the mean of the numeric variable Score, you could specify summary="Score \nmean score: %mean%". Note that the part of the string following the first space is "\nmean score: %mean%". This specifies that in each node, after the usual frequency and percentage, the summary should start on a new line with the words “mean score:” followed by the mean.
To see the means without any decimals, the cdigits parameter can be used; for example:
The following codes can be used to show summary information:
%mean% |
mean |
%SD% |
standard deviation |
%sum% |
sum |
%min% |
minimum |
%max% |
maximum |
%pX% |
Xth percentile (e.g. p50 means the 50th percentile) |
%median% |
median, i.e. p50 |
%IQR% |
IQR, i.e. p25, p75 |
%npct% |
frequency and percentage of a logical variable. By default “valid percentages” are used. Any missing values are also reported. |
%pct% |
same as %npct% but percentage only (with no parentheses). |
%list% |
list of individual values, separated by commas |
%listlines% |
list of individual values, each on a separate line |
%mv% |
the number of missing values |
%nonmv% |
the number of non-missing values |
%v% |
the name of the variable |
The summary argument can use any number of these codes, mixed with text and formatting codes.
More than one variable
Sometimes it is useful to display summary information for more than one variable. To do this, specify summary as a vector of character strings:
The %list% code
It is sometimes convenient to see individual values of a variable in each node. For example you might want to see ID numbers. To do this, use the %list% code. By default this information will be displayed in each node. When a value occurs more than once in the subset, it will be followed by a count of the number of repetitions in parentheses. The %list% code separates values by commas. Alternatively, the %listlines% code can be used to put each value on a new line.
When there are many IDs, it is often convenient to truncate the output. If you specify %trunc=N%, summary information will be truncated after N characters with “…”.
The %noroot%, %leafonly%, %var=v%, and %node=n% codes
By default, summary information is shown in all nodes. However, it may also be convenient to only show it in specific nodes. The following codes are available:
%noroot% |
all nodes except the root |
%leafonly% |
leaf nodes |
%var=v% |
nodes of variable v |
%node=n% |
nodes named n |
Specification of variables in the summary argument
Variables in the summary parameter can also be specified in a way similar to the specification of variables for structuring a variable tree. For example, if we wish to know the proportion of patients in each node whose Category is single, we specify Category=single in the summary argument.
Continuous variables such as Score can be dichotomized using notation such as Score>10 or Score<20.
R expressions in the summary argument
Rather than starting the summary argument with a variable name, an R expression involving variables in the data frame can be given, as long as it does not contain any spaces.
Expressions involving functions can also be used; for example sqrt(abs(Post/Pre)).
Pattern trees and pattern tables
Each node in a variable tree provides the frequency of a particular combination of values of the variables. The leaf nodes represent all the observed combinations of values of all of the variables. For example, in a variable tree for Severity and Sex, the leaf nodes correspond to Mild F, Mild M, Moderate F, Moderate M, etc. These combinations, or “patterns”, can be treated as an additional variable. And if this new pattern variable is used as the first variable in a tree, then the branches of the tree will be simplified: each branch will represent a unique pattern, with no sub-branches. A “pattern tree” can be easily produced by specifying pattern=TRUE:
Pattern trees are easier to read than ordinary variable trees, but they involve a considerable loss of information, since they only represent the nth-level subsets (where n is the number of variables).
Note that by default, when pattern=TRUE is specified, the root node is not shown (in order to simplify the display). A disadvantage of this is that the total sample size is not shown. You can override this behavior by specifying showroot=TRUE.
A pattern tree has two other special characteristics. First, note that after the first level (representing pattern), counts and percentages are not shown, since they are not informative: by definition, all nodes within a branch have the same count. Second, note that in place of arrows, undirected line segments are shown. This is because, unlike in a regular variable tree, the order of variables is irrelevant in a pattern tree. Sometimes, however, the variables do have a natural ordering, as in the case of longitudinal variables. To show arrows, specify seq=TRUE instead of pattern=TRUE, and a “sequence” (i.e. an ordered pattern) will be shown.
Summaries can be shown in pattern trees (using the summary parameter), but they only appear in the pattern node (or the sequence node if seq=TRUE).
Pattern tables
A pattern tree has the same structure as a table. Indeed, it may be more convenient to produce a table rather than a tree. A data frame containing the information from the pattern tree can be exported by specifying ptable=TRUE:
## n pct Severity Sex
## 1 2 4 Severe F
## 2 3 7 <NA> F
## 3 3 7 <NA> M
## 4 3 7 Severe M
## 5 5 11 Moderate M
## 6 8 17 Mild M
## 7 11 24 Mild F
## 8 11 24 Moderate F
The pattern table includes a column for the counts from the pattern nodes, and a column for percentages. Compared to a variable tree, this table is much more compact, and may be more suitable for use in a manuscript.
Indicator variables
Pattern trees are useful for indicator variables, i.e. variables that take values like 0/1, no/yes, FALSE/TRUE, etc. For convenience in this section, we’ll refer to 0 (or no, FALSE, etc.) as a negative and 1 (or yes, TRUE, etc.) as an affirmative.
The variables Ind1 through Ind4 in FakeData are 0/1 indicator variables. If these variables are interpreted as representing set membership (0 = non-member, 1 = member), then a pattern tree is an alternative representation of a Venn diagram. If you specify Venn=TRUE, the nodes (except for the pattern nodes) will be blank, with only their shade indicating their value (dark = 1, light = 0, white = missing).
A pattern tree for indicator variables provides all the information that a Venn diagram represents, but unlike a Venn diagram, missing values are also represented. This can also be shown as a pattern table. For example:
## n pct Ind1 Ind2
## 1 1 2 <NA> 0
## 2 10 22 1 0
## 3 11 24 0 1
## 4 12 26 0 0
## 5 12 26 1 1
The VennTable function
For indicator variables, there is an extra function, VennTable, which converts the pattern table to a matrix of character strings and adds some additional totals.
## n pct Ind2 Ind1
## "1" "2" "0" NA
## "10" "22" "0" "10"
## "11" "24" "11" "0"
## "12" "26" "0" "0"
## "12" "26" "12" "12"
## Total "46" "100" "" ""
## N "" "" "23" "22"
## pct "" "" "50" "48"
By default in R, when a matrix of character strings is printed, quotation marks are displayed around each element. Unfortunately the result is unattractive. Instead it’s helpful to call the print function and specify quote=FALSE:
## n pct Ind2 Ind1
## 1 2 0 <NA>
## 10 22 0 10
## 11 24 11 0
## 12 26 0 0
## 12 26 12 12
## Total 46 100
## N 23 22
## pct 50 48
Without all those quotation marks, it’s easier to see what VennTable adds:
the total sample size (46) and percentage (100), and
the total number (N) of affirmatives for each variable, together with a percentage.
The VennTable function can also be used in an R Markdown document. Specifying markdown=TRUE generates a pandoc markdown pipetable, with several formatting tweaks:
the rows and columns of the table are transposed
affirmatives are represented by checkmarks
negatives are represented by spaces
missing values are represented by dashes (which can be changed with the NAcode parameter).
To display the table in R Markdown, use this inline call:
| n |
1 |
10 |
11 |
12 |
12 |
46 |
|
|
| % |
2 |
22 |
24 |
26 |
26 |
100 |
|
|
| Ind2 |
|
|
✔ |
|
✔ |
|
23 |
50 |
| Ind1 |
- |
✔ |
|
|
✔ |
|
22 |
48 |
VennTable has some additional parameters. The checked parameter is used to specify values that should be interpreted as affirmative. By default, it is set to c("1","TRUE","Yes","yes","N/A"). Similarly, the unchecked parameter is used to specify values that should be interpreted as negative, with default c("0","FALSE","No","no","not N/A").
Using the summary parameter in pattern tables
The summary parameter can also be used in pattern tables. If a single summary is requested, it appears in the summary_1 variable in the data frame. Additional summaries appear as summary_2, summary_3, etc.
## n pct Severity Sex summary_1 summary_2
## 1 2 4 Severe F 28.0 -0.4
## 2 3 7 <NA> F 6.3 -0.1
## 3 3 7 <NA> M 23.7 -0.9
## 4 3 7 Severe M 44.0 -0.3
## 5 5 11 Moderate M 8.2 -0.7
## 6 8 17 Mild M 6.3 0.2
## 7 11 24 Mild F 15.7 -0.4
## 8 11 24 Moderate F 21.5 0.0
Checking for missing values with the check.is.na parameter
If check.is.na=TRUE is specified, each variable is replaced by an indicator of whether or not it is missing, and pattern=TRUE is automatically set. As when Venn=TRUE is specified, all nodes except for the pattern node are blank, and only their shade indicates missing (dark) or not (light). Whereas the variables used to build a variable tree are normally categorical, in this situation non-categorical variables can be used, because their missingness is represented instead of their actual values.
Specifying ptable=TRUE produces this information in a data frame, and calling VennTable shows additional information. To display the table in R Markdown, use this inline call:
| n |
1 |
1 |
1 |
1 |
2 |
4 |
4 |
32 |
46 |
|
|
| % |
2 |
2 |
2 |
2 |
4 |
9 |
9 |
70 |
100 |
|
|
| MISSING_Age |
✔ |
|
|
|
✔ |
|
✔ |
|
|
7 |
15 |
| MISSING_Severity |
|
|
|
|
✔ |
✔ |
|
|
|
6 |
13 |
| MISSING_Pre |
✔ |
✔ |
✔ |
|
|
|
|
|
|
3 |
7 |
| MISSING_Post |
|
✔ |
|
✔ |
|
|
|
|
|
2 |
4 |
The rows n and pct represent the frequency and percentage of the total number of cases for each pattern of missingness, and the columns N and pct on the right-hand side represent the frequency and percentage of missingness for each variable.
It may be useful to identify the ID numbers for these patterns. Here the results are truncated to 15 characters:
## n pct MISSING_Severity MISSING_Age MISSING_Pre MISSING_Post summary_1
## 1 1 2 not N/A N/A N/A not N/A 124
## 2 1 2 not N/A not N/A N/A N/A 118
## 3 1 2 not N/A not N/A N/A not N/A 108
## 4 1 2 not N/A not N/A not N/A N/A 104
## 5 2 4 N/A N/A not N/A not N/A 112, 135
## 6 4 9 N/A not N/A not N/A not N/A 103, 116, 126, ...
## 7 4 9 not N/A N/A not N/A not N/A 105, 119, 128, ...
## 8 32 70 not N/A not N/A not N/A not N/A 101, 102, 106, ...
REDCap checkboxes
In datasets exported from REDCap, checkboxes (i.e. the boxes where you select all that apply) are represented in a special way. For each item in a checklist, a separate variable is created. Suppose survey respondents were asked to select which flavors of ice cream (Chocolate, Vanilla, Strawberry) they like. Within REDCap, the variable name for this list of checkboxes is IceCream, but when the dataset is exported, individual variables IceCream___1 (representing Chocolate), IceCream___2 (Vanilla), and IceCream___3 (Strawberry) are created. When the dataset is read into R, the names of the flavors are embedded in the attributes of these variables.
prefix stem:
vtree includes a feature designed to make REDCap checkbox variables easier to use. Instead of typing:
you can use a special syntax where stem: precedes the REDCap variable name:
By default, vtree will also extract the names of the choices and create variables with those names. (This can be disabled by specifying choicechecklist=FALSE.)
An especially convenient way to display checkbox variables with vtree is:
prefix rc:
Alternatively, if you wish to only examine specific REDCap checkbox items, the rc: prefix can be used. For example to examine results for just Chocolate and Strawberry:
Examining the DOT script generated by vtree
Specifying getscript=TRUE lets you capture the DOT script representing a variable tree. (DOT is a graph description language used by Graphviz, which is used by DiagrammeR, which is used by vtree!). Here is an example:
digraph vtree {
graph [layout = dot, compound=true, nodesep=0.1, ranksep=0.5, fontsize=12]
node [fontname = Helvetica, fontcolor = black,shape = rectangle, color = black,margin=0.1]
rankdir=LR;
Node_L0[style=invisible]
Node_L1[label=<<FONT POINT-SIZE="18"><FONT COLOR="#DE2D26"><B>Severity </B></FONT></FONT><BR/>> shape=none margin=0]
edge[style=invis];
Node_L0->Node_L1
edge[style=solid]
Node_1->Node_2 Node_1->Node_3 Node_1->Node_4 Node_1->Node_5
Node_1[label=<46> color=black style="rounded,filled" fillcolor=<#EFF3FF>]
Node_2[label=<Mild<BR/>19 (48%)> color=black style="rounded,filled" fillcolor=<#FEE0D2> ]
Node_1[label=<46> color=black style="rounded,filled" fillcolor=<#EFF3FF>]
Node_3[label=<Moderate<BR/>16 (40%)> color=black style="rounded,filled" fillcolor=<#FC9272> ]
Node_1[label=<46> color=black style="rounded,filled" fillcolor=<#EFF3FF>]
Node_4[label=<Severe<BR/>5 (12%)> color=black style="rounded,filled" fillcolor=<#DE2D26> ]
Node_1[label=<46> color=black style="rounded,filled" fillcolor=<#EFF3FF>]
Node_5[label=<NA<BR/>6> color=black style="rounded,filled" fillcolor=<white> ]
}
If you wish to directly edit this code, it can can be pasted into an online Graphviz editor, for example:
https://dreampuf.github.io/GraphvizOnline
http://magjac.com/graphviz-visual-editor/
