Decision tree diagram

About decision trees

A decision tree is a branching diagram that represents a sequence of choices and their consequences as a rooted tree: each internal node is a question or decision, each edge is an answer or action, and each leaf is an outcome. The format appears across three quite different practices — troubleshooting flowcharts and clinical decision rules (taxonomy trees), risk and investment analysis using expected value (decision analysis), and machine learning model inspection (classifier trees). Despite surface differences all three share the same tree structure, which is why Schematex encodes them under one keyword with a mode selector.

Schematex decision trees cover: (1) taxonomy mode — the yes/no question flows used in medical triage (Turing 1937 lineage; now standard in clinical decision support), (2) decision analysis mode — the expected-value rollback method developed in management science (Raiffa & Schlaifer, 1961), and (3) ML mode — the CART split/leaf format used to visualize scikit-learn and similar trained classifiers (Breiman et al., 1984).

1. Your first decision tree

The smallest useful decision tree: a root question with two branches.

Four rules cover 80% of usage:

1. Start with decisiontree, optionally with :mode and a quoted title.
2. Each question node uses question "text" (or shorthand q "text").
3. Each answer/leaf uses answer "text" (or a "text" or leaf "text").
4. Branch labels — yes:, no:, or a custom label "X": — prefix the child node on the same line.

Indentation controls nesting: each level adds 2 spaces. The parser computes parent-child relationships from indent depth.

Comments must start with # or // on their own line.

2. Modes

The mode is set in the header line:

Default direction is top-down for taxonomy and ML, left-right for decision analysis.

3. Taxonomy mode

Best for: troubleshooting guides, FAQs, clinical protocols, product recommendation flows.

Node keywords

Branch labels

Custom labels let you go beyond yes/no for multi-way decisions from one question.

4. Decision analysis mode

Best for: investment decisions, build-vs-buy analysis, risk-weighted strategy evaluation.

Node keywords

Branch keywords

Payoff attribute

payoff=N on any node sets the payoff value. On end / outcome nodes it defines the terminal value. The parser runs expected-value rollback automatically: each chance node's EV is the probability-weighted sum of its children's EVs; each decision node's EV is the maximum child EV, and the optimal branch is flagged.

Constraint: probabilities on all direct children of a chance node must sum to 1.0 (±0.01). The parser throws a DTreeParseError if they do not.

5. Influence diagram mode

Best for: framing a decision problem compactly before you unroll it. Where decision-analysis mode draws every branch of every outcome as an explicit tree, an influence diagram (Howard & Matheson, 1981) draws the same problem as a directed acyclic graph (DAG) of variables and the dependencies between them — one node per decision, uncertainty, and objective, no matter how many states each can take. It is the diagram decision analysts reach for first, because it shows the structure (what informs what, what affects the payoff) without the combinatorial blow-up of a tree.

This mode is structural, not computational. Unlike decision-analysis mode, it does not solve for expected value — the compact graph deliberately omits the probability and payoff tables that an EV rollback would need. Use it to communicate and validate the shape of the problem; use decision-analysis mode (section 4) when you want the numbers folded back.

Header forms

Two equivalent ways to select the mode:

decisiontree:influence "Oil Wildcatter"

or, as a directive on its own line after the header:

decisiontree "Market Entry"
  mode: influence

Node keywords

Each node is declared as kind Id "label" — an id (used to wire arcs) followed by a quoted display label.

The shapes follow the standard influence-diagram convention: decisions are rectangles, uncertainties are ovals, and the value node is an octagon. Add utility=N to a value node to annotate the payoff it represents (value Profit "Net profit" utility=42).

Arcs and their semantics

Arcs are written Source -> Target on their own lines, by node id. An arc's meaning is read from its destination, exactly as in the published standard:

The dashed informational arc is the one to watch: Seismic -> Drill means "the seismic test result is observed before choosing whether to drill," which is precisely what makes the decision worth modelling.

Validation rules

• The graph must be acyclic — a cycle (e.g. A -> B and B -> A) is rejected.
• At least one value node is required; an influence diagram with no objective is not a decision problem.
• Arcs reference node ids that must be declared.

Examples

The Oil Wildcatter — the canonical teaching problem. The seismic test result is observed before the drill decision (dashed informational arc Seismic -> Drill), the test is relevant to whether oil is actually present (Seismic -> Oil), and both the oil state and the drill choice feed the profit (Oil -> Profit, Drill -> Profit).

A market-entry decision using the mode: influence directive form. Demand is observed before entering (Demand -> Enter, informational/dashed) and also drives profit directly, while the competitor's response feeds only the payoff.

6. Machine learning mode

Best for: explaining trained CART classifiers, model transparency reports, feature importance analysis.

Node keywords

Branch prefixes

true and false prefix child nodes to mark which branch each child represents.

Properties (key=value, no colon, no quotes around values)

7. Config options

Config lines appear between the header and the first node. Each is key: value (colon, no config keyword).

Shared config (all modes)

Taxonomy config

Decision analysis config

ML config

decisiontree:ml "Loan classifier"
direction: top-down
impurity: gini
classes: Approved, Denied, Review

8. Labels & comments

• Diagram title: decisiontree "Title" — the quoted string after the header keyword.
• Node label: the quoted string immediately after the node keyword — question "Is the fee waived?".
• Branch label: yes:, no:, or label "Custom": before the child node — on the same line as the child.
• Payoff: payoff=250000 at the end of a decision/end node line.
• ML properties: key=value tokens after the node's label string (no […] brackets, no colons).
• Comments: # or // at the start of a line (after optional leading whitespace). Only full-line comments are supported — inline trailing comments are not.

