[ENH] Simulation module for data-generating graphical models emphasiz…

…ing usage with discrete data (#82)

* Begin work on discrete sampling
* Add nvidia install for pgmpy
* Fix codecov

---------

Signed-off-by: Adam Li <adam2392@gmail.com>

.circleci/config.yml

@@ -65,14 +65,19 @@ jobs:
           name: Install pysal dependencies
           command: |
             sudo apt install libspatialindex-dev xdg-utils shared-mime-info desktop-file-utils
+      - run:
+          name: Setup torch for pgmpy
+          command: |
+            sudo apt-get install nvidia-cuda-toolkit nvidia-cuda-toolkit-gcc
+
       - run:
           name: Setup pandoc
           command: sudo apt update && sudo apt install -y pandoc optipng
 
       - python/install-packages:
           pkg-manager: poetry
-          cache-version: "v2" # change to clear cache
-          args: "--with docs --extras viz"
+          cache-version: "v1" # change to clear cache
+          args: "--with docs --extras viz --extras sims"
       - run:
           name: Check poetry package versions
           command: |
@@ -87,28 +92,28 @@ jobs:
       - run:
           name: Build documentation
           command: |
-            cd docs
+            cd doc
             poetry run poe build_docs
       # Save the example test results
       - store_test_results:
-          path: docs/_build/test-results
+          path: doc/_build/test-results
       - store_artifacts:
-          path: docs/_build/test-results
+          path: doc/_build/test-results
           destination: test-results
       # Save the SG RST
       - store_artifacts:
-          path: docs/auto_examples.zip
+          path: doc/auto_examples.zip
       - store_artifacts:
-          path: docs/generated.zip
+          path: doc/generated.zip
       # Save the outputs
       - store_artifacts:
-          path: docs/_build/html/
+          path: doc/_build/html/
           destination: dev
       - store_artifacts:
-          path: docs/_build/html_stable/
+          path: doc/_build/html_stable/
           destination: stable
       - persist_to_workspace:
-          root: docs/_build
+          root: doc/_build
           paths:
             - html
             - html_stable
@@ -152,14 +157,14 @@ jobs:
       - run:
           name: make linkcheck
           command: |
-            poetry run make -C docs linkcheck
+            poetry run make -C doc linkcheck
       - run:
           name: make linkcheck-grep
           when: always
           command: |
-            poetry run make -C docs linkcheck-grep
+            poetry run make -C doc linkcheck-grep
       - store_artifacts:
-          path: docs/_build/linkcheck
+          path: doc/_build/linkcheck
           destination: linkcheck
 
   deploy:
@@ -169,7 +174,7 @@ jobs:
       - checkout
 
       - attach_workspace:
-          at: docs/_build
+          at: doc/_build
       - run:
           name: Set BASH_ENV
           command: |
@@ -179,7 +184,7 @@ jobs:
       - run:
           name: Check docs
           command: |
-            if [ ! -f docs/_build/html/index.html ] && [ ! -f docs/_build/html_stable/index.html ]; then
+            if [ ! -f doc/_build/html/index.html ] && [ ! -f doc/_build/html_stable/index.html ]; then
               echo "No files found to upload (build: ${CIRCLE_BRANCH}).";
               circleci-agent step halt;
             fi;
@@ -200,10 +205,10 @@ jobs:
           command: |
             if [ "${CIRCLE_BRANCH}" == "main" ]; then
               echo "Deploying dev doc for ${CIRCLE_BRANCH}.";
-              node_modules/gh-pages/bin/gh-pages.js --dotfiles --message "doc updates [skip ci]" --dist docs/_build/html --dest ./dev
+              node_modules/gh-pages/bin/gh-pages.js --dotfiles --message "doc updates [skip ci]" --dist doc/_build/html --dest ./dev
             else
               echo "Deploying stable doc for ${CIRCLE_BRANCH}.";
-              node_modules/gh-pages/bin/gh-pages.js --dotfiles --message "doc updates [skip ci]" --dist docs/_build/html_stable --dest ./stable
+              node_modules/gh-pages/bin/gh-pages.js --dotfiles --message "doc updates [skip ci]" --dist doc/_build/html_stable --dest ./stable
             fi;
 
 workflows:

.codespellignore

@@ -1,3 +1,5 @@
 raison
 GES
-ges
+ges
+te
+fo

.flake8

@@ -18,7 +18,7 @@ exclude =
     .circleci
     paper
     setup.py
-    docs
+    doc
 
 per-file-ignores =
     # __init__.py files are allowed to have unused imports

.github/workflows/main.yml

@@ -143,10 +143,17 @@ jobs:
         run: |
           pip uninstall -yq networkx
           pip install --progress-bar off git+https://github.com/networkx/networkx
+      
+      - name: Setup torch for pgmpy
+        if: "matrix.os == 'ubuntu'"
+        shell: bash
+        run: |
+          sudo apt-get install nvidia-cuda-toolkit nvidia-cuda-toolkit-gcc
+  
       - name: Run pytest  # headless via Xvfb on linux
         run: poetry run poe unit_test
       - name: Upload coverage stats to codecov
-        if: ${{ matrix.os == 'ubuntu' && matrix.python-version == '3.10' && matrix.networkx == 'stable' }}
+        if: ${{ matrix.os == 'ubuntu' && matrix.python-version == '3.11' && matrix.networkx == 'stable' }}
         uses: codecov/codecov-action@v3
         with:
           files: ./coverage.xml

.github/workflows/pr_checks.yml

@@ -37,14 +37,14 @@ jobs:
           then
             exit 0
           fi
-          all_changelogs=$(cat ./docs/whats_new/v*.rst)
+          all_changelogs=$(cat ./doc/whats_new/v*.rst)
           if [[ "$all_changelogs" =~ :pr:\`$PR_NUMBER\` ]]
           then
             echo "Changelog has been updated."
             # If the pull request is milestoned check the correspondent changelog
-            if exist -f ./docs/whats_new/v${TAGGED_MILESTONE:0:4}.rst
+            if exist -f ./doc/whats_new/v${TAGGED_MILESTONE:0:4}.rst
             then
-              expected_changelog=$(cat ./docs/whats_new/v${TAGGED_MILESTONE:0:4}.rst)
+              expected_changelog=$(cat ./doc/whats_new/v${TAGGED_MILESTONE:0:4}.rst)
               if [[ "$expected_changelog" =~ :pr:\`$PR_NUMBER\` ]]
               then
                 echo "Changelog and milestone correspond."
@@ -58,7 +58,7 @@ jobs:
           else
             echo "A Changelog entry is missing."
             echo ""
-            echo "Please add an entry to the changelog at 'docs/whats_new/v*.rst'"
+            echo "Please add an entry to the changelog at 'doc/whats_new/v*.rst'"
             echo "to docsument your change assuming that the PR will be merged"
             echo "in time for the next release of pywhy-graphs."
             echo ""

.gitignore

@@ -75,7 +75,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+doc/_build/
 
 # PyBuilder
 target/
@@ -123,7 +123,7 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
-# mkdocs documentation
+# mkdoc documentation
 /site
 
 # mypy

CITATION.cff

@@ -0,0 +1,28 @@
+# YAML 1.2
+---
+# Metadata for citation of this software according to the CFF format (https://citation-file-format.github.io/)
+cff-version: 1.2.0
+title: 'Pywhy-Graphs:  Causal graphs that are networkx-compliant for the py-why ecosystem.'
+abstract: 'Pywhy-Graphs is a Python library to represent causal graphs and its related algorithms using a networkx-like API in Python.'
+authors:
+    - given-names: Adam
+      family-names: Li
+      affiliation: 'Department of Computer Science, Columbia University, New York, NY, USA'
+      orcid: 'https://orcid.org/0000-0001-8421-365X'
+    - given-names: Jaron
+      family-names: Lee
+      affiliation: 'Johns Hopkins University'
+      email: 'jaron2005@gmail.com'
+    - given-names: Aryan
+      family-names: Roy
+      affiliation: 'Manipal Institute of Technology'
+      email: 'aryanroy5678@gmail.com'
+type: software
+repository-code: 'https://github.com/py-why/pywhy-graphs'
+license: MIT
+keywords:
+  - causality
+  - pywhy
+  - graphs
+  - networkx
+...

README.md

@@ -3,18 +3,18 @@
 [![unit-tests](https://github.com/py-why/pywhy-graphs/actions/workflows/main.yml/badge.svg)](https://github.com/py-why/pywhy-graphs/actions/workflows/main.yml)
 [![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
 [![codecov](https://codecov.io/gh/py-why/pywhy-graphs/branch/main/graph/badge.svg?token=H1reh7Qwf4)](https://codecov.io/gh/py-why/pywhy-graphs)
+[![PyPI Download count](https://pepy.tech/badge/pywhy-graphs)](https://pepy.tech/project/pywhy-graphs)
+[![Latest PyPI release](https://img.shields.io/pypi/v/pywhy-graphs.svg)](https://pypi.org/project/pywhy-graphs/)
 
 # PyWhy-Graphs
 
 pywhy-graphs is a Python graph library that extends [networkx](https://github.com/networkx/networkx) with the notion of a `MixedEdgeGraph` to implement a light-weight API for causal graphical structures that contain mixed-edges and contain causal graph traversal algorithms.
 
-Note: The API is subject to change without deprecation cycles due to the current work-in-progress `MixedEdgeGraph` class in networkx. For more information, follow the PR at https://github.com/networkx/networkx/pull/5947
-
 ## Why?
 
 Representation of causal graphical models in Python are severely lacking.
 
-PyWhy-Graphs implements a graphical API layer for ADMG, CPDAG and PAG. For causal DAGs, we recommend using the `networkx.DiGraph` class and
+PyWhy-Graphs implements a graphical API layer for representing commmon graphs in causal inference: ADMG, CPDAG and PAG. For causal DAGs, we recommend using the `networkx.DiGraph` class and
 ensuring acylicity via `networkx.is_directed_acyclic_graph` function.
 
 Existing packages that aim to represent causal graphs either break from the networkX API, or only implement a subset of the relevant causal graphs. By keeping in-line with the robust NetworkX API, we aim to ensure a consistent user experience and a gentle introduction to causal graphical models. A `MixedEdgeGraph` instance is a composition of networkx graphs and has a similar API, with the additional notion of an "edge type", which specifies what edge type subgraph any function should operate over. For example:
@@ -77,3 +77,7 @@ To install the package from github, clone the repository and then `cd` into the
 Pywhy-Graphs is always looking for new contributors to help make the package better, whether it is algorithms, documentation, examples of graph usage, and more! Contributing to Pywhy-Graphs will be rewarding because you will contribute to a much needed package for causal inference.
 
 See our [contributing guide](https://github.com/py-why/pywhy-graphs/CONTRIBUTING.md) for more details.
+
+# Citing
+
+Please refer to the Github Citation to cite the repository.

docs/conf.py → doc/conf.py

@@ -24,6 +24,7 @@
 sys.path.insert(0, os.path.abspath("../"))
 
 import pywhy_graphs  # noqa: E402
+import pywhy_graphs.functional.discrete
 
 curdir = os.path.dirname(__file__)
 sys.path.append(os.path.abspath(os.path.join(curdir, "..")))
@@ -52,7 +53,7 @@
     "sphinx.ext.intersphinx",
     "sphinx_issues",
     "sphinx.ext.viewcode",
-    # "nbsphinx",  # enables building Jupyter notebooks and rendering
+    "nbsphinx",  # enables building Jupyter notebooks and rendering
     "sphinx.ext.mathjax",
     "sphinx_gallery.gen_gallery",
     "sphinxcontrib.bibtex",
@@ -213,10 +214,9 @@ def setup(app):
     "_build",
     "Thumbs.db",
     "**.ipynb_checkpoints",
-    # "auto_examples/*.rst",
-    # "auto_examples/index.rst",
-    # "auto_examples/mixededge/index.rst",
-    # "auto_examples/mixededge/*.rst",
+    '**/*.py',
+    "auto_examples/**/*.py",
+    "auto_examples/**/*.ipynb",
 ]
 
 source_suffix = [".rst", ".md"]
@@ -235,6 +235,7 @@ def setup(app):
     "pygraphviz": ("https://pygraphviz.github.io/documentation/stable/", None),
     "graphviz": ("https://graphviz.readthedocs.io/en/stable/", None),
     "sphinx-gallery": ("https://sphinx-gallery.github.io/stable/", None),
+    "pgmpy": ("https://pgmpy.org/", None),
 }
 intersphinx_timeout = 5
 
@@ -301,6 +302,7 @@ def setup(app):
             "../examples/mixededge",
             "../examples/intro",
             "../examples/visualization",
+            "../examples/simulations",
         ]
     ),
     # "filename_pattern": "^((?!sgskip).)*$",
@@ -356,6 +358,9 @@ def setup(app):
     ('py:obj', r"networkx*"),
 ]
 
+# -- Options for NBSphinx output ---------------------------------------------
+# Set nbsphinx_allow_errors to only allow Jupyter notebooks
+# nbsphinx_allow_errors = True
 
 doctest_global_setup = "import networkx as nx"
 
@@ -368,4 +373,5 @@ def setup(app):
 linkcheck_timeout = 15  # some can be quite slow
 linkcheck_ignore = [
     "https://github.com/{group}/{project}/pull/",  # sphinx-issues will render this properly
-]
+]
+

docs/reference/classes/index.rst → doc/reference/classes/index.rst

@@ -56,7 +56,7 @@ Finally, we also support time-series and create graphs that represent
 stationary time-series causal processes.
 
 +------------------------------------+----------------------------------+---------------------------------+
-| Pywhy_graph Class                  | Edge Types                       | Analagous non time-series graph |
+| Pywhy_graph Class                  | Edge Types                       | Analogous non time-series graph |
 +====================================+==================================+=================================+
 | StationaryTimeSeriesGraph          | undirected                       | nx.Graph                        |
 +------------------------------------+----------------------------------+---------------------------------+