more docs and example

Author: felixleopoldo

VERSION

@@ -1 +1 @@
-2.11.6
+2.12.0

docs/source/index.rst

@@ -96,6 +96,7 @@ generated datasets, the workflow also includes a number of standard datasets and
 
 .. rubric:: News
 
+* 2024-12-26: Benchpress 2.12.0. This version introduces the :ref:`pyagrum` module, providing access to the `pyAgrum <https://agrum.gitlab.io/>`_ library's structure learning capabilities for discrete valued Bayesian networks. 
 * 2024-12-16: Benchpress 2.11.0. This version introduces the :ref:`bips_tpc` module, based on the temporal PC (`tPC <https://github.com/bips-hb/tpc>`_) and the `micd <https://github.com/bips-hb/micd>`_ package. It enables causal discovery through the PC algorithm allowing for :ref:`edge_constraints`, mixed data, and missing data handling. Thanks `Leibniz-Institut für Präventionsforschung und Epidemiologie – (BIPS GmbH)  <https://github.com/bips-hb>`_. 
 * 2024-11-30: Benchpress 2.10.0. This version includes algorithms from the `missing value PC (MVPC) <https://github.com/TURuibo/MVPC>`_ package for sampling data with missing values (:ref:`mvpc_gen_data`) and causal discovery (:ref:`mvpc`) in the presence of missing values.
 * 2024-11-24: Benchpress 2.9.0. This version comes with three new major features. 

workflow/envs/build_images.sh

@@ -1,4 +1,4 @@
-#!/usr/bin/bash
+#!/usr/local/bin/bash
 # Using bash 5
 
 # ARCH should be arm64 or amd64

…learning_algorithms/pyagrum/pyagrum.json …_learning_algorithms/pyagrum/config.jsonworkflow/rules/structure_learning_algorithms/pyagrum/pyagrum.json renamed to workflow/rules/structure_learning_algorithms/pyagrum/config.json workflow/rules/structure_learning_algorithms/pyagrum/pyagrum.json renamed to workflow/rules/structure_learning_algorithms/pyagrum/config.json

