This is GraphicalModelsMLE.info, produced by Macaulay2, version 1.24.11

GraphicalModelsMLE -- a package for MLE of parameters for Gaussian graphical models
***********************************************************************************

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

Graphical Models MLE is a package for algebraic statistics that broadens the
functionalities of GraphicalModels. It computes
the maximum likelihood estimates (MLE) of the covariance matrix of Gaussian
graphical models associated to loopless mixed graphs(LMG).

The main features of the package are the computation of the
sampleCovarianceMatrix, of sample data, the ideal
generated by scoreEquations, of log-likelihood functions
of Gaussian graphical model, the MLdegree, of such models and
the MLE for the covariance or concentration matrix via solverMLE.

For more details on the type of graphical models that are accepted see
gaussianRing (GraphicalModels). In particular, for further
information about LMG with undirected, directed and bidirected edges, check
partitionLMG (StatGraphs).

References:

An introduction to key notions such as MLE and ML-degree can be found in the
books:

Seth Sullivant, Algebraic statistics, American Mathematical Society, Vol 194,
2018.

Mathias Drton, Bernd Sturmfels and Seth Sullivant, Lectures on Algebraic
Statistics, Oberwolfach Seminars, Vol 40, Birkhauser, Basel, 2009.

The definition and classification of loopless mixed graphs (LMG) can be found
in the paper:

Kayvan Sadeghi and Steffen Lauritzen, Markov properties for mixed graphs,
Bernoulli, 20 (2014), no 2, 676-696.

Examples:

Computation of a sample covariance matrix from sample data:

+------------------------------------------------------------------+
|i1 : U= matrix{{1,2,1,-1},{2,1,3,0},{-1, 0, 1, 1},{-5, 3, 4, -6}};|
|                                                                  |
|              4       4                                           |
|o1 : Matrix ZZ  <-- ZZ                                            |
+------------------------------------------------------------------+
|i2 : sampleCovarianceMatrix(U)                                    |
|                                                                  |
|o2 = | 115/16 -13/8 -29/16 47/8  |                                |
|     | -13/8  5/4   7/8    -11/4 |                                |
|     | -29/16 7/8   27/16  -21/8 |                                |
|     | 47/8   -11/4 -21/8  29/4  |                                |
|                                                                  |
|              4       4                                           |
|o2 : Matrix QQ  <-- QQ                                            |
+------------------------------------------------------------------+

The ideal generated by the score equations of the log-likelihood function of
the graphical model associated to the graph $1\rightarrow 2,1\rightarrow
3,2\rightarrow 3,3\rightarrow 4,3<-> 4$ is computed as follows:

+-----------------------------------------------------------------------------+
|i3 : G = mixedGraph(digraph {{1,2},{1,3},{2,3},{3,4}},bigraph{{3,4}});       |
+-----------------------------------------------------------------------------+
|i4 : R = gaussianRing(G);                                                    |
+-----------------------------------------------------------------------------+
|i5 : U = matrix{{6, 10, 1/3, 1}, {3/5, 3, 1/2, 1}, {4/5, 3/2, 9/8, 3/10},    |
|                                                                             |
|              4       4                                                      |
|o5 : Matrix QQ  <-- QQ                                                       |
|-----------------------------------------------------------------------------|
|{10/7, 2/3,1, 8/3}};                                                         |
+-----------------------------------------------------------------------------+
|i6 : scoreEquations(R,U)                                                     |
|                                                                             |
|o6 = ideal (192199680p    - 99333449, 267221621760p    - 849243924773,       |
|                      3,4                          4,4                       |
|     ------------------------------------------------------------------------|
|     1353974896462794079472640p    - 142165262245288892244817, 6898968p    - |
|                               3,3                                     2,2   |
|     ------------------------------------------------------------------------|
|     11533057, 19600p    - 95819, 20855l    + 90447,                         |
|                     1,1                3,4                                  |
|     ------------------------------------------------------------------------|
|     146915678869660815915l    - 4228634793402814499,                        |
|                           2,3                                               |
|     ------------------------------------------------------------------------|
|     58766271547864326366l    + 4167005135395196717, 574914l    - 896035)    |
|                          1,3                               1,2              |
|                                                                             |
|o6 : Ideal of QQ[l   ..l   , l   , l   , p   , p   , p   , p   , p   ]       |
|                  1,2   1,3   2,3   3,4   1,1   2,2   3,3   4,4   3,4        |
+-----------------------------------------------------------------------------+

Computation of the ML-degree of the 4-cycle:

+--------------------------------------+
|i7 : G=graph{{1,2},{2,3},{3,4},{4,1}};|
+--------------------------------------+
|i8 : MLdegree(gaussianRing G)         |
|                                      |
|o8 = 5                                |
+--------------------------------------+

Next compute the MLE for the covariance matrix of the graphical model
associated to the graph $1\rightarrow 3,2\rightarrow 4,3<-> 4,1 - 2$. The input
is the sample covariance instead of the sample data.

+-----------------------------------------------------------------------------+
|i9 : G = mixedGraph(digraph {{1,3},{2,4}},bigraph {{3,4}},graph {{1,2}});    |
+-----------------------------------------------------------------------------+
|i10 : V =  matrix {{7/20, 13/50, -3/50, -19/100}, {13/50, 73/100, -7/100,    |
|                                                                             |
|               4       4                                                     |
|o10 : Matrix QQ  <-- QQ                                                      |
|-----------------------------------------------------------------------------|
|-9/100},{-3/50, -7/100, 2/5, 3/50}, {-19/100, -9/100, 3/50, 59/100}};        |
+-----------------------------------------------------------------------------+
|i11 : solverMLE(G,V,SampleData=>false)                                       |
|                                                                             |
|o11 = (-.655574, {| .35       .26       -.0548792 -.19146  |}, 2)            |
|                  | .26       .73       -.0291359 -.101648 |                 |
|                  | -.0548792 -.0291359 .4        .06      |                 |
|                  | -.19146   -.101648  .06       .59      |                 |
|                                                                             |
|o11 : Sequence                                                               |
+-----------------------------------------------------------------------------+

As an application of solverMLE,: positive definite matrix
completion

Consider the following symmetric matrix with some unknown entries:

+---------------------------------------------------------------------+
|i12 : R=QQ[x,y];                                                     |
+---------------------------------------------------------------------+
|i13 : M=matrix{{115,-13,x,47},{-13,5,7,y},{x,7,27,-21},{47,y,-21,29}}|
|                                                                     |
|o13 = | 115 -13 x   47  |                                            |
|      | -13 5   7   y   |                                            |
|      | x   7   27  -21 |                                            |
|      | 47  y   -21 29  |                                            |
|                                                                     |
|              4      4                                               |
|o13 : Matrix R  <-- R                                                |
+---------------------------------------------------------------------+

Unknown entries correspond to the non-edges of the 4-cycle. A positive definite
completion of this matrix is obtained by giving values to x and y and computing
the MLE for the covariance matrix in the Gaussian graphical model given by the
4-cycle. Check solverMLE, for more details.

+-----------------------------------------------------------------------------+
|i14 : G=graph{{1,2},{2,3},{3,4},{1,4}};                                      |
+-----------------------------------------------------------------------------+
|i15 : V=matrix{{115,-13,-29,47},{-13,5,7,-11},{-29,7,27,-21},{47,-11,-21,29  |
|                                                                             |
|               4       4                                                     |
|o15 : Matrix ZZ  <-- ZZ                                                      |
|-----------------------------------------------------------------------------|
|}};                                                                          |
+-----------------------------------------------------------------------------+
|i16 : (mx,MLE,ML)=solverMLE(G,V,SampleData=>false)                           |
|                                                                             |
|o16 = (-15.8404, | 115      -13       .645756  -.129151  |, 1)               |
|                 | -13      5         .0922509 -.0184502 |                   |
|                 | .645756  .0922509  27       -21       |                   |
|                 | -.129151 -.0184502 -21      29        |                   |
|                                                                             |
|o16 : Sequence                                                               |
+-----------------------------------------------------------------------------+

Caveat
======

GraphicalModelsMLE requires Graphs,  StatGraphs,
and  GraphicalModels. In order to
use the default numerical solver, it also requires EigenSolver.

See Graphs, allows 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
GraphicalModelsMLE must have sortable vertex labels, e.g., all numbers or all
letters.

See StatGraphs, allows the user to work with objects such as
bigraphs and mixedGraphs.

See GraphicalModels, is used to generate
gaussianRing (GraphicalModels), i.e. rings encoding graph
properties.

