Docs

Causal Inference — std.causal Reference

Tip

See also

• cookbook/causal/causal_demo.eta — gentle end-to-end primer (3-node DAG, single confounder) combining symbolic differentiation, do-calculus identification, findall + CLP validation, and a libtorch neural ATE.
• Causal Counterfactual - focused counterfactual reference for twin networks, ID*, IDC*, and ETT.
• Portfolio — full institutional pipeline: 6-node macro DAG, AAD risk sensitivities, CLP(R) + QP allocation, scenario stress, dynamic control.

Overview

This page is the API reference for Eta’s causal-inference stack. The implementation is research-grade and covers Pearl’s identification and estimation surface end-to-end:

The layer also composes with:

• std.logic — structural unification and backtracking
• std.clp / std.clpr — bounding probability estimands and feasibility checks
• std.stats — Fisher-z residualisation for CI tests, OLS / GLS for outcome and propensity models
• std.torch — neural propensity / outcome models for std.causal.estimate
• std.ml.tree / std.ml.forest — tree and random-forest learners for CATE backbones

The finance-oriented running example estimates the causal effect of market-beta exposure on excess stock returns, adjusting for sector membership as an observed confounder.

Finance Motivation

Quantitative finance asks causal questions that cannot be answered by correlation alone. For example:

“Does increasing a portfolio’s market-beta exposure actually cause higher excess returns — or does the apparent relationship simply reflect the fact that high-beta stocks are concentrated in high-return sectors?”

A naive OLS regression of stock-return on market-beta conflates two distinct paths:

sector ──→ market-beta ──→ stock-return     (causal path)
sector ──────────────────→ stock-return     (direct sector effect)

sector is a confounder: it influences both the exposure (market-beta) and the outcome (stock-return), creating a spurious association. Pearl’s do-calculus provides a formal procedure to identify the interventional distribution P(return | do(beta)) — the return we would observe if we set beta externally — from purely observational data.

The Causal DAG

(define finance-dag
  '((sector      -> market-beta)
    (sector      -> stock-return)
    (market-beta -> stock-return)))

sector ──→ market-beta ──→ stock-return
  │                              ↑
  └──────────────────────────────┘

Nodes and their roles:

Symbolic Identification with Do-Calculus

The Three Rules

Pearl’s do-calculus provides three rules that transform interventional quantities into observational ones. Eta exposes these directly in std.causal via:

• dag:mutilate-do
• dag:mutilate-see
• do-rule1-applies?
• do-rule2-applies?
• do-rule3-applies?

Rule 1 — Insertion/deletion of observations:

P(y | do(x), z, w) = P(y | do(x), w)
if  Y ⊥ Z | X, W  in  G_{X̄}

G_{X̄} is the graph with all incoming edges to X removed. If Y is independent of Z given X and W in that graph, we can drop Z from the conditioning set.

Rule 2 — Action/observation exchange:

P(y | do(x), do(z), w) = P(y | do(x), z, w)
if  Y ⊥ Z | X, W  in  G_{X̄, Z_}

G_{X̄, Z_} additionally removes all outgoing edges from Z. If Y is then independent of Z, a do(z) intervention can be replaced by passive observation of z.

Rule 3 — Insertion/deletion of actions:

P(y | do(x), do(z), w) = P(y | do(x), w)
if  Y ⊥ Z | X, W  in  G_{X̄, Z̄(W)}

where Z̄(W) contains the Z-nodes that are not ancestors of any W-node in G_{X̄}. If the condition holds, the do(z) can be dropped entirely.

Back-Door Identification

For the finance DAG, the back-door criterion identifies the adjustment set directly without applying the three rules sequentially. (do:identify dag y x) checks it automatically:

(do:identify finance-dag 'stock-return 'market-beta)
;; => (adjust (sector) (P stock-return market-beta (sector)) (P (sector)))

To inspect all valid adjustment sets and status metadata:

(do:identify-details finance-dag 'stock-return 'market-beta)
;; => ((status . adjust)
;;     (result . (adjust (sector) ...))
;;     (chosen-z . (sector))
;;     (all-z-sets . ((sector)))
;;     (assumptions . (...)))

