[ENH] Export and import graph classes from other common interfaces (#60)

* Working export and unit-tests for common external packages

---------
Signed-off-by: Adam Li <[email protected]>

Author: adam2392

.github/workflows/main.yml

@@ -152,40 +152,6 @@ jobs:
           files: ./coverage.xml
           fail_ci_if_error: true
           verbose: true
-      
-  integration_test:
-    timeout-minutes: 30
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu]
-        python-version: ["3.10"]  # oldest and newest supported versions
-        poetry-version: [1.3.0]
-        networkx: [stable, main]
-    name: Integration-test ${{ matrix.os }} - py${{ matrix.python-version }} - Networkx ${{ matrix.networkx }}
-    runs-on: ${{ matrix.os }}-latest
-    defaults:
-      run:
-        shell: bash
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v3
-      - name: Setup Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
-        with:
-          python-version: ${{ matrix.python-version }}
-          architecture: 'x64'
-      - name: Install Poetry ${{ matrix.poetry-version }}
-        uses: abatilo/[email protected]
-        with:
-          poetry-version: ${{ matrix.poetry-version }}
-      - name: Install Poetry Dynamic Versioning Plugin
-        run: pip install poetry-dynamic-versioning
-      - name: Install packages via poetry
-        run: |
-          poetry install --with test,ts
-      - name: Run pytest  # headless via Xvfb on linux
-        run: poetry run poe integration_test
 
   # release is ran when a release is made on Github
   release:

CONTRIBUTING.md

