An R6 class to represent a decision tree model.
Andrew J. Sims andrew.sims@newcastle.ac.uk
rdecision::Graph -> rdecision::Digraph -> rdecision::Arborescence -> DecisionTree
Inherited methods
rdecision::Graph$degree()rdecision::Graph$edge_along()rdecision::Graph$edge_at()rdecision::Graph$edge_index()rdecision::Graph$graph_adjacency_matrix()rdecision::Graph$has_edge()rdecision::Graph$has_vertex()rdecision::Graph$is_simple()rdecision::Graph$neighbours()rdecision::Graph$order()rdecision::Graph$size()rdecision::Graph$vertex_along()rdecision::Graph$vertex_at()rdecision::Graph$vertex_index()rdecision::Digraph$as_DOT()rdecision::Digraph$digraph_adjacency_matrix()rdecision::Digraph$digraph_incidence_matrix()rdecision::Digraph$direct_predecessors()rdecision::Digraph$direct_successors()rdecision::Digraph$is_acyclic()rdecision::Digraph$is_arborescence()rdecision::Digraph$is_connected()rdecision::Digraph$is_polytree()rdecision::Digraph$is_tree()rdecision::Digraph$is_weakly_connected()rdecision::Digraph$paths()rdecision::Digraph$topological_sort()rdecision::Digraph$walk()rdecision::Arborescence$is_leaf()rdecision::Arborescence$is_parent()rdecision::Arborescence$postree()rdecision::Arborescence$root()rdecision::Arborescence$root_to_leaf_paths()rdecision::Arborescence$siblings()
new()Create a new decision tree.
DecisionTree$new(V, E)VA list of nodes.
EA list of edges.
The tree must consist of a set of nodes and a set of edges which satisfy the conditions given in the details section of this class.
A DecisionTree object
decision_nodes()Find the decision nodes in the tree.
DecisionTree$decision_nodes(what = "node")whatA character string defining what to return. Must be one of "node", "label" or "index".
A list of DecisionNode objects (for what="node"); a list
of character strings (for what="label"); or a list of integer indexes of
the decision nodes (for what="index").
chance_nodes()Find the chance nodes in the tree.
DecisionTree$chance_nodes()A list of ChanceNode objects.
leaf_nodes()Find the leaf nodes in the tree.
DecisionTree$leaf_nodes(what = "node")whatOne of "node" (returns Node objects), "label" (returns the leaf node labels) or "index" (returns the vertex indexes of the leaf nodes).
A list of LeafNode objects (for what="node"); a list
of character strings (for what="label"); or a list of integer indexes of
the decision nodes (for what="index").
actions()Find the edges that have the specified decision node as their source.
DecisionTree$actions(d)dA decision node.
A list of Action edges.
modvars()Find all the model variables of type ModVar.
DecisionTree$modvars()Find ModVars that have been specified as values
associated with the nodes and edges of the tree.
A list of ModVars.
modvar_table()Tabulate the model variables.
DecisionTree$modvar_table(expressions = TRUE)expressionsA logical that defines whether expression model variables should be included in the tabulation.
Data frame with one row per model variable, as follows:
DescriptionAs given at initialization.
UnitsUnits of the variable.
DistributionEither the uncertainty distribution, if
it is a regular model variable, or the expression used to create it,
if it is an ExprModVar.
MeanMean; calculated from means of operands if an expression.
EExpectation; estimated from random sample if expression, mean otherwise.
SDStandard deviation; estimated from random sample if expression, exact value otherwise.
Q2.5p=0.025 quantile; estimated from random sample if expression, exact value otherwise.
Q97.5p=0.975 quantile; estimated from random sample if expression, exact value otherwise.
EstTRUE if the quantiles and SD have been estimated by random sampling.
draw()Draw the decision tree to the current graphics output.
DecisionTree$draw(border = FALSE)borderIf TRUE draw a light grey border around the plot area.
Uses the algorithm of Walker (1989) to distribute the nodes compactly (see the Arborescence class help for details).
No return value.
is_strategy()Tests whether a strategy is valid.
DecisionTree$is_strategy(strategy)strategyA list of Action edges.
A strategy is a unanimous prescription of an action in each decision node, specified as a list of actions. This checks whether the strategy is valid for this decision tree.
TRUE if the strategy is valid for this tree. Returns FALSE if the list of Action edges are not a valid strategy.
strategy_table()Find all potential strategies for the decision tree.
DecisionTree$strategy_table(what = "index", select = NULL)whatA character string defining what to return. Must be one of "label" or "index".
selectA single strategy (given as a list of action edges, with one action edge per decision node). If provided, only that strategy is selected from the returned table. Intended for tabulating a single strategy into a readable form.
A strategy is a unanimous prescription of the actions at each decision node. If there are decision nodes that are descendants of other nodes in the tree, the strategies returned will not necessarily be unique.
A data frame where each row is a potential strategy and each column is a Decision Node. Values are either the index of each action edge, or their label. The row names are the edge labels of each strategy, concatenated with underscores.
strategy_paths()Find all paths walked in each possible strategy.
DecisionTree$strategy_paths()A strategy is a unanimous prescription of an action in each decision node. Some paths can be walked in more than one strategy, if there exist paths that do not pass a decision node.
A data frame, where each row is a path walked in a strategy. The
structure is similar to that returned by strategy_table but
includes an extra column, Leaf which gives the leaf node index of
each path, and there is one row for each path in each strategy.
edge_properties()Properties of all actions and reactions as a matrix.
DecisionTree$edge_properties()Gets the properties (probability, cost, benefit) of each action and reaction in the decision tree in matrix form.
A numeric matrix with one row per edge, and with four columns:
the index of the edge, the conditional probability of traversing the
edge, the cost of traversing the edge and the benefit associated with
traversing the edge. The column names are index,
probability, cost, benefit and the row names are
the labels of the edges.
evaluate_walks()Evaluate the components of pay-off associated with a set of walks in the decision tree.
DecisionTree$evaluate_walks(W = NULL, Wi = NULL)WA list of root-to-leaf walks. A walk is a sequence of edges (actions and reactions), stored as a list. Each walk must start with an edge whose source is the root node and end with an edge whose target is a leaf node. The list of walks is normally the walks associated with all the root to leaf paths in a tree.
WiAs W but with edge indices instead of Edge objects. One of W and Wi must be NULL. It is more efficient to provide Wi during PSA, where the paths do not change between cycles, to avoid repeated conversion of edges to indices.
For each walk, probability, cost, benefit and utility are calculated. There is minimal checking of the argument because this function is intended to be called repeatedly during tree evaluation, including PSA.
A matrix (pay-off table) with one row per path and columns organized as follows:
LeafThe unique identifier of the path, taken to be the index of the terminal (leaf) node.
ProbabilityThe probability of traversing the pathway.
Path.CostThe cost of traversing the pathway.
Path.BenefitThe benefit derived from traversing the pathway.
Path.UtilityThe utility associated with the outcome (leaf node).
Path.QALYThe QALYs associated with the outcome (leaf node).
CostPath.Cost \(*\) probability of traversing the
pathway.
BenefitPath.Benefit \(*\) probability of
traversing the pathway.
UtilityPath.Utility \(*\) probability of
traversing the pathway.
QALYPath.QALY \(*\) probability of traversing the
pathway.
evaluate()Evaluate each strategy.
DecisionTree$evaluate(setvars = "expected", N = 1, by = "strategy")setvarsOne of "expected" (evaluate with each model variable at its mean value), "random" (sample each variable from its uncertainty distribution and evaluate the model), "q2.5", "q50", "q97.5" (set each model variable to its 2.5%, 50% or 97.5% quantile, respectively, and evaluate the model) or "current" (leave each model variable at its current value prior to calling the function and evaluate the model).
NNumber of replicates. Intended for use with PSA
(modvars="random"); use with modvars = "expected"
will be repetitive and uninformative.
byOne of "path", "strategy", "run". If "path", the table has one row per path walked per strategy, per run, and includes the label of the terminating leaf node to identify each path. If "strategy" (the default), the table is aggregated by strategy, i.e. there is one row per strategy per run. If "run", the table has one row per run and uses concatenated strategy names and one (cost, benefit, utility, QALY) column for each strategy.
Starting with the root, the function works though all possible paths to leaf nodes and computes the probability, cost, benefit and utility of each, then optionally aggregates by strategy or run. The columns of the returned data frame are:
by="path"LeafThe label of terminating leaf node
<label of first decision node>label of action leaving the node
<label of second decision node (etc.)>label of action
ProbabilityProbability of traversing the path
CostCost of traversing the path
BenefitBenefit of traversing the path
UtilityUtility of traversing the path
QALYQALY of traversing the path
RunRun number
by="strategy"<label of first decision node>label of action leaving the node
<label of second decision node (etc)label of action
RunRun number
Probability\(\Sigma p_i\) for the run (1)
CostAggregate cost of the strategy
BenefitAggregate benefit of the strategy
UtilityAggregate utility of the strategy
QALYAggregate QALY of the strategy
by="run"RunRun number
Probability.<S>Probability for strategy S
Cost.<S>Cost for strategy S
Benefit.<S>Benefit for strategy S
Utility.<S>Benefit for strategy S
QALY.<S>QALY for strategy S
where <S> is string composed of the action labels in strategy S
concatenated with an underscore and there will be one probability etc.,
column for each strategy.
A data frame whose columns depend on by; see "Details".
tornado()Create a "tornado" diagram.
DecisionTree$tornado(
index,
ref,
outcome = "saving",
exclude = NULL,
draw = TRUE
)indexThe index strategy (option) to be evaluated.
refThe reference strategy (option) with which the index strategy will be compared.
outcomeOne of "saving" or "ICER". For
"saving" (e.g. in cost consequence analysis), the x axis is cost
saved (cost of reference minus
cost of index), on the presumption that the new technology will be cost
saving at the point estimate. For "ICER" the x axis is
\(\Delta C/\Delta E\) and is expected to be positive at the point
estimate (i.e. in the NE or SW quadrants of the cost-effectiveness
plane), where \(\Delta C\) is cost of index minus cost of reference,
and \(\Delta E\) is utility of index minus utility of reference.
excludeA list of descriptions of model variables to be excluded from the tornado.
drawTRUE if the graph is to be drawn; otherwise return the data frame silently.
Used to compare two strategies for traversing the decision tree. A strategy is a unanimous prescription of the actions at each decision node. The extreme values of each input variable are the upper and lower 95% confidence limits of the uncertainty distributions of each variable. This ensures that the range of each input is defensible (Briggs 2012).
A data frame with one row per input model variable and columns
for: minimum value of the variable, maximum value of the variable,
minimum value of the outcome and maximum value of the outcome. NULL
if there are no ModVars.
threshold()Find the threshold value of a model variable at which the cost difference is zero or the ICER is equal to a threshold, for an index strategy compared with a reference strategy.
DecisionTree$threshold(
index,
ref,
outcome = "saving",
mvd,
a,
b,
tol,
lambda = NULL,
nmax = 1000
)indexThe index strategy (option) to be evaluated.
refThe reference strategy (option) with which the index strategy will be compared.
outcomeOne of "saving" or "ICER". For
"saving" (e.g. in cost consequence analysis), the value of
mvd
is found at which cost saved is zero (cost saved is cost of reference
minus cost of index, on the presumption that the new technology will be
cost saving at the point estimate). For "ICER" the value of
mvd
is found for which the incremental cost effectiveness ratio (ICER) is
equal to the threshold lambda. ICER is calculated as
\(\Delta C/\Delta E\), which will normally be positive
at the point estimate (i.e. in the NE or SW quadrants of the
cost-effectiveness plane), where \(\Delta C\) is cost of index minus
cost of reference and \(\Delta E\) is utility of index minus utility
of reference.
mvdThe description of the model variable for which the threshold is to be found.
aThe lower bound of the range of values of mvd to search
for the root (numeric).
bThe upper bound of the range of values of mvd to search
for the root (numeric).
tolThe tolerance to which the threshold should be calculated (numeric).
lambdaThe ICER threshold (threshold ratio) for outcome="ICER".
nmaxMaximum number if iterations allowed to reach convergence.
Uses a rudimentary bisection method method to find the root. In PSA terms, the algorithm finds the value of the specified model variable for which 50% of runs are cost saving (or above the ICER threshold) and 50% are cost incurring (below the ICER threshold).
Value of the model variable of interest at the threshold.
clone()The objects of this class are cloneable with this method.
DecisionTree$clone(deep = FALSE)deepWhether to make a deep clone.
A class to represent a decision tree. An object contains a tree of
decision nodes, chance nodes and leaf nodes, connected by edges
(either actions or reactions). It inherits from class Arborescence and
satisfies the following conditions:
Nodes and edges must form a tree with a single root and there must be a unique path from the root to each node. In graph theory terminology, the directed graph formed by the nodes and edges must be an arborescence.
Each node must inherit from one of DecisionNode,
ChanceNode or LeafNode. Formally the set of vertices
must be a disjoint union of sets of decision nodes, chance nodes
and leaf nodes.
All and only leaf nodes must have no children.
Each edge must inherit from either Action or
Reaction.
All and only edges that have source endpoints joined to
decision nodes must inherit from Action.
All and only edges that have source endpoints joined to
chance nodes must inherit from Reaction.
The sum of probabilities of each set of reaction edges with a common source endpoint must be 1.
Each DecisionNode must have a label, and the labels of all
DecisionNodes must be unique within the model.
Each Action must have a label, and the labels of
Actions that share a common source endpoint must be unique.
Briggs A, Claxton K, Sculpher M. Decision modelling for health economic evaluation. Oxford, UK: Oxford University Press; 2006. Briggs AH, Weinstein MC, Fenwick EAL, Karnon J, Sculpher MJ, Paltiel AD. Model Parameter Estimation and Uncertainty: A Report of the ISPOR-SMDM Modeling Good Research Practices Task Force-6. Value in Health 2012;15:835–42, tools:::Rd_expr_doi("10.1016/j.jval.2012.04.014"). Kaminski B, Jakubczyk M, Szufel P. A framework for sensitivity analysis of decision trees. Central European Journal of Operational Research 2018;26:135–59, tools:::Rd_expr_doi("10.1007/s10100-017-0479-6").