|Build Status|
.. image:: docs/source/_static/img/chirho_logo_wide.png
:alt: ChiRho logo
:align: center
.. index-inclusion-marker
Causal Reasoning with ChiRho
============================
ChiRho is a causal extension to the Pyro probabilistic programming
language. It was built to bridge the gap between the capabilities of
modern probabilistic programming systems, such as Pyro, and the needs of
policymakers, scientists, and AI researchers, who often want to use
models to answer their questions about cause-and-effect relationships.
As a non-exhaustive set of examples, ChiRho makes it easier to
answer the following kinds of causal questions that appear frequently in
practice.
- **Interventional**: *How many COVID-19 hospitalizations will occur if
the USA imposes a national mask mandate?*
- **Counterfactual**: *Given that 100,000 people were infected with
COVID-19 in the past month, how many would have been infected if a
mask mandate had been in place?*
- **Explanation**: *Why were 100,000 people infected with COVID-19 in
the past month?*
- **Causal structure discovery**: *What individual attributes influence
risk of COVID-19 hospitalization?*
To see how ChiRho supports causal reasoning, take a look at our `Tutorial <https://basisresearch.github.io/chirho/tutorial_i.html>`_.
Installation
------------
**Install using pip:**
.. code:: sh
pip install chirho
**Install from source:**
.. code:: sh
git clone git@github.com:BasisResearch/chirho.git
cd chirho
git checkout master
pip install .
**Install with extra packages:**
To install the dependencies required to run the tutorials in
``examples``/``tutorials`` directories, please use the following
command:
.. code:: sh
pip install chirho[extras]
Make sure that the models come from the same release version of the
`ChiRho source
code <https://github.com/BasisResearch/chirho/releases>`__ as you
have installed.
Getting Started
---------------
Below is a simple example of how to use ChiRho to answer an
interventional question. For more in-depth examples, go to `Learn
more <#learn-more>`__.
.. code:: python
import torch
import pyro
import pyro.distributions as dist
from chirho.interventional.handlers import do
pyro.set_rng_seed(101)
# Define a causal model with single confounder h
def model():
h = pyro.sample("h", dist.Normal(0, 1))
x = pyro.sample("x", dist.Normal(h, 1))
y = pyro.sample("y", dist.Normal(x + h, 1))
return y
# Define a causal query (here intervening on x)
def queried_model():
return do(model, {"x": 1})
# Generate 10,000 samples from the observational distribution P(y) ~ N(0, 2)
obs_samples = pyro.infer.Predictive(model, num_samples=1000)()["y"]
# Generate 10,000 samples from the interventional distribution P(y | do(X=1)) ~ N(1, 1)
int_samples = pyro.infer.Predictive(queried_model(), num_samples=1000)()["y"]
Learn more
----------
We have written a number of tutorials and examples for ChiRho. We
have tried to choose simple examples that would be of interest to both
the causal inference and probabilistic programming communities: they
collectively span Pearl’s causal hierarchy (Pearl 2009), and
most are broadly applicable, empirically validated, have an
unconventional or limited identification result, and make use of modern
probabilistic machine learning tools, like neural networks or stochastic
variational inference.
Our examples demonstrate how real-world causal assumptions can be expressed as probabilistic programs
and real-world causal estimands can be expressed as program transformations.
These example illustrate how ChiRho is compatible with any inference method
implemented in Pyro, including the kinds of scalable gradient-based
approximations that power much of the modern probabilistic machine learning landscape.
- `Tutorial <https://basisresearch.github.io/chirho/tutorial_i.html>`_
- Key observations inspiring ChiRho's design and outlines a causal Bayesian workflow for using ChiRho to answer causal questions
- `Example: Backdoor Adjustment Criteria <https://basisresearch.github.io/chirho/backdoor.html>`_
- Adjusting for observed confounders
- `Example: Causal Effect Variational Autoencoder <https://basisresearch.github.io/chirho/cevae.html>`_
- Causal inference with deep models and proxy variables
- `Example: Mediation analysis and (in)direct effects <https://basisresearch.github.io/chirho/mediation.html>`_
- Mediation analysis for path specific effects
- `Example: Deep structural causal model counterfactuals <https://basisresearch.github.io/chirho/deepscm.html>`_
- Counterfactuals with normalizing flows
- `Example: Structured Latent Confounders <https://basisresearch.github.io/chirho/slc.html>`_
- Causal effect estimation when latent confounders are shared across groups
- `Example: Synthetic difference-in-differences <https://basisresearch.github.io/chirho/sdid.html>`_
- Counterfactual estimation from longitudinal data
- `Example: Robust estimation with the DR learner <https://basisresearch.github.io/chirho/dr_learner.html>`_
- Heterogeneous causal effect estimation with a misspecified model
- `Example: Estimating the effects of drugs on gene expression <https://basisresearch.github.io/chirho/sciplex.html>`_
- Causal inference with single-cell RNA-seq data
- `Example: Causal reasoning in dynamical systems <https://basisresearch.github.io/chirho/dynamical_intro.html>`_
- Causal inference with continuous-time dynamical systems
- `Design notes <https://basisresearch.github.io/chirho/design_notes>`_
- Technical implementation details of ChiRho using effect handlers
*Note*: These tutorials and examples assume some familiarity with Pyro and
probabilistic programming. For introductory Pyro tutorials, please see
`Additional background reading
material <#additional-background-reading-material>`__ below.
Documentation
-------------
- `Counterfactual <https://basisresearch.github.io/chirho/counterfactual.html>`_
- Effect handlers for counterfactual world splitting
- `Interventional <https://basisresearch.github.io/chirho/interventional.html>`_
- Effect handlers for performing interventions
- `Observational <https://basisresearch.github.io/chirho/observational.html>`_
- Effect handler utilities for computing probabilistic quantities for
partially deterministic models which is useful for counterfactual reasoning
- `Indexed <https://basisresearch.github.io/chirho/indexed.html>`_
- Effect handler utilities for named indices in ChiRho which is useful for manipluating
and tracking counterfactual worlds
- `Dynamical <https://basisresearch.github.io/chirho/dynamical.html>`_
- Operations and effect handlers for counterfactual reasoning in dynamical systems
Caveats
-------
ChiRho does not answer causal questions by magic. In fact, there is
no escaping the fact that
*behind any causal conclusion there must lie some causal assumption,*
a phrase made famous by Judea Pearl (Pearl 2009). Instead,
ChiRho provides a substrate for writing causal assumptions as
probabilistic programs, and for writing causal questions in terms of
program transformations.
Additional background reading material
--------------------------------------
- Causal Probabilistic Programming Without Tears
https://drive.google.com/file/d/1Uzjg-vX77BdSnAcfpUcb-aIXxhnAPI24/view?usp=sharing
- Introduction to Pyro: \ http://pyro.ai/examples/intro_long.html
- Tensor shapes in Pyro: \ http://pyro.ai/examples/tensor_shapes.html
- A guide to programming with effect handlers in
Pyro \ http://pyro.ai/examples/effect_handlers.html
- Minipyro: \ http://pyro.ai/examples/minipyro.html
- Reparameterization of Pyro
programs: \ https://docs.pyro.ai/en/stable/infer.reparam.html
- Optional: getting started with
NumPyro \ https://num.pyro.ai/en/stable/getting_started.html
References
----------
Pearl, Judea. *Causality: Models, Reasoning and Inference*. 2nd ed. USA: Cambridge University Press, 2009.
.. |Build Status| image:: https://github.com/BasisResearch/chirho/actions/workflows/test.yml/badge.svg
:target: https://github.com/BasisResearch/chirho/actions/workflows/test.yml
Raw data
{
"_id": null,
"home_page": "https://www.basis.ai/",
"name": "chirho",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "machine learning statistics probabilistic programming bayesian modeling pytorch",
"author": "Basis",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/f5/a1/2b8e0410f9e7174b9abc3edda057a1a62665795be6425bb6391b94b9b3d8/chirho-0.2.0.tar.gz",
"platform": null,
"description": "|Build Status|\n\n.. image:: docs/source/_static/img/chirho_logo_wide.png\n :alt: ChiRho logo\n :align: center\n\n.. index-inclusion-marker\n\nCausal Reasoning with ChiRho\n============================\n\nChiRho is a causal extension to the Pyro probabilistic programming\nlanguage. It was built to bridge the gap between the capabilities of\nmodern probabilistic programming systems, such as Pyro, and the needs of\npolicymakers, scientists, and AI researchers, who often want to use\nmodels to answer their questions about cause-and-effect relationships.\nAs a non-exhaustive set of examples, ChiRho makes it easier to\nanswer the following kinds of causal questions that appear frequently in\npractice.\n\n- **Interventional**: *How many COVID-19 hospitalizations will occur if\n the USA imposes a national mask mandate?*\n\n- **Counterfactual**: *Given that 100,000 people were infected with\n COVID-19 in the past month, how many would have been infected if a\n mask mandate had been in place?*\n\n- **Explanation**: *Why were 100,000 people infected with COVID-19 in\n the past month?*\n\n- **Causal structure discovery**: *What individual attributes influence\n risk of COVID-19 hospitalization?*\n\nTo see how ChiRho supports causal reasoning, take a look at our `Tutorial <https://basisresearch.github.io/chirho/tutorial_i.html>`_.\n\nInstallation\n------------\n\n**Install using pip:**\n\n.. code:: sh\n\n pip install chirho\n\n**Install from source:**\n\n.. code:: sh\n\n git clone git@github.com:BasisResearch/chirho.git\n cd chirho\n git checkout master\n pip install .\n\n**Install with extra packages:**\n\nTo install the dependencies required to run the tutorials in\n``examples``/``tutorials`` directories, please use the following\ncommand:\n\n.. code:: sh\n\n pip install chirho[extras] \n\nMake sure that the models come from the same release version of the\n`ChiRho source\ncode <https://github.com/BasisResearch/chirho/releases>`__ as you\nhave installed.\n\nGetting Started\n---------------\n\nBelow is a simple example of how to use ChiRho to answer an\ninterventional question. For more in-depth examples, go to `Learn\nmore <#learn-more>`__.\n\n.. code:: python\n\n import torch\n import pyro\n import pyro.distributions as dist\n from chirho.interventional.handlers import do\n\n pyro.set_rng_seed(101)\n\n # Define a causal model with single confounder h\n def model():\n h = pyro.sample(\"h\", dist.Normal(0, 1))\n x = pyro.sample(\"x\", dist.Normal(h, 1))\n y = pyro.sample(\"y\", dist.Normal(x + h, 1))\n return y\n\n # Define a causal query (here intervening on x)\n def queried_model():\n return do(model, {\"x\": 1})\n\n # Generate 10,000 samples from the observational distribution P(y) ~ N(0, 2)\n obs_samples = pyro.infer.Predictive(model, num_samples=1000)()[\"y\"]\n\n # Generate 10,000 samples from the interventional distribution P(y | do(X=1)) ~ N(1, 1)\n int_samples = pyro.infer.Predictive(queried_model(), num_samples=1000)()[\"y\"]\n\nLearn more\n----------\n\nWe have written a number of tutorials and examples for ChiRho. We\nhave tried to choose simple examples that would be of interest to both\nthe causal inference and probabilistic programming communities: they\ncollectively span Pearl\u2019s causal hierarchy (Pearl 2009), and\nmost are broadly applicable, empirically validated, have an\nunconventional or limited identification result, and make use of modern\nprobabilistic machine learning tools, like neural networks or stochastic\nvariational inference.\n\nOur examples demonstrate how real-world causal assumptions can be expressed as probabilistic programs \nand real-world causal estimands can be expressed as program transformations.\nThese example illustrate how ChiRho is compatible with any inference method \nimplemented in Pyro, including the kinds of scalable gradient-based\napproximations that power much of the modern probabilistic machine learning landscape.\n\n- `Tutorial <https://basisresearch.github.io/chirho/tutorial_i.html>`_\n - Key observations inspiring ChiRho's design and outlines a causal Bayesian workflow for using ChiRho to answer causal questions\n- `Example: Backdoor Adjustment Criteria <https://basisresearch.github.io/chirho/backdoor.html>`_\n - Adjusting for observed confounders\n- `Example: Causal Effect Variational Autoencoder <https://basisresearch.github.io/chirho/cevae.html>`_\n - Causal inference with deep models and proxy variables\n- `Example: Mediation analysis and (in)direct effects <https://basisresearch.github.io/chirho/mediation.html>`_\n - Mediation analysis for path specific effects\n- `Example: Deep structural causal model counterfactuals <https://basisresearch.github.io/chirho/deepscm.html>`_\n - Counterfactuals with normalizing flows\n- `Example: Structured Latent Confounders <https://basisresearch.github.io/chirho/slc.html>`_\n - Causal effect estimation when latent confounders are shared across groups\n- `Example: Synthetic difference-in-differences <https://basisresearch.github.io/chirho/sdid.html>`_\n - Counterfactual estimation from longitudinal data\n- `Example: Robust estimation with the DR learner <https://basisresearch.github.io/chirho/dr_learner.html>`_\n - Heterogeneous causal effect estimation with a misspecified model\n- `Example: Estimating the effects of drugs on gene expression <https://basisresearch.github.io/chirho/sciplex.html>`_\n - Causal inference with single-cell RNA-seq data\n- `Example: Causal reasoning in dynamical systems <https://basisresearch.github.io/chirho/dynamical_intro.html>`_\n - Causal inference with continuous-time dynamical systems\n- `Design notes <https://basisresearch.github.io/chirho/design_notes>`_\n - Technical implementation details of ChiRho using effect handlers\n\n*Note*: These tutorials and examples assume some familiarity with Pyro and\nprobabilistic programming. For introductory Pyro tutorials, please see\n`Additional background reading\nmaterial <#additional-background-reading-material>`__ below.\n\nDocumentation\n-------------\n- `Counterfactual <https://basisresearch.github.io/chirho/counterfactual.html>`_\n - Effect handlers for counterfactual world splitting\n- `Interventional <https://basisresearch.github.io/chirho/interventional.html>`_\n - Effect handlers for performing interventions\n- `Observational <https://basisresearch.github.io/chirho/observational.html>`_\n - Effect handler utilities for computing probabilistic quantities for \n partially deterministic models which is useful for counterfactual reasoning\n- `Indexed <https://basisresearch.github.io/chirho/indexed.html>`_\n - Effect handler utilities for named indices in ChiRho which is useful for manipluating\n and tracking counterfactual worlds\n- `Dynamical <https://basisresearch.github.io/chirho/dynamical.html>`_\n - Operations and effect handlers for counterfactual reasoning in dynamical systems\n \nCaveats\n-------\nChiRho does not answer causal questions by magic. In fact, there is\nno escaping the fact that\n\n *behind any causal conclusion there must lie some causal assumption,*\n\na phrase made famous by Judea Pearl (Pearl 2009). Instead,\nChiRho provides a substrate for writing causal assumptions as\nprobabilistic programs, and for writing causal questions in terms of\nprogram transformations.\n\nAdditional background reading material\n--------------------------------------\n\n- Causal Probabilistic Programming Without Tears\n https://drive.google.com/file/d/1Uzjg-vX77BdSnAcfpUcb-aIXxhnAPI24/view?usp=sharing\n- Introduction to Pyro:\u00a0\\ http://pyro.ai/examples/intro_long.html\n- Tensor shapes in Pyro:\u00a0\\ http://pyro.ai/examples/tensor_shapes.html\n- A guide to programming with effect handlers in\n Pyro\u00a0\\ http://pyro.ai/examples/effect_handlers.html\n- Minipyro:\u00a0\\ http://pyro.ai/examples/minipyro.html\n- Reparameterization of Pyro\n programs:\u00a0\\ https://docs.pyro.ai/en/stable/infer.reparam.html\n- Optional: getting started with\n NumPyro\u00a0\\ https://num.pyro.ai/en/stable/getting_started.html\n\n\nReferences\n----------\nPearl, Judea. *Causality: Models, Reasoning and Inference*. 2nd ed. USA: Cambridge University Press, 2009.\n\n\n.. |Build Status| image:: https://github.com/BasisResearch/chirho/actions/workflows/test.yml/badge.svg\n :target: https://github.com/BasisResearch/chirho/actions/workflows/test.yml\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Causal reasoning",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://www.basis.ai/",
"Source": "https://github.com/BasisResearch/chirho"
},
"split_keywords": [
"machine",
"learning",
"statistics",
"probabilistic",
"programming",
"bayesian",
"modeling",
"pytorch"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9f794e01b94559737fa6d79e7e41015a930eedd39ff83b649af98c5f745052e8",
"md5": "4e6b0309e533b005325552e780112dcb",
"sha256": "55c1f826d6af17af093b52bb7734c624dbc27c7d952b4d8b5acd8e05a0c99ae4"
},
"downloads": -1,
"filename": "chirho-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4e6b0309e533b005325552e780112dcb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 53058,
"upload_time": "2023-12-11T12:12:18",
"upload_time_iso_8601": "2023-12-11T12:12:18.791467Z",
"url": "https://files.pythonhosted.org/packages/9f/79/4e01b94559737fa6d79e7e41015a930eedd39ff83b649af98c5f745052e8/chirho-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f5a12b8e0410f9e7174b9abc3edda057a1a62665795be6425bb6391b94b9b3d8",
"md5": "2c18217edc816d73d82781e1fbeca2f8",
"sha256": "bf3a60efcf0882e9044c818a21173a70a8de441cf99dadddd8e611c487337dbe"
},
"downloads": -1,
"filename": "chirho-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "2c18217edc816d73d82781e1fbeca2f8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 44157,
"upload_time": "2023-12-11T12:12:20",
"upload_time_iso_8601": "2023-12-11T12:12:20.698618Z",
"url": "https://files.pythonhosted.org/packages/f5/a1/2b8e0410f9e7174b9abc3edda057a1a62665795be6425bb6391b94b9b3d8/chirho-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-11 12:12:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BasisResearch",
"github_project": "chirho",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "chirho"
}
JSON
