v2.11.0 (#138)

* Adding bips_tpc: This version introduces the bips_tpc module, based on the temporal PC (tPC) and the micd package. It enables causal discovery through the PC algorithm allowing for Edge constraints, mixed data, and missing data handling. * Updating basic conf example. Updating example for MVPC.
felixleopoldo · Dec 16, 2024 · bc5dfcb · bc5dfcb
1 parent 1c11ba4
commit bc5dfcb
Show file tree

Hide file tree

Showing 56 changed files with 1,308 additions and 132 deletions.
diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-2.10.0
+2.11.0
diff --git a/config/config.json b/config/config.json
@@ -1,6 +1,7 @@
 {
   "benchmark_setup": [
     {
+      "title": "example_config",
       "data": [
         {
           "graph_id": "avneigs4_p20",
@@ -31,17 +32,24 @@
         "graph_true_plots": true,
         "graph_true_stats": true,
         "ggally_ggpairs": true,
-        "graph_plots": [
-          "fges-sem-bic",
-          "tabu-bge",
-          "itsearch-bge",
-          "pc-gaussCItest"
-        ],
+        "graph_estimation": {
+          "ids": [
+            "fges-sem-bic",
+            "tabu-bge",
+            "itsearch-bge",
+            "pc-gaussCItest"
+          ],
+          "convert_to": [],
+          "graphs": true,
+          "adjmats": true,
+          "diffplots": true,
+          "csvs": true,
+          "graphvizcompare": true
+        },
         "mcmc_traj_plots": [],
         "mcmc_heatmaps": [],
         "mcmc_autocorr_plots": []
-      },
-      "title": "config"
+      }      
     }
   ],
   "resources": {

diff --git a/config/paper_er_bin.json b/config/paper_er_bin.json
@@ -26,7 +26,6 @@
           "path": true,
           "text": false,
           "ids": [
-            "gobnilp-bde",
             "grasp-bdeu",
             "boss-bdeu",
             "asobs-bdeu",

diff --git a/config/paper_er_sem.json b/config/paper_er_sem.json
@@ -26,7 +26,6 @@
           "path": true,
           "text": false,
           "ids": [
-            "gobnilp-bge",
             "boss-sem-bic",
             "grasp-sem-bic",
             "notears-l2",

diff --git a/config/paper_er_sem_small.json b/config/paper_er_sem_small.json
@@ -26,7 +26,6 @@
           "path": true,
           "text": false,
           "ids": [
-            "gobnilp-bge",
             "boss-sem-bic",
             "grasp-sem-bic",
             "notears-l2",

diff --git a/config/paper_hepar2_bin.json b/config/paper_hepar2_bin.json
@@ -26,7 +26,6 @@
           "path": true,
           "text": false,
           "ids": [
-            "gobnilp-bde",
             "grasp-bdeu",
             "boss-bdeu",
             "asobs-bdeu",

diff --git a/config/paper_hepar2_sem.json b/config/paper_hepar2_sem.json
@@ -26,7 +26,6 @@
           "path": true,
           "text": false,
           "ids": [
-            "gobnilp-bge",
             "boss-sem-bic",
             "grasp-sem-bic",
             "notears-l2",

diff --git a/config/paper_sachs.json b/config/paper_sachs.json
@@ -19,7 +19,6 @@
           "path": true,
           "text": false,
           "ids": [
-            "gobnilp-bge",
             "boss-sem-bic",
             "grasp-sem-bic",
             "notears-l2",

diff --git a/docs/source/available_background_knowledge.rst b/docs/source/available_background_knowledge.rst
@@ -8,47 +8,54 @@ Edge constraints
 ---------------------------------------
 
 Benchpress allows users to incorporate edge constraints to guide structure learning algorithms in several packages: 
-**pcalg**, **mvpc**, **bnlearn**, **tetrad**, **gobnilp**, and **bidag**. These constraints enable the inclusion of prior knowledge to refine 
+**pcalg**, **bips_tpc**, **mvpc**, **bnlearn**, **tetrad**, **gobnilp**, and **bidag**. These constraints enable the inclusion of prior knowledge to refine 
 the search space of causal graphs, improving the reliability of the inferred relationships. Users can specify **forbidden or 
 required edges**, **tiers for temporal ordering**, and **group-based constraints**.
 
 The edge constraints should be defined in a JSON file located within the ``resources/constraints`` folder.
 
 .. rubric:: Supported Constraints
 
-+-------------+---------------------+--------------------+-----------+----------------------+---------------------+
-| **Package** | **forbidden_edges** | **required_edges** | **tiers** | **forbidden_groups** | **required_groups** |
-+=============+=====================+====================+===========+======================+=====================+
-| mvpc        | X                   | X                  | N/A       | N/A                  | N/A                 |
-+-------------+---------------------+--------------------+-----------+----------------------+---------------------+
-| pcalg       | X                   | X                  | N/A       | N/A                  | N/A                 |
-+-------------+---------------------+--------------------+-----------+----------------------+---------------------+
-| bnlearn     | X                   | X                  | X         | X                    | X                   |
-+-------------+---------------------+--------------------+-----------+----------------------+---------------------+
-| tetrad      | X                   | X                  | X         | X                    | X                   |
-+-------------+---------------------+--------------------+-----------+----------------------+---------------------+
-| gobnilp     | X                   | X                  | X         | X                    | X                   |
-+-------------+---------------------+--------------------+-----------+----------------------+---------------------+
-| bidag       | X                   | N/A                | N/A       | X                    | N/A                 |
-+-------------+---------------------+--------------------+-----------+----------------------+---------------------+
++-------------+---------------------+--------------------+-----------+----------------------+---------------------+-----------------+------------------+------------------+
+| **Package** | **forbidden_edges** | **required_edges** | **tiers** | **forbidden_groups** | **required_groups** | **context_all** | **context_tier** | **source_nodes** |
++=============+=====================+====================+===========+======================+=====================+=================+==================+==================+
+| bips_tpc    | X                   | N/A                | X         | X                    | N/A                 | X               | X                | X                |
++-------------+---------------------+--------------------+-----------+----------------------+---------------------+-----------------+------------------+------------------+
+| mvpc        | X                   | X                  | N/A       | N/A                  | N/A                 | N/A             | N/A              | N/A              |
++-------------+---------------------+--------------------+-----------+----------------------+---------------------+-----------------+------------------+------------------+
+| pcalg       | X                   | X                  | N/A       | N/A                  | N/A                 | N/A             | N/A              | N/A              |
++-------------+---------------------+--------------------+-----------+----------------------+---------------------+-----------------+------------------+------------------+
+| bnlearn     | X                   | X                  | X         | X                    | X                   | N/A             | N/A              | N/A              |
++-------------+---------------------+--------------------+-----------+----------------------+---------------------+-----------------+------------------+------------------+
+| tetrad      | X                   | X                  | X         | X                    | X                   | N/A             | N/A              | N/A              |
++-------------+---------------------+--------------------+-----------+----------------------+---------------------+-----------------+------------------+------------------+
+| gobnilp     | X                   | X                  | X         | X                    | X                   | N/A             | N/A              | N/A              |
++-------------+---------------------+--------------------+-----------+----------------------+---------------------+-----------------+------------------+------------------+
+| bidag       | X                   | N/A                | N/A       | X                    | N/A                 | N/A             | N/A              | N/A              |
++-------------+---------------------+--------------------+-----------+----------------------+---------------------+-----------------+------------------+------------------+
+
 
 .. rubric:: Description
 
 - ``forbidden_edges``: A list of directed edges that are explicitly prohibited from existing between specific nodes. Each edge is defined as a pair of nodes, where the first node cannot directly cause the second node. 
 - ``required_edges``: A list of directed edges that are enforced between specific nodes. Each edge is defined as a pair of nodes, where the first node must directly cause the second node. 
-
-  - *Note: For algorithms in the* **pcalg** and **mvpc** *package, the above attributes only specify the presence or absence of edges and do not control their directionality.*
 - ``tiers``: Defines a temporal ordering of nodes across multiple levels (or) tiers. Nodes in one tier are constrained from causing nodes in any of the preceding tiers. 
 - ``tier_settings``: 
 
   - ``forbidden_within_tiers``: If set to `true`, prevents edges between nodes that reside within the same tier. 
   - ``can_only_cause_next_tier``: If set to `true`, restricts nodes in one tier to only influence or cause nodes in the immediate next tier. 
 
-- ``Groups``: Defines relationships between sets of nodes, grouping them for the purpose of controlling edge behavior across multiple nodes at once. Each group is defined by a collection of "cause" nodes and "effect" nodes.
+- *Groups*: Defines relationships between sets of nodes, grouping them for the purpose of controlling edge behavior across multiple nodes at once. Each group is defined by a collection of "cause" nodes and "effect" nodes.
 
   - ``forbidden_groups``: A set of constraints that prohibits directed edges between specified groups of nodes. 
   - ``required_groups``: A set of requirements that enforces directed edges between specified groups of nodes. 
+- ``context_all``: If set to `true`, edges added from this node to all other nodes.
+- ``context_tier``: If set to `true`, edges added from this node to all nodes within the same tier.
+- ``source_nodes``: A list of nodes that are restricted to have no parents.
 
+.. note::
+
+    For algorithms in the **pcalg** and **mvpc** *package, the above attributes only specify the presence or absence of edges and do not control their directionality.*
 
 .. rubric:: Example JSON
 
@@ -89,7 +96,10 @@ The edge constraints should be defined in a JSON file located within the ``resou
                 "cause": ["22"],
                 "effect": ["23"]
             }
-        ]
+        ],
+        "context_all": ["1"],
+        "context_tier": ["3"],
+        "source_nodes": ["11"]
     }
 
 

diff --git a/docs/source/available_structure_learning_algorithms.rst b/docs/source/available_structure_learning_algorithms.rst
@@ -15,6 +15,7 @@ Algorithms
     structure_learning_algorithms/bidag_itsearch
     structure_learning_algorithms/bidag_order_mcmc
     structure_learning_algorithms/bidag_partition_mcmc
+    structure_learning_algorithms/bips_tpc
     structure_learning_algorithms/bnlearn_fastiamb
     structure_learning_algorithms/bnlearn_gs
     structure_learning_algorithms/bnlearn_h2pc
@@ -30,7 +31,6 @@ Algorithms
     structure_learning_algorithms/bnlearn_sihitonpc
     structure_learning_algorithms/bnlearn_tabu
     structure_learning_algorithms/causaldag_gsp
-    structure_learning_algorithms/causallearn_ges
     structure_learning_algorithms/causallearn_grasp
     structure_learning_algorithms/corr_thresh
     structure_learning_algorithms/dualpc
@@ -112,6 +112,10 @@ To add new modules, see :ref:`new_modules`.
      - `DAG <https://en.wikipedia.org/wiki/Directed_acyclic_graph>`__, `CPDAG <https://search.r-project.org/CRAN/refmans/pcalg/html/dag2cpdag.html>`__
      - `BiDAG <https://cran.r-project.org/web/packages/BiDAG/index.html>`__
      - :ref:`bidag_partition_mcmc` 
+   * - tPC
+     - `CPDAG <https://search.r-project.org/CRAN/refmans/pcalg/html/dag2cpdag.html>`__
+     - `tpc <https://github.com/bips-hb/tpc>`__
+     - :ref:`bips_tpc` 
    * - Fast IAMB
      - `DAG <https://en.wikipedia.org/wiki/Directed_acyclic_graph>`__
      - `bnlearn <https://www.bnlearn.com/>`__
@@ -248,7 +252,7 @@ To add new modules, see :ref:`new_modules`.
      - `UDG <https://arxiv.org/pdf/2210.00822.pdf#subsection.2.2>`__
      - `gues <https://pypi.org/project/gues/>`__
      - :ref:`grues` 
-   * - Graphical lasso
+   * - GLasso
      - `UG <https://en.wikipedia.org/wiki/Graph_(discrete_mathematics)#Graph>`__
      - `huge <https://cran.r-project.org/web/packages/huge/index.html>`__
      - :ref:`huge_glasso` 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -43,8 +43,8 @@
     'sphinxcontrib.bibtex',
     'sphinx_last_updated_by_git',
     'versionwarning.extension',
+    "sphinxext.opengraph",
     "sphinxcontrib.googleanalytics"
-
 ]
 googleanalytics_id = "G-CDYR88PWR3"
 
@@ -93,6 +93,10 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+ogp_site_url = "https://benchpressdocs.readthedocs.io"
+ogp_image = "https://github.com/felixleopoldo/benchpress/raw/master/docs/source/_static/benchpress-logo-white-bg.png"
+ogp_description = "Benchpress is a platform-independent open-source software to develop, execute, and benchmark causal discovery algorithms."
+ogp_enable_meta_description = False
 
 html_logo = '_static/benchpress-logo-readthedocs@2x.png'
 html_theme_options = {

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,12 +1,9 @@
-.. Benchpress documentation master file, created by
-   sphinx-quickstart on Mon Oct 26 10:03:54 2020.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
+:og:description: Benchpress is a platform-independent open-source software to develop, execute, and benchmark causal discovery algorithms.
 
 .. meta::
     :title: Benchpress: Open-Source Causal Discovery Suite
     :description: Benchpress is a platform-independent open-source software to develop, execute, and benchmark causal discovery algorithms.
+
 .. toctree::
     :hidden:
     :glob:
@@ -99,18 +96,21 @@ generated datasets, the workflow also includes a number of standard datasets and
 
 .. rubric:: News
 
-* 2024-11-30: Benchpress 2.10.0. This version includes algorithms from the MVPC package for sampling (:ref:`mvpc_gen_data`) and causal discovery (:ref:`mvpc`) in the presence of missing data.
+* 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. 
 
     I) The ability to incorporate background knowledge in terms of :ref:`edge_constraints`. Thanks to `Gomathi Lakshmanan <https://www.linkedin.com/in/gomathi-l/>`_ for this great feature. 
-    II) The ability to specify multiple benchmark setups in the same config file (See :ref:`json_config`). To convert the old config format to this new one run 
+    II) The ability to specify multiple benchmark setups in the same config file (See :ref:`json_config`).             
+    III) Generating DAGs using the `gCastle <https://github.com/huawei-noah/trustworthyAI/blob/master/gcastle/README.md>`_  package (:ref:`gcastle_dag`). Thanks to `Damian Machlanski <https://dmachlanski.com/>`_.
+
+    To convert the config files (<2.9.0) to this new format run 
 
         .. prompt:: bash
 
             chmod +x scripts/utils/reformat_conf_files.py 
             workflow/scripts/utils/reformat_conf_files.py
-
-    III) Generating DAGs using the `gCastle <https://github.com/huawei-noah/trustworthyAI/blob/master/gcastle/README.md>`_  package (:ref:`gcastle_dag`). Thanks to `Damian Machlanski <https://dmachlanski.com/>`_.
+
 * 2024-06-27: Benchpress 2.8.0. The new :ref:`graph_estimation` module enables graph estimation and plotting. It will replace the :ref:`graph_plots` module as it is faster an easier to use. 
 * 2024-03-20: `Jack Kuipers <https://bsse.ethz.ch/cbg/group/people/person-detail.MjA3Mjc0.TGlzdC81MTYsOTQ0ODM3Mzc2.html>`_ gives a `Zoom seminar <https://ethz.zoom.us/j/65832714361>`_ on Benchpress today at 5 PM CET at `The Swiss Reproducibility Network <https://www.swissrn.org/computational/>`_
 * 2024-02-13: Updated :ref:`examples` with timings and the algorithms BOSS (:ref:`tetrad_boss`) and GRaSP (:ref:`tetrad_grasp`).

