DecisionTree {rdecision}

A decision tree

Description

An R6 class to represent a decision tree model.

Details

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:

1. 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.

2. 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.

3. All and only leaf nodes must have no children.

4. Each edge must inherit from either Action or Reaction.

5. All and only edges that have source endpoints joined to decision nodes must inherit from Action.

6. All and only edges that have source endpoints joined to chance nodes must inherit from Reaction.

7. The sum of probabilities of each set of reaction edges with a common source endpoint must be 1.

8. Each DecisionNode must have a label, and the labels of all DecisionNodes must be unique within the model.

9. Each Action must have a label, and the labels of Actions that share a common source endpoint must be unique.

Super classes

rdecision::Graph -> rdecision::Digraph -> rdecision::Arborescence -> DecisionTree

Methods

Public methods

• DecisionTree$new()

• DecisionTree$decision_nodes()

• DecisionTree$chance_nodes()

• DecisionTree$leaf_nodes()

• DecisionTree$actions()

• DecisionTree$modvars()

• DecisionTree$modvar_table()

• DecisionTree$draw()

• DecisionTree$is_strategy()

• DecisionTree$strategy_table()

• DecisionTree$strategy_paths()

• DecisionTree$edge_properties()

• DecisionTree$evaluate_walks()

• DecisionTree$evaluate()

• DecisionTree$tornado()

• DecisionTree$threshold()

• DecisionTree$clone()

Inherited methods

• rdecision::Graph$degree()
• rdecision::Graph$edge_along()
• rdecision::Graph$edge_at()
• rdecision::Graph$edge_index()
• rdecision::Graph$edge_label()
• rdecision::Graph$edges()
• 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::Graph$vertex_label()
• rdecision::Graph$vertexes()
• rdecision::Digraph$arrow_source()
• rdecision::Digraph$arrow_target()
• 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$is_root()
• rdecision::Arborescence$parent()
• rdecision::Arborescence$postree()
• rdecision::Arborescence$root()
• rdecision::Arborescence$root_to_leaf_paths()
• rdecision::Arborescence$siblings()

Method new()

Create a new decision tree.

Usage

DecisionTree$new(V, E)

Arguments

V

A list of nodes.

E

A list of edges.

Details

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.

Returns

A DecisionTree object

Method decision_nodes()

Find the decision nodes in the tree.

Usage

DecisionTree$decision_nodes(what = "node")

Arguments

what

A character string defining what to return. Must be one of "node", "label" or "index".

Returns

A list of DecisionNode objects (for what = "node"); a list of character strings (for what = "label"), or an integer vector with indexes of the decision nodes (for what = "index").

Method chance_nodes()

Find the chance nodes in the tree.

Usage

DecisionTree$chance_nodes(what = "node")

Arguments

what

A character string defining what to return. Must be one of "node", "label" or "index".

Returns

A list of ChanceNode objects (for what = "node"); a list of character strings (for what = "label"), or an integer vector with indexes of the decision nodes (for what = "index").

Method leaf_nodes()

Find the leaf nodes in the tree.

Usage

DecisionTree$leaf_nodes(what = "node")

Arguments

what

One of "node" (returns Node objects), "label" (returns the leaf node labels) or "index" (returns the vertex indexes of the leaf nodes).

Returns

A list of LeafNode objects (for what = "node"); a list of character strings (for what = "label"); or an integer vector of leaf node indexes (for what = "index").

Method actions()

Find the edges that have the specified decision node as their source.

Usage

DecisionTree$actions(d)

Arguments

d

A decision node.

Returns

A list of Action edges.

Method modvars()

Find all the model variables of type ModVar.

Usage

DecisionTree$modvars()

Details

Find ModVars that have been specified as values associated with the nodes and edges of the tree.

Returns

A list of ModVars.

Method modvar_table()

Tabulate the model variables.

Usage

DecisionTree$modvar_table(expressions = TRUE)

Arguments

expressions

A logical that defines whether expression model variables should be included in the tabulation.

Returns

Data frame with one row per model variable, as follows:

Description

As given at initialization.

Units

Units of the variable.

Distribution

Either the uncertainty distribution, if it is a regular model variable, or the expression used to create it, if it is an ExprModVar.

Mean

Mean; calculated from means of operands if an expression.

E

Expectation; estimated from random sample if expression, mean otherwise.

SD

Standard deviation; estimated from random sample if expression, exact value otherwise.

Q2.5

p=0.025 quantile; estimated from random sample if expression, exact value otherwise.

Q97.5

p=0.975 quantile; estimated from random sample if expression, exact value otherwise.

Est

TRUE if the quantiles and SD have been estimated by random sampling.

Method draw()

Draw the decision tree to the current graphics output.

Usage

DecisionTree$draw(border = FALSE)

Arguments

border

If TRUE draw a light grey border around the plot area.

Details

Uses the algorithm of Walker (1989) to distribute the nodes compactly (see the Arborescence class help for details).

Returns

No return value.

Method is_strategy()

Tests whether an object is a valid strategy.

Usage

DecisionTree$is_strategy(strategy)

Arguments

strategy

A list of Action edges.

Details

