Package: pycid
PyCID: Causal Influence Diagrams libraryThis package implements causal influence diagrams and methods to analyze them, and is part of theCausal Incentivesproject.Building onpgmpyandNetworkX, pycid provides methods for
defining CBNs, CIDs and MACIDs,
computing optimal policies in CIDs, pure and mixed Nash equilibria in multi-agent CIDs,
studying the effects of interventions, and
checking graphical criteria for various types of incentives.NewsVersion 0.8 breaks backwards compatibility by removing the get_all_pure_ne, get_all_pure_ne_in_sg, and get_all_pure_spe class methods from the MACID class. This is because pure variants of NE and SPE can now be found by simply selecting the "enumpure" solver as an argument in the new get_ne, get_ne_in_sg, and get_spe MACID class methods.Version 0.7breaks backwards compatibilityby requiring CPD arguments to match the case of the parent nodes.
To update your code to the latest version, simply change the case of the arguments, as illustratedhere.
Alternatively, stick to version 0.2.8.InstallCreate and activate
apython virtual environmentor
aconda environment.
Then install using:python3-mpipinstallpycidPyCID requires python version 3.8 or greater.Basic usage# Importimportpycid# Specify the nodes and edges of a simple CIDcid=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 nodeutilities=['U'])# U is a utility node# specify the causal relationships with CPDs using keyword argumentscid.add_cpds(S=pycid.discrete_uniform([-1,1]),# S is -1 or 1 with equal probabilityD=[-1,1],# the permitted action choices for D are -1 and 1U=lambdaS,D:S*D)# U is the product of S and D (argument names match parent names)# Draw the resultcid.draw()Thenotebooksprovide many more examples, including:CBN Tutorialshows how to specify the structure and (causal) relationships between nodes, and ask simple queries.CID tutorialadds special decision and utility nodes for one agent, and how to compute optimal policies.MACID tutorialcovers methods for handling multiple agents, including finding subgames and Nash equilibria.Incentive Analysis tutorialillustrates various methods for analyzing the incentives of agents.The above notebooks links all open in Colab, and can be run
directly in the browser with no further setup or installation required.Code overviewThe code is structured into the following folders:pycid/corecontains 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/analyzehas methods for analyzing different types of effects and interventions
as well as incentives in single-decision CIDs and reasoning patterns in MACIDs.pycid/randomhas methods for generating random CIDs.pycid/exampleshas a range of pre-specified CBNs, CIDs and MACIDs.notebookshas iPython notebooks illustrating the use of key methods.testshas unit tests for all public methods.ContributingThe project is developed athttps://github.com/causalincentives/pycid.InstallFirst create and activate
apython virtual environmentor
aconda environment.gitclonehttps://github.com/causalincentives/pycid# download the codecdpycid
python3-mpipinstall--editable.[test]python3-mpytest# check that everything worksMaking CommitsFast checks are set up as git pre-commit hooks.
To enable them, run:pip3installpre-commit
pre-commitinstallThey will run on every commit or can be run manually withpre-commit run.Before committing to the master branch, please ensure that:The scripttests/check-code.shcompletes without error (you can add it as a pre-commit hook)Any new requirements are added tosetup.cfg.Your functions have docstrings and types, and a unit test verifying that they workFor notebooks, you have done "restart kernel and run all cells" before saving and committingAny documentation (such as this file) is up-to-dateCitingPlease use the following BibTeX entry for citingPyCIDin your research:@InProceedings{ james_fox-proc-scipy-2021,
  author    = { {J}ames {F}ox and {T}om {E}veritt and {R}yan {C}arey and {E}ric {L}anglois and {A}lessandro {A}bate and {M}ichael {W}ooldridge },
  title     = { {P}y{C}{I}{D}: {A} {P}ython {L}ibrary for {C}ausal {I}nfluence {D}iagrams },
  booktitle = { {P}roceedings of the 20th {P}ython in {S}cience {C}onference },
  pages     = { 43 - 51 },
  year      = { 2021 },
  editor    = { {M}eghann {A}garwal and {C}hris {C}alloway and {D}illon {N}iederhut and {D}avid {S}hupe },
  doi       = {10.25080/majora-1b6fd038-008}
}