# Gaussian Graphical Models

The OSCAR type for graphical models is of parametrized form `GraphicalModel{G, T}`

where `T`

represents the type of ring in which the vanishing ideal of the model belongs and `G`

represents the associated graph. Gaussian graphical models are those where the `T`

is of type `GaussianRing`

which is a multivariate polynomial ring equipped with some extra features.

## Gaussian Rings

`gaussian_ring`

— Method`gaussian_ring(n::Int; s_var_name::VarName="s", K::Field=QQ, cached=false)`

A polynomial ring whose variables correspond to the entries of a covariance matrix of `n`

Gaussian random variables. It is a multivariate polynomial ring whose variables are named `s[i,j]`

and whose coefficient field `K`

is by default `QQ`

.

If `cached`

is `true`

, the internally generated polynomial ring will be cached.

**Examples**

```
julia> R = gaussian_ring(3)
Gaussian ring over Rational field in 6 variables
s[1, 1], s[1, 2], s[1, 3], s[2, 2], s[2, 3], s[3, 3]
```

This function is part of the experimental code in Oscar. Please read here for more details.

`gens`

— Method`gens(R::GaussianRing)`

Return the generators of the multivariate polynomial ring inside the GaussianRing as a dictionary which can be easily indexed

**Examples**

```
julia> R = gaussian_ring(3)
Gaussian ring over Rational field in 6 variables
s[1, 1], s[1, 2], s[1, 3], s[2, 2], s[2, 3], s[3, 3]
julia> gens(R)
Dict{Tuple{Int64, Int64}, QQMPolyRingElem} with 6 entries:
(1, 2) => s[1, 2]
(1, 1) => s[1, 1]
(3, 3) => s[3, 3]
(1, 3) => s[1, 3]
(2, 2) => s[2, 2]
(2, 3) => s[2, 3]
```

This function is part of the experimental code in Oscar. Please read here for more details.

`covariance_matrix`

— Method`covariance_matrix(R::GaussianRing)`

Return the covariance matrix associated to `R`

as a matrix over the underlying polynomial ring of `R`

**Examples**

```
julia> R = gaussian_ring(3)
Gaussian ring over Rational field in 6 variables
s[1, 1], s[1, 2], s[1, 3], s[2, 2], s[2, 3], s[3, 3]
julia> covariance_matrix(R)
[s[1, 1] s[1, 2] s[1, 3]]
[s[1, 2] s[2, 2] s[2, 3]]
[s[1, 3] s[2, 3] s[3, 3]]
```

This function is part of the experimental code in Oscar. Please read here for more details.

## Directed Gaussian Graphical Models

A directed Gaussian graphical model is constructed from `G::Graph{Directed}`

and `S::GaussianRing`

. Optionally, the user may specify a string `l_var_name::String`

which corresponds to the edge weights in the parametrization of the model and a string `w_var_name::String`

for labeling the error covariance parameters.

`graphical_model`

— Method`graphical_model(G::Graph{Directed}, S::GaussianRing; l_var_name::VarName="l", w_var_name::VarName="w", cached=false)`

A parametric statistical model associated to a directed acyclic graph. It contains a directed acylic graph `G`

, a GaussianRing `S`

where the vanishing ideal of the model naturally lives, and a parameter ring whose variables `l[i,j]`

correspond to the directed edges `i -> j`

in `G`

.

If `cached`

is `true`

, the internally generated polynomial ring will be cached.

**Examples**

```
julia> M = graphical_model(graph_from_edges(Directed, [[1,2], [2,3]]), gaussian_ring(3))
Gaussian graphical model on a directed graph with edges:
(1, 2), (2, 3)
```

This function is part of the experimental code in Oscar. Please read here for more details.

The parametrization for a directed Gaussian graphical model on a DAG $G$ is built from the weighted adjacency matrix $\Lambda$ and the covariance matrix $\Omega$ of the error terms. The model is then the set of all covariance matrices $\Sigma = (Id - \Lambda)^{-T} \Omega (Id - \Lambda)^{-1}$. $\Lambda$ and $\Omega$ can be built with the following functions:

`directed_edges_matrix`

— Method`directed_edges_matrix(M::GraphicalModel{Graph{Directed}, GaussianRing})`

Creates the weighted adjacency matrix $\Lambda$ of a directed graph `G`

whose entries are the parameter ring of the graphical model `M`

.

**Examples**

