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

Line 5: Orphan line (bad indent): yes: question "Outage confirmed on status page?"

1. Your first decision tree

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

Line 4: Orphan line (bad indent): yes: answer "Check display — connect external monitor"

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.

Line 4: Orphan line (bad indent): yes: q "ECG changes present?"

Line 4: Orphan line (bad indent): label "Severe (8-10)": answer "Emergency — send to ER immediately"

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.

Line 4: Orphan line (bad indent): choice "Build in-house"

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

Line 6: Orphan line (bad indent): true leaf "Setosa" class=Iris-setosa value=50 gini=0.0

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

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

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

9. Common mistakes

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

11. Standard compliance

Schematex decision trees cover three 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).

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 three modes: taxonomy, decision analysis, 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
• ✅ ML: split, leaf, true/false branch prefixes, feature=, threshold=, gini=, entropy=, mse=, class=, value=
• ✅ Config: direction:, edgeStyle:, impurity:, classes:, branchLabels:, branchLength:
• ⏳ 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.
• Breiman, L. et al. (1984). Classification and Regression Trees. Wadsworth.
• Wikipedia — Decision tree · Decision tree learning

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