y0
(pronounced "why not?") is Python code for causal inference.
y0
has a fully featured internal domain specific language for representing
probability expressions:
from y0.dsl import P, A, B
# The probability of A given B
expr_1 = P(A | B)
# The probability of A given not B
expr_2 = P(A | ~B)
# The joint probability of A and B
expr_3 = P(A, B)
It can also be used to manipulate expressions:
from y0.dsl import P, A, B, Sum
P(A, B).marginalize(A) == Sum[A](P(A, B))
P(A, B).conditional(A) == P(A, B) / Sum[A](P(A, B))
DSL objects can be converted into strings with str()
and parsed back
using y0.parser.parse_y0()
.
A full demo of the DSL can be found in this Jupyter Notebook
y0
has a notion of acyclic directed mixed graphs built on top of
networkx
that can be used to model causality:
from y0.graph import NxMixedGraph
from y0.dsl import X, Y, Z1, Z2
# Example from:
# J. Pearl and D. Mackenzie (2018)
# The Book of Why: The New Science of Cause and Effect.
# Basic Books, p. 240.
napkin = NxMixedGraph.from_edges(
directed=[
(Z2, Z1),
(Z1, X),
(X, Y),
],
undirected=[
(Z2, X),
(Z2, Y),
],
)
y0
has many pre-written examples in y0.examples
from Pearl, Shpitser,
Bareinboim, and others.
y0
provides actual implementations of many algorithms that have remained
unimplemented for the last 15 years of publications including:
Algorithm | Reference |
---|---|
ID | Shpitser and Pearl, 2006 |
IDC | Shpitser and Pearl, 2008 |
ID* | Shpitser and Pearl, 2012 |
IDC* | Shpitser and Pearl, 2012 |
Surrogate Outcomes | Tikka and Karvanen, 2018 |
Apply an algorithm to an ADMG and a causal query to generate an estimand represented in the DSL like:
from y0.dsl import P, X, Y
from y0.examples import napkin
from y0.algorithm.identify import Identification, identify
# TODO after ID* and IDC* are done, we'll update this interface
query = Identification.from_expression(graph=napkin, query=P(Y @ X))
estimand = identify(query)
assert estimand == P(Y @ X)
The most recent release can be installed from PyPI with:
$ pip install y0
The most recent code and data can be installed directly from GitHub with:
$ pip install git+https://github.com/y0-causal-inference/y0.git
Contributions, whether filing an issue, making a pull request, or forking, are appreciated. See CONTRIBUTING.md for more information on getting involved.
The code in this package is licensed under the BSD-3-Clause license.
Before we publish an application note on y0
, you can cite this software
via our Zenodo record (also see the badge above):
@software{y0,
author = {Charles Tapley Hoyt and
Jeremy Zucker and
Marc-Antoine Parent},
title = {y0-causal-inference/y0},
month = jun,
year = 2021,
publisher = {Zenodo},
version = {v0.1.0},
doi = {10.5281/zenodo.4950768},
url = {https://doi.org/10.5281/zenodo.4950768}
}
This project has been supported by several organizations (in alphabetical order):
- Harvard Program in Therapeutic Science - Laboratory of Systems Pharmacology
- Pacific Northwest National Laboratory
The development of the Y0 Causal Inference Engine has been funded by the following grants:
Funding Body | Program | Grant |
---|---|---|
DARPA | Automating Scientific Knowledge Extraction (ASKE) | HR00111990009 |
PNNL Data Model Convergence Initiative | Causal Inference and Machine Learning Methods for Analysis of Security Constrained Unit Commitment (SCY0) | 90001 |
DARPA | Automating Scientific Knowledge Extraction and Modeling (ASKEM) | HR00112220036 |
This package was created with @audreyfeldroy's cookiecutter package using @cthoyt's cookiecutter-python-package template.
See developer instructions
The final section of the README is for if you want to get involved by making a code contribution.
To install in development mode, use the following:
$ git clone git+https://github.com/y0-causal-inference/y0.git
$ cd y0
$ pip install -e .
After cloning the repository and installing tox
with pip install tox
, the unit tests in the tests/
folder can be
run reproducibly with:
$ tox
Additionally, these tests are automatically re-run with each commit in a GitHub Action.
After installing the package in development mode and installing
tox
with pip install tox
, the commands for making a new release are contained within the finish
environment
in tox.ini
. Run the following from the shell:
$ tox -e finish
This script does the following:
- Uses BumpVersion to switch the version number in the
setup.cfg
andsrc/y0/version.py
to not have the-dev
suffix - Packages the code in both a tar archive and a wheel
- Uploads to PyPI using
twine
. Be sure to have a.pypirc
file configured to avoid the need for manual input at this step - Push to GitHub. You'll need to make a release going with the commit where the version was bumped.
- Bump the version to the next patch. If you made big changes and want to bump the version by minor, you can
use
tox -e bumpversion minor
after.