[ENH] Adding multi-domain functional linear graph and fix bug related…

… to drawing causal graphs (#77) * Adding multi-domain linear func graph * Adding user-guide doc for functional graphical models's * Refactoring the augmented graph * Update poetry to v1.5 * Fix bug in draw for CPDAG and casual graphs that draw edges between node and its descendants --------- Signed-off-by: Adam Li <adam2392@gmail.com>
py-why · May 24, 2023 · 2d6f1d3 · 2d6f1d3
1 parent 3de911e
commit 2d6f1d3
Show file tree

Hide file tree

Showing 24 changed files with 1,250 additions and 254 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -46,7 +46,7 @@ jobs:
       - run:
           name: Install the latest version of Poetry
           command: |
-            curl -sSL https://install.python-poetry.org | python3 - --version 1.3.0
+            curl -sSL https://install.python-poetry.org | python3 - --version 1.5.0
             poetry --version
       - run:
           name: Set BASH_ENV
@@ -64,10 +64,11 @@ jobs:
       - run:
           name: Install pysal dependencies
           command: |
-            sudo apt install libspatialindex-dev xdg-utils
+            sudo apt install libspatialindex-dev xdg-utils shared-mime-info
       - run:
           name: Setup pandoc
           command: sudo apt update && sudo apt install -y pandoc optipng
+
       - python/install-packages:
           pkg-manager: poetry
           cache-version: "v1" # change to clear cache

diff --git a/docs/api.rst b/docs/api.rst
@@ -29,8 +29,7 @@ graphs encountered in the literature.
    CPDAG
    PAG
    AugmentedGraph
-   IPAG
-   PsiPAG
+   AugmentedPAG
 
 :mod:`pywhy_graphs.algorithms`: Algorithms for Mixed-Edge Graphs
 ================================================================
@@ -55,6 +54,9 @@ causal graph operations.
    uncovered_pd_path
    acyclification
    is_definite_noncollider
+   find_connected_pairs
+   add_all_snode_combinations
+   compute_invariant_domains_per_node
 
 Conversions between other package's causal graphs
 =================================================
@@ -158,6 +160,9 @@ linear structural equation Gaussian models (SEMs).
    :toctree: generated/
 
    make_graph_linear_gaussian
+   apply_linear_soft_intervention
+   set_node_attributes_with_G
+   make_graph_multidomain
 
 Visualization of causal graphs
 ==============================

diff --git a/docs/reference/classes/index.rst b/docs/reference/classes/index.rst
@@ -49,9 +49,7 @@ the addition of "F-nodes", which represent interventions :footcite:`pearl1993asp
 +===================+==========================================+==============+
 | AugmentedGraph    | directed, undirected, bidirected         | Yes          |
 +-------------------+------------------------------------------+--------------+
-| IPAG              | directed, undirected, bidirected, circle | Yes          |
-+-------------------+------------------------------------------+--------------+
-| PsiPAG            | directed, undirected, bidirected, circle | No           |
+| AugmentedPAG      | directed, undirected, bidirected, circle | Yes          |
 +-------------------+------------------------------------------+--------------+
 
 Finally, we also support time-series and create graphs that represent

diff --git a/docs/reference/functional/index.rst b/docs/reference/functional/index.rst
@@ -0,0 +1,103 @@
+.. _functional-causal-graphical-models:
+
+**********************************
+Functional Causal Graphical Models
+**********************************
+
+.. automodule:: pywhy_graphs.functional
+    :no-members:
+    :no-inherited-members:
+
+Pywhy-graphs provides a layer to convert imbue causal graphs with a data-generating
+model. Currently, we only support linear models, but we plan to support non-linear
+and we also do not support latent confounders yet.
+
+To add a latent confounder, one can add a confounder explicitly, generate the data
+and then drop the confounder varialble in the final dataset. In the roadmap of this submodule,
+the plan is to represent any bidirected edge as a uniformly randomly distributed variable
+that has an additive noise effect on both variables simulatanously.
+
+Linear
+======
+
+In order to represent linear functions, we imbue nodes with a set of node attributes:
+
+- ``parent_functions``: a mapping of functions that map each node to a nested dictionary
+    of parents and their corresponding weight and function that map parent values to
+    values that are input to the node value with the weight. 
+- ``gaussian_noise_function``: a dictionary with keys ``mean`` and ``std`` that
+    encodes the data-generating function for the Gaussian noise.
+
+    For example, if the node
+    is :math:`X` and its parents are :math:`Y` and :math:`Z`, then ``parent_functions``
+    and ``gaussian_noise_function`` for node :math:`X` is:
+
+    .. code-block:: python
+
+        {
+            'X': {
+                'parent_functions': {
+                    'Y': {
+                        'weight': <weight of Y added to X>,
+                        'func': <function that takes input Y>,
+                    },
+                    'Z': {
+                        'weight': <weight of Z added to X>,
+                        'func': <function that takes input Z>,
+                    },
+                },
+                'gaussian_noise_function': {
+                    'mean': <mean of gaussian noise added to X>,
+                    'std': <std of gaussian noise added to X>,
+                }
+            }
+        }
+
+Linear functional graphs
+========================
+.. currentmodule:: pywhy_graphs.functional
+
+.. autosummary::
+   :toctree: ../../generated/
+
+   make_graph_linear_gaussian
+   apply_linear_soft_intervention
+
+Multidomain
+===========
+
+Currently, this submodule only supports linear functions.
+
+Multiple-domain causal graphs are represented by selection diagrams :footcite:`bareinboim_causal_2016`,
+or augmented selection diagrams (TODO: CITATION FOR LEARNING SEL DIAGRAMS).
+
+In order to represent multidomain functions, we imbue nodes with a set of node attributes
+in addition to the ones for linear functions. The nodes that are imbued with extra attributes
+are the direct children of an S-node.
+
+- ``invariant_domains``: a list of domain IDs that are invariant for this node.
+- ``domain_gaussian_noise_function``: a dictionary with keys ``mean`` and ``std`` that
+    encodes the data-generating function for the Gaussian noise for each non-invariant domain.
+
+    .. code-block:: python
+        
+        {
+            'X': {
+                'domain_gaussian_noise_function': {
+                    <domain_id>: {
+                        'mean': <mean of gaussian noise added to X>,
+                        'std': <std of gaussian noise added to X>,
+                    },
+                'invariant_domains': [<domain_id>, ...],
+                }
+            }
+        }
+
+Linear functional selection diagrams
+====================================
+.. currentmodule:: pywhy_graphs.functional
+
+.. autosummary::
+   :toctree: ../../generated/
+
+   make_graph_multidomain
diff --git a/docs/references.bib b/docs/references.bib
@@ -1,6 +1,22 @@
 % Encoding: UTF-8
 % Try to keep this list in alphabetical order based on citing name
 
+
+@article{bareinboim_causal_2016,
+	title = {Causal inference and the data-fusion problem},
+	volume = {113},
+	url = {https://www.pnas.org/content/113/27/7345},
+	doi = {10.1073/PNAS.1510507113},
+	number = {27},
+	journal = {Proceedings of the National Academy of Sciences},
+	author = {Bareinboim, Elias and Pearl, Judea},
+	month = jul,
+	year = {2016},
+	note = {Publisher: National Academy of Sciences},
+	keywords = {Causal inference, Counterfactuals, External validity, Selection bias, Transportability},
+	pages = {7345--7352},
+}
+
 @article{Colombo2012,
   author    = {Diego Colombo and Marloes H. Maathuis and Markus Kalisch and Thomas S. Richardson},
   title     = {{Learning high-dimensional directed acyclic graphs with latent and selection variables}},

diff --git a/docs/user_guide.rst b/docs/user_guide.rst
@@ -15,6 +15,7 @@ User Guide
    :maxdepth: 2
 
    reference/classes/index
+   reference/functional/index
    reference/algorithms/index
    reference/simulation/index
    reference/export/index

diff --git a/docs/whats_new/v0.1.rst b/docs/whats_new/v0.1.rst
@@ -44,6 +44,7 @@ Changelog
 - |Feature| Implement export/import functions to go to/from pywhy-graphs to ananke-causal, by `Jaron Lee`_ (:pr:`63`)
 - |Feature| Implement pre-commit hooks for development, by `Jaron Lee`_ (:pr:`68`)
 - |Feature| Implement a new submodule for converting graphs to a functional model, with :func:`pywhy_graphs.functional.make_graph_linear_gaussian`, by `Adam Li`_ (:pr:`75`)
+- |Feature| Implement a multidomain linear functional graph, with :func:`pywhy_graphs.functional.make_graph_multidomain`, by `Adam Li`_ (:pr:`77`)
 
 Code and Documentation Contributors
 -----------------------------------