This is GraphicalModels.info, produced by Macaulay2, version 1.21

GraphicalModels -- a package for discrete and Gaussian statistical graphical models
***********************************************************************************

Description
===========

Graphical Models is a package for algebraic statistics. It constructs ideals of
discrete and Gaussian graphical models. This package supersedes Markov.m2.

This package constructs ideals of discrete Bayesian networks (directed acyclic
graphs) as described in several places, including the paper: Luis David Garcia,
Michael Stillman and Bernd Sturmfels, The algebraic geometry of Bayesian
networks, J. Symbolic Comput., 39(3-4):331–355, 2005.

It also constructs ideals of Gaussian Bayesian networks and Gaussian graphical
models (graphs containing both directed and bidirected edges), as described in
the papers: Seth Sullivant, Algebraic geometry of Gaussian Bayesian networks,
Adv. in Appl. Math. 40 (2008), no. 4, 482–513; and Seth Sullivant, Kelli
Talaska and Jan Draisma, "Trek separation for Gaussian graphical models",
Annals of Statistics 38 no.3 (2010) 1665–1685.

The package also contains procedures to solve the identifiability problem for
Gaussian graphical models as described in the paper: Luis D. Garcia-Puente,
Sarah Spielvogel and Seth Sullivant, Identifying causal effects with computer
algebra, Proceedings of the $26^{th}$ Conference of Uncertainty in Artificial
Intelligence.

Furthermore, this package allows to construct the Gaussian rings of loopless
mixed graphs (LMG) and the corresponding matrices of indeterminates as
introduced in Kayvan Sadeghi and Steffen Lauritzen, Markov properties for mixed
graphs, Bernoulli 20.2 (2014): 676-696.

Here is a typical use of this package.  We create the ideal in 16 variables
whose zero set represents the probability distributions on four binary random
variables  satisfying the conditional independence statements coming from the
"diamond" graph $4 \to 3, 4 \to 2, 3 \to 1, 2 \to 1$.

+-----------------------------------------------------------------------------+
|i1 : G = digraph  {{1,{}},{2,{1}},{3,{1}},{4,{2,3}}}                         |
|                                                                             |
|o1 = Digraph{1 => {}    }                                                    |
|             2 => {1}                                                        |
|             3 => {1}                                                        |
|             4 => {2, 3}                                                     |
|                                                                             |
|o1 : Digraph                                                                 |
+-----------------------------------------------------------------------------+
|i2 : R = markovRing (2,2,2,2) -- this ring corresponds to four binary random |
|                                                                             |
|o2 = R                                                                       |
|                                                                             |
|o2 : PolynomialRing                                                          |
|-----------------------------------------------------------------------------|
|variables                                                                    |
+-----------------------------------------------------------------------------+
|i3 : S = globalMarkov G                                                      |
|                                                                             |
|o3 = {{{1}, {4}, {2, 3}}, {{2}, {3}, {4}}}                                   |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : I = conditionalIndependenceIdeal (R,S);                                 |
|                                                                             |
|o4 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i5 : netList I_*                                                             |
|                                                                             |
|     +-----------------------------------------------------------------------|
|o5 = |- p       p        + p       p                                         |
|     |   1,1,1,2 2,1,1,1    1,1,1,1 2,1,1,2                                  |
|     +-----------------------------------------------------------------------|
|     |- p       p        + p       p                                         |
|     |   1,1,2,2 2,1,2,1    1,1,2,1 2,1,2,2                                  |
|     +-----------------------------------------------------------------------|
|     |- p       p        + p       p                                         |
|     |   1,2,1,2 2,2,1,1    1,2,1,1 2,2,1,2                                  |
|     +-----------------------------------------------------------------------|
|     |- p       p        + p       p                                         |
|     |   1,2,2,2 2,2,2,1    1,2,2,1 2,2,2,2                                  |
|     +-----------------------------------------------------------------------|
|     |- p       p        + p       p        + p       p        - p       p   |
|     |   1,1,2,1 1,2,1,1    1,1,1,1 1,2,2,1    1,2,2,1 2,1,1,1    1,2,1,1 2,1|
|     +-----------------------------------------------------------------------|
|     |- p       p        + p       p        + p       p        - p       p   |
|     |   1,1,2,2 1,2,1,2    1,1,1,2 1,2,2,2    1,2,2,2 2,1,1,2    1,2,1,2 2,1|
|     +-----------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|     - p       p        - p       p        + p       p        + p       p    |
|,2,1    1,1,2,1 2,2,1,1    2,1,2,1 2,2,1,1    1,1,1,1 2,2,2,1    2,1,1,1 2,2,|
|-----------------------------------------------------------------------------|
|     - p       p        - p       p        + p       p        + p       p    |
|,2,2    1,1,2,2 2,2,1,2    2,1,2,2 2,2,1,2    1,1,1,2 2,2,2,2    2,1,1,2 2,2,|
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|---+                                                                         |
|   |                                                                         |
|   |                                                                         |
|---+                                                                         |
|   |                                                                         |
|   |                                                                         |
|---+                                                                         |
|   |                                                                         |
|   |                                                                         |
|---+                                                                         |
|   |                                                                         |
|   |                                                                         |
|---+                                                                         |
|   |                                                                         |
|2,1|                                                                         |
|---+                                                                         |
|   |                                                                         |
|2,2|                                                                         |
|---+                                                                         |
+-----------------------------------------------------------------------------+

Sometimes an ideal can be simplified by changing variables. For example,
conditional independence ideals are often transformed to binomial ideals by
using marginMap. This is the case here.

+-----------------------------------------------------------------------------+
|i6 : F = marginMap (1,R)                                                     |
|                                                                             |
|o6 = map (R, R, {p        - p       , p        - p       , p        -        |
|                  1,1,1,1    2,1,1,1   1,1,1,2    2,1,1,2   1,1,2,1          |
|                                                                             |
|o6 : RingMap R <--- R                                                        |
|-----------------------------------------------------------------------------|
|p       , p        - p       , p        - p       , p        - p       ,     |
| 2,1,2,1   1,1,2,2    2,1,2,2   1,2,1,1    2,2,1,1   1,2,1,2    2,2,1,2      |
|-----------------------------------------------------------------------------|
|p        - p       , p        - p       , p       , p       , p       ,      |
| 1,2,2,1    2,2,2,1   1,2,2,2    2,2,2,2   2,1,1,1   2,1,1,2   2,1,2,1       |
|-----------------------------------------------------------------------------|
|p       , p       , p       , p       , p       })                           |
| 2,1,2,2   2,2,1,1   2,2,1,2   2,2,2,1   2,2,2,2                             |
+-----------------------------------------------------------------------------+
|i7 : J = F I;                                                                |
|                                                                             |
|o7 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i8 : netList J_*                                                             |
|                                                                             |
|     +-------------------------------------+                                 |
|o8 = |- p       p        + p       p       |                                 |
|     |   1,1,1,2 2,1,1,1    1,1,1,1 2,1,1,2|                                 |
|     +-------------------------------------+                                 |
|     |- p       p        + p       p       |                                 |
|     |   1,1,2,2 2,1,2,1    1,1,2,1 2,1,2,2|                                 |
|     +-------------------------------------+                                 |
|     |- p       p        + p       p       |                                 |
|     |   1,2,1,2 2,2,1,1    1,2,1,1 2,2,1,2|                                 |
|     +-------------------------------------+                                 |
|     |- p       p        + p       p       |                                 |
|     |   1,2,2,2 2,2,2,1    1,2,2,1 2,2,2,2|                                 |
|     +-------------------------------------+                                 |
|     |- p       p        + p       p       |                                 |
|     |   1,1,2,1 1,2,1,1    1,1,1,1 1,2,2,1|                                 |
|     +-------------------------------------+                                 |
|     |- p       p        + p       p       |                                 |
|     |   1,1,2,2 1,2,1,2    1,1,1,2 1,2,2,2|                                 |
|     +-------------------------------------+                                 |
+-----------------------------------------------------------------------------+

This ideal has 5 primary components.  The first component is the one that has
statistical significance. It is the defining ideal of the variety parameterized
by the the factorization of the probability distributions according to the
graph $G$. The remaining components lie on the boundary of the simplex.

+-----------------------------------------------------------------------------+
|i9 : netList primaryDecomposition J                                          |
|                                                                             |
|     +-----------------------------------------------------------------------|
|o9 = |ideal (p       , p       , p       , p       , p       p        - p    |
|     |        1,2,2,2   1,2,2,1   1,2,1,2   1,2,1,1   1,1,2,2 2,1,2,1    1,1,|
|     +-----------------------------------------------------------------------|
|     |ideal (p       , p       , p       , p       , p       p        - p    |
|     |        1,2,2,2   1,2,2,1   1,1,2,2   1,1,2,1   1,2,1,2 2,2,1,1    1,2,|
|     +-----------------------------------------------------------------------|
|     |ideal (p       , p       , p       , p       , p       p        - p    |
|     |        1,2,1,2   1,2,1,1   1,1,1,2   1,1,1,1   1,2,2,2 2,2,2,1    1,2,|
|     +-----------------------------------------------------------------------|
|     |ideal (p       , p       , p       , p       , p       p        - p    |
|     |        1,1,2,2   1,1,2,1   1,1,1,2   1,1,1,1   1,2,2,2 2,2,2,1    1,2,|
|     +-----------------------------------------------------------------------|
|     |ideal (p       p        - p       p       , p       p        - p       |
|     |        1,2,2,2 2,2,2,1    1,2,2,1 2,2,2,2   1,2,1,2 2,2,1,1    1,2,1,1|
|     +-----------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|   p       , p       p        - p       p       )                            |
|2,1 2,1,2,2   1,1,1,2 2,1,1,1    1,1,1,1 2,1,1,2                             |
|-----------------------------------------------------------------------------|
|   p       , p       p        - p       p       )                            |
|1,1 2,2,1,2   1,1,1,2 2,1,1,1    1,1,1,1 2,1,1,2                             |
|-----------------------------------------------------------------------------|
|   p       , p       p        - p       p       )                            |
|2,1 2,2,2,2   1,1,2,2 2,1,2,1    1,1,2,1 2,1,2,2                             |
|-----------------------------------------------------------------------------|
|   p       , p       p        - p       p       )                            |
|2,1 2,2,2,2   1,2,1,2 2,2,1,1    1,2,1,1 2,2,1,2                             |
|-----------------------------------------------------------------------------|
|p       , p       p        - p       p       , p       p        - p       p  |
| 2,2,1,2   1,1,2,2 2,1,2,1    1,1,2,1 2,1,2,2   1,1,1,2 2,1,1,1    1,1,1,1 2,|
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|     , p       p        - p       p       , p       p        - p       p     |
|1,1,2   1,1,2,2 1,2,1,2    1,1,1,2 1,2,2,2   1,1,2,1 1,2,1,1    1,1,1,1 1,2,2|
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|  , p       p       p       p        - p       p       p       p       , p   |
|,1   2,1,1,1 2,1,2,2 2,2,1,2 2,2,2,1    2,1,1,2 2,1,2,1 2,2,1,1 2,2,2,2   1,1|
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|    p       p       p        - p       p       p       p       , p       p   |
|,1,1 2,1,2,2 2,2,1,2 2,2,2,1    1,1,1,2 2,1,2,1 2,2,1,1 2,2,2,2   1,1,2,2 2,1|
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|    p       p        - p       p       p       p       , p       p       p   |
|,1,1 2,2,1,2 2,2,2,1    1,1,2,1 2,1,1,2 2,2,1,1 2,2,2,2   1,1,1,1 1,1,2,2 2,2|
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|    p        - p       p       p       p       , p       p       p       p   |
|,1,2 2,2,2,1    1,1,1,2 1,1,2,1 2,2,1,1 2,2,2,2   1,2,1,2 2,1,1,1 2,1,2,2 2,2|
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|     - p       p       p       p       , p       p       p       p        - p|
|,2,1    1,2,1,1 2,1,1,2 2,1,2,1 2,2,2,2   1,1,1,1 1,2,1,2 2,1,2,2 2,2,2,1    |
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|       p       p       p       , p       p       p       p        - p       p|
|1,1,1,2 1,2,1,1 2,1,2,1 2,2,2,2   1,2,2,2 2,1,1,2 2,1,2,1 2,2,1,1    1,2,2,1 |
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|       p       p       , p       p       p       p        - p       p       p|
|2,1,1,1 2,1,2,2 2,2,1,2   1,1,2,1 1,2,2,2 2,1,1,2 2,2,1,1    1,1,2,2 1,2,2,1 |
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|       p       , p       p       p       p        - p       p       p       p|
|2,1,1,1 2,2,1,2   1,2,1,1 1,2,2,2 2,1,1,2 2,1,2,1    1,2,1,2 1,2,2,1 2,1,1,1 |
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|--------+                                                                    |
|        |                                                                    |
|        |                                                                    |
|--------+                                                                    |
|        |                                                                    |
|        |                                                                    |
|--------+                                                                    |
|        |                                                                    |
|        |                                                                    |
|--------+                                                                    |
|        |                                                                    |
|        |                                                                    |
|--------+                                                                    |
|       )|                                                                    |
|2,1,2,2 |                                                                    |
|--------+                                                                    |
+-----------------------------------------------------------------------------+

The ideal in the next example corresponds to a Gaussian graphical model on a
graph with directed and bidirected edges. The method trekIdeal,
computes the ideal based on the trek separation statements of the
mixed graph.

+------------------------------------------------------------------+
|i10 : G = mixedGraph (digraph {{b,{c,d}},{c,{d}}},bigraph {{a,d}})|
|                                                                  |
|o10 = MixedGraph{Bigraph => Bigraph{a => {d}}   }                 |
|                                    d => {a}                      |
|                 Digraph => Digraph{b => {c, d}}                  |
|                                    c => {d}                      |
|                                    d => {}                       |
|                 Graph => Graph{}                                 |
|                                                                  |
|o10 : MixedGraph                                                  |
+------------------------------------------------------------------+
|i11 : R = gaussianRing G                                          |
|                                                                  |
|o11 = R                                                           |
|                                                                  |
|o11 : PolynomialRing                                              |
+------------------------------------------------------------------+
|i12 : J = trekIdeal (R,G);                                        |
|                                                                  |
|o12 : Ideal of R                                                  |
+------------------------------------------------------------------+
|i13 : J / print;                                                  |
|s                                                                 |
| a,b                                                              |
|s                                                                 |
| a,c                                                              |
|- s   s    + s   s                                                |
|   a,c b,b    a,b b,c                                             |
|- s   s    + s   s                                                |
|   a,c b,b    a,b b,c                                             |
|- s   s    + s   s                                                |
|   a,c b,c    a,b c,c                                             |
|s   s    - s   s                                                  |
| a,c b,d    a,b c,d                                               |
+------------------------------------------------------------------+

The following ideal corresponds to a set of conditional statements of 5
Gaussian random variables.

+-----------------------------------------------------------------------------+
|i14 : R=gaussianRing 5                                                       |
|                                                                             |
|o14 = R                                                                      |
|                                                                             |
|o14 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i15 : S={{{1},{2},{3,4}}, {{2,3},{1},{5}}}                                   |
|                                                                             |
|o15 = {{{1}, {2}, {3, 4}}, {{2, 3}, {1}, {5}}}                               |
|                                                                             |
|o15 : List                                                                   |
+-----------------------------------------------------------------------------+
|i16 : I=conditionalIndependenceIdeal (R,S);                                  |
|                                                                             |
|o16 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i17 : I / print;                                                             |
|                                                    2                        |
|- s   s   s    + s   s   s    + s   s   s    - s   s    - s   s   s    +     |
|   1,4 2,4 3,3    1,4 2,3 3,4    1,3 2,4 3,4    1,2 3,4    1,3 2,3 4,4       |
|- s   s    + s   s                                                           |
|   1,3 2,5    1,2 3,5                                                        |
|- s   s    + s   s                                                           |
|   1,5 2,5    1,2 5,5                                                        |
|- s   s    + s   s                                                           |
|   1,5 3,5    1,3 5,5                                                        |
|-----------------------------------------------------------------------------|
|s   s   s                                                                    |
| 1,2 3,3 4,4                                                                 |
+-----------------------------------------------------------------------------+

The following people have generously contributed their time and effort to this
project:

Alexander Diaz,

Shaowei Lin<http://math.berkeley.edu/~shaowei/>,

David Murrugarra<http://people.math.gatech.edu/~davidmur/Home.html>.

Caveat
======

GraphicalModels requires Graphs.m2 and StatGraphs.m2. These packages allow the
user to create graphs whose vertices are labeled arbitrarily. However, several
functions in GraphicalModels sort the vertices of the graph. Hence, graphs used
as input to methods in GraphicalModels must have sortable vertex labels, e.g.,
all numbers or all letters.

The methods in GraphicalModels differ in the classes of acceptable graphs for
input:

- functions used in package GraphicalModelsMLE (see gaussianRing,
see covarianceMatrix,
bidirectedEdgesMatrix, directedEdgesMatrix,
see directedEdgesMatrix,
undirectedEdgesMatrix) and
conditionalIndependenceIdeal, accept Graph (Graphs),
see Digraph (Graphs), Bigraph (StatGraphs),
and MixedGraph (StatGraphs).

- conditional independence statement generators (see pairMarkov,
localMarkov, and globalMarkov) accept
only Graph (Graphs), or Digraph (Graphs),;

- the remaining functions that accepts graphs, only accept Graph (Graphs),
see Digraph (Graphs), or MixedGraph (StatGraphs),
without undirected edges.

