org.replikativ.foerster.counterfactual — org.replikativ/foerster 0.1.120

Counterfactual queries by abduction, action and prediction (Pearl).

A program's sample and observe sites are structural equations (foerster.mechanism). Given evidence and interventions:

1. abduction — condition the program on the evidence (importance sampling by gfi/generate) and read each weighted factual trace's exogenous noise off its sites;
2. action — install the interventions;
3. prediction — run the program again in a world of its own with every other site fed its factual noise, aligned by address.

The result pairs each factual world with its counterfactual twin, under the factual weight: a joint measure, so quantities that need both worlds (probability of necessity, effect of treatment on the treated) are expectations over it. A site that exists only in the counterfactual world draws fresh noise and is listed as :unaligned: its answer is interventional, not counterfactual.

abduct-posterior clj/s

(abduct-posterior posterior)

(abduct-posterior posterior {:keys [reconstruct seed]})

Abduct every draw of an EmpiricalMeasure, retaining its existing weights. Accepts the legacy traces kept by SMC and MCMC. :reconstruct may instead map a particle to {:noise … :unsupported […] :factual …}; this is the explicit adapter for blocks/compiled models whose mechanisms are hidden. :seed makes posterior discrete-noise draws reproducible. No live worlds are retained.

abduct-trace clj/s

(abduct-trace t)

(abduct-trace t weight)

Recover reusable noise from a live GFI trace. weight is a log weight; pass 0 for an already-posterior MCMC draw, not its likelihood.

condition-worlds clj/s

(condition-worlds population event)

Condition a computed world population on an arbitrary cross-world event. Retain existing log weights. A zero-mass event is an error, not a uniform posterior. This is Monte Carlo conditioning, not causal identification.

counterfactual clj/s

(counterfactual model
                {:keys [evidence interventions particles] :or {particles 1}}
                &
                [opts])

Pairs of factual and counterfactual results of model (a spin, as for foerster.gfi) given :evidence ({address value}, fixed in the factual world) and :interventions ({selector transform}, as for foerster.trace/policy), from :particles importance-weighted factual worlds (default 1: enough when the evidence fixes every noise).

Resolves a vector of {:factual r :counterfactual r' :weight log-w :unaligned [address …]}.

expectation clj/s

(expectation population f)

Weighted expectation of numeric f on a computed draw (pair or worlds). Refuses an empty or zero-mass population.

noise-of clj/s

(noise-of trace)

{address u} of the sample and observe sites of trace whose law is a mechanism, and the addresses of those that are not.

predict clj/s

(predict model abduction interventions)

(predict model
         {:keys [noise unsupported factual weight]}
         interventions
         {:keys [strict? run-opts] :or {strict? true}})

Replay model under interventions using a reusable abducted draw. Returns CPS resolving {:factual :counterfactual :weight :unaligned :status}. :strict? defaults true: incomplete coupling is refused. With false, fresh noise is explicitly reported; this makes no claim of full coupling. :run-opts supplies GFI executor/session options. Sessions are always closed.

query clj/s

(query model
       {:keys [posterior abductions evidence particles worlds interventions
               event strict? reconstruct seed]
        :or {particles 1 strict? true}
        :as request}
       &
       [run-opts])

Compose factual inference, reusable abduction and multiple worlds.

Supply exactly one of :posterior (an EmpiricalMeasure), :abductions (reusable draws), or :evidence (site values, importance inference with :particles, default 1). :worlds is an ordered vector of [name spec]; a spec may depend on previously computed worlds. Alternatively supply :interventions for one world named :counterfactual. :event optionally conditions on any predicate of the resulting world map.

:strict? defaults true. :reconstruct and :seed go to abduct-posterior; run-opts goes to GFI. Resolves a vector of weighted world draws. This evaluates a specified causal model; it does not identify it from data.

worlds clj/s

(worlds model abduction specs)

(worlds model abduction specs opts)

Evaluate ordered [name intervention-spec] pairs against ONE abducted draw. A spec is an intervention map or a function of already computed worlds; :factual is available initially. This expresses nested counterfactuals, e.g. use a mediator from world :untreated in a later :direct world. Resolves {:worlds {name result …} :weight :unaligned :status}.