@@ -1,7 +1,7 @@
 {
   "benchmark_setup": [
     {
-      "title": "pyagrum_config",
+      "title": "pyagrum_demo",
       "data": [
         {
           "graph_id": "avneigs4",

workflow/rules/structure_learning_algorithms/pyagrum/docs.rst

@@ -1,2 +1,25 @@
 pyAgrum is a scientific C++ and Python library dedicated to Bayesian networks (BN) and other Probabilistic Graphical Models. Based on the C++ aGrUM library, it provides a high-level interface to the C++ part of aGrUM allowing to create, manage and perform efficient computations with Bayesian networks and others probabilistic graphical models : Markov random fields (MRF), influence diagrams (ID) and LIMIDs, credal networks (CN), dynamic BN (dBN), probabilistic relational models (PRM).
 
+
+.. rubric:: Example 
+
+Config file: `config.json <https://github.com/felixleopoldo/benchpress/blob/master/workflow/rules/structure_learning_algorithms/pyagrum/config.json>`_
+
+Command:
+
+.. code:: bash
+
+    snakemake --cores all --use-singularity --configfile workflow/rules/structure_learning_algorithms/pyagrum/config.json
+
+The following figure shows FP/P vs. TP/P for pattern graphs based on 5 datsets corresponding to 5 realisations of a 80-variables random binary Bayesian network, with an average indegree of 4.
+
+
+.. _pyagrumplot:
+
+.. figure:: ../../../workflow/rules/structure_learning_algorithms/pyagrum/pattern.png
+    :width: 320 
+    :alt: pyAgrum FP/P vs. TP/P example
+    :align: center
+
+    FP/P vs. TP/P. for pattern graphs
+

workflow/rules/structure_learning_algorithms/pyagrum/pattern.png

@@ -11,15 +11,41 @@
         "description": "Algorithm identifier",
         "type": "string"
       },
+        "useMDLCorrection": {
+            "anyOf":[
+                {
+                    "type": "boolean"
+                },
+                {
+                    "type": "array",
+                    "items": {
+                        "type": "boolean"
+                    }
+                }
+            ]
+        },
+        "useSmoothingPrior": {
+            "anyOf": [
+                {
+                    "type": "boolean"
+                },
+                {
+                    "type": "array",
+                    "items": {
+                        "type": "boolean"
+                    }
+                }
+            ]
+        },
       "timeout": {
         "$ref": "../../../schemas/definitions.schema.json#/definitions/flexnonnegnumnull"
       }
     },
-    "required": ["id", "timeout"],
+    "required": ["id", "timeout", "useMDLCorrection", "useSmoothingPrior"],
     "examples": [
       {
         "id": "pyagrum",
-        "useMDLCorrection": [true],
+        "useMDLCorrection": true,
         "useSmoothingPrior": [true, false],
         "timeout": null
       }

workflow/rules/structure_learning_algorithms/pyagrum/schema.json

@@ -20,34 +20,39 @@ def adjacency_to_csv(bn: BayesNet, *, to_file: str):
         writer = csv.writer(csvfile)
         # write header
         writer.writerow(id_to_name[col_id] for col_id in range(bn.size()))
-        #write rows
+        # write rows
         adj_mat = bn.adjacencyMatrix()
         writer.writerows(row for row in adj_mat)
 
+
 def myalg():
     # Read in data (not used in this algorithm)
     df = pd.read_csv(snakemake.input["data"])
 
     # The algorithm goes here
     np.random.seed(int(snakemake.wildcards["seed"]))
-    
-    df = df.iloc[1:] # remove the first row with cardinalities
 
-    tmpfile = snakemake.output["adjmat"] + ".tmp.csv"  # save the data to a temporary file
-    df.to_csv(tmpfile, index=False) 
+    df = df.iloc[1:]  # remove the first row with cardinalities
+
+    tmpfile = (
+        snakemake.output["adjmat"] + ".tmp.csv"
+    )  # save the data to a temporary file
+    df.to_csv(tmpfile, index=False)
+
+    learner = gum.BNLearner(
+        tmpfile
+    )  # MIIC is used as default (some score-based are also implented)
+
+    os.remove(tmpfile)  # remove the temporary file
 
-    learner=gum.BNLearner(tmpfile) # MIIC is used as default (some score-based are also implented)
-    
-    os.remove(tmpfile) # remove the temporary file
-   
     if eval(snakemake.wildcards["useMDLCorrection"]):
-        learner.useMDLCorrection() # for small dataset
-        
+        learner.useMDLCorrection()  # for small dataset
+
     if eval(snakemake.wildcards["useSmoothingPrior"]):
-        learner.useSmoothingPrior() # smoothing (default weight=1) for parameters
+        learner.useSmoothingPrior()  # smoothing (default weight=1) for parameters
+
+    bn = learner.learnBN()  # learning
 
-    bn = learner.learnBN() # learning
-    
     # Save time
     tottime = time.perf_counter() - start
     with open(snakemake.output["time"], "w") as text_file:
@@ -61,15 +66,17 @@ def myalg():
         text_file.write("None")
 
 
-# This part starts the timer 
+# This part starts the timer
 start = time.perf_counter()
 
 if snakemake.wildcards["timeout"] == "None":
     myalg()
 else:
-    with timeoutf(int(snakemake.wildcards["timeout"]),
-                  snakemake.output["adjmat"],
-                  snakemake.output["time"],
-                  snakemake.output["ntests"],
-                  start):
-        myalg()
+    with timeoutf(
+        int(snakemake.wildcards["timeout"]),
+        snakemake.output["adjmat"],
+        snakemake.output["time"],
+        snakemake.output["ntests"],
+        start,
+    ):
+        myalg()