Add documentation and test for it

gtsam/discrete/DiscreteConditional.h

@@ -58,24 +58,28 @@ public:
   DiscreteConditional(const Signature& signature);
 
   /**
-  * Construct from key, parents, and a Table specifying the CPT.
+   * Construct from key, parents, and a Signature::Table specifying the
-  *
+   * conditional probability table (CPT) in 00 01 10 11 order. For
-  * The first string is parsed to add a key and parents.
+   * three-valued, it would be 00 01 02 10 11 12 20 21 22, etc....
-  * 
+   *
-  * Example: DiscreteConditional P(D, {B,E}, table);
+   * The first string is parsed to add a key and parents.
-  */
+   *
+   * Example: DiscreteConditional P(D, {B,E}, table);
+   */
   DiscreteConditional(const DiscreteKey& key, const DiscreteKeys& parents,
                       const Signature::Table& table)
       : DiscreteConditional(Signature(key, parents, table)) {}
 
   /**
-  * Construct from key, parents, and a string specifying the CPT.
+   * Construct from key, parents, and a string specifying the conditional
-  *
+   * probability table (CPT) in 00 01 10 11 order. For three-valued, it would
-  * The first string is parsed to add a key and parents. The second string
+   * be 00 01 02 10 11 12 20 21 22, etc....
-  * parses into a table.
+   *
-  * 
+   * The first string is parsed to add a key and parents. The second string
-  * Example: DiscreteConditional P(D, {B,E}, "9/1 2/8 3/7 1/9");
+   * parses into a table.
-  */
+   *
+   * Example: DiscreteConditional P(D, {B,E}, "9/1 2/8 3/7 1/9");
+   */
   DiscreteConditional(const DiscreteKey& key, const DiscreteKeys& parents,
                       const std::string& spec)
       : DiscreteConditional(Signature(key, parents, spec)) {}

gtsam/discrete/Signature.h

@@ -30,7 +30,7 @@ namespace gtsam {
    * The format is (Key % string) for nodes with no parents,
    * and (Key | Key, Key = string) for nodes with parents.
    *
-   * The string specifies a conditional probability spec in the 00 01 10 11 order.
+   * The string specifies a conditional probability table in 00 01 10 11 order.
    * For three-valued, it would be 00 01 02 10 11 12 20 21 22, etc...
    *
    * For example, given the following keys
@@ -73,22 +73,29 @@ namespace gtsam {
 
   public:
    /**
-    * Construct from key, parents, and a Table specifying the CPT.
+    * Construct from key, parents, and a Signature::Table specifying the
+    * conditional probability table (CPT) in 00 01 10 11 order. For
+    * three-valued, it would be 00 01 02 10 11 12 20 21 22, etc....
     *
     * The first string is parsed to add a key and parents.
-    * 
+    *
-    * Example: Signature sig(D, {B,E}, table);
+    * Example:
+    *   Signature::Table table{{0.9, 0.1}, {0.2, 0.8}, {0.3, 0.7}, {0.1, 0.9}};
+    *   Signature sig(D, {E, B}, table);
     */
    Signature(const DiscreteKey& key, const DiscreteKeys& parents,
              const Table& table);
 
    /**
-    * Construct from key, parents, and a string specifying the CPT.
+    * Construct from key, parents, and a string specifying the conditional
+    * probability table (CPT) in 00 01 10 11 order. For three-valued, it would
+    * be 00 01 02 10 11 12 20 21 22, etc....
     *
     * The first string is parsed to add a key and parents. The second string
     * parses into a table.
-    * 
+    *
-    * Example: Signature sig(D, {B,E}, "9/1 2/8 3/7 1/9");
+    * Example (same CPT as above):
+    *   Signature sig(D, {B,E}, "9/1 2/8 3/7 1/9");
     */
    Signature(const DiscreteKey& key, const DiscreteKeys& parents,
              const std::string& spec);

gtsam/discrete/tests/testSignature.cpp

@@ -92,7 +92,6 @@ TEST(testSignature, all_examples) {
   Signature b(B, {S}, "70/30  40/60");
   Signature e(E, {T, L}, "F F F 1");
   Signature x(X, {E}, "95/5 2/98");
-  Signature d(D, {E, B}, "9/1 2/8 3/7 1/9");
 }
 
 // Make sure we can create all signatures for Asia network with operator magic.
@@ -105,7 +104,17 @@ TEST(testSignature, all_examples_magic) {
   Signature b(B | S = "70/30  40/60");
   Signature e((E | T, L) = "F F F 1");
   Signature x(X | E = "95/5 2/98");
-  Signature d((D | E, B) = "9/1 2/8 3/7 1/9");
+}
+
+// Check example from docs.
+TEST(testSignature, doxygen_example) {
+  Signature::Table table{{0.9, 0.1}, {0.2, 0.8}, {0.3, 0.7}, {0.1, 0.9}};
+  Signature d1(D, {E, B}, table);
+  Signature d2((D | E, B) = "9/1 2/8 3/7 1/9");
+  Signature d3(D, {E, B}, "9/1 2/8 3/7 1/9");
+  EXPECT(*(d1.table()) == table);
+  EXPECT(*(d2.table()) == table);
+  EXPECT(*(d3.table()) == table);
 }
 
 /* ************************************************************************* */