9. Reserved words & escaping

Reserved node keywords: decision, chance, end, outcome, choice, prob, split, leaf, question, q, answer, a.

Reserved branch prefixes: yes:, no:, true, false, label.

Reserved header forms: decisiontree, decisiontree:decision, decisiontree:da, decisiontree:ml.

Strings with spaces must be double-quoted: question "Annual revenue > $1M?". Node labels, branch labels from label "…": syntax, and the diagram title all require double quotes.

10. Common mistakes

11. Grammar (EBNF)

document       = header ( config-line )* node

header         = "decisiontree" ( ":" mode )? ( WS quoted-string )? NEWLINE
mode           = "decision" | "da" | "ml"
                 // omitted → taxonomy

config-line    = config-key ":" WS config-value NEWLINE
config-key     = "direction" | "edgeStyle" | "edge-style"
               | "branchLabels" | "branch-labels"
               | "branchLength" | "branch-length"
               | "impurity" | "classes"

// ── Taxonomy mode ──────────────────────────────
node           = ( branch-prefix WS )? tax-node ( WS "[" tax-attrs "]" )? NEWLINE
                   INDENT child-node*
tax-node       = ( "question" | "q" ) WS quoted-string
               | ( "answer" | "a" | "leaf" ) WS quoted-string
branch-prefix  = "yes:" | "no:" | "label" WS quoted-string ":"

// ── Decision-analysis mode ─────────────────────
da-node        = "decision" WS quoted-string NEWLINE INDENT da-child+
               | "chance" WS quoted-string NEWLINE INDENT da-prob-child+
               | ( "end" | "outcome" ) WS quoted-string ( WS "payoff=" number )? NEWLINE
da-child       = "choice" WS quoted-string NEWLINE INDENT da-node
da-prob-child  = "prob" WS number WS da-node    // prob, value, and child all on one line

// ── ML mode ───────────────────────────────────
ml-node        = ( "true" | "false" )? ml-kind WS quoted-string ml-prop* NEWLINE
                   INDENT ml-child*
                 // "true"/"false" and ml-kind must be on the same line
ml-kind        = "split" | "leaf"
ml-prop        = WS key "=" value     // no spaces around "="

comment        = ( "#" | "//" ) any NEWLINE
quoted-string  = '"' any-char-but-quote* '"'

Authoritative source: src/diagrams/decisiontree/parser.ts. If this diverges from the parser, the parser wins — please open an issue.

12. Standard compliance

Schematex decision trees cover four established conventions:

Taxonomy mode follows the question/answer flowchart conventions common in clinical decision support systems (Arden Syntax lineage) and ISO 9001 troubleshooting procedures.

Decision analysis mode follows the expected-value rollback method from management science: decision nodes (square, actor chooses), chance nodes (circle, probabilistic), terminal nodes with payoffs. EV is computed automatically via backward induction (Raiffa & Schlaifer, 1961).

Influence diagram mode follows the Howard & Matheson (1981) convention: decision (rectangle), chance (oval), and value (octagon) nodes wired as an acyclic graph, with arc meaning read from the destination (informational into decisions, drawn dashed; relevance into chance; functional into value). It is a structural diagram — it does not solve for EV.

ML mode follows the CART (Classification and Regression Trees) split/leaf notation (Breiman et al., 1984) compatible with scikit-learn's export_text and plot_tree output.

What is implemented today:

• ✅ All four modes: taxonomy, decision analysis, influence diagram, ML
• ✅ Taxonomy: question/q, answer/a/leaf, yes:, no:, label "X": branch labels
• ✅ Decision: decision, chance, end/outcome, choice, prob, payoff=N, automatic EV rollback
• ✅ Influence: decision/chance/value nodes, utility=N, Source -> Target arcs, destination-derived arc semantics, dashed informational arcs, acyclicity + value-node validation
• ✅ ML: split, leaf, true/false branch prefixes, feature=, threshold=, gini=, entropy=, mse=, class=, value=
• ✅ Config: direction:, edgeStyle:, impurity:, classes:, branchLabels:, branchLength:, mode:
• ⏳ Probability-weighted branch length rendering (branchLength: probability parsed but not yet applied visually)
• ⏳ Sensitivity analysis overlays (tornado chart-style annotations on decision trees)
• ⏳ Forest / ensemble view — multiple trees side-by-side

References:

• Raiffa, H. & Schlaifer, R. (1961). Applied Statistical Decision Theory. Harvard Business School.
• Howard, R. A. & Matheson, J. E. (1981/2005). Influence Diagrams. Decision Analysis 2(3).
• Breiman, L. et al. (1984). Classification and Regression Trees. Wadsworth.
• Wikipedia — Decision tree · Influence diagram · Decision tree learning

13. Roadmap

Planned — not yet parseable. Do not use these in generated DSL today; the parser will reject or ignore them.

• branchLength: probability visual rendering — the config key parses but the layout engine does not yet scale branch lengths by probability.
• Sensitivity / tornado analysis — sensitivity: block annotating which prob values most affect the final EV.
• Export annotations — structured table output (decision matrix) alongside the diagram SVG.
• Forest view — forest keyword wrapping multiple decisiontree blocks in a side-by-side comparison layout.
• Collapse/expand interactive markers — collapsed: true on a node to render a triangle placeholder for deep subtrees.

Track in the GitHub issues if you need any of these sooner.

Related examples

Ready-to-use scenarios from the examples gallery: