dowhy package
Subpackages
- dowhy.api package
- dowhy.causal_estimators package
- Submodules
- dowhy.causal_estimators.econml_cate_estimator module
- dowhy.causal_estimators.instrumental_variable_estimator module
- dowhy.causal_estimators.linear_regression_estimator module
- dowhy.causal_estimators.propensity_score_matching_estimator module
- dowhy.causal_estimators.propensity_score_stratification_estimator module
- dowhy.causal_estimators.propensity_score_weighting_estimator module
- dowhy.causal_estimators.regression_discontinuity_estimator module
- Module contents
- dowhy.causal_refuters package
- dowhy.data_transformers package
- dowhy.do_samplers package
- dowhy.utils package
Submodules
dowhy.causal_estimator module
- class dowhy.causal_estimator.CausalEstimate(estimate, target_estimand, realized_estimand_expr, **kwargs)[source]
Bases:
objectClass for the estimate object that every causal estimator returns
- class dowhy.causal_estimator.CausalEstimator(data, identified_estimand, treatment, outcome, control_value=0, treatment_value=1, test_significance=False, evaluate_effect_strength=False, confidence_intervals=False, target_units=None, effect_modifiers=None, params=None)[source]
Bases:
objectBase class for an estimator of causal effect.
Subclasses implement different estimation methods. All estimation methods are in the package “dowhy.causal_estimators”
Initializes an estimator with data and names of relevant variables.
More description.
- Parameters
data – data frame containing the data
identified_estimand – probability expression representing the target identified estimand to estimate.
treatment – name of the treatment variable
outcome – name of the outcome variable
control_value – Value of the treatment in the control group, for effect estimation. If treatment is multi-variate, this can be a list.
treatment_value – Value of the treatment in the treated group, for effect estimation. If treatment is multi-variate, this can be a list.
test_significance – whether to test significance
evaluate_effect_strength – (Experimental) whether to evaluate the strength of effect
confidence_intervals – (Experimental) Binary flag indicating whether confidence intervals should be computed.
target_units – (Experimental) The units for which the treatment effect should be estimated. This can be a string for common specifications of target units (namely, “ate”, “att” and “atc”). It can also be a lambda function that can be used as an index for the data (pandas DataFrame). Alternatively, it can be a new DataFrame that contains values of the effect_modifiers and effect will be estimated only for this new data.
effect_modifiers – variables on which to compute separate effects, or return a heterogeneous effect function. Not all methods support this currently.
params – (optional) additional method parameters
- Returns
an instance of the estimator class.
- do(x)[source]
Method that implements the do-operator.
Given a value x for the treatment, returns the expected value of the outcome when the treatment is intervened to a value x.
- Parameters
x – Value of the treatment
- Returns
Value of the outcome when treatment is intervened/set to x.
- estimate_effect()[source]
Base estimation method that calls the estimate_effect method of its calling subclass.
Can optionally also test significance and estimate effect strength for any returned estimate.
TODO: Enable methods to return a confidence interval in addition to the point estimate.
- Parameters
self – object instance of class Estimator
- Returns
point estimate of causal effect
- test_significance(estimate, num_simulations=None)[source]
Test statistical significance of obtained estimate.
Uses resampling to create a non-parametric significance test. A general procedure. Individual estimators can override this method.
- Parameters
self – object instance of class Estimator
estimate – obtained estimate
num_simulations – (optional) number of simulations to run
- Returns
dowhy.causal_graph module
- class dowhy.causal_graph.CausalGraph(treatment_name, outcome_name, graph=None, common_cause_names=None, instrument_names=None, effect_modifier_names=None, observed_node_names=None, missing_nodes_as_confounders=False)[source]
Bases:
objectClass for creating and modifying the causal graph.
Accepts a graph string (or a text file) in gml format (preferred) and dot format. Graphviz-like attributes can be set for edges and nodes. E.g. style=”dashed” as an edge attribute ensures that the edge is drawn with a dashed line.
If a graph string is not given, names of treatment, outcome, and confounders, instruments and effect modifiers (if any) can be provided to create the graph.
- build_graph(common_cause_names, instrument_names, effect_modifier_names)[source]
Creates nodes and edges based on variable names and their semantics.
Currently only considers the graphical representation of “direct” effect modifiers. Thus, all effect modifiers are assumed to be “direct” unless otherwise expressed using a graph. Based on the taxonomy of effect modifiers by VanderWheele and Robins: “Four types of effect modification: A classification based on directed acyclic graphs. Epidemiology. 2007.”
dowhy.causal_identifier module
- class dowhy.causal_identifier.CausalIdentifier(graph, estimand_type, proceed_when_unidentifiable=False)[source]
Bases:
objectClass that implements different identification methods.
Currently supports backdoor and instrumental variable identification methods. The identification is based on the causal graph provided.
Other specific ways of identification, such as the ID* algorithm, minimal adjustment criteria, etc. will be added in the future. If you’d like to contribute, please raise an issue or a pull request on Github.
- identify_effect()[source]
Main method that returns an identified estimand (if one exists).
Uses both backdoor and instrumental variable methods to check if an identified estimand exists, based on the causal graph.
- Parameters
self – instance of the CausalEstimator class (or its subclass)
- Returns
target estimand, an instance of the IdentifiedEstimand class
dowhy.causal_model module
Module containing the main model class for the dowhy package.
- class dowhy.causal_model.CausalModel(data, treatment, outcome, graph=None, common_causes=None, instruments=None, effect_modifiers=None, estimand_type='nonparametric-ate', proceed_when_unidentifiable=False, missing_nodes_as_confounders=False, **kwargs)[source]
Bases:
objectMain class for storing the causal model state.
Initialize data and create a causal graph instance.
Assigns treatment and outcome variables. Also checks and finds the common causes and instruments for treatment and outcome.
At least one of graph, common_causes or instruments must be provided.
- Parameters
data – a pandas dataframe containing treatment, outcome and other
variables. :param treatment: name of the treatment variable :param outcome: name of the outcome variable :param graph: path to DOT file containing a DAG or a string containing a DAG specification in DOT format :param common_causes: names of common causes of treatment and _outcome :param instruments: names of instrumental variables for the effect of treatment on outcome :param effect_modifiers: names of variables that can modify the treatment effect (useful for heterogeneous treatment effect estimation) :param estimand_type: the type of estimand requested (currently only “nonparametric-ate” is supported). In the future, may support other specific parametric forms of identification. :proceed_when_unidentifiable: does the identification proceed by ignoring potential unobserved confounders. Binary flag. :missing_nodes_as_confounders: Binary flag indicating whether variables in the dataframe that are not included in the causal graph, should be automatically included as confounder nodes.
- Returns
an instance of CausalModel class
- do(x, identified_estimand, method_name=None, method_params=None)[source]
Do operator for estimating values of the outcome after intervening on treatment.
- Parameters
identified_estimand – a probability expression that represents the effect to be estimated. Output of CausalModel.identify_effect method
method_name – any of the estimation method to be used. See docs for estimate_effect method for a list of supported estimation methods.
method_params – Dictionary containing any method-specific parameters. These are passed directly to the estimating method.
- Returns
an instance of the CausalEstimate class, containing the causal effect estimate and other method-dependent information
- estimate_effect(identified_estimand, method_name=None, control_value=0, treatment_value=1, test_significance=None, evaluate_effect_strength=False, confidence_intervals=False, target_units='ate', effect_modifiers=None, method_params=None)[source]
Estimate the identified causal effect.
- Currently requires an explicit method name to be specified. Method names follow the convention of identification method followed by the specific estimation method: “[backdoor/iv].estimation_method_name”. Following methods are supported.
Propensity Score Matching: “backdoor.propensity_score_matching”
Propensity Score Stratification: “backdoor.propensity_score_stratification”
Propensity Score-based Inverse Weighting: “backdoor.propensity_score_weighting”
Linear Regression: “backdoor.linear_regression”
Instrumental Variables: “iv.instrumental_variable”
Regression Discontinuity: “iv.regression_discontinuity”
In addition, you can directly call any of the EconML estimation methods. The convention is “backdoor.econml.path-to-estimator-class”. For example, for the double machine learning estimator (“DMLCateEstimator” class) that is located inside “dml” module of EconML, you can use the method name, “backdoor.econml.dml.DMLCateEstimator”.
- Parameters
identified_estimand – a probability expression that represents the effect to be estimated. Output of CausalModel.identify_effect method
method_name – name of the estimation method to be used.
control_value – Value of the treatment in the control group, for effect estimation. If treatment is multi-variate, this can be a list.
treatment_value – Value of the treatment in the treated group, for effect estimation. If treatment is multi-variate, this can be a list.
test_significance – Binary flag on whether to additionally do a statistical signficance test for the estimate.
evaluate_effect_strength – (Experimental) Binary flag on whether to estimate the relative strength of the treatment’s effect. This measure can be used to compare different treatments for the same outcome (by running this method with different treatments sequentially).
confidence_intervals – (Experimental) Binary flag indicating whether confidence intervals should be computed.
target_units – (Experimental) The units for which the treatment effect should be estimated. This can be of three types. (1) a string for common specifications of target units (namely, “ate”, “att” and “atc”), (2) a lambda function that can be used as an index for the data (pandas DataFrame), or (3) a new DataFrame that contains values of the effect_modifiers and effect will be estimated only for this new data.
effect_modifiers – Names of effect modifier variables can be (optionally) specified here too, since they do not affect identification. If None, the effect_modifiers from the CausalModel are used.
method_params – Dictionary containing any method-specific parameters. These are passed directly to the estimating method. See the docs for each estimation method for allowed method-specific params.
- Returns
An instance of the CausalEstimate class, containing the causal effect estimate and other method-dependent information
- identify_effect(proceed_when_unidentifiable=None)[source]
Identify the causal effect to be estimated, using properties of the causal graph.
- Parameters
proceed_when_unidentifiable – Binary flag indicating whether identification should proceed in the presence of (potential) unobserved confounders.
- Returns
a probability expression (estimand) for the causal effect if identified, else NULL
- refute_estimate(estimand, estimate, method_name=None, **kwargs)[source]
Refute an estimated causal effect.
- If method_name is provided, uses the provided method. In the future, we may support automatic selection of suitable refutation tests. Following refutation methods are supported.
Adding a randomly-generated confounder: “random_common_cause”
Adding a confounder that is associated with both treatment and outcome: “add_unobserved_common_cause”
Replacing the treatment with a placebo (random) variable): “placebo_treatment_refuter”
Removing a random subset of the data: “data_subset_refuter”
- Parameters
estimand – target estimand, an instance of the IdentifiedEstimand class (typically, the output of identify_effect)
estimate – estimate to be refuted, an instance of the CausalEstimate class (typically, the output of estimate_effect)
method_name – name of the refutation method
**kwargs –
(optional) additional arguments that are passed directly to the refutation method. Can specify a random seed here to ensure reproducible results (‘random_seed’ parameter). For method-specific parameters, consult the documentation for the specific method. All refutation methods are in the causal_refuters subpackage.
- Returns
an instance of the RefuteResult class
dowhy.causal_refuter module
- class dowhy.causal_refuter.CausalRefutation(estimated_effect, new_effect, refutation_type)[source]
Bases:
objectClass for storing the result of a refutation method.
dowhy.data_transformer module
dowhy.datasets module
Module for generating some sample datasets.
- dowhy.datasets.choice(a, size=None, replace=True, p=None)
Generates a random sample from a given 1-D array
New in version 1.7.0.
Note
New code should use the
choicemethod of adefault_rng()instance instead; please see the random-quick-start.- a1-D array-like or int
If an ndarray, a random sample is generated from its elements. If an int, the random sample is generated as if it were
np.arange(a)- sizeint or tuple of ints, optional
Output shape. If the given shape is, e.g.,
(m, n, k), thenm * n * ksamples are drawn. Default is None, in which case a single value is returned.- replaceboolean, optional
Whether the sample is with or without replacement. Default is True, meaning that a value of
acan be selected multiple times.- p1-D array-like, optional
The probabilities associated with each entry in a. If not given, the sample assumes a uniform distribution over all entries in
a.
- samplessingle item or ndarray
The generated random samples
- ValueError
If a is an int and less than zero, if a or p are not 1-dimensional, if a is an array-like of size 0, if p is not a vector of probabilities, if a and p have different lengths, or if replace=False and the sample size is greater than the population size
randint, shuffle, permutation random.Generator.choice: which should be used in new code
Setting user-specified probabilities through
puses a more general but less efficient sampler than the default. The general sampler produces a different sample than the optimized sampler even if each element ofpis 1 / len(a).Sampling random rows from a 2-D array is not possible with this function, but is possible with Generator.choice through its
axiskeyword.Generate a uniform random sample from np.arange(5) of size 3:
>>> np.random.choice(5, 3) array([0, 3, 4]) # random >>> #This is equivalent to np.random.randint(0,5,3)
Generate a non-uniform random sample from np.arange(5) of size 3:
>>> np.random.choice(5, 3, p=[0.1, 0, 0.3, 0.6, 0]) array([3, 3, 0]) # random
Generate a uniform random sample from np.arange(5) of size 3 without replacement:
>>> np.random.choice(5, 3, replace=False) array([3,1,0]) # random >>> #This is equivalent to np.random.permutation(np.arange(5))[:3]
Generate a non-uniform random sample from np.arange(5) of size 3 without replacement:
>>> np.random.choice(5, 3, replace=False, p=[0.1, 0, 0.3, 0.6, 0]) array([2, 3, 0]) # random
Any of the above can be repeated with an arbitrary array-like instead of just integers. For instance:
>>> aa_milne_arr = ['pooh', 'rabbit', 'piglet', 'Christopher'] >>> np.random.choice(aa_milne_arr, 5, p=[0.5, 0.1, 0.1, 0.3]) array(['pooh', 'pooh', 'pooh', 'Christopher', 'piglet'], # random dtype='<U11')
- dowhy.datasets.create_dot_graph(treatments, outcome, common_causes, instruments, effect_modifiers=[])[source]
- dowhy.datasets.create_gml_graph(treatments, outcome, common_causes, instruments, effect_modifiers=[])[source]
- dowhy.datasets.linear_dataset(beta, num_common_causes, num_samples, num_instruments=0, num_effect_modifiers=0, num_treatments=1, treatment_is_binary=True, outcome_is_binary=False)[source]
dowhy.do_sampler module
- class dowhy.do_sampler.DoSampler(data, params=None, variable_types=None, num_cores=1, causal_model=None, keep_original_treatment=False)[source]
Bases:
objectBase class for a sampler from the interventional distribution.
Initializes a do sampler with data and names of relevant variables.
Do sampling implements the do() operation from Pearl (2000). This is an operation is defined on a causal bayesian network, an explicit implementation of which is the basis for the MCMC sampling method.
We abstract the idea behind the three-step process to allow other methods, as well. The disrupt_causes method is the means to make treatment assignment ignorable. In the Pearlian framework, this is where we cut the edges pointing into the causal state. With other methods, this will typically be by using some approach which assumes conditional ignorability (e.g. weighting, or explicit conditioning with Robins G-formula.)
Next, the make_treatment_effective method reflects the assumption that the intervention we impose is “effective”. Most simply, we fix the causal state to some specific value. We skip this step there is no value specified for the causal state, and the original values are used instead.
Finally, we sample from the resulting distribution. This can be either from a point_sample method, in the case that the inference method doesn’t support batch sampling, or the sample method in the case that it does. For convenience, the point_sample method parallelizes with multiprocessing using the num_cores kwargs to set the number of cores to use for parallelization.
While different methods will have their own class attributes, the _df method should be common to all methods. This is them temporary dataset which starts as a copy of the original data, and is modified to reflect the steps of the do operation. Read through the existing methods (weighting is likely the most minimal) to get an idea of how this works to implement one yourself.
- Parameters
data – pandas.DataFrame containing the data
identified_estimand – dowhy.causal_identifier.IdentifiedEstimand: and estimand using a backdoor method
for effect identification. :param treatments: list or str: names of the treatment variables :param outcomes: list or str: names of the outcome variables :param variable_types: dict: A dictionary containing the variable’s names and types. ‘c’ for continuous, ‘o’ for ordered, ‘d’ for discrete, and ‘u’ for unordered discrete. :param keep_original_treatment: bool: Whether to use make_treatment_effective, or to keep the original treatment assignments. :param params: (optional) additional method parameters
- disrupt_causes()[source]
Override this method to render treatment assignment conditionally ignorable :return:
- make_treatment_effective(x)[source]
This is more likely the implementation you’d like to use, but some methods may require overriding this method to make the treatment effective. :param x: :return: