pycid 0.2.6

Causal Influence Diagram library

PyCID: Causal Influence Diagrams library

This package implements causal influence diagrams and methods to analyze them, and is part of the Causal Incentives project.

Building on pgmpy, pycid provides methods for defining CIDs and MACIDs, computing optimal policies and Nash equilibria, studying the effects of interventions, and checking graphical criteria for various types of incentives.

Install

Create and activate a python virtual environment or a conda environment. Then install using:

python3 -m pip install pycid

PyCID requires python version 3.7 or greater.

Basic usage

# Import
import pycid

# Specify the nodes and edges of a simple CID
cid = pycid.CID([
    ('S', 'D'),   # add nodes S and D, and a link S -> D
    ('S', 'U'),   # add node U, and a link S -> U
    ('D', 'U'),   # add a link D -> U
    ],
    decisions=['D'],   # D is a decision node
    utilities=['U'])   # U is a utility node

# specify the causal relationships
cid.add_cpds(
    pycid.UniformRandomCPD('S', [-1, 1]),     # S is -1 or 1 with equal probability
    pycid.DecisionDomain('D', [-1, 1]),       # the permitted choices for D are -1 and 1
    pycid.FunctionCPD('U', lambda s, d: s*d)  # U is the product of S and D (arguments lowercase the variable names)
)

# Draw the result
cid.draw()

The notebooks provide many more examples, including a CID Basics Tutorial, a MACID Basics Tutorial, and a CID Incentives Tutorial.

To quickly get started using colab, make a copy of this notebook.

Code overview

The code is structured into the following folders:

• pycid/core contains methods and classes for specifying CBN, CID and MACID models, for finding and characterising types of paths in these models' graphs, and for computing optimal policies and Nash equilibria.
• pycid/analyze has methods for analyzing different types of effects and interventions as well as incentives in single-decision CIDs and reasoning patterns in MACIDs.
• pycid/random has methods for generating random CIDs.
• pycid/examples has a range of pre-specified CBNs, CIDs and MACIDs.
• notebooks has iPython notebooks illustrating the use of key methods.
• tests has unit tests for all public methods.

Contributing

The project is developed at https://github.com/causalincentives/pycid.

Install

First create and activate a python virtual environment or a conda environment.

git clone https://github.com/causalincentives/pycid  # download the code
cd pycid
python3 -m pip install --editable .[test]
python3 -m pytest   # check that everything works

Making Commits

Fast checks are set up as git pre-commit hooks. To enable them, run:

pip3 install pre-commit
pre-commit install

They will run on every commit or can be run manually with pre-commit run.

Before committing to the master branch, please ensure that:

• The script tests/check-code.sh completes without error (you can add it as a pre-commit hook)
• Any new requirements are added to setup.cfg.
• Your functions have docstrings and types, and a unit test verifying that they work
• For notebooks, you have done "restart kernel and run all cells" before saving and committing
• Any documentation (such as this file) is up-to-date