@@ -138,7 +138,7 @@ We use [Sphinx](https://www.sphinx-doc.org/en/master/index.html) to build our AP
 of public classes and methods. All docstrings should adhere to the [Numpy styling convention](https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html).
 
 ### Testing Changes Locally With Poetry
-With poetry installed, we have included a few convenience functions to check your code. These checks must pass and will be checked by the PR's continuous integration services. You can install the various different developer dependencies with poetry:
+With poetry installed, we have included a few convenience functions to check your code. **These checks must pass** and will be checked by the PR's continuous integration services. You can install the various different developer dependencies with poetry:
 
     poetry install --with style, docs, test
 

README.md

@@ -4,9 +4,9 @@
 [![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)
 
-# PyWhy-Graphs (Experimental)
+# PyWhy-Graphs
 
-pywhy-graphs is a Python graph library that extends `MixedEdgeGraph` in [networkx](https://github.com/networkx/networkx) to implement a light-weight API for causal graphical structures.
+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
 
@@ -17,7 +17,15 @@ 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
 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.
+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:
+
+```Python
+# adds a directed edge from x to y
+G.add_edge('x', 'y', edge_type='directed')
+
+# adds a bidirected edge from x to y
+G.add_edge('x', 'y', edge_type='bidirected')
+```
 
 Moreover, sampling from causal models is non-trivial, but a requirement for benchmarking many causal algorithms in discovery, ID, estimation and more. We aim to provide simulation modules that are easily connected with causal graphs to provide a simple robust API for modeling causal graphs and then simulating data.
 
@@ -29,17 +37,19 @@ Or see [stable version documentation](https://py-why.github.io/pywhy-graphs/stab
 
 # Installation
 
-Installation is best done via `pip` or `conda`. For developers, they can also install from source using `pip`. See [installation page](TBD) for full details.
+Installation is best done via `pip` or `conda`. For developers, they can also install from source using `pip`. See [installation page](https://py-why.github.io/pywhy-graphs/dev/installation.html) for full details.
 
 ## Dependencies
 
-Minimally, pywhy-graphs requires:
+We aim to provide a very light-weight dependency structure. Minimally, pywhy-graphs requires:
 
     * Python (>=3.8)
     * numpy
     * scipy
     * networkx
 
+Additional functionality may be required when running unit-tests and documentation.
+
 ## User Installation
 
 If you already have a working installation of numpy, scipy and networkx, the easiest way to install pywhy-graphs is using `pip`:
@@ -58,3 +68,9 @@ To install the package from github, clone the repository and then `cd` into the
     pip install -e .
 
     pip install https://api.github.com/repos/py-why/pywhy-graphs/zipball/main
+
+# Contributing
+
+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.

docs/api.rst

@@ -63,13 +63,19 @@ implement various causal inference procedures, but encode a causal graph object
 differently. This submodule converts between those causal graph data structures
 and corresponding causal graphs in pywhy-graphs.
 
-.. currentmodule:: pywhy_graphs.array
+.. currentmodule:: pywhy_graphs.export
 
 .. autosummary::
    :toctree: generated/
 
-   graph_to_arr
-   clearn_arr_to_graph
+   graph_to_clearn
+   clearn_to_graph
+   graph_to_numpy
+   numpy_to_graph
+   graph_to_tetrad
+   tetrad_to_graph
+   graph_to_pcalg
+   pcalg_to_graph
 
 NetworkX Experimental Functionality
 ===================================

docs/index.rst

@@ -9,8 +9,6 @@ algorithms and data structures of ``networkx``.
 We encourage you to use the package for your causal inference research and also build on top
 with relevant Pull Requests. Also, see our `contributing guide <https://github.com/mne-tools/mne-icalabel/blob/main/CONTRIBUTING.md>`_.
 
-See our examples for walk-throughs of how to use the package.
-
 Please refer to our :ref:`user_guide` for details on all the tools that we
 provide. You can also find an exhaustive list of the public API in the
 :ref:`api_ref`. You can also look at our numerous :ref:`examples <general_examples>`
@@ -25,7 +23,6 @@ eventually converge to a stable API that maintains the common software engineeri
 will be marked as "alpha" indicating that their might be drastic changes over different releases.
 One should use alpha functionality with caution.
 
-
 Contents
 --------
 
@@ -42,7 +39,12 @@ Contents
 Team
 ----
 
-**pywhy-graphs** is developed and maintained by pywhy.
+**pywhy-graphs** is developed and maintained by open-source contributors like yourself, and is always interested
+in getting contributions from YOU! Our Github Issues page contains many issues that need to be solved to
+improve the overall package. If you are interested in contributing, please do not hesitate to reach out to us on Github!
+
+See our `contributing document <https://github.com/py-why/pywhy-graphs/CONTRIBUTING.md>`_ for details on our approach to Issues and Pull Requests.
+
 To learn more about who specifically contributed to this codebase, see
 `our contributors <https://github.com/py-why/pywhy-graphs/graphs/contributors>`_ page.
 

docs/reference/export/index.rst

@@ -0,0 +1,82 @@
+.. _export:
+
+**************************************************************************************
+Importing causal graphs to PyWhy-Graphs, or exporting PyWhy-Graphs to another package
+**************************************************************************************
+
+.. automodule:: pywhy_graphs.export
+    :no-members:
+    :no-inherited-members:
+
+Pywhy-graphs provides light-weight data structures and networkx-like methods for
+storing causal graphs.
+
+The causality community is quite large and currently there is no de-facto standard
+for representing causal graphs with mixed edges. Therefore, we provide an interface
+for importing/exporting graphs from other packages.
+
+We currently only offer support for a package if they have a way of representing
+all types of causal graphs (not just DAGs). We welcome contributions here!
+
+Causal-Learn
+============
+Causal-learn maintains its own graph interpretation in the form of a structured
+upper-triangular numpy array.
+
+.. currentmodule:: pywhy_graphs.export
+   
+.. autosummary::
+   :toctree: ../../generated/
+
+   graph_to_clearn
+   clearn_to_graph
+
+Numpy (graphviz and dagitty)
+============================
+GraphViz stores a graph that allows mixed-edges using a numpy array with values filled
+in following a specific enumeration, so all values can be mapped to an edge, or multiple
+edges if more than one edge is allowed between nodes.
+
+.. autosummary::
+   :toctree: ../../generated/
+
+   graph_to_numpy
+   numpy_to_graph
+
+
+PCAlg from R (Experimental)
+===========================
+``pcalg`` from R uses the following mapping for their array:
+
+- 0: no edge
+- 1: -o
+- 2: -> (arrowhead)
+- 3: - (tail)
+
+and stores a structured numpy array following this format. This functionality
+is experimental because this is not tested against the actual implementation in R.
+Please raise an issue if you encounter errors, or issues.
+
+.. autosummary::
+   :toctree: ../../generated/
+
+   graph_to_pcalg
+   pcalg_to_graph
+
+Tetrad from Java
+================
+``tetrad`` from Java uses the following mapping for their endpoints 
+stored in a text file:
+
+- TAIL = "-"
+- ARROW = ">"
+- CIRCLE = "o"
+
+This functionality is experimental because this is not tested against the actual implementation in Java.
+Please raise an issue if you encounter errors, or issues.
+
+.. autosummary::
+   :toctree: ../../generated/
+
+   graph_to_tetrad
+   tetrad_to_graph

docs/user_guide.rst

@@ -14,6 +14,8 @@ User Guide
    :numbered:
    :maxdepth: 3
 
+   
    reference/classes/index
    reference/simulation/index
+   reference/export/index
    glossary

docs/whats_new/v0.1.rst

@@ -39,6 +39,8 @@ Changelog
 - |Feature| Add :class:`pywhy_graphs.networkx.MixedEdgeGraph` for mixed-edge graphs, by `Adam Li`_ (:pr:`29`)
 - |MajorFeature| Implement a series of graph classes for time-series graphs, such as ``pywhy_graphs.classes.timeseries.StationaryTimeSeriesMixedEdgeGraph``, by `Adam Li`_ (:pr:`21`)
 - |MajorFeature| Implement a series of graph classes for modeling interventions, such as :class:`pywhy_graphs.AugmentedGraph`, by `Adam Li`_ (:pr:`49`)
+- |Feature| Implement export/import functions to go to/from pywhy-graphs to causallearn and to/from pywhy-graphs to numpy, by `Adam Li`_ (:pr:`51`)
+- |Feature| Implement export/import functions to go to/from pywhy-graphs to pcalg and tetrad, by `Adam Li`_ (:pr:`60`)
 
 Code and Documentation Contributors
 -----------------------------------

pyproject.toml

@@ -108,8 +108,7 @@ _pydocstyle = 'pydocstyle .'
 _codespell = 'codespell pywhy_graphs/ doc/ examples/ --ignore-words=.codespellignore --skip "**/_build/*"'
 
 type_check = 'mypy -p pywhy_graphs --config-file pyproject.toml'
-unit_test = 'pytest ./pywhy_graphs ./integration_tests --cov=pywhy_graphs --cov-report=xml --cov-config=pyproject.toml'
-integration_test = 'pytest ./integration_tests'
+unit_test = 'pytest ./pywhy_graphs --cov=pywhy_graphs --cov-report=xml --cov-config=pyproject.toml'
 build_docs = 'make -C docs clean html'
 build_docs_noplot = 'make -C docs clean html-noplot'
 

pywhy_graphs/__init__.py

@@ -13,9 +13,9 @@
     StationaryTimeSeriesPAG,
 )
 from .algorithms import *  # noqa: F403
-from .array import export
 from .config import sys_info
 
+from . import export
 from . import classes
 from . import networkx
 from . import simulate