```
julia> M = graphical_model(graph_from_edges(Directed, [[1,2], [2,3]]), gaussian_ring(3))
Gaussian graphical model on a directed graph with edges:
(1, 2), (2, 3)
julia> directed_edges_matrix(M)
[0 l[1, 2] 0]
[0 0 l[2, 3]]
[0 0 0]
```

This function is part of the experimental code in Oscar. Please read here for more details.

`error_covariance_matrix`

— Method`error_covariance_matrix(M::GraphicalModel{Graph{Directed}, GaussianRing})`

Creates the covariance matrix $ \Omega $ of the independent error terms in a directed Gaussian graphical model `M`

**Examples**

```
julia> M = graphical_model(graph_from_edges(Directed, [[1,2], [2,3]]), gaussian_ring(3))
Gaussian graphical model on a directed graph with edges:
(1, 2), (2, 3)
julia> error_covariance_matrix(M)
[w[1] 0 0]
[ 0 w[2] 0]
[ 0 0 w[3]]
```

This function is part of the experimental code in Oscar. Please read here for more details.

It is easy to create new types of graphical models by overloading the methods `directed_edges_matrix`

and `error_covariance_matrix`

. For instance, colored graphical models may easily be created by creating a new type of `GraphicalModel{G, T}`

and a new `directed_edges_matrix`

function. The following two functions will then work almost immediately on this new type.

`parametrization`

— Method`parametrization(M::GraphicalModel{Graph{Directed}, GaussianRing})`

Creates the polynomial map which parametrizes the vanishing ideal of the directed Gaussian graphical model `M`

. The vanishing ideal of the statistical model is the kernel of this map. This ring map is the pull back of the parametrization $\phi_G$ given by $(Id - \Lambda)^{-T} \Omega (Id - \Lambda)^{T} \mapsto \Sigma$ where $\Lambda =$ `directed_edges_matrix(M)`

and $ \Omega = $ `error_covariance_matrix(M)`

.

**Examples**

```
julia> M = graphical_model(graph_from_edges(Directed, [[1,2], [2,3]]), gaussian_ring(3))
Gaussian graphical model on a directed graph with edges:
(1, 2), (2, 3)
julia> parametrization(M)
Ring homomorphism
from multivariate polynomial ring in 6 variables over QQ
to multivariate polynomial ring in 5 variables over QQ
defined by
s[1, 1] -> w[1]
s[1, 2] -> l[1, 2]*w[1]
s[1, 3] -> l[1, 2]*l[2, 3]*w[1]
s[2, 2] -> l[1, 2]^2*w[1] + w[2]
s[2, 3] -> l[1, 2]^2*l[2, 3]*w[1] + l[2, 3]*w[2]
s[3, 3] -> l[1, 2]^2*l[2, 3]^2*w[1] + l[2, 3]^2*w[2] + w[3]
```

This function is part of the experimental code in Oscar. Please read here for more details.

`vanishing_ideal`

— Method`vanishing_ideal(M::GraphicalModel)`

Computes the vanishing ideal for a graphical model `M`

. This is done by computing the kernel of the parametrization.

**Examples**

```
julia> M = graphical_model(graph_from_edges(Directed, [[1,2], [2,3]]), gaussian_ring(3))
Gaussian graphical model on a directed graph with edges:
(1, 2), (2, 3)
julia> vanishing_ideal(M)
Ideal generated by
-s[1, 2]*s[2, 3] + s[1, 3]*s[2, 2]
```

This function is part of the experimental code in Oscar. Please read here for more details.

With almost all graphical models, the vanishing ideal is computed by taking the kernel of the ring map given by `parametrization(M:GraphicalModel{G, T})`

.

## Undirected Gaussian Graphical Models

A undirected Gaussian graphical model is constructed from `G::Graph{Undirected}`

, `S::GaussianRing`

. Optionally, the user may specify a string `k_var_name::String`

which corresponds to the entries of the concentration matrix.

`graphical_model`

— Method`graphical_model(G::Graph{Undirected}, S::GaussianRing; k_var_name::VarName="k", cached=false)`

A parametric statistical model associated to an undirected graph. It contains an undirected graph `G`

, a GaussianRing `S`

where the vanishing ideal of the model naturally lives, and a parameter ring whose variables `k[i,j]`

correspond to the edges `i - j`

in `G`

.

If `cached`

is `true`

, the internally generated polynomial ring will be cached.

**Examples**

