y0
v0.2.10
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 y0The most recent code and data can be installed directly from GitHub with:
$ pip install git+https://github.com/y0-causal-inference/y0.gitContributions, 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):
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-snekpack template.
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 .This project uses cruft to keep boilerplate (i.e., configuration, contribution guidelines, documentation
configuration)
up-to-date with the upstream cookiecutter package. Update with the following:
pip install cruft
cruft updateMore info on Cruft's update command is available here.
After cloning the repository and installing tox with pip install tox tox-uv,
the unit tests in the tests/ folder can be run reproducibly with:
tox -e pyAdditionally, these tests are automatically re-run with each commit in a GitHub Action.
The documentation can be built locally using the following:
git clone git+https://github.com/y0-causal-inference/y0.git
cd y0
tox -e docs
open docs/build/html/index.htmlThe documentation automatically installs the package as well as the docs
extra specified in the pyproject.toml. sphinx plugins
like texext can be added there. Additionally, they need to be added to the
extensions list in docs/source/conf.py.
The documentation can be deployed to ReadTheDocs using
this guide.
The .readthedocs.yml YAML file contains all the configuration you'll need.
You can also set up continuous integration on GitHub to check not only that
Sphinx can build the documentation in an isolated environment (i.e., with tox -e docs-test)
but also that ReadTheDocs can build it too.
Zenodo is a long-term archival system that assigns a DOI to each release of your package.
After these steps, you're ready to go! After you make "release" on GitHub (steps for this are below), you can navigate to https://zenodo.org/account/settings/github/repository/y0-causal-inference/y0 to see the DOI for the release and link to the Zenodo record for it.
You only have to do the following steps once.
You have to do the following steps once per machine. Create a file in your home directory called
.pypirc and include the following:
[distutils]
index-servers =
pypi
testpypi
[pypi]
username = __token__
password = <the API token you just got>
# This block is optional in case you want to be able to make test releases to the Test PyPI server
[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = <an API token from test PyPI>Note that since PyPI is requiring token-based authentication, we use __token__ as the user, verbatim.
If you already have a .pypirc file with a [distutils] section, just make sure that there is an index-servers
key and that pypi is in its associated list. More information on configuring the .pypirc file can
be found here.
After installing the package in development mode and installing
tox with pip install tox tox-uv,
run the following from the shell:
tox -e finishThis script does the following:
pyproject.toml, CITATION.cff, src/y0/version.py,
and docs/source/conf.py to not have the -dev suffixbuild
twine.tox -e bumpversion -- minor after.This will trigger Zenodo to assign a DOI to your release as well.
