Merge branch 'add_readme'

3 files changed, 131 insertions, 0 deletions

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.
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