diff --git a/docs/source/requirements.txt b/docs/source/requirements.txt
@@ -10,3 +10,4 @@ requests
 sphinx-version-warning
 sphinx-last-updated-by-git
 sphinxcontrib-googleanalytics==0.4
+sphinxext-opengraph
diff --git a/docs/source/structure_learning_algorithms/bdgraph.rst b/docs/source/structure_learning_algorithms/bdgraph.rst
@@ -3,7 +3,7 @@
 
     .. meta::
         :title: BDgraph 
-        :description:    
+        :description: BDgraph performs Bayesian structure learning for general undirected graphical models (decomposable and non-decomposable) with continuous, discrete, and mixed variables using MCMC.
 
 
 .. _bdgraph: 
@@ -39,10 +39,15 @@ BDgraph
 -----------
 
 
-
-
-
-
+Abstract: Graphical models provide powerful tools to uncover complicated patterns in multivariate data and are commonly used in Bayesian statistics and machine learning. In this
+paper, we introduce the R package BDgraph which performs Bayesian structure learning for general undirected graphical models (decomposable and non-decomposable) with
+continuous, discrete, and mixed variables. The package efficiently implements recent improvements in the Bayesian literature, including that of Mohammadi and Wit (2015) :footcite:p:`mohammadi2015bayesian` and 
+Dobra and Mohammadi (2018) :footcite:p:`10.1214/18-AOAS1164`. To speed up computations, the computationally intensive tasks have been implemented in C++ and interfaced with R, and the package has
+parallel computing capabilities. In addition, the package contains several functions for
+simulation and visualization, as well as several multivariate datasets taken from the literature and used to describe the package capabilities. The paper includes a brief overview
+of the statistical methods which have been implemented in the package. The main part
+of the paper explains how to use the package. Furthermore, we illustrate the package’s
+functionality in both real and artificial examples.