Axiom Effect

Causal effect estimation for tabular data. Given a table, its causal graph and a treatment / outcome pair, Axiom Effect estimates what happens to the outcome when the treatment is set to one value instead of another, E[Y | do(T = b)] - E[Y | do(T = a)], with 90% and 50% intervals, and the whole dose-response curve. It is trained on simulated causal models, where the true effect is known.

Version 0.0.1 is experimental. The API and the weights will change in 0.0.x releases. Check its answers against what you know about your data.

The graph decides what to adjust for: the model reads only the treatment, the outcome and the graph's optimal adjustment set, so mediators, colliders and other variables that would bias the answer never enter. The graph can come from domain knowledge or from Axiom, the causal discovery model this is a sibling of.

6.5M parameters, fp32 safetensors (26 MB). Project page: maxpagels.com/axiom.

Recommended use (ballpark)

recommendation
graph a DAG over the table's columns that you trust, with no unmeasured common causes of the treatment and the outcome. The model takes it as true.
treatment continuous: at least 20 distinct values. Binary and categorical treatments are not supported yet.
treatment values inside the 2-98% quantiles of the observed treatment (refused outside them unless extrapolate=True): beyond them the data has no support for the answer.
rows trained on 128-1024. Below 128 it warns. Over 1024 rows, effect averages 8 random 1024-row subsets, whose intervals are those of 1024 rows: on the wide side.
adjustment set up to 18 variables, as in training (the table itself can have more columns: only the adjustment set is read).
missing values not supported in the treatment, the outcome and the adjustment set; other columns may have them.

Usage

pip install "git+https://huggingface.co/maxpagels/axiom-effect"
from axiom_effect import AxiomEffect

model = AxiomEffect.from_pretrained("maxpagels/axiom-effect")

graph = [("age", "price"), ("age", "sales"), ("price", "visits"), ("visits", "sales")]
r = model.effect(df, graph, treatment="price", outcome="sales")
print(r)

For example, on a simulated table:

Effect of price on sales (800 rows; adjusted for age)
  price 29.74 -> 36.89: -10.14   90% [-12.53, -7.738]   50% [-10.99, -9.248]
  dose-response, from price = 33.36:
    26.28  +9.224   90% [5.852, 12.66]
    29.74  +5.172   90% [3.908, 6.547]
    33.36  +0   90% [-0.8777, 0.8777]
    36.89  -4.971   90% [-6.539, -3.388]
    40.34  -9.736   90% [-13.38, -6.002]

Everything is in the data's own units: the treatment values in the treatment's, the effects in the outcome's (effect standardizes the columns it reads, as in training, and converts back). The graph can be:

  • a list of (cause, effect) column-name pairs, as above;
  • a (d, d) adjacency matrix in the table's column order (A[i, j] = 1 means i -> j);
  • a pandas DataFrame adjacency matrix with the column names as index and columns;
  • a discover() result from Axiom: its directed edges.
from axiom import Axiom

g = Axiom.from_pretrained("maxpagels/axiom-discovery").discover(df)
r = model.effect(df, g, treatment="price", outcome="sales")

A discovered graph is only as good as its edges. Undirected or confounded relations near the treatment or outcome are ignored with a warning, and if the discovered graph has no directed path from the treatment to the outcome the effect is exactly 0, with a warning too: one wrong edge is enough for that.

Reading the result

r.estimate        # the headline contrast: moving the treatment from its 25% to its 75% quantile
r.contrast        # those two treatment values, (a, b)
r.interval        # 90% interval of the contrast; r.interval50 the 50% one
r.adjustment      # the variables adjusted for
r.to_frame()      # the dose-response curve: each value's effect from the reference, with intervals
argument default meaning
contrast=(a, b) the 25% and 75% quantiles the headline effect: moving the treatment from a to b
values the 10/25/50/75/90% quantiles treatment values on the dose-response curve
reference the median where the curve starts (its effect is 0)

The curve's intervals are pointwise, not simultaneous. The intervals are the model's own quantiles, conformally calibrated on held-out simulated data from its training distribution. How well they cover on real data is not yet known.

If the graph has no directed path from the treatment to the outcome, setting the treatment cannot move the outcome: the effect is exactly 0, with a zero-width interval, whatever their correlation (r.zero_by_graph).

Limitations

  • The graph is taken as true. A missing confounder or a reversed edge biases the answer, and the interval does not widen for it.
  • No hidden confounders: front-door, instrumental-variable and other identification strategies beyond adjustment are not supported, and the model never says "not identifiable".
  • Continuous treatments only; average effects only (no per-row or conditional effects).
  • Trained and validated on simulated data only: no evaluation on real data yet.
  • Where the adjustment set nearly determines the treatment (poor overlap), and on purely linear data, classical estimators can be more accurate.

Versions

Each release is a tagged commit in this repo; main is the latest. The package loads the weights released with it, so code and weights always match. To use a specific release, install its code and load its weights by tag:

pip install "git+https://huggingface.co/maxpagels/axiom-effect@v0.0.1"
model = AxiomEffect.from_pretrained("maxpagels/axiom-effect")      # this package's release: v0.0.1
  • v0.0.1: first release: continuous treatments, a known DAG without hidden confounders, adjustment by the optimal adjustment set; conformally calibrated 90% and 50% intervals.
Downloads last month
-
Safetensors
Model size
6.53M params
Tensor type
F32
ยท
Inference Providers NEW
This model isn't deployed by any Inference Provider. ๐Ÿ™‹ Ask for provider support