Formatted as a human-readable formula:

(do:adjustment-formula->string formula 'stock-return 'market-beta)
;; => "P(stock-return | do(market-beta)) =
;;     Σ_{sector} P(stock-return | market-beta, sector) · P(sector)"

Proof that {sector} satisfies the back-door criterion:

1. No descendant condition: sector is not a descendant of market-beta ✓ (it is a parent of market-beta)

2. Blocking condition: sector blocks the only back-door path:

   market-beta ← sector → stock-return
   

   Conditioning on sector closes this path ✓

(dag:satisfies-backdoor? finance-dag 'market-beta 'stock-return '(sector))
;; => #t

Observed-set-restricted identification (useful for latent-confounder stress DAGs):

(define latent-dag
  '((latent-u    -> market-beta)
    (latent-u    -> stock-return)
    (sector      -> market-beta)
    (sector      -> stock-return)
    (market-beta -> stock-return)))

(do:identify-details-observed
  latent-dag 'stock-return 'market-beta '(sector market-beta stock-return))
;; => ((status . unidentified) ...)

dag:d-connected? and dag:d-separated? are implemented with Bayes-ball traversal, so reachability queries scale linearly with graph size.

DAG Graph Utilities

std.causal provides a complete graph library over the (from -> to) edge-list format:

(dag:ancestors finance-dag 'stock-return)
;; => (market-beta sector)

(dag:non-descendants finance-dag 'market-beta)
;; => (sector)    — stock-return is a descendant, so excluded

(dag:has-path? finance-dag 'sector 'stock-return '(market-beta))
;; => #t  — path: sector → stock-return (direct edge)

(dag:has-path? finance-dag 'sector 'stock-return '(market-beta stock-return))
;; => #f  — both paths blocked

ADMG Utilities

For mixed graphs with latent confounding, import:

(import std.causal.admg)

std.causal.admg provides:

ID and IDC on ADMGs

To identify effects in mixed graphs with latent confounding:

(import std.causal.identify)

The returned AST uses:

• (P vars) for factors
• (sum vars expr) for marginalization
• (prod e1 e2 ...) for products
• (cond-on expr cond) for conditional forms
• (fail (hedge ...)) for non-identifiable queries

Worked examples

(import std.causal.identify)

;; Direct effect — trivial conditional.
(id '((x -> y)) '(y) '(x))
;; => (P (y x))

;; Front-door (X -> M -> Y, X <-> Y latent confounder).
(id '((x -> m) (m -> y) (x <-> y)) '(y) '(x))
;; => (sum (m)
;;      (prod (P (m x))
;;            (sum (x*) (prod (P (y x* m)) (P (x*))))))

;; Bow graph — non-identifiable, returns a hedge witness.
(id '((x -> y) (x <-> y)) '(y) '(x))
;; => (fail (hedge ...))

;; Napkin graph — identifiable through W1, W2.
(id '((w1 -> w2) (w2 -> x) (x -> y) (w1 <-> x) (w1 <-> y)) '(y) '(x))
;; => (sum ...)   ; not a hedge

;; IDC: condition on Z.
(idc '((x -> y) (z -> y)) '(y) '(x) '(z))
;; => (P (y x z))

Adjustment, Front-Door, and IV

For generalized adjustment enumeration and structural criteria checks:

(import std.causal.adjustment)

Mediation Analysis

For natural and controlled direct/indirect effect decomposition:

(import std.causal.mediation)

The mediation helpers enforce data support checks for requested treatment values and mediator-treatment strata.

Transportability and Selection Bias

For selection-diagram checks and transport queries:

(import std.causal.transport)

do:transport uses a conservative workflow:

• return target-domain ID when no S-nodes are present;
• return target-domain ID when Y is selection-invariant given X;
• otherwise try an s-backdoor adjustment set Z;
• otherwise return a transport failure witness.

When s-backdoor transport applies, the returned estimand uses P* for source-domain interventional information:

(sum (z) (prod (P* (y x z)) (P (z))))

Counterfactual Queries

For counterfactual graph transforms and ID*/IDC* wrappers:

(import std.causal.counterfactual)

Event syntax and a fuller worked example live on the counterfactual reference page.

Structure Learning

For data-driven structure learning helpers:

(import std.causal.learn)

CPDAG edge format:

• directed edge: (u -> v)
• undirected edge: (u -- v)

Worked example

(import std.causal.learn)

;; Linear-Gaussian chain  a -> b -> c.
(define chain-data
  (let loop ((i 0) (acc '()))
    (if (= i 240)
        (reverse acc)
        (let* ((a (- (* 1.0 i) 120.0))
               (b (+ (* 0.9 a) (if (even? i) 0.15 -0.15)))
               (c (+ (* 0.9 b) (if (zero? (modulo i 3)) 0.10 -0.10))))
          (loop (+ i 1)
                (cons (list (cons 'a a) (cons 'b b) (cons 'c c))
                      acc))))))

(learn:pc chain-data 0.01 learn:ci-test:fisher-z)
;; => CPDAG containing (a -- b) (b -- c) ; long edge a-c removed.

(learn:notears chain-data 0.2 100)
;; => ((a -> b) (b -> c))   ; transitive a->c reduced away.

(learn:ci-test:fisher-z chain-data 'a 'c '(b) 0.05)
;; => (#t . p-value)   ; conditionally independent given the mediator.

Rendering and the define-dag macro

For visualisation and validated graph literals:

(import std.causal.render)

(define-dag finance-dag
  (sector      -> market-beta)
  (sector      -> stock-return)
  (market-beta -> stock-return))

(dag:->mermaid '((a -> b) (a <-> c) (b -- c)))
;; flowchart LR
;;   n0["a"]
;;   n1["b"]
;;   n2["c"]
;;   n0 --> n1
;;   n0 -.-> n2
;;   n2 -.-> n0
;;   n1 --- n2

(dag:->dot finance-dag '((title . "Finance DAG") (rankdir . "TB")))
;; digraph "Finance DAG" {
;;   rankdir=TB;
;;   "market-beta" -> "stock-return";
;;   "sector" -> "market-beta";
;;   "sector" -> "stock-return";
;; }

Graph Rendering

For graph rendering and graph-literal validation helpers:

(import std.causal.render)

DOT options:

• (title . "...") sets the graph title ("Causal DAG" by default)
• (rankdir . "...") sets Graphviz rank direction ("LR" by default)

Rendering conventions:

• bidirected edge (u <-> v) is rendered as a dashed bidirectional edge
• undirected edge (u -- v) is rendered without arrowheads

Numeric Estimation

Once an estimand is identified, two estimation surfaces are available:

1. Plug-in stratified adjustment — bundled in std.causal, evaluates the back-door formula directly from the data.
2. Modern estimators — in std.causal.estimate: g-formula, IPW, AIPW, TMLE, plus bootstrap CIs and sensitivity tools.

1. Plug-in adjustment (std.causal)

For the finance DAG the back-door formula is

E[Y | do(X=x)] = Σ_s  E[Y | X=x, sector=s]  ·  P(sector=s)

std.causal evaluates it with plain Eta arithmetic:

(do:estimate-effect y-var x-var x-val z-set data)
;; legacy arity also accepted:
;; (do:estimate-effect y-var x-var x-val z-set z-val data)

(do:conditional-mean
  (filter (lambda (obs) (eq? (cdr (assq 'sector obs)) 'tech)) data)
  'stock-return)
;; => sample mean of stock-return in the tech stratum

2. Modern estimators (std.causal.estimate)

For practical ATE estimation on binary-treatment observational data:

(import std.causal.estimate)

Notes:

• Binary treatment x in {0,1} or {#f,#t}.
• Strata-based nuisance models; for richer nuisance fits plug std.torch or std.stats regressors into your own wrapper.
• do:bootstrap-ci is generic over any of the estimators above.

End-to-end example

(module causal-demo
  (import std.causal)
  (import std.io)
  (begin
    (define dag
      '((sector      -> market-beta)
        (sector      -> stock-return)
        (market-beta -> stock-return)))

    ;; Embedded toy data: 30 observations
    ;; (sector market-beta stock-return)
    (define data '(...))   ; see cookbook/causal/causal_demo.eta for the DGP

    ;; Symbolic identification
    (define formula (do:identify dag 'stock-return 'market-beta))
    (println (do:adjustment-formula->string formula 'stock-return 'market-beta))

    ;; Numeric estimation: CATE for beta=1.4 vs beta=0.9
    (define cate
      (- (do:estimate-effect 'stock-return 'market-beta 1.4
                             '(sector) data)
         (do:estimate-effect 'stock-return 'market-beta 0.9
                             '(sector) data)))
    (print "Adjusted CATE: ")
    (println cate)))

Run the full primer:

etai cookbook/causal/causal_demo.eta

CATE Meta-Learners

For conditional treatment-effect modelling:

(import std.causal.cate)

Learner-spec protocol expected by the fitters:

((fit . (lambda (X y) -> model))
 (predict . (lambda (model X) -> yhat))
 (kind . regressor|classifier)
 (fit-weighted . (lambda (X y w) -> model))) ; optional

std.stats already ships compatible constructors:

(define reg (stats:make-ols-regressor))
(define cls (stats:make-logistic))
(define m (cate:fit-dr-learner data 'y 'x '(z1 z2 z3) reg cls))
(cate:ate m data)

Cross-fitting and DML

For cross-fitted nuisance estimation and Double Machine Learning:

(import std.causal.crossfit)

Minimal usage:

(import std.causal.crossfit)
(import std.stats)

(define reg (stats:make-ols-regressor))
(define cls (stats:make-logistic))

(crossfit:dml-plr data 'y 'x '(z1 z2 z3) reg reg 5 42)
;; => ((theta . ...) (se . ...) (ci . (... ...)) (n . ...))

(crossfit:dml-irm data 'y 'x '(z1 z2 z3) reg cls 5 42)
;; => ((theta . ...) (se . ...) (ci . (... ...)) (n . ...))

Notes:

• crossfit:dml-irm expects binary treatment (0/1 or #f/#t).
• All nuisance vectors are aligned with input row order.

Uplift, Qini, and Policy Value

For treatment-ranking metrics, policy evaluation, and synthetic-effect diagnostics:

(import std.causal.policy)

Minimal usage:

(import std.causal.policy)

(define curve (policy:qini-curve tau-hat y x))
(policy:qini-coefficient curve)
(policy:auuc curve)

(policy:value-ipw data 'y 'x '(z1 z2) policy-fn e-hat)
(policy:value-aipw data 'y 'x '(z1 z2) policy-fn mu1 mu0 e-hat)

Trees, Random Forests, and Causal Forest

M13 introduces native tree/forest learners plus a causal-forest wrapper.

Regression tree (std.ml.tree)

(import std.ml.tree)

Random forest (std.ml.forest)

(import std.ml.forest)

Causal forest (std.causal.forest)

(import std.causal.forest)

Minimal usage:

(define cf
  (forest:fit-causal-forest data 'y 'x '(z1 z2 z3)
                            'n-trees 500
                            'min-leaf 5
                            'subsample 0.8
                            'seed 42))

(forest:predict-cate cf (car data))

CLP Integration

std.clp connects to causal reasoning through structural constraints on the estimands. For example, since P(sector) is a probability it must lie in (0, 1). Representing as a percentage:

(import std.clp)

(let ((w-tech (logic-var)))
  (clp:domain w-tech 1 99)   ; P(tech) ∈ (0,1) — non-degenerate
  (unify w-tech 33)           ; observed: 33% of data is tech
  (println (deref-lvar w-tech)))  ; => 33

CLP is also used to assert that estimated causal effects satisfy prior knowledge bounds — a lightweight form of causal sensitivity analysis:

;; The CAPM predicts that the excess-return slope wrt beta equals
;; the equity risk premium.  Historically this is in [3%, 8%] per unit beta.
(let ((slope (logic-var)))
  (clp:domain slope 3 8)      ; prior knowledge: slope ∈ [3,8]% per unit beta
  (if (and (unify slope estimated-slope-pct)
           (ground? slope))
      (println "Estimate is consistent with CAPM prior.")
      (println "Warning: estimate outside historical ERP range.")))

Source Locations