Authors
=======

  * Carlos Amendola (see http://www.carlos-amendola.com/ )
    <carlos.amendola@tum.de>
  * Luis David Garcia Puente (see http://www.shsu.edu/~ldg005 )
    <lgarcia@shsu.edu>
  * Roser Homs Pons (see https://personal-homepages.mis.mpg.de/homspons/index.
    html ) <roser.homs@tum.de>
  * Olga Kuznetsova (see https://okuznetsova.com ) <kuznetsova.olga@gmail.com>
  * Harshit J Motwani (see https://sites.google.com/view/harshitjmotwani/home )
    <harshitmotwani2015@gmail.com>
  * Sonja Petrovic (see http://www.personal.psu.edu/sxp61 ) <sonja@psu.edu>
  * Mike Stillman (see http://www.math.cornell.edu/~mike/ )
    <mike@math.cornell.edu>
  * Seth Sullivant (see http://www4.ncsu.edu/~smsulli2/ ) <smsulli2@ncsu.edu>

Certification a gold star
=========================

Version 1.0 of this package was accepted for publication in volume 5 (see
http://j-sag.org/Volume5/ ) of The Journal of Software for Algebra and Geometry
(see http://j-sag.org/ ) on 2013-03-05, in the article Graphical Models (see
http://j-sag.org/Volume5/jsag-1-2013.pdf ). That version can be obtained from
the journal (see http://j-sag.org/Volume5/GraphicalModels.m2 ) or from the
Macaulay2 source code repository (see
http://github.com/Macaulay2/M2/blob/68f41d641fadb0a1054023432eb60177f1d7cbd9/M2
/Macaulay2/packages/GraphicalModels.m2 ).

Version
=======

This documentation describes version 2.0 of GraphicalModels.

Source code
===========

The source code from which this documentation is derived is in the file
GraphicalModels.m2 (see common/share/Macaulay2/GraphicalModels.m2 ).

Exports
=======

  * Functions and commands
      * bidirectedEdgesMatrix -- matrix
        corresponding to the bidirected edges of a bigraph or a mixed graph
      * conditionalIndependenceIdeal, --
        ideal of a list of conditional independent statements
      * covarianceMatrix -- covariance matrix of a
        Gaussian graphical model
      * directedEdgesMatrix -- matrix corresponding
        to the directed edges of a digraph or a mixed graph
      * discreteVanishingIdeal -- vanishing
        ideal of a discrete graphical model
      * gaussianMatrices -- matrices whose minors
        generate the Gaussian conditional independence ideal
      * gaussianParametrization, --
        parametrization of the covariance matrix in terms of treks
      * gaussianRing -- ring of Gaussian correlations on n
        random variables or a graphical model
      * gaussianVanishingIdeal -- vanishing
        ideal of a Gaussian graphical model
      * globalMarkov -- global Markov statements for a
        graph or a directed graph
      * hiddenMap -- linear map between the ring of a model
        with one hidden variable and the ring of the corresponding fully
        observed model
      * identifyParameters -- solve the
        identifiability problem for Gaussian graphical models
      * inverseMarginMap -- inverse of the marginMap
      * localMarkov -- local Markov statements for a graph
        or a directed graph
      * marginMap -- linear map on joint distributions for
        discrete random variables replacing marginals for indeterminates
      * markovMatrices -- matrices whose minors form the
        ideal of a list of independence statements
      * markovRing -- ring of joint probability
        distributions on several discrete random variables
      * pairMarkov -- pairwise Markov statements for a graph
        or a  directed graph
      * trekIdeal -- trek separation ideal of a mixed graph
      * trekSeparation -- trek separation statements of
        a mixed graph
      * undirectedEdgesMatrix -- matrix
        corresponding to the edges of an undirected graph
  * Methods
      * "bidirectedEdgesMatrix(Ring)" -- see bidirectedEdgesMatrix,
        -- matrix corresponding to the bidirected edges
        of a bigraph or a mixed graph
      * "conditionalIndependenceIdeal(Ring,List)" -- see
        conditionalIndependenceIdeal, -- ideal of
        a list of conditional independent statements
      * "conditionalIndependenceIdeal(Ring,List,List)" -- see
        conditionalIndependenceIdeal, -- ideal of
        a list of conditional independent statements
      * "covarianceMatrix(Ring)" -- see covarianceMatrix,
        -- covariance matrix of a Gaussian graphical model
      * "directedEdgesMatrix(Ring)" -- see directedEdgesMatrix,
        -- matrix corresponding to the directed edges of a
        digraph or a mixed graph
      * "discreteVanishingIdeal(Ring,Digraph)" -- see
        discreteVanishingIdeal, -- vanishing ideal of a
        discrete graphical model
      * "gaussianMatrices(Ring,List)" -- see gaussianMatrices,
        -- matrices whose minors generate the Gaussian
        conditional independence ideal
      * "gaussianParametrization(Ring)" -- see gaussianParametrization,
        -- parametrization of the covariance matrix in
        terms of treks
      * gaussianRing(Bigraph) -- ring of
        Gaussian correlations of a graphical model coming from a bigraph
      * gaussianRing(Digraph) -- ring of
        Gaussian correlations of a graphical model coming from a digraph
      * gaussianRing(Graph) -- ring of Gaussian
        correlations of a graphical model coming from an undirected graph
      * gaussianRing(MixedGraph) -- ring
        of Gaussian correlations of a graphical model coming from a mixed graph
      * gaussianRing(ZZ) -- ring of Gaussian
        correlations on n random variables
      * "gaussianVanishingIdeal(Ring)" -- see gaussianVanishingIdeal,
        -- vanishing ideal of a Gaussian graphical
        model
      * "globalMarkov(Digraph)" -- see globalMarkov, --
        global Markov statements for a graph or a directed graph
      * "globalMarkov(Graph)" -- see globalMarkov, --
        global Markov statements for a graph or a directed graph
      * "hiddenMap(ZZ,Ring)" -- see hiddenMap, -- linear map
        between the ring of a model with one hidden variable and the ring of
        the corresponding fully observed model
      * "identifyParameters(Ring)" -- see identifyParameters,
        -- solve the identifiability problem for Gaussian
        graphical models
      * "inverseMarginMap(ZZ,Ring)" -- see inverseMarginMap,
        -- inverse of the marginMap
      * "localMarkov(Digraph)" -- see localMarkov, -- local
        Markov statements for a graph or a directed graph
      * "localMarkov(Graph)" -- see localMarkov, -- local
        Markov statements for a graph or a directed graph
      * "marginMap(ZZ,Ring)" -- see marginMap, -- linear map
        on joint distributions for discrete random variables replacing
        marginals for indeterminates
      * "markovMatrices(Ring,List)" -- see markovMatrices,
        -- matrices whose minors form the ideal of a list of
        independence statements
      * "markovMatrices(Ring,List,List)" -- see markovMatrices,
        -- matrices whose minors form the ideal of a list of
        independence statements
      * "markovRing(Sequence)" -- see markovRing, -- ring of
        joint probability distributions on several discrete random variables
      * "pairMarkov(Digraph)" -- see pairMarkov, -- pairwise
        Markov statements for a graph or a  directed graph
      * "pairMarkov(Graph)" -- see pairMarkov, -- pairwise
        Markov statements for a graph or a  directed graph
      * "trekIdeal(Ring,Digraph)" -- see trekIdeal, -- trek
        separation ideal of a mixed graph
      * "trekIdeal(Ring,Graph)" -- see trekIdeal, -- trek
        separation ideal of a mixed graph
      * "trekIdeal(Ring,MixedGraph)" -- see trekIdeal, -- trek
        separation ideal of a mixed graph
      * "trekSeparation(MixedGraph)" -- see trekSeparation,
        -- trek separation statements of a mixed graph
      * "undirectedEdgesMatrix(Ring)" -- see undirectedEdgesMatrix,
        -- matrix corresponding to the edges of an
        undirected graph
  * Symbols
      * Coefficients -- optional input to choose the base
        field
      * compU -- key in hash table gaussianRingData: component of
        undirected edges in vertex set of a mixed graph
      * compW -- key in hash table gaussianRingData: component of
        bidirected edges in vertex set of a mixed graph
      * gaussianRingData -- hash table with main
        parameters of a gaussian ring
      * graphType -- class of graph used to generate a
        gaussian ring
      * kVar -- key in hash table gaussianRingData: labels of k
        variables
      * kVariableName -- optional input to choose the
        variable names for concentration matrix in gaussianRing
      * lVar -- key in hash table gaussianRingData: labels of l
        variables
      * lVariableName -- optional input to choose the
        variable names for the regression matrix
      * nn -- key in hash table gaussianRingData: total number of
        variables
      * OldVersion -- optional argument in
        gaussianVanishingIdeal to use old method for gaussianRings coming from
        directed graphs
      * pVar -- key in hash table gaussianRingData: labels of p
        variables
      * pVariableName -- optional input to choose the
        variable names for the covariance matrix of the error terms
      * SimpleTreks -- optional input for
        gaussianParametrization
      * sVar -- key in hash table gaussianRingData: labels of s
        variables
      * sVariableName -- optional input to choose the
        variable names for the covariance matrix
      * VariableName -- optional input to choose
        indeterminate name in markovRing

For the programmer
==================

The object GraphicalModels, is a package (Macaulay2Doc).

bidirectedEdgesMatrix -- matrix corresponding to the bidirected edges of a bigraph or a mixed graph
***************************************************************************************************

Synopsis
========

  * Usage:
        bidirectedEdgesMatrix R
  * Inputs:
      * R, a ring (Macaulay2Doc), which should be a gaussianRing
        created with an instance of the type Bigraph (StatGraphs),
        or an instance of the type MixedGraph (StatGraphs),
  * Outputs:
      * a matrix (Macaulay2Doc), the $n \times{} n$ covariance
        matrix of the noise variables in the Gaussian graphical model of a
        mixed graph.

Description
===========

This method returns the $n \times{} n$ covariance matrix of the noise variables
in the Gaussian graphical model. The diagonal in this matrix consists of the
indeterminates  $p_{(i,i)}$. Each off-diagonal entry is zero unless there is a
bidirected edge between i and j in which case the corresponding entry in the
matrix is the indeterminate $p_{(i,j)}$. The documentation of
gaussianRing, further describes the indeterminates $p_{(i,j)}$.

+----------------------------------------------------------------+
|i1 : G = mixedGraph(digraph {{b,{c,d}},{c,{d}}},bigraph {{a,d}})|
|                                                                |
|o1 = MixedGraph{Bigraph => Bigraph{a => {d}}   }                |
|                                   d => {a}                     |
|                Digraph => Digraph{b => {c, d}}                 |
|                                   c => {d}                     |
|                                   d => {}                      |
|                Graph => Graph{}                                |
|                                                                |
|o1 : MixedGraph                                                 |
+----------------------------------------------------------------+
|i2 : R = gaussianRing G                                         |
|                                                                |
|o2 = R                                                          |
|                                                                |
|o2 : PolynomialRing                                             |
+----------------------------------------------------------------+
|i3 : compactMatrixForm =false;                                  |
+----------------------------------------------------------------+
|i4 : bidirectedEdgesMatrix R                                    |
|                                                                |
|o4 = |  p       0     0   p     |                               |
|     |   a,a               a,d  |                               |
|     |                          |                               |
|     |    0   p       0     0   |                               |
|     |         b,b              |                               |
|     |                          |                               |
|     |    0     0   p       0   |                               |
|     |               c,c        |                               |
|     |                          |                               |
|     |  p       0     0   p     |                               |
|     |   a,d               d,d  |                               |
|                                                                |
|             4       4                                          |
|o4 : Matrix R  <--- R                                           |
+----------------------------------------------------------------+

For mixed graphs that also have undirected edges, the size of the matrix
coincides with the number of elements in compW, which depends on
the vertex partition built in partitionLMG (StatGraphs).

+-------------------------------------------------------------------------+
|i5 : G = mixedGraph(digraph {{1,3},{2,4}},bigraph {{3,4}},graph {{1,2}});|
+-------------------------------------------------------------------------+
|i6 : R = gaussianRing G                                                  |
|                                                                         |
|o6 = R                                                                   |
|                                                                         |
|o6 : PolynomialRing                                                      |
+-------------------------------------------------------------------------+
|i7 : bidirectedEdgesMatrix R                                             |
|                                                                         |
|o7 = |  p     p     |                                                    |
|     |   3,3   3,4  |                                                    |
|     |              |                                                    |
|     |  p     p     |                                                    |
|     |   3,4   4,4  |                                                    |
|                                                                         |
|             2       2                                                   |
|o7 : Matrix R  <--- R                                                    |
+-------------------------------------------------------------------------+

Bidirected graphs can also be considered:

+----------------------------------+
|i8 : G = bigraph {{a,d},{b},{c}}  |
|                                  |
|o8 = Bigraph{a => {d}}            |
|             b => {}              |
|             c => {}              |
|             d => {a}             |
|                                  |
|o8 : Bigraph                      |
+----------------------------------+
|i9 : R = gaussianRing G           |
|                                  |
|o9 = R                            |
|                                  |
|o9 : PolynomialRing               |
+----------------------------------+
|i10 : bidirectedEdgesMatrix R     |
|                                  |
|o10 = |  p       0     0   p     ||
|      |   a,a               a,d  ||
|      |                          ||
|      |    0   p       0     0   ||
|      |         b,b              ||
|      |                          ||
|      |    0     0   p       0   ||
|      |               c,c        ||
|      |                          ||
|      |  p       0     0   p     ||
|      |   a,d               d,d  ||
|                                  |
|              4       4           |
|o10 : Matrix R  <--- R            |
+----------------------------------+

See also
========

  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model
  * gaussianParametrization -- parametrization
    of the covariance matrix in terms of treks
  * covarianceMatrix -- covariance matrix of a
    Gaussian graphical model
  * directedEdgesMatrix -- matrix corresponding to
    the directed edges of a digraph or a mixed graph

Ways to use bidirectedEdgesMatrix :
===================================

  * "bidirectedEdgesMatrix(Ring)"

For the programmer
==================

The object bidirectedEdgesMatrix, is a
method function (Macaulay2Doc).

Coefficients -- optional input to choose the base field
*******************************************************

Description
===========

Put Coefficients => r for a choice of ring(field) r as an argument in the
function markovRing, or gaussianRing,

See also
========

  * markovRing -- ring of joint probability distributions on
    several discrete random variables
  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model

Functions with optional argument named Coefficients :
=====================================================

  * "gaussianRing(...,Coefficients=>...)" -- see
    markovRing(...,Coefficients=>...),
    -- optional input to
    choose the base field in markovRing or gaussianRing
  * markovRing(...,Coefficients=>...)
    -- optional input to
    choose the base field in markovRing or gaussianRing

For the programmer
==================

The object Coefficients, is a symbol (Macaulay2Doc).

compU -- key in hash table gaussianRingData: component of undirected edges in vertex set of a mixed graph
*********************************************************************************************************

Description
===========

This key is present in every gaussianRingData that comes from a graph of class
MixedGraph (StatGraphs). It is equal to the set of vertices
that are incident to undirected edges. For more details, check component U in
partitionLMG (StatGraphs).

+---------------------------------------+
|i1 : U = graph {{1,2},{2,3}}           |
|                                       |
|o1 = Graph{1 => {2}   }                |
|           2 => {1, 3}                 |
|           3 => {2}                    |
|                                       |
|o1 : Graph                             |
+---------------------------------------+
|i2 : B = bigraph{{4,5}}                |
|                                       |
|o2 = Bigraph{4 => {5}}                 |
|             5 => {4}                  |
|                                       |
|o2 : Bigraph                           |
+---------------------------------------+
|i3 : D = digraph {{1,4}}               |
|                                       |
|o3 = Digraph{1 => {4}}                 |
|             4 => {}                   |
|                                       |
|o3 : Digraph                           |
+---------------------------------------+
|i4 : R = gaussianRing mixedGraph(U,B,D)|
|                                       |
|o4 = R                                 |
|                                       |
|o4 : PolynomialRing                    |
+---------------------------------------+
|i5 : R.gaussianRingData                |
|                                       |
|o5 = HashTable{compU => {1, 2, 3}}     |
|               compW => {4, 5}         |
|               kVar => k               |
|               lVar => l               |
|               nn => 5                 |
|               pVar => p               |
|               sVar => s               |
|                                       |
|o5 : HashTable                         |
+---------------------------------------+

Since the gaussian rings of graphs of classes Digraph (Graphs),
and Bigraph (StatGraphs), are created by first changing the class
to  MixedGraph (StatGraphs), the key compU is also present in
the gaussianRingData hashtables of these two classes of graphs and the
corresponding value is computed according to the rules described in
partitionLMG (StatGraphs).

+--------------------------------+
|i6 : U = graph {{1,2},{2,3}}    |
|                                |
|o6 = Graph{1 => {2}   }         |
|           2 => {1, 3}          |
|           3 => {2}             |
|                                |
|o6 : Graph                      |
+--------------------------------+
|i7 : B = bigraph{{4,5}}         |
|                                |
|o7 = Bigraph{4 => {5}}          |
|             5 => {4}           |
|                                |
|o7 : Bigraph                    |
+--------------------------------+
|i8 : D = digraph {{1,4}}        |
|                                |
|o8 = Digraph{1 => {4}}          |
|             4 => {}            |
|                                |
|o8 : Digraph                    |
+--------------------------------+
|i9 : R1 = gaussianRing B        |
|                                |
|o9 = R1                         |
|                                |
|o9 : PolynomialRing             |
+--------------------------------+
|i10 : R2 = gaussianRing D       |
|                                |
|o10 = R2                        |
|                                |
|o10 : PolynomialRing            |
+--------------------------------+
|i11 : R1.gaussianRingData       |
|                                |
|o11 = HashTable{compU => {}    }|
|                compW => {4, 5} |
|                kVar => k       |
|                lVar => l       |
|                nn => 2         |
|                pVar => p       |
|                sVar => s       |
|                                |
|o11 : HashTable                 |
+--------------------------------+
|i12 : R2.gaussianRingData       |
|                                |
|o12 = HashTable{compU => {}    }|
|                compW => {1, 4} |
|                kVar => k       |
|                lVar => l       |
|                nn => 2         |
|                pVar => p       |
|                sVar => s       |
|                                |
|o12 : HashTable                 |
+--------------------------------+

See also
========

  * partitionLMG (StatGraphs) -- partition the vertices of
    a loopless mixed graph into adjacent to undirected edges and adjacent to
    bidirected edges
  * gaussianRingData -- hash table with main
    parameters of a gaussian ring
  * kVar -- key in hash table gaussianRingData: labels of k
    variables
  * pVar -- key in hash table gaussianRingData: labels of p
    variables
  * sVar -- key in hash table gaussianRingData: labels of s
    variables
  * lVar -- key in hash table gaussianRingData: labels of l
    variables
  * compW -- key in hash table gaussianRingData: component of
    bidirected edges in vertex set of a mixed graph
  * nn -- key in hash table gaussianRingData: total number of
    variables

For the programmer
==================

The object compU, is a symbol (Macaulay2Doc).

compW -- key in hash table gaussianRingData: component of bidirected edges in vertex set of a mixed graph
*********************************************************************************************************

Description
===========

This key is present in every gaussianRingData that comes from a graph of class
MixedGraph (StatGraphs). It is equal to the set of vertices
that are incident to bidirected edges. For more details, check component W in
partitionLMG (StatGraphs).

+---------------------------------------+
|i1 : U = graph {{1,2},{2,3}}           |
|                                       |
|o1 = Graph{1 => {2}   }                |
|           2 => {1, 3}                 |
|           3 => {2}                    |
|                                       |
|o1 : Graph                             |
+---------------------------------------+
|i2 : B = bigraph{{4,5}}                |
|                                       |
|o2 = Bigraph{4 => {5}}                 |
|             5 => {4}                  |
|                                       |
|o2 : Bigraph                           |
+---------------------------------------+
|i3 : D = digraph {{1,4}}               |
|                                       |
|o3 = Digraph{1 => {4}}                 |
|             4 => {}                   |
|                                       |
|o3 : Digraph                           |
+---------------------------------------+
|i4 : R = gaussianRing mixedGraph(U,B,D)|
|                                       |
|o4 = R                                 |
|                                       |
|o4 : PolynomialRing                    |
+---------------------------------------+
|i5 : R.gaussianRingData                |
|                                       |
|o5 = HashTable{compU => {1, 2, 3}}     |
|               compW => {4, 5}         |
|               kVar => k               |
|               lVar => l               |
|               nn => 5                 |
|               pVar => p               |
|               sVar => s               |
|                                       |
|o5 : HashTable                         |
+---------------------------------------+

Since the gaussian rings of graphs of classes Digraph (Graphs),
and Bigraph (StatGraphs), are created by first changing the class
to  MixedGraph (StatGraphs), the key compW is also present in
the gaussianRingData hashtables of these two classes of graphs and the
corresponding value is computed according to the rules described in
partitionLMG (StatGraphs).

+--------------------------------+
|i6 : U = graph {{1,2},{2,3}}    |
|                                |
|o6 = Graph{1 => {2}   }         |
|           2 => {1, 3}          |
|           3 => {2}             |
|                                |
|o6 : Graph                      |
+--------------------------------+
|i7 : B = bigraph{{4,5}}         |
|                                |
|o7 = Bigraph{4 => {5}}          |
|             5 => {4}           |
|                                |
|o7 : Bigraph                    |
+--------------------------------+
|i8 : D = digraph {{1,4}}        |
|                                |
|o8 = Digraph{1 => {4}}          |
|             4 => {}            |
|                                |
|o8 : Digraph                    |
+--------------------------------+
|i9 : R1 = gaussianRing B        |
|                                |
|o9 = R1                         |
|                                |
|o9 : PolynomialRing             |
+--------------------------------+
|i10 : R2 = gaussianRing D       |
|                                |
|o10 = R2                        |
|                                |
|o10 : PolynomialRing            |
+--------------------------------+
|i11 : R1.gaussianRingData       |
|                                |
|o11 = HashTable{compU => {}    }|
|                compW => {4, 5} |
|                kVar => k       |
|                lVar => l       |
|                nn => 2         |
|                pVar => p       |
|                sVar => s       |
|                                |
|o11 : HashTable                 |
+--------------------------------+
|i12 : R2.gaussianRingData       |
|                                |
|o12 = HashTable{compU => {}    }|
|                compW => {1, 4} |
|                kVar => k       |
|                lVar => l       |
|                nn => 2         |
|                pVar => p       |
|                sVar => s       |
|                                |
|o12 : HashTable                 |
+--------------------------------+

See also
========

  * partitionLMG (StatGraphs) -- partition the vertices of
    a loopless mixed graph into adjacent to undirected edges and adjacent to
    bidirected edges
  * gaussianRingData -- hash table with main
    parameters of a gaussian ring
  * kVar -- key in hash table gaussianRingData: labels of k
    variables
  * pVar -- key in hash table gaussianRingData: labels of p
    variables
  * sVar -- key in hash table gaussianRingData: labels of s
    variables
  * lVar -- key in hash table gaussianRingData: labels of l
    variables
  * compU -- key in hash table gaussianRingData: component of
    undirected edges in vertex set of a mixed graph
  * nn -- key in hash table gaussianRingData: total number of
    variables

For the programmer
==================

The object compW, is a symbol (Macaulay2Doc).

conditionalIndependenceIdeal -- ideal of a list of conditional independent statements
*************************************************************************************

Synopsis
========

  * Usage:
        conditionalIndependenceIdeal(R,Stmts)
        conditionalIndependenceIdeal(R,Stmts,VarNames)
  * Inputs:
      * R, a ring (Macaulay2Doc), it must be a gaussianRing,
        or a markovRing,
      * Stmts, a list (Macaulay2Doc), list of conditional
        independence statements
      * VarNames, a list (Macaulay2Doc), list of names of random
        variables in conditional independence statements in Stmts. This
        argument allows to choose a subset of random variables and is only
        available for markov rings. By default, this is a list of integers 1 to
        $n$ where $n$ is the number of variables in the declaration of
        markovRing or gaussianRing. If R is a gaussian ring, then only the
        default input is accepted.
  * Outputs:
      * an ideal (Macaulay2Doc), ideal of conditional independence
        relations

Description
===========

conditionalIndependenceIdeal computes the ideal of a list of conditional
independence statements. This method works for both discrete and Gaussian
graphical models. In the case of discrete random variables, it computes the 2x2
minors of the matrices produced by markovMatrices. For
Gaussian graphical models, it computes the minors of the matrices produced by
gaussianMatrices.

A single conditional independence statement is a list consisting of three
disjoint lists of indices for random variables, e.g. $\{ \{1,2\},\{4\}, \{3\}
\}$ which represents the conditional independence statement ``$(X_1, X_2)$ is
conditionally independent of $X_4$ given $X_3$''. In the input to
conditionalIndependenceIdeal a list of conditional independence statements is
used.

A common way that we arrive at collections of conditional independence
statements is through the Markov statements implied by a graph. Below are two
examples of independence ideals on discrete random variables, using
globalMarkov, statements and localMarkov,
statements.

+-----------------------------------------------------------------------------+
|i1 : G = graph {{1,2},{2,3},{3,4},{4,1}}                                     |
|                                                                             |
|o1 = Graph{1 => {2, 4}}                                                      |
|           2 => {1, 3}                                                       |
|           3 => {2, 4}                                                       |
|           4 => {1, 3}                                                       |
|                                                                             |
|o1 : Graph                                                                   |
+-----------------------------------------------------------------------------+
|i2 : D = digraph {{1,{}},{2,{1}},{3,{1}},{4,{2,3}}}                          |
|                                                                             |
|o2 = Digraph{1 => {}    }                                                    |
|             2 => {1}                                                        |
|             3 => {1}                                                        |
|             4 => {2, 3}                                                     |
|                                                                             |
|o2 : Digraph                                                                 |
+-----------------------------------------------------------------------------+
|i3 : R = markovRing (2,2,2,2)                                                |
|                                                                             |
|o3 = R                                                                       |
|                                                                             |
|o3 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i4 : conditionalIndependenceIdeal (R, globalMarkov(G)) / print;              |
|- p       p        + p       p                                               |
|   1,1,2,1 2,1,1,1    1,1,1,1 2,1,2,1                                        |
|- p       p        + p       p                                               |
|   1,1,2,2 2,1,1,2    1,1,1,2 2,1,2,2                                        |
|- p       p        + p       p                                               |
|   1,2,2,1 2,2,1,1    1,2,1,1 2,2,2,1                                        |
|- p       p        + p       p                                               |
|   1,2,2,2 2,2,1,2    1,2,1,2 2,2,2,2                                        |
|- p       p        + p       p                                               |
|   1,1,1,2 1,2,1,1    1,1,1,1 1,2,1,2                                        |
|- p       p        + p       p                                               |
|   1,1,2,2 1,2,2,1    1,1,2,1 1,2,2,2                                        |
|- p       p        + p       p                                               |
|   2,1,1,2 2,2,1,1    2,1,1,1 2,2,1,2                                        |
|- p       p        + p       p                                               |
|   2,1,2,2 2,2,2,1    2,1,2,1 2,2,2,2                                        |
+-----------------------------------------------------------------------------+
|i5 : conditionalIndependenceIdeal (R, localMarkov(D)) / print;               |
|- p       p        + p       p                                               |
|   1,1,1,2 2,1,1,1    1,1,1,1 2,1,1,2                                        |
|- p       p        + p       p                                               |
|   1,1,2,2 2,1,2,1    1,1,2,1 2,1,2,2                                        |
|- p       p        + p       p                                               |
|   1,2,1,2 2,2,1,1    1,2,1,1 2,2,1,2                                        |
|- p       p        + p       p                                               |
|   1,2,2,2 2,2,2,1    1,2,2,1 2,2,2,2                                        |
|- p       p        + p       p        + p       p        - p       p        -|
|   1,1,2,1 1,2,1,1    1,1,1,1 1,2,2,1    1,2,2,1 2,1,1,1    1,2,1,1 2,1,2,1  |
|- p       p        + p       p        + p       p        - p       p        -|
|   1,1,2,2 1,2,1,2    1,1,1,2 1,2,2,2    1,2,2,2 2,1,1,2    1,2,1,2 2,1,2,2  |
|-----------------------------------------------------------------------------|
|p       p        - p       p        + p       p        + p       p           |
| 1,1,2,1 2,2,1,1    2,1,2,1 2,2,1,1    1,1,1,1 2,2,2,1    2,1,1,1 2,2,2,1    |
|p       p        - p       p        + p       p        + p       p           |
| 1,1,2,2 2,2,1,2    2,1,2,2 2,2,1,2    1,1,1,2 2,2,2,2    2,1,1,2 2,2,2,2    |
+-----------------------------------------------------------------------------+

The following example is an independence ideal of a Gaussian graphical model.

+-----------------------------------------------------------------------------+
|i6 : G = graph {{a,b},{b,c},{c,d},{d,a}}                                     |
|                                                                             |
|o6 = Graph{a => {b, d}}                                                      |
|           b => {a, c}                                                       |
|           c => {b, d}                                                       |
|           d => {a, c}                                                       |
|                                                                             |
|o6 : Graph                                                                   |
+-----------------------------------------------------------------------------+
|i7 : R=gaussianRing G                                                        |
|                                                                             |
|o7 = R                                                                       |
|                                                                             |
|o7 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i8 : conditionalIndependenceIdeal (R,globalMarkov(G))  / print;              |
|                    2                                                        |
|s   s   s    - s   s    - s   s   s    + s   s   s    + s   s   s    -       |
| a,d b,c b,d    a,c b,d    a,d b,b c,d    a,b b,d c,d    a,c b,b d,d         |
|                2                                                            |
|s   s   s    - s   s    - s   s   s    + s   s   s    + s   s   s    -       |
| a,c a,d b,c    a,c b,d    a,b a,d c,c    a,a b,d c,c    a,b a,c c,d         |
|-----------------------------------------------------------------------------|
|s   s   s                                                                    |
| a,b b,c d,d                                                                 |
|                                                                             |
|s   s   s                                                                    |
| a,a b,c c,d                                                                 |
+-----------------------------------------------------------------------------+

For Gaussian models, conditionalIndependenceIdeal  can compute the ideal of a
list of independence statements on a graph even if the ring was not constructed
with that specific graph. However, the vertex labels in the graph should be
integers.

+-----------------------------------------------------------------------------+
|i9 : G = graph({{1,2},{2,3},{3,4},{4,1}})                                    |
|                                                                             |
|o9 = Graph{1 => {2, 4}}                                                      |
|           2 => {1, 3}                                                       |
|           3 => {2, 4}                                                       |
|           4 => {1, 3}                                                       |
|                                                                             |
|o9 : Graph                                                                   |
+-----------------------------------------------------------------------------+
|i10 : R=gaussianRing 4                                                       |
|                                                                             |
|o10 = R                                                                      |
|                                                                             |
|o10 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i11 : conditionalIndependenceIdeal (R, globalMarkov G)  / print;             |
|                    2                                                        |
|s   s   s    - s   s    - s   s   s    + s   s   s    + s   s   s    -       |
| 1,4 2,3 2,4    1,3 2,4    1,4 2,2 3,4    1,2 2,4 3,4    1,3 2,2 4,4         |
|                2                                                            |
|s   s   s    - s   s    - s   s   s    + s   s   s    + s   s   s    -       |
| 1,3 1,4 2,3    1,3 2,4    1,2 1,4 3,3    1,1 2,4 3,3    1,2 1,3 3,4         |
|-----------------------------------------------------------------------------|
|s   s   s                                                                    |
| 1,2 2,3 4,4                                                                 |
|                                                                             |
|s   s   s                                                                    |
| 1,1 2,3 3,4                                                                 |
+-----------------------------------------------------------------------------+

This method also accepts as input arbitrary lists of independent statements
that may not arise from a graphical model.

+-----------------------------------------------------------------------------+
|i12 : R=gaussianRing 5                                                       |
|                                                                             |
|o12 = R                                                                      |
|                                                                             |
|o12 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i13 : S={{{1},{2},{3,4}}, {{2,3},{1},{5}}}                                   |
|                                                                             |
|o13 = {{{1}, {2}, {3, 4}}, {{2, 3}, {1}, {5}}}                               |
|                                                                             |
|o13 : List                                                                   |
+-----------------------------------------------------------------------------+
|i14 : conditionalIndependenceIdeal (R,S) / print;                            |
|                                                    2                        |
|- s   s   s    + s   s   s    + s   s   s    - s   s    - s   s   s    +     |
|   1,4 2,4 3,3    1,4 2,3 3,4    1,3 2,4 3,4    1,2 3,4    1,3 2,3 4,4       |
|- s   s    + s   s                                                           |
|   1,3 2,5    1,2 3,5                                                        |
|- s   s    + s   s                                                           |
|   1,5 2,5    1,2 5,5                                                        |
|- s   s    + s   s                                                           |
|   1,5 3,5    1,3 5,5                                                        |
|-----------------------------------------------------------------------------|
|s   s   s                                                                    |
| 1,2 3,3 4,4                                                                 |
+-----------------------------------------------------------------------------+

For general discrete independence models (not necessarily arising from a
graph), conditionalIndependenceIdeal requires one of the following two options:
\break (1) the random variables are labelled by integers (as in the first
example above) or  \break (2) in case the random variables have arbitrary
names, an extra input parameter must be used in order to specify the names of
the random variables.

+-----------------------------------------------------------------------------+
|i15 : R = markovRing (2,2,2,2)                                               |
|                                                                             |
|o15 = R                                                                      |
|                                                                             |
|o15 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i16 : VarNames = {c,d,e,f}                                                   |
|                                                                             |
|o16 = {c, d, e, f}                                                           |
|                                                                             |
|o16 : List                                                                   |
+-----------------------------------------------------------------------------+
|i17 : Stmts = { {{c,d},{e},{}}, {{d,e},{c},{f}}}                             |
|                                                                             |
|o17 = {{{c, d}, {e}, {}}, {{d, e}, {c}, {f}}}                                |
|                                                                             |
|o17 : List                                                                   |
+-----------------------------------------------------------------------------+
|i18 : conditionalIndependenceIdeal(R,Stmts,VarNames)    / print;             |
|- p       p        - p       p        - p       p        - p       p        +|
|   1,1,2,1 1,2,1,1    1,1,2,2 1,2,1,1    1,1,2,1 1,2,1,2    1,1,2,2 1,2,1,2  |
|- p       p        - p       p        - p       p        - p       p        +|
|   1,1,2,1 2,1,1,1    1,1,2,2 2,1,1,1    1,1,2,1 2,1,1,2    1,1,2,2 2,1,1,2  |
|- p       p        - p       p        - p       p        - p       p        +|
|   1,2,2,1 2,1,1,1    1,2,2,2 2,1,1,1    1,2,2,1 2,1,1,2    1,2,2,2 2,1,1,2  |
|- p       p        - p       p        - p       p        - p       p        +|
|   1,1,2,1 2,2,1,1    1,1,2,2 2,2,1,1    1,1,2,1 2,2,1,2    1,1,2,2 2,2,1,2  |
|- p       p        - p       p        - p       p        - p       p        +|
|   1,2,2,1 2,2,1,1    1,2,2,2 2,2,1,1    1,2,2,1 2,2,1,2    1,2,2,2 2,2,1,2  |
|- p       p        - p       p        - p       p        - p       p        +|
|   2,1,2,1 2,2,1,1    2,1,2,2 2,2,1,1    2,1,2,1 2,2,1,2    2,1,2,2 2,2,1,2  |
|- p       p        + p       p                                               |
|   1,1,2,1 2,1,1,1    1,1,1,1 2,1,2,1                                        |
|- p       p        + p       p                                               |
|   1,2,1,1 2,1,1,1    1,1,1,1 2,2,1,1                                        |
|- p       p        + p       p                                               |
|   1,2,1,1 2,1,2,1    1,1,2,1 2,2,1,1                                        |
|- p       p        + p       p                                               |
|   1,2,2,1 2,1,1,1    1,1,1,1 2,2,2,1                                        |
|- p       p        + p       p                                               |
|   1,2,2,1 2,1,2,1    1,1,2,1 2,2,2,1                                        |
|- p       p        + p       p                                               |
|   1,2,2,1 2,2,1,1    1,2,1,1 2,2,2,1                                        |
|- p       p        + p       p                                               |
|   1,1,2,2 2,1,1,2    1,1,1,2 2,1,2,2                                        |
|- p       p        + p       p                                               |
|   1,2,1,2 2,1,1,2    1,1,1,2 2,2,1,2                                        |
|- p       p        + p       p                                               |
|   1,2,1,2 2,1,2,2    1,1,2,2 2,2,1,2                                        |
|- p       p        + p       p                                               |
|   1,2,2,2 2,1,1,2    1,1,1,2 2,2,2,2                                        |
|- p       p        + p       p                                               |
|   1,2,2,2 2,1,2,2    1,1,2,2 2,2,2,2                                        |
|- p       p        + p       p                                               |
|   1,2,2,2 2,2,1,2    1,2,1,2 2,2,2,2                                        |
|-----------------------------------------------------------------------------|
|p       p        + p       p        + p       p        + p       p           |
| 1,1,1,1 1,2,2,1    1,1,1,2 1,2,2,1    1,1,1,1 1,2,2,2    1,1,1,2 1,2,2,2    |
|p       p        + p       p        + p       p        + p       p           |
| 1,1,1,1 2,1,2,1    1,1,1,2 2,1,2,1    1,1,1,1 2,1,2,2    1,1,1,2 2,1,2,2    |
|p       p        + p       p        + p       p        + p       p           |
| 1,2,1,1 2,1,2,1    1,2,1,2 2,1,2,1    1,2,1,1 2,1,2,2    1,2,1,2 2,1,2,2    |
|p       p        + p       p        + p       p        + p       p           |
| 1,1,1,1 2,2,2,1    1,1,1,2 2,2,2,1    1,1,1,1 2,2,2,2    1,1,1,2 2,2,2,2    |
|p       p        + p       p        + p       p        + p       p           |
| 1,2,1,1 2,2,2,1    1,2,1,2 2,2,2,1    1,2,1,1 2,2,2,2    1,2,1,2 2,2,2,2    |
|p       p        + p       p        + p       p        + p       p           |
| 2,1,1,1 2,2,2,1    2,1,1,2 2,2,2,1    2,1,1,1 2,2,2,2    2,1,1,2 2,2,2,2    |
+-----------------------------------------------------------------------------+

The following example illustrates the caveat below.

+-------------------------------------------------------------+
|i19 : D = digraph {{b,{a}},{a,{c}},{c,{}}}                   |
|                                                             |
|o19 = Digraph{a => {c}}                                      |
|              b => {a}                                       |
|              c => {}                                        |
|                                                             |
|o19 : Digraph                                                |
+-------------------------------------------------------------+
|i20 : R = markovRing (2,3,2)                                 |
|                                                             |
|o20 = R                                                      |
|                                                             |
|o20 : PolynomialRing                                         |
+-------------------------------------------------------------+
|i21 : VarNames = {b,a,c}                                     |
|                                                             |
|o21 = {b, a, c}                                              |
|                                                             |
|o21 : List                                                   |
+-------------------------------------------------------------+
|i22 : S = globalMarkov D                                     |
|                                                             |
|o22 = {{{b}, {c}, {a}}}                                      |
|                                                             |
|o22 : List                                                   |
+-------------------------------------------------------------+
|i23 : conditionalIndependenceIdeal(R, S, VarNames) / print;  |
|- p     p      + p     p                                     |
|   1,1,2 2,1,1    1,1,1 2,1,2                                |
|- p     p      + p     p                                     |
|   1,2,2 2,2,1    1,2,1 2,2,2                                |
|- p     p      + p     p                                     |
|   1,3,2 2,3,1    1,3,1 2,3,2                                |
+-------------------------------------------------------------+
|i24 : vertices D                                             |
|                                                             |
|o24 = {c, a, b}                                              |
|                                                             |
|o24 : List                                                   |
+-------------------------------------------------------------+
|i25 : conditionalIndependenceIdeal(R, S, vertices D) / print;|
|- p     p      + p     p                                     |
|   1,1,2 2,1,1    1,1,1 2,1,2                                |
|- p     p      + p     p                                     |
|   1,2,2 2,2,1    1,2,1 2,2,2                                |
|- p     p      + p     p                                     |
|   1,3,2 2,3,1    1,3,1 2,3,2                                |
+-------------------------------------------------------------+

Caveat
======

We note that the list of random variable names must be in the same order as the
implicit order used in the sequence $d$. In the previous example, we have the
graph $b \to a \to c$, where $a$ has three states and $b$ and $c$ are both
binary. Note that the ring $R$ was created with the sequence $d = (2,3,2)$,
having in mind the topological order of the graph as opposed to the vertex
labels. Note how the first instance of this method returns the correct output,
however, the second instance returns an incorrect ideal since vertices D is not
in the same order as the sequence $d$.

See also
========

  * discreteVanishingIdeal -- vanishing ideal of
    a discrete graphical model
  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model
  * gaussianVanishingIdeal -- vanishing ideal of
    a Gaussian graphical model
  * markovRing -- ring of joint probability distributions on
    several discrete random variables
  * trekIdeal -- trek separation ideal of a mixed graph

Ways to use conditionalIndependenceIdeal :
==========================================

  * "conditionalIndependenceIdeal(Ring,List)"
  * "conditionalIndependenceIdeal(Ring,List,List)"

For the programmer
==================

The object conditionalIndependenceIdeal, is
a method function (Macaulay2Doc).

covarianceMatrix -- covariance matrix of a Gaussian graphical model
*******************************************************************

Synopsis
========

  * Usage:
        covarianceMatrix R
  * Inputs:
      * R, a ring (Macaulay2Doc), which should be a gaussianRing
  * Outputs:
      * a matrix (Macaulay2Doc), the $n \times{} n$ covariance
        matrix of the Gaussian graphical model.

Description
===========

This method returns the $n \times{} n$ covariance matrix of the Gaussian
graphical model where $n$ is the number of random variables in the model.  If
the gaussianRing was created using a graph, $n$ will be the number of vertices
of the graph. If this function is called without a graph $G$, it is assumed
that $R$ is the gaussianRing of a directed acyclic graph.

+-----------------------------------------------------------------------------+
|i1 : compactMatrixForm =false;                                               |
+-----------------------------------------------------------------------------+
|i2 : covarianceMatrix gaussianRing 4                                         |
|                                                                             |
|o2 = |  s     s     s     s     |                                            |
|     |   1,1   1,2   1,3   1,4  |                                            |
|     |                          |                                            |
|     |  s     s     s     s     |                                            |
|     |   1,2   2,2   2,3   2,4  |                                            |
|     |                          |                                            |
|     |  s     s     s     s     |                                            |
|     |   1,3   2,3   3,3   3,4  |                                            |
|     |                          |                                            |
|     |  s     s     s     s     |                                            |
|     |   1,4   2,4   3,4   4,4  |                                            |
|                                                                             |
|                                                          4                  |
|o2 : Matrix (QQ[s   ..s   , s   ..s   , s   ..s   , s   ])  <---             |
|                 1,1   1,4   2,2   2,4   3,3   3,4   4,4                     |
|-----------------------------------------------------------------------------|
|                                              4                              |
|(QQ[s   ..s   , s   ..s   , s   ..s   , s   ])                               |
|     1,1   1,4   2,2   2,4   3,3   3,4   4,4                                 |
+-----------------------------------------------------------------------------+
|i3 : G = digraph {{a,{b,c}}, {b,{c,d}}, {c,{}}, {d,{}}}                      |
|                                                                             |
|o3 = Digraph{a => {c, b}}                                                    |
|             b => {c, d}                                                     |
|             c => {}                                                         |
|             d => {}                                                         |
|                                                                             |
|o3 : Digraph                                                                 |
+-----------------------------------------------------------------------------+
|i4 : R = gaussianRing G                                                      |
|                                                                             |
|o4 = R                                                                       |
|                                                                             |
|o4 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i5 : S = covarianceMatrix R                                                  |
|                                                                             |
|o5 = |  s     s     s     s     |                                            |
|     |   a,a   a,b   a,c   a,d  |                                            |
|     |                          |                                            |
|     |  s     s     s     s     |                                            |
|     |   a,b   b,b   b,c   b,d  |                                            |
|     |                          |                                            |
|     |  s     s     s     s     |                                            |
|     |   a,c   b,c   c,c   c,d  |                                            |
|     |                          |                                            |
|     |  s     s     s     s     |                                            |
|     |   a,d   b,d   c,d   d,d  |                                            |
|                                                                             |
|             4       4                                                       |
|o5 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+

This function also works for gaussianRings created with a graph or mixedGraph.

+----------------------------------------------------------------+
|i6 : G = graph({{a,b},{b,c},{c,d},{a,d}})                       |
|                                                                |
|o6 = Graph{a => {b, d}}                                         |
|           b => {a, c}                                          |
|           c => {b, d}                                          |
|           d => {a, c}                                          |
|                                                                |
|o6 : Graph                                                      |
+----------------------------------------------------------------+
|i7 : R = gaussianRing G                                         |
|                                                                |
|o7 = R                                                          |
|                                                                |
|o7 : PolynomialRing                                             |
+----------------------------------------------------------------+
|i8 : S = covarianceMatrix R                                     |
|                                                                |
|o8 = |  s     s     s     s     |                               |
|     |   a,a   a,b   a,c   a,d  |                               |
|     |                          |                               |
|     |  s     s     s     s     |                               |
|     |   a,b   b,b   b,c   b,d  |                               |
|     |                          |                               |
|     |  s     s     s     s     |                               |
|     |   a,c   b,c   c,c   c,d  |                               |
|     |                          |                               |
|     |  s     s     s     s     |                               |
|     |   a,d   b,d   c,d   d,d  |                               |
|                                                                |
|             4       4                                          |
|o8 : Matrix R  <--- R                                           |
+----------------------------------------------------------------+
|i9 : G = mixedGraph(digraph {{b,{c,d}},{c,{d}}},bigraph {{a,d}})|
|                                                                |
|o9 = MixedGraph{Bigraph => Bigraph{a => {d}}   }                |
|                                   d => {a}                     |
|                Digraph => Digraph{b => {c, d}}                 |
|                                   c => {d}                     |
|                                   d => {}                      |
|                Graph => Graph{}                                |
|                                                                |
|o9 : MixedGraph                                                 |
+----------------------------------------------------------------+
|i10 : R = gaussianRing G                                        |
|                                                                |
|o10 = R                                                         |
|                                                                |
|o10 : PolynomialRing                                            |
+----------------------------------------------------------------+
|i11 : S = covarianceMatrix R                                    |
|                                                                |
|o11 = |  s     s     s     s     |                              |
|      |   a,a   a,b   a,c   a,d  |                              |
|      |                          |                              |
|      |  s     s     s     s     |                              |
|      |   a,b   b,b   b,c   b,d  |                              |
|      |                          |                              |
|      |  s     s     s     s     |                              |
|      |   a,c   b,c   c,c   c,d  |                              |
|      |                          |                              |
|      |  s     s     s     s     |                              |
|      |   a,d   b,d   c,d   d,d  |                              |
|                                                                |
|              4       4                                         |
|o11 : Matrix R  <--- R                                          |
+----------------------------------------------------------------+

See also
========

  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model
  * gaussianParametrization -- parametrization
    of the covariance matrix in terms of treks
  * bidirectedEdgesMatrix -- matrix corresponding
    to the bidirected edges of a bigraph or a mixed graph
  * directedEdgesMatrix -- matrix corresponding to
    the directed edges of a digraph or a mixed graph

Ways to use covarianceMatrix :
==============================

  * "covarianceMatrix(Ring)"

For the programmer
==================

The object covarianceMatrix, is a method function (Macaulay2Doc).

directedEdgesMatrix -- matrix corresponding to the directed edges of a digraph or a mixed graph
***********************************************************************************************

Synopsis
========

  * Usage:
        directedEdgesMatrix R
  * Inputs:
      * R, a ring (Macaulay2Doc), which should be a gaussianRing
        created with a digraph (Graphs), or an instance of the
        type MixedGraph (StatGraphs),
  * Outputs:
      * a matrix (Macaulay2Doc), the $n \times{} n$ matrix of
        direct causal effect indeterminates.

Description
===========

This method returns the  $n \times{} n$ matrix of direct causal effect
indeterminates. This matrix has the parameter $l_{(i,j)}$ in the $(i,j)$
position if there is a directed edge $i \to j$, and 0 otherwise. Note that this
matrix is not symmetric. The documentation of gaussianRing,
further describes the indeterminates $l_{(i,j)}$.

+----------------------------------------------------------------+
|i1 : G = mixedGraph(digraph {{b,{c,d}},{c,{d}}},bigraph {{a,d}})|
|                                                                |
|o1 = MixedGraph{Bigraph => Bigraph{a => {d}}   }                |
|                                   d => {a}                     |
|                Digraph => Digraph{b => {c, d}}                 |
|                                   c => {d}                     |
|                                   d => {}                      |
|                Graph => Graph{}                                |
|                                                                |
|o1 : MixedGraph                                                 |
+----------------------------------------------------------------+
|i2 : R = gaussianRing G                                         |
|                                                                |
|o2 = R                                                          |
|                                                                |
|o2 : PolynomialRing                                             |
+----------------------------------------------------------------+
|i3 : compactMatrixForm =false;                                  |
+----------------------------------------------------------------+
|i4 : directedEdgesMatrix R                                      |
|                                                                |
|o4 = |  0  0    0     0   |                                     |
|     |                    |                                     |
|     |  0  0  l     l     |                                     |
|     |         b,c   b,d  |                                     |
|     |                    |                                     |
|     |  0  0    0   l     |                                     |
|     |               c,d  |                                     |
|     |                    |                                     |
|     |  0  0    0     0   |                                     |
|                                                                |
|             4       4                                          |
|o4 : Matrix R  <--- R                                           |
+----------------------------------------------------------------+
+---------------------------------------+
|i5 : D = digraph{{a,b},{c,d}}          |
|                                       |
|o5 = Digraph{a => {b}}                 |
|             b => {}                   |
|             c => {d}                  |
|             d => {}                   |
|                                       |
|o5 : Digraph                           |
+---------------------------------------+
|i6 : directedEdgesMatrix gaussianRing D|
|                                       |
|o6 = |  0  0    0     0   |            |
|     |                    |            |
|     |  0  0  l     l     |            |
|     |         b,c   b,d  |            |
|     |                    |            |
|     |  0  0    0   l     |            |
|     |               c,d  |            |
|     |                    |            |
|     |  0  0    0     0   |            |
|                                       |
|             4       4                 |
|o6 : Matrix R  <--- R                  |
+---------------------------------------+

See also
========

  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model
  * gaussianParametrization -- parametrization
    of the covariance matrix in terms of treks
  * covarianceMatrix -- covariance matrix of a
    Gaussian graphical model
  * bidirectedEdgesMatrix -- matrix corresponding
    to the bidirected edges of a bigraph or a mixed graph

Ways to use directedEdgesMatrix :
=================================

  * "directedEdgesMatrix(Ring)"

For the programmer
==================

The object directedEdgesMatrix, is a method function (Macaulay2Doc).

discreteVanishingIdeal -- vanishing ideal of a discrete graphical model
***********************************************************************

Synopsis
========

  * Usage:
        discreteVanishingIdeal(R,G)
  * Inputs:
      * R, a ring (Macaulay2Doc), created with markovRing,
      * G, a digraph (Graphs),
  * Outputs:
      * an ideal (Macaulay2Doc), an ideal in $R$

Description
===========

This method computes the ideal in $R$ of homogeneous polynomial relations on
the joint probabilities of random variables represented by the vertices of $G$.

Here is a small example that compute the vanishing ideal on the joint
probabilities of two independent binary random variables. In this case, this
ideal equals the ideal obtained using conditionalIndependenceIdeal.

+---------------------------------------------------+
|i1 : G = digraph {{1,{}}, {2,{}}}                  |
|                                                   |
|o1 = Digraph{1 => {}}                              |
|             2 => {}                               |
|                                                   |
|o1 : Digraph                                       |
+---------------------------------------------------+
|i2 : R = markovRing (2,2)                          |
|                                                   |
|o2 = R                                             |
|                                                   |
|o2 : PolynomialRing                                |
+---------------------------------------------------+
|i3 : discreteVanishingIdeal (R,G)                  |
|                                                   |
|o3 = ideal(p   p    - p   p   )                    |
|            1,2 2,1    1,1 2,2                     |
|                                                   |
|o3 : Ideal of R                                    |
+---------------------------------------------------+
|i4 : conditionalIndependenceIdeal(R, localMarkov G)|
|                                                   |
|o4 = ideal(- p   p    + p   p   )                  |
|              1,2 2,1    1,1 2,2                   |
|                                                   |
|o4 : Ideal of R                                    |
+---------------------------------------------------+

Here is an example for a graph on four vertices. The random variables a,b,c and
d have 2,3,4, and 2 states, respectively.

+-------------------------------------------------------+
|i5 : G = digraph {{a,{b,c}}, {b,{c,d}}, {c,{}}, {d,{}}}|
|                                                       |
|o5 = Digraph{a => {c, b}}                              |
|             b => {c, d}                               |
|             c => {}                                   |
|             d => {}                                   |
|                                                       |
|o5 : Digraph                                           |
+-------------------------------------------------------+
|i6 : R = markovRing (2,3,4,2)                          |
|                                                       |
|o6 = R                                                 |
|                                                       |
|o6 : PolynomialRing                                    |
+-------------------------------------------------------+
|i7 : I = discreteVanishingIdeal (R,G);                 |
|                                                       |
|o7 : Ideal of R                                        |
+-------------------------------------------------------+

The vanishing ideal is generated by 84 quadrics, which we don't display.

+----------------+
|i8 : betti I    |
|                |
|            0  1|
|o8 = total: 1 84|
|         0: 1  .|
|         1: . 84|
|                |
|o8 : BettiTally |
+----------------+

See also
========

  * markovRing -- ring of joint probability distributions on
    several discrete random variables
  * conditionalIndependenceIdeal -- ideal
    of a list of conditional independent statements

Ways to use discreteVanishingIdeal :
====================================

  * "discreteVanishingIdeal(Ring,Digraph)"

For the programmer
==================

The object discreteVanishingIdeal, is a
method function (Macaulay2Doc).

gaussianMatrices -- matrices whose minors generate the Gaussian conditional independence ideal
**********************************************************************************************

Synopsis
========

  * Usage:
        gaussianMatrices(R,S)
  * Inputs:
      * R, a ring (Macaulay2Doc), must be a gaussianRing
      * S, a list (Macaulay2Doc), of conditional independence
        statements
  * Outputs:
      * a matrix (Macaulay2Doc), whose minors generate the
        Gaussian conditional independence ideal

Description
===========

This method displays a list of matrices whose minors generate the  Gaussian
conditional independence ideal.  It is called as a subroutine in
conditionalIndependenceIdeal, but it is useful to
list these matrices explicitly.

+--------------------------------------------+
|i1 : R = gaussianRing 4;                    |
+--------------------------------------------+
|i2 : Stmts = {{{1,2},{3},{4}}, {{1},{3},{}}}|
|                                            |
|o2 = {{{1, 2}, {3}, {4}}, {{1}, {3}, {}}}   |
|                                            |
|o2 : List                                   |
+--------------------------------------------+
|i3 : compactMatrixForm =false;              |
+--------------------------------------------+
|i4 : gaussianMatrices(R,Stmts)              |
|                                            |
|o4 = {|  s     s     |, |  s     |}         |
|      |   1,3   1,4  |  |   1,3  |          |
|      |              |                      |
|      |  s     s     |                      |
|      |   2,3   2,4  |                      |
|      |              |                      |
|      |  s     s     |                      |
|      |   3,4   4,4  |                      |
|                                            |
|o4 : List                                   |
+--------------------------------------------+

See also
========

  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model
  * conditionalIndependenceIdeal -- ideal
    of a list of conditional independent statements

Ways to use gaussianMatrices :
==============================

  * "gaussianMatrices(Ring,List)"

For the programmer
==================

The object gaussianMatrices, is a method function (Macaulay2Doc).

gaussianParametrization -- parametrization of the covariance matrix in terms of treks
*************************************************************************************

Synopsis
========

  * Usage:
        M = gaussianParametrization(R)
  * Inputs:
      * R, a ring (Macaulay2Doc), which should be a gaussianRing of
        a mixed graph without undirected edges
  * Optional inputs (Macaulay2Doc),:
      * SimpleTreks,
        => ..., default value false, optional input for
        gaussianParametrization
  * Outputs:
      * M, a matrix (Macaulay2Doc), the parametrization of the
        covariance matrix in terms of treks

Description
===========

Given a mixed graph $G$ with directed and bidirected edges, let $L$ be the
matrix corresponding to the directed edges (see directedEdgesMatrix)
and let $W$ be the matrix corresponding to the bidirected
edges (see bidirectedEdgesMatrix). Then, the
covariance matrix $S$ (see covarianceMatrix) of the
random variables in the Gaussian graphical model corresponding to the mixed
graph $G$ can be parametrized by the matrix equation $S =
(I-L)^{-T}W(I-L)^{-1}$, where $I$ is the identity matrix.

The entry $s_{(i,j)}$ of the covariance matrix can also be written as the sum
of all monomials corresponding to treks between vertices $i$ and $j$. See
trekSeparation, for the definition of a trek. The monomial
corresponding to a trek is the product of all parameters associated to the
directed and bidirected edges on the trek.

The following example shows how to compute the ideal of the model using the
parametrization, which could also be computed using
gaussianVanishingIdeal,

+-----------------------------------------------------------------------------+
|i1 : G = mixedGraph(digraph {{b,{c,d}},{c,{d}}},bigraph {{a,d}})             |
|                                                                             |
|o1 = MixedGraph{Bigraph => Bigraph{a => {d}}   }                             |
|                                   d => {a}                                  |
|                Digraph => Digraph{b => {c, d}}                              |
|                                   c => {d}                                  |
|                                   d => {}                                   |
|                Graph => Graph{}                                             |
|                                                                             |
|o1 : MixedGraph                                                              |
+-----------------------------------------------------------------------------+
|i2 : R = gaussianRing G                                                      |
|                                                                             |
|o2 = R                                                                       |
|                                                                             |
|o2 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i3 : compactMatrixForm =false;                                               |
+-----------------------------------------------------------------------------+
|i4 : S = covarianceMatrix(R)                                                 |
|                                                                             |
|o4 = |  s     s     s     s     |                                            |
|     |   a,a   a,b   a,c   a,d  |                                            |
|     |                          |                                            |
|     |  s     s     s     s     |                                            |
|     |   a,b   b,b   b,c   b,d  |                                            |
|     |                          |                                            |
|     |  s     s     s     s     |                                            |
|     |   a,c   b,c   c,c   c,d  |                                            |
|     |                          |                                            |
|     |  s     s     s     s     |                                            |
|     |   a,d   b,d   c,d   d,d  |                                            |
|                                                                             |
|             4       4                                                       |
|o4 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i5 : L = directedEdgesMatrix(R)                                              |
|                                                                             |
|o5 = |  0  0    0     0   |                                                  |
|     |                    |                                                  |
|     |  0  0  l     l     |                                                  |
|     |         b,c   b,d  |                                                  |
|     |                    |                                                  |
|     |  0  0    0   l     |                                                  |
|     |               c,d  |                                                  |
|     |                    |                                                  |
|     |  0  0    0     0   |                                                  |
|                                                                             |
|             4       4                                                       |
|o5 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i6 : W = bidirectedEdgesMatrix(R)                                            |
|                                                                             |
|o6 = |  p       0     0   p     |                                            |
|     |   a,a               a,d  |                                            |
|     |                          |                                            |
|     |    0   p       0     0   |                                            |
|     |         b,b              |                                            |
|     |                          |                                            |
|     |    0     0   p       0   |                                            |
|     |               c,c        |                                            |
|     |                          |                                            |
|     |  p       0     0   p     |                                            |
|     |   a,d               d,d  |                                            |
|                                                                             |
|             4       4                                                       |
|o6 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i7 : M = gaussianParametrization(R)                                          |
|                                                                             |
|o7 = |  p                0                                0                  |
|     |   a,a                                                                 |
|     |                                                                       |
|     |    0             p                             l   p                  |
|     |                   b,b                           b,c b,b               |
|     |                                                                       |
|     |                                              2                        |
|     |    0           l   p                        l   p    + p              |
|     |                 b,c b,b                      b,c b,b    c,c           |
|     |                                                                       |
|     |                                  2                                    |
|     |  p     l   l   p    + l   p     l   l   p    + l   l   p    + l   p   |
|     |   a,d   b,c c,d b,b    b,d b,b   b,c c,d b,b    b,c b,d b,b    c,d c,c|
|     ------------------------------------------------------------------------|
|                                  p                                 |        |
|                                   a,d                              |        |
|                                                                    |        |
|                        l   l   p    + l   p                        |        |
|                         b,c c,d b,b    b,d b,b                     |        |
|                                                                    |        |
|                  2                                                 |        |
|                 l   l   p    + l   l   p    + l   p                |        |
|                  b,c c,d b,b    b,c b,d b,b    c,d c,c             |        |
|                                                                    |        |
|      2   2                              2          2               |        |
|     l   l   p    + 2l   l   l   p    + l   p    + l   p    + p     |        |
|      b,c c,d b,b     b,c b,d c,d b,b    b,d b,b    c,d c,c    d,d  |        |
|                                                                             |
|             4       4                                                       |
|o7 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i8 : J = delete(0_R, flatten entries (L|W))                                  |
|                                                                             |
|o8 = {p   , p   , l   , l   , p   , l   , p   , p   , p   }                  |
|       a,a   a,d   b,c   b,d   b,b   c,d   c,c   a,d   d,d                   |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+
|i9 : eliminate(J, ideal(S-M))                                                |
|                                                                             |
|o9 = ideal (s   , s   )                                                      |
|             a,c   a,b                                                       |
|                                                                             |
|o9 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i10 : gaussianVanishingIdeal(R)                                              |
|                                                                             |
|o10 = ideal (s   , s   )                                                     |
|              a,c   a,b                                                      |
|                                                                             |
|o10 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+

This next example shows how to use the option SimpleTreks,
to compute a parametrization using simple treks instead of all treks. The
resulting covariance matrix has diagonal entries equal to 1.  This is giving a
parametrization of all correlation matrices of matrices that belong to the
model.  This formulation is also known as Wright's method of path analysis.

+-------------------------------------------------------------------+
|i11 : G = mixedGraph(digraph {{b,{c,d}},{c,{d}}},bigraph {{a,d}})  |
|                                                                   |
|o11 = MixedGraph{Bigraph => Bigraph{a => {d}}   }                  |
|                                    d => {a}                       |
|                 Digraph => Digraph{b => {c, d}}                   |
|                                    c => {d}                       |
|                                    d => {}                        |
|                 Graph => Graph{}                                  |
|                                                                   |
|o11 : MixedGraph                                                   |
+-------------------------------------------------------------------+
|i12 : R = gaussianRing G                                           |
|                                                                   |
|o12 = R                                                            |
|                                                                   |
|o12 : PolynomialRing                                               |
+-------------------------------------------------------------------+
|i13 : M = gaussianParametrization(R,SimpleTreks=>true)             |
|                                                                   |
|o13 = |    1          0                0               p          ||
|      |                                                 a,d       ||
|      |                                                           ||
|      |    0          1               l          l   l    + l     ||
|      |                                b,c        b,c c,d    b,d  ||
|      |                                                           ||
|      |    0         l                 1         l   l    + l     ||
|      |               b,c                         b,c b,d    c,d  ||
|      |                                                           ||
|      |  p     l   l    + l     l   l    + l            1         ||
|      |   a,d   b,c c,d    b,d   b,c b,d    c,d                   ||
|                                                                   |
|              4       4                                            |
|o13 : Matrix R  <--- R                                             |
+-------------------------------------------------------------------+

See also
========

  * covarianceMatrix -- covariance matrix of a
    Gaussian graphical model
  * directedEdgesMatrix -- matrix corresponding to
    the directed edges of a digraph or a mixed graph
  * bidirectedEdgesMatrix -- matrix corresponding
    to the bidirected edges of a bigraph or a mixed graph
  * trekSeparation -- trek separation statements of a
    mixed graph

Ways to use gaussianParametrization :
=====================================

  * "gaussianParametrization(Ring)"

For the programmer
==================

The object gaussianParametrization, is a
method function with options (Macaulay2Doc).

gaussianParametrization(...,SimpleTreks=>...) -- optional input for gaussianParametrization
*******************************************************************************************

Synopsis
========

  * Usage:
        M = gaussianParametrization(R,SimpleTreks => true)
  * Inputs:
      * R, a ring (Macaulay2Doc), which should be a gaussianRing
  * Outputs:
      * M, a matrix (Macaulay2Doc), the parametrization of the
        covariance matrix in terms of treks

Description
===========

Put SimpleTreks => true as an argument in the function
gaussianParametrization, to compute a parametrization
of the covariance matrix $S=(s_{(i,j)})$ where $s_{(i,j)}$ is the sum of
monomials corresponding to simple treks between vertices $i$ and $j$. Here, a
simple trek is a trek $(P_L,P_R)$ where the paths $P_L$ and $P_R$ do not have
any common vertices except perhaps at their source. See trekSeparation,
for the definition of a trek.

If the option SimpleTreks => false is used, then the sum is over all treks, and
not just simple treks.

Further information
===================

  * Default value: false (Macaulay2Doc),
  * Function: gaussianParametrization, --
    parametrization of the covariance matrix in terms of treks
  * Option key: SimpleTreks, -- optional input for
    gaussianParametrization

See also
========

  * gaussianParametrization -- parametrization
    of the covariance matrix in terms of treks

Functions with optional argument named SimpleTreks :
====================================================

  * gaussianParametrization(...,SimpleTreks=>...),
    --
    optional input for gaussianParametrization

gaussianRing -- ring of Gaussian correlations on n random variables or a graphical model
****************************************************************************************

Synopsis
========

  * Usage:
        gaussianRing n
        gaussianRing G
  * Inputs:
      * n, an integer (Macaulay2Doc), the number of random variables
      * G, a graph (Graphs), or a digraph (Graphs),
        or an instance of the type Bigraph (StatGraphs), or an
        instance of the type MixedGraph (StatGraphs),
  * Optional inputs (Macaulay2Doc),:
      * Coefficients,
        => ..., default value QQ, optional input to choose the base field in
        markovRing or gaussianRing
      * kVariableName,
        => ..., default value "k", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
      * lVariableName,
        => ..., default value "l", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
      * pVariableName,
        => ..., default value "p", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
      * sVariableName,
        => ..., default value "s", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
  * Outputs:
      * a ring (Macaulay2Doc), a polynomial ring with
        indeterminates associated to the graphical model

Description
===========

This function creates a ring whose indeterminates are the covariances of an n
dimensional Gaussian random vector.  Using a graph, digraph, or mixed graph $G$
as input gives a gaussianRing with extra indeterminates related to the
parametrization of the graphical model associated to that graph. Check the
details of the gaussianRing for each type of input:

* gaussianRing(ZZ)

* gaussianRing(Graph)

* gaussianRing(Digraph)

* gaussianRing(Bigraph)

* gaussianRing(MixedGraph)

The indeterminates of the ring - $s_{(i,j)},k_{(i,j)},l_{(i,j)},p_{(i,j)}$ -
can be placed into an appropriate matrix format using the functions
covarianceMatrix, undirectedEdgesMatrix,
see directedEdgesMatrix, and
bidirectedEdgesMatrix, respectively.

The variable names that appear can be changed using the options sVariableName,
lVariableName, pVariableName, and kVariableName

+-----------------------------------------------------------------------------+
|i1 : G = mixedGraph(digraph {{b,{c,d}},{c,{d}}},bigraph {{a,d}})             |
|                                                                             |
|o1 = MixedGraph{Bigraph => Bigraph{a => {d}}   }                             |
|                                   d => {a}                                  |
|                Digraph => Digraph{b => {c, d}}                              |
|                                   c => {d}                                  |
|                                   d => {}                                   |
|                Graph => Graph{}                                             |
|                                                                             |
|o1 : MixedGraph                                                              |
+-----------------------------------------------------------------------------+
|i2 : R = gaussianRing (G,pVariableName => psi)                               |
|                                                                             |
|o2 = R                                                                       |
|                                                                             |
|o2 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i3 : gens R                                                                  |
|                                                                             |
|o3 = {l   , l   , l   , psi   , psi   , psi   , psi   , psi   , s   , s   ,  |
|       b,c   b,d   c,d     a,a     b,b     c,c     d,d     a,d   a,a   a,b   |
|     ------------------------------------------------------------------------|
|     s   , s   , s   , s   , s   , s   , s   , s   }                         |
|      a,c   a,d   b,b   b,c   b,d   c,c   c,d   d,d                          |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+

The routines  conditionalIndependenceIdeal,
see trekIdeal,
covarianceMatrix, undirectedEdgesMatrix,
see directedEdgesMatrix,
bidirectedEdgesMatrix, gaussianVanishingIdeal,
and gaussianParametrization,
require that the ring be created by this function.

See also
========

  * bidirectedEdgesMatrix -- matrix corresponding
    to the bidirected edges of a bigraph or a mixed graph
  * conditionalIndependenceIdeal -- ideal
    of a list of conditional independent statements
  * covarianceMatrix -- covariance matrix of a
    Gaussian graphical model
  * directedEdgesMatrix -- matrix corresponding to
    the directed edges of a digraph or a mixed graph
  * gaussianVanishingIdeal -- vanishing ideal of
    a Gaussian graphical model
  * trekIdeal -- trek separation ideal of a mixed graph
  * undirectedEdgesMatrix -- matrix corresponding
    to the edges of an undirected graph

Ways to use gaussianRing :
==========================

  * gaussianRing(Bigraph) -- ring of Gaussian
    correlations of a graphical model coming from a bigraph
  * gaussianRing(Digraph) -- ring of Gaussian
    correlations of a graphical model coming from a digraph
  * gaussianRing(Graph) -- ring of Gaussian
    correlations of a graphical model coming from an undirected graph
  * gaussianRing(MixedGraph) -- ring of
    Gaussian correlations of a graphical model coming from a mixed graph
  * gaussianRing(ZZ) -- ring of Gaussian
    correlations on n random variables

For the programmer
==================

The object gaussianRing, is a method function with a single argument (Macaulay2Doc).

gaussianRing(...,kVariableName=>...) -- symbol used for indeterminates in a ring of Gaussian joint probability distributions
****************************************************************************************************************************

Synopsis
========

  * Usage:
        gaussianRing(G,kVariableName=>m)
  * Inputs:
      * m, a Symbol (Macaulay2Doc), or a String (Macaulay2Doc),

Description
===========

The option gaussianRing(G,kVariableName=>m) changes the symbol used for
intedeterminates in the concentration matrix in a polynomial ring created with
gaussianRing.

+-----------------------------------------------------------------------------+
|i1 : R = gaussianRing graph({{a,b},{b,c},{c,d},{a,d}})                       |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : compactMatrixForm =false;                                               |
+-----------------------------------------------------------------------------+
|i3 : undirectedEdgesMatrix R                                                 |
|                                                                             |
|o3 = |  k     k       0   k     |                                            |
|     |   a,a   a,b         a,d  |                                            |
|     |                          |                                            |
|     |  k     k     k       0   |                                            |
|     |   a,b   b,b   b,c        |                                            |
|     |                          |                                            |
|     |    0   k     k     k     |                                            |
|     |         b,c   c,c   c,d  |                                            |
|     |                          |                                            |
|     |  k       0   k     k     |                                            |
|     |   a,d         c,d   d,d  |                                            |
|                                                                             |
|             4       4                                                       |
|o3 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i4 : gens R                                                                  |
|                                                                             |
|o4 = {k   , k   , k   , k   , k   , k   , k   , k   , s   , s   , s   , s   ,|
|       a,a   b,b   c,c   d,d   a,b   a,d   b,c   c,d   a,a   a,b   a,c   a,d |
|     ------------------------------------------------------------------------|
|     s   , s   , s   , s   , s   , s   }                                     |
|      b,b   b,c   b,d   c,c   c,d   d,d                                      |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : Rnew = gaussianRing( graph({{a,b},{b,c},{c,d},{a,d}}), kVariableName => |
|                                                                             |
|o5 = Rnew                                                                    |
|                                                                             |
|o5 : PolynomialRing                                                          |
|-----------------------------------------------------------------------------|
|kappa)                                                                       |
+-----------------------------------------------------------------------------+
|i6 : gens Rnew                                                               |
|                                                                             |
|o6 = {kappa   , kappa   , kappa   , kappa   , kappa   , kappa   , kappa   ,  |
|           a,a       b,b       c,c       d,d       a,b       a,d       b,c   |
|     ------------------------------------------------------------------------|
|     kappa   , s   , s   , s   , s   , s   , s   , s   , s   , s   , s   }   |
|          c,d   a,a   a,b   a,c   a,d   b,b   b,c   b,d   c,c   c,d   d,d    |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+

Further information
===================

  * Default value: k
  * Function: gaussianRing, -- ring of Gaussian
    correlations on n random variables or a graphical model
  * Option key: kVariableName, -- optional input to choose
    the variable names for concentration matrix in gaussianRing

Functions with optional argument named kVariableName :
======================================================

  * gaussianRing(...,kVariableName=>...)
    -- symbol used for
    indeterminates in a ring of Gaussian joint probability distributions

gaussianRing(...,lVariableName=>...) -- symbol used for indeterminates in a ring of Gaussian joint probability distributions
****************************************************************************************************************************

Synopsis
========

  * Usage:
        gaussianRing(G,lVariableName=>w)
  * Inputs:
      * w, a Symbol (Macaulay2Doc), or a String (Macaulay2Doc),

Description
===========

The option gaussianRing(G,lVariableName=>w) changes the symbol used for
intedeterminates in the regression matrix in a polynomial ring created with
gaussianRing.

+-----------------------------------------------------------------------------+
|i1 : G = mixedGraph(digraph {{b,{c,d}},{c,{d}}},bigraph {{a,d}})             |
|                                                                             |
|o1 = MixedGraph{Bigraph => Bigraph{a => {d}}   }                             |
|                                   d => {a}                                  |
|                Digraph => Digraph{b => {c, d}}                              |
|                                   c => {d}                                  |
|                                   d => {}                                   |
|                Graph => Graph{}                                             |
|                                                                             |
|o1 : MixedGraph                                                              |
+-----------------------------------------------------------------------------+
|i2 : gens gaussianRing(G,lVariableName=>"lambda")                            |
|                                                                             |
|o2 = {lambda   , lambda   , lambda   , p   , p   , p   , p   , p   , s   ,   |
|            b,c        b,d        c,d   a,a   b,b   c,c   d,d   a,d   a,a    |
|     ------------------------------------------------------------------------|
|     s   , s   , s   , s   , s   , s   , s   , s   , s   }                   |
|      a,b   a,c   a,d   b,b   b,c   b,d   c,c   c,d   d,d                    |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

Further information
===================

  * Default value: l
  * Function: gaussianRing, -- ring of Gaussian
    correlations on n random variables or a graphical model
  * Option key: lVariableName, -- optional input to choose
    the variable names for the regression matrix

Functions with optional argument named lVariableName :
======================================================

  * gaussianRing(...,lVariableName=>...)
    -- symbol used for
    indeterminates in a ring of Gaussian joint probability distributions

gaussianRing(...,pVariableName=>...) -- symbol used for indeterminates in a ring of Gaussian joint probability distributions
****************************************************************************************************************************

Synopsis
========

  * Usage:
        gaussianRing(G,pVariableName=>q)
  * Inputs:
      * q, a Symbol (Macaulay2Doc), or a String (Macaulay2Doc),

Description
===========

The option gaussianRing(G,pVariableName=>q) changes the symbol used for
intedeterminates in the covariance matrix of the error terms in a polynomial
ring created with gaussianRing.

+-----------------------------------------------------------------------------+
|i1 : G = mixedGraph(digraph {{b,{c,d}},{c,{d}}},bigraph {{a,d}})             |
|                                                                             |
|o1 = MixedGraph{Bigraph => Bigraph{a => {d}}   }                             |
|                                   d => {a}                                  |
|                Digraph => Digraph{b => {c, d}}                              |
|                                   c => {d}                                  |
|                                   d => {}                                   |
|                Graph => Graph{}                                             |
|                                                                             |
|o1 : MixedGraph                                                              |
+-----------------------------------------------------------------------------+
|i2 : R = gaussianRing G                                                      |
|                                                                             |
|o2 = R                                                                       |
|                                                                             |
|o2 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i3 : gens R                                                                  |
|                                                                             |
|o3 = {l   , l   , l   , p   , p   , p   , p   , p   , s   , s   , s   , s   ,|
|       b,c   b,d   c,d   a,a   b,b   c,c   d,d   a,d   a,a   a,b   a,c   a,d |
|     ------------------------------------------------------------------------|
|     s   , s   , s   , s   , s   , s   }                                     |
|      b,b   b,c   b,d   c,c   c,d   d,d                                      |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : R = gaussianRing (G,pVariableName => psi)                               |
|                                                                             |
|o4 = R                                                                       |
|                                                                             |
|o4 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i5 : gens R                                                                  |
|                                                                             |
|o5 = {l   , l   , l   , psi   , psi   , psi   , psi   , psi   , s   , s   ,  |
|       b,c   b,d   c,d     a,a     b,b     c,c     d,d     a,d   a,a   a,b   |
|     ------------------------------------------------------------------------|
|     s   , s   , s   , s   , s   , s   , s   , s   }                         |
|      a,c   a,d   b,b   b,c   b,d   c,c   c,d   d,d                          |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+

Further information
===================

  * Default value: p
  * Function: gaussianRing, -- ring of Gaussian
    correlations on n random variables or a graphical model
  * Option key: pVariableName, -- optional input to choose
    the variable names for the covariance matrix of the error terms

Functions with optional argument named pVariableName :
======================================================

  * gaussianRing(...,pVariableName=>...)
    -- symbol used for
    indeterminates in a ring of Gaussian joint probability distributions

gaussianRing(...,sVariableName=>...) -- symbol used for indeterminates in a ring of Gaussian joint probability distributions
****************************************************************************************************************************

Synopsis
========

  * Usage:
        gaussianRing(G,sVariableName=>t)
  * Inputs:
      * t, a Symbol (Macaulay2Doc), or a String (Macaulay2Doc),

Description
===========

The option gaussianRing(G,sVariableName=>t) changes the symbol used for
intedeterminates in the covariance matrix in a polynomial ring created with
gaussianRing.

+-----------------------------------------------------------------+
|i1 : R = gaussianRing 4                                          |
|                                                                 |
|o1 = R                                                           |
|                                                                 |
|o1 : PolynomialRing                                              |
+-----------------------------------------------------------------+
|i2 : gens R                                                      |
|                                                                 |
|o2 = {s   , s   , s   , s   , s   , s   , s   , s   , s   , s   }|
|       1,1   1,2   1,3   1,4   2,2   2,3   2,4   3,3   3,4   4,4 |
|                                                                 |
|o2 : List                                                        |
+-----------------------------------------------------------------+
|i3 : Rnew=gaussianRing(4,sVariableName => "t")                   |
|                                                                 |
|o3 = Rnew                                                        |
|                                                                 |
|o3 : PolynomialRing                                              |
+-----------------------------------------------------------------+
|i4 : gens Rnew                                                   |
|                                                                 |
|o4 = {t   , t   , t   , t   , t   , t   , t   , t   , t   , t   }|
|       1,1   1,2   1,3   1,4   2,2   2,3   2,4   3,3   3,4   4,4 |
|                                                                 |
|o4 : List                                                        |
+-----------------------------------------------------------------+

Further information
===================

  * Default value: s
  * Function: gaussianRing, -- ring of Gaussian
    correlations on n random variables or a graphical model
  * Option key: sVariableName, -- optional input to choose
    the variable names for the covariance matrix

Functions with optional argument named sVariableName :
======================================================

  * gaussianRing(...,sVariableName=>...)
    -- symbol used for
    indeterminates in a ring of Gaussian joint probability distributions

gaussianRing(Bigraph) -- ring of Gaussian correlations of a graphical model coming from a bigraph
*************************************************************************************************

Synopsis
========

  * Function: gaussianRing,
  * Usage:
        gaussianRing G
  * Inputs:
      * G, an instance of the type Bigraph (StatGraphs),
  * Optional inputs (Macaulay2Doc),:
      * Coefficients,
        => ..., default value QQ, optional input to choose the base field in
        markovRing or gaussianRing
      * kVariableName,
        => ..., default value "k", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
      * lVariableName,
        => ..., default value "l", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
      * pVariableName,
        => ..., default value "p", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
      * sVariableName,
        => ..., default value "s", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
  * Outputs:
      * a ring (Macaulay2Doc), a ring with indeterminates
        $s_{(i,j)}, p_{(i,j)}$

Description
===========

A gaussianRing of a bidirected graph is built as a gaussianRing of a mixed
graph with only bidirected edges, see gaussianRing(MixedGraph).

+-----------------------------------------------------------------------------+
|i1 : G = bigraph {{a,{b,c}}, {b,{c,d}}, {c,{}}, {d,{}}};                     |
+-----------------------------------------------------------------------------+
|i2 : R = gaussianRing G;                                                     |
+-----------------------------------------------------------------------------+
|i3 : gens R                                                                  |
|                                                                             |
|o3 = {p   , p   , p   , p   , p   , p   , p   , p   , s   , s   , s   , s   ,|
|       a,a   b,b   c,c   d,d   a,c   a,b   b,c   b,d   a,a   a,b   a,c   a,d |
|     ------------------------------------------------------------------------|
|     s   , s   , s   , s   , s   , s   }                                     |
|      b,b   b,c   b,d   c,c   c,d   d,d                                      |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : covarianceMatrix R                                                      |
|                                                                             |
|o4 = | s_(a,a) s_(a,b) s_(a,c) s_(a,d) |                                     |
|     | s_(a,b) s_(b,b) s_(b,c) s_(b,d) |                                     |
|     | s_(a,c) s_(b,c) s_(c,c) s_(c,d) |                                     |
|     | s_(a,d) s_(b,d) s_(c,d) s_(d,d) |                                     |
|                                                                             |
|             4       4                                                       |
|o4 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i5 : directedEdgesMatrix R                                                   |
|                                                                             |
|o5 = 0                                                                       |
|                                                                             |
|             4       4                                                       |
|o5 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i6 : bidirectedEdgesMatrix R                                                 |
|                                                                             |
|o6 = | p_(a,a) p_(a,b) p_(a,c) 0       |                                     |
|     | p_(a,b) p_(b,b) p_(b,c) p_(b,d) |                                     |
|     | p_(a,c) p_(b,c) p_(c,c) 0       |                                     |
|     | 0       p_(b,d) 0       p_(d,d) |                                     |
|                                                                             |
|             4       4                                                       |
|o6 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+

See also
========

  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model

Ways to use this method:
========================

  * gaussianRing(Bigraph) -- ring of Gaussian
    correlations of a graphical model coming from a bigraph

gaussianRing(Digraph) -- ring of Gaussian correlations of a graphical model coming from a digraph
*************************************************************************************************

Synopsis
========

  * Function: gaussianRing,
  * Usage:
        gaussianRing G
  * Inputs:
      * G, a digraph (Graphs),
  * Optional inputs (Macaulay2Doc),:
      * Coefficients,
        => ..., default value QQ, optional input to choose the base field in
        markovRing or gaussianRing
      * kVariableName,
        => ..., default value "k", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
      * lVariableName,
        => ..., default value "l", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
      * pVariableName,
        => ..., default value "p", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
      * sVariableName,
        => ..., default value "s", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
  * Outputs:
      * a ring (Macaulay2Doc), a polynomial ring with
        indeterminates $s_{(i,j)},l_{(i,j)}, p_{(i,j)}$ .

Description
===========

This function creates a polynomial ring in the indeterminates $s_{(i,j)}$
associated to the covariance matrix of the model plus two new lists of
indeterminates:

- The $l_{(i,j)}$ indeterminates consist of regression coefficients associated
to the directed edges in the graph.

- The $p_{(i,j)}$ indeterminates  in the gaussianRing are the nonzero entries
in the covariance matrix of the error terms in the graphical model associated
to a mixed graph with bidirected edges.

Note that since version 2.0 of the package, gaussianRing of a directed graph is
built as a gaussianRing of a mixed graph with only directed edges, see
gaussianRing(MixedGraph).

+-----------------------------------------------------------------------------+
|i1 : G = digraph {{a,{b,c}}, {b,{c,d}}, {c,{}}, {d,{}}};                     |
+-----------------------------------------------------------------------------+
|i2 : R = gaussianRing G;                                                     |
+-----------------------------------------------------------------------------+
|i3 : gens R                                                                  |
|                                                                             |
|o3 = {l   , l   , l   , l   , p   , p   , p   , p   , s   , s   , s   , s   ,|
|       a,c   a,b   b,c   b,d   a,a   b,b   c,c   d,d   a,a   a,b   a,c   a,d |
|     ------------------------------------------------------------------------|
|     s   , s   , s   , s   , s   , s   }                                     |
|      b,b   b,c   b,d   c,c   c,d   d,d                                      |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : covarianceMatrix R                                                      |
|                                                                             |
|o4 = | s_(a,a) s_(a,b) s_(a,c) s_(a,d) |                                     |
|     | s_(a,b) s_(b,b) s_(b,c) s_(b,d) |                                     |
|     | s_(a,c) s_(b,c) s_(c,c) s_(c,d) |                                     |
|     | s_(a,d) s_(b,d) s_(c,d) s_(d,d) |                                     |
|                                                                             |
|             4       4                                                       |
|o4 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i5 : directedEdgesMatrix R                                                   |
|                                                                             |
|o5 = | 0 l_(a,b) l_(a,c) 0       |                                           |
|     | 0 0       l_(b,c) l_(b,d) |                                           |
|     | 0 0       0       0       |                                           |
|     | 0 0       0       0       |                                           |
|                                                                             |
|             4       4                                                       |
|o5 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i6 : bidirectedEdgesMatrix R                                                 |
|                                                                             |
|o6 = | p_(a,a) 0       0       0       |                                     |
|     | 0       p_(b,b) 0       0       |                                     |
|     | 0       0       p_(c,c) 0       |                                     |
|     | 0       0       0       p_(d,d) |                                     |
|                                                                             |
|             4       4                                                       |
|o6 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * gaussianRing(Digraph) -- ring of Gaussian
    correlations of a graphical model coming from a digraph

gaussianRing(Graph) -- ring of Gaussian correlations of a graphical model coming from an undirected graph
*********************************************************************************************************

Synopsis
========

  * Function: gaussianRing,
  * Usage:
        gaussianRing G
  * Inputs:
      * G, a graph (Graphs),
  * Optional inputs (Macaulay2Doc),:
      * Coefficients,
        => ..., default value QQ, optional input to choose the base field in
        markovRing or gaussianRing
      * kVariableName,
        => ..., default value "k", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
      * lVariableName,
        => ..., default value "l", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
      * pVariableName,
        => ..., default value "p", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
      * sVariableName,
        => ..., default value "s", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
  * Outputs:
      * a ring (Macaulay2Doc), a polynomial ring with
        indeterminates $s_{(i,j)}$ and $k_{(i,j)}$

Description
===========

This function creates a polynomial ring with indeterminates $s_{(i,j)}$ for $1
\leq i \leq j \leq n$, where $n$ is the number of vertices in $G$, and
$k_{(i,j)}$.

The $s_{(i,j)}$ indeterminates in the gaussianRing are the entries in the
covariance matrix of the jointly normal random variables.

The $k_{(i,j)}$ indeterminates in the gaussianRing are the nonzero entries in
the concentration matrix in the graphical model associated to the undirected
graph.

+-----------------------------------------------------------------------------+
|i1 : G = graph({{a,b},{b,c},{c,d},{a,d}})                                    |
|                                                                             |
|o1 = Graph{a => {b, d}}                                                      |
|           b => {a, c}                                                       |
|           c => {b, d}                                                       |
|           d => {a, c}                                                       |
|                                                                             |
|o1 : Graph                                                                   |
+-----------------------------------------------------------------------------+
|i2 : R = gaussianRing G                                                      |
|                                                                             |
|o2 = R                                                                       |
|                                                                             |
|o2 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i3 : gens R                                                                  |
|                                                                             |
|o3 = {k   , k   , k   , k   , k   , k   , k   , k   , s   , s   , s   , s   ,|
|       a,a   b,b   c,c   d,d   a,b   a,d   b,c   c,d   a,a   a,b   a,c   a,d |
|     ------------------------------------------------------------------------|
|     s   , s   , s   , s   , s   , s   }                                     |
|      b,b   b,c   b,d   c,c   c,d   d,d                                      |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : covarianceMatrix R                                                      |
|                                                                             |
|o4 = | s_(a,a) s_(a,b) s_(a,c) s_(a,d) |                                     |
|     | s_(a,b) s_(b,b) s_(b,c) s_(b,d) |                                     |
|     | s_(a,c) s_(b,c) s_(c,c) s_(c,d) |                                     |
|     | s_(a,d) s_(b,d) s_(c,d) s_(d,d) |                                     |
|                                                                             |
|             4       4                                                       |
|o4 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i5 : undirectedEdgesMatrix R                                                 |
|                                                                             |
|o5 = | k_(a,a) k_(a,b) 0       k_(a,d) |                                     |
|     | k_(a,b) k_(b,b) k_(b,c) 0       |                                     |
|     | 0       k_(b,c) k_(c,c) k_(c,d) |                                     |
|     | k_(a,d) 0       k_(c,d) k_(d,d) |                                     |
|                                                                             |
|             4       4                                                       |
|o5 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+

See also
========

  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model

Ways to use this method:
========================

  * gaussianRing(Graph) -- ring of Gaussian
    correlations of a graphical model coming from an undirected graph

gaussianRing(MixedGraph) -- ring of Gaussian correlations of a graphical model coming from a mixed graph
********************************************************************************************************

Synopsis
========

  * Function: gaussianRing,
  * Usage:
        gaussianRing G
  * Inputs:
      * G, an instance of the type MixedGraph (StatGraphs),
  * Optional inputs (Macaulay2Doc),:
      * Coefficients,
        => ..., default value QQ, optional input to choose the base field in
        markovRing or gaussianRing
      * kVariableName,
        => ..., default value "k", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
      * lVariableName,
        => ..., default value "l", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
      * pVariableName,
        => ..., default value "p", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
      * sVariableName,
        => ..., default value "s", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
  * Outputs:
      * a ring (Macaulay2Doc), a polynomial ring with
        indeterminates $s_{(i,j)},k_{(i,j)},l_{(i,j)},p_{(i,j)}$

Description
===========

This function accepts a mixed graph as input. The outputted ring contains the
indeterminates $s_{(i,j)}$ associated to the covariance matrix of the model
plus two or three new lists of indeterminates depending on the type of edges of
the graph:

- The $k_{(i,j)}$ indeterminates in the gaussianRing are the nonzero entries in
the concentration matrix in the graphical model associated to the undirected
graph.

- The $l_{(i,j)}$ indeterminates consist of regression coefficients associated
to the directed edges in the graph.

- The $p_{(i,j)}$ indeterminates  in the gaussianRing are the nonzero entries
in the covariance matrix of the error terms in the graphical model associated
to a mixed graph with bidirected edges.

Mixed graphs in this package can be of two different types depending on their
edges:

Directed and bidirected edges: two new lists of indeterminates. For each
directed edge $i \to j$ in the mixed graph there is an indeterminate, denoted
by default $l_{(i,j)}$, corresponding to the associated direct causal effect
parameter in the model. For each  bidirected edge $i$<->$j$ there is an
indeterminate, denoted by default $p_{(i,j)}$, corresponding to the associated
noise parameter. Finally, for each node $i$, there is an indeterminate
$p_{(i,i)}$.

+-----------------------------------------------------------------------------+
|i1 : G = mixedGraph(digraph {{b,{c,d}},{c,{d}}},bigraph {{a,d}})             |
|                                                                             |
|o1 = MixedGraph{Bigraph => Bigraph{a => {d}}   }                             |
|                                   d => {a}                                  |
|                Digraph => Digraph{b => {c, d}}                              |
|                                   c => {d}                                  |
|                                   d => {}                                   |
|                Graph => Graph{}                                             |
|                                                                             |
|o1 : MixedGraph                                                              |
+-----------------------------------------------------------------------------+
|i2 : R = gaussianRing G                                                      |
|                                                                             |
|o2 = R                                                                       |
|                                                                             |
|o2 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i3 : gens R                                                                  |
|                                                                             |
|o3 = {l   , l   , l   , p   , p   , p   , p   , p   , s   , s   , s   , s   ,|
|       b,c   b,d   c,d   a,a   b,b   c,c   d,d   a,d   a,a   a,b   a,c   a,d |
|     ------------------------------------------------------------------------|
|     s   , s   , s   , s   , s   , s   }                                     |
|      b,b   b,c   b,d   c,c   c,d   d,d                                      |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : covarianceMatrix R                                                      |
|                                                                             |
|o4 = | s_(a,a) s_(a,b) s_(a,c) s_(a,d) |                                     |
|     | s_(a,b) s_(b,b) s_(b,c) s_(b,d) |                                     |
|     | s_(a,c) s_(b,c) s_(c,c) s_(c,d) |                                     |
|     | s_(a,d) s_(b,d) s_(c,d) s_(d,d) |                                     |
|                                                                             |
|             4       4                                                       |
|o4 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i5 : directedEdgesMatrix R                                                   |
|                                                                             |
|o5 = | 0 0 0       0       |                                                 |
|     | 0 0 l_(b,c) l_(b,d) |                                                 |
|     | 0 0 0       l_(c,d) |                                                 |
|     | 0 0 0       0       |                                                 |
|                                                                             |
|             4       4                                                       |
|o5 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i6 : bidirectedEdgesMatrix R                                                 |
|                                                                             |
|o6 = | p_(a,a) 0       0       p_(a,d) |                                     |
|     | 0       p_(b,b) 0       0       |                                     |
|     | 0       0       p_(c,c) 0       |                                     |
|     | p_(a,d) 0       0       p_(d,d) |                                     |
|                                                                             |
|             4       4                                                       |
|o6 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+

Undirected, directed and bidirected edges: three new lists of indeterminates.
Besides the two already described above, undirected edges are dealt with in the
same way as in gaussianRing applied to a graph (Graphs), with the
corresponding indeterminates being $k_{(i,j)}$ by default.

Only loopless mixed graphs are accepted and they must have a vertex ordering
compatible with partitionLMG (StatGraphs). For more details
about loopless mixed graphs, see the paper: Kayvan Sadeghi and Steffen
Lauritzen, Markov properties for mixed graphs, Bernoulli, 20 (2014), no 2,
676-696.

Be aware that several functions in this package that accept mixed graphs are
still not implemented for mixed graphs with undirected edges:
gaussianParametrization,
gaussianVanishingIdeal, trekIdeal,
trekSeparation, identifyParameters.

+-----------------------------------------------------------------------------+
|i7 : G = mixedGraph(digraph {{1,3},{2,4}},bigraph {{3,4}},graph {{1,2}});    |
+-----------------------------------------------------------------------------+
|i8 : R = gaussianRing G                                                      |
|                                                                             |
|o8 = R                                                                       |
|                                                                             |
|o8 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i9 : gens R                                                                  |
|                                                                             |
|o9 = {k   , k   , k   , l   , l   , p   , p   , p   , s   , s   , s   , s   ,|
|       1,1   2,2   1,2   1,3   2,4   3,3   4,4   3,4   1,1   1,2   1,3   1,4 |
|     ------------------------------------------------------------------------|
|     s   , s   , s   , s   , s   , s   }                                     |
|      2,2   2,3   2,4   3,3   3,4   4,4                                      |
|                                                                             |
|o9 : List                                                                    |
+-----------------------------------------------------------------------------+
|i10 : covarianceMatrix R                                                     |
|                                                                             |
|o10 = | s_(1,1) s_(1,2) s_(1,3) s_(1,4) |                                    |
|      | s_(1,2) s_(2,2) s_(2,3) s_(2,4) |                                    |
|      | s_(1,3) s_(2,3) s_(3,3) s_(3,4) |                                    |
|      | s_(1,4) s_(2,4) s_(3,4) s_(4,4) |                                    |
|                                                                             |
|              4       4                                                      |
|o10 : Matrix R  <--- R                                                       |
+-----------------------------------------------------------------------------+
|i11 : undirectedEdgesMatrix R                                                |
|                                                                             |
|o11 = | k_(1,1) k_(1,2) |                                                    |
|      | k_(1,2) k_(2,2) |                                                    |
|                                                                             |
|              2       2                                                      |
|o11 : Matrix R  <--- R                                                       |
+-----------------------------------------------------------------------------+
|i12 : directedEdgesMatrix R                                                  |
|                                                                             |
|o12 = | 0 0 l_(1,3) 0       |                                                |
|      | 0 0 0       l_(2,4) |                                                |
|      | 0 0 0       0       |                                                |
|      | 0 0 0       0       |                                                |
|                                                                             |
|              4       4                                                      |
|o12 : Matrix R  <--- R                                                       |
+-----------------------------------------------------------------------------+
|i13 : bidirectedEdgesMatrix R                                                |
|                                                                             |
|o13 = | p_(3,3) p_(3,4) |                                                    |
|      | p_(3,4) p_(4,4) |                                                    |
|                                                                             |
|              2       2                                                      |
|o13 : Matrix R  <--- R                                                       |
+-----------------------------------------------------------------------------+

See also
========

  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model

Ways to use this method:
========================

  * gaussianRing(MixedGraph) -- ring of
    Gaussian correlations of a graphical model coming from a mixed graph

gaussianRing(ZZ) -- ring of Gaussian correlations on n random variables
***********************************************************************

Synopsis
========

  * Function: gaussianRing,
  * Usage:
        gaussianRing n
  * Inputs:
      * n, an integer (Macaulay2Doc), the number of random variables
  * Optional inputs (Macaulay2Doc),:
      * Coefficients,
        => ..., default value QQ, optional input to choose the base field in
        markovRing or gaussianRing
      * kVariableName,
        => ..., default value "k", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
      * lVariableName,
        => ..., default value "l", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
      * pVariableName,
        => ..., default value "p", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
      * sVariableName,
        => ..., default value "s", symbol used for indeterminates in a
        ring of Gaussian joint probability distributions
  * Outputs:
      * a ring (Macaulay2Doc), a ring with indeterminates
        $s_{(i,j)}$ for $1 \leq i \leq j \leq n$

Description
===========

This function creates a polynomial ring with indeterminates $s_{(i,j)}$ for $1
\leq i \leq j \leq n$. The $s_{(i,j)}$ indeterminates in the gaussianRing are
the entries in the covariance matrix of the jointly normal random variables.

+-----------------------------------------------------------------------------+
|i1 : R = gaussianRing 5;                                                     |
+-----------------------------------------------------------------------------+
|i2 : gens R                                                                  |
|                                                                             |
|o2 = {s   , s   , s   , s   , s   , s   , s   , s   , s   , s   , s   , s   ,|
|       1,1   1,2   1,3   1,4   1,5   2,2   2,3   2,4   2,5   3,3   3,4   3,5 |
|     ------------------------------------------------------------------------|
|     s   , s   , s   }                                                       |
|      4,4   4,5   5,5                                                        |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : compactMatrixForm =false;                                               |
+-----------------------------------------------------------------------------+
|i4 : covarianceMatrix R                                                      |
|                                                                             |
|o4 = |  s     s     s     s     s     |                                      |
|     |   1,1   1,2   1,3   1,4   1,5  |                                      |
|     |                                |                                      |
|     |  s     s     s     s     s     |                                      |
|     |   1,2   2,2   2,3   2,4   2,5  |                                      |
|     |                                |                                      |
|     |  s     s     s     s     s     |                                      |
|     |   1,3   2,3   3,3   3,4   3,5  |                                      |
|     |                                |                                      |
|     |  s     s     s     s     s     |                                      |
|     |   1,4   2,4   3,4   4,4   4,5  |                                      |
|     |                                |                                      |
|     |  s     s     s     s     s     |                                      |
|     |   1,5   2,5   3,5   4,5   5,5  |                                      |
|                                                                             |
|             5       5                                                       |
|o4 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+

See also
========

  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model

Ways to use this method:
========================

  * gaussianRing(ZZ) -- ring of Gaussian
    correlations on n random variables

gaussianRingData -- hash table with main parameters of a gaussian ring
**********************************************************************

Description
===========

The contents of gaussianRingData depend on the type of gaussian ring.

First, we show an example of a gaussian ring with 5 variables

+-----------------------+
|i1 : R = gaussianRing 5|
|                       |
|o1 = R                 |
|                       |
|o1 : PolynomialRing    |
+-----------------------+
|i2 : gaussianRingData  |
|                       |
|o2 = gaussianRingData  |
|                       |
|o2 : Symbol            |
+-----------------------+

In case of the gaussian ring of a graph, there are two options. First one, is
when the graph is of class Graph (Graphs), .

+---------------------------------------+
|i3 : R=gaussianRing graph {{1,2},{2,3}}|
|                                       |
|o3 = R                                 |
|                                       |
|o3 : PolynomialRing                    |
+---------------------------------------+
|i4 : R.gaussianRingData                |
|                                       |
|o4 = HashTable{kVar => k}              |
|               nn => 3                 |
|               sVar => s               |
|                                       |
|o4 : HashTable                         |
+---------------------------------------+

If the graph is of any other class -i.e.,  see Bigraph (StatGraphs),
Digraph (Graphs), MixedGraph (StatGraphs), -
then it is internally converted to a MixedGraph (StatGraphs),
and the gaussianRingData has the same structure.

+-----------------------------------------+
|i5 : U = graph {{1,2},{2,3}}             |
|                                         |
|o5 = Graph{1 => {2}   }                  |
|           2 => {1, 3}                   |
|           3 => {2}                      |
|                                         |
|o5 : Graph                               |
+-----------------------------------------+
|i6 : B = bigraph{{4,5}}                  |
|                                         |
|o6 = Bigraph{4 => {5}}                   |
|             5 => {4}                    |
|                                         |
|o6 : Bigraph                             |
+-----------------------------------------+
|i7 : D = digraph {{1,4}}                 |
|                                         |
|o7 = Digraph{1 => {4}}                   |
|             4 => {}                     |
|                                         |
|o7 : Digraph                             |
+-----------------------------------------+
|i8 : R1 = gaussianRing B                 |
|                                         |
|o8 = R1                                  |
|                                         |
|o8 : PolynomialRing                      |
+-----------------------------------------+
|i9 : R2 = gaussianRing D                 |
|                                         |
|o9 = R2                                  |
|                                         |
|o9 : PolynomialRing                      |
+-----------------------------------------+
|i10 : R3 = gaussianRing mixedGraph(U,B,D)|
|                                         |
|o10 = R3                                 |
|                                         |
|o10 : PolynomialRing                     |
+-----------------------------------------+
|i11 : R1.gaussianRingData                |
|                                         |
|o11 = HashTable{compU => {}    }         |
|                compW => {4, 5}          |
|                kVar => k                |
|                lVar => l                |
|                nn => 2                  |
|                pVar => p                |
|                sVar => s                |
|                                         |
|o11 : HashTable                          |
+-----------------------------------------+
|i12 : R2.gaussianRingData                |
|                                         |
|o12 = HashTable{compU => {}    }         |
|                compW => {1, 4}          |
|                kVar => k                |
|                lVar => l                |
|                nn => 2                  |
|                pVar => p                |
|                sVar => s                |
|                                         |
|o12 : HashTable                          |
+-----------------------------------------+
|i13 : R3.gaussianRingData                |
|                                         |
|o13 = HashTable{compU => {1, 2, 3}}      |
|                compW => {4, 5}          |
|                kVar => k                |
|                lVar => l                |
|                nn => 5                  |
|                pVar => p                |
|                sVar => s                |
|                                         |
|o13 : HashTable                          |
+-----------------------------------------+

See also
========

  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model
  * kVar -- key in hash table gaussianRingData: labels of k
    variables
  * pVar -- key in hash table gaussianRingData: labels of p
    variables
  * lVar -- key in hash table gaussianRingData: labels of l
    variables
  * sVar -- key in hash table gaussianRingData: labels of s
    variables
  * compU -- key in hash table gaussianRingData: component of
    undirected edges in vertex set of a mixed graph
  * compW -- key in hash table gaussianRingData: component of
    bidirected edges in vertex set of a mixed graph
  * nn -- key in hash table gaussianRingData: total number of
    variables

For the programmer
==================

The object gaussianRingData, is a symbol (Macaulay2Doc).

gaussianVanishingIdeal -- vanishing ideal of a Gaussian graphical model
***********************************************************************

Synopsis
========

  * Usage:
        gaussianVanishingIdeal(R)
  * Inputs:
      * R, a ring (Macaulay2Doc), created with gaussianRing,
        using a graphs of classes Graph (Graphs),
        Digraph (Graphs), or  MixedGraph (StatGraphs),
        without undirected edges as input.
  * Optional inputs (Macaulay2Doc),:
      * OldVersion,
        => ..., default value false, optional argument in
        gaussianVanishingIdeal to use old method for gaussianRings coming from
        directed graphs
  * Outputs:
      * an ideal (Macaulay2Doc), ideal in R

Description
===========

gaussianVanishingIdeal computes the ideal in $R$ of homogeneous polynomial
relations on the variance-covariance parameters of a graphical model on $G$ as
explained in Chapter 3.3 of ``Lectures on Algebraic Statistics'' by Drton,
Sturmfels, and Sullivant.

+-----------------------------------------------------------------------------+
|i1 : G = graph({{a,b},{b,c},{c,d},{a,d}})                                    |
|                                                                             |
|o1 = Graph{a => {b, d}}                                                      |
|           b => {a, c}                                                       |
|           c => {b, d}                                                       |
|           d => {a, c}                                                       |
|                                                                             |
|o1 : Graph                                                                   |
+-----------------------------------------------------------------------------+
|i2 : R = gaussianRing G                                                      |
|                                                                             |
|o2 = R                                                                       |
|                                                                             |
|o2 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i3 : J = gaussianVanishingIdeal(R);                                          |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i4 : ideal mingens J / print;                                                |
|                    2                                                        |
|s   s   s    - s   s    - s   s   s    + s   s   s    + s   s   s    -       |
| a,d b,c b,d    a,c b,d    a,d b,b c,d    a,b b,d c,d    a,c b,b d,d         |
|                2                                                            |
|s   s   s    - s   s    - s   s   s    + s   s   s    + s   s   s    -       |
| a,c a,d b,c    a,c b,d    a,b a,d c,c    a,a b,d c,c    a,b a,c c,d         |
|-----------------------------------------------------------------------------|
|s   s   s                                                                    |
| a,b b,c d,d                                                                 |
|                                                                             |
|s   s   s                                                                    |
| a,a b,c c,d                                                                 |
+-----------------------------------------------------------------------------+

This method works for graphs, digraphs and mixed graphs without undirected
edges.

+---------------------------------------------------------------------------+
|i5 : G = digraph {{a,{b,c}}, {b,{c,d}}, {c,{}}, {d,{}}}                    |
|                                                                           |
|o5 = Digraph{a => {c, b}}                                                  |
|             b => {c, d}                                                   |
|             c => {}                                                       |
|             d => {}                                                       |
|                                                                           |
|o5 : Digraph                                                               |
+---------------------------------------------------------------------------+
|i6 : R = gaussianRing G                                                    |
|                                                                           |
|o6 = R                                                                     |
|                                                                           |
|o6 : PolynomialRing                                                        |
+---------------------------------------------------------------------------+
|i7 : gaussianVanishingIdeal(R)                                             |
|                                                                           |
|o7 = ideal (s   s    - s   s   , s   s    - s   s   , s   s    - s   s   ) |
|             b,c b,d    b,b c,d   a,d b,c    a,b c,d   a,d b,b    a,b b,d  |
|                                                                           |
|o7 : Ideal of R                                                            |
+---------------------------------------------------------------------------+
|i8 : H = mixedGraph(digraph {{a,{c}},{b,{c}}, {c,{d}}},bigraph {{c,d}})    |
|                                                                           |
|o8 = MixedGraph{Bigraph => Bigraph{c => {d}}}                              |
|                                   d => {c}                                |
|                Digraph => Digraph{a => {c}}                               |
|                                   b => {c}                                |
|                                   c => {d}                                |
|                                   d => {}                                 |
|                Graph => Graph{}                                           |
|                                                                           |
|o8 : MixedGraph                                                            |
+---------------------------------------------------------------------------+
|i9 : S = gaussianRing H                                                    |
|                                                                           |
|o9 = R                                                                     |
|                                                                           |
|o9 : PolynomialRing                                                        |
+---------------------------------------------------------------------------+
|i10 : gaussianVanishingIdeal(S)                                            |
|                                                                           |
|o10 = ideal (s   s    - s   s   , s   s    - s   s   , s   s    - s   s   )|
|              b,c b,d    b,b c,d   a,d b,c    a,b c,d   a,d b,b    a,b b,d |
|                                                                           |
|o10 : Ideal of R                                                           |
+---------------------------------------------------------------------------+

Caveat
======

This method currently works on really small examples because it computes the
vanishing ideal as an elimination ideal.

See also
========

  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model
  * trekIdeal -- trek separation ideal of a mixed graph
  * OldVersion -- optional argument in
    gaussianVanishingIdeal to use old method for gaussianRings coming from
    directed graphs

Ways to use gaussianVanishingIdeal :
====================================

  * "gaussianVanishingIdeal(Ring)"

For the programmer
==================

The object gaussianVanishingIdeal, is a
method function with options (Macaulay2Doc).

gaussianVanishingIdeal(...,OldVersion=>...) -- optional argument in gaussianVanishingIdeal to use old method for gaussianRings coming from directed graphs
**********************************************************************************************************************************************************

Synopsis
========

  * Usage:
        gaussianVanishingIdeal(R,G,OldVersion=>false)
  * Inputs:
      * b, a Boolean value (Macaulay2Doc), false by default

Description
===========

By default, see gaussianVanishingIdeal, uses the code
of the current version. However, if the graph only has directed edges, the user
can choose to use the code from the previous version which is based on (2) from
Seth Sullivant, Kelli Talaska, and Jan Draisma, Trek separation for Gaussian
graphical models, The Annals of Statistics 38.3 (2010): 1665-1685.

Further information
===================

  * Default value: false (Macaulay2Doc),
  * Function: gaussianVanishingIdeal, --
    vanishing ideal of a Gaussian graphical model
  * Option key: OldVersion, -- optional argument in
    gaussianVanishingIdeal to use old method for gaussianRings coming from
    directed graphs

See also
========

  * gaussianVanishingIdeal -- vanishing ideal of
    a Gaussian graphical model

Functions with optional argument named OldVersion :
===================================================

  * gaussianVanishingIdeal(...,OldVersion=>...)
    -- optional
    argument in gaussianVanishingIdeal to use old method for gaussianRings
    coming from directed graphs

globalMarkov -- global Markov statements for a graph or a directed graph
************************************************************************

Synopsis
========

  * Usage:
        globalMarkov G
  * Inputs:
      * G, a graph (Graphs), or a digraph (Graphs),
  * Outputs:
      * a list (Macaulay2Doc), whose entries are triples {A,B,C}
        representing global Markov  conditional independence statements of the
        form ``A is independent of B given C'' that hold for G.

Description
===========

Given an undirected graph $G$, a global Markov statement is of the form $\{A,
B, C\}$, where the subset $C$ separates the subset $A$ from the subset $B$ in
the graph $G$.

For example, for the undirected  5-cycle graph $G$, that is, the graph on 5
vertices with $a—b—c—d—e—a$, we get the following global Markov statements:

+-----------------------------------------------------------------------------+
|i1 : G = graph({{a,b},{b,c},{c,d},{d,e},{e,a}})                              |
|                                                                             |
|o1 = Graph{a => {b, e}}                                                      |
|           b => {a, c}                                                       |
|           c => {b, d}                                                       |
|           d => {c, e}                                                       |
|           e => {a, d}                                                       |
|                                                                             |
|o1 : Graph                                                                   |
+-----------------------------------------------------------------------------+
|i2 : globalMarkov G                                                          |
|                                                                             |
|o2 = {{{a}, {c, d}, {e, b}}, {{b, c}, {e}, {d, a}}, {{a, e}, {c}, {d, b}},   |
|     ------------------------------------------------------------------------|
|     {{a, b}, {d}, {c, e}}, {{b}, {d, e}, {c, a}}}                           |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

Given a directed acyclic graph $G$, global Markov states that $A$ is
independent of $B$ given $C$ for every triple of sets of vertices $A$, $B$, and
$C$, such that $A$ and $B$ are $d$-separated by $C$ (in the graph $G$).\break

The global independent statements of a directed graph are computed using the
Bayes-Ball algorithm, as described in the paper Ross D. Shachter, Bayes-Ball:
The Rational Pastime (for Determining Irrelevance and Requisite Information in
Belief Networks and Influence Diagrams)  In Proceedings of the Fourteenth
Conference in Uncertainty in Artificial Intelligence, p. 480–487, 1998.

For example, given the digraph $D$ on $7$ vertices with edges $1 \to 2, 1 \to
3, 2 \to 4, 2 \to 5, 3 \to 5, 3 \to 6, 4 \to 7, 5 \to 7$, and $6\to 7$, we get
the following global Markov statements:

+-----------------------------------------------------------------------------+
|i3 : D = digraph {{1,{2,3}}, {2,{4,5}}, {3,{5,6}}, {4,{7}},                  |
|                                                                             |
|o3 = Digraph{1 => {2, 3}}                                                    |
|             2 => {4, 5}                                                     |
|             3 => {5, 6}                                                     |
|             4 => {7}                                                        |
|             5 => {7}                                                        |
|             6 => {7}                                                        |
|             7 => {}                                                         |
|                                                                             |
|o3 : Digraph                                                                 |
|-----------------------------------------------------------------------------|
|{5,{7}},{6,{7}},{7,{}}}                                                      |
+-----------------------------------------------------------------------------+
|i4 : netList pack (3, globalMarkov D)                                        |
|                                                                             |
|     +---------------------------+---------------------------+---------------|
|o4 = |{{1}, {4, 5, 6, 7}, {2, 3}}|{{2, 4}, {3, 6}, {1}}      |{{1, 3}, {4, 7}|
|     +---------------------------+---------------------------+---------------|
|     |{{1, 4}, {5, 6}, {2, 3}}   |{{1, 6}, {4, 5}, {2, 3}}   |{{1, 5}, {4, 6}|
|     +---------------------------+---------------------------+---------------|
|     |{{1, 2}, {6, 7}, {4, 5, 3}}|{{1, 2, 4, 5}, {6}, {3}}   |{{1, 3, 5, 6}, |
|     +---------------------------+---------------------------+---------------|
|     |{{1, 4, 6}, {5}, {2, 3}}   |{{1, 2, 3}, {7}, {4, 5, 6}}|               |
|     +---------------------------+---------------------------+---------------|
|-----------------------------------------------------------------------------|
|------------+                                                                |
|, {5, 6, 2}}|                                                                |
|------------+                                                                |
|, {2, 3}}   |                                                                |
|------------+                                                                |
|{4}, {2}}   |                                                                |
|------------+                                                                |
|            |                                                                |
|------------+                                                                |
+-----------------------------------------------------------------------------+

This method displays only non-redundant statements. In general, given a set $S$
of conditional independent statements and a statement $s$, then we say that $s$
is a a redundant statement if $s$ can be obtained from the statements in $S$
using the semigraphoid axioms of conditional independence: symmetry,
decomposition, weak union,  and contraction as described in Section 1.1 of
Judea Pearl, Causality: models, reasoning, and inference, Cambridge University
Press.  We do not use the intersection axiom since it is only valid for
strictly positive probability distributions.

Caveat
======

See also
========

  * localMarkov -- local Markov statements for a graph or a
    directed graph
  * pairMarkov -- pairwise Markov statements for a graph or
    a  directed graph

Ways to use globalMarkov :
==========================

  * "globalMarkov(Digraph)"
  * "globalMarkov(Graph)"

For the programmer
==================

The object globalMarkov, is a method function (Macaulay2Doc).

graphType -- class of graph used to generate a gaussian ring
************************************************************

Description
===========

For a gaussianRing R generated with a digraph (Graphs), and an
instance of the type Bigraph (StatGraphs), the class we retrieve
when typing R.graph is MixedGraph. This is consistent with the treatment of
such objects. Therefore, this variable is essentially used to differentiate
graphs from a graph (Graphs), and an instance of the type
MixedGraph (StatGraphs).

See also
========

  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model
  * gaussianRingData -- hash table with main
    parameters of a gaussian ring

For the programmer
==================

The object graphType, is a symbol (Macaulay2Doc).

hiddenMap -- linear map between the ring of a model with one hidden variable and the ring of the corresponding fully observed model
***********************************************************************************************************************************

Synopsis
========

  * Usage:
        hiddenMap(i,R)
  * Inputs:
      * i, an integer (Macaulay2Doc), the index corresponding to the
        hidden random variable
      * R, a ring (Macaulay2Doc), a markovRing
  * Outputs:
      * a ring map (Macaulay2Doc),

Description
===========

The ring $R$ is  a ring of probability distributions on $n$ random variables
created using markovRing. This method creates a ring map $F: S \to R$ from the
ring $S$ of probability distributions on $n-1$ random variables, leaving out
the $i$th random variable from $R$. This corresponds to the situation where the
$i$th random variable is hidden and $S$ is the ring of observed probability
distributions.

+------------------------------------------------------------+
|i1 : F = hiddenMap(1,markovRing(2,3,2));                    |
|                                                            |
|o1 : RingMap QQ[p     ..p     ] <--- QQ[p   ..p   ]         |
|                 1,1,1   2,3,2           1,1   3,2          |
+------------------------------------------------------------+
|i2 : compactMatrixForm =false;                              |
+------------------------------------------------------------+
|i3 : transpose F.matrix                                     |
|                                                            |
|o3 = {-1}  |  p      + p       |                            |
|           |   1,1,1    2,1,1  |                            |
|           |                   |                            |
|     {-1}  |  p      + p       |                            |
|           |   1,1,2    2,1,2  |                            |
|           |                   |                            |
|     {-1}  |  p      + p       |                            |
|           |   1,2,1    2,2,1  |                            |
|           |                   |                            |
|     {-1}  |  p      + p       |                            |
|           |   1,2,2    2,2,2  |                            |
|           |                   |                            |
|     {-1}  |  p      + p       |                            |
|           |   1,3,1    2,3,1  |                            |
|           |                   |                            |
|     {-1}  |  p      + p       |                            |
|           |   1,3,2    2,3,2  |                            |
|                                                            |
|                                6                          1|
|o3 : Matrix (QQ[p     ..p     ])  <--- (QQ[p     ..p     ]) |
|                 1,1,1   2,3,2              1,1,1   2,3,2   |
+------------------------------------------------------------+

This method is frequently used when computing the vanishing ideal of a
graphical model with hidden variables by computing the kernel of $F$. For more
details see the paper ``Algebraic Geometry of Bayesian Networks'' by Garcia,
Stillman, and Sturmfels.

+----------------------------------------------------+
|i4 : G = digraph  {{1,{}},{2,{}},{3,{}},{4,{1,2,3}}}|
|                                                    |
|o4 = Digraph{1 => {}       }                        |
|             2 => {}                                |
|             3 => {}                                |
|             4 => {1, 2, 3}                         |
|                                                    |
|o4 : Digraph                                        |
+----------------------------------------------------+
|i5 : R = markovRing (2,2,3,2)                       |
|                                                    |
|o5 = R                                              |
|                                                    |
|o5 : PolynomialRing                                 |
+----------------------------------------------------+
|i6 : I = discreteVanishingIdeal (R,G);              |
|                                                    |
|o6 : Ideal of R                                     |
+----------------------------------------------------+
|i7 : I / print;                                     |
|p       p        - p       p                        |
| 1,2,3,2 2,2,3,1    1,2,3,1 2,2,3,2                 |
|p       p        - p       p                        |
| 1,2,3,2 2,2,2,2    1,2,2,2 2,2,3,2                 |
|p       p        - p       p                        |
| 1,2,3,2 2,2,2,1    1,2,2,1 2,2,3,2                 |
|p       p        - p       p                        |
| 1,2,3,2 2,2,1,2    1,2,1,2 2,2,3,2                 |
|p       p        - p       p                        |
| 1,2,3,2 2,2,1,1    1,2,1,1 2,2,3,2                 |
|p       p        - p       p                        |
| 2,2,2,2 2,2,3,1    2,2,2,1 2,2,3,2                 |
|p       p        - p       p                        |
| 1,2,2,2 2,2,3,1    1,2,2,1 2,2,3,2                 |
|p       p        - p       p                        |
| 2,2,1,2 2,2,3,1    2,2,1,1 2,2,3,2                 |
|p       p        - p       p                        |
| 1,2,1,2 2,2,3,1    1,2,1,1 2,2,3,2                 |
|p       p        - p       p                        |
| 1,2,3,1 2,2,2,2    1,2,2,1 2,2,3,2                 |
|p       p        - p       p                        |
| 1,2,2,2 1,2,3,1    1,2,2,1 1,2,3,2                 |
|p       p        - p       p                        |
| 1,2,3,1 2,2,2,1    1,2,2,1 2,2,3,1                 |
|p       p        - p       p                        |
| 1,2,3,1 2,2,1,2    1,2,1,1 2,2,3,2                 |
|p       p        - p       p                        |
| 1,2,1,2 1,2,3,1    1,2,1,1 1,2,3,2                 |
|p       p        - p       p                        |
| 1,2,3,1 2,2,1,1    1,2,1,1 2,2,3,1                 |
|p       p        - p       p                        |
| 1,2,2,2 2,2,2,1    1,2,2,1 2,2,2,2                 |
|p       p        - p       p                        |
| 1,2,2,2 2,2,1,2    1,2,1,2 2,2,2,2                 |
|p       p        - p       p                        |
| 1,2,2,2 2,2,1,1    1,2,1,1 2,2,2,2                 |
|p       p        - p       p                        |
| 2,2,1,2 2,2,2,1    2,2,1,1 2,2,2,2                 |
|p       p        - p       p                        |
| 1,2,1,2 2,2,2,1    1,2,1,1 2,2,2,2                 |
|p       p        - p       p                        |
| 1,2,2,1 2,2,1,2    1,2,1,1 2,2,2,2                 |
|p       p        - p       p                        |
| 1,2,1,2 1,2,2,1    1,2,1,1 1,2,2,2                 |
|p       p        - p       p                        |
| 1,2,2,1 2,2,1,1    1,2,1,1 2,2,2,1                 |
|p       p        - p       p                        |
| 1,2,1,2 2,2,1,1    1,2,1,1 2,2,1,2                 |
|p       p        - p       p                        |
| 1,1,3,2 2,1,3,1    1,1,3,1 2,1,3,2                 |
|p       p        - p       p                        |
| 1,1,3,2 2,1,2,2    1,1,2,2 2,1,3,2                 |
|p       p        - p       p                        |
| 1,1,3,2 2,1,2,1    1,1,2,1 2,1,3,2                 |
|p       p        - p       p                        |
| 1,1,3,2 2,1,1,2    1,1,1,2 2,1,3,2                 |
|p       p        - p       p                        |
| 1,1,3,2 2,1,1,1    1,1,1,1 2,1,3,2                 |
|p       p        - p       p                        |
| 2,1,2,2 2,1,3,1    2,1,2,1 2,1,3,2                 |
|p       p        - p       p                        |
| 1,1,2,2 2,1,3,1    1,1,2,1 2,1,3,2                 |
|p       p        - p       p                        |
| 2,1,1,2 2,1,3,1    2,1,1,1 2,1,3,2                 |
|p       p        - p       p                        |
| 1,1,1,2 2,1,3,1    1,1,1,1 2,1,3,2                 |
|p       p        - p       p                        |
| 1,1,3,1 2,1,2,2    1,1,2,1 2,1,3,2                 |
|p       p        - p       p                        |
| 1,1,2,2 1,1,3,1    1,1,2,1 1,1,3,2                 |
|p       p        - p       p                        |
| 1,1,3,1 2,1,2,1    1,1,2,1 2,1,3,1                 |
|p       p        - p       p                        |
| 1,1,3,1 2,1,1,2    1,1,1,1 2,1,3,2                 |
|p       p        - p       p                        |
| 1,1,1,2 1,1,3,1    1,1,1,1 1,1,3,2                 |
|p       p        - p       p                        |
| 1,1,3,1 2,1,1,1    1,1,1,1 2,1,3,1                 |
|p       p        - p       p                        |
| 1,1,2,2 2,1,2,1    1,1,2,1 2,1,2,2                 |
|p       p        - p       p                        |
| 1,1,2,2 2,1,1,2    1,1,1,2 2,1,2,2                 |
|p       p        - p       p                        |
| 1,1,2,2 2,1,1,1    1,1,1,1 2,1,2,2                 |
|p       p        - p       p                        |
| 2,1,1,2 2,1,2,1    2,1,1,1 2,1,2,2                 |
|p       p        - p       p                        |
| 1,1,1,2 2,1,2,1    1,1,1,1 2,1,2,2                 |
|p       p        - p       p                        |
| 1,1,2,1 2,1,1,2    1,1,1,1 2,1,2,2                 |
|p       p        - p       p                        |
| 1,1,1,2 1,1,2,1    1,1,1,1 1,1,2,2                 |
|p       p        - p       p                        |
| 1,1,2,1 2,1,1,1    1,1,1,1 2,1,2,1                 |
|p       p        - p       p                        |
| 1,1,1,2 2,1,1,1    1,1,1,1 2,1,1,2                 |
+----------------------------------------------------+
|i8 : S = markovRing(2,2,3)                          |
|                                                    |
|o8 = S                                              |
|                                                    |
|o8 : PolynomialRing                                 |
+----------------------------------------------------+
|i9 : F = hiddenMap(4,R);                            |
|                                                    |
|o9 : RingMap R <--- S                               |
+----------------------------------------------------+
|i10 : transpose F.matrix                            |
|                                                    |
|o10 = {-1}  |  p        + p         |               |
|            |   1,1,1,1    1,1,1,2  |               |
|            |                       |               |
|      {-1}  |  p        + p         |               |
|            |   1,1,2,1    1,1,2,2  |               |
|            |                       |               |
|      {-1}  |  p        + p         |               |
|            |   1,1,3,1    1,1,3,2  |               |
|            |                       |               |
|      {-1}  |  p        + p         |               |
|            |   1,2,1,1    1,2,1,2  |               |
|            |                       |               |
|      {-1}  |  p        + p         |               |
|            |   1,2,2,1    1,2,2,2  |               |
|            |                       |               |
|      {-1}  |  p        + p         |               |
|            |   1,2,3,1    1,2,3,2  |               |
|            |                       |               |
|      {-1}  |  p        + p         |               |
|            |   2,1,1,1    2,1,1,2  |               |
|            |                       |               |
|      {-1}  |  p        + p         |               |
|            |   2,1,2,1    2,1,2,2  |               |
|            |                       |               |
|      {-1}  |  p        + p         |               |
|            |   2,1,3,1    2,1,3,2  |               |
|            |                       |               |
|      {-1}  |  p        + p         |               |
|            |   2,2,1,1    2,2,1,2  |               |
|            |                       |               |
|      {-1}  |  p        + p         |               |
|            |   2,2,2,1    2,2,2,2  |               |
|            |                       |               |
|      {-1}  |  p        + p         |               |
|            |   2,2,3,1    2,2,3,2  |               |
|                                                    |
|              12       1                            |
|o10 : Matrix R   <--- R                             |
+----------------------------------------------------+
|i11 : J = preimage (F, I);                          |
|                                                    |
|o11 : Ideal of S                                    |
+----------------------------------------------------+
|i12 : J / print;                                    |
|p     p      - p     p                              |
| 1,2,3 2,2,2    1,2,2 2,2,3                         |
|p     p      - p     p                              |
| 1,2,3 2,2,1    1,2,1 2,2,3                         |
|p     p      - p     p                              |
| 1,2,2 2,2,1    1,2,1 2,2,2                         |
|p     p      - p     p                              |
| 1,1,3 2,1,2    1,1,2 2,1,3                         |
|p     p      - p     p                              |
| 1,1,3 2,1,1    1,1,1 2,1,3                         |
|p     p      - p     p                              |
| 1,1,2 2,1,1    1,1,1 2,1,2                         |
+----------------------------------------------------+

See also
========

  * marginMap -- linear map on joint distributions for
    discrete random variables replacing marginals for indeterminates

Ways to use hiddenMap :
=======================

  * "hiddenMap(ZZ,Ring)"

For the programmer
==================

The object hiddenMap, is a method function (Macaulay2Doc).

identifyParameters -- solve the identifiability problem for Gaussian graphical models
*************************************************************************************

Synopsis
========

  * Usage:
        H = identifyParameters(R)
  * Inputs:
      * R, a ring (Macaulay2Doc), which should be a gaussianRing
        created with a mixed graph without undirected edges
  * Outputs:
      * H, a hash table (Macaulay2Doc), where H#p is the ideal
        of equations involving only the parameter $p$ and the covariances
        $s_{(i,j)}$

Description
===========

Expresses each parameter in the gaussianParametrization in terms of
covariances, if it is possible to do so, or displays that no identification
formula is possible.  The identifiability problem for mixed graph models is
described in Garcia, Spielvogel, Sullivant,  "Identifying causal effects with
computer algebra", UAI, Proceedings of the 26th Conferences, AUAI Press, 2010.

If H#p contains a linear equation $a*p+b$ where a is always nonzero, then $p$
is identifiable.

If H#p contains a linear equation $a*p+b$ where a may be zero, then $p$ is
generically identifiable.

If H#p contains a polynomial in $p$ of degree $d$, then $p$ is algebraically
$d$-identifiable.

If H#p does not contain any polynomial in $p$, then $p$ is not generically
identifiable.

+---------------------------------------------------------------------+
|i1 : G = mixedGraph(digraph {{a,{b}},{b,{c}}},bigraph {{a,c}, {b,c}})|
|                                                                     |
|o1 = MixedGraph{Bigraph => Bigraph{a => {c}   }}                     |
|                                   b => {c}                          |
|                                   c => {a, b}                       |
|                Digraph => Digraph{a => {b}}                         |
|                                   b => {c}                          |
|                                   c => {}                           |
|                Graph => Graph{}                                     |
|                                                                     |
|o1 : MixedGraph                                                      |
+---------------------------------------------------------------------+
|i2 : R = gaussianRing G                                              |
|                                                                     |
|o2 = R                                                               |
|                                                                     |
|o2 : PolynomialRing                                                  |
+---------------------------------------------------------------------+
|i3 : H = identifyParameters R                                        |
|                                                                     |
|o3 = HashTable{l    => ideal(l   s    - s   )           }            |
|                a,b           a,b a,a    a,b                         |
|               l    => ideal ()                                      |
|                b,c                                                  |
|               p    => ideal(p    - s   )                            |
|                a,a           a,a    a,a                             |
|               p    => ideal ()                                      |
|                a,c                                                  |
|                                         2                           |
|               p    => ideal(p   s    + s    - s   s   )             |
|                b,b           b,b a,a    a,b    a,a b,b              |
|               p    => ideal ()                                      |
|                b,c                                                  |
|               p    => ideal ()                                      |
|                c,c                                                  |
|                                                                     |
|o3 : HashTable                                                       |
+---------------------------------------------------------------------+

Reading the output (first line in the HashTable), we see that parameter
$l_{(a,b)}$ is identifiable by the formula $l_{(a,b)} = s_{(a,b)}/s_{(a,a)}$.
On the other hand, $l_{(b,c)}$ is not identifiable.

See also
========

  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model

Ways to use identifyParameters :
================================

  * "identifyParameters(Ring)"

For the programmer
==================

The object identifyParameters, is a method function (Macaulay2Doc).

inverseMarginMap -- inverse of the marginMap
********************************************

Synopsis
========

  * Usage:
        inverseMarginMap(i,R)
  * Inputs:
      * i, an integer (Macaulay2Doc), the index of the variable for
        which to undo the "margin trick"
      * R, a ring (Macaulay2Doc), a markovRing
  * Outputs:
      * a ring map (Macaulay2Doc),

Description
===========

This method computes the inverse of the marginMap.

+-----------------------------------------------------------------------------+
|i1 : R = markovRing (3,2)                                                    |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : F = marginMap(1,R)                                                      |
|                                                                             |
|o2 = map (R, R, {p    - p    - p   , p    - p    - p   , p   , p   , p   ,   |
|                  1,1    2,1    3,1   1,2    2,2    3,2   2,1   2,2   3,1    |
|                                                                             |
|o2 : RingMap R <--- R                                                        |
|-----------------------------------------------------------------------------|
|p   })                                                                       |
| 3,2                                                                         |
+-----------------------------------------------------------------------------+
|i3 : G = inverseMarginMap(1,R)                                               |
|                                                                             |
|o3 = map (R, R, {p    + p    + p   , p    + p    + p   , p   , p   , p   ,   |
|                  1,1    2,1    3,1   1,2    2,2    3,2   2,1   2,2   3,1    |
|                                                                             |
|o3 : RingMap R <--- R                                                        |
|-----------------------------------------------------------------------------|
|p   })                                                                       |
| 3,2                                                                         |
+-----------------------------------------------------------------------------+
|i4 : gens R                                                                  |
|                                                                             |
|o4 = {p   , p   , p   , p   , p   , p   }                                    |
|       1,1   1,2   2,1   2,2   3,1   3,2                                     |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : F*G -- we see that the composition is the identity map:                 |
|                                                                             |
|o5 = map (R, R, {p   , p   , p   , p   , p   , p   })                        |
|                  1,1   1,2   2,1   2,2   3,1   3,2                          |
|                                                                             |
|o5 : RingMap R <--- R                                                        |
+-----------------------------------------------------------------------------+

See also
========

  * hiddenMap -- linear map between the ring of a model with
    one hidden variable and the ring of the corresponding fully observed model
  * marginMap -- linear map on joint distributions for
    discrete random variables replacing marginals for indeterminates

Ways to use inverseMarginMap :
==============================

  * "inverseMarginMap(ZZ,Ring)"

For the programmer
==================

The object inverseMarginMap, is a method function (Macaulay2Doc).

kVar -- key in hash table gaussianRingData: labels of k variables
*****************************************************************

Description
===========

This key is present in every gaussianRingData that comes from a graph. It is
equal to the value of the optional input
gaussianRing(...,kVariableName=>...).

+----------------------------------------+
|i1 : U = graph {{1,2},{2,3}}            |
|                                        |
|o1 = Graph{1 => {2}   }                 |
|           2 => {1, 3}                  |
|           3 => {2}                     |
|                                        |
|o1 : Graph                              |
+----------------------------------------+
|i2 : B = bigraph{{4,5}}                 |
|                                        |
|o2 = Bigraph{4 => {5}}                  |
|             5 => {4}                   |
|                                        |
|o2 : Bigraph                            |
+----------------------------------------+
|i3 : D = digraph {{1,4}}                |
|                                        |
|o3 = Digraph{1 => {4}}                  |
|             4 => {}                    |
|                                        |
|o3 : Digraph                            |
+----------------------------------------+
|i4 : R1 = gaussianRing B                |
|                                        |
|o4 = R1                                 |
|                                        |
|o4 : PolynomialRing                     |
+----------------------------------------+
|i5 : R2 = gaussianRing D                |
|                                        |
|o5 = R2                                 |
|                                        |
|o5 : PolynomialRing                     |
+----------------------------------------+
|i6 : R3 = gaussianRing U                |
|                                        |
|o6 = R3                                 |
|                                        |
|o6 : PolynomialRing                     |
+----------------------------------------+
|i7 : R4 = gaussianRing mixedGraph(U,B,D)|
|                                        |
|o7 = R4                                 |
|                                        |
|o7 : PolynomialRing                     |
+----------------------------------------+
|i8 : R1.gaussianRingData                |
|                                        |
|o8 = HashTable{compU => {}    }         |
|               compW => {4, 5}          |
|               kVar => k                |
|               lVar => l                |
|               nn => 2                  |
|               pVar => p                |
|               sVar => s                |
|                                        |
|o8 : HashTable                          |
+----------------------------------------+
|i9 : R2.gaussianRingData                |
|                                        |
|o9 = HashTable{compU => {}    }         |
|               compW => {1, 4}          |
|               kVar => k                |
|               lVar => l                |
|               nn => 2                  |
|               pVar => p                |
|               sVar => s                |
|                                        |
|o9 : HashTable                          |
+----------------------------------------+
|i10 : R3.gaussianRingData               |
|                                        |
|o10 = HashTable{kVar => k}              |
|                nn => 3                 |
|                sVar => s               |
|                                        |
|o10 : HashTable                         |
+----------------------------------------+
|i11 : R4.gaussianRingData               |
|                                        |
|o11 = HashTable{compU => {1, 2, 3}}     |
|                compW => {4, 5}         |
|                kVar => k               |
|                lVar => l               |
|                nn => 5                 |
|                pVar => p               |
|                sVar => s               |
|                                        |
|o11 : HashTable                         |
+----------------------------------------+

See also
========

  * kVariableName -- optional input to choose the
    variable names for concentration matrix in gaussianRing
  * gaussianRingData -- hash table with main
    parameters of a gaussian ring
  * pVar -- key in hash table gaussianRingData: labels of p
    variables
  * lVar -- key in hash table gaussianRingData: labels of l
    variables
  * sVar -- key in hash table gaussianRingData: labels of s
    variables
  * compU -- key in hash table gaussianRingData: component of
    undirected edges in vertex set of a mixed graph
  * compW -- key in hash table gaussianRingData: component of
    bidirected edges in vertex set of a mixed graph
  * nn -- key in hash table gaussianRingData: total number of
    variables

For the programmer
==================

The object kVar, is a symbol (Macaulay2Doc).

kVariableName -- optional input to choose the variable names for concentration matrix in gaussianRing
*****************************************************************************************************

Description
===========

The option kVariableName => Symbol changes the symbol used for intedeterminates
in a polynomial ring created with gaussianRing. These
indeterminates, k's by default, are entries in the concentration matrix.

See also
========

  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model

Functions with optional argument named kVariableName :
======================================================

  * gaussianRing(...,kVariableName=>...)
    -- symbol used for
    indeterminates in a ring of Gaussian joint probability distributions

For the programmer
==================

The object kVariableName, is a symbol (Macaulay2Doc).

localMarkov -- local Markov statements for a graph or a directed graph
**********************************************************************

Synopsis
========

  * Usage:
        localMarkov G
  * Inputs:
      * G, a graph (Graphs), or a digraph (Graphs),
  * Outputs:
      * a list (Macaulay2Doc), whose entries are triples
        $\{A,B,C\}$ representing local Markov  conditional independence
        statements of the form ``$A$ is independent of B given C'' that hold
        for G.

Description
===========

Given an undirected graph $G$, a local Markov statement is of the form \{$v$,
non-neighbours($v$), neighbours($v$)\} . That is, every vertex $v$ of $G$ is
independent of its non-neighbours given its neighbours.

For example, for the undirected  5-cycle graph $G$, that is, the graph on 5
vertices with $a—b—c—d—e—a$, we get the following local Markov statements:

+-----------------------------------------------------------------------------+
|i1 : G = graph({{a,b},{b,c},{c,d},{d,e},{e,a}})                              |
|                                                                             |
|o1 = Graph{a => {b, e}}                                                      |
|           b => {a, c}                                                       |
|           c => {b, d}                                                       |
|           d => {c, e}                                                       |
|           e => {a, d}                                                       |
|                                                                             |
|o1 : Graph                                                                   |
+-----------------------------------------------------------------------------+
|i2 : localMarkov G                                                           |
|                                                                             |
|o2 = {{{a}, {c, d}, {e, b}}, {{b, c}, {e}, {d, a}}, {{a, e}, {c}, {d, b}},   |
|     ------------------------------------------------------------------------|
|     {{b}, {d, e}, {c, a}}, {{a, b}, {d}, {c, e}}}                           |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

Given a directed acyclic graph $G$, local Markov statements are of the form
\{$v$, nondescendents($v$) - parents($v$), parents($v$)\} . In other words,
every vertex $v$ of $G$ is independent of its nondescendents (excluding
parents) given its parents.

For example, given the digraph $D$ on $7$ vertices with edges $1 \to 2, 1 \to
3, 2 \to 4, 2 \to 5, 3 \to 5, 3 \to 6, 4 \to 7, 5 \to 7$, and $6\to 7$, we get
the following local Markov statements:

+-----------------------------------------------------------------------------+
|i3 : D = digraph {{1,{2,3}}, {2,{4,5}}, {3,{5,6}}, {4,{7}},                  |
|                                                                             |
|o3 = Digraph{1 => {2, 3}}                                                    |
|             2 => {4, 5}                                                     |
|             3 => {5, 6}                                                     |
|             4 => {7}                                                        |
|             5 => {7}                                                        |
|             6 => {7}                                                        |
|             7 => {}                                                         |
|                                                                             |
|o3 : Digraph                                                                 |
|-----------------------------------------------------------------------------|
|{5,{7}},{6,{7}},{7,{}}}                                                      |
+-----------------------------------------------------------------------------+
|i4 : netList pack (3, localMarkov D)                                         |
|                                                                             |
|     +------------------------+------------------------+---------------------|
|o4 = |{{1, 3, 5, 6}, {4}, {2}}|{{1, 2, 4, 5}, {6}, {3}}|{{1, 2, 3}, {7}, {4, |
|     +------------------------+------------------------+---------------------|
|     |{{1, 4, 6}, {5}, {2, 3}}|{{2}, {3, 6}, {1}}      |{{2, 4}, {3}, {1}}   |
|     +------------------------+------------------------+---------------------|
|-----------------------------------------------------------------------------|
|------+                                                                      |
|5, 6}}|                                                                      |
|------+                                                                      |
|      |                                                                      |
|------+                                                                      |
+-----------------------------------------------------------------------------+

This method displays only non-redundant statements. In general, given a set $S$
of conditional independent statements and a statement $s$, then we say that $s$
is a a redundant statement if $s$ can be obtained from the statements in $S$
using the semigraphoid axioms of conditional independence: symmetry,
decomposition, weak union,  and contraction as described in Section 1.1 of
Judea Pearl, Causality: models, reasoning, and inference, Cambridge University
Press.  We do not use the intersection axiom since it is only valid for
strictly positive probability distributions.

See also
========

  * pairMarkov -- pairwise Markov statements for a graph or
    a  directed graph
  * globalMarkov -- global Markov statements for a graph
    or a directed graph

Ways to use localMarkov :
=========================

  * "localMarkov(Digraph)"
  * "localMarkov(Graph)"

For the programmer
==================

The object localMarkov, is a method function (Macaulay2Doc).

lVar -- key in hash table gaussianRingData: labels of l variables
*****************************************************************

Description
===========

This key is present in every gaussianRingData that comes from a graph. It is
equal to the value of the optional input
gaussianRing(...,lVariableName=>...).

+----------------------------------------+
|i1 : U = graph {{1,2},{2,3}}            |
|                                        |
|o1 = Graph{1 => {2}   }                 |
|           2 => {1, 3}                  |
|           3 => {2}                     |
|                                        |
|o1 : Graph                              |
+----------------------------------------+
|i2 : B = bigraph{{4,5}}                 |
|                                        |
|o2 = Bigraph{4 => {5}}                  |
|             5 => {4}                   |
|                                        |
|o2 : Bigraph                            |
+----------------------------------------+
|i3 : D = digraph {{1,4}}                |
|                                        |
|o3 = Digraph{1 => {4}}                  |
|             4 => {}                    |
|                                        |
|o3 : Digraph                            |
+----------------------------------------+
|i4 : R1 = gaussianRing B                |
|                                        |
|o4 = R1                                 |
|                                        |
|o4 : PolynomialRing                     |
+----------------------------------------+
|i5 : R2 = gaussianRing D                |
|                                        |
|o5 = R2                                 |
|                                        |
|o5 : PolynomialRing                     |
+----------------------------------------+
|i6 : R3 = gaussianRing U                |
|                                        |
|o6 = R3                                 |
|                                        |
|o6 : PolynomialRing                     |
+----------------------------------------+
|i7 : R4 = gaussianRing mixedGraph(U,B,D)|
|                                        |
|o7 = R4                                 |
|                                        |
|o7 : PolynomialRing                     |
+----------------------------------------+
|i8 : R1.gaussianRingData                |
|                                        |
|o8 = HashTable{compU => {}    }         |
|               compW => {4, 5}          |
|               kVar => k                |
|               lVar => l                |
|               nn => 2                  |
|               pVar => p                |
|               sVar => s                |
|                                        |
|o8 : HashTable                          |
+----------------------------------------+
|i9 : R2.gaussianRingData                |
|                                        |
|o9 = HashTable{compU => {}    }         |
|               compW => {1, 4}          |
|               kVar => k                |
|               lVar => l                |
|               nn => 2                  |
|               pVar => p                |
|               sVar => s                |
|                                        |
|o9 : HashTable                          |
+----------------------------------------+
|i10 : R3.gaussianRingData               |
|                                        |
|o10 = HashTable{kVar => k}              |
|                nn => 3                 |
|                sVar => s               |
|                                        |
|o10 : HashTable                         |
+----------------------------------------+
|i11 : R4.gaussianRingData               |
|                                        |
|o11 = HashTable{compU => {1, 2, 3}}     |
|                compW => {4, 5}         |
|                kVar => k               |
|                lVar => l               |
|                nn => 5                 |
|                pVar => p               |
|                sVar => s               |
|                                        |
|o11 : HashTable                         |
+----------------------------------------+

See also
========

  * lVariableName -- optional input to choose the
    variable names for the regression matrix
  * gaussianRingData -- hash table with main
    parameters of a gaussian ring
  * kVar -- key in hash table gaussianRingData: labels of k
    variables
  * pVar -- key in hash table gaussianRingData: labels of p
    variables
  * sVar -- key in hash table gaussianRingData: labels of s
    variables
  * compU -- key in hash table gaussianRingData: component of
    undirected edges in vertex set of a mixed graph
  * compW -- key in hash table gaussianRingData: component of
    bidirected edges in vertex set of a mixed graph
  * nn -- key in hash table gaussianRingData: total number of
    variables

For the programmer
==================

The object lVar, is a symbol (Macaulay2Doc).

lVariableName -- optional input to choose the variable names for the regression matrix
**************************************************************************************

Description
===========

Put lVariableName => Symbol for a choice of a symbol l as an argument in the
function gaussianRing,

See also
========

  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model

Functions with optional argument named lVariableName :
======================================================

  * gaussianRing(...,lVariableName=>...)
    -- symbol used for
    indeterminates in a ring of Gaussian joint probability distributions

For the programmer
==================

The object lVariableName, is a symbol (Macaulay2Doc).

marginMap -- linear map on joint distributions for discrete random variables replacing marginals for indeterminates
*******************************************************************************************************************

Synopsis
========

  * Usage:
        marginMap(i,R)
  * Inputs:
      * i, an integer (Macaulay2Doc), the index of the variable on
        which to perform the `marginalization trick'
      * R, a ring (Macaulay2Doc), a markovRing
  * Outputs:
      * a ring map (Macaulay2Doc),

Description
===========

The ring $R$ must be a ring of probability distributions on $n$ random
variables created using markovRing. The integer $i$ must be
in the range from 1 to $n$.

Let $p_{u_1,u_2,\dots, +,\dots,u_n}$ denote the linear form $p_{u_1,u_2,\dots,
1,\dots,u_n} + \dots + p_{u_1,u_2,\dots, d_i,\dots,u_n}$, where $d_i$ is the
number of states of random variable $X_i$.

The method marginMap returns a ring map $F : R \to R$ such that after applying
$F$, the indeterminate $p_{u_1,u_2,\dots,1,\dots,u_n}$ refers to $
p_{u_1,u_2,\dots, +,\dots,u_n}$, where the '1' and the '$+$' are in the $i$th
spot.

Further $F$ is the identity on all other indeterminates, that is, $
F(p_{u_1,u_2,\dots, j,\dots,u_n}) = p_{u_1,u_2,\dots, j,\dots,u_n} $, for all
$j\geq 2$.

+----------------------------------------------------+
|i1 : F = marginMap(1,markovRing(3,2));              |
|                                                    |
|o1 : RingMap QQ[p   ..p   ] <--- QQ[p   ..p   ]     |
|                 1,1   3,2           1,1   3,2      |
+----------------------------------------------------+
|i2 : compactMatrixForm =false;                      |
+----------------------------------------------------+
|i3 : transpose F.matrix                             |
|                                                    |
|o3 = {-1}  |  p    - p    - p     |                 |
|           |   1,1    2,1    3,1  |                 |
|           |                      |                 |
|     {-1}  |  p    - p    - p     |                 |
|           |   1,2    2,2    3,2  |                 |
|           |                      |                 |
|     {-1}  |         p            |                 |
|           |          2,1         |                 |
|           |                      |                 |
|     {-1}  |         p            |                 |
|           |          2,2         |                 |
|           |                      |                 |
|     {-1}  |         p            |                 |
|           |          3,1         |                 |
|           |                      |                 |
|     {-1}  |         p            |                 |
|           |          3,2         |                 |
|                                                    |
|                            6                      1|
|o3 : Matrix (QQ[p   ..p   ])  <--- (QQ[p   ..p   ]) |
|                 1,1   3,2              1,1   3,2   |
+----------------------------------------------------+

This linear transformation simplifies ideals and/or polynomials involving $
p_{u_1,u_2,..., +,...,u_n} $. Sometimes, the resulting ideals are toric ideals
as the example below shows. For more details see the paper "Algebraic Geometry
of Bayesian Networks" by Garcia, Stillman, and Sturmfels.

+-----------------------------------------------------------------------------+
|i4 : G = digraph  {{1,{}},{2,{1}},{3,{1}},{4,{2,3}}}                         |
|                                                                             |
|o4 = Digraph{1 => {}    }                                                    |
|             2 => {1}                                                        |
|             3 => {1}                                                        |
|             4 => {2, 3}                                                     |
|                                                                             |
|o4 : Digraph                                                                 |
+-----------------------------------------------------------------------------+
|i5 : R = markovRing (2,2,2,2)                                                |
|                                                                             |
|o5 = R                                                                       |
|                                                                             |
|o5 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i6 : S = globalMarkov G                                                      |
|                                                                             |
|o6 = {{{1}, {4}, {2, 3}}, {{2}, {3}, {4}}}                                   |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+
|i7 : I = conditionalIndependenceIdeal (R,S);                                 |
|                                                                             |
|o7 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i8 : I / print;                                                              |
|- p       p        + p       p                                               |
|   1,1,1,2 2,1,1,1    1,1,1,1 2,1,1,2                                        |
|- p       p        + p       p                                               |
|   1,1,2,2 2,1,2,1    1,1,2,1 2,1,2,2                                        |
|- p       p        + p       p                                               |
|   1,2,1,2 2,2,1,1    1,2,1,1 2,2,1,2                                        |
|- p       p        + p       p                                               |
|   1,2,2,2 2,2,2,1    1,2,2,1 2,2,2,2                                        |
|- p       p        + p       p        + p       p        - p       p        -|
|   1,1,2,1 1,2,1,1    1,1,1,1 1,2,2,1    1,2,2,1 2,1,1,1    1,2,1,1 2,1,2,1  |
|- p       p        + p       p        + p       p        - p       p        -|
|   1,1,2,2 1,2,1,2    1,1,1,2 1,2,2,2    1,2,2,2 2,1,1,2    1,2,1,2 2,1,2,2  |
|-----------------------------------------------------------------------------|
|p       p        - p       p        + p       p        + p       p           |
| 1,1,2,1 2,2,1,1    2,1,2,1 2,2,1,1    1,1,1,1 2,2,2,1    2,1,1,1 2,2,2,1    |
|p       p        - p       p        + p       p        + p       p           |
| 1,1,2,2 2,2,1,2    2,1,2,2 2,2,1,2    1,1,1,2 2,2,2,2    2,1,1,2 2,2,2,2    |
+-----------------------------------------------------------------------------+
|i9 : F = marginMap(1,R);                                                     |
|                                                                             |
|o9 : RingMap R <--- R                                                        |
+-----------------------------------------------------------------------------+
|i10 : transpose F.matrix                                                     |
|                                                                             |
|o10 = {-1}  |  p        - p         |                                        |
|            |   1,1,1,1    2,1,1,1  |                                        |
|            |                       |                                        |
|      {-1}  |  p        - p         |                                        |
|            |   1,1,1,2    2,1,1,2  |                                        |
|            |                       |                                        |
|      {-1}  |  p        - p         |                                        |
|            |   1,1,2,1    2,1,2,1  |                                        |
|            |                       |                                        |
|      {-1}  |  p        - p         |                                        |
|            |   1,1,2,2    2,1,2,2  |                                        |
|            |                       |                                        |
|      {-1}  |  p        - p         |                                        |
|            |   1,2,1,1    2,2,1,1  |                                        |
|            |                       |                                        |
|      {-1}  |  p        - p         |                                        |
|            |   1,2,1,2    2,2,1,2  |                                        |
|            |                       |                                        |
|      {-1}  |  p        - p         |                                        |
|            |   1,2,2,1    2,2,2,1  |                                        |
|            |                       |                                        |
|      {-1}  |  p        - p         |                                        |
|            |   1,2,2,2    2,2,2,2  |                                        |
|            |                       |                                        |
|      {-1}  |        p              |                                        |
|            |         2,1,1,1       |                                        |
|            |                       |                                        |
|      {-1}  |        p              |                                        |
|            |         2,1,1,2       |                                        |
|            |                       |                                        |
|      {-1}  |        p              |                                        |
|            |         2,1,2,1       |                                        |
|            |                       |                                        |
|      {-1}  |        p              |                                        |
|            |         2,1,2,2       |                                        |
|            |                       |                                        |
|      {-1}  |        p              |                                        |
|            |         2,2,1,1       |                                        |
|            |                       |                                        |
|      {-1}  |        p              |                                        |
|            |         2,2,1,2       |                                        |
|            |                       |                                        |
|      {-1}  |        p              |                                        |
|            |         2,2,2,1       |                                        |
|            |                       |                                        |
|      {-1}  |        p              |                                        |
|            |         2,2,2,2       |                                        |
|                                                                             |
|              16       1                                                     |
|o10 : Matrix R   <--- R                                                      |
+-----------------------------------------------------------------------------+
|i11 : J = F I;                                                               |
|                                                                             |
|o11 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i12 : J / print;                                                             |
|- p       p        + p       p                                               |
|   1,1,1,2 2,1,1,1    1,1,1,1 2,1,1,2                                        |
|- p       p        + p       p                                               |
|   1,1,2,2 2,1,2,1    1,1,2,1 2,1,2,2                                        |
|- p       p        + p       p                                               |
|   1,2,1,2 2,2,1,1    1,2,1,1 2,2,1,2                                        |
|- p       p        + p       p                                               |
|   1,2,2,2 2,2,2,1    1,2,2,1 2,2,2,2                                        |
|- p       p        + p       p                                               |
|   1,1,2,1 1,2,1,1    1,1,1,1 1,2,2,1                                        |
|- p       p        + p       p                                               |
|   1,1,2,2 1,2,1,2    1,1,1,2 1,2,2,2                                        |
+-----------------------------------------------------------------------------+

See also
========

  * hiddenMap -- linear map between the ring of a model with
    one hidden variable and the ring of the corresponding fully observed model
  * inverseMarginMap -- inverse of the marginMap

Ways to use marginMap :
=======================

  * "marginMap(ZZ,Ring)"

For the programmer
==================

The object marginMap, is a method function (Macaulay2Doc).

markovMatrices -- matrices whose minors form the ideal of a list of independence statements
*******************************************************************************************

Synopsis
========

  * Usage:
        markovMatrices(R,S)
        markovMatrices(R,S,VarNames)
  * Inputs:
      * R, a ring (Macaulay2Doc), R must be a markovRing
      * S, a list (Macaulay2Doc), list of conditional independence
        statements among discrete random variables.
      * VarNames, a list (Macaulay2Doc), list of names of the
        random variables in the statements of $S$.  If this is omitted it is
        assumed that these are integers in the range from 1 to $n$ where $n$ is
        the number of random variables in the declaration of markovRing.
  * Outputs:
      * a list (Macaulay2Doc), list whose elements are instances of
        Matrix.

Description
===========

List of matrices whose 2x2 minors form the conditional independence ideal of
the independence statements on the list $S$. This method is used in
conditionalIndependenceIdeal,  it is exported to
be able to read independence constraints as minors of matrices instead of their
polynomial expansions.

+-----------------------------------------------------+
|i1 : S = {{{1},{3},{4}}}                             |
|                                                     |
|o1 = {{{1}, {3}, {4}}}                               |
|                                                     |
|o1 : List                                            |
+-----------------------------------------------------+
|i2 : R = markovRing (4:2)                            |
|                                                     |
|o2 = R                                               |
|                                                     |
|o2 : PolynomialRing                                  |
+-----------------------------------------------------+
|i3 : compactMatrixForm =false;                       |
+-----------------------------------------------------+
|i4 : netList markovMatrices (R,S)                    |
|                                                     |
|     +----------------------------------------------+|
|o4 = ||  p        + p         p        + p         |||
|     ||   1,1,1,1    1,2,1,1   1,1,2,1    1,2,2,1  |||
|     ||                                            |||
|     ||  p        + p         p        + p         |||
|     ||   2,1,1,1    2,2,1,1   2,1,2,1    2,2,2,1  |||
|     +----------------------------------------------+|
|     ||  p        + p         p        + p         |||
|     ||   1,1,1,2    1,2,1,2   1,1,2,2    1,2,2,2  |||
|     ||                                            |||
|     ||  p        + p         p        + p         |||
|     ||   2,1,1,2    2,2,1,2   2,1,2,2    2,2,2,2  |||
|     +----------------------------------------------+|
+-----------------------------------------------------+

Here is an example where the independence statements are extracted from a
graph.

+-----------------------------------------------------------------------------+
|i5 : G = graph{{a,b},{b,c},{c,d},{a,d}}                                      |
|                                                                             |
|o5 = Graph{a => {b, d}}                                                      |
|           b => {a, c}                                                       |
|           c => {b, d}                                                       |
|           d => {a, c}                                                       |
|                                                                             |
|o5 : Graph                                                                   |
+-----------------------------------------------------------------------------+
|i6 : S = localMarkov G                                                       |
|                                                                             |
|o6 = {{{a}, {c}, {d, b}}, {{b}, {d}, {c, a}}}                                |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+
|i7 : R = markovRing (4:2)                                                    |
|                                                                             |
|o7 = R                                                                       |
|                                                                             |
|o7 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i8 : markovMatrices (R,S,vertices G)                                         |
|                                                                             |
|o8 = {|  p         p         |, |  p         p         |, |  p               |
|      |   1,1,1,1   1,1,2,1  |  |   1,1,1,2   1,1,2,2  |  |   1,2,1,1        |
|      |                      |  |                      |  |                  |
|      |  p         p         |  |  p         p         |  |  p               |
|      |   2,1,1,1   2,1,2,1  |  |   2,1,1,2   2,1,2,2  |  |   2,2,1,1        |
|     ------------------------------------------------------------------------|
|     p         |, |  p         p         |, |  p         p         |, |      |
|      1,2,2,1  |  |   1,2,1,2   1,2,2,2  |  |   1,1,1,1   1,1,1,2  |  |      |
|               |  |                      |  |                      |  |      |
|     p         |  |  p         p         |  |  p         p         |  |      |
|      2,2,2,1  |  |   2,2,1,2   2,2,2,2  |  |   1,2,1,1   1,2,1,2  |  |      |
|     ------------------------------------------------------------------------|
|     p         p         |, |  p         p         |, |  p         p         |
|      1,1,2,1   1,1,2,2  |  |   2,1,1,1   2,1,1,2  |  |   2,1,2,1   2,1,2,2  |
|                         |  |                      |  |                      |
|     p         p         |  |  p         p         |  |  p         p         |
|      1,2,2,1   1,2,2,2  |  |   2,2,1,1   2,2,1,2  |  |   2,2,2,1   2,2,2,2  |
|     ------------------------------------------------------------------------|
|     |}                                                                      |
|     |                                                                       |
|     |                                                                       |
|     |                                                                       |
|     |                                                                       |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+

Caveat
======

In case the random variables are not numbered $1, 2, \dots, n$, then this
method requires an additional input in the form of a list of the random
variable names. This list must be in the same order as the implicit order used
in the sequence $d$. The user is encouraged to read the caveat on the method
conditionalIndependenceIdeal, regarding
probability distributions on discrete random variables that have been labeled
arbitrarily.

See also
========

  * conditionalIndependenceIdeal -- ideal
    of a list of conditional independent statements
  * markovRing -- ring of joint probability distributions on
    several discrete random variables

Ways to use markovMatrices :
============================

  * "markovMatrices(Ring,List)"
  * "markovMatrices(Ring,List,List)"

For the programmer
==================

The object markovMatrices, is a method function (Macaulay2Doc).

markovRing -- ring of joint probability distributions on several discrete random variables
******************************************************************************************

Synopsis
========

  * Usage:
        markovRing(d)
  * Inputs:
      * d, a sequence (Macaulay2Doc), with positive integer
        entries $(d_1,\dots ,d_r)$
  * Optional inputs (Macaulay2Doc),:
      * Coefficients,
        => ..., default value QQ, optional input to choose the base field in
        markovRing or gaussianRing
      * VariableName,
        => ..., default value "p", symbol used for indeterminates in a ring
        of discrete joint probability distributions
  * Outputs:
      * a ring (Macaulay2Doc), a polynomial ring with
        $d_1*d_2*\dots   *d_r$ variables $p_{i_1,\dots ,i_r}$, with each $i_j$
        satisfying $1\leq i_j \leq d_j$.
  * Consequences:
      * Information about this sequence of integers is placed into the ring,
        and is used by other functions in this package.  Also, at most one ring
        for each such sequence is created since the ring is  cached.

Description
===========

The sequence $d$ represents the number of states of each discrete random
variable. This example creates a ring of joint probability distributions on 4
random variables with 2, 3, 4, and 5 states. This ring has a total of 120
indeterminates.

+-----------------------------------------------------------------+
|i1 : d=(2,3,4,5);                                                |
+-----------------------------------------------------------------+
|i2 : R = markovRing d;                                           |
+-----------------------------------------------------------------+
|i3 : numgens R                                                   |
|                                                                 |
|o3 = 120                                                         |
+-----------------------------------------------------------------+
|i4 : R_0, R_1, R_119 --here are some of the variables in the ring|
|                                                                 |
|o4 = (p       , p       , p       )                              |
|       1,1,1,1   1,1,1,2   2,3,4,5                               |
|                                                                 |
|o4 : Sequence                                                    |
+-----------------------------------------------------------------+

If no coefficient choice is specified, the polynomial ring is created over the
rationals.

+----------------------+
|i5 : coefficientRing R|
|                      |
|o5 = QQ               |
|                      |
|o5 : Ring             |
+----------------------+

The optional argument Coefficients, allows to change the
base field.

+------------------------------------------+
|i6 : R2 = markovRing (d,Coefficients=>CC);|
+------------------------------------------+
|i7 : coefficientRing R2                   |
|                                          |
|o7 = CC                                   |
|       53                                 |
|                                          |
|o7 : ComplexField                         |
+------------------------------------------+

The indeterminates are labeled with the letter ''p'' suggesting probability
distributions. However, it is useful to be able to create a new ring where the
indeterminates are labeled different (for example, they may represent marginal
probabilities). This can be accomplished with the VariableName,
option.

+--------------------------------------+
|i8 : d=(1,2);                         |
+--------------------------------------+
|i9 : markovRing (d,VariableName => q);|
+--------------------------------------+
|i10 : gens oo                         |
|                                      |
|o10 = {q   , q   }                    |
|        1,1   1,2                     |
|                                      |
|o10 : List                            |
+--------------------------------------+

The routines  hiddenMap, inverseMarginMap,
see marginMap, markovMatrices,
require the ring to be created by this function. The routines
conditionalIndependenceIdeal,
discreteVanishingIdeal, require the ring to be created
by this function or the method gaussianRing.

Caveat
======

As opposed to gaussianRing, this method does not store
information about a graph or the names of the random variables. In case these
random variables are not numbered $1, 2, \dots, n$, then the methods
conditionalIndependenceIdeal, and
markovMatrices, require an additional input in the form of a
list of the random variable names. This list must be in the same order as the
implicit order used in the sequence $d$. The user is encouraged to read the
caveat on the method conditionalIndependenceIdeal,
regarding probability distributions on discrete
random variables that have been labeled arbitrarily.

See also
========

  * conditionalIndependenceIdeal -- ideal
    of a list of conditional independent statements
  * discreteVanishingIdeal -- vanishing ideal of
    a discrete graphical model
  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model
  * hiddenMap -- linear map between the ring of a model with
    one hidden variable and the ring of the corresponding fully observed model
  * inverseMarginMap -- inverse of the marginMap
  * marginMap -- linear map on joint distributions for
    discrete random variables replacing marginals for indeterminates
  * markovMatrices -- matrices whose minors form the
    ideal of a list of independence statements

Ways to use markovRing :
========================

  * "markovRing(Sequence)"

For the programmer
==================

The object markovRing, is a method function with a single argument (Macaulay2Doc).

markovRing(...,Coefficients=>...) -- optional input to choose the base field in markovRing or gaussianRing
**********************************************************************************************************

Synopsis
========

  * Usage:
        gaussianRing(n,Coefficients=>Ring)
        gaussianRing(G,Coefficients=>Ring)
        markovRing(d,Coefficients=>Ring)
  * Inputs:
      * d, a sequence (Macaulay2Doc), with positive integer
        entries $(d_1,\dots ,d_r)$
      * n, an integer (Macaulay2Doc), number of random variables
      * G, a graph (Graphs), a graph (Graphs), or a
        digraph (Graphs), or an instance of the type
        MixedGraph (StatGraphs), with directed and bidirected edges
  * Outputs:
      * a ring (Macaulay2Doc),

Description
===========

In both markovRing and gaussianRing, the default coefficient ring is QQ.
Putting Coefficients => r for a choice of ring(field) r as an argument in the
function markovRing, or gaussianRing,
creates a ring with the desired coefficient ring.

+----------------------------------------------+
|i1 : R2 = markovRing ((2,2),Coefficients=>CC);|
+----------------------------------------------+
|i2 : coefficientRing R2                       |
|                                              |
|o2 = CC                                       |
|       53                                     |
|                                              |
|o2 : ComplexField                             |
+----------------------------------------------+

Further information
===================

  * Default value: QQ (Macaulay2Doc),
  * Function: markovRing, -- ring of joint probability
    distributions on several discrete random variables
  * Option key: Coefficients, -- optional input to choose
    the base field

See also
========

  * markovRing -- ring of joint probability distributions on
    several discrete random variables
  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model

Functions with optional argument named Coefficients :
=====================================================

  * "gaussianRing(...,Coefficients=>...)"
  * markovRing(...,Coefficients=>...)
    -- optional input to
    choose the base field in markovRing or gaussianRing

markovRing(...,VariableName=>...) -- symbol used for indeterminates in a ring of discrete joint probability distributions
*************************************************************************************************************************

Synopsis
========

  * Usage:
        markovRing (d,VariableName => q)
  * Inputs:
      * q, a symbol (Macaulay2Doc), or a string (Macaulay2Doc),

Description
===========

The indeterminates in the polynomial ring made by markovRing are labeled with
the letter ''p'' suggesting probability distributions. However, it is useful to
be able to create a new ring where the indeterminates are labeled different
(for example, they may represent marginal probabilities).

+--------------------------------------+
|i1 : d=(1,2);                         |
+--------------------------------------+
|i2 : markovRing (d,VariableName => q);|
+--------------------------------------+
|i3 : gens oo                          |
|                                      |
|o3 = {q   , q   }                     |
|       1,1   1,2                      |
|                                      |
|o3 : List                             |
+--------------------------------------+

Further information
===================

  * Default value: p
  * Function: markovRing, -- ring of joint probability
    distributions on several discrete random variables
  * Option key: VariableName, -- optional input to choose
    indeterminate name in markovRing

Functions with optional argument named VariableName :
=====================================================

  * markovRing(...,VariableName=>...)
    -- symbol used for
    indeterminates in a ring of discrete joint probability distributions

nn -- key in hash table gaussianRingData: total number of variables
*******************************************************************

Description
===========

This key is present in every gaussianRingData hash table

+----------------------------------------+
|i1 : R = gaussianRing 5                 |
|                                        |
|o1 = R                                  |
|                                        |
|o1 : PolynomialRing                     |
+----------------------------------------+
|i2 : R.gaussianRingData                 |
|                                        |
|o2 = HashTable{nn => 5}                 |
|                                        |
|o2 : HashTable                          |
+----------------------------------------+
|i3 : U = graph {{1,2},{2,3}}            |
|                                        |
|o3 = Graph{1 => {2}   }                 |
|           2 => {1, 3}                  |
|           3 => {2}                     |
|                                        |
|o3 : Graph                              |
+----------------------------------------+
|i4 : B = bigraph{{4,5}}                 |
|                                        |
|o4 = Bigraph{4 => {5}}                  |
|             5 => {4}                   |
|                                        |
|o4 : Bigraph                            |
+----------------------------------------+
|i5 : D = digraph {{1,4}}                |
|                                        |
|o5 = Digraph{1 => {4}}                  |
|             4 => {}                    |
|                                        |
|o5 : Digraph                            |
+----------------------------------------+
|i6 : R1 = gaussianRing B                |
|                                        |
|o6 = R1                                 |
|                                        |
|o6 : PolynomialRing                     |
+----------------------------------------+
|i7 : R2 = gaussianRing D                |
|                                        |
|o7 = R2                                 |
|                                        |
|o7 : PolynomialRing                     |
+----------------------------------------+
|i8 : R3 = gaussianRing U                |
|                                        |
|o8 = R3                                 |
|                                        |
|o8 : PolynomialRing                     |
+----------------------------------------+
|i9 : R4 = gaussianRing mixedGraph(U,B,D)|
|                                        |
|o9 = R4                                 |
|                                        |
|o9 : PolynomialRing                     |
+----------------------------------------+
|i10 : R1.gaussianRingData               |
|                                        |
|o10 = HashTable{compU => {}    }        |
|                compW => {4, 5}         |
|                kVar => k               |
|                lVar => l               |
|                nn => 2                 |
|                pVar => p               |
|                sVar => s               |
|                                        |
|o10 : HashTable                         |
+----------------------------------------+
|i11 : R2.gaussianRingData               |
|                                        |
|o11 = HashTable{compU => {}    }        |
|                compW => {1, 4}         |
|                kVar => k               |
|                lVar => l               |
|                nn => 2                 |
|                pVar => p               |
|                sVar => s               |
|                                        |
|o11 : HashTable                         |
+----------------------------------------+
|i12 : R3.gaussianRingData               |
|                                        |
|o12 = HashTable{kVar => k}              |
|                nn => 3                 |
|                sVar => s               |
|                                        |
|o12 : HashTable                         |
+----------------------------------------+
|i13 : R4.gaussianRingData               |
|                                        |
|o13 = HashTable{compU => {1, 2, 3}}     |
|                compW => {4, 5}         |
|                kVar => k               |
|                lVar => l               |
|                nn => 5                 |
|                pVar => p               |
|                sVar => s               |
|                                        |
|o13 : HashTable                         |
+----------------------------------------+

See also
========

  * gaussianRingData -- hash table with main
    parameters of a gaussian ring
  * kVar -- key in hash table gaussianRingData: labels of k
    variables
  * pVar -- key in hash table gaussianRingData: labels of p
    variables
  * lVar -- key in hash table gaussianRingData: labels of l
    variables
  * sVar -- key in hash table gaussianRingData: labels of s
    variables
  * compU -- key in hash table gaussianRingData: component of
    undirected edges in vertex set of a mixed graph
  * compW -- key in hash table gaussianRingData: component of
    bidirected edges in vertex set of a mixed graph

For the programmer
==================

The object nn, is a symbol (Macaulay2Doc).

OldVersion -- optional argument in gaussianVanishingIdeal to use old method for gaussianRings coming from directed graphs
*************************************************************************************************************************

Description
===========

Alternative computation of the vanishing ideal of a Gaussian directed graphical
model using (2) from Seth Sullivant, Kelli Talaska, and Jan Draisma, Trek
separation for Gaussian graphical models, The Annals of Statistics 38.3 (2010):
1665-1685.

See also
========

  * gaussianVanishingIdeal -- vanishing ideal of
    a Gaussian graphical model

Functions with optional argument named OldVersion :
===================================================

  * gaussianVanishingIdeal(...,OldVersion=>...)
    -- optional
    argument in gaussianVanishingIdeal to use old method for gaussianRings
    coming from directed graphs

For the programmer
==================

The object OldVersion, is a symbol (Macaulay2Doc).

pairMarkov -- pairwise Markov statements for a graph or a  directed graph
*************************************************************************

Synopsis
========

  * Usage:
        pairMarkov G
  * Inputs:
      * G, a graph (Graphs), or a digraph (Graphs),
  * Outputs:
      * a list (Macaulay2Doc), whose entries are triples
        $\{A,B,C\}$ representing pairwise Markov  conditional independence
        statements of the form ``$A$ is independent of $B$ given $C$'' that
        hold for $G$.

Description
===========

Given an undirected graph $G$, pairwise Markov statements are statements of the
form \{$v$, $w$, all other vertices\}\ for each pair of non-adjacent vertices
$v$ and $w$ of $G$.

For example, for the undirected 5-cycle graph $G$, that is, the graph on $5$
vertices with edges $a—b—c—d—e—a$, we get the following pairwise Markov
statements:

+-----------------------------------------------------------------------------+
|i1 : G = graph({{a,b},{b,c},{c,d},{d,e},{e,a}})                              |
|                                                                             |
|o1 = Graph{a => {b, e}}                                                      |
|           b => {a, c}                                                       |
|           c => {b, d}                                                       |
|           d => {c, e}                                                       |
|           e => {a, d}                                                       |
|                                                                             |
|o1 : Graph                                                                   |
+-----------------------------------------------------------------------------+
|i2 : pairMarkov G                                                            |
|                                                                             |
|o2 = {{{a}, {c}, {d, e, b}}, {{c}, {e}, {d, a, b}}, {{b}, {d}, {c, a, e}},   |
|     ------------------------------------------------------------------------|
|     {{a}, {d}, {c, e, b}}, {{b}, {e}, {c, d, a}}}                           |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

Given a directed acyclic graph $G$, pairwise Markov statements are statements
of the form \{$v$, $w$, nondescendents($G,v$)-$w$\}\ for each vertex $v$ of $G$
and each non-descendent vertex $w$ of $v$. In other words, for every vertex $v$
of $G$ and each nondescendent $w$ of $v$, this method returns the statement:
$v$ is independent of $w$ given all other nondescendents.

For example, given the digraph $D$ on $7$ vertices with edges $1 \to 2, 1 \to
3, 2 \to 4, 2 \to 5, 3 \to 5, 3 \to 6, 4 \to 7, 5 \to 7$, and $6\to 7$, we get
the following pairwise Markov statements:

+-----------------------------------------------------------------------------+
|i3 : D = digraph {{1,{2,3}}, {2,{4,5}}, {3,{5,6}}, {4,{7}},                  |
|                                                                             |
|o3 = Digraph{1 => {2, 3}}                                                    |
|             2 => {4, 5}                                                     |
|             3 => {5, 6}                                                     |
|             4 => {7}                                                        |
|             5 => {7}                                                        |
|             6 => {7}                                                        |
|             7 => {}                                                         |
|                                                                             |
|o3 : Digraph                                                                 |
|-----------------------------------------------------------------------------|
|{5,{7}},{6,{7}},{7,{}}}                                                      |
+-----------------------------------------------------------------------------+
|i4 : netList pack (3, pairMarkov D)                                          |
|                                                                             |
|     +------------------------+---------------------------+------------------|
|o4 = |{{2}, {6}, {1, 3}}      |{{5}, {6}, {1, 2, 3, 4}}   |{{1}, {6}, {2, 3, |
|     +------------------------+---------------------------+------------------|
|     |{{1}, {5}, {2, 3, 4, 6}}|{{2}, {3}, {1, 6}}         |{{2}, {7}, {1, 3, |
|     +------------------------+---------------------------+------------------|
|     |{{3}, {4}, {1, 2, 5, 6}}|{{3}, {7}, {1, 2, 4, 5, 6}}|{{2}, {3}, {4, 1}}|
|     +------------------------+---------------------------+------------------|
|     |{{3}, {4}, {1, 2}}      |{{1}, {4}, {2, 3, 5, 6}}   |{{4}, {5}, {1, 2, |
|     +------------------------+---------------------------+------------------|
|     |{{4}, {6}, {1, 2, 3, 5}}|{{1}, {7}, {2, 3, 4, 5, 6}}|{{2}, {6}, {1, 3, |
|     +------------------------+---------------------------+------------------|
|-----------------------------------------------------------------------------|
|---------+                                                                   |
|4, 5}}   |                                                                   |
|---------+                                                                   |
|4, 5, 6}}|                                                                   |
|---------+                                                                   |
|         |                                                                   |
|---------+                                                                   |
|3, 6}}   |                                                                   |
|---------+                                                                   |
|4, 5}}   |                                                                   |
|---------+                                                                   |
+-----------------------------------------------------------------------------+

This method displays only non-redundant statements. In general, given a set $S$
of conditional independent statements and a statement $s$, then we say that $s$
is a a redundant statement if $s$ can be obtained from the statements in $S$
using the semigraphoid axioms of conditional independence: symmetry,
decomposition, weak union,  and contraction as described in Section 1.1 of
Judea Pearl, Causality: models, reasoning, and inference, Cambridge University
Press.  We do not use the intersection axiom since it is only valid for
strictly positive probability distributions.

See also
========

  * localMarkov -- local Markov statements for a graph or a
    directed graph
  * globalMarkov -- global Markov statements for a graph
    or a directed graph

Ways to use pairMarkov :
========================

  * "pairMarkov(Digraph)"
  * "pairMarkov(Graph)"

For the programmer
==================

The object pairMarkov, is a method function (Macaulay2Doc).

pVar -- key in hash table gaussianRingData: labels of p variables
*****************************************************************

Description
===========

This key is present in every gaussianRingData that comes from a graph. It is
equal to the value of the optional input
gaussianRing(...,pVariableName=>...).

+----------------------------------------+
|i1 : U = graph {{1,2},{2,3}}            |
|                                        |
|o1 = Graph{1 => {2}   }                 |
|           2 => {1, 3}                  |
|           3 => {2}                     |
|                                        |
|o1 : Graph                              |
+----------------------------------------+
|i2 : B = bigraph{{4,5}}                 |
|                                        |
|o2 = Bigraph{4 => {5}}                  |
|             5 => {4}                   |
|                                        |
|o2 : Bigraph                            |
+----------------------------------------+
|i3 : D = digraph {{1,4}}                |
|                                        |
|o3 = Digraph{1 => {4}}                  |
|             4 => {}                    |
|                                        |
|o3 : Digraph                            |
+----------------------------------------+
|i4 : R1 = gaussianRing B                |
|                                        |
|o4 = R1                                 |
|                                        |
|o4 : PolynomialRing                     |
+----------------------------------------+
|i5 : R2 = gaussianRing D                |
|                                        |
|o5 = R2                                 |
|                                        |
|o5 : PolynomialRing                     |
+----------------------------------------+
|i6 : R3 = gaussianRing U                |
|                                        |
|o6 = R3                                 |
|                                        |
|o6 : PolynomialRing                     |
+----------------------------------------+
|i7 : R4 = gaussianRing mixedGraph(U,B,D)|
|                                        |
|o7 = R4                                 |
|                                        |
|o7 : PolynomialRing                     |
+----------------------------------------+
|i8 : R1.gaussianRingData                |
|                                        |
|o8 = HashTable{compU => {}    }         |
|               compW => {4, 5}          |
|               kVar => k                |
|               lVar => l                |
|               nn => 2                  |
|               pVar => p                |
|               sVar => s                |
|                                        |
|o8 : HashTable                          |
+----------------------------------------+
|i9 : R2.gaussianRingData                |
|                                        |
|o9 = HashTable{compU => {}    }         |
|               compW => {1, 4}          |
|               kVar => k                |
|               lVar => l                |
|               nn => 2                  |
|               pVar => p                |
|               sVar => s                |
|                                        |
|o9 : HashTable                          |
+----------------------------------------+
|i10 : R3.gaussianRingData               |
|                                        |
|o10 = HashTable{kVar => k}              |
|                nn => 3                 |
|                sVar => s               |
|                                        |
|o10 : HashTable                         |
+----------------------------------------+
|i11 : R4.gaussianRingData               |
|                                        |
|o11 = HashTable{compU => {1, 2, 3}}     |
|                compW => {4, 5}         |
|                kVar => k               |
|                lVar => l               |
|                nn => 5                 |
|                pVar => p               |
|                sVar => s               |
|                                        |
|o11 : HashTable                         |
+----------------------------------------+

See also
========

  * pVariableName -- optional input to choose the
    variable names for the covariance matrix of the error terms
  * gaussianRingData -- hash table with main
    parameters of a gaussian ring
  * kVar -- key in hash table gaussianRingData: labels of k
    variables
  * lVar -- key in hash table gaussianRingData: labels of l
    variables
  * sVar -- key in hash table gaussianRingData: labels of s
    variables
  * compU -- key in hash table gaussianRingData: component of
    undirected edges in vertex set of a mixed graph
  * compW -- key in hash table gaussianRingData: component of
    bidirected edges in vertex set of a mixed graph
  * nn -- key in hash table gaussianRingData: total number of
    variables

For the programmer
==================

The object pVar, is a symbol (Macaulay2Doc).

pVariableName -- optional input to choose the variable names for the covariance matrix of the error terms
*********************************************************************************************************

Description
===========

Put pVariableName => Symbol for a choice of a symbol p as an argument in the
function gaussianRing,

See also
========

  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model

Functions with optional argument named pVariableName :
======================================================

  * gaussianRing(...,pVariableName=>...)
    -- symbol used for
    indeterminates in a ring of Gaussian joint probability distributions

For the programmer
==================

The object pVariableName, is a symbol (Macaulay2Doc).

SimpleTreks -- optional input for gaussianParametrization
*********************************************************

Description
===========

This is an option to tell gaussianParametrization,
to use simple treks.  false is the default option.

See also
========

  * gaussianParametrization -- parametrization
    of the covariance matrix in terms of treks

Functions with optional argument named SimpleTreks :
====================================================

  * gaussianParametrization(...,SimpleTreks=>...),
    --
    optional input for gaussianParametrization

For the programmer
==================

The object SimpleTreks, is a symbol (Macaulay2Doc).

sVar -- key in hash table gaussianRingData: labels of s variables
*****************************************************************

Description
===========

This key is present in every gaussianRingData that comes from a graph. It is
equal to the value of the optional input
gaussianRing(...,sVariableName=>...).

+----------------------------------------+
|i1 : U = graph {{1,2},{2,3}}            |
|                                        |
|o1 = Graph{1 => {2}   }                 |
|           2 => {1, 3}                  |
|           3 => {2}                     |
|                                        |
|o1 : Graph                              |
+----------------------------------------+
|i2 : B = bigraph{{4,5}}                 |
|                                        |
|o2 = Bigraph{4 => {5}}                  |
|             5 => {4}                   |
|                                        |
|o2 : Bigraph                            |
+----------------------------------------+
|i3 : D = digraph {{1,4}}                |
|                                        |
|o3 = Digraph{1 => {4}}                  |
|             4 => {}                    |
|                                        |
|o3 : Digraph                            |
+----------------------------------------+
|i4 : R1 = gaussianRing B                |
|                                        |
|o4 = R1                                 |
|                                        |
|o4 : PolynomialRing                     |
+----------------------------------------+
|i5 : R2 = gaussianRing D                |
|                                        |
|o5 = R2                                 |
|                                        |
|o5 : PolynomialRing                     |
+----------------------------------------+
|i6 : R3 = gaussianRing U                |
|                                        |
|o6 = R3                                 |
|                                        |
|o6 : PolynomialRing                     |
+----------------------------------------+
|i7 : R4 = gaussianRing mixedGraph(U,B,D)|
|                                        |
|o7 = R4                                 |
|                                        |
|o7 : PolynomialRing                     |
+----------------------------------------+
|i8 : R1.gaussianRingData                |
|                                        |
|o8 = HashTable{compU => {}    }         |
|               compW => {4, 5}          |
|               kVar => k                |
|               lVar => l                |
|               nn => 2                  |
|               pVar => p                |
|               sVar => s                |
|                                        |
|o8 : HashTable                          |
+----------------------------------------+
|i9 : R2.gaussianRingData                |
|                                        |
|o9 = HashTable{compU => {}    }         |
|               compW => {1, 4}          |
|               kVar => k                |
|               lVar => l                |
|               nn => 2                  |
|               pVar => p                |
|               sVar => s                |
|                                        |
|o9 : HashTable                          |
+----------------------------------------+
|i10 : R3.gaussianRingData               |
|                                        |
|o10 = HashTable{kVar => k}              |
|                nn => 3                 |
|                sVar => s               |
|                                        |
|o10 : HashTable                         |
+----------------------------------------+
|i11 : R4.gaussianRingData               |
|                                        |
|o11 = HashTable{compU => {1, 2, 3}}     |
|                compW => {4, 5}         |
|                kVar => k               |
|                lVar => l               |
|                nn => 5                 |
|                pVar => p               |
|                sVar => s               |
|                                        |
|o11 : HashTable                         |
+----------------------------------------+

See also
========

  * sVariableName -- optional input to choose the
    variable names for the covariance matrix
  * gaussianRingData -- hash table with main
    parameters of a gaussian ring
  * pVar -- key in hash table gaussianRingData: labels of p
    variables
  * lVar -- key in hash table gaussianRingData: labels of l
    variables
  * kVar -- key in hash table gaussianRingData: labels of k
    variables
  * compU -- key in hash table gaussianRingData: component of
    undirected edges in vertex set of a mixed graph
  * compW -- key in hash table gaussianRingData: component of
    bidirected edges in vertex set of a mixed graph
  * nn -- key in hash table gaussianRingData: total number of
    variables

For the programmer
==================

The object sVar, is a symbol (Macaulay2Doc).

sVariableName -- optional input to choose the variable names for the covariance matrix
**************************************************************************************

Description
===========

Put sVariableName =>  Symbol for a choice of a symbol s as an argument in the
function gaussianRing,

See also
========

  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model

Functions with optional argument named sVariableName :
======================================================

  * gaussianRing(...,sVariableName=>...)
    -- symbol used for
    indeterminates in a ring of Gaussian joint probability distributions

For the programmer
==================

The object sVariableName, is a symbol (Macaulay2Doc).

trekIdeal -- trek separation ideal of a mixed graph
***************************************************

Synopsis
========

  * Usage:
        I = trekIdeal(R,G)
  * Inputs:
      * R, a ring (Macaulay2Doc), which should be a gaussianRing
      * G, a graph (Graphs), a graph (Graphs), or a
        digraph (Graphs), with no cycles, or an instance of the
        type MixedGraph (StatGraphs), with directed and
        bidirected edges
  * Outputs:
      * I, an ideal (Macaulay2Doc), the ideal of determinantal
        trek separation statements implied by the graph $G$.

Description
===========

For mixed graphs, the ideal corresponding to all trek separation statements
{A,B,CA,CB} (where A,B,CA,CB are disjoint lists of vertices of G) is generated
by the r+1 x r+1 minors of the submatrix of the covariance matrix M =
(s_{(i,j)}), whose rows are in A, and whose columns are in B, and where r =
#CA+#CB.

This function is not yet implemented for mixed graphs with undirected edges.

These ideals are described in more detail by Sullivant, Talaska and Draisma in
"Trek Separation for Gaussian Graphical Models" Annals of Statistics 38 no.3
(2010) 1665–1685 and give all determinantal constraints on the covariance
matrix of a Gaussian graphical model.

+-----------------------------------------------------------------------------+
|i1 : G = mixedGraph(digraph {{b,{c,d}},{c,{d}}},bigraph {{a,d}})             |
|                                                                             |
|o1 = MixedGraph{Bigraph => Bigraph{a => {d}}   }                             |
|                                   d => {a}                                  |
|                Digraph => Digraph{b => {c, d}}                              |
|                                   c => {d}                                  |
|                                   d => {}                                   |
|                Graph => Graph{}                                             |
|                                                                             |
|o1 : MixedGraph                                                              |
+-----------------------------------------------------------------------------+
|i2 : R = gaussianRing G                                                      |
|                                                                             |
|o2 = R                                                                       |
|                                                                             |
|o2 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i3 : T = trekIdeal(R,G)                                                      |
|                                                                             |
|o3 = ideal (s   , s   , - s   s    + s   s   , - s   s    + s   s   , -      |
|             a,b   a,c     a,c b,b    a,b b,c     a,c b,b    a,b b,c         |
|     ------------------------------------------------------------------------|
|     s   s    + s   s   , s   s    - s   s   )                               |
|      a,c b,c    a,b c,c   a,c b,d    a,b c,d                                |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i4 : ideal gens gb T                                                         |
|                                                                             |
|o4 = ideal (s   , s   )                                                      |
|             a,c   a,b                                                       |
|                                                                             |
|o4 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+

For undirected graphs $G$, the trekIdeal(R,G) is the same as
conditionalIndependenceIdeal(R,globalMarkov(G)).  For directed graphs $G$,
trekIdeal(R,G) is generally larger than
conditionalIndependenceIdeal(R,globalMarkov(G)).

+-----------------------------------------------------------+
|i5 : G = graph{{a,b},{b,c},{c,d},{a,d}}                    |
|                                                           |
|o5 = Graph{a => {b, d}}                                    |
|           b => {a, c}                                     |
|           c => {b, d}                                     |
|           d => {a, c}                                     |
|                                                           |
|o5 : Graph                                                 |
+-----------------------------------------------------------+
|i6 : R = gaussianRing G                                    |
|                                                           |
|o6 = R                                                     |
|                                                           |
|o6 : PolynomialRing                                        |
+-----------------------------------------------------------+
|i7 : T = trekIdeal(R,G);                                   |
|                                                           |
|o7 : Ideal of R                                            |
+-----------------------------------------------------------+
|i8 : CI = conditionalIndependenceIdeal(R,globalMarkov(G)); |
|                                                           |
|o8 : Ideal of R                                            |
+-----------------------------------------------------------+
|i9 : T == CI                                               |
|                                                           |
|o9 = true                                                  |
+-----------------------------------------------------------+
|i10 : H = digraph{{1,{4}},{2,{4}},{3,{4,5}},{4,{5}}}       |
|                                                           |
|o10 = Digraph{1 => {4}   }                                 |
|              2 => {4}                                     |
|              3 => {4, 5}                                  |
|              4 => {5}                                     |
|              5 => {}                                      |
|                                                           |
|o10 : Digraph                                              |
+-----------------------------------------------------------+
|i11 : R = gaussianRing H                                   |
|                                                           |
|o11 = R                                                    |
|                                                           |
|o11 : PolynomialRing                                       |
+-----------------------------------------------------------+
|i12 : T = trekIdeal(R,H);                                  |
|                                                           |
|o12 : Ideal of R                                           |
+-----------------------------------------------------------+
|i13 : CI = conditionalIndependenceIdeal(R,globalMarkov(H));|
|                                                           |
|o13 : Ideal of R                                           |
+-----------------------------------------------------------+
|i14 : T == CI                                              |
|                                                           |
|o14 = false                                                |
+-----------------------------------------------------------+

Caveat
======

trekSeparation is currently only implemented with mixedGraphs that have
directed and bidirected edges.

See also
========

  * trekSeparation -- trek separation statements of a
    mixed graph

Ways to use trekIdeal :
=======================

  * "trekIdeal(Ring,Digraph)"
  * "trekIdeal(Ring,Graph)"
  * "trekIdeal(Ring,MixedGraph)"

For the programmer
==================

The object trekIdeal, is a method function (Macaulay2Doc).

trekSeparation -- trek separation statements of a mixed graph
*************************************************************

Synopsis
========

  * Usage:
        trekSeparation(G)
  * Inputs:
      * G, an instance of the type MixedGraph (StatGraphs),
        mixed graph with directed and bidirected edges
  * Outputs:
      * a list (Macaulay2Doc), of lists \{A,B,CA,CB\}, where
        (CA,CB) trek-separates A from B

Description
===========

A trek between vertices $i$ and $j$ in a mixed graph $G$ with directed and
bidirected edges is a triple $(P_L,P_R)$ where $P_L$ is a directed path of
directed edges with sink $i$ and source $k$, $P_R$ is a directed path of
directed edges with sink $j$ and source $l$, and either $k=l$ or there is a
bidirected edge between $k$ and $l$. Let $A,B,CA,CB$ be subsets of vertices of
$G$.

We say that $(CA,CB)$ trek-separates $A$ from $B$ in $G$ if for every trek
$(P_L,P_R)$ from a vertex in $A$ to a vertex in $B$, either $P_L$ contains a
vertex in $CA$ or $P_R$ contains a vertex in $CB$.

The function trekSeparation, returns a list of trek
separation statements $\{A,B,CA,CB\}$\,where $#CA + #CB < min(#A, #B)$. Each
statement is maximal in the ordering where
$\{A1,B1,CA,CB\}\,<\,\{A2,B2,CA,CB\}$\,if $A1$ is a subset of $A2$ and $B1$ is
a subset of $B2$. Each statement is also unique up to symmetry, since
$\{B,A,CB,CA\}$\,is a trek separation statement if and only if $\{A,B,CA,CB\}$.

+-----------------------------------------------------------------------------+
|i1 : G = mixedGraph(digraph {{b,{c,d}},{c,{d}}},bigraph {{a,d}})             |
|                                                                             |
|o1 = MixedGraph{Bigraph => Bigraph{a => {d}}   }                             |
|                                   d => {a}                                  |
|                Digraph => Digraph{b => {c, d}}                              |
|                                   c => {d}                                  |
|                                   d => {}                                   |
|                Graph => Graph{}                                             |
|                                                                             |
|o1 : MixedGraph                                                              |
+-----------------------------------------------------------------------------+
|i2 : S = trekSeparation G                                                    |
|                                                                             |
|o2 = {{{a}, {b, c}, {}, {}}, {{a, b}, {b, c}, {}, {b}}, {{b, c}, {a, b}, {}, |
|     ------------------------------------------------------------------------|
|     {b}}, {{b, c}, {a, c}, {}, {c}}, {{b, c}, {d, a}, {}, {d}}}             |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

Caveat
======

trekSeparation $G$ is only implemented for mixedGraphs with directed and
bidirected edges.

See also
========

  * trekIdeal -- trek separation ideal of a mixed graph

Ways to use trekSeparation :
============================

  * "trekSeparation(MixedGraph)"

For the programmer
==================

The object trekSeparation, is a method function (Macaulay2Doc).

undirectedEdgesMatrix -- matrix corresponding to the edges of an undirected graph
*********************************************************************************

Synopsis
========

  * Usage:
        undirectedEdgesMatrix(R)
  * Inputs:
      * R, a ring (Macaulay2Doc), which should be created with
        gaussianRing, created with a graph (Graphs),
        or an instance of the type MixedGraph (StatGraphs),
  * Outputs:
      * a matrix (Macaulay2Doc), the n x n symmetric
        concentration matrix of an undirected gaussian graphical model.

Description
===========

This symmetric matrix has entries $k_{(i,i)}$ along the diagonal and entry
$k_{(i,j)}$ in the $(i,j)$ position if there is an edge  between i and j, and a
zero otherwise. The documentation of gaussianRing, further
describes the indeterminates $k_{(i,j)}$.

+-----------------------------------------+
|i1 : G = graph({{a,b},{b,c},{c,d},{a,d}})|
|                                         |
|o1 = Graph{a => {b, d}}                  |
|           b => {a, c}                   |
|           c => {b, d}                   |
|           d => {a, c}                   |
|                                         |
|o1 : Graph                               |
+-----------------------------------------+
|i2 : R = gaussianRing G                  |
|                                         |
|o2 = R                                   |
|                                         |
|o2 : PolynomialRing                      |
+-----------------------------------------+
|i3 : compactMatrixForm =false;           |
+-----------------------------------------+
|i4 : K = undirectedEdgesMatrix(R)        |
|                                         |
|o4 = |  k     k       0   k     |        |
|     |   a,a   a,b         a,d  |        |
|     |                          |        |
|     |  k     k     k       0   |        |
|     |   a,b   b,b   b,c        |        |
|     |                          |        |
|     |    0   k     k     k     |        |
|     |         b,c   c,c   c,d  |        |
|     |                          |        |
|     |  k       0   k     k     |        |
|     |   a,d         c,d   d,d  |        |
|                                         |
|             4       4                   |
|o4 : Matrix R  <--- R                    |
+-----------------------------------------+

For mixed graphs with other types of edges, the size of the matrix coincides
with the number of elements in compU, which depends on the vertex
partition built in partitionLMG (StatGraphs).

+-------------------------------------------------------------------------+
|i5 : G = mixedGraph(digraph {{1,3},{2,4}},bigraph {{3,4}},graph {{1,2}});|
+-------------------------------------------------------------------------+
|i6 : R = gaussianRing G;                                                 |
+-------------------------------------------------------------------------+
|i7 : K = undirectedEdgesMatrix(R)                                        |
|                                                                         |
|o7 = |  k     k     |                                                    |
|     |   1,1   1,2  |                                                    |
|     |              |                                                    |
|     |  k     k     |                                                    |
|     |   1,2   2,2  |                                                    |
|                                                                         |
|             2       2                                                   |
|o7 : Matrix R  <--- R                                                    |
+-------------------------------------------------------------------------+

See also
========

  * gaussianRing -- ring of Gaussian correlations on n
    random variables or a graphical model
  * gaussianParametrization -- parametrization
    of the covariance matrix in terms of treks
  * covarianceMatrix -- covariance matrix of a
    Gaussian graphical model
  * directedEdgesMatrix -- matrix corresponding to
    the directed edges of a digraph or a mixed graph

Ways to use undirectedEdgesMatrix :
===================================

  * "undirectedEdgesMatrix(Ring)"

For the programmer
==================

The object undirectedEdgesMatrix, is a
method function (Macaulay2Doc).

VariableName -- optional input to choose indeterminate name in markovRing
*************************************************************************

Description
===========

The option VariableName => q changes the symbol used for intedeterminates in a
polynomial ring created with markovRing.

See also
========

  * markovRing -- ring of joint probability distributions on
    several discrete random variables

Functions with optional argument named VariableName :
=====================================================

  * markovRing(...,VariableName=>...)
    -- symbol used for
    indeterminates in a ring of discrete joint probability distributions

For the programmer
==================

The object VariableName, is a symbol (Macaulay2Doc).