[ENH, GRAPH] Experimental: A module for time-series graphs that relies on only networkx, and simulation and algorithms for time-series (#21)

* Adding API for time series graph for dodiscover
* Adding new time-series graph
* Working time-series graphs with forward and backwards homologous edge removal
* Adding set max lag method
* Adding pds algorithms for time-series graphs
* Adding sys info

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

Author: adam2392

.circleci/config.yml

@@ -46,8 +46,8 @@ jobs:
       - run:
           name: Install the latest version of Poetry
           command: |
-            curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | POETRY_UNINSTALL=1 python -
-            curl -sSL https://install.python-poetry.org | python3 -
+            curl -sSL https://install.python-poetry.org | python3 - --version 1.3.0
+            poetry --version
       - run:
           name: Set BASH_ENV
           command: |
@@ -70,7 +70,7 @@ jobs:
           command: sudo apt update && sudo apt install -y pandoc optipng
       - python/install-packages:
           pkg-manager: poetry
-          cache-version: "v2" # change to clear cache
+          cache-version: "v1" # change to clear cache
           args: "--with docs"
       - run:
           name: Check poetry package versions
@@ -140,6 +140,7 @@ jobs:
       - python/install-packages:
           pkg-manager: poetry
           cache-version: "v1" # change to clear cache
+          args: "--with docs"
       - run:
           name: make linkcheck
           command: |

.github/workflows/main.yml

@@ -137,7 +137,7 @@ jobs:
         run: pip install poetry-dynamic-versioning
       - name: Install packages via poetry
         run: |
-          poetry install --with test
+          poetry install --with test,ts
       # TODO: uncomment, when MixedEdgeGraph PRed into networkx
       # - name: Install Networkx (main)
       #   if: "matrix.networkx == 'main'"

Makefile

@@ -12,11 +12,15 @@ Note: The API is subject to change without deprecation cycles due to the current
 
 ## Why?
 
-Representation of causal inference models in Python are severely lacking. Moreover, sampling from causal models is non-trivial. However, sampling from simulations is a requirement to benchmark different structural learning, causal ID, or other causal related algorithms.
+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.
+
+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.
+
 # Documentation
 
 See the [development version documentation](https://py-why.github.io/pywhy-graphs/dev/index.html).
@@ -47,9 +51,6 @@ To install the package from github, clone the repository and then `cd` into the
 
     poetry install
 
-    # for time-series graph functionality
-    poetry install --extras ts
-
     # for vizualizing graph functionality
     poetry install --extras viz
 

README.md

@@ -0,0 +1,5 @@
+{{ objname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

docs/_templates/autosummary/base.rst

@@ -13,8 +13,8 @@ for classes (``CamelCase`` names) and functions
 (``underscore_case`` names) of pywhy-graphs, grouped thematically by analysis
 stage.
 
-Most-used classes
-=================
+Causal graph classes
+====================
 These are the causal classes for Structural Causal Models (SCMs), or various causal
 graphs encountered in the literature. 
 
@@ -78,7 +78,21 @@ welcome feedback.
    MixedEdgeGraph
    bidirected_to_unobserved_confounder
    m_separated
-   
+
+Timeseries
+==========
+The following are useful functions that operate specifically on time-series graphs.
+
+.. currentmodule:: pywhy_graphs.classes.timeseries
+.. autosummary::
+   :toctree: generated/
+
+   complete_ts_graph
+   empty_ts_graph
+   get_summary_graph
+   has_homologous_edges
+   nodes_in_time_order
+
 Visualization of causal graphs
 ==============================
 Visualization of causal graphs is different compared to networkx because causal graphs
@@ -91,3 +105,14 @@ to perform modular visualization of nodes and edges.
    :toctree: generated/
 
    draw
+   timeseries_layout
+
+Utilities for debugging
+=======================
+.. currentmodule:: pywhy_graphs
+
+.. autosummary::
+   :toctree: generated/
+
+   sys_info
+

docs/api.rst

@@ -40,7 +40,7 @@
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-needs_sphinx = "4.0"
+needs_sphinx = "5.0"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -57,6 +57,7 @@
     "sphinx_gallery.gen_gallery",
     "sphinxcontrib.bibtex",
     "sphinx_copybutton",
+    # 'sphinx.ext.napoleon',
     "numpydoc",
     # "IPython.sphinxext.ipython_console_highlighting",
 ]
@@ -68,16 +69,21 @@
 # generate autosummary even if no references
 # -- sphinx.ext.autosummary
 autosummary_generate = True
-autodoc_default_options = {"inherited-members": None}
+autodoc_default_options = {
+    "inherited-members": None,
+}
+autodoc_inherit_docstrings = True
 # autodoc_typehints = "signature"
 
 # -- numpydoc
 # Below is needed to prevent errors
-numpydoc_xref_param_type = True
+# numpydoc_xref_param_type = True
+numpydoc_show_inherited_class_members = False
+numpydoc_show_class_members = False
 numpydoc_class_members_toctree = False
 numpydoc_attributes_as_param_list = True
 numpydoc_use_blockquotes = True
-numpydoc_validate = True
+# numpydoc_validate = True
 
 numpydoc_xref_ignore = {
     # words
@@ -108,13 +114,16 @@
     "no",
     "attributes",
     "dictionary",
-    "ArrayLike",
     "pywhy_nx.MixedEdgeGraph",
     # pywhy-graphs
     "causal",
     "Node",
     "circular",
     "endpoint",
+    "TsNode",
+    "tsdict",
+    "TimeSeriesGraph",
+    "TimeSeriesDiGraph",
     # networkx
     "node",
     "nodes",
@@ -136,6 +145,7 @@
     "Graph",
     "sets",
     "value",
+    'edges is None', 'nodes is None', 'G = nx.DiGraph(D)',
     # shapes
     "n_times",
     "obj",
@@ -159,12 +169,15 @@
     "nx.MultiDiGraph": "networkx.MultiDiGraph",
     "NetworkXError": "networkx.NetworkXError",
     "pgmpy.models.BayesianNetwork": "pgmpy.models.BayesianNetwork",
-    "ArrayLike": "numpy.ndarray",
+    "ArrayLike": "numpy.typing.ArrayLike",
     # pywhy-graphs
     "ADMG": "pywhy_graphs.ADMG",
     "PAG": "pywhy_graphs.PAG",
     "CPDAG": "pywhy_graphs.CPDAG",
     "pywhy_nx.MixedEdgeGraph": "pywhy_graphs.networkx.MixedEdgeGraph",
+    "TimeSeriesGraph": "pywhy_graphs.classes.timeseries.TimeSeriesGraph",
+    "TimeSeriesDiGraph": "pywhy_graphs.classes.timeseries.TimeSeriesDiGraph",
+    "TimeSeriesMixedEdgeGraph": "pywhy_graphs.classes.timeseries.TimeSeriesMixedEdgeGraph",
     # joblib
     "joblib.Parallel": "joblib.Parallel",
     # pandas
@@ -199,15 +212,18 @@
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
-    "numpy": ("https://numpy.org/devdocs", None),
-    "scipy": ("https://scipy.github.io/devdocs", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "neps": ("https://numpy.org/neps", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
     "networkx": ("https://networkx.org/documentation/latest/", None),
     "nx-guides": ("https://networkx.org/nx-guides/", None),
     "matplotlib": ("https://matplotlib.org/stable", None),
-    "pandas": ("https://pandas.pydata.org/pandas-docs/dev", None),
-    "pgmpy": ("https://pgmpy.org", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None),
     "sklearn": ("https://scikit-learn.org/stable", None),
     "joblib": ("https://joblib.readthedocs.io/en/latest", None),
+    "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),
 }
 intersphinx_timeout = 5
 
@@ -315,10 +331,23 @@
     ("py:obj", "networkx.MixedEdgeGraph"),
     ("py:obj", "pywhy_graphs.networkx.MixedEdgeGraph"),
     ("py:obj", "pywhy_nx.MixedEdgeGraph"),
+    ("py:class", "optional"),
+    ("py:class", "array"),
+    ("py:class", "pywhy_nx.classes.timeseries.TimeSeriesGraph"),
+    ("py:class", "pywhy_nx.classes.timeseries.TimeSeriesDiGraph"),
+    ("py:class", "pywhy_nx.classes.timeseries.TimeSeriesMixedEdgeGraph"),
+    ("py:class", "pywhy_nx.classes.timeseries.StationaryTimeSeriesGraph"),
+    ("py:class", "pywhy_nx.classes.timeseries.StationaryTimeSeriesDiGraph"),
+    ("py:class", "pywhy_nx.classes.timeseries.StationaryTimeSeriesMixedEdgeGraph"),
+    ("py:class", "pywhy_graphs.classes.timeseries.base.tsdict"),
     ("py:class", "networkx.classes.mixededge.MixedEdgeGraph"),
     ("py:class", "numpy._typing._array_like._SupportsArray"),
     ("py:class", "numpy._typing._nested_sequence._NestedSequence"),
 ]
+nitpick_ignore_regex = [
+    ('py:obj', r"pywhy_graphs\.classes\.timeseries*"),
+    ('py:obj', r"networkx*"),
+]
 
 
 # -- Warnings management -----------------------------------------------------

docs/conf.py

@@ -0,0 +1,59 @@
+.. _classes:
+
+***********
+Graph types
+***********
+
+Pywhy-graphs provides data structures and methods for storing causal graphs.
+
+The classes heavily rely on NetworkX and follows a similar API.
+
+The choice of graph class depends on the structure of the
+graph you want to represent.
+
+Which graph class should I use?
+===============================
+
++-------------------+----------------------------------+-----------------------+
+| Pywhy_graph Class | Edge Types                       | Latent confounders    |
++===================+==================================+=======================+
+| ADMG              | directed, bidirected, undirected | Yes                   |
++-------------------+------------+--------------------+------------------------+
+
+We also represent common equivalence classes of causal graphs.
+
++-------------------+----------------------------------+-----------------------+
+| Pywhy_graph Class | Edge Types                       | Latent confounders    |
++===================+==================================+=======================+
+| CPDAG             | directed, undirected             | No                    |
++-------------------+----------------------------------+-----------------------+
+| PAG               | directed, bidirected, undirected | Yes                   |
++-------------------+---------------------------------+------------------------+
+| MultiDiGraph      | directed   | Yes                | Yes                    |
++-------------------+------------+--------------------+------------------------+
+
+Causal graph types
+==================
+
+.. currentmodule:: pywhy_graphs.classes.timeseries
+.. autoclass:: TimeSeriesGraph
+    :inherited-members:
+.. autoclass:: TimeSeriesDiGraph
+    :inherited-members:
+.. autoclass:: TimeSeriesMixedEdgeGraph
+    :inherited-members:
+.. autoclass:: StationaryTimeSeriesCPDAG
+    :inherited-members:
+.. autoclass:: StationaryTimeSeriesDiGraph
+    :inherited-members:
+.. autoclass:: StationaryTimeSeriesGraph
+    :inherited-members:
+.. autoclass:: StationaryTimeSeriesMixedEdgeGraph
+    :inherited-members:
+.. autoclass:: StationaryTimeSeriesPAG
+    :inherited-members:
+
+.. note:: NetworkX uses `dicts` to store the nodes and neighbors in a graph.
+   So the reporting of nodes and edges for the base graph classes may not
+   necessarily be consistent across versions and platforms; however, the reporting
+   for CPython is consistent across platforms and versions after 3.6.

docs/reference/classes/index

@@ -36,6 +36,24 @@ @article{Gamez2011
   doi     = {10.1007/s10618-010-0178-6}
 }
 
+
+@InProceedings{Malinsky18a_svarfci,
+  title = 	 {Causal Structure Learning from Multivariate Time Series in Settings with Unmeasured Confounding},
+  author = 	 {Malinsky, Daniel and Spirtes, Peter},
+  booktitle = 	 {Proceedings of 2018 ACM SIGKDD Workshop on Causal Disocvery},
+  pages = 	 {23--47},
+  year = 	 {2018},
+  editor = 	 {Le, Thuc Duy and Zhang, Kun and Kıcıman, Emre and Hyvärinen, Aapo and Liu, Lin},
+  volume = 	 {92},
+  series = 	 {Proceedings of Machine Learning Research},
+  month = 	 {20 Aug},
+  publisher =    {PMLR},
+  pdf = 	 {http://proceedings.mlr.press/v92/malinsky18a/malinsky18a.pdf},
+  url = 	 {https://proceedings.mlr.press/v92/malinsky18a.html},
+  abstract = 	 {We present constraint-based and (hybrid) score-based algorithms for causal structure learning that estimate dynamic graphical models from multivariate time series data. In contrast to previous work, our methods allow for both “contemporaneous” causal relations and arbitrary unmeasured (“latent”) processes influencing observed variables. The performance of our algorithms is investigated with simulation experiments and we briefly illustrate the proposed approach on some real data from international political economy.}
+}
+
+
 @article{Meek1995,
   author  = {Meek, Christopher},
   year    = {2013},
@@ -168,6 +186,10 @@ @article{Zhang2008
   abstract = {Causal discovery becomes especially challenging when the possibility of latent confounding and/or selection bias is not assumed away. For this task, ancestral graph models are particularly useful in that they can represent the presence of latent confounding and selection effect, without explicitly invoking unobserved variables. Based on the machinery of ancestral graphs, there is a provably sound causal discovery algorithm, known as the FCI algorithm, that allows the possibility of latent confounders and selection bias. However, the orientation rules used in the algorithm are not complete. In this paper, we provide additional orientation rules, augmented by which the FCI algorithm is shown to be complete, in the sense that it can, under standard assumptions, discover all aspects of the causal structure that are uniquely determined by facts of probabilistic dependence and independence. The result is useful for developing any causal discovery and reasoning system based on ancestral graph models.}
 }
 
+@article{Zhang2008AncestralGraphs,
+  title    = {Causal Reasoning with Ancestral Graphs},
+}
+
 @inproceedings{Zhang2011,
   author    = {Zhang, Kun and Peters, Jonas and Janzing, Dominik and Sch\"{o}lkopf, Bernhard},
   title     = {Kernel-Based Conditional Independence Test and Application in Causal Discovery},

docs/references.bib

@@ -20,5 +20,5 @@
 .. |API| replace:: :raw-html:`<span class="badge badge-warning">API Change</span>` :raw-latex:`{\small\sc [API Change]}`
 
 
-.. _Adam Li: https://py-why.github.io
+.. _Adam Li: https://github.com/adam2392
 .. _Julien Siebert: https://github.com/siebert-julien