Add documentation or example using EffectHandler on Constraint and CausalEstimand

[samjmolyneux]

Is Your Feature Request Related to a Problem? Please Describe

Currently we do not have any examples demonstrating how to use the effect_handlers attribute of causalprog.causal_problem.CausalEstimand and causalprog.causal_problem.Constraint.

When first reading the codebase, I had assumed that the effect_handlers attribute was added for numpyro.handlers such as do or condition, and then become confused by the presence of algorithms.do and algorithms.condition.

In a meeting on 25/09/2025, @willGraham01 mentioned the need for algorithms.do and algorithms.condition due to limitations using numpyro.handlers for the effect_handlers.

We would benefit from making it clearer why effect_handlers exist and how they differ from algorithms.do and algorithms.condition and what the limitation with the handlers is.

Describe the Solution You'd Like

Clarify in documentation or example notebook:

1. Why effect_handlers exist,
2. How they differ from algorithms.do/algorithms.condition,
3. What limitations in NumPyro’s effect handlers led to requiring the algorithms layer.

Describe Alternatives You've Considered

No response

Additional Context

No response

[willGraham01]

algorithms and effect_handlers both exist to serve slightly different circumstances under which we want to do similar things. Colloquially we'd have

numpyro.handler.<method>(g.model, ...) == (algorithms.<method>(g, ...)).model()
# Effect handlers edit models               algorithms edit graphs

Let's suppose we have a setup like the following;

• Parameter nodes $\mu_U$, $\mu_V$.
• RVs
  • $U\sim\mathcal{N}(\mu_U, 1)$,
  • $V\sim\mathcal{N}(\mu_V, 1)$,
  • $X | U, V \sim\mathcal{N}(U, V)$.
• For ease of the example, we'll also use $d$ and $\epsilon$ as placeholders for some given data and tolerance in said data, respectively.

Then the two use cases that I envision are as follows.

effect_handlers

These are used when some, but not all of the constraints and / or causal estimand would require "edits" to the graph (equivalently edits to the model). Conditioning a RV on a value or applying "do" are the ones that jump to mind.

For example, suppose that we have the CP

$$\sigma = \mathbb{E}[X], \quad \text{s.t.}\quad c:=\vert \mathbb{E}[X | V = 1] - d | < \epsilon.$$

Evaluating $\sigma$ requires a model of our graph without any conditioning being done. Conversely, evaluating $c$ requires a model of our graph with conditioning applied. As such, we have our graph create two realizations of its .model attribute, one with the effect_handler for condition pre-applied, and one without. Since this is all one CausalProblem, we need to do apply certain effect_handlers to the graph model when evaluating some parts of the problem, and don't want to apply them when evaluating others:

g = Graph(...)

# sigma = E[X]
sigma = CausalEstimand(do_with_samples=lambda **rvs: rvs[X].mean())

# Since we condition on V = 1 in the constraint, we need to inform our CP
# this is the case.
condition_on_V1 = HandlerToApply(numpyro.handlers.condition, {"V": 1})
# Now we can setup the constraint that relies on this, but uses the same graph structure
# as the rest of our CP.
c = Constraint(
    condition_on_V1,
    model_quantity=lambda **rvs: rvs[X].mean(),
    data=d,
    tolerance=epsilon,
)

causal_prob = CausalProblem(g, c, sigma)

# Things like the Lagrangian, which require BOTH evaluation of sigma and the constraint,
# will now be able to do this successfully, without the need to create a separate graph
# representing the "V = 1" conditioned graph.

algorithms

(The hypothetical) algorithms.condition returns a new graph instance representing the result of applying the given effect. This can be helpful for sampling purposes, or creating new models from others in which to pose new problems.

In the context of the example above,

conditioned_g = algorithms.condition(g, {"V":1})

# NOTE: same def as sigma above
sigma_conditioned = CausalEstimand(do_with_samples=lambda **rvs: rvs[X].mean())
# NOTE: No longer passing a handler!
c_conditioned = Constraint(
    model_quantity=lambda **rvs: rvs[X].mean(),
    data=d,
    tolerance=epsilon,
)

causal_prob_on_conditioned_graph = CausalProblem(conditioned_g, c_conditioned, sigma_conditioned)

is the equivalent of doing

g = Graph(...)
condition_on_V1 = HandlerToApply(numpyro.handlers.condition, {"V": 1})

# sigma = E[X | V = 1]
sigma = CausalEstimand(condition_on_V1, do_with_samples=lambda **rvs: rvs[X].mean())

# | E[X | V = 1] - d | < epsilon
c = Constraint(
    condition_on_V1,
    model_quantity=lambda **rvs: rvs[X].mean(),
    data=d,
    tolerance=epsilon,
)

causal_prob = CausalProblem(g, c, sigma)

It's impossible to pose the CP outlined in the above section on conditioned_g, since V = 1 has already been applied to the graph. Conversely, it is impossible to draw samples from g under the conditioning V = 1, we need to create conditioned_g and sample from it to do this.