From c3f5f71c4cd3eef45ac430e64b80085a1205a624 Mon Sep 17 00:00:00 2001 From: Cathy Yeh Date: Sat, 3 Feb 2018 19:50:34 -0800 Subject: readme --- README.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) diff --git a/README.md b/README.md index 4aecf55..8892e2b 100644 --- a/README.md +++ b/README.md @@ -1 +1,86 @@ # beliefs + +A library for performing inference with Bayesian Networks for a +special use case, derived +from [pgmpy](https://github.com/pgmpy/pgmpy). + + +## Motivation + +**Exact inference** + +This library provides the ability to perform exact inference in a +computationally tractable* way for a specific but useful case: Bayesian +Networks with +* polytree structure +* consisting of Bernoulli random variables whose relationship to their + parents in the probabilistic graphical model are described by AND or + OR logic + +Non-deterministic conditional probability distributions for +multinomial, discrete random variables are also supported, although +the algorithm is specifically optimized for the case of Bernoulli AND +and Bernoulli OR variables. + +*See the "Many parents model" in + the + [jupyter notebook](https://render.githubusercontent.com/view/ipynb?commit=73aa4a35d08f1c16569bc78d176710381b9e9605&enc_url=68747470733a2f2f7261772e67697468756275736572636f6e74656e742e636f6d2f64726976657267726f75702f62656c696566732f373361613461333564303866316331363536396263373864313736373130333831623965393630352f6578616d706c65732f636f6d706172655f70676d70795f62656c6965665f70726f7061676174696f6e2e6970796e623f746f6b656e3d4158386c536f5a35622d2d7848394a736a58727a65345a7846587531333150426b733561646f4f567741253344253344&nwo=drivergroup%2Fbeliefs&path=examples%2Fcompare_pgmpy_belief_propagation.ipynb&repository_id=110306600&repository_type=Repository#IV.-Many-parents-model) under + the examples/ directory for an example of a case in which + inference becomes computationally intractable with pgmpy but can + be handled by beliefs optimized algorithm. + +## Additional features + +* In addition to being able to perform inference based on direct + observation of a variable in the PGM, beliefs also provides the + ability to specify virtual evidence, i.e. evidence that modifies the + belief, or marginal probability, of a variable by affecting its + likelihood based on observations of variables not in the PGM, while + not pinning the variable into a definite (observed) state. +* The ability to catch conflicting evidence errors during inference, + which manifest as numpy NaNs in pgmpy's inference results. +* Utility for gathering the direct observations that influenced the + beliefs of variables that were inferred to be in a definite state. + + +## Getting started + +### Installation + +Using conda: +``` +conda install -c driver beliefs +``` + +### Example + +Perform inference on a Bayesian Network: +```python +from beliefs.inference.belief_propagation import BeliefPropagation +from beliefs.models.belief_update_node_model import ( + BeliefUpdateNodeModel, + BernoulliOrNode +) + +# directed edges for a polytree Bayes Net +edges = [('u', 'x'), ('v', 'x'), ('x', 'y'), ('x', 'z') + +# initialize model w/ edges, default to OR CPD for all variables +model = BeliefUpdateNodeModel.init_from_edges(edges, BernoulliOrNode) + +# initialize inference +infer = BeliefPropagation(model) + +# perform inference, with 'x' is observed to be True. +result = infer.query(evidence={'x': np.array([0, 1])}) +``` + +## Tests + +From the project root directory: +``` +pytest tests -vv +``` + +## License +This project is licensed under the terms of the MIT license. -- cgit v1.2.3 From 87b9ee369fcf74fcf0ee72e7f9ce87c50ffdabe5 Mon Sep 17 00:00:00 2001 From: Cathy Yeh Date: Tue, 6 Feb 2018 10:07:44 -0800 Subject: include pgmpy MIT license in discrete_factor.py, base_models.py --- beliefs/factors/discrete_factor.py | 23 +++++++++++++++++++++++ beliefs/models/base_models.py | 23 +++++++++++++++++++++++ 2 files changed, 46 insertions(+) diff --git a/beliefs/factors/discrete_factor.py b/beliefs/factors/discrete_factor.py index 708f00c..f72e835 100644 --- a/beliefs/factors/discrete_factor.py +++ b/beliefs/factors/discrete_factor.py @@ -1,3 +1,26 @@ +""" +The MIT License (MIT) + +Copyright (c) 2013-2017 pgmpy + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software is furnished to do so, +subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS +FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR +COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER +IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +""" + import copy import numpy as np diff --git a/beliefs/models/base_models.py b/beliefs/models/base_models.py index 71af0cb..e868278 100644 --- a/beliefs/models/base_models.py +++ b/beliefs/models/base_models.py @@ -1,3 +1,26 @@ +""" +The MIT License (MIT) + +Copyright (c) 2013-2017 pgmpy + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software is furnished to do so, +subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS +FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR +COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER +IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +""" + import networkx as nx from beliefs.utils.math_helper import is_kronecker_delta -- cgit v1.2.3