A strategy is a unanimous prescription of an action taken at each decision node, coded as a list of action edges. This checks whether the strategy is valid for this decision tree.

Returns

TRUE if the strategy is valid for this tree. Returns FALSE if the list of Action edges are not a valid strategy.

Method strategy_table()

Find all potential strategies for the decision tree.

Usage

DecisionTree$strategy_table(what = "index", select = NULL)

Arguments

what

A character string defining what to return. Must be one of "label" or "index".

select

A 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.

Details

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.

Returns

A data frame where each row is a potential strategy and each column is a decision node, ordered lexicographically. 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.

Method strategy_paths()

Find all paths walked in each possible strategy.

Usage

DecisionTree$strategy_paths()

Details

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.

Returns

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.

Method edge_properties()

Properties of all actions and reactions as a matrix.

Usage

DecisionTree$edge_properties()

Details

Gets the properties (probability, cost, benefit) of each action and reaction in the decision tree in matrix form.

Returns

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.

Method evaluate_walks()

Evaluate the components of pay-off associated with a set of walks in the decision tree.

Usage

DecisionTree$evaluate_walks(W = NULL, Wi = NULL)

Arguments

W

A 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.

Wi

As 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.

Details

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.

Returns

A pay-off table, represented as a matrix of numeric values with response columns as follows:

Probability

The probability of traversing the pathway.

Path.Cost

The cost of traversing the pathway.

Path.Benefit

The benefit derived from traversing the pathway.

Path.Utility

The utility associated with the outcome (leaf node).

Path.QALY

The QALYs associated with the outcome (leaf node).

Cost

Path.Cost * probability of traversing the pathway.

Benefit

Path.Benefit * probability of traversing the pathway.

Utility

Path.Utility * probability of traversing the pathway.

QALY

Path.QALY * probability of traversing the pathway.

The matrix has one row per path, with the row label equal to the character representation of the index of the leaf node at the end of the path.

Method evaluate()

Evaluate each strategy.

Usage

DecisionTree$evaluate(setvars = "expected", N = 1L, by = "strategy")

Arguments

setvars

One 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).

N

Number of replicates. Intended for use with PSA (modvars = "random"); use with modvars = "expected" will be repetitive and uninformative.

by

One 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 (as above) and one (cost, benefit, utility, QALY) as row names.

Details

Starting with the root, the function works though all possible paths to leaf nodes and computes the probability, cost, benefit and utility of each, optionally aggregated by strategy or run. The columns of the returned data frame are:

by = "path"

Run

Run number

<label of first decision node>

label of action leaving the node

<label of second decision node (etc.)>

label of action leaving the node

Leaf

The label of terminating leaf node

Probability

Probability of traversing the path

Cost

Cost of traversing the path

Benefit

Benefit of traversing the path

Utility

Utility of traversing the path

QALY

QALY of traversing the path

by = "strategy"

Run

Run number

<label of first decision node>

label of action leaving the node

<label of second decision node (etc)

label of action

Probability

\Sigma p_i for the run (1)

Cost

Aggregate cost of the strategy

Benefit

Aggregate benefit of the strategy

Utility

Aggregate utility of the strategy

QALY

Aggregate QALY of the strategy

by = "run"

Run

Run 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 a label associated with strategy S. Each strategy label is a list of the labels of the action edges that are traversed in the strategy, concatenated with underscores. The ordering of each label part follows the lexicographical order of the decision node labels concatenated with underscores. For example, if there are three decision nodes labelled d1, d2 and d3, each strategy label will be of the form a1i_a2i_a3i where a1i is the label of one action edge emanating from decision node d1, etc. There will be one probability, cost, benefit, utility and QALY column for each strategy.

Returns

A data frame whose columns depend on by; see "Details".

Method tornado()

Create a "tornado" diagram.

Usage

DecisionTree$tornado(
  index,
  ref,
  outcome = "saving",
  exclude = NULL,
  draw = TRUE
)

Arguments

index

The index strategy (option) to be evaluated.

ref

The reference strategy (option) with which the index strategy will be compared.

outcome

One 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.

exclude

A list of descriptions of model variables to be excluded from the tornado.

draw

TRUE if the graph is to be drawn; otherwise return the data frame silently.

Details

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).

Returns

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.

Method 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.

Usage

DecisionTree$threshold(
  index,
  ref,
  outcome,
  mvd,
  a,
  b,
  tol,
  lambda = NULL,
  nmax = 1000L
)

Arguments

index

The index strategy (option) to be evaluated.

ref

The reference strategy (option) with which the index strategy will be compared.

outcome

One 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.

mvd

The description of the model variable for which the threshold is to be found.

a

The lower bound of the range of values of mvd to search for the root (numeric).

b

The upper bound of the range of values of mvd to search for the root (numeric).

tol

The tolerance to which the threshold should be calculated (numeric).

lambda

The ICER threshold (threshold ratio) for outcome="ICER".

nmax

Maximum number if iterations allowed to reach convergence.

Details

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).

Returns

Value of the model variable of interest at the threshold.

Method clone()

The objects of this class are cloneable with this method.

Usage

DecisionTree$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Author(s)

Andrew J. Sims [e-mail]

References

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, 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, doi:10.1007/s10100-017-0479-6.