```
julia> M = graphical_model(graph_from_edges([[1,2], [2,3]]), gaussian_ring(3))
Gaussian graphical model on an undirected graph with edges:
(1, 2), (2, 3)
```

This function is part of the experimental code in Oscar. Please read here for more details.

As with their directed counterpart, it is very easy to create new subtypes of graphical models by overloading the function `concentration_matrix`

below. Unlike most other types of graphical models though, the vanishing ideal computation of an undirected graphical model is done by eliminating all concentration variables $k_{ij}$ from the ideal given by the equations $\Sigma K - Id$ after saturating by $\det(K)$.

`concentration_matrix`

— Method`concentration_matrix(M::GraphicalModel{Graph{Undirected}, GaussianRing})`

Creates the concentration matrix `K`

of an undirected Gaussian graphical model which is a symmetric positive definite matrix whose nonzero entries correspond to the edges of the associated graph.

**Examples**

```
julia> M = graphical_model(graph_from_edges([[1,2], [2,3]]), gaussian_ring(3))
Gaussian graphical model on an undirected graph with edges:
(1, 2), (2, 3)
julia> concentration_matrix(M)
[k[1, 1] k[1, 2] 0]
[k[1, 2] k[2, 2] k[2, 3]]
[ 0 k[2, 3] k[3, 3]]
```

This function is part of the experimental code in Oscar. Please read here for more details.

`parametrization`

— Method`parametrization(M::GraphicalModel{Graph{Undirected}, GaussianRing})`

Creates the polynomial map which parametrizes the vanishing ideal of the undirected Gaussian graphical model `M`

. The vanishing ideal of the statistical model is the kernel of this map. This ring map is the pull back of the parametrization $\phi_G$ given by $ K \mapsto K^{-1}$ where $ K = $ `concentration_matrix(M)`

and the entries of $ K^{-1} $ are given by the standard cofactor formula.

**Examples**

```
julia> M = graphical_model(graph_from_edges([[1,2], [2,3]]), gaussian_ring(3))
Gaussian graphical model on an undirected graph with edges:
(1, 2), (2, 3)
julia> parametrization(M)
Ring homomorphism
from multivariate polynomial ring in 6 variables over QQ
to fraction field of multivariate polynomial ring
defined by
s[1, 1] -> (k[2, 2]*k[3, 3] - k[2, 3]^2)//(k[1, 1]*k[2, 2]*k[3, 3] - k[1, 1]*k[2, 3]^2 - k[1, 2]^2*k[3, 3])
s[1, 2] -> (-k[1, 2]*k[3, 3])//(k[1, 1]*k[2, 2]*k[3, 3] - k[1, 1]*k[2, 3]^2 - k[1, 2]^2*k[3, 3])
s[1, 3] -> (k[1, 2]*k[2, 3])//(k[1, 1]*k[2, 2]*k[3, 3] - k[1, 1]*k[2, 3]^2 - k[1, 2]^2*k[3, 3])
s[2, 2] -> (k[1, 1]*k[3, 3])//(k[1, 1]*k[2, 2]*k[3, 3] - k[1, 1]*k[2, 3]^2 - k[1, 2]^2*k[3, 3])
s[2, 3] -> (-k[1, 1]*k[2, 3])//(k[1, 1]*k[2, 2]*k[3, 3] - k[1, 1]*k[2, 3]^2 - k[1, 2]^2*k[3, 3])
s[3, 3] -> (k[1, 1]*k[2, 2] - k[1, 2]^2)//(k[1, 1]*k[2, 2]*k[3, 3] - k[1, 1]*k[2, 3]^2 - k[1, 2]^2*k[3, 3])
```

This function is part of the experimental code in Oscar. Please read here for more details.

`vanishing_ideal`

— Method`vanishing_ideal(M::GraphicalModel{Graph{Undirected}, GaussianRing})`

Computes the vanishing ideal of the undirected Gaussian graphical model `M`

. This is done by saturating the ideal given by $ \Sigma K - Id $ by the determinant of $ K $ and then eliminating all variables `k[i,j]`

where $ K =$ `concentration_matrix(M)`

.

**Examples**

```
julia> M = graphical_model(graph_from_edges([[1,2], [2,3]]), gaussian_ring(3))
Gaussian graphical model on an undirected graph with edges:
(1, 2), (2, 3)
julia> vanishing_ideal(M)
Ideal generated by
-s[1, 2]*s[2, 3] + s[1, 3]*s[2, 2]
```

This function is part of the experimental code in Oscar. Please read here for more details.