-
Notifications
You must be signed in to change notification settings - Fork 995
API proposal for v1
DoWhy's current API was designed for effect estimation task. As the library expands to more tasks, we revisit some of the design decisions in this doc and propose an updated API. In particular, the most significant change is moving from an object-oriented API to a functional API. Beyond this change, our goal is to retain the current effect estimation API with exactly the same signatures while adding new API functions to include other tasks.
Welcome your contributions and feedback. You can join in the discussion page here.
DoWhy started out by using a CausalModel class for the effect estimation task, and the current API provides an easy four-step process.
m = CausalModel(data, graph, ..)
identified_estimand = m.identify_effect()
estimate = m.estimate_effect(identified_estimand,
method="dowhy.propensity_score_matching")
refute = m.refute_estimate(identified_estimand, estimate,
method=”placebo_treatment_refuter”)However, there can be other uses of CausalModel for different tasks. Further, object-oriented methods do not explicitly mention all the inputs required (e.g., the identification method does not require access to data).
To make the function arguments explicit and avoid book-keeping for the CausalModel class for different tasks, we propose switching to a functional approach. The idea is that the same code will work in the new API, often just by replacing CausalModel.method with dowhy.method([data,graph]) where the parameters may be optional.
# Ia. Create a networkx DiGraph as causal graph
# This can be later expanded to support ADMGs or other mixed graphs
# But the assumption is that the object will be a networkx Graph object or at least follows the basic graph interface that we define below.
causal_graph = networkx.DiGraph(...)
# Ia. [Alternative] uses causal discovery
# Using LiNGAM (an example of causal discovery)
causal_graph = dowhy.discover.DirectLingam().learn_graph(data)
# user can edit the graph after visualizing it, using standard networkx operations
...
# Ib. The user can validate whether the constraints from the graph are satisfied by data
validate = dowhy.refute_graph(causal_graph, data)
# II. Identify causal effect and return target estimands
estimand = dowhy.identify_effect(causal_graph
action_node="X",
outcome_node="Y",
observed_nodes=...)
# IIIa. Fit estimand
# Directly calling the causal estimator class
estimator = dowhy.LinearRegressionEstimator(estimand)
estimator.fit(data)
# IIIb. Estimate the target estimand using a statistical method.
estimate = estimator.estimate_effect(action_value=..., control_value=...)
# IIIb. Alternative.
estimate = estimator.do(value=...) - estimator.do(value=...)
# IV. Refute the obtained estimate using multiple robustness checks.
dowhy.refute_estimate(estimate, estimand, data, causal_graph,
method_name="random_common_cause")