.. _api_ref:

###
API
###

:py:mod:`pywhy_graphs`:

.. automodule:: pywhy_graphs
   :no-members:
   :no-inherited-members:

This is the application programming interface (API) reference
for classes (``CamelCase`` names) and functions
(``underscore_case`` names) of pywhy-graphs, grouped thematically by analysis
stage.

:mod:`pywhy_graphs.classes`: Causal graph classes
=================================================
These are the causal classes for Structural Causal Models (SCMs), or various causal
graphs encountered in the literature. 

.. currentmodule:: pywhy_graphs

.. autosummary::
   :toctree: generated/

   ADMG
   CPDAG
   PAG
   AugmentedGraph
   AugmentedPAG

:mod:`pywhy_graphs.algorithms`: Algorithms for Mixed-Edge Graphs
================================================================
Traditional graph algorithms operate over graphs with only one type of edge.
Equivalence class graphs in causality generally consist of more than one type of
edge. These algorithms are common algorithms used in a variety of different
causal graph operations.

.. currentmodule:: pywhy_graphs.algorithms

.. autosummary::
   :toctree: generated/

   dag_to_mag
   valid_mag
   has_adc
   inducing_path
   is_valid_mec_graph
   possible_ancestors
   possible_descendants
   discriminating_path
   pds
   pds_path
   pds_t
   pds_t_path
   uncovered_pd_path
   acyclification
   is_definite_noncollider
   find_connected_pairs
   add_all_snode_combinations
   compute_invariant_domains_per_node
   is_semi_directed_path
   all_semi_directed_paths

:mod:`pywhy_graphs.algorithms`: Algorithms for dealing with CPDAGs
==================================================================
With Markov equivalence classes of DAGs in a Markovian SCM setting, we obtain
a potentially directed acyclic graph (PDAG), which may be completed (CPDAG).
We may want to generate a consistent DAG extension (i.e. Markov equivalent) of a CPDAG
then we may use some of the algorithms described here. Or perhaps one may want to 
convert a DAG to its corresponding CPDAG.

.. currentmodule:: pywhy_graphs.algorithms

.. autosummary::
   :toctree: generated/

   pdag_to_dag
   dag_to_cpdag
   pdag_to_cpdag
   order_edges
   label_edges
   

Conversions between other package's causal graphs
=================================================
Other packages, such as `causal-learn <https://github.com/cmu-phil/causal-learn>`_,
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.export

.. autosummary::
   :toctree: generated/

   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
===================================
Currently, NetworkX does not support mixed-edge graphs, which are crucial
for representing causality with latent confounders and selection bias. The
following represent functionality that we intend to PR eventually into
networkx. They are included in pywhy-graphs as a temporary bridge. We 
welcome feedback.

.. currentmodule:: pywhy_graphs.networkx
.. autosummary::
   :toctree: generated/
   
   MixedEdgeGraph
   bidirected_to_unobserved_confounder
   m_separated
   is_minimal_m_separator
   minimal_m_separator

:mod:`pywhy_graphs.classes.timeseries`: 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

We also have classes for representing causal time-series graphs.

Pywhy-graphs implements a networkx-like graph class for representing time-series.
Stationary causal timeseries graphs may be useful in various applications.

.. currentmodule:: pywhy_graphs.classes.timeseries
.. autosummary::
   :toctree: generated/
   
   TimeSeriesGraph
   TimeSeriesDiGraph
   TimeSeriesMixedEdgeGraph

For stationary time-series, we explicitly represent them with different classes.

.. autosummary::
   :toctree: generated/

   StationaryTimeSeriesCPDAG
   StationaryTimeSeriesDiGraph
   StationaryTimeSeriesGraph
   StationaryTimeSeriesMixedEdgeGraph
   StationaryTimeSeriesPAG

:mod:`pywhy_graphs.simulate`: Causal graphical model simulations
================================================================
Pywhy-graphs implements a various functions for assisting in simulating
a SCM and their data starting from the causal graph.

.. currentmodule:: pywhy_graphs

.. autosummary::
   :toctree: generated/

   simulate.simulate_linear_var_process
   simulate.simulate_data_from_var
   simulate.simulate_var_process_from_summary_graph

Converting graphs to functional models
======================================
An experimental submodule for converting graphs to functional models, such as
linear structural equation Gaussian models (SEMs).

.. currentmodule:: pywhy_graphs.functional

.. autosummary::
   :toctree: generated/

   make_graph_linear_gaussian
   apply_linear_soft_intervention
   set_node_attributes_with_G
   make_graph_multidomain

Visualization of causal graphs
==============================
Visualization of causal graphs is different compared to networkx because causal graphs
can consist of mixed-edges. We implement an API that wraps ``graphviz`` and ``pygraphviz``
to perform modular visualization of nodes and edges.

.. currentmodule:: pywhy_graphs.viz

.. autosummary::
   :toctree: generated/

   draw
   timeseries_layout

Utilities for debugging
=======================
.. currentmodule:: pywhy_graphs

.. autosummary::
   :toctree: generated/

   sys_info

Simulation
==========
.. toctree::
   :maxdepth: 1

   reference/simulation/index