Updated Inference and Weight learning documentaton

- Adds further details
- Fixes some typos
- Fixes some bibliography references

Author: anskarl

.DS_Store

@@ -6,6 +6,8 @@ syntax: glob
 *.bak
 #*.off
 *.old
+.DS_Store
+
 
 # eclipse conf file
 .settings

.gitignore

@@ -1,3 +1,20 @@
+<pre>
+    o                        o     o   o         o
+    |             o          |     |\ /|         | /
+    |    o-o o--o    o-o  oo |     | O |  oo o-o OO   o-o o   o
+    |    | | |  | | |    | | |     |   | | | |   | \  | |  \ /
+    O---oo-o o--O |  o-o o-o-o     o   o o-o-o   o  o o-o   o
+                |
+             o--o
+    o--o              o               o--o       o    o
+    |   |             |               |    o     |    |
+    O-Oo   oo o-o   o-O o-o o-O-o     O-o    o-o |  o-O o-o
+    |  \  | | |  | |  | | | | | |     |    | |-' | |  |  \
+    o   o o-o-o  o  o-o o-o o o o     o    | o-o o  o-o o-o
+
+    Logical Markov Random Fields.
+</pre>
+
 # LoMRF: Logical Markov Random Fields
 
 LoMRF is an open-source implementation of [Markov Logic Networks](https://en.wikipedia.org/wiki/Markov_logic_network) (MLNs) written in [Scala programming language](http://scala-lang.org).

README.md

@@ -1,4 +1,6 @@
-# Inference 
+# Inference
+
+In brief, inference in Markov Logic Networks (MLNs), is the process of estimating the marginal probability or the most probable truth state of the groundings of some query atoms, given a MLN theory (i.e., a collection of weighted formulas) and a collection of imput ground evidence atoms (i.e., input ground predicates with known truth state).
 
 ## Types of inference in LoMRF
 
@@ -18,8 +20,7 @@ In order to perform inference, we have to define the following:
 
 ### Inference using the `lomrf` commmand-line tool
 
-To demonstrate the usage of LoMRF from commmand-line interface, assume that we have one knowledge base
-file, named as `theoy.mln`, and one evidence file, named as `evidence.db`.  
+To demonstrate the usage of LoMRF from commmand-line interface, assume that we have one knowledge base file, named as `theoy.mln`, and one evidence file, named as `evidence.db`.
 
 In our example knowledge-base we have the following predicates:
 
@@ -73,6 +74,12 @@ lomrf -infer map -i theory.mln -e evidence.db -r map-out.result -q Query_A/2,Que
 The results from MAP inference are stored in the `map-out.result` (see paramter `-r`)
 
 
+## Probabilistic Inference Examples
+
+See Sections [Probabilistic Inference Examples](2_1_inference_examples.md) and [Temporal Probabilistic Inference Examples](2_2_temporal_inference_examples.md). Sources from the examples are located in the LoMRF-data project (follow the instructions in [Download Example Data](6_2_download_example_data.md)).
+
+
+
 ## Command-line Interface Options ##
 
 By executing the ```lomrf -h``` (or ```lomrf --help```) command from the command-line interface, we take a print of multiple parameters. Below we explain all LoMRF inference command-line interface parameters:
@@ -219,26 +226,13 @@ literal become unit clauses with positive literal and inverted sign in their cor
 * `-dynamic, --dynamic-implementations <string>` **[Optional]** Comma separated paths to search recursively for dynamic
 predicates/functions implementations (*.class and *.jar files).
 
-## Examples
-
-See Sections [Probabilistic Inference Examples](2_1_inference_examples.md) and [Temporal Probabilistic Inference Examples](2_2_temporal_inference_examples.md).
-Sources from the examples are located in the LoMRF-data project (follow the instructions in
-[Download Example Data](6_2_download_example_data.md)).
-
 
 ## References
 
-Bart Selman, Henry Kautz, and Bram Cohen. (1993) Local Search Strategies for Satisfiability Testing.  Final version appears
-in Cliques, Coloring, and Satisfiability: Second DIMACS Implementation Challenge. In David S. Johnson and Michael A. Trick, (Ed.),
-DIMACS Series in Discrete Mathematics and Theoretical Computer Science, vol. 26, AMS. ([link](http://www.cs.cornell.edu/selman/papers/pdf/dimacs.pdf))
+* Bart Selman, Henry Kautz, and Bram Cohen. (1993) Local Search Strategies for Satisfiability Testing.  Final version appears in Cliques, Coloring, and Satisfiability: Second DIMACS Implementation Challenge. In David S. Johnson and Michael A. Trick, (Ed.), DIMACS Series in Discrete Mathematics and Theoretical Computer Science, vol. 26, AMS. ([link](http://www.cs.cornell.edu/selman/papers/pdf/dimacs.pdf))
 
-Henry Kautz, Bart Selman and Yueyen Jiang. (1996) A General Stochastic Approach to Solving Problems with Hard and Soft Constraints.
-In Gu, D., Du, J. and Pardalos, P. (Eds.), The Satisfiability Problem: Theory and Applications, Vol. 35 of DIMACS Series in
-Discrete Mathematics and Theoretical Computer Science, pp. 573–586. AMS. ([link](https://cs.rochester.edu/u/kautz/papers/maxsatDIMACSfinal.ps))
+* Henry Kautz, Bart Selman and Yueyen Jiang. (1996) A General Stochastic Approach to Solving Problems with Hard and Soft Constraints. In Gu, D., Du, J. and Pardalos, P. (Eds.), The Satisfiability Problem: Theory and Applications, Vol. 35 of DIMACS Series in Discrete Mathematics and Theoretical Computer Science, pp. 573–586. AMS. ([link](https://cs.rochester.edu/u/kautz/papers/maxsatDIMACSfinal.ps))
 
-Tuyen N. Huynh and Raymond J. Mooney. (2011). Max-Margin Weight Learning for Markov Logic Networks. In Proceedings of the
-European Conference on Machine Learning and Principles and Practice of Knowledge Discovery in Databases (ECML-PKDD 2011),
-Vol. 2, pp. 81-96. ([link](http://www.ai.sri.com/~huynh/papers/huynh_mooney_ecmlpkdd09.pdf))
+* Tuyen N. Huynh and Raymond J. Mooney. (2009). Max-Margin Weight Learning for Markov Logic Networks. In Proceedings of the European Conference on Machine Learning and Principles and Practice of Knowledge Discovery in Databases (ECML PKDD-09). ([link](http://www.ai.sri.com/~huynh/papers/huynh_mooney_ecmlpkdd09.pdf))
 
-Poon, Hoifung and Domingos, Pedro (2006). Sound and Efficient Inference with Probabilistic and Deterministic Dependencies.
-In Proceedings of the 21th National Conference on Artificial Intelligence (pp. 458-463), 2006. Boston, MA: AAAI Press. ([link](http://homes.cs.washington.edu/~pedrod/papers/aaai06a.pdf))
+* Poon, Hoifung and Domingos, Pedro (2006). Sound and Efficient Inference with Probabilistic and Deterministic Dependencies. In Proceedings of the 21th National Conference on Artificial Intelligence (pp. 458-463), 2006. Boston, MA: AAAI Press. ([link](http://homes.cs.washington.edu/~pedrod/papers/aaai06a.pdf))

doc/2_inference.md

@@ -1,6 +1,6 @@
 # Weight Learning Examples
 
-Below we provide some example MLNs, in order to demonstrate the LoMRF weight learning command-line tool:
+Below we provide simple example models, in order to demonstrate weight learning in LoMRF.
 
 ## Social Network Analysis
 
@@ -10,7 +10,10 @@ We would like to model a simple social network of friends, smoking, and cancer.
 
 *Predicate schema:*
 ```lang-none
+// Input predicates:
 Friends(person, person)
+
+// Query/non-evidence predicates:
 Smokes(person)
 Cancer(person)
 ```
@@ -22,15 +25,18 @@ Cancer(person)
 Smokes(x) => Cancer(x)
 
 // People having friends who smoke, also smoke and those having friends
-// who don't smoke, don't smoke.
+// who don't smoke, they don't smoke.
 Friends(x, y) => (Smokes(x) <=> Smokes(y))
 ```
 
-Of course, this does not hold for all smokers, so in Markov logic we can just tack a weight
-on to the rule, or, as we do here, learn a weight from training data.
+Since this cannot not hold for all smokers with absolute certainty, in Markov Logic we can associate a weight value to each logical formula, or use weight learning in order to estimate the weights from training data.
+
+Please note, that both example formulas are not hard-constrained (i.e., ending with a full-stop character). On the other hand, although they are both soft-constrained, they are not (yet) associated with a weight value. The lack of weight value, indicates that the weight needs to be estimated by the weight learning algorithm.
 
 ### Training data (smoking-train.db)
 
+In the following training data we are giving example relations between friends, e.g., the fact that the persons `Anna` and `Bob` are friends (using the true ground fact `Friends(Anna, Bob)`). Furthermore, we are stating the fact who is a smoker, e.g., `Anna` is a smoker, therefore we are givind the true ground fact `Smokes(Anna)`. Similarly, we are stating which persons have been diagnosed with cancer, e.g., `Canser(Anna)`. Please note that, due to Closed-world assumption we do not nessesary need to give which possible is false, e.g., the fact that `Bob` is not a smoker (i.e., `!Smokes(Bob)`). Below we are giving the full example of our training data: 
+
 ```lang-none
 Friends(Anna, Bob)
 Friends(Bob, Anna)
@@ -60,16 +66,21 @@ Cancer(Edward)
 
 ***Weight learning execution***
 
+In order to perform weight learning for this example we are giving the following:
+
 ```lang-none
 lomrf-wlearn -i smoking.mln -o smoking-learned.mln -t smoking-train.db -ne Smokes/1,Cancer/1
 ```
+Where the parameter '-i smoking.mln' is the input MLN theory, '-o smoking-learned.mln' is the resulting output theory with the estimated weights, '-t smoking-train.db' is the training data and the parameer '-ne Smokes/1,Cancer/1' specifies which predicates are the non-evidence predicates. After the execution of this example, the resulting file smoking-learned.mln is an MLN knowledge base with the learned weights. Using this file along with the test data, we can compute the truth value of each person smoking and getting cancer.
+
+## Car traffic modelling
 
-This produces the file smoking-learned.mln with the learned weights. Using this along with the test data, we can compute the truth value of each person smoking and getting cancer.
+In the following example we are going to demonstrate weight learning using a naive implementation of [Hidden Markov Model](https://en.wikipedia.org/wiki/Hidden_Markov_model) for modelling car traffic (see [original example](http://alchemy.cs.washington.edu/tutorial/7Hidden_Markov_Models.html)).
+We assume that each day a car may take one of the following actions (1) stopped, (2) driving, (3) or slowing down. Furthermore, we assume that these actions are dependent by the state of the stoplight in front of it, which can be either red, green or yellow.
 
-## Hidden Markov Models
+In a Markov process we need to model `states` and `observations` at certain points in `time`. Using first-order logic representation we can model a `state` and `observation` using predicates. On the other hand, time, car actions and traffic light observations are represented as variables in each one of these predicates.
 
-Suppose, on a given day, we observe a car taking three actions: it is either stopped, driving, or slowing. We assume this is only dependent on the state of the stoplight in front of it: red, green or yellow. In a Markov process we need to model
-`states` and `observations` at certain points in `time`. In LoMRF, we model a `state` and `observation` with a first-order predicate and `time` is a variable in each of these predicates.
+Please find below the example knowledge base and training data:
 
 ### Knowledge base (traffic.mln)
 
@@ -168,4 +179,4 @@ State(Drive, 10)
 lomrf-wlearn -i traffic.mln -o traffic-learned.mln -t traffic-train.db -ne State/2
 ```
 
-This produces the file traffic-learned.mln with the learned weights. Using this along with the test data, we can compute the truth value of each state.
+This produces the file traffic-learned.mln with the learned weights. Using the resulting trained MLN model along with the test data, we can compute the truth value of each state.

doc/3_1_weight_learning_examples.md

@@ -4,10 +4,7 @@ Below we provide examples that demonstrate LoMRF weight learning capabilities in
 
 ## Activity Recognition
 
-In this example we demonstrate how to perform weight learning for activity recognition, using a small fragment of the first
-set of the [CAVIAR dataset](http://homepages.inf.ed.ac.uk/rbf/CAVIARDATA1/). We use the same Probabilistic Event Calculus
-formalism as presented in the [Quick Start](0_quick_start.md) section and the same knowledge base as the one defined in
-the [Temporal Inference Examples](2_2_temporal_inference_examples.md).
+In this example we demonstrate how to perform weight learning for activity recognition, using a small fragment of the first set of the [CAVIAR dataset](http://homepages.inf.ed.ac.uk/rbf/CAVIARDATA1/). We use the same Probabilistic Event Calculus formalism as presented in the [Quick Start](0_quick_start.md) section and the same knowledge base as the one defined in the [Temporal Inference Examples](2_2_temporal_inference_examples.md).
 
 ###Training data
 
@@ -66,19 +63,25 @@ Happens(Active_ID1, 170)
 
 The files of this example are the following:
   * Knowledge base files:
-    * Main MLN file in CNF: [theory_cnf.mln](/Examples/Weight_Learning/Activity_Recognition/theory.mln)
-    * Definitions of moving activity: [definitions/moving.mln](/Examples/Weight_Learning/Activity_Recognition/definitions/moving.mln)
-    * Definitions of meeting activity: [definitions/meeting.mln](/Examples/Weight_Learning/Activity_Recognition/definitions/meeting.mln)
-  * Training file for batch learning: [training.db](/Examples/Weight_Learning/Activity_Recognition/training/batch/training.db)
-  * Training files for online learning: [micro-batches](/Examples/Weight_Learning/Activity_Recognition/training/online/)
+    * Main MLN file in CNF: [theory_cnf.mln](../Data/Examples/Weight_Learning/Activity_Recognition/theory.mln)
+    * Definitions of moving activity: [definitions/moving.mln](../Data/Examples/Weight_Learning/Activity_Recognition/definitions/moving.mln)
+    * Definitions of meeting activity: [definitions/meeting.mln](../Data/Examples/Weight_Learning/Activity_Recognition/definitions/meeting.mln)
+  * Training file for batch learning: [training.db](../Data/Examples/Weight_Learning/Activity_Recognition/training/batch/training.db)
+  * Training files for online learning: [micro-batches](../Data/Examples/Weight_Learning/Activity_Recognition/training/online/)
+
 
 Parameters:
- * Non-evidence predicates: `HoldsAt/2`
+ * Non-evidence predicates: `-ne HoldsAt/2`
+ * Input MLN theory: `-i theory_cnf.mln`
+ * Input training data: `-t training.db`
+ * Resulting output MLN theory: `-o learned.mln`
+ * Enable loss augmented inference (also known as seperation oracle) using the Hamming loss function by adding to the objective function during inference additional loss terms: `-lossAugmented`
+ * Specify the learning alogirhtm, i.e., Max-Margin (default), Adagrad or CDA: `-alg`
 
 ***Max-Margin Learning***
 
 ```lang-none
-lomrf-wlearn -i theory_cnf.mln -t training.db -o learned.mln -ne HoldsAt/2 -lossAugmented
+lomrf-wlearn -alg MAX_MARGIN -i theory_cnf.mln -t training.db -o learned.mln -ne HoldsAt/2 -lossAugmented
 ```
 ***Online Learning using AdaGrad or CDA***