Authors
=======

  * Carlos Amendola (see http://www.carlos-amendola.com/ )
    <carlos.amendola@mis.mpg.de>
  * Luis David Garcia Puente (see https://luisgarciapuente.github.io )
    <lgarciapuente@coloradocollege.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>
  * Elina Robeva (see https://www.math.ubc.ca/~erobeva/ ) <erobeva@gmail.com>
  * David Swinarski (see http://faculty.fordham.edu/dswinarski )
    <dswinarski@fordham.edu>

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

Version 1.0 of this package was accepted for publication in volume 12 (see
https://msp.org/jsag/2022/12-1/ ) of The Journal of Software for Algebra and
Geometry (see https://msp.org/jsag/ ) on 14 March 2022, in the article
Computing maximum likelihood estimates for Gaussian graphical models with
Macaulay2 (see https://msp.org/jsag/2022/12-1/p01.xhtml ) (DOI:
10.2140/jsag.2022.12.1 (see https://doi.org/10.2140/jsag.2022.12.1 )). That
version can be obtained from the journal (see
https://msp.org/jsag/2022/12-1/jsag-v12-n1-x01-GraphicalModelsMLE.zip ) or from
the Macaulay2 source code repository (see
https://github.com/Macaulay2/M2/blob/f0aaf5e74216283f022f7773bc1116f8de6b944b/
M2/Macaulay2/packages/GraphicalModelsMLE.m2 ).

Version
=======

This documentation describes version 1.0 of GraphicalModelsMLE.

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

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

Exports
=======

  * Functions and commands
      * checkPD -- returns positive definite matrices from a
        list of symmetric  matrices
      * checkPSD -- returns positive semidefinite matrices
        from a list of symmetric matrices
      * jacobianMatrixOfRationalFunction
        -- Jacobian matrix of a rational
        function
      * MLdegree -- ML-degree of a graphical model
      * sampleCovarianceMatrix -- sample
        covariance matrix of observation vectors
      * scoreEquations -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * solverMLE -- Maximum likelihood estimate of a
        loopless mixed graph
  * Methods
      * "checkPD(List)" -- see checkPD, -- returns positive
        definite matrices from a list of symmetric  matrices
      * "checkPD(Matrix)" -- see checkPD, -- returns positive
        definite matrices from a list of symmetric  matrices
      * "checkPSD(List)" -- see checkPSD, -- returns positive
        semidefinite matrices from a list of symmetric matrices
      * "checkPSD(Matrix)" -- see checkPSD, -- returns positive
        semidefinite matrices from a list of symmetric matrices
      * "jacobianMatrixOfRationalFunction(RingElement)" -- see
        jacobianMatrixOfRationalFunction, --
        Jacobian matrix of a rational function
      * "MLdegree(Ring)" -- see MLdegree, -- ML-degree of a
        graphical model
      * "sampleCovarianceMatrix(List)" -- see sampleCovarianceMatrix,
        -- sample covariance matrix of observation
        vectors
      * "sampleCovarianceMatrix(Matrix)" -- see sampleCovarianceMatrix,
        -- sample covariance matrix of observation
        vectors
      * "scoreEquations(Bigraph,Digraph,Graph,List)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(Bigraph,Digraph,Graph,Matrix)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(Bigraph,Digraph,List)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Bigraph,Digraph,Matrix)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Bigraph,Graph,Digraph,List)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(Bigraph,Graph,Digraph,Matrix)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(Bigraph,Graph,List)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Bigraph,Graph,Matrix)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Bigraph,List)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Bigraph,Matrix)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Digraph,Bigraph,Graph,List)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(Digraph,Bigraph,Graph,Matrix)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(Digraph,Bigraph,List)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Digraph,Bigraph,Matrix)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Digraph,Graph,Bigraph,List)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(Digraph,Graph,Bigraph,Matrix)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(Digraph,Graph,List)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Digraph,Graph,Matrix)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Digraph,List)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Digraph,Matrix)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Graph,Bigraph,Digraph,List)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(Graph,Bigraph,Digraph,Matrix)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(Graph,Bigraph,List)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Graph,Bigraph,Matrix)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Graph,Digraph,Bigraph,List)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(Graph,Digraph,Bigraph,Matrix)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(Graph,Digraph,List)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Graph,Digraph,Matrix)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Graph,List)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Graph,Matrix)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(List,Bigraph)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(List,Bigraph,Digraph)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(List,Bigraph,Digraph,Graph)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(List,Bigraph,Graph)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(List,Bigraph,Graph,Digraph)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(List,Digraph)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(List,Digraph,Bigraph)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(List,Digraph,Bigraph,Graph)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(List,Digraph,Graph)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(List,Digraph,Graph,Bigraph)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(List,Graph)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(List,Graph,Bigraph)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(List,Graph,Bigraph,Digraph)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(List,Graph,Digraph)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(List,Graph,Digraph,Bigraph)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(List,MixedGraph)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(List,Ring)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Matrix,Bigraph)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Matrix,Bigraph,Digraph)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Matrix,Bigraph,Digraph,Graph)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(Matrix,Bigraph,Graph)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Matrix,Bigraph,Graph,Digraph)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(Matrix,Digraph)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Matrix,Digraph,Bigraph)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Matrix,Digraph,Bigraph,Graph)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(Matrix,Digraph,Graph)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Matrix,Digraph,Graph,Bigraph)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(Matrix,Graph)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Matrix,Graph,Bigraph)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Matrix,Graph,Bigraph,Digraph)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(Matrix,Graph,Digraph)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Matrix,Graph,Digraph,Bigraph)" -- see
        scoreEquations, -- score equations of the
        log-likelihood function of a Gaussian graphical model
      * "scoreEquations(Matrix,MixedGraph)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Matrix,Ring)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(MixedGraph,List)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(MixedGraph,Matrix)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Ring,List)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "scoreEquations(Ring,Matrix)" -- see scoreEquations,
        -- score equations of the log-likelihood function of a
        Gaussian graphical model
      * "solverMLE(Bigraph,Digraph,Graph,List)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Bigraph,Digraph,Graph,Matrix)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Bigraph,Digraph,List)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Bigraph,Digraph,Matrix)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Bigraph,Graph,Digraph,List)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Bigraph,Graph,Digraph,Matrix)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Bigraph,Graph,List)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Bigraph,Graph,Matrix)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Bigraph,List)" -- see solverMLE, -- Maximum
        likelihood estimate of a loopless mixed graph
      * "solverMLE(Bigraph,Matrix)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Digraph,Bigraph,Graph,List)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Digraph,Bigraph,Graph,Matrix)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Digraph,Bigraph,List)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Digraph,Bigraph,Matrix)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Digraph,Graph,Bigraph,List)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Digraph,Graph,Bigraph,Matrix)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Digraph,Graph,List)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Digraph,Graph,Matrix)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Digraph,List)" -- see solverMLE, -- Maximum
        likelihood estimate of a loopless mixed graph
      * "solverMLE(Digraph,Matrix)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Graph,Bigraph,Digraph,List)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Graph,Bigraph,Digraph,Matrix)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Graph,Bigraph,List)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Graph,Bigraph,Matrix)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Graph,Digraph,Bigraph,List)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Graph,Digraph,Bigraph,Matrix)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Graph,Digraph,List)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Graph,Digraph,Matrix)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Graph,List)" -- see solverMLE, -- Maximum
        likelihood estimate of a loopless mixed graph
      * "solverMLE(Graph,Matrix)" -- see solverMLE, -- Maximum
        likelihood estimate of a loopless mixed graph
      * "solverMLE(List,Bigraph)" -- see solverMLE, -- Maximum
        likelihood estimate of a loopless mixed graph
      * "solverMLE(List,Bigraph,Digraph)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(List,Bigraph,Digraph,Graph)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(List,Bigraph,Graph)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(List,Bigraph,Graph,Digraph)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(List,Digraph)" -- see solverMLE, -- Maximum
        likelihood estimate of a loopless mixed graph
      * "solverMLE(List,Digraph,Bigraph)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(List,Digraph,Bigraph,Graph)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(List,Digraph,Graph)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(List,Digraph,Graph,Bigraph)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(List,Graph)" -- see solverMLE, -- Maximum
        likelihood estimate of a loopless mixed graph
      * "solverMLE(List,Graph,Bigraph)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(List,Graph,Bigraph,Digraph)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(List,Graph,Digraph)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(List,Graph,Digraph,Bigraph)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(List,MixedGraph)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(List,Ring)" -- see solverMLE, -- Maximum
        likelihood estimate of a loopless mixed graph
      * "solverMLE(Matrix,Bigraph)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Matrix,Bigraph,Digraph)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Matrix,Bigraph,Digraph,Graph)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Matrix,Bigraph,Graph)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Matrix,Bigraph,Graph,Digraph)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Matrix,Digraph)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Matrix,Digraph,Bigraph)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Matrix,Digraph,Bigraph,Graph)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Matrix,Digraph,Graph)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Matrix,Digraph,Graph,Bigraph)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Matrix,Graph)" -- see solverMLE, -- Maximum
        likelihood estimate of a loopless mixed graph
      * "solverMLE(Matrix,Graph,Bigraph)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Matrix,Graph,Bigraph,Digraph)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Matrix,Graph,Digraph)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Matrix,Graph,Digraph,Bigraph)" -- see solverMLE,
        -- Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Matrix,MixedGraph)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Matrix,Ring)" -- see solverMLE, -- Maximum
        likelihood estimate of a loopless mixed graph
      * "solverMLE(MixedGraph,List)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(MixedGraph,Matrix)" -- see solverMLE, --
        Maximum likelihood estimate of a loopless mixed graph
      * "solverMLE(Ring,List)" -- see solverMLE, -- Maximum
        likelihood estimate of a loopless mixed graph
      * "solverMLE(Ring,Matrix)" -- see solverMLE, -- Maximum
        likelihood estimate of a loopless mixed graph
  * Symbols
      * ConcentrationMatrix -- optional input to
        output MLE for concentration matrix instead of MLE for covariance
        matrix
      * CovarianceMatrix -- optional input to output
        covariance matrix
      * OptionsEigenSolver -- optional input to use
        options of "zeroDimSolve" in "EigenSolver"
      * OptionsNAG4M2 -- optional parameter to set the
        parameters of solveSystem in NumericalAlgebraicGeometry
      * RealPrecision -- optional input to choose the
        number of decimals used to round to QQ when inputing data in RR
      * SampleData -- optional input to allow to input the
        sample covariance matrix instead of sample data
      * Saturate -- optional input whether to saturate
      * SaturateOptions -- optional input to use
        options "saturate"
      * Solver -- optional input to choose numerical solver
      * ZeroTolerance -- optional input to set the
        largest absolute value that should be treated as zero

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

The object GraphicalModelsMLE, is a package (Macaulay2Doc).

checkPD -- returns positive definite matrices from a list of symmetric  matrices
********************************************************************************

Synopsis
========

  * Usage:
        checkPD(L)
  * Inputs:
      * L, a list (Macaulay2Doc), of symmetric matrices, or a
        single symmetric Matrix (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * ZeroTolerance,
        => ..., default value 1e-10, optional input to set the largest absolute
        value that should be treated as zero
  * Outputs:
      * a list (Macaulay2Doc), of positive definite matrices

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

This function takes a list of symmetric matrices (or a single symmetric matrix)
and returns the sublist of its positive definite matrices. If there are no
positive definite matrices in the list, it returns an empty list.

Note that the function does not check whether the matrices in the original list
are symmetric.

If a matrix contains an imaginary part below the tolerance level, then only the
real part is reported in the output. (See
checkPD(...,ZeroTolerance=>...))

+-----------------------------------------------------------------------------+
|i1 : L={matrix{{1,0},{0,1}},matrix{{-2,0},{0,1}},matrix{{sqrt(-1),0},{0,sqrt |
|                                                                             |
|o1 = {| 1 0 |, | -2 0 |, | ii 0  |}                                          |
|      | 0 1 |  | 0  1 |  | 0  ii |                                           |
|                                                                             |
|o1 : List                                                                    |
|-----------------------------------------------------------------------------|
|(-1)}}}                                                                      |
+-----------------------------------------------------------------------------+
|i2 : checkPD(L)                                                              |
|                                                                             |
|o2 = {| 1 0 |}                                                               |
|      | 0 1 |                                                                |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

Ways to use checkPD:
====================

  * "checkPD(List)"
  * "checkPD(Matrix)"

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

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

checkPD(...,ZeroTolerance=>...) -- optional input to set the largest absolute value that should be treated as zero
******************************************************************************************************************

Synopsis
========

  * Usage:
        checkPD(L,ZeroTolerance=>n)
  * Inputs:
      * n, a real number (Macaulay2Doc), default is 1e-10

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

A matrix is assumed to be positive definite if for all eigenvalues e:

-  realPart (Macaulay2Doc), e > ZeroTolerance

-  abs (Macaulay2Doc), imaginaryPart (Macaulay2Doc),
e <= ZeroTolerance

If a matrix contains an imaginary part below the tolerance level, then only the
real part is reported in the output.

+-----------------------------------------------------------------------------+
|i1 : L={matrix{{10^(-9)+10^(-10)*sqrt(-1),0},{0,10^(-9)+10^(-10)*sqrt (-1)}},|
|         matrix{{10^(-10)+10^(-10)*sqrt(-1),0},{0,10^(-10)+10^(-10)*sqrt (-1)|
|         matrix{{1+10^(-10)*sqrt(-1),0},{0,1+10^(-10)*sqrt (-1)}},           |
|         matrix{{1-10^(-9)*sqrt(-1),0},{0,1+10^(-9)*sqrt (-1)}}              |
|         }                                                                   |
|                                                                             |
|o1 = {| 1e-9+1e-10ii 0            |, | 1e-10+1e-10ii 0             |, |      |
|      | 0            1e-9+1e-10ii |  | 0             1e-10+1e-10ii |  |      |
|     ------------------------------------------------------------------------|
|     1+1e-10ii 0         |, | 1-1e-9ii 0        |}                           |
|     0         1+1e-10ii |  | 0        1+1e-9ii |                            |
|                                                                             |
|o1 : List                                                                    |
|-----------------------------------------------------------------------------|
|}},                                                                          |
+-----------------------------------------------------------------------------+
|i2 : checkPD L                                                               |
|                                                                             |
|o2 = {| 1e-9 0    |, | 1 0 |}                                                |
|      | 0    1e-9 |  | 0 1 |                                                 |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

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

  * Default value: 1e-10
  * Function: checkPD, -- returns positive definite matrices
    from a list of symmetric  matrices
  * Option key: ZeroTolerance, -- optional input to set
    the largest absolute value that should be treated as zero

See also
========

  * checkPSD(...,ZeroTolerance=>...)
    -- optional input to
    set the largest absolute value that should be treated as zero
  * solverMLE -- Maximum likelihood estimate of a loopless
    mixed graph

Functions with optional argument named ZeroTolerance:
=====================================================

  * checkPD(...,ZeroTolerance=>...)
    -- optional input to set
    the largest absolute value that should be treated as zero
  * checkPSD(...,ZeroTolerance=>...)
    -- optional input to
    set the largest absolute value that should be treated as zero
  * solverMLE(...,ZeroTolerance=>...)
    -- optional input to
    set the largest absolute value that should be treated as zero

checkPSD -- returns positive semidefinite matrices from a list of symmetric matrices
************************************************************************************

Synopsis
========

  * Usage:
        checkPSD(L)
  * Inputs:
      * L, a list (Macaulay2Doc), of symmetric matrices, or a
        single symmetric Matrix (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * ZeroTolerance,
        => ..., default value 1e-10, optional input to set the largest
        absolute value that should be treated as zero
  * Outputs:
      * a list (Macaulay2Doc), of positive semidefinite matrices

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

This function takes a list of symmetric matrices (or a single symmetric matrix)
and returns the sublist of its positive semidefinite matrices.

Note that the function does not check whether the matrices in the original list
are symmetric.

If there are no positive semidefinite matrices in the list, it returns an empty
list.

+-----------------------------------------------------------------------------+
|i1 : L={matrix{{1,0},{0,1}},matrix{{-2,0},{0,1}},matrix{{sqrt(-1),0},{0,sqrt |
|                                                                             |
|o1 = {| 1 0 |, | -2 0 |, | ii 0  |, 0}                                       |
|      | 0 1 |  | 0  1 |  | 0  ii |                                           |
|                                                                             |
|o1 : List                                                                    |
|-----------------------------------------------------------------------------|
|(-1)}},matrix{{0,0},{0,0}}}                                                  |
+-----------------------------------------------------------------------------+
|i2 : checkPSD(L)                                                             |
|                                                                             |
|o2 = {| 1 0 |, 0}                                                            |
|      | 0 1 |                                                                |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

Ways to use checkPSD:
=====================

  * "checkPSD(List)"
  * "checkPSD(Matrix)"

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

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

checkPSD(...,ZeroTolerance=>...) -- optional input to set the largest absolute value that should be treated as zero
*******************************************************************************************************************

Synopsis
========

  * Usage:
        checkPD(L,ZeroTolerance=>n)
  * Inputs:
      * n, a real number (Macaulay2Doc), default is 1e-10

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

A matrix is assumed to be positive semidefinite if for all eigenvalues e:

-  realPart (Macaulay2Doc), e >= -ZeroTolerance

-  abs (Macaulay2Doc), imaginaryPart (Macaulay2Doc),
e <= ZeroTolerance

If a matrix contains an imaginary part below the tolerance level, then only the
real part is reported in the output.

+-----------------------------------------------------------------------------+
|i1 : L={matrix{{10^(-9)+10^(-10)*sqrt(-1),0},{0,10^(-9)+10^(-10)*sqrt (-1)}},|
|         matrix{{10^(-10)+10^(-10)*sqrt(-1),0},{0,10^(-10)+10^(-10)*sqrt (-1)|
|         matrix{{1+10^(-10)*sqrt(-1),0},{0,1+10^(-10)*sqrt (-1)}},           |
|         matrix{{1-10^(-9)*sqrt(-1),0},{0,1+10^(-9)*sqrt (-1)}}              |
|         }                                                                   |
|                                                                             |
|o1 = {| 1e-9+1e-10ii 0            |, | 1e-10+1e-10ii 0             |, |      |
|      | 0            1e-9+1e-10ii |  | 0             1e-10+1e-10ii |  |      |
|     ------------------------------------------------------------------------|
|     1+1e-10ii 0         |, | 1-1e-9ii 0        |}                           |
|     0         1+1e-10ii |  | 0        1+1e-9ii |                            |
|                                                                             |
|o1 : List                                                                    |
|-----------------------------------------------------------------------------|
|}},                                                                          |
+-----------------------------------------------------------------------------+
|i2 : checkPD L                                                               |
|                                                                             |
|o2 = {| 1e-9 0    |, | 1 0 |}                                                |
|      | 0    1e-9 |  | 0 1 |                                                 |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

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

  * Default value: 1e-10
  * Function: checkPSD, -- returns positive semidefinite
    matrices from a list of symmetric matrices
  * Option key: ZeroTolerance, -- optional input to set
    the largest absolute value that should be treated as zero

See also
========

  * checkPD(...,ZeroTolerance=>...)
    -- optional input to set
    the largest absolute value that should be treated as zero

Functions with optional argument named ZeroTolerance:
=====================================================

  * checkPD(...,ZeroTolerance=>...)
    -- optional input to set
    the largest absolute value that should be treated as zero
  * checkPSD(...,ZeroTolerance=>...)
    -- optional input to
    set the largest absolute value that should be treated as zero
  * solverMLE(...,ZeroTolerance=>...)
    -- optional input to
    set the largest absolute value that should be treated as zero

ConcentrationMatrix -- optional input to output MLE for concentration matrix instead of MLE for covariance matrix
*****************************************************************************************************************

See also
========

  * solverMLE -- Maximum likelihood estimate of a loopless
    mixed graph

Functions with optional argument named ConcentrationMatrix:
===========================================================

  * solverMLE(...,ConcentrationMatrix=>...)
    -- output MLE
    for concentration matrix instead of MLE for covariance matrix

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

The object ConcentrationMatrix, is a symbol (Macaulay2Doc).

CovarianceMatrix -- optional input to output covariance matrix
**************************************************************

See also
========

  * scoreEquations -- score equations of the
    log-likelihood function of a Gaussian graphical model

Functions with optional argument named CovarianceMatrix:
========================================================

  * scoreEquations(...,CovarianceMatrix=>...)
    -- output
    covariance matrix

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

The object CovarianceMatrix, is a symbol (Macaulay2Doc).

jacobianMatrixOfRationalFunction -- Jacobian matrix of a rational function
**************************************************************************

Synopsis
========

  * Usage:
        jacobianMatrixOfRationalFunction(F)
  * Inputs:
      * F, a ring element (Macaulay2Doc), in frac (Macaulay2Doc),
  * Outputs:
      * a matrix (Macaulay2Doc), the Jacobian matrix of a
        rational function

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

This function computes the Jacobian matrix of a rational function. The input is
an element in a fraction field.

+----------------------------------------+
|i1 : R=QQ[x,y];                         |
+----------------------------------------+
|i2 : FR=frac R;                         |
+----------------------------------------+
|i3 : F=1/(x^2+y^2);                     |
+----------------------------------------+
|i4 : jacobianMatrixOfRationalFunction(F)|
|                                        |
|o4 = {1} | (-2x)/(x4+2x2y2+y4) |        |
|     {1} | (-2y)/(x4+2x2y2+y4) |        |
|                                        |
|              2       1                 |
|o4 : Matrix FR  <-- FR                  |
+----------------------------------------+
+-----------------------------------------------------------------------------+
|i5 : R=QQ[t_1,t_2,t_3];                                                      |
+-----------------------------------------------------------------------------+
|i6 : FR=frac R;                                                              |
+-----------------------------------------------------------------------------+
|i7 : jacobianMatrixOfRationalFunction( (t_1^2*t_2)/(t_1+t_2^2+t_3^3) )       |
|                                                                             |
|o7 = {-2} | (2t_1t_2t_3^3+2t_1t_2^3+t_1^2t_2)/(t_3^6+2t_2^2t_3^3+t_2^4+2t_1t_|
|     {-2} | (t_1^2t_3^3-t_1^2t_2^2+t_1^3)/(t_3^6+2t_2^2t_3^3+t_2^4+2t_1t_3^3+|
|     {-2} | (-3t_1^2t_2t_3^2)/(t_3^6+2t_2^2t_3^3+t_2^4+2t_1t_3^3+2t_1t_2^2+t_|
|     ------------------------------------------------------------------------|
|     3^3+2t_1t_2^2+t_1^2) |                                                  |
|     2t_1t_2^2+t_1^2)     |                                                  |
|     1^2)                 |                                                  |
|                                                                             |
|              3       1                                                      |
|o7 : Matrix FR  <-- FR                                                       |
+-----------------------------------------------------------------------------+

Ways to use jacobianMatrixOfRationalFunction:
=============================================

  * "jacobianMatrixOfRationalFunction(RingElement)"

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

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

MLdegree -- ML-degree of a graphical model
******************************************

Synopsis
========

  * Usage:
        MLdegree(R)
  * Inputs:
      * R, a ring (Macaulay2Doc), defined as a gaussianRing (GraphicalModels),
        of Graph (Graphs), or
        Digraph (Graphs), or Bigraph (StatGraphs), or
        MixedGraph (StatGraphs),
  * Outputs:
      * an integer (Macaulay2Doc), the ML-degree of the model

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

This function computes the ML-degree of a graphical model. It takes as input a
gaussianRing (GraphicalModels), of a Graph (Graphs),
or a Digraph (Graphs), or a Bigraph (StatGraphs),
or a  MixedGraph (StatGraphs). It
computes the degree of the score equation ideal given by scoreEquations,
with a random sample data matrix.

We compute the ML-degree of the 4-cycle:

+-------------------------------------+
|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 : MLdegree(gaussianRing G)        |
|                                     |
|o2 = 5                               |
+-------------------------------------+

Ways to use MLdegree:
=====================

  * "MLdegree(Ring)"

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

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

OptionsEigenSolver -- optional input to use options of "zeroDimSolve" in "EigenSolver"
**************************************************************************************

See also
========

  * solverMLE -- Maximum likelihood estimate of a loopless
    mixed graph
  * EigenSolver -- polynomial system solver via
    eigen-computations
  * zeroDimSolve (EigenSolver) -- zero-dimensional
    polynomial system solver

Functions with optional argument named OptionsEigenSolver:
==========================================================

  * solverMLE(...,OptionsEigenSolver=>...)
    -- use options of
    "zeroDimSolve" in "EigenSolver"

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

The object OptionsEigenSolver, is a symbol (Macaulay2Doc).

OptionsNAG4M2 -- optional parameter to set the parameters of solveSystem in NumericalAlgebraicGeometry
******************************************************************************************************

See also
========

  * solverMLE -- Maximum likelihood estimate of a loopless
    mixed graph
  * NumericalAlgebraicGeometry, --
    Numerical Algebraic Geometry
  * solveSystem (NumericalAlgebraicGeometry), --
    solve a system of polynomial equations

Functions with optional argument named OptionsNAG4M2:
=====================================================

  * solverMLE(...,OptionsNAG4M2=>...)
    -- use options of
    "solveSystem" in "NumericalAlgebraicGeometry"

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

The object OptionsNAG4M2, is a symbol (Macaulay2Doc).

RealPrecision -- optional input to choose the number of decimals used to round to QQ when inputing data in RR
*************************************************************************************************************

See also
========

  * scoreEquations -- score equations of the
    log-likelihood function of a Gaussian graphical model
  * solverMLE -- Maximum likelihood estimate of a loopless
    mixed graph

Functions with optional argument named RealPrecision:
=====================================================

  * scoreEquations(...,RealPrecision=>...)
    -- the number of
    bits of precision to use in the computation
  * solverMLE(...,RealPrecision=>...)
    -- the number of bits
    of precision to use in the computation

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

The object RealPrecision, is a symbol (Macaulay2Doc).

sampleCovarianceMatrix -- sample covariance matrix of observation vectors
*************************************************************************

Synopsis
========

  * Usage:
        sampleCovarianceMatrix U
  * Inputs:
      * U, a matrix (Macaulay2Doc), or List (Macaulay2Doc),
        of sample data
  * Outputs:
      * a matrix (Macaulay2Doc), sample covariance matrix of the
        sample data

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

The sample covariance matrix is $S = \frac{1}{n} \sum_{i=1}^{n}
(X^{(i)}-\bar{X}) (X^{(i)}-\bar{X})^T$. Note that for normally distributed
random variables, $S$ is the maximum likelihood estimator (MLE) for the
covariance matrix. This is different from the unbiased estimator, which uses a
denominator of $n-1$ instead of $n$.

Sample data is input as a matrix or a list. The rows of the matrix or the
elements of the list are observation vectors.

+------------------------------------------------------------------+
|i1 : L= {{1,2,1,-1},{2,1,3,0},{-1, 0, 1, 1},{-5, 3, 4, -6}};      |
+------------------------------------------------------------------+
|i2 : sampleCovarianceMatrix(L)                                    |
|                                                                  |
|o2 = | 115/16 -13/8 -29/16 47/8  |                                |
|     | -13/8  5/4   7/8    -11/4 |                                |
|     | -29/16 7/8   27/16  -21/8 |                                |
|     | 47/8   -11/4 -21/8  29/4  |                                |
|                                                                  |
|              4       4                                           |
|o2 : Matrix QQ  <-- QQ                                            |
+------------------------------------------------------------------+
|i3 : U= matrix{{1,2,1,-1},{2,1,3,0},{-1, 0, 1, 1},{-5, 3, 4, -6}};|
|                                                                  |
|              4       4                                           |
|o3 : Matrix ZZ  <-- ZZ                                            |
+------------------------------------------------------------------+
|i4 : sampleCovarianceMatrix(U)                                    |
|                                                                  |
|o4 = | 115/16 -13/8 -29/16 47/8  |                                |
|     | -13/8  5/4   7/8    -11/4 |                                |
|     | -29/16 7/8   27/16  -21/8 |                                |
|     | 47/8   -11/4 -21/8  29/4  |                                |
|                                                                  |
|              4       4                                           |
|o4 : Matrix QQ  <-- QQ                                            |
+------------------------------------------------------------------+

Ways to use sampleCovarianceMatrix:
===================================

  * "sampleCovarianceMatrix(List)"
  * "sampleCovarianceMatrix(Matrix)"

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

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

SampleData -- optional input to allow to input the sample covariance matrix instead of sample data
**************************************************************************************************

See also
========

  * scoreEquations -- score equations of the
    log-likelihood function of a Gaussian graphical model
  * solverMLE -- Maximum likelihood estimate of a loopless
    mixed graph

Functions with optional argument named SampleData:
==================================================

  * scoreEquations(...,SampleData=>...)
    -- input sample
    covariance matrix instead of sample data
  * solverMLE(...,SampleData=>...)
    -- input sample
    covariance matrix instead of sample data

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

The object SampleData, is a symbol (Macaulay2Doc).

Saturate -- optional input whether to saturate
**********************************************

See also
========

  * scoreEquations -- score equations of the
    log-likelihood function of a Gaussian graphical model
  * solverMLE -- Maximum likelihood estimate of a loopless
    mixed graph

Functions with optional argument named Saturate:
================================================

  * scoreEquations(...,Saturate=>...)
    -- whether to saturate
  * solverMLE(...,Saturate=>...)
    -- whether to saturate

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

The object Saturate, is a symbol (Macaulay2Doc).

SaturateOptions -- optional input to use options "saturate"
***********************************************************

See also
========

  * scoreEquations -- score equations of the
    log-likelihood function of a Gaussian graphical model
  * solverMLE -- Maximum likelihood estimate of a loopless
    mixed graph
  * Saturate -- optional input whether to saturate
  * saturate (missing documentation)

Functions with optional argument named SaturateOptions:
=======================================================

  * scoreEquations(...,SaturateOptions=>...)
    -- use options
    from "saturate"
  * solverMLE(...,SaturateOptions=>...)
    -- use options from
    "saturate"

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

The object SaturateOptions, is a symbol (Macaulay2Doc).

scoreEquations -- score equations of the log-likelihood function of a Gaussian graphical model
**********************************************************************************************

Synopsis
========

  * Usage:
        scoreEquations(R,U)
  * Inputs:
      * R, a ring (Macaulay2Doc), defined as a gaussianRing (GraphicalModels),
        of Graph (Graphs), or
        Digraph (Graphs), or Bigraph (StatGraphs), or
        MixedGraph (StatGraphs),
      * U, a matrix (Macaulay2Doc), or List (Macaulay2Doc),
        of sample data. Alternatively, the input can be the
        sample covariance Matrix (Macaulay2Doc), by setting the
        optional input SampleData, to false
  * Optional inputs (Macaulay2Doc),:
      * CovarianceMatrix,
        => ...,
        default value false, output covariance matrix
      * RealPrecision,
        => ..., default value 53, the number of bits of precision to
        use in the computation
      * SampleData,
        => ..., default value true, input sample covariance matrix instead of
        sample data
      * Saturate, =>
        ..., default value true, whether to saturate
      * SaturateOptions,
        => ...,
        default value new OptionTable from {Strategy => null, BasisElementLimit
        => infinity, DegreeLimit => {}, MinimalGenerators => true, PairLimit =>
        infinity}, use options from "saturate"
  * Outputs:
      * a sequence (Macaulay2Doc), consisting either of (Ideal)
        or (Ideal,Matrix) where the ideal is generated by the score equations
        of the log-likelihood function of the Gaussian model and the matrix is
        the symbolic covariance matrix of the model

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

This function computes the score equations that arise from taking partial
derivatives of the log-likelihood function of the concentration matrix (the
inverse of the covariance matrix) of a Gaussian graphical statistical model and
returns the ideal generated by such equations.

The input of this function is a gaussianRing (GraphicalModels),
and statistical data. The latter can be given as
a matrix or a list of observations. The rows of the matrix or the elements of
the list are observation vectors given as lists. It is possible to input the
sample covariance matrix directly by using the optional input SampleData.

+-----------------------------------------------------------------------------+
|i1 : G = mixedGraph(digraph {{1,2},{1,3},{2,3},{3,4}},bigraph{{3,4}});       |
+-----------------------------------------------------------------------------+
|i2 : R = gaussianRing(G);                                                    |
+-----------------------------------------------------------------------------+
|i3 : U = matrix{{6, 10, 1/3, 1}, {3/5, 3, 1/2, 1}, {4/5, 3/2, 9/8, 3/10},    |
|                                                                             |
|              4       4                                                      |
|o3 : Matrix QQ  <-- QQ                                                       |
|-----------------------------------------------------------------------------|
|{10/7, 2/3,1, 8/3}};                                                         |
+-----------------------------------------------------------------------------+
|i4 : JU=scoreEquations(R,U)                                                  |
|                                                                             |
|o4 = ideal (192199680p    - 99333449, 267221621760p    - 849243924773,       |
|                      3,4                          4,4                       |
|     ------------------------------------------------------------------------|
|     1353974896462794079472640p    - 142165262245288892244817, 6898968p    - |
|                               3,3                                     2,2   |
|     ------------------------------------------------------------------------|
|     11533057, 19600p    - 95819, 20855l    + 90447,                         |
|                     1,1                3,4                                  |
|     ------------------------------------------------------------------------|
|     146915678869660815915l    - 4228634793402814499,                        |
|                           2,3                                               |
|     ------------------------------------------------------------------------|
|     58766271547864326366l    + 4167005135395196717, 574914l    - 896035)    |
|                          1,3                               1,2              |
|                                                                             |
|o4 : Ideal of QQ[l   ..l   , l   , l   , p   , p   , p   , p   , p   ]       |
|                  1,2   1,3   2,3   3,4   1,1   2,2   3,3   4,4   3,4        |
+-----------------------------------------------------------------------------+
|i5 : V = sampleCovarianceMatrix U                                            |
|                                                                             |
|o5 = | 95819/19600 25601/3360 -2129/4480 -1313/16800 |                       |
|     | 25601/3360  867/64     -2321/2304 -173/192    |                       |
|     | -2129/4480  -2321/2304 337/3072   473/11520   |                       |
|     | -1313/16800 -173/192   473/11520  3641/4800   |                       |
|                                                                             |
|              4       4                                                      |
|o5 : Matrix QQ  <-- QQ                                                       |
+-----------------------------------------------------------------------------+
|i6 : JV=scoreEquations(R,V,SampleData=>false)                                |
|                                                                             |
|o6 = ideal (192199680p    - 99333449, 267221621760p    - 849243924773,       |
|                      3,4                          4,4                       |
|     ------------------------------------------------------------------------|
|     1353974896462794079472640p    - 142165262245288892244817, 6898968p    - |
|                               3,3                                     2,2   |
|     ------------------------------------------------------------------------|
|     11533057, 19600p    - 95819, 20855l    + 90447,                         |
|                     1,1                3,4                                  |
|     ------------------------------------------------------------------------|
|     146915678869660815915l    - 4228634793402814499,                        |
|                           2,3                                               |
|     ------------------------------------------------------------------------|
|     58766271547864326366l    + 4167005135395196717, 574914l    - 896035)    |
|                          1,3                               1,2              |
|                                                                             |
|o6 : Ideal of QQ[l   ..l   , l   , l   , p   , p   , p   , p   , p   ]       |
|                  1,2   1,3   2,3   3,4   1,1   2,2   3,3   4,4   3,4        |
+-----------------------------------------------------------------------------+

See SaturateOptions, allows to use all functionalities of
saturate (Saturation). See Saturate, determines
whether to saturate. Note that the latter will not provide the score equations
of the model.

+-----------------------------------------------------------------------------+
|i7 : G = mixedGraph(digraph {{1,2},{1,3},{2,3},{3,4}},bigraph{{3,4}});       |
+-----------------------------------------------------------------------------+
|i8 : R = gaussianRing(G);                                                    |
+-----------------------------------------------------------------------------+
|i9 : U = matrix{{6, 10, 1/3, 1}, {3/5, 3, 1/2, 1}, {4/5, 3/2, 9/8, 3/10},    |
|                                                                             |
|              4       4                                                      |
|o9 : Matrix QQ  <-- QQ                                                       |
|-----------------------------------------------------------------------------|
|{10/7, 2/3,1, 8/3}};                                                         |
+-----------------------------------------------------------------------------+
|i10 : J=scoreEquations(R,U,SaturateOptions => {Strategy => Eliminate})       |
|                                                                             |
|o10 = ideal (192199680p    - 99333449, 267221621760p    - 849243924773,      |
|                       3,4                          4,4                      |
|      -----------------------------------------------------------------------|
|      1353974896462794079472640p    - 142165262245288892244817, 6898968p    -|
|                                3,3                                     2,2  |
|      -----------------------------------------------------------------------|
|      11533057, 19600p    - 95819, 20855l    + 90447,                        |
|                      1,1                3,4                                 |
|      -----------------------------------------------------------------------|
|      146915678869660815915l    - 4228634793402814499,                       |
|                            2,3                                              |
|      -----------------------------------------------------------------------|
|      58766271547864326366l    + 4167005135395196717, 574914l    - 896035)   |
|                           1,3                               1,2             |
|                                                                             |
|o10 : Ideal of QQ[l   ..l   , l   , l   , p   , p   , p   , p   , p   ]      |
|                   1,2   1,3   2,3   3,4   1,1   2,2   3,3   4,4   3,4       |
+-----------------------------------------------------------------------------+
|i11 : JnoSat=scoreEquations(R,U,Saturate=>false)                             |
|                                                                             |
|                                                                             |
|o11 = ideal (- 574914l    + 896035, - 2299656l   p    - 3584140l   p    -    |
|                      1,2                     1,3 4,4           2,3 4,4      |
|      -----------------------------------------------------------------------|
|                                                                             |
|      223545l   p    - 223545p    + 36764p   , - 614424l   p    -            |
|             3,4 3,4          4,4         3,4           1,3 4,4              |
|      -----------------------------------------------------------------------|
|                                                                             |
|      1092420l   p    - 81235l   p    - 81235p    + 72660p   , -             |
|              2,3 4,4         3,4 3,4         4,4         3,4                |
|      -----------------------------------------------------------------------|
|                                                                             |
|      35385l   p    - 153288l   p    - 324940l   p    + 13244p    -          |
|            3,4 3,3          1,3 3,4          2,3 3,4         3,3            |
|      -----------------------------------------------------------------------|
|                                              2                              |
|      35385p   , - 19600p    + 95819, 1149828l    - 3584140l    - 235200p    |
|            3,4          1,1                  1,2           1,2          2,2 |
|      -----------------------------------------------------------------------|
|                          2   2                       2               2   2  |
|      + 3186225, 55191744l   p    + 172038720l   l   p    + 152938800l   p   |
|                          1,3 4,4             1,3 2,3 4,4             2,3 4,4|
|      -----------------------------------------------------------------------|
|                                                                      2   2  |
|      + 10730160l   l   p   p    + 22745800l   l   p   p    + 1238475l   p   |
|                 1,3 3,4 4,4 3,4            2,3 3,4 4,4 3,4           3,4 3,4|
|      -----------------------------------------------------------------------|
|                     2                  2                  2                 |
|      + 10730160l   p    + 22745800l   p    - 11289600p   p    -             |
|                 1,3 4,4            2,3 4,4            3,3 4,4               |
|      -----------------------------------------------------------------------|
|                                                                             |
|      1764672l   p   p    - 20344800l   p   p    + 2476950l   p   p    -     |
|              1,3 4,4 3,4            2,3 4,4 3,4           3,4 4,4 3,4       |
|      -----------------------------------------------------------------------|
|                 2                  2             2                          |
|      927080l   p    + 11289600p   p    + 1238475p    - 927080p   p    +     |
|             3,4 3,4            4,4 3,4           4,4          4,4 3,4       |
|      -----------------------------------------------------------------------|
|              2            2   2                                             |
|      8563632p   , 1238475l   p    + 10730160l   l   p   p    +              |
|              3,4          3,4 3,3            1,3 3,4 3,3 3,4                |
|      -----------------------------------------------------------------------|
|                                          2   2                       2      |
|      22745800l   l   p   p    + 55191744l   p    + 172038720l   l   p    +  |
|               2,3 3,4 3,3 3,4            1,3 3,4             1,3 2,3 3,4    |
|      -----------------------------------------------------------------------|
|                2   2                2              2                        |
|      152938800l   p    - 927080l   p    - 11289600p   p    -                |
|                2,3 3,4          3,4 3,3            3,3 4,4                  |
|      -----------------------------------------------------------------------|
|                                                                             |
|      1764672l   p   p    - 20344800l   p   p    + 2476950l   p   p    +     |
|              1,3 3,3 3,4            2,3 3,3 3,4           3,4 3,3 3,4       |
|      -----------------------------------------------------------------------|
|                   2                  2                  2             2     |
|      10730160l   p    + 22745800l   p    + 11289600p   p    + 8563632p    - |
|               1,3 3,4            2,3 3,4            3,3 3,4           3,3   |
|      -----------------------------------------------------------------------|
|                               2                                             |
|      927080p   p    + 1238475p   , - 5365080l   l   p   p    -              |
|             3,3 3,4           3,4            1,3 3,4 3,3 4,4                |
|      -----------------------------------------------------------------------|
|                                         2                      2            |
|      11372900l   l   p   p    - 1238475l   p   p    - 55191744l   p   p    -|
|               2,3 3,4 3,3 4,4           3,4 3,3 3,4            1,3 4,4 3,4  |
|      -----------------------------------------------------------------------|
|                                            2                             2  |
|      172038720l   l   p   p    - 152938800l   p   p    - 5365080l   l   p   |
|                1,3 2,3 4,4 3,4             2,3 4,4 3,4           1,3 3,4 3,4|
|      -----------------------------------------------------------------------|
|                         2                                                   |
|      - 11372900l   l   p    + 882336l   p   p    + 10172400l   p   p    -   |
|                 2,3 3,4 3,4          1,3 3,3 4,4            2,3 3,3 4,4     |
|      -----------------------------------------------------------------------|
|                                                                             |
|      1238475l   p   p    + 927080l   p   p    - 10730160l   p   p    -      |
|              3,4 3,3 4,4          3,4 3,3 3,4            1,3 4,4 3,4        |
|      -----------------------------------------------------------------------|
|                                                               2             |
|      22745800l   p   p    + 11289600p   p   p    + 882336l   p    +         |
|               2,3 4,4 3,4            3,3 4,4 3,4          1,3 3,4           |
|      -----------------------------------------------------------------------|
|                   2                 2              3                        |
|      10172400l   p    - 1238475l   p    - 11289600p    + 463540p   p    -   |
|               2,3 3,4           3,4 3,4            3,4          3,3 4,4     |
|      -----------------------------------------------------------------------|
|                                                 2                           |
|      8563632p   p    - 1238475p   p    + 463540p   )                        |
|              3,3 3,4           4,4 3,4          3,4                         |
|                                                                             |
|o11 : Ideal of QQ[l   ..l   , l   , l   , p   , p   , p   , p   , p   ]      |
|                   1,2   1,3   2,3   3,4   1,1   2,2   3,3   4,4   3,4       |
+-----------------------------------------------------------------------------+

The ML-degree of the model is the degree of the score equations ideal. The
ML-degree of the running example is 1:

+-----------------------------------------------------------------------------+
|i12 : G = mixedGraph(digraph {{1,2},{1,3},{2,3},{3,4}},bigraph{{3,4}});      |
+-----------------------------------------------------------------------------+
|i13 : R = gaussianRing(G);                                                   |
+-----------------------------------------------------------------------------+
|i14 : U = matrix{{6, 10, 1/3, 1}, {3/5, 3, 1/2, 1}, {4/5, 3/2, 9/8, 3/10},   |
|                                                                             |
|               4       4                                                     |
|o14 : Matrix QQ  <-- QQ                                                      |
|-----------------------------------------------------------------------------|
|{10/7, 2/3,1, 8/3}};                                                         |
+-----------------------------------------------------------------------------+
|i15 : J = scoreEquations(R,U)                                                |
|                                                                             |
|o15 = ideal (192199680p    - 99333449, 267221621760p    - 849243924773,      |
|                       3,4                          4,4                      |
|      -----------------------------------------------------------------------|
|      1353974896462794079472640p    - 142165262245288892244817, 6898968p    -|
|                                3,3                                     2,2  |
|      -----------------------------------------------------------------------|
|      11533057, 19600p    - 95819, 20855l    + 90447,                        |
|                      1,1                3,4                                 |
|      -----------------------------------------------------------------------|
|      146915678869660815915l    - 4228634793402814499,                       |
|                            2,3                                              |
|      -----------------------------------------------------------------------|
|      58766271547864326366l    + 4167005135395196717, 574914l    - 896035)   |
|                           1,3                               1,2             |
|                                                                             |
|o15 : Ideal of QQ[l   ..l   , l   , l   , p   , p   , p   , p   , p   ]      |
|                   1,2   1,3   2,3   3,4   1,1   2,2   3,3   4,4   3,4       |
+-----------------------------------------------------------------------------+
|i16 : dim J, degree J                                                        |
|                                                                             |
|o16 = (0, 1)                                                                 |
|                                                                             |
|o16 : Sequence                                                               |
+-----------------------------------------------------------------------------+

Ways to use scoreEquations:
===========================

  * "scoreEquations(Bigraph,Digraph,Graph,List)"
  * "scoreEquations(Bigraph,Digraph,Graph,Matrix)"
  * "scoreEquations(Bigraph,Digraph,List)"
  * "scoreEquations(Bigraph,Digraph,Matrix)"
  * "scoreEquations(Bigraph,Graph,Digraph,List)"
  * "scoreEquations(Bigraph,Graph,Digraph,Matrix)"
  * "scoreEquations(Bigraph,Graph,List)"
  * "scoreEquations(Bigraph,Graph,Matrix)"
  * "scoreEquations(Bigraph,List)"
  * "scoreEquations(Bigraph,Matrix)"
  * "scoreEquations(Digraph,Bigraph,Graph,List)"
  * "scoreEquations(Digraph,Bigraph,Graph,Matrix)"
  * "scoreEquations(Digraph,Bigraph,List)"
  * "scoreEquations(Digraph,Bigraph,Matrix)"
  * "scoreEquations(Digraph,Graph,Bigraph,List)"
  * "scoreEquations(Digraph,Graph,Bigraph,Matrix)"
  * "scoreEquations(Digraph,Graph,List)"
  * "scoreEquations(Digraph,Graph,Matrix)"
  * "scoreEquations(Digraph,List)"
  * "scoreEquations(Digraph,Matrix)"
  * "scoreEquations(Graph,Bigraph,Digraph,List)"
  * "scoreEquations(Graph,Bigraph,Digraph,Matrix)"
  * "scoreEquations(Graph,Bigraph,List)"
  * "scoreEquations(Graph,Bigraph,Matrix)"
  * "scoreEquations(Graph,Digraph,Bigraph,List)"
  * "scoreEquations(Graph,Digraph,Bigraph,Matrix)"
  * "scoreEquations(Graph,Digraph,List)"
  * "scoreEquations(Graph,Digraph,Matrix)"
  * "scoreEquations(Graph,List)"
  * "scoreEquations(Graph,Matrix)"
  * "scoreEquations(List,Bigraph)"
  * "scoreEquations(List,Bigraph,Digraph)"
  * "scoreEquations(List,Bigraph,Digraph,Graph)"
  * "scoreEquations(List,Bigraph,Graph)"
  * "scoreEquations(List,Bigraph,Graph,Digraph)"
  * "scoreEquations(List,Digraph)"
  * "scoreEquations(List,Digraph,Bigraph)"
  * "scoreEquations(List,Digraph,Bigraph,Graph)"
  * "scoreEquations(List,Digraph,Graph)"
  * "scoreEquations(List,Digraph,Graph,Bigraph)"
  * "scoreEquations(List,Graph)"
  * "scoreEquations(List,Graph,Bigraph)"
  * "scoreEquations(List,Graph,Bigraph,Digraph)"
  * "scoreEquations(List,Graph,Digraph)"
  * "scoreEquations(List,Graph,Digraph,Bigraph)"
  * "scoreEquations(List,MixedGraph)"
  * "scoreEquations(List,Ring)"
  * "scoreEquations(Matrix,Bigraph)"
  * "scoreEquations(Matrix,Bigraph,Digraph)"
  * "scoreEquations(Matrix,Bigraph,Digraph,Graph)"
  * "scoreEquations(Matrix,Bigraph,Graph)"
  * "scoreEquations(Matrix,Bigraph,Graph,Digraph)"
  * "scoreEquations(Matrix,Digraph)"
  * "scoreEquations(Matrix,Digraph,Bigraph)"
  * "scoreEquations(Matrix,Digraph,Bigraph,Graph)"
  * "scoreEquations(Matrix,Digraph,Graph)"
  * "scoreEquations(Matrix,Digraph,Graph,Bigraph)"
  * "scoreEquations(Matrix,Graph)"
  * "scoreEquations(Matrix,Graph,Bigraph)"
  * "scoreEquations(Matrix,Graph,Bigraph,Digraph)"
  * "scoreEquations(Matrix,Graph,Digraph)"
  * "scoreEquations(Matrix,Graph,Digraph,Bigraph)"
  * "scoreEquations(Matrix,MixedGraph)"
  * "scoreEquations(Matrix,Ring)"
  * "scoreEquations(MixedGraph,List)"
  * "scoreEquations(MixedGraph,Matrix)"
  * "scoreEquations(Ring,List)"
  * "scoreEquations(Ring,Matrix)"

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

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

scoreEquations(...,CovarianceMatrix=>...) -- output covariance matrix
*********************************************************************

Synopsis
========

  * Usage:
        scoreEquations(R,U,CovarianceMatrix=>b)
  * Inputs:
      * b, a Boolean value (Macaulay2Doc), default is false

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

See scoreEquations(...,CovarianceMatrix=>...),
is set to false by
default. If b is true, see scoreEquations, gives an
additional output: the covariance matrix with rational entries in the same
variables as the ideal of score equations.

+-----------------------------------------------------------------------------+
|i1 : G = mixedGraph(digraph {{1,2},{1,3},{2,3},{3,4}},bigraph {{3,4}});      |
+-----------------------------------------------------------------------------+
|i2 : R=gaussianRing(G);                                                      |
+-----------------------------------------------------------------------------+
|i3 : U = matrix{{6, 10, 1/3, 1}, {3/5, 3, 1/2, 1}, {4/5, 3/2, 9/8, 3/10},    |
|                                                                             |
|              4       4                                                      |
|o3 : Matrix QQ  <-- QQ                                                       |
|-----------------------------------------------------------------------------|
|{10/7, 2/3,1, 8/3}};                                                         |
+-----------------------------------------------------------------------------+
|i4 : (J,Sigma)=scoreEquations(R,U,CovarianceMatrix=>true);                   |
+-----------------------------------------------------------------------------+
|i5 : Sigma                                                                   |
|                                                                             |
|o5 = | p_(1,1)                                                               |
|     | l_(1,2)p_(1,1)                                                        |
|     | l_(1,2)l_(2,3)p_(1,1)+l_(1,3)p_(1,1)                                  |
|     | l_(1,2)l_(2,3)l_(3,4)p_(1,1)+l_(1,3)l_(3,4)p_(1,1)                    |
|     ------------------------------------------------------------------------|
|     l_(1,2)p_(1,1)                                                          |
|     l_(1,2)^2p_(1,1)+p_(2,2)                                                |
|     l_(1,2)^2l_(2,3)p_(1,1)+l_(1,2)l_(1,3)p_(1,1)+l_(2,3)p_(2,2)            |
|     l_(1,2)^2l_(2,3)l_(3,4)p_(1,1)+l_(1,2)l_(1,3)l_(3,4)p_(1,1)+l_(2,3)l_(3,|
|     ------------------------------------------------------------------------|
|               l_(1,2)l_(2,3)p_(1,1)+l_(1,3)p_(1,1)                          |
|               l_(1,2)^2l_(2,3)p_(1,1)+l_(1,2)l_(1,3)p_(1,1)+l_(2,3)p_(2,2)  |
|               l_(1,2)^2l_(2,3)^2p_(1,1)+2l_(1,2)l_(1,3)l_(2,3)p_(1,1)+l_(1,3|
|     4)p_(2,2) l_(1,2)^2l_(2,3)^2l_(3,4)p_(1,1)+2l_(1,2)l_(1,3)l_(2,3)l_(3,4)|
|     ------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|     )^2p_(1,1)+l_(2,3)^2p_(2,2)+p_(3,3)                                     |
|     p_(1,1)+l_(1,3)^2l_(3,4)p_(1,1)+l_(2,3)^2l_(3,4)p_(2,2)+l_(3,4)p_(3,3)+p|
|     ------------------------------------------------------------------------|
|            l_(1,2)l_(2,3)l_(3,4)p_(1,1)+l_(1,3)l_(3,4)p_(1,1)               |
|            l_(1,2)^2l_(2,3)l_(3,4)p_(1,1)+l_(1,2)l_(1,3)l_(3,4)p_(1,1)+l_(2,|
|            l_(1,2)^2l_(2,3)^2l_(3,4)p_(1,1)+2l_(1,2)l_(1,3)l_(2,3)l_(3,4)p_(|
|     _(3,4) l_(1,2)^2l_(2,3)^2l_(3,4)^2p_(1,1)+2l_(1,2)l_(1,3)l_(2,3)l_(3,4)^|
|     ------------------------------------------------------------------------|
|                                                                             |
|     3)l_(3,4)p_(2,2)                                                        |
|     1,1)+l_(1,3)^2l_(3,4)p_(1,1)+l_(2,3)^2l_(3,4)p_(2,2)+l_(3,4)p_(3,3)+p_( |
|     2p_(1,1)+l_(1,3)^2l_(3,4)^2p_(1,1)+l_(2,3)^2l_(3,4)^2p_(2,2)+l_(3,4)^2p |
|     ------------------------------------------------------------------------|
|                                    |                                        |
|                                    |                                        |
|     3,4)                           |                                        |
|     _(3,3)+2l_(3,4)p_(3,4)+p_(4,4) |                                        |
|                                                                             |
|                                                                            4|
|o5 : Matrix (frac(QQ[l   ..l   , l   , l   , p   , p   , p   , p   , p   ])) |
|                      1,2   1,3   2,3   3,4   1,1   2,2   3,3   4,4   3,4    |
|-----------------------------------------------------------------------------|
|                                                                    4        |
|<-- (frac(QQ[l   ..l   , l   , l   , p   , p   , p   , p   , p   ]))         |
|              1,2   1,3   2,3   3,4   1,1   2,2   3,3   4,4   3,4            |
+-----------------------------------------------------------------------------+

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

  * Default value: false (Macaulay2Doc),
  * Function: scoreEquations, -- score equations of the
    log-likelihood function of a Gaussian graphical model
  * Option key: CovarianceMatrix, -- optional input to
    output covariance matrix

See also
========

  * scoreEquations -- score equations of the
    log-likelihood function of a Gaussian graphical model

Functions with optional argument named CovarianceMatrix:
========================================================

  * scoreEquations(...,CovarianceMatrix=>...)
    -- output
    covariance matrix

scoreEquations(...,RealPrecision=>...) -- the number of bits of precision to use in the computation
***************************************************************************************************

Synopsis
========

  * Usage:
        scoreEquations(R,U,RealPrecision=>n)
  * Inputs:
      * n, an integer (Macaulay2Doc), default is 53

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

This optional input only applies when the sample data or the sample covariance
matrix has real entries. By default, the precision is 53 (the default precision
for real numbers in M2).

+-----------------------------------------------------------------------------+
|i1 : G = mixedGraph(digraph {{1,2},{1,3},{2,3},{3,4}},bigraph {{3,4}});      |
+-----------------------------------------------------------------------------+
|i2 : R=gaussianRing(G);                                                      |
+-----------------------------------------------------------------------------+
|i3 : U = matrix{{6.2849049, 10.292875, 1.038475, 1.1845757}, {3.1938475,     |
|                                                                             |
|                4         4                                                  |
|o3 : Matrix RR    <-- RR                                                     |
|              53        53                                                   |
|-----------------------------------------------------------------------------|
|3.2573, 1.13847, 1}, {4/5, 3/2, 9/8, 3/10}, {10/7, 2/3,1, 8/3}};             |
+-----------------------------------------------------------------------------+
|i4 : J=scoreEquations(R,U,RealPrecision=>3)                                  |
|                                                                             |
|                                                                             |
|o4 = ideal (19026p    + 1431174p    - 9211, 1310966502451200p    +           |
|                  4,4           3,4                          3,3             |
|     ------------------------------------------------------------------------|
|                                                                             |
|     274389565440p    - 4362116140411, 5p    - 6, p    - 5, 21l    + 6144p   |
|                  3,4                    2,2       1,1         3,4        3,4|
|     ------------------------------------------------------------------------|
|                                                                             |
|     + 256, 97542150480l    - 3183089664p    - 341458895, 341397526680l    + |
|                        2,3              3,4                           1,3   |
|     ------------------------------------------------------------------------|
|                                                       2                     |
|     21426247680p    + 3228576859, 5l    - 8, 11132928p    + 2862348p    -   |
|                 3,4                 1,2               3,4           3,4     |
|     ------------------------------------------------------------------------|
|     9211)                                                                   |
|                                                                             |
|o4 : Ideal of QQ[l   ..l   , l   , l   , p   , p   , p   , p   , p   ]       |
|                  1,2   1,3   2,3   3,4   1,1   2,2   3,3   4,4   3,4        |
+-----------------------------------------------------------------------------+

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

  * Default value: 53
  * Function: scoreEquations, -- score equations of the
    log-likelihood function of a Gaussian graphical model
  * Option key: RealPrecision, -- optional input to choose
    the number of decimals used to round to QQ when inputing data in RR

See also
========

  * scoreEquations -- score equations of the
    log-likelihood function of a Gaussian graphical model

Functions with optional argument named RealPrecision:
=====================================================

  * scoreEquations(...,RealPrecision=>...)
    -- the number of
    bits of precision to use in the computation
  * solverMLE(...,RealPrecision=>...)
    -- the number of bits
    of precision to use in the computation

scoreEquations(...,SampleData=>...) -- input sample covariance matrix instead of sample data
********************************************************************************************

Synopsis
========

  * Usage:
        scoreEquations(R,U,SampleData=>b)
  * Inputs:
      * b, a Boolean value (Macaulay2Doc), default is true

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

See scoreEquations, requires a matrix or a list of sample
data as part of the default input. Setting
scoreEquations(...,SampleData=>...),
to false allows the user
to enter a sample covariance matrix instead of sample data. It must be a
symmetric matrix.

+-----------------------------------------------------------------------------+
|i1 : G = mixedGraph(digraph {{1,2},{1,3},{2,3},{3,4}},bigraph {{3,4}});      |
+-----------------------------------------------------------------------------+
|i2 : R=gaussianRing(G);                                                      |
+-----------------------------------------------------------------------------+
|i3 : U = matrix{{6, 10, 1/3, 1}, {3/5, 3, 1/2, 1}, {4/5, 3/2, 9/8, 3/10},    |
|                                                                             |
|o3 = | 6    10  1/3 1    |                                                   |
|     | 3/5  3   1/2 1    |                                                   |
|     | 4/5  3/2 9/8 3/10 |                                                   |
|     | 10/7 2/3 1   8/3  |                                                   |
|                                                                             |
|              4       4                                                      |
|o3 : Matrix QQ  <-- QQ                                                       |
|-----------------------------------------------------------------------------|
|{10/7, 2/3,1, 8/3}}                                                          |
+-----------------------------------------------------------------------------+
|i4 : J=scoreEquations(R,U,SampleData=>true)                                  |
|                                                                             |
|o4 = ideal (192199680p    - 99333449, 267221621760p    - 849243924773,       |
|                      3,4                          4,4                       |
|     ------------------------------------------------------------------------|
|     1353974896462794079472640p    - 142165262245288892244817, 6898968p    - |
|                               3,3                                     2,2   |
|     ------------------------------------------------------------------------|
|     11533057, 19600p    - 95819, 20855l    + 90447,                         |
|                     1,1                3,4                                  |
|     ------------------------------------------------------------------------|
|     146915678869660815915l    - 4228634793402814499,                        |
|                           2,3                                               |
|     ------------------------------------------------------------------------|
|     58766271547864326366l    + 4167005135395196717, 574914l    - 896035)    |
|                          1,3                               1,2              |
|                                                                             |
|o4 : Ideal of QQ[l   ..l   , l   , l   , p   , p   , p   , p   , p   ]       |
|                  1,2   1,3   2,3   3,4   1,1   2,2   3,3   4,4   3,4        |
+-----------------------------------------------------------------------------+
|i5 : V=sampleCovarianceMatrix(U)                                             |
|                                                                             |
|o5 = | 95819/19600 25601/3360 -2129/4480 -1313/16800 |                       |
|     | 25601/3360  867/64     -2321/2304 -173/192    |                       |
|     | -2129/4480  -2321/2304 337/3072   473/11520   |                       |
|     | -1313/16800 -173/192   473/11520  3641/4800   |                       |
|                                                                             |
|              4       4                                                      |
|o5 : Matrix QQ  <-- QQ                                                       |
+-----------------------------------------------------------------------------+
|i6 : I=scoreEquations(R,V,SampleData=>false)                                 |
|                                                                             |
|o6 = ideal (192199680p    - 99333449, 267221621760p    - 849243924773,       |
|                      3,4                          4,4                       |
|     ------------------------------------------------------------------------|
|     1353974896462794079472640p    - 142165262245288892244817, 6898968p    - |
|                               3,3                                     2,2   |
|     ------------------------------------------------------------------------|
|     11533057, 19600p    - 95819, 20855l    + 90447,                         |
|                     1,1                3,4                                  |
|     ------------------------------------------------------------------------|
|     146915678869660815915l    - 4228634793402814499,                        |
|                           2,3                                               |
|     ------------------------------------------------------------------------|
|     58766271547864326366l    + 4167005135395196717, 574914l    - 896035)    |
|                          1,3                               1,2              |
|                                                                             |
|o6 : Ideal of QQ[l   ..l   , l   , l   , p   , p   , p   , p   , p   ]       |
|                  1,2   1,3   2,3   3,4   1,1   2,2   3,3   4,4   3,4        |
+-----------------------------------------------------------------------------+

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

  * Default value: true (Macaulay2Doc),
  * Function: scoreEquations, -- score equations of the
    log-likelihood function of a Gaussian graphical model
  * Option key: SampleData, -- optional input to allow to
    input the sample covariance matrix instead of sample data

See also
========

  * scoreEquations -- score equations of the
    log-likelihood function of a Gaussian graphical model

Functions with optional argument named SampleData:
==================================================

  * scoreEquations(...,SampleData=>...)
    -- input sample
    covariance matrix instead of sample data
  * solverMLE(...,SampleData=>...)
    -- input sample
    covariance matrix instead of sample data

scoreEquations(...,Saturate=>...) -- whether to saturate
********************************************************

Synopsis
========

  * Usage:
        scoreEquations(R,U,Saturate=>b)
  * Inputs:
      * b, a Boolean value (Macaulay2Doc), default is true

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

See scoreEquations(...,Saturate=>...),
is set to true by default.
If b is false, saturation is not performed.

Avoiding saturation is only intended for big computations when saturation
cannot be computed or the computational time is very high. When Saturate,
is set to false, see scoreEquations, might not
output the ideal generated by score equations because of the existence of
vanishing denominators.

For graphs with only undirected edges, the ideal of score equations is the
saturation of the outputted ideal by the determinant of the concentration
matrix. In the general case, the ideal of score equations consist of the
saturation of the outputted ideal by the product of denominators of the
Jacobian matrix.

For example, in the following case the degree of the ideal prior to saturation
already gives the right ML-degree:

+-----------------------------------------------------------------------------+
|i1 : G = mixedGraph(digraph {{1,2},{1,3},{2,3},{3,4}},bigraph {{3,4}});      |
+-----------------------------------------------------------------------------+
|i2 : R=gaussianRing(G);                                                      |
+-----------------------------------------------------------------------------+
|i3 : U = matrix{{6, 10, 1/3, 1}, {3/5, 3, 1/2, 1}, {4/5, 3/2, 9/8, 3/10},    |
|                                                                             |
|              4       4                                                      |
|o3 : Matrix QQ  <-- QQ                                                       |
|-----------------------------------------------------------------------------|
|{10/7, 2/3,1, 8/3}};                                                         |
+-----------------------------------------------------------------------------+
|i4 : JnoSat=scoreEquations(R,U,Saturate=>false);                             |
|                                                                             |
|o4 : Ideal of QQ[l   ..l   , l   , l   , p   , p   , p   , p   , p   ]       |
|                  1,2   1,3   2,3   3,4   1,1   2,2   3,3   4,4   3,4        |
+-----------------------------------------------------------------------------+
|i5 : dim JnoSat                                                              |
|                                                                             |
|o5 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i6 : degree JnoSat                                                           |
|                                                                             |
|o6 = 1                                                                       |
+-----------------------------------------------------------------------------+
|i7 : J=scoreEquations(R,U)                                                   |
|                                                                             |
|o7 = ideal (192199680p    - 99333449, 267221621760p    - 849243924773,       |
|                      3,4                          4,4                       |
|     ------------------------------------------------------------------------|
|     1353974896462794079472640p    - 142165262245288892244817, 6898968p    - |
|                               3,3                                     2,2   |
|     ------------------------------------------------------------------------|
|     11533057, 19600p    - 95819, 20855l    + 90447,                         |
|                     1,1                3,4                                  |
|     ------------------------------------------------------------------------|
|     146915678869660815915l    - 4228634793402814499,                        |
|                           2,3                                               |
|     ------------------------------------------------------------------------|
|     58766271547864326366l    + 4167005135395196717, 574914l    - 896035)    |
|                          1,3                               1,2              |
|                                                                             |
|o7 : Ideal of QQ[l   ..l   , l   , l   , p   , p   , p   , p   , p   ]       |
|                  1,2   1,3   2,3   3,4   1,1   2,2   3,3   4,4   3,4        |
+-----------------------------------------------------------------------------+
|i8 : degree JnoSat==degree J                                                 |
|                                                                             |
|o8 = true                                                                    |
+-----------------------------------------------------------------------------+

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

  * Default value: true (Macaulay2Doc),
  * Function: scoreEquations, -- score equations of the
    log-likelihood function of a Gaussian graphical model
  * Option key: Saturate, -- optional input whether to saturate

See also
========

  * scoreEquations -- score equations of the
    log-likelihood function of a Gaussian graphical model

Functions with optional argument named Saturate:
================================================

  * scoreEquations(...,Saturate=>...)
    -- whether to saturate
  * solverMLE(...,Saturate=>...)
    -- whether to saturate

scoreEquations(...,SaturateOptions=>...) -- use options from "saturate"
***********************************************************************

Synopsis
========

  * Usage:
        scoreEquations(R,U,SaturateOptions=>L)
  * Inputs:
      * L, a list (Macaulay2Doc), of options to set up saturation.
        Accepts any option from the function saturate (Saturation),

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

Default SaturateOptions, in scoreEquations,
are the default options in saturate (Saturation).
All optional input in saturate (Saturation),
is allowed.

+-----------------------------------------------------------------------------+
|i1 : G = mixedGraph(digraph {{1,2},{1,3},{2,3},{3,4}},bigraph {{3,4}})       |
|                                                                             |
|o1 = MixedGraph{Bigraph => Bigraph{3 => {4}}   }                             |
|                                   4 => {3}                                  |
|                Digraph => Digraph{1 => {2, 3}}                              |
|                                   2 => {3}                                  |
|                                   3 => {4}                                  |
|                                   4 => {}                                   |
|                Graph => Graph{}                                             |
|                                                                             |
|o1 : MixedGraph                                                              |
+-----------------------------------------------------------------------------+
|i2 : R=gaussianRing(G)                                                       |
|                                                                             |
|o2 = R                                                                       |
|                                                                             |
|o2 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i3 : U = matrix{{6, 10, 1/3, 1}, {3/5, 3, 1/2, 1}, {4/5, 3/2, 9/8, 3/10},    |
|                                                                             |
|              4       4                                                      |
|o3 : Matrix QQ  <-- QQ                                                       |
|-----------------------------------------------------------------------------|
|{10/7, 2/3,1, 8/3}};                                                         |
+-----------------------------------------------------------------------------+
|i4 : J=scoreEquations(R,U,SaturateOptions => {DegreeLimit=>1, MinimalGenerato|
|                                                                             |
|o4 = ideal (192199680p    - 99333449, 267221621760p    - 849243924773,       |
|                      3,4                          4,4                       |
|     ------------------------------------------------------------------------|
|     1353974896462794079472640p    - 142165262245288892244817, 6898968p    - |
|                               3,3                                     2,2   |
|     ------------------------------------------------------------------------|
|     11533057, 19600p    - 95819, 20855l    + 90447,                         |
|                     1,1                3,4                                  |
|     ------------------------------------------------------------------------|
|     146915678869660815915l    - 4228634793402814499,                        |
|                           2,3                                               |
|     ------------------------------------------------------------------------|
|     58766271547864326366l    + 4167005135395196717, 574914l    - 896035)    |
|                          1,3                               1,2              |
|                                                                             |
|o4 : Ideal of QQ[l   ..l   , l   , l   , p   , p   , p   , p   , p   ]       |
|                  1,2   1,3   2,3   3,4   1,1   2,2   3,3   4,4   3,4        |
|-----------------------------------------------------------------------------|
|rs => false})                                                                |
+-----------------------------------------------------------------------------+

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

  * Default value: new OptionTable from {Strategy => null, BasisElementLimit =>
    infinity, DegreeLimit => {}, MinimalGenerators => true, PairLimit =>
    infinity}
  * Function: scoreEquations, -- score equations of the
    log-likelihood function of a Gaussian graphical model
  * Option key: SaturateOptions, -- optional input to
    use options "saturate"

See also
========

  * scoreEquations -- score equations of the
    log-likelihood function of a Gaussian graphical model
  * Saturate -- optional input whether to saturate
  * saturate (missing documentation)
  * solverMLE -- Maximum likelihood estimate of a loopless
    mixed graph

Functions with optional argument named SaturateOptions:
=======================================================

  * scoreEquations(...,SaturateOptions=>...)
    -- use options
    from "saturate"
  * solverMLE(...,SaturateOptions=>...)
    -- use options from
    "saturate"

Solver -- optional input to choose numerical solver
***************************************************

See also
========

  * solverMLE -- Maximum likelihood estimate of a loopless
    mixed graph
  * EigenSolver -- polynomial system solver via
    eigen-computations
  * NumericalAlgebraicGeometry, --
    Numerical Algebraic Geometry
  * zeroDimSolve (EigenSolver) -- zero-dimensional
    polynomial system solver
  * solveSystem (NumericalAlgebraicGeometry), --
    solve a system of polynomial equations

Functions with optional argument named Solver:
==============================================

  * solverMLE(...,Solver=>...)
    -- choose numerical solver

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

The object Solver, is a symbol (Macaulay2Doc).

solverMLE -- Maximum likelihood estimate of a loopless mixed graph
******************************************************************

Synopsis
========

  * Usage:
        solverMLE(G,U)
  * Inputs:
      * G, a graph (Graphs), or a digraph (Graphs),
        or an instance of the type Bigraph (StatGraphs), or an
        instance of the type MixedGraph (StatGraphs),
      * U, a matrix (Macaulay2Doc), or a list (Macaulay2Doc),
        of sample data. Alternatively, the sample
        covariance matrix can be given as input by setting SampleData,
        to false
  * Optional inputs (Macaulay2Doc),:
      * ConcentrationMatrix,
        => ...,
        default value false, output MLE for concentration matrix instead of MLE
        for covariance matrix
      * OptionsEigenSolver,
        => ...,
        default value new OptionTable from {Strategy => Stickelberger,
        Tolerance => .000001, Basis => null, Multiplier => 0}, use options of
        "zeroDimSolve" in "EigenSolver"
      * OptionsNAG4M2,
        => ..., default value new OptionTable from {EndZoneFactor => null,
        maxCorrSteps => null, Predictor => null, stepIncreaseFactor => null,
        Precision => null, tStep => null, tDegree => null, CorrectorTolerance
        => null, InfinityThreshold => null, gamma => null, Software => null,
        ResidualTolerance => null, numberSuccessesBeforeIncrease => null,
        Normalize => null, SingularConditionNumber => null, Projectivize =>
        null, PostProcess => true, tStepMin => null}, use options of
        "solveSystem" in "NumericalAlgebraicGeometry"
      * RealPrecision,
        => ..., default value 53, the number of bits of precision to use in
        the computation
      * SampleData, =>
        ..., default value true, input sample covariance matrix instead of
        sample data
      * Saturate, => ...,
        default value true, whether to saturate
      * SaturateOptions,
        => ..., default
        value new OptionTable from {Strategy => null, BasisElementLimit =>
        infinity, DegreeLimit => {}, MinimalGenerators => true, PairLimit =>
        infinity}, use options from "saturate"
      * Solver, => ...,
        default value "EigenSolver", choose numerical solver
      * ZeroTolerance,
        => ..., default value 1e-10, optional input to set the largest
        absolute value that should be treated as zero
  * Outputs:
      * a sequence (Macaulay2Doc), of length 3, whose first
        element is the maximum value attained in the log-likelihood function
        (of type RR (Macaulay2Doc)), its second element is the MLE
        (or MLEs) of the covariance matrix (of types Matrix (Macaulay2Doc),
        or List (Macaulay2Doc)), and its
        third element is the ML-degree of the model (of type ZZ (Macaulay2Doc)).
        By providing true as the value for the option
        ConcentrationMatrix, the MLE for the
        concentration matrix can be given as output.

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

This function takes as input a graph (Graphs), or a digraph (Graphs),
or a bigraph (StatGraphs), or a mixed graph (StatGraphs),
and a list or matrix that encodes, by default,
the sample data. It computes the critical points of the score equations and
selects the maximum value achieved among those that lie in the cone of
positive-definite matrices. The default output is the maximum value in the
log-likelihood function, maximum likelihood estimators (MLE) for the covariance
matrix and the ML-degree of the model. MLE for the concentration matrix can be
obtained by setting the optional input ConcentrationMatrix,
to false.

The same optional inputs as in scoreEquations, can be
used, plus extra optional inputs related to the numerical solver (EigenSolver
by default, NAG4M2 alternatively) and its functionalities.

Below we reproduce Example 2.1.13 for the 4-cycle in the book: Mathias Drton,
Bernd Sturmfels and Seth Sullivant, Lectures on Algebraic Statistics,
Oberwolfach Seminars, Vol 40, Birkhauser, Basel, 2009.

+------------------------------------------------------------------+
|i1 : G=graph{{1,2},{2,3},{3,4},{1,4}};                            |
+------------------------------------------------------------------+
|i2 : U =matrix{{1,2,1,-1},{2,1,3,0},{-1, 0, 1, 1},{-5, 3, 4, -6}};|
|                                                                  |
|              4       4                                           |
|o2 : Matrix ZZ  <-- ZZ                                            |
+------------------------------------------------------------------+
|i3 : solverMLE(G,U)                                               |
|                                                                  |
|o3 = (-6.2615, | 7.1875   -1.625   -2.22576 5.875    |, 5)        |
|               | -1.625   1.25     .875     -1.62833 |            |
|               | -2.22576 .875     1.6875   -2.625   |            |
|               | 5.875    -1.62833 -2.625   7.25     |            |
|                                                                  |
|o3 : Sequence                                                     |
+------------------------------------------------------------------+

The data sample can also be given as a list:

+-------------------------------------------------------------+
|i4 : G=graph{{1,2},{2,3},{3,4},{1,4}};                       |
+-------------------------------------------------------------+
|i5 : U = {{1,2,1,-1},{2,1,3,0},{-1, 0, 1, 1},{-5, 3, 4, -6}};|
+-------------------------------------------------------------+
|i6 : solverMLE(G,U)                                          |
|                                                             |
|o6 = (-6.2615, | 7.1875   -1.625   -2.22576 5.875    |, 5)   |
|               | -1.625   1.25     .875     -1.62833 |       |
|               | -2.22576 .875     1.6875   -2.625   |       |
|               | 5.875    -1.62833 -2.625   7.25     |       |
|                                                             |
|o6 : Sequence                                                |
+-------------------------------------------------------------+

In the following example we compute the MLE for the covariance matrix of the
graphical model associated to the graph $1\rightarrow 2,1\rightarrow
3,2\rightarrow 3,3\rightarrow 4,3<-> 4$ In this case we give as input the
sample covariance matrix:

+-----------------------------------------------------------------------------+
|i7 : G = mixedGraph(digraph {{1,3},{2,4}},bigraph {{3,4}});                  |
+-----------------------------------------------------------------------------+
|i8 : S =  matrix {{7/20, 13/50, -3/50, -19/100}, {13/50, 73/100, -7/100,     |
|                                                                             |
|              4       4                                                      |
|o8 : Matrix QQ  <-- QQ                                                       |
|-----------------------------------------------------------------------------|
|-9/100},{-3/50, -7/100, 2/5, 3/50}, {-19/100, -9/100, 3/50, 59/100}};        |
+-----------------------------------------------------------------------------+
|i9 : solverMLE(G,S,SampleData=>false)                                        |
|                                                                             |
|o9 = (-.665426, | .35       .26      -.0362724 -.19     |, 5)                |
|                | .26       .73      -.07      -.145523 |                    |
|                | -.0362724 -.07     .4        .06      |                    |
|                | -.19      -.145523 .06       .59      |                    |
|                                                                             |
|o9 : Sequence                                                                |
+-----------------------------------------------------------------------------+

Next we provide the MLE for the concentration matrix of the graphical model
associated to the graph $1\rightarrow 3,2\rightarrow 4,3<->4,1 - 2$. Again the
sample covariance matrix is given as input.

+-----------------------------------------------------------------------------+
|i10 : G = mixedGraph(digraph {{1,3},{2,4}},bigraph {{3,4}},graph {{1,2}});   |
+-----------------------------------------------------------------------------+
|i11 : S =  matrix {{7/20, 13/50, -3/50, -19/100}, {13/50, 73/100, -7/100,    |
|                                                                             |
|               4       4                                                     |
|o11 : Matrix QQ  <-- QQ                                                      |
|-----------------------------------------------------------------------------|
|-9/100},{-3/50, -7/100, 2/5, 3/50}, {-19/100, -9/100, 3/50, 59/100}};        |
+-----------------------------------------------------------------------------+
|i12 : solverMLE(G,S,SampleData=>false,ConcentrationMatrix=>true)             |
|                                                                             |
|o12 = (-.665426, | 4.47695  -1.37472 0        1.10266  |, 5)                 |
|                 | -1.37472 1.87907  .204176  0        |                     |
|                 | 0        .204176  2.56734  -.210726 |                     |
|                 | 1.10266  0        -.210726 2.07144  |                     |
|                                                                             |
|o12 : Sequence                                                               |
+-----------------------------------------------------------------------------+

Application to positive definite matrix completion problems

Consider the following symmetric matrix with some unknown entries:

+---------------------------------------------------------------------+
|i13 : R=QQ[x,y];                                                     |
+---------------------------------------------------------------------+
|i14 : M=matrix{{115,-13,x,47},{-13,5,7,y},{x,7,27,-21},{47,y,-21,29}}|
|                                                                     |
|o14 = | 115 -13 x   47  |                                            |
|      | -13 5   7   y   |                                            |
|      | x   7   27  -21 |                                            |
|      | 47  y   -21 29  |                                            |
|                                                                     |
|              4      4                                               |
|o14 : Matrix R  <-- R                                                |
+---------------------------------------------------------------------+

Unknown entries correspond to non-edges of the 4-cycle. A positive definite
completion of this matrix is obtained by giving values to x and y and computing
the MLE for the covariance matrix in the Gaussian graphical model given by the
4-cycle. To understand which values of x and y will result in a maximum
likelihood estimate, see Example 12.16 in the book: Mateusz Michalek and Bernd
Sturmfels, Invitation to Nonlinear Algebra, Graduate Studies in Mathematics,
Vol ???, American Mathematical Society, 2021.

+-----------------------------------------------------------------------------+
|i15 : G=graph{{1,2},{2,3},{3,4},{1,4}};                                      |
+-----------------------------------------------------------------------------+
|i16 : V=matrix{{115,-13,-29,47},{-13,5,7,-11},{-29,7,27,-21},{47,-11,-21,29}}|
|                                                                             |
|o16 = | 115 -13 -29 47  |                                                    |
|      | -13 5   7   -11 |                                                    |
|      | -29 7   27  -21 |                                                    |
|      | 47  -11 -21 29  |                                                    |
|                                                                             |
|               4       4                                                     |
|o16 : Matrix ZZ  <-- ZZ                                                      |
+-----------------------------------------------------------------------------+
|i17 : (mx,MLE,ML)=solverMLE(G,V,SampleData=>false)                           |
|                                                                             |
|o17 = (-14.5793, | 115      -13      -35.6122 47       |, 5)                 |
|                 | -13      5        7        -6.51331 |                     |
|                 | -35.6122 7        27       -21      |                     |
|                 | 47       -6.51331 -21      29       |                     |
|                                                                             |
|o17 : Sequence                                                               |
+-----------------------------------------------------------------------------+

The MLE of the covariance matrix is the unique positive definite completion of
the matrix M such that its inverse, namely the concentration matrix, has zero's
in the entries corresponding to non-edges of the graph. Observe that all
entries of V remain the same in the MLE except for those that correspond to
non-edges of the graph.

See also
========

  * checkPD -- returns positive definite matrices from a list
    of symmetric  matrices
  * checkPSD -- returns positive semidefinite matrices from a
    list of symmetric matrices
  * scoreEquations -- score equations of the
    log-likelihood function of a Gaussian graphical model
  * jacobianMatrixOfRationalFunction,
    -- Jacobian matrix of a rational function
  * sampleCovarianceMatrix -- sample covariance
    matrix of observation vectors

Ways to use solverMLE:
======================

  * "solverMLE(Bigraph,Digraph,Graph,List)"
  * "solverMLE(Bigraph,Digraph,Graph,Matrix)"
  * "solverMLE(Bigraph,Digraph,List)"
  * "solverMLE(Bigraph,Digraph,Matrix)"
  * "solverMLE(Bigraph,Graph,Digraph,List)"
  * "solverMLE(Bigraph,Graph,Digraph,Matrix)"
  * "solverMLE(Bigraph,Graph,List)"
  * "solverMLE(Bigraph,Graph,Matrix)"
  * "solverMLE(Bigraph,List)"
  * "solverMLE(Bigraph,Matrix)"
  * "solverMLE(Digraph,Bigraph,Graph,List)"
  * "solverMLE(Digraph,Bigraph,Graph,Matrix)"
  * "solverMLE(Digraph,Bigraph,List)"
  * "solverMLE(Digraph,Bigraph,Matrix)"
  * "solverMLE(Digraph,Graph,Bigraph,List)"
  * "solverMLE(Digraph,Graph,Bigraph,Matrix)"
  * "solverMLE(Digraph,Graph,List)"
  * "solverMLE(Digraph,Graph,Matrix)"
  * "solverMLE(Digraph,List)"
  * "solverMLE(Digraph,Matrix)"
  * "solverMLE(Graph,Bigraph,Digraph,List)"
  * "solverMLE(Graph,Bigraph,Digraph,Matrix)"
  * "solverMLE(Graph,Bigraph,List)"
  * "solverMLE(Graph,Bigraph,Matrix)"
  * "solverMLE(Graph,Digraph,Bigraph,List)"
  * "solverMLE(Graph,Digraph,Bigraph,Matrix)"
  * "solverMLE(Graph,Digraph,List)"
  * "solverMLE(Graph,Digraph,Matrix)"
  * "solverMLE(Graph,List)"
  * "solverMLE(Graph,Matrix)"
  * "solverMLE(List,Bigraph)"
  * "solverMLE(List,Bigraph,Digraph)"
  * "solverMLE(List,Bigraph,Digraph,Graph)"
  * "solverMLE(List,Bigraph,Graph)"
  * "solverMLE(List,Bigraph,Graph,Digraph)"
  * "solverMLE(List,Digraph)"
  * "solverMLE(List,Digraph,Bigraph)"
  * "solverMLE(List,Digraph,Bigraph,Graph)"
  * "solverMLE(List,Digraph,Graph)"
  * "solverMLE(List,Digraph,Graph,Bigraph)"
  * "solverMLE(List,Graph)"
  * "solverMLE(List,Graph,Bigraph)"
  * "solverMLE(List,Graph,Bigraph,Digraph)"
  * "solverMLE(List,Graph,Digraph)"
  * "solverMLE(List,Graph,Digraph,Bigraph)"
  * "solverMLE(List,MixedGraph)"
  * "solverMLE(List,Ring)"
  * "solverMLE(Matrix,Bigraph)"
  * "solverMLE(Matrix,Bigraph,Digraph)"
  * "solverMLE(Matrix,Bigraph,Digraph,Graph)"
  * "solverMLE(Matrix,Bigraph,Graph)"
  * "solverMLE(Matrix,Bigraph,Graph,Digraph)"
  * "solverMLE(Matrix,Digraph)"
  * "solverMLE(Matrix,Digraph,Bigraph)"
  * "solverMLE(Matrix,Digraph,Bigraph,Graph)"
  * "solverMLE(Matrix,Digraph,Graph)"
  * "solverMLE(Matrix,Digraph,Graph,Bigraph)"
  * "solverMLE(Matrix,Graph)"
  * "solverMLE(Matrix,Graph,Bigraph)"
  * "solverMLE(Matrix,Graph,Bigraph,Digraph)"
  * "solverMLE(Matrix,Graph,Digraph)"
  * "solverMLE(Matrix,Graph,Digraph,Bigraph)"
  * "solverMLE(Matrix,MixedGraph)"
  * "solverMLE(Matrix,Ring)"
  * "solverMLE(MixedGraph,List)"
  * "solverMLE(MixedGraph,Matrix)"
  * "solverMLE(Ring,List)"
  * "solverMLE(Ring,Matrix)"

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

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

solverMLE(...,ConcentrationMatrix=>...) -- output MLE for concentration matrix instead of MLE for covariance matrix
*******************************************************************************************************************

Synopsis
========

  * Usage:
        solverMLE(G,U,ConcentrationMatrix=>b)
  * Inputs:
      * b, a Boolean value (Macaulay2Doc), false by default

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

By default, see solverMLE, outputs the MLE for the covariance
matrix. By providing true as the value for the option
solverMLE(...,ConcentrationMatrix=>...),
see solverMLE,
provides the MLE for the concentration matrix.

Note that both the maximum value attained in the log-likelihood function and
the ML-degree remain the same.

+-----------------------------------------------------------------------------+
|i1 : G= mixedGraph(graph{{a,b},{b,c}},digraph {{a,d},{c,e},{f,g}},bigraph    |
|                                                                             |
|o1 = MixedGraph{Bigraph => Bigraph{d => {e}}}                                |
|                                   e => {d}                                  |
|                Digraph => Digraph{a => {d}}                                 |
|                                   c => {e}                                  |
|                                   d => {}                                   |
|                                   e => {}                                   |
|                                   f => {g}                                  |
|                                   g => {}                                   |
|                Graph => Graph{a => {b}   }                                  |
|                               b => {a, c}                                   |
|                               c => {b}                                      |
|                                                                             |
|o1 : MixedGraph                                                              |
|-----------------------------------------------------------------------------|
|{{d,e}})                                                                     |
+-----------------------------------------------------------------------------+
|i2 : solverMLE (G, random(QQ^7,QQ^7))                                        |
|                                                                             |
|o2 = (-8.88546, | 1.76276   -.132596  .0588765 1.19122   -.0121464 0         |
|                | -.132596  .406406   -.180456 -.0896046 .0372285  0         |
|                | .0588765  -.180456  4.53915  .0397869  -.93644   0         |
|                | 1.19122   -.0896046 .0397869 4.6897    5.61757   0         |
|                | -.0121464 .0372285  -.93644  5.61757   9.69158   0         |
|                | 0         0         0        0         0         2.42434   |
|                | 0         0         0        0         0         -.115437  |
|     ------------------------------------------------------------------------|
|     0        |, 5)                                                          |
|     0        |                                                              |
|     0        |                                                              |
|     0        |                                                              |
|     0        |                                                              |
|     -.115437 |                                                              |
|     .171669  |                                                              |
|                                                                             |
|o2 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i3 : solverMLE (G, random(QQ^7,QQ^7), ConcentrationMatrix=>true)             |
|                                                                             |
|o3 = (-6.95349, | 2.63818  .250925  -.421645 1.01192  .164301  0             |
|                | .250925  .493839  .0300089 0        0        0             |
|                | -.421645 .0300089 6.42505  -.309127 -.386315 0             |
|                | 1.01192  0        -.309127 .741884  .120456  0             |
|                | .164301  0        -.386315 .120456  .150534  0             |
|                | 0        0        0        0        0        2.54322       |
|                | 0        0        0        0        0        -2.42347      |
|     ------------------------------------------------------------------------|
|     0        |, 5)                                                          |
|     0        |                                                              |
|     0        |                                                              |
|     0        |                                                              |
|     0        |                                                              |
|     -2.42347 |                                                              |
|     3.70744  |                                                              |
|                                                                             |
|o3 : Sequence                                                                |
+-----------------------------------------------------------------------------+

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

  * Default value: false (Macaulay2Doc),
  * Function: solverMLE, -- Maximum likelihood estimate of a
    loopless mixed graph
  * Option key: ConcentrationMatrix, -- optional
    input to output MLE for concentration matrix instead of MLE for covariance
    matrix

See also
========

  * solverMLE -- Maximum likelihood estimate of a loopless
    mixed graph

Functions with optional argument named ConcentrationMatrix:
===========================================================

  * solverMLE(...,ConcentrationMatrix=>...)
    -- output MLE
    for concentration matrix instead of MLE for covariance matrix

solverMLE(...,OptionsEigenSolver=>...) -- use options of "zeroDimSolve" in "EigenSolver"
****************************************************************************************

Synopsis
========

  * Usage:
        solverMLE(G,U,Solver=>"EigenSolver",OptionsEigenSolver=>L)
  * Inputs:
      * L, a list (Macaulay2Doc), of optional inputs in
        zeroDimSolve (EigenSolver),

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

Default OptionsEigenSolver, in solverMLE,
are the default options in zeroDimSolve (EigenSolver),
in EigenSolver. All
optional input in zeroDimSolve (EigenSolver), is allowed.

+-----------------------------------------------------------------------------+
|i1 : G=mixedGraph(graph{{a,b},{b,c}})                                        |
|                                                                             |
|o1 = MixedGraph{Bigraph => Bigraph{}       }                                 |
|                Digraph => Digraph{}                                         |
|                Graph => Graph{a => {b}   }                                  |
|                               b => {a, c}                                   |
|                               c => {b}                                      |
|                                                                             |
|o1 : MixedGraph                                                              |
+-----------------------------------------------------------------------------+
|i2 : solverMLE(G,matrix{{1,0,0},{0,1,0},{0,0,1}},Solver=>"EigenSolver",      |
|                                                                             |
|o2 = (2.0876, | .222222  -.111111 .0555556 |, 1)                             |
|              | -.111111 .222222  -.111111 |                                 |
|              | .0555556 -.111111 .222222  |                                 |
|                                                                             |
|o2 : Sequence                                                                |
|-----------------------------------------------------------------------------|
|OptionsEigenSolver=>{Multiplier =>1, Strategy=>"Stickelberger"})             |
+-----------------------------------------------------------------------------+

In fact, since zeroDimSolve (EigenSolver), is the current
default numerical solver. the sintaxis below is enough:

+-----------------------------------------------------------------------------+
|i3 : G=mixedGraph(graph{{a,b},{b,c}})                                        |
|                                                                             |
|o3 = MixedGraph{Bigraph => Bigraph{}       }                                 |
|                Digraph => Digraph{}                                         |
|                Graph => Graph{a => {b}   }                                  |
|                               b => {a, c}                                   |
|                               c => {b}                                      |
|                                                                             |
|o3 : MixedGraph                                                              |
+-----------------------------------------------------------------------------+
|i4 : solverMLE(G,matrix{{1,0,0},{0,1,0},{0,0,1}},OptionsEigenSolver=>{       |
|                                                                             |
|o4 = (2.0876, | .222222  -.111111 .0555556 |, 1)                             |
|              | -.111111 .222222  -.111111 |                                 |
|              | .0555556 -.111111 .222222  |                                 |
|                                                                             |
|o4 : Sequence                                                                |
|-----------------------------------------------------------------------------|
|Multiplier =>1, Strategy=>"Stickelberger"})                                  |
+-----------------------------------------------------------------------------+

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

  * Default value: new OptionTable from {Strategy => Stickelberger, Tolerance
    => .000001, Basis => null, Multiplier => 0}
  * Function: solverMLE, -- Maximum likelihood estimate of a
    loopless mixed graph
  * Option key: OptionsEigenSolver, -- optional input
    to use options of "zeroDimSolve" in "EigenSolver"

See also
========

  * solverMLE -- Maximum likelihood estimate of a loopless
    mixed graph
  * EigenSolver -- polynomial system solver via
    eigen-computations
  * zeroDimSolve (EigenSolver) -- zero-dimensional
    polynomial system solver

Functions with optional argument named OptionsEigenSolver:
==========================================================

  * solverMLE(...,OptionsEigenSolver=>...)
    -- use options of
    "zeroDimSolve" in "EigenSolver"

solverMLE(...,OptionsNAG4M2=>...) -- use options of "solveSystem" in "NumericalAlgebraicGeometry"
*************************************************************************************************

Synopsis
========

  * Usage:
        solverMLE(G,U,Solver=>"NAG4M2",OptionsNAG4M2=>L)
  * Inputs:
      * L, a list (Macaulay2Doc), of optional inputs to
        solveSystem (NumericalAlgebraicGeometry),

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

Default OptionsNAG4M2, in solverMLE, when
setting solverMLE(...,Solver=>...),
to "NAG4M2" are the default
options of solveSystem (NumericalAlgebraicGeometry),
in
NumericalAlgebraicGeometry. All optional
input in solveSystem (NumericalAlgebraicGeometry),
is allowed.

+-----------------------------------------------------------------------------+
|i1 : G=mixedGraph(graph{{a,b},{b,c}})                                        |
|                                                                             |
|o1 = MixedGraph{Bigraph => Bigraph{}       }                                 |
|                Digraph => Digraph{}                                         |
|                Graph => Graph{a => {b}   }                                  |
|                               b => {a, c}                                   |
|                               c => {b}                                      |
|                                                                             |
|o1 : MixedGraph                                                              |
+-----------------------------------------------------------------------------+
|i2 : solverMLE(G,matrix{{1,0,0},{0,1,0},{0,0,1}},Solver=>"NAG4M2",           |
|                                                                             |
|o2 = (2.0876, | .222222  -.111111 .0555556 |, 1)                             |
|              | -.111111 .222222  -.111111 |                                 |
|              | .0555556 -.111111 .222222  |                                 |
|                                                                             |
|o2 : Sequence                                                                |
|-----------------------------------------------------------------------------|
|OptionsNAG4M2=>{tStep =>.01,numberSuccessesBeforeIncrease => 5})             |
+-----------------------------------------------------------------------------+

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

  * Default value: new OptionTable from {EndZoneFactor => null, maxCorrSteps =>
    null, Predictor => null, stepIncreaseFactor => null, Precision => null,
    tStep => null, tDegree => null, CorrectorTolerance => null,
    InfinityThreshold => null, gamma => null, Software => null,
    ResidualTolerance => null, numberSuccessesBeforeIncrease => null, Normalize
    => null, SingularConditionNumber => null, Projectivize => null, PostProcess
    => true, tStepMin => null}
  * Function: solverMLE, -- Maximum likelihood estimate of a
    loopless mixed graph
  * Option key: OptionsNAG4M2, -- optional parameter to
    set the parameters of solveSystem in NumericalAlgebraicGeometry

See also
========

  * solverMLE -- Maximum likelihood estimate of a loopless
    mixed graph
  * NumericalAlgebraicGeometry, --
    Numerical Algebraic Geometry
  * solveSystem (NumericalAlgebraicGeometry), --
    solve a system of polynomial equations

Functions with optional argument named OptionsNAG4M2:
=====================================================

  * solverMLE(...,OptionsNAG4M2=>...)
    -- use options of
    "solveSystem" in "NumericalAlgebraicGeometry"

solverMLE(...,RealPrecision=>...) -- the number of bits of precision to use in the computation
**********************************************************************************************

Synopsis
========

  * Usage:
        solverMLE(G,U,RealPrecision=>n)
  * Inputs:
      * n, an integer (Macaulay2Doc), default is 53

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

This optional input only applies when the sample data or the sample covariance
matrix has real entries. By default, the precision is 53 (the default precision
for real numbers in M2).

+-----------------------------------------------------------------------------+
|i1 : G = mixedGraph(digraph {{1,2},{1,3},{2,3},{3,4}},bigraph {{3,4}});      |
+-----------------------------------------------------------------------------+
|i2 : U = matrix{{6.2849049, 10.292875, 1.038475, 1.1845757}, {3.1938475,     |
|                                                                             |
|                4         4                                                  |
|o2 : Matrix RR    <-- RR                                                     |
|              53        53                                                   |
|-----------------------------------------------------------------------------|
|3.2573, 1.13847, 1}, {4/5, 3/2, 9/8, 3/10}, {10/7, 2/3,1, 8/3}};             |
+-----------------------------------------------------------------------------+
|i3 : solverMLE(G,U,RealPrecision=>10)                                        |
|                                                                             |
|o3 = (1.83311, | 4.52904   7.81123   -.0250185 .309951   |, 2)               |
|               | 7.81123   14.3732   -.0382332 .473665   |                   |
|               | -.0250185 -.0382332 .00337164 -.0418254 |                   |
|               | .309951   .473665   -.0418254 .742627   |                   |
|                                                                             |
|o3 : Sequence                                                                |
+-----------------------------------------------------------------------------+

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

  * Default value: 53
  * Function: solverMLE, -- Maximum likelihood estimate of a
    loopless mixed graph
  * Option key: RealPrecision, -- optional input to choose
    the number of decimals used to round to QQ when inputing data in RR

See also
========

  * scoreEquations -- score equations of the
    log-likelihood function of a Gaussian graphical model
  * solverMLE -- Maximum likelihood estimate of a loopless
    mixed graph

Functions with optional argument named RealPrecision:
=====================================================

  * scoreEquations(...,RealPrecision=>...)
    -- the number of
    bits of precision to use in the computation
  * solverMLE(...,RealPrecision=>...)
    -- the number of bits
    of precision to use in the computation

solverMLE(...,SampleData=>...) -- input sample covariance matrix instead of sample data
***************************************************************************************

Synopsis
========

  * Usage:
        solverMLE(G,U,SampleData=>b)
  * Inputs:
      * b, a Boolean value (Macaulay2Doc), default is true

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

See solverMLE, requires a matrix or a list of sample data as part
of the default input. Setting solverMLE(...,SampleData=>...),
to false allows the user to
enter a sample covariance matrix as input. It must be a symmetric matrix.

+-----------------------------------------------------+
|i1 : G=graph{{1,2},{2,3},{3,4},{1,4}}                |
|                                                     |
|o1 = Graph{1 => {2, 4}}                              |
|           2 => {1, 3}                               |
|           3 => {2, 4}                               |
|           4 => {1, 3}                               |
|                                                     |
|o1 : Graph                                           |
+-----------------------------------------------------+
|i2 : U=random(ZZ^4,ZZ^4)                             |
|                                                     |
|o2 = | 8 8 8 8 |                                     |
|     | 1 3 8 5 |                                     |
|     | 3 3 5 2 |                                     |
|     | 7 7 7 3 |                                     |
|                                                     |
|              4       4                              |
|o2 : Matrix ZZ  <-- ZZ                               |
+-----------------------------------------------------+
|i3 : solverMLE(G,U,SampleData=>true)                 |
|                                                     |
|o3 = (-5.76639, | 8.1875 6.3125  1.5433 2.625   |, 5)|
|                | 6.3125 5.1875  1.25   2.11114 |    |
|                | 1.5433 1.25    1.5    2.25    |    |
|                | 2.625  2.11114 2.25   5.25    |    |
|                                                     |
|o3 : Sequence                                        |
+-----------------------------------------------------+
|i4 : V=sampleCovarianceMatrix(U)                     |
|                                                     |
|o4 = | 131/16 101/16 3/4 21/8 |                      |
|     | 101/16 83/16  5/4 23/8 |                      |
|     | 3/4    5/4    3/2 9/4  |                      |
|     | 21/8   23/8   9/4 21/4 |                      |
|                                                     |
|              4       4                              |
|o4 : Matrix QQ  <-- QQ                               |
+-----------------------------------------------------+
|i5 : solverMLE(G,V,SampleData=>false)                |
|                                                     |
|o5 = (-5.76639, | 8.1875 6.3125  1.5433 2.625   |, 5)|
|                | 6.3125 5.1875  1.25   2.11114 |    |
|                | 1.5433 1.25    1.5    2.25    |    |
|                | 2.625  2.11114 2.25   5.25    |    |
|                                                     |
|o5 : Sequence                                        |
+-----------------------------------------------------+

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

  * Default value: true (Macaulay2Doc),
  * Function: solverMLE, -- Maximum likelihood estimate of a
    loopless mixed graph
  * Option key: SampleData, -- optional input to allow to
    input the sample covariance matrix instead of sample data

See also
========

  * scoreEquations -- score equations of the
    log-likelihood function of a Gaussian graphical model
  * solverMLE -- Maximum likelihood estimate of a loopless
    mixed graph

Functions with optional argument named SampleData:
==================================================

  * scoreEquations(...,SampleData=>...)
    -- input sample
    covariance matrix instead of sample data
  * solverMLE(...,SampleData=>...)
    -- input sample
    covariance matrix instead of sample data

solverMLE(...,Saturate=>...) -- whether to saturate
***************************************************

Synopsis
========

  * Usage:
        solverMLE(G,U,Saturate=>b)
  * Inputs:
      * b, a Boolean value (Macaulay2Doc), default is true

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

See solverMLE(...,Saturate=>...),
is set to true by default. If
we set Saturate, to false in solverMLE,
saturation will not be performed when computing the score equations of the
log-likelihood function, see scoreEquations(...,Saturate=>...).

If the ideal returned by scoreEquations, has positive
dimension, see solverMLE, gives this ideal as output.

On the other hand, if we obtain a zero-dimensional ideal in
scoreEquations, solverMLE, computes the
solutions of this polynomial system and returns:

* the maximal value of the log-likelihood function attained by positive
definite matrices corresponding to such solutions,

* the positive definite matrices where the maximum is attained,

* the degree of the zero-dimensional ideal.

Be aware that this output might not correspond to the right MLE.

+-----------------------------------------------------------------------------+
|i1 : G=graph{{1,2},{2,3},{3,4},{1,4}}                                        |
|                                                                             |
|o1 = Graph{1 => {2, 4}}                                                      |
|           2 => {1, 3}                                                       |
|           3 => {2, 4}                                                       |
|           4 => {1, 3}                                                       |
|                                                                             |
|o1 : Graph                                                                   |
+-----------------------------------------------------------------------------+
|i2 : U=random(ZZ^4,ZZ^4)                                                     |
|                                                                             |
|o2 = | 8 8 8 8 |                                                             |
|     | 1 3 8 5 |                                                             |
|     | 3 3 5 2 |                                                             |
|     | 7 7 7 3 |                                                             |
|                                                                             |
|              4       4                                                      |
|o2 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i3 : solverMLE(G,U,Saturate=>false)                                          |
|                                                                             |
|              131                   131         2     131         2          |
|o3 = ideal (- ---k   k   k   k    + ---k   k   k    + ---k   k   k    +      |
|               16 1,1 2,2 3,3 4,4    16 3,3 4,4 1,2    16 2,2 3,3 1,4        |
|     ------------------------------------------------------------------------|
|     131         2     131 2   2     131                   131         2     |
|     ---k   k   k    - ---k   k    + ---k   k   k   k    + ---k   k   k    - |
|      16 1,1 4,4 2,3    16 1,4 2,3    8  1,2 1,4 2,3 3,4    16 1,1 2,2 3,4   |
|     ------------------------------------------------------------------------|
|     131 2   2                         2          2      83                  |
|     ---k   k    + k   k   k    - k   k    - k   k   , - --k   k   k   k    +|
|      16 1,2 3,4    2,2 3,3 4,4    4,4 2,3    2,2 3,4    16 1,1 2,2 3,3 4,4  |
|     ------------------------------------------------------------------------|
|     83         2     83         2     83         2     83 2   2             |
|     --k   k   k    + --k   k   k    + --k   k   k    - --k   k    +         |
|     16 3,3 4,4 1,2   16 2,2 3,3 1,4   16 1,1 4,4 2,3   16 1,4 2,3           |
|     ------------------------------------------------------------------------|
|     83                   83         2     83 2   2                          |
|     --k   k   k   k    + --k   k   k    - --k   k    + k   k   k    -       |
|      8 1,2 1,4 2,3 3,4   16 1,1 2,2 3,4   16 1,2 3,4    1,1 3,3 4,4         |
|     ------------------------------------------------------------------------|
|          2          2      3                   3         2     3         2  |
|     k   k    - k   k   , - -k   k   k   k    + -k   k   k    + -k   k   k   |
|      3,3 1,4    1,1 3,4    2 1,1 2,2 3,3 4,4   2 3,3 4,4 1,2   2 2,2 3,3 1,4|
|     ------------------------------------------------------------------------|
|       3         2     3 2   2                         3         2           |
|     + -k   k   k    - -k   k    + 3k   k   k   k    + -k   k   k    -       |
|       2 1,1 4,4 2,3   2 1,4 2,3     1,2 1,4 2,3 3,4   2 1,1 2,2 3,4         |
|     ------------------------------------------------------------------------|
|     3 2   2                         2          2      21                    |
|     -k   k    + k   k   k    - k   k    - k   k   , - --k   k   k   k    +  |
|     2 1,2 3,4    1,1 2,2 4,4    4,4 1,2    2,2 1,4     4 1,1 2,2 3,3 4,4    |
|     ------------------------------------------------------------------------|
|     21         2     21         2     21         2     21 2   2             |
|     --k   k   k    + --k   k   k    + --k   k   k    - --k   k    +         |
|      4 3,3 4,4 1,2    4 2,2 3,3 1,4    4 1,1 4,4 2,3    4 1,4 2,3           |
|     ------------------------------------------------------------------------|
|     21                   21         2     21 2   2                          |
|     --k   k   k   k    + --k   k   k    - --k   k    + k   k   k    -       |
|      2 1,2 1,4 2,3 3,4    4 1,1 2,2 3,4    4 1,2 3,4    1,1 2,2 3,3         |
|     ------------------------------------------------------------------------|
|          2          2      101                   101         2              |
|     k   k    - k   k   , - ---k   k   k   k    + ---k   k   k    +          |
|      3,3 1,2    1,1 2,3     8  1,1 2,2 3,3 4,4    8  3,3 4,4 1,2            |
|     ------------------------------------------------------------------------|
|     101         2     101         2     101 2   2     101                   |
|     ---k   k   k    + ---k   k   k    - ---k   k    + ---k   k   k   k    + |
|      8  2,2 3,3 1,4    8  1,1 4,4 2,3    8  1,4 2,3    4  1,2 1,4 2,3 3,4   |
|     ------------------------------------------------------------------------|
|     101         2     101 2   2                                             |
|     ---k   k   k    - ---k   k    - 2k   k   k    - 2k   k   k    +         |
|      8  1,1 2,2 3,4    8  1,2 3,4     3,3 4,4 1,2     1,4 2,3 3,4           |
|     ------------------------------------------------------------------------|
|           2      21                   21         2     21         2         |
|     2k   k   , - --k   k   k   k    + --k   k   k    + --k   k   k    +     |
|       1,2 3,4     4 1,1 2,2 3,3 4,4    4 3,3 4,4 1,2    4 2,2 3,3 1,4       |
|     ------------------------------------------------------------------------|
|     21         2     21 2   2     21                   21         2         |
|     --k   k   k    - --k   k    + --k   k   k   k    + --k   k   k    -     |
|      4 1,1 4,4 2,3    4 1,4 2,3    2 1,2 1,4 2,3 3,4    4 1,1 2,2 3,4       |
|     ------------------------------------------------------------------------|
|     21 2   2                           2                                    |
|     --k   k    - 2k   k   k    + 2k   k    - 2k   k   k   , -               |
|      4 1,2 3,4     2,2 3,3 1,4     1,4 2,3     1,2 2,3 3,4                  |
|     ------------------------------------------------------------------------|
|     5                   5         2     5         2     5         2         |
|     -k   k   k   k    + -k   k   k    + -k   k   k    + -k   k   k    -     |
|     2 1,1 2,2 3,3 4,4   2 3,3 4,4 1,2   2 2,2 3,3 1,4   2 1,1 4,4 2,3       |
|     ------------------------------------------------------------------------|
|     5 2   2                         5         2     5 2   2                 |
|     -k   k    + 5k   k   k   k    + -k   k   k    - -k   k    -             |
|     2 1,4 2,3     1,2 1,4 2,3 3,4   2 1,1 2,2 3,4   2 1,2 3,4               |
|     ------------------------------------------------------------------------|
|                       2                          9                          |
|     2k   k   k    + 2k   k    - 2k   k   k   , - -k   k   k   k    +        |
|       1,1 4,4 2,3     1,4 2,3     1,2 1,4 3,4    2 1,1 2,2 3,3 4,4          |
|     ------------------------------------------------------------------------|
|     9         2     9         2     9         2     9 2   2                 |
|     -k   k   k    + -k   k   k    + -k   k   k    - -k   k    +             |
|     2 3,3 4,4 1,2   2 2,2 3,3 1,4   2 1,1 4,4 2,3   2 1,4 2,3               |
|     ------------------------------------------------------------------------|
|                         9         2     9 2   2                             |
|     9k   k   k   k    + -k   k   k    - -k   k    - 2k   k   k    -         |
|       1,2 1,4 2,3 3,4   2 1,1 2,2 3,4   2 1,2 3,4     1,2 1,4 2,3           |
|     ------------------------------------------------------------------------|
|                       2                                                     |
|     2k   k   k    + 2k   k   )                                              |
|       1,1 2,2 3,4     1,2 3,4                                               |
|                                                                             |
|o3 : Ideal of QQ[k   , k   , k   , k   , k   , k   , k   , k   ]             |
|                  1,1   2,2   3,3   4,4   1,2   1,4   2,3   3,4              |
+-----------------------------------------------------------------------------+

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

  * Default value: true (Macaulay2Doc),
  * Function: solverMLE, -- Maximum likelihood estimate of a
    loopless mixed graph
  * Option key: Saturate, -- optional input whether to saturate

See also
========

  * solverMLE -- Maximum likelihood estimate of a loopless
    mixed graph
  * scoreEquations -- score equations of the
    log-likelihood function of a Gaussian graphical model
  * scoreEquations(...,Saturate=>...)
    -- whether to saturate

Functions with optional argument named Saturate:
================================================

  * scoreEquations(...,Saturate=>...)
    -- whether to saturate
  * solverMLE(...,Saturate=>...)
    -- whether to saturate

solverMLE(...,SaturateOptions=>...) -- use options from "saturate"
******************************************************************

Synopsis
========

  * Usage:
        solverMLE(G,U,SaturateOptions=>L)
  * Inputs:
      * L, a list (Macaulay2Doc), of options to set up saturation.
        Accepts any option from the function saturate (Saturation),

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

Default SaturateOptions, in solverMLE,
are the default options in saturate (Saturation). All optional
input in saturate (Saturation), is allowed.

+-----------------------------------------------------------------------------+
|i1 : G=graph{{1,2},{2,3},{3,4},{1,4}}                                        |
|                                                                             |
|o1 = Graph{1 => {2, 4}}                                                      |
|           2 => {1, 3}                                                       |
|           3 => {2, 4}                                                       |
|           4 => {1, 3}                                                       |
|                                                                             |
|o1 : Graph                                                                   |
+-----------------------------------------------------------------------------+
|i2 : U=random(ZZ^4,ZZ^4)                                                     |
|                                                                             |
|o2 = | 8 8 8 8 |                                                             |
|     | 1 3 8 5 |                                                             |
|     | 3 3 5 2 |                                                             |
|     | 7 7 7 3 |                                                             |
|                                                                             |
|              4       4                                                      |
|o2 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i3 : solverMLE(G,U,SaturateOptions => {DegreeLimit=>1, MinimalGenerators =>  |
|                                                                             |
|o3 = (-5.76639, | 8.1875 6.3125  1.5433 2.625   |, 5)                        |
|                | 6.3125 5.1875  1.25   2.11114 |                            |
|                | 1.5433 1.25    1.5    2.25    |                            |
|                | 2.625  2.11114 2.25   5.25    |                            |
|                                                                             |
|o3 : Sequence                                                                |
|-----------------------------------------------------------------------------|
|false})                                                                      |
+-----------------------------------------------------------------------------+

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

  * Default value: new OptionTable from {Strategy => null, BasisElementLimit =>
    infinity, DegreeLimit => {}, MinimalGenerators => true, PairLimit =>
    infinity}
  * Function: solverMLE, -- Maximum likelihood estimate of a
    loopless mixed graph
  * Option key: SaturateOptions, -- optional input to
    use options "saturate"

See also
========

  * scoreEquations -- score equations of the
    log-likelihood function of a Gaussian graphical model
  * Saturate -- optional input whether to saturate
  * saturate (missing documentation)
  * solverMLE -- Maximum likelihood estimate of a loopless
    mixed graph

Functions with optional argument named SaturateOptions:
=======================================================

  * scoreEquations(...,SaturateOptions=>...)
    -- use options
    from "saturate"
  * solverMLE(...,SaturateOptions=>...)
    -- use options from
    "saturate"

solverMLE(...,Solver=>...) -- choose numerical solver
*****************************************************

Synopsis
========

  * Usage:
        solverMLE(G,U,Solver=>P)
  * Inputs:
      * P, a string (Macaulay2Doc), name of the corresponding
        package

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

This option allows to choose which numerical solver to use to estimate the
critical points. There are two options: "EigenSolver" or "NAG4M2" (Numerical
Algebraic Geometry for Macaulay2).

The default and strongly recommended option is "EigenSolver", in which case the
function zeroDimSolve (EigenSolver), is used. If "NAG4M2" is
chosen, then solveSystem (NumericalAlgebraicGeometry),
is used.

+----------------------------------------------------------------------+
|i1 : G=mixedGraph(graph{{a,b}},digraph{{a,d}},bigraph{{c,d}})         |
|                                                                      |
|o1 = MixedGraph{Bigraph => Bigraph{c => {d}}}                         |
|                                   d => {c}                           |
|                Digraph => Digraph{a => {d}}                          |
|                                   d => {}                            |
|                Graph => Graph{a => {b}}                              |
|                               b => {a}                               |
|                                                                      |
|o1 : MixedGraph                                                       |
+----------------------------------------------------------------------+
|i2 : U=matrix{{1, 2, 5, 1}, {5, 3, 2, 1}, {4, 3, 5, 10}, {2, 5,1, 3}};|
|                                                                      |
|              4       4                                               |
|o2 : Matrix ZZ  <-- ZZ                                                |
+----------------------------------------------------------------------+
|i3 : solverMLE (G,U,Solver=>"EigenSolver")                            |
|                                                                      |
|o3 = (-8.4691, | 2.5     0      0       2.26215 |, 1)                 |
|               | 0       1.1875 0       0       |                     |
|               | 0       0      3.1875  3.26493 |                     |
|               | 2.26215 0      3.26493 14.6143 |                     |
|                                                                      |
|o3 : Sequence                                                         |
+----------------------------------------------------------------------+
|i4 : solverMLE (G,U,Solver=>"NAG4M2")                                 |
|                                                                      |
|o4 = (-8.4691, | 2.5     0      0       2.26215 |, 1)                 |
|               | 0       1.1875 0       0       |                     |
|               | 0       0      3.1875  3.26493 |                     |
|               | 2.26215 0      3.26493 14.6143 |                     |
|                                                                      |
|o4 : Sequence                                                         |
+----------------------------------------------------------------------+

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

  * Default value: EigenSolver
  * Function: solverMLE, -- Maximum likelihood estimate of a
    loopless mixed graph
  * Option key: Solver, -- optional input to choose numerical
    solver

See also
========

  * solverMLE -- Maximum likelihood estimate of a loopless
    mixed graph
  * EigenSolver -- polynomial system solver via
    eigen-computations
  * NumericalAlgebraicGeometry, --
    Numerical Algebraic Geometry
  * zeroDimSolve (EigenSolver) -- zero-dimensional
    polynomial system solver
  * solveSystem (NumericalAlgebraicGeometry), --
    solve a system of polynomial equations

Functions with optional argument named Solver:
==============================================

  * solverMLE(...,Solver=>...)
    -- choose numerical solver

solverMLE(...,ZeroTolerance=>...) -- optional input to set the largest absolute value that should be treated as zero
********************************************************************************************************************

Synopsis
========

  * Usage:
        solverMLE(G,U,ZeroTolerance=>n)
  * Inputs:
      * n, a real number (Macaulay2Doc), default is 1e-10

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

After computing the variety of the zero-dimensional ideal of the score
equations, solverMLE needs to determine which points lie in the PD cone. A
matrix is assumed to be positive definite if for all eigenvalues e:

-  realPart (Macaulay2Doc), e > ZeroTolerance

-  abs (Macaulay2Doc), imaginaryPart (Macaulay2Doc),
e <= ZeroTolerance

If an MLE matrix contains an imaginary part below the tolerance level, then
only the real part is reported in the output. (See
checkPD(...,ZeroTolerance=>...))

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

  * Default value: 1e-10
  * Function: solverMLE, -- Maximum likelihood estimate of a
    loopless mixed graph
  * Option key: ZeroTolerance, -- optional input to set
    the largest absolute value that should be treated as zero

See also
========

  * checkPD -- returns positive definite matrices from a list
    of symmetric  matrices

Functions with optional argument named ZeroTolerance:
=====================================================

  * checkPD(...,ZeroTolerance=>...)
    -- optional input to set
    the largest absolute value that should be treated as zero
  * checkPSD(...,ZeroTolerance=>...)
    -- optional input to
    set the largest absolute value that should be treated as zero
  * solverMLE(...,ZeroTolerance=>...)
    -- optional input to
    set the largest absolute value that should be treated as zero

ZeroTolerance -- optional input to set the largest absolute value that should be treated as zero
************************************************************************************************

See also
========

  * checkPD -- returns positive definite matrices from a list
    of symmetric  matrices
  * checkPSD -- returns positive semidefinite matrices from a
    list of symmetric matrices
  * solverMLE -- Maximum likelihood estimate of a loopless
    mixed graph

Functions with optional argument named ZeroTolerance:
=====================================================

  * checkPD(...,ZeroTolerance=>...)
    -- optional input to set
    the largest absolute value that should be treated as zero
  * checkPSD(...,ZeroTolerance=>...)
    -- optional input to
    set the largest absolute value that should be treated as zero
  * solverMLE(...,ZeroTolerance=>...)
    -- optional input to
    set the largest absolute value that should be treated as zero

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

The object ZeroTolerance, is a symbol (Macaulay2Doc).