This is RandomMonomialIdeals.info, produced by Macaulay2, version 1.26.06

RandomMonomialIdeals -- A package for generating Erdos-Renyi-type random monomial ideals and variations
*******************************************************************************************************

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

RandomMonomialIdeals is a  package for sampling random monomial ideals from an
Erdos-Renyi-type distribution, the graded version of it, and some extensions.
It also introduces new types of objects, see Sample, and Model,
to allow for streamlined handling of random objects and their
statistics in Macaulay2. Most of the models implemented are drawn from the
paper Random Monomial Ideals by Jesus A. De Loera, Sonja Petrovic, Lily
Silverstein, Despina Stasi, and Dane Wilburne
(https://arxiv.org/abs/1701.07130).

The main method, see randomMonomialSets, generates a
sample of size $N$ from the distribution $\mathcal B(n, D, p)$ of sets of
monomials of degree at most $D$ on $n$ variables, where $p$ is the probability
of selecting any given monomial:

+-----------------------------------------------------------------------------+
|i1 : n=3; D=2; p=0.5; N=4;                                                   |
+-----------------------------------------------------------------------------+
|i5 : L = randomMonomialSets(n,D,p,N)                                         |
|                                                                             |
|                      2         2             2   2               2          |
|o5 = {{x , x , x x , x , x x , x }, {x , x , x , x }, {x , x x , x , x x ,   |
|        2   3   1 2   2   2 3   3     2   3   2   3     3   1 3   2   2 3    |
|     ------------------------------------------------------------------------|
|      2                 2         2         2                                |
|     x }, {x , x , x , x , x x , x , x x , x }}                              |
|      3     1   2   3   1   1 2   2   2 3   3                                |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+

For a formal definition of the distribution, see Section 1 of
https://arxiv.org/abs/1701.07130. As is customary, we use the word `model' when
referring to a distribution of the random objects at hand.

The model defined by $\mathcal B(n, D, p)$ was inspired by the Erdos-Renyi
random graph model denoted by $G(n,p)$: it is a natural generalization, as
squarefree monomials of degree tww can be encoded by edges of a graph whose
vertices are the variables. The random graph model can be introduced in two
ways: one can either fix the probability of an edge or fix the total number of
edges. Thus the package also includes the model variant that generates a fixed
number of monomials:

+--------------------------------------------------------------------+
|i6 : n=3; D=2; M=3; N=4;                                            |
+--------------------------------------------------------------------+
|i10 : L = randomMonomialSets(n,D,M,N)                               |
|9                                                                   |
|9                                                                   |
|9                                                                   |
|9                                                                   |
|                                                                    |
|         2       2           2                   2               2  |
|o10 = {{x , x , x }, {x x , x , x }, {x x , x , x }, {x , x x , x }}|
|         3   1   2     2 3   2   2     2 3   3   3     1   2 3   2  |
|                                                                    |
|o10 : List                                                          |
+--------------------------------------------------------------------+

To sample from the graded model from Section 6 of
https://arxiv.org/abs/1701.07130, simply replace $p$ by a list of $D$
probabilities, one for each degree. In the example below, monomials of degree 1
are not selected since their probability = 0, while each monomial of degree 2
is selected with probability 1.

+-----------------------------------------------------------------------------+
|i11 : n=3; D=2; N=4;                                                         |
+-----------------------------------------------------------------------------+
|i14 : randomMonomialSets(n,D,{0.0,1.0},N)                                    |
|                                                                             |
|         2               2         2     2               2         2     2   |
|o14 = {{x , x x , x x , x , x x , x }, {x , x x , x x , x , x x , x }, {x ,  |
|         1   1 2   1 3   2   2 3   3     1   1 2   1 3   2   2 3   3     1   |
|      -----------------------------------------------------------------------|
|                   2         2     2               2         2               |
|      x x , x x , x , x x , x }, {x , x x , x x , x , x x , x }}             |
|       1 2   1 3   2   2 3   3     1   1 2   1 3   2   2 3   3               |
|                                                                             |
|o14 : List                                                                   |
+-----------------------------------------------------------------------------+

The package also allows for sampling from the graded version of the fixed
number of monomials model, where we specify the requested number of monomials
of each degree. In the example below, we sample random sets of monomials with
one monomial of degree 1, zero of degree 2 and three monomials of degree 3.

+-----------------------------------------------------------------------------+
|i15 : n=3; D=3; N=4;                                                         |
+-----------------------------------------------------------------------------+
|i18 : randomMonomialSets(n,D,{1,0,3},N)                                      |
|                                                                             |
|             3   3     2                 3   2           3     2   2         |
|o18 = {{x , x , x , x x }, {x , x x x , x , x x }, {x , x , x x , x x }, {x ,|
|         2   3   1   1 3     1   1 2 3   1   2 3     3   2   1 3   1 3     2 |
|      -----------------------------------------------------------------------|
|       2       2     2                                                       |
|      x x , x x , x x }}                                                     |
|       2 3   2 3   1 3                                                       |
|                                                                             |
|o18 : List                                                                   |
+-----------------------------------------------------------------------------+

Finally, we can request the monomial sets generated by the graded model with a
fixed number of monomials to be minimal generating sets. We can also employ the
minimal strategy for a couple of other versions of the randomMonomialSets
method.

+-----------------------------------------------------------------------------+
|i19 : n=3; D=3; N=4;                                                         |
+-----------------------------------------------------------------------------+
|i22 : randomMonomialSets(n,D,{1,0,3},N, Strategy=>"Minimal")                 |
|                                                                             |
|             2     3     2           2   3   2           3   3   2           |
|o22 = {{x , x x , x , x x }, {x , x x , x , x x }, {x , x , x , x x }, {x ,  |
|         1   2 3   2   2 3     2   1 3   1   1 3     1   2   3   2 3     3   |
|      -----------------------------------------------------------------------|
|       3     2   3                                                           |
|      x , x x , x }}                                                         |
|       1   1 2   2                                                           |
|                                                                             |
|o22 : List                                                                   |
+-----------------------------------------------------------------------------+
|i23 : randomMonomialSets(n,D,{0.0,0.3,0.5},N, Strategy=>"Minimal")           |
|                                                                             |
|         2     2             2   3   2       3   2       2     2       2     |
|o23 = {{x , x x , x x x , x x , x , x x }, {x , x x , x x }, {x x , x x ,    |
|         1   1 2   1 2 3   1 3   2   2 3     1   1 3   1 2     1 3   1 2     |
|      -----------------------------------------------------------------------|
|               3   3                 3     2   3                             |
|      x x x , x , x }, {x x , x x , x , x x , x }}                           |
|       1 2 3   2   3     1 2   1 3   2   2 3   3                             |
|                                                                             |
|o23 : List                                                                   |
+-----------------------------------------------------------------------------+
|i24 : randomMonomialSets(n,D,0.1,N, Strategy=>"Minimal")                     |
|                                                                             |
|              2                 2   3     3     2     2                      |
|o24 = {{0}, {x , x x }, {x x , x , x }, {x , x x , x x }}                    |
|              2   2 3     1 3   2   1     1   1 3   2 3                      |
|                                                                             |
|o24 : List                                                                   |
+-----------------------------------------------------------------------------+

Once a sample (that is, a set of random objects) is generated, one can compute
various statistics of algebraic properties of the sample. The methods in the
package offer a way to compute and summarize statistics of some of the common
properties, such as degree, dimension, projective dimension,
Castelnuovo-Mumford regularity, etc. For example, we can use the method
dimStats, to get the Krull dimension statistics:

+-----------------------------------------------------------------------------+
|i25 : ideals=idealsFromGeneratingSets(L)                                     |
|                                                                             |
|                           2   2                                             |
|o25 = {monomialIdeal (x , x , x ), monomialIdeal x , monomialIdeal x ,       |
|                       1   2   3                  2                 3        |
|      -----------------------------------------------------------------------|
|                          2                                                  |
|      monomialIdeal (x , x , x x )}                                          |
|                      1   2   2 3                                            |
|                                                                             |
|o25 : List                                                                   |
+-----------------------------------------------------------------------------+
|i26 : dimStats(ideals,ShowTally=>true)                                       |
|                                                                             |
|o26 = (1.25, .829156, Tally{0 => 1})                                         |
|                            1 => 1                                           |
|                            2 => 2                                           |
|                                                                             |
|o26 : Sequence                                                               |
+-----------------------------------------------------------------------------+

The first entry in the output of the method dimStats, is the
mean Krull dimension of the sample. The second entry is the standard deviation.
Similarly, one can obtain the mean and standard deviations of the number of
minimal generators and degree complexity via mingenStats,
and the average Betti table shape, mean Betti table, and its standard deviation
via bettiStats,:

+---------------------------------------------------------------------------+
|i27 : mingenStats ideals                                                   |
|                                                                           |
|o27 = (2, 1, 1.5, .5)                                                      |
|                                                                           |
|o27 : Sequence                                                             |
+---------------------------------------------------------------------------+
|i28 : bettiStats ideals                                                    |
|                                                                           |
|              0   1   2   3         0 1    2   3         1       2       3 |
|o28 = (total: 1 1.5 .75  .5, total: 1 2  1.5  .5, total: 1 1.73205 .866025)|
|           0: 1   1   .   .      0: 1 1    .   .      1: 1 1.29904 .433013 |
|           1: .  .5  .5 .25      1: . 1 1.25 .25      2: . .433013 .433013 |
|           2: .   . .25 .25      2: . .  .25 .25                           |
|                                                                           |
|o28 : Sequence                                                             |
+---------------------------------------------------------------------------+

For developing other models and computing statistics on objects other than
monomial ideals, the package also defines two new types of object, see Model,
and Sample, which allow for convenient storage of
statistics from a sample of algebraic objects and streamlines writing sample
data into files.

For example, below we create a sample of size 10 from the Erdos-Renyi
distribution $\mathcal B(n, D, p)$ on monomials in $Q[y,w]$ with $D=4$, and
$p=0.5$, and then a sample of size 15 from the graded version of this
distribution on monomials in $Z/101[z_1..z_8]$ with $D=2$, and $p={0.25,0.5}$:

+-------------------------------------------------------------+
|i29 : sample1 = sample(ER(QQ[y,w],4,0.5),10)                 |
|                                                             |
|o29 = Sample{...4...}                                        |
|                                                             |
|o29 : Sample                                                 |
+-------------------------------------------------------------+
|i30 : sample2 = sample(ER(ZZ/101[z_1..z_8],2,{0.25,0.75}),15)|
|                                                             |
|o30 = Sample{...4...}                                        |
|                                                             |
|o30 : Sample                                                 |
+-------------------------------------------------------------+

The output is a hash table with 4 entries. To obtain the random sets of
monomials that were generated (that is, the actual data we are interested in),
use the command getData,:

+-----------------------------------------------+
|i31 : keys sample1                             |
|                                               |
|o31 = {SampleSize, ModelName, Data, Parameters}|
|                                               |
|o31 : List                                     |
+-----------------------------------------------+
|i32 : sample2.Parameters                       |
|                                               |
|        ZZ                                     |
|o32 = (---[z ..z ], 2, {.25, .75})             |
|       101  1   8                              |
|                                               |
|o32 : Sequence                                 |
+-----------------------------------------------+
|i33 : myData = getData(sample1);               |
+-----------------------------------------------+
|i34 : myData_0                                 |
|                                               |
|              2   2   3   2    3   4     3     |
|o34 = {y, w, y , w , y , y w, w , y , y*w }    |
|                                               |
|o34 : List                                     |
+-----------------------------------------------+

We can also use the object of type Sample, to calculate the mean,
standard deviation, and tally of the dimension of the ideals in the sample:

+-------------------------------------------------------------------+
|i35 : statistics(sample(ER(CC[z_1..z_8],5,0.1),100), degree@@ideal)|
|                                                                   |
|o35 = HashTable{Histogram => Tally{1 => 15 }}                      |
|                                   2 => 10                         |
|                                   3 => 5                          |
|                                   4 => 4                          |
|                                   5 => 2                          |
|                                   6 => 7                          |
|                                   7 => 8                          |
|                                   8 => 4                          |
|                                   9 => 4                          |
|                                   10 => 4                         |
|                                   12 => 2                         |
|                                   13 => 3                         |
|                                   14 => 2                         |
|                                   15 => 2                         |
|                                   16 => 2                         |
|                                   17 => 4                         |
|                                   18 => 5                         |
|                                   20 => 1                         |
|                                   21 => 5                         |
|                                   23 => 1                         |
|                                   26 => 1                         |
|                                   34 => 1                         |
|                                   36 => 1                         |
|                                   39 => 1                         |
|                                   40 => 1                         |
|                                   44 => 1                         |
|                                   81 => 1                         |
|                                   101 => 1                        |
|                                   138 => 1                        |
|                                   158 => 1                        |
|                        719                                        |
|                Mean => ---                                        |
|                         50                                        |
|                StdDev => 24.1192                                  |
|                                                                   |
|o35 : HashTable                                                    |
+-------------------------------------------------------------------+

Most of the methods in this package offer various options, such as selecting a
specific ring with which to work, or specifying variable names, coefficients,
etc. Here is a simple example:

+-----------------------------------------------------------------------------+
|i36 : R=ZZ/101[a..e];                                                        |
+-----------------------------------------------------------------------------+
|i37 : randomMonomialSets(R,D,p,N)                                            |
|                                                                             |
|                     2                            2        2   2    2    2   |
|o37 = {{a, b, c, e, a , a*b, a*c, a*e, b*c, c*d, d , d*e, e , a b, a d, a e, |
|      -----------------------------------------------------------------------|
|         2     2                   2          3   2    2    2             2  |
|      a*b , a*c , a*c*d, a*c*e, a*d , a*d*e, b , b c, b d, b e, b*c*d, b*d , |
|      -----------------------------------------------------------------------|
|                2   3     2          3     2   3           2                 |
|      b*d*e, b*e , c , c*d , c*d*e, d , d*e , e }, {a, c, a , a*b, b*c, c*e, |
|      -----------------------------------------------------------------------|
|       2        3   2    2                    2            2   2             |
|      d , d*e, a , a b, a c, a*b*d, a*b*e, a*c , a*d*e, a*e , b d, b*c*d,    |
|      -----------------------------------------------------------------------|
|                2     2   3   2      2     2   3                     2       |
|      b*c*e, b*d , b*e , c , c d, c*d , d*e , e }, {a, d, a*b, a*c, b , b*c, |
|      -----------------------------------------------------------------------|
|                           2   3   2    2                                  2 |
|      b*d, b*e, c*d, c*e, e , a , a c, a d, a*b*c, a*b*d, a*b*e, a*c*e, a*d ,|
|      -----------------------------------------------------------------------|
|                2   2    2      2            2            2   3   2      2   |
|      a*d*e, a*e , b c, b d, b*c , b*c*d, b*d , b*d*e, b*e , c , c e, c*d ,  |
|      -----------------------------------------------------------------------|
|              3        2                  2             2        2     2     |
|      c*d*e, e }, {d, a , a*b, a*c, a*e, b , b*c, c*d, d , d*e, e , a*b ,    |
|      -----------------------------------------------------------------------|
|                       2     2            2   2      2            2          |
|      a*b*d, a*b*e, a*c , a*d , a*d*e, a*e , b d, b*c , b*c*d, b*d , b*d*e,  |
|      -----------------------------------------------------------------------|
|       2    2      2     2                                                   |
|      c d, c e, c*d , d*e }}                                                 |
|                                                                             |
|o37 : List                                                                   |
+-----------------------------------------------------------------------------+
|i38 : randomMonomialSets(n,D,p,N,VariableName=>"t")                          |
|                                                                             |
|                             3   2     2       2     2   3         2   2   3 |
|o38 = {{t , t , t t , t t , t , t t , t t , t t , t t , t }, {t , t , t , t ,|
|         1   2   1 2   1 3   1   1 2   1 3   1 3   2 3   3     3   1   2   1 |
|      -----------------------------------------------------------------------|
|       2     2       2     2   3   2                 2   3   2             3 |
|      t t , t t , t t , t t , t , t t }, {t , t t , t , t , t t , t t t , t ,|
|       1 2   1 3   1 2   1 3   2   2 3     3   1 2   2   1   1 2   1 2 3   2 |
|      -----------------------------------------------------------------------|
|       3         2         2         3   2       2     2   2     3           |
|      t }, {t , t , t t , t , t t , t , t t , t t , t t , t t , t }}         |
|       3     2   1   1 3   2   2 3   1   1 2   1 2   1 3   2 3   3           |
|                                                                             |
|o38 : List                                                                   |
+-----------------------------------------------------------------------------+

In some cases, we may want to work directly with the sets of randomly chosen
monomials, while at other times it may be more convenient to pass directly to
the corresponding random monomial ideals. Both options induce the same
distribution on monomial ideals:

+-----------------------------------------------------------------------------+
|i39 : randomMonomialSets(3,4,1.0,1)                                          |
|                                                                             |
|                     2               2         2   3   2     2       2       |
|o39 = {{x , x , x , x , x x , x x , x , x x , x , x , x x , x x , x x ,      |
|         1   2   3   1   1 2   1 3   2   2 3   3   1   1 2   1 3   1 2       |
|      -----------------------------------------------------------------------|
|                 2   3   2       2   3   4   3     3     2 2   2       2 2   |
|      x x x , x x , x , x x , x x , x , x , x x , x x , x x , x x x , x x ,  |
|       1 2 3   1 3   2   2 3   2 3   3   1   1 2   1 3   1 2   1 2 3   1 3   |
|      -----------------------------------------------------------------------|
|         3     2         2     3   4   3     2 2     3   4                   |
|      x x , x x x , x x x , x x , x , x x , x x , x x , x }}                 |
|       1 2   1 2 3   1 2 3   1 3   2   2 3   2 3   2 3   3                   |
|                                                                             |
|o39 : List                                                                   |
+-----------------------------------------------------------------------------+
|i40 : monomialIdeal flatten oo                                               |
|                                                                             |
|o40 = monomialIdeal (x , x , x )                                             |
|                      1   2   3                                              |
|                                                                             |
|o40 : MonomialIdeal of QQ[x ..x ]                                            |
|                           1   3                                             |
+-----------------------------------------------------------------------------+
|i41 : randomMonomialIdeals(3,4,1.0,1)                                        |
|                                                                             |
|o41 = {monomialIdeal (x , x , x )}                                           |
|                       1   2   3                                             |
|                                                                             |
|o41 : List                                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * randomMonomialSet -- randomly generates a list of
    monomials in fixed number of variables up to a given degree
  * Verbose (Macaulay2Doc) -- an optional argument
  * sample -- generates a sample from the given model
  * model -- creates a new model for random objects with a given
    list of parameters and generating function

Authors
=======

  * Sonja Petrovic (see http://math.iit.edu/~spetrov1/ )
    <sonja.petrovic@iit.edu>
  * Despina Stasi (see http://math.iit.edu/~stasdes/ ) <stasdes@iit.edu>
  * Dane Wilburne (see http://mypages.iit.edu/~dwilburn/ )
    <dwilburn@hawk.iit.edu>
  * Tanner Zielinski (see https://www.linkedin.com/in/tannerzielinski/ )
    <tzielin1@hawk.iit.edu>
  * Daniel Kosmas (see https://www.linkedin.com/in/daniel-kosmas-03160988/ )
    <dkosmas@hawk.iit.edu>
  * Parker Joncus <pjoncus@hawk.iit.edu>
  * Richard Osborn <rosborn@hawk.iit.edu>
  * Monica Yun <myun1@hawk.iit.edu>
  * Genevieve Hummel <ghummel1@hawk.iit.edu>

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

Version 1.0 of this package was accepted for publication in volume 9 (see
https://msp.org/jsag/2019/9-1/ ) of The Journal of Software for Algebra and
Geometry (see https://msp.org/jsag/ ) on 11 April 2019, in the article Random
Monomial Ideals: a Macaulay2 package (see
https://msp.org/jsag/2019/9-1/p08.xhtml ) (DOI: 10.2140/jsag.2019.9.65 (see
https://doi.org/10.2140/jsag.2019.9.65 )). That version can be obtained from
the journal (see https://msp.org/jsag/2019/9-1/jsag-v9-n1-x08-
RandomMonomialIdeals.m2 ).

Version
=======

This documentation describes version 1.0 of RandomMonomialIdeals, released
January 28, 2019.

Citation
========

If you have used this package in your research, please cite it as follows:

+-----------------------------------------------------------------------------+
|@misc{RandomMonomialIdealsSource,                                            |
|  title = {{RandomMonomialIdeals: Erdos-Renyi-type random monomial ideals.   |
|  author = {Sonja Petrovic and Despina Stasi and Dane Wilburne and Tanner    |
|  howpublished = {A \emph{Macaulay2} package available at                    |
|    \url{https://github.com/Macaulay2/M2/tree/stable/M2/Macaulay2/packages   |
|}                                                                            |
|                                                                             |
|@article{RandomMonomialIdealsArticle,                                        |
|  title = {{Random Monomial Ideals: a \emph{Macaulay2} package}},            |
|  author = {Sonja Petrovic and Despina Stasi and Dane Wilburne and Tanner    |
|  journal = {The Journal of Software for Algebra and Geometry},              |
|  volume = {9},                                                              |
|  year = {2019},                                                             |
|}                                                                            |
|-----------------------------------------------------------------------------|
| Version~1.0}},                                                              |
|Zielinski and Daniel Kosmas and Parker Joncus and Richard Osborn and Monica  |
|                                                                             |
|}}                                                                           |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|Zielinski and Daniel Kosmas and Parker Joncus and Richard Osborn and Monica  |
|-----------------------------------------------------------------------------|
|Yun and Genevieve Hummel},                                                   |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|Yun and Genevieve Hummel},                                                   |
+-----------------------------------------------------------------------------+

Exports
=======

  * Types
      * Model -- a type used to store a statistical model and its
        parameters
      * Sample -- a type used to store a data sample from a
        statistical model
  * Functions and commands
      * bettiStats -- statistics on Betti tables of a sample
        of monomial ideals or list of objects
      * borelFixedStats -- fraction of Borel-fixed
        monomial ideals in the given list
      * CMStats -- fraction of monomial ideals (or other
        objects) in the given list whose quotient ring is Cohen-Macaulay
      * degStats -- statistics on the degrees of a list of
        objects
      * dimStats -- statistics on the Krull dimension of a
        list of objects
      * ER -- model for sampling from Erdos-Renyi type distributions
        on monomials
      * getData -- get the underlying samples
      * idealsFromGeneratingSets -- creates
        ideals from sets of monomials
      * mingenStats -- statistics on the minimal generators
        of a list of ideals: number and degree complexity
      * model -- creates a new model for random objects with a
        given list of parameters and generating function
      * pdimStats -- statistics on projective dimension of a
        list of objects
      * randomMonomialIdeals -- generates random
        sets of monomial ideals
      * randomMonomialSet -- randomly generates a
        list of monomials in fixed number of variables up to a given degree
      * randomMonomialSets -- randomly generates
        lists of monomials in fixed number of variables up to a given degree
      * regStats -- statistics on the regularities of a list
        of objects
      * sample -- generates a sample from the given model
      * statistics -- generate statistics for a sample
      * writeSample -- write sample data to a directory
  * Methods
      * "bettiStats(List)" -- see bettiStats, -- statistics
        on Betti tables of a sample of monomial ideals or list of objects
      * "borelFixedStats(List)" -- see borelFixedStats,
        -- fraction of Borel-fixed monomial ideals in the given list
      * "CMStats(List)" -- see CMStats, -- fraction of monomial
        ideals (or other objects) in the given list whose quotient ring is
        Cohen-Macaulay
      * "degStats(List)" -- see degStats, -- statistics on the
        degrees of a list of objects
      * "dimStats(List)" -- see dimStats, -- statistics on the
        Krull dimension of a list of objects
      * ER(PolynomialRing,ZZ,List),
        -- Graded Erdos-Renyi type distribution on monomials over (R,D,L)
      * ER(PolynomialRing,ZZ,RR), --
        Erdos-Renyi type distribution on monomials over (R,D,p)
      * ER(PolynomialRing,ZZ,ZZ), --
        Erdos-Renyi type distribution on monomials over (R,D,M)
      * ER(ZZ,ZZ,List) -- Graded Erdos-Renyi
        type distribution on monomials over (n,D,L)
      * ER(ZZ,ZZ,RR) -- Erdos-Renyi type
        distribution on monomials over (n,D,p)
      * ER(ZZ,ZZ,ZZ) -- Erdos-Renyi type
        distribution on monomials over (n,D,M)
      * "getData(Sample)" -- see getData, -- get the underlying
        samples
      * "idealsFromGeneratingSets(List)" -- see idealsFromGeneratingSets,
        -- creates ideals from sets of monomials
      * "mingenStats(List)" -- see mingenStats, --
        statistics on the minimal generators of a list of ideals: number and
        degree complexity
      * "model(List,FunctionClosure,String)" -- see model, --
        creates a new model for random objects with a given list of parameters
        and generating function
      * "pdimStats(List)" -- see pdimStats, -- statistics on
        projective dimension of a list of objects
      * "randomMonomialIdeals(ZZ,ZZ,List,ZZ)" -- see
        randomMonomialIdeals, -- generates random sets of
        monomial ideals
      * "randomMonomialIdeals(ZZ,ZZ,RR,ZZ)" -- see randomMonomialIdeals,
        -- generates random sets of monomial ideals
      * "randomMonomialIdeals(ZZ,ZZ,ZZ,ZZ)" -- see randomMonomialIdeals,
        -- generates random sets of monomial ideals
      * "randomMonomialSet(PolynomialRing,ZZ,List)" -- see
        randomMonomialSet, -- randomly generates a list of
        monomials in fixed number of variables up to a given degree
      * "randomMonomialSet(PolynomialRing,ZZ,RR)" -- see
        randomMonomialSet, -- randomly generates a list of
        monomials in fixed number of variables up to a given degree
      * "randomMonomialSet(PolynomialRing,ZZ,ZZ)" -- see
        randomMonomialSet, -- randomly generates a list of
        monomials in fixed number of variables up to a given degree
      * "randomMonomialSet(ZZ,ZZ,List)" -- see randomMonomialSet,
        -- randomly generates a list of monomials in fixed
        number of variables up to a given degree
      * "randomMonomialSet(ZZ,ZZ,RR)" -- see randomMonomialSet,
        -- randomly generates a list of monomials in fixed
        number of variables up to a given degree
      * "randomMonomialSet(ZZ,ZZ,ZZ)" -- see randomMonomialSet,
        -- randomly generates a list of monomials in fixed
        number of variables up to a given degree
      * "randomMonomialSets(PolynomialRing,ZZ,List,ZZ)" -- see
        randomMonomialSets, -- randomly generates lists of
        monomials in fixed number of variables up to a given degree
      * "randomMonomialSets(PolynomialRing,ZZ,RR,ZZ)" -- see
        randomMonomialSets, -- randomly generates lists of
        monomials in fixed number of variables up to a given degree
      * "randomMonomialSets(PolynomialRing,ZZ,ZZ,ZZ)" -- see
        randomMonomialSets, -- randomly generates lists of
        monomials in fixed number of variables up to a given degree
      * "randomMonomialSets(ZZ,ZZ,List,ZZ)" -- see randomMonomialSets,
        -- randomly generates lists of monomials in fixed
        number of variables up to a given degree
      * "randomMonomialSets(ZZ,ZZ,RR,ZZ)" -- see randomMonomialSets,
        -- randomly generates lists of monomials in fixed
        number of variables up to a given degree
      * "randomMonomialSets(ZZ,ZZ,ZZ,ZZ)" -- see randomMonomialSets,
        -- randomly generates lists of monomials in fixed
        number of variables up to a given degree
      * "regStats(List)" -- see regStats, -- statistics on the
        regularities of a list of objects
      * "sample(Model,ZZ)" -- see sample, -- generates a sample
        from the given model
      * sample(String) -- creates an object of type
        Sample from a sample stored in a directory on disk
      * "statistics(Sample,Function)" -- see statistics, --
        generate statistics for a sample
      * "writeSample(Sample,String)" -- see writeSample, --
        write sample data to a directory
  * Symbols
      * Coefficients -- optional input to choose the
        coefficients of the ambient polynomial ring
      * CountPure -- optional input to show the number of
        objects in the list whose Betti tables are pure
      * Generate -- model construct function
      * Histogram -- a summary statistic for a list of
        objects
      * IncludeZeroIdeals -- optional input to choose
        whether zero ideals should be included
      * Mean -- a summary statistic for a list of objects
      * ModelName -- name of the model used to generate a
        given sample
      * Parameters -- values of the model parameters that
        were used to generate a given sample
      * SampleSize -- size of the random sample
      * SaveBettis -- optional input to store all Betti
        tables computed
      * ShowTally -- optional input to choose if the tally is
        to be returned
      * StdDev -- a summary statistic for a list of objects
      * VariableName -- optional input to choose the
        indexed variable name for the polynomial ring

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

The object RandomMonomialIdeals, is a package (Macaulay2Doc),
defined in RandomMonomialIdeals.m2.

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:835:0.

bettiStats -- statistics on Betti tables of a sample of monomial ideals or list of objects
******************************************************************************************

  * Usage:
        bettiStats(List)
  * Inputs:
      * L, a list (Macaulay2Doc), of objects of type
        MonomialIdeal (Macaulay2Doc), or any objects to which
        betti (Macaulay2Doc), freeResolution (Complexes),
        can be applied.
  * Optional inputs (Macaulay2Doc),:
      * CountPure, => ..., default value false, optional input
        to show the number of objects in the list whose Betti tables are pure
      * IncludeZeroIdeals, => ..., default value true,
        optional input to choose whether zero ideals should be included
      * SaveBettis, => ..., default value "", optional input
        to store all Betti tables computed
      * Verbose, => ...,
        default value false, optional input to request verbose feedback
  * Outputs:
      * a sequence (Macaulay2Doc), of objects of type
        BettiTally (Macaulay2Doc), representing the mean Betti
        table shape and the mean Betti table of the elements in the list L.

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

For a sample of ideals stored as a list, this function computes some basic
Betti table statistics of the sample. Namely, it computes the average shape of
the Betti tables (where 1 is recorded in entry (ij) for each element if
$beta_{ij}$ is not zero), and it also computes the average Betti table (that
is, the table whose (ij) entry is the mean value of $beta_{ij}$ for all ideals
in the sample).

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a..e];                                                       |
+-----------------------------------------------------------------------------+
|i2 : L={monomialIdeal"a2b,bc", monomialIdeal"ab,bc3",monomialIdeal"ab,ac,bd,b|
|                                                                             |
|                      2                                3                   3 |
|o2 = {monomialIdeal (a b, b*c), monomialIdeal (a*b, b*c ), monomialIdeal (a ,|
|     ------------------------------------------------------------------------|
|           3        3             3                  3                       |
|     a*b, b , a*c, c , b*d, c*d, d , a*e, b*e, c*e, e )}                     |
|                                                                             |
|o2 : List                                                                    |
|-----------------------------------------------------------------------------|
|e,ae,cd,ce,a3,b3,c3,d3,e3"}                                                  |
+-----------------------------------------------------------------------------+
|i3 : (meanBettiShape,meanBetti,stdDevBetti) = bettiStats L;                  |
+-----------------------------------------------------------------------------+
|i4 : meanBettiShape                                                          |
|                                                                             |
|            0       1       2       3       4       5                        |
|o4 = total: 1       2       2 1.33333 1.33333 .333333                        |
|         0: 1       .       .       .       .       .                        |
|         1: .       1 .333333 .333333 .333333       .                        |
|         2: . .666667 .666667 .333333 .333333       .                        |
|         3: . .333333 .666667 .333333 .333333       .                        |
|         4: .       . .333333 .333333 .333333 .333333                        |
|                                                                             |
|o4 : BettiTally                                                              |
+-----------------------------------------------------------------------------+
|i5 : meanBetti                                                               |
|                                                                             |
|            0       1       2       3       4 5                              |
|o5 = total: 1 5.33333 10.3333      10       5 1                              |
|         0: 1       .       .       .       . .                              |
|         1: .       3 3.66667       2 .333333 .                              |
|         2: .       2       5 4.33333 1.33333 .                              |
|         3: . .333333 .666667 .666667 .333333 .                              |
|         4: .       .       1       3       3 1                              |
|                                                                             |
|o5 : BettiTally                                                              |
+-----------------------------------------------------------------------------+
|i6 : stdDevBetti                                                             |
|                                                                             |
|                  1       2       3       4       5                          |
|o6 = total: 5.46008 13.4481 14.1421 7.07107 1.41421                          |
|         1: 2.82843 5.18545 2.82843 .471405       .                          |
|         2: 2.16025 6.37704 6.12826 1.88562       .                          |
|         3: .471405 .471405 .942809 .471405       .                          |
|         4:       . 1.41421 4.24264 4.24264 1.41421                          |
|                                                                             |
|o6 : BettiTally                                                              |
+-----------------------------------------------------------------------------+

For sample size $N$, the average Betti table shape considers nonzero Betti
numbers. It is to be interpreted as follows: entry (i,j) encodes the following
sum of indicators: $\sum_{all ideals} 1_{beta_{ij}>0} / N$; that is, the
proportion of ideals with a nonzero $beta_{ij}$. Thus an entry of 0.33 means
33% of ideals have a non-zero Betti number there.

+---------------------------------------------------------+
|i7 : apply(L,i->betti res i)                             |
|                                                         |
|             0 1 2         0 1 2         0  1  2  3  4 5 |
|o7 = {total: 1 2 1, total: 1 2 1, total: 1 12 29 30 15 3}|
|          0: 1 . .      0: 1 . .      0: 1  .  .  .  . . |
|          1: . 1 .      1: . 1 .      1: .  7 11  6  1 . |
|          2: . 1 1      2: . . .      2: .  5 14 13  4 . |
|                        3: . 1 1      3: .  .  1  2  1 . |
|                                      4: .  .  3  9  9 3 |
|                                                         |
|o7 : List                                                |
+---------------------------------------------------------+
|i8 : meanBettiShape                                      |
|                                                         |
|            0       1       2       3       4       5    |
|o8 = total: 1       2       2 1.33333 1.33333 .333333    |
|         0: 1       .       .       .       .       .    |
|         1: .       1 .333333 .333333 .333333       .    |
|         2: . .666667 .666667 .333333 .333333       .    |
|         3: . .333333 .666667 .333333 .333333       .    |
|         4: .       . .333333 .333333 .333333 .333333    |
|                                                         |
|o8 : BettiTally                                          |
+---------------------------------------------------------+

For sample size $N$, the average Betti table is to be interpreted as follows:
entry $(i,j)$ encodes  $\sum_{I\in ideals}beta_{ij}(R/I) / N$:

+---------------------------------------------------------+
|i9 : apply(L,i->betti res i)                             |
|                                                         |
|             0 1 2         0 1 2         0  1  2  3  4 5 |
|o9 = {total: 1 2 1, total: 1 2 1, total: 1 12 29 30 15 3}|
|          0: 1 . .      0: 1 . .      0: 1  .  .  .  . . |
|          1: . 1 .      1: . 1 .      1: .  7 11  6  1 . |
|          2: . 1 1      2: . . .      2: .  5 14 13  4 . |
|                        3: . 1 1      3: .  .  1  2  1 . |
|                                      4: .  .  3  9  9 3 |
|                                                         |
|o9 : List                                                |
+---------------------------------------------------------+
|i10 : meanBetti                                          |
|                                                         |
|             0       1       2       3       4 5         |
|o10 = total: 1 5.33333 10.3333      10       5 1         |
|          0: 1       .       .       .       . .         |
|          1: .       3 3.66667       2 .333333 .         |
|          2: .       2       5 4.33333 1.33333 .         |
|          3: . .333333 .666667 .666667 .333333 .         |
|          4: .       .       1       3       3 1         |
|                                                         |
|o10 : BettiTally                                         |
+---------------------------------------------------------+

Ways to use bettiStats:
=======================

  * "bettiStats(List)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:924:0.

borelFixedStats -- fraction of Borel-fixed monomial ideals in the given list
****************************************************************************

  * Usage:
        borelFixedStats(List)
  * Inputs:
      * ideals, a list (Macaulay2Doc), of objects of type
        MonomialIdeal (Macaulay2Doc), or any type to which
        isBorel (Macaulay2Doc), can be applied
  * Optional inputs (Macaulay2Doc),:
      * Verbose, => ...,
        default value false, optional input to request verbose feedback
  * Outputs:
      * a rational number (Macaulay2Doc), the fraction of Borel-fixed
        monomial ideals in the list

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

The function computes the fraction of Borel-fixed ideals in the list of
monomial ideals.

+---------------------------------------------------------+
|i1 : R=ZZ/101[a,b,c];                                    |
+---------------------------------------------------------+
|i2 : ideals = {monomialIdeal"a3", monomialIdeal"a3,b,ac"}|
|                                                         |
|                     3                  3                |
|o2 = {monomialIdeal a , monomialIdeal (a , b, a*c)}      |
|                                                         |
|o2 : List                                                |
+---------------------------------------------------------+
|i3 : borelFixedStats(ideals)                             |
|                                                         |
|     1                                                   |
|o3 = -                                                   |
|     2                                                   |
|                                                         |
|o3 : QQ                                                  |
+---------------------------------------------------------+

Ways to use borelFixedStats:
============================

  * "borelFixedStats(List)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1558:0.

CMStats -- fraction of monomial ideals (or other objects) in the given list whose quotient ring is Cohen-Macaulay
*****************************************************************************************************************

  * Usage:
        CMStats(List)
  * Inputs:
      * ideals, a list (Macaulay2Doc), of objects of type
        MonomialIdeal (Macaulay2Doc), or any type to which
        isCM (Depth), can be applied
  * Optional inputs (Macaulay2Doc),:
      * Verbose, => ...,
        default value false, optional input to request verbose feedback
  * Outputs:
      * a rational number (Macaulay2Doc), the fraction of
        Cohen-Macaulay ideals in the list

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

The function checks whether the coordinate ring of each ideal in the given
sample is arithmetically Cohen-Macaulay and returns the proportion that are.

+--------------------------------------------------------------+
|i1 : R=ZZ/101[a,b,c];                                         |
+--------------------------------------------------------------+
|i2 : ideals = {monomialIdeal"a3,b,c2", monomialIdeal"a3,b,ac"}|
|                                                              |
|                      3      2                   3            |
|o2 = {monomialIdeal (a , b, c ), monomialIdeal (a , b, a*c)}  |
|                                                              |
|o2 : List                                                     |
+--------------------------------------------------------------+
|i3 : CMStats(ideals)                                          |
|                                                              |
|     1                                                        |
|o3 = -                                                        |
|     2                                                        |
|                                                              |
|o3 : QQ                                                       |
+--------------------------------------------------------------+

Ways to use CMStats:
====================

  * "CMStats(List)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1535:0.

Coefficients -- optional input to choose the coefficients of the ambient polynomial ring
****************************************************************************************

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

Put Coefficients => r for a choice of the ground field r as an argument in the
function randomMonomialSet, or
randomMonomialSets.

+--------------------------------------------------+
|i1 : n=2; D=3; p=0.2;                             |
+--------------------------------------------------+
|i4 : randomMonomialSet(n,D,p)                     |
|                                                  |
|       2   2     3                                |
|o4 = {x , x x , x }                               |
|       1   1 2   2                                |
|                                                  |
|o4 : List                                         |
+--------------------------------------------------+
|i5 : ring ideal oo                                |
|                                                  |
|o5 = QQ[x ..x ]                                   |
|         1   2                                    |
|                                                  |
|o5 : PolynomialRing                               |
+--------------------------------------------------+
|i6 : randomMonomialSet(n,D,p,Coefficients=>ZZ/101)|
|                                                  |
|       2                                          |
|o6 = {x x }                                       |
|       1 2                                        |
|                                                  |
|o6 : List                                         |
+--------------------------------------------------+
|i7 : ring ideal oo                                |
|                                                  |
|      ZZ                                          |
|o7 = ---[x ..x ]                                  |
|     101  1   2                                   |
|                                                  |
|o7 : PolynomialRing                               |
+--------------------------------------------------+

See also
========

  * randomMonomialSet -- randomly generates a list of
    monomials in fixed number of variables up to a given degree
  * randomMonomialSets -- randomly generates lists
    of monomials in fixed number of variables up to a given degree
  * randomMonomialIdeals -- generates random sets
    of monomial ideals

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

  * "randomMonomialIdeals(...,Coefficients=>...)"
  * "randomMonomialSet(...,Coefficients=>...)"
  * "randomMonomialSets(...,Coefficients=>...)"

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

The object Coefficients, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1280:0.

CountPure -- optional input to show the number of objects in the list whose Betti tables are pure
*************************************************************************************************

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

Putting the option CountPure => true in function bettiStats,
adds the number of pure Betti tables to the Betti table statistics. In the
following example, exactly one of the ideals has a pure Betti table:

+----------------------------------------------------------------------------+
|i1 : ZZ/101[a..c];                                                          |
+----------------------------------------------------------------------------+
|i2 : L={monomialIdeal"ab,bc", monomialIdeal"ab,bc3"}                        |
|                                                                            |
|                                                       3                    |
|o2 = {monomialIdeal (a*b, b*c), monomialIdeal (a*b, b*c )}                  |
|                                                                            |
|o2 : List                                                                   |
+----------------------------------------------------------------------------+
|i3 : (meanShape,meanBetti,stdevBetti,pure) = bettiStats (L,CountPure=>true);|
+----------------------------------------------------------------------------+
|i4 : pure                                                                   |
|                                                                            |
|o4 = 1                                                                      |
+----------------------------------------------------------------------------+

See also
========

  * bettiStats -- statistics on Betti tables of a sample of
    monomial ideals or list of objects
  * SaveBettis -- optional input to store all Betti tables
    computed
  * Verbose (Macaulay2Doc) -- an optional argument
  * IncludeZeroIdeals -- optional input to choose
    whether zero ideals should be included

Functions with optional argument named CountPure:
=================================================

  * "bettiStats(...,CountPure=>...)"

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

The object CountPure, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:967:0.

degStats -- statistics on the degrees of a list of objects
**********************************************************

  * Usage:
        degStats(List)
  * Inputs:
      * ideals, a list (Macaulay2Doc), of objects of type
        MonomialIdeal (Macaulay2Doc), or any objects to which
        degree (Macaulay2Doc), can be applied.
  * Optional inputs (Macaulay2Doc),:
      * ShowTally, => ..., default value false, optional input
        to choose if the tally is to be returned
      * Verbose, => ...,
        default value false, optional input to request verbose feedback
  * Outputs:
      * a sequence (Macaulay2Doc), whose first entry is the
        average degree of a list of monomial ideals, second entry is the
        standard deviation of the degree, and third entry (if option turned on)
        is the degree tally

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

This function computes the degree of $R/I$ for each ideal $I$ in the list and
computes the mean and standard deviation of the degrees.

+--------------------------------------------------------------+
|i1 : R=ZZ/101[a,b,c];                                         |
+--------------------------------------------------------------+
|i2 : ideals = {monomialIdeal"a3,b,c2", monomialIdeal"a3,b,ac"}|
|                                                              |
|                      3      2                   3            |
|o2 = {monomialIdeal (a , b, c ), monomialIdeal (a , b, a*c)}  |
|                                                              |
|o2 : List                                                     |
+--------------------------------------------------------------+
|i3 : degStats(ideals)                                         |
|                                                              |
|o3 = (3.5, 2.5)                                               |
|                                                              |
|o3 : Sequence                                                 |
+--------------------------------------------------------------+

The following examples use the existing functions randomMonomialSets,
and idealsFromGeneratingSets,
or randomMonomialIdeals,
to automatically generate a list of ideals, rather than creating the list
manually:

+-----------------------------------------------------------------------------+
|i4 : ideals = idealsFromGeneratingSets(randomMonomialSets(4,3,1.0,3))        |
|                                                                             |
|o4 = {monomialIdeal (x , x , x , x ), monomialIdeal (x , x , x , x ),        |
|                      1   2   3   4                   1   2   3   4          |
|     ------------------------------------------------------------------------|
|     monomialIdeal (x , x , x , x )}                                         |
|                     1   2   3   4                                           |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : degStats(ideals)                                                        |
|                                                                             |
|o5 = (1, 0)                                                                  |
|                                                                             |
|o5 : Sequence                                                                |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
|i6 : ideals = randomMonomialIdeals(4,3,1.0,3)                                |
|                                                                             |
|o6 = {monomialIdeal (x , x , x , x ), monomialIdeal (x , x , x , x ),        |
|                      1   2   3   4                   1   2   3   4          |
|     ------------------------------------------------------------------------|
|     monomialIdeal (x , x , x , x )}                                         |
|                     1   2   3   4                                           |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+
|i7 : degStats(ideals)                                                        |
|                                                                             |
|o7 = (1, 0)                                                                  |
|                                                                             |
|o7 : Sequence                                                                |
+-----------------------------------------------------------------------------+

Note that this function can be run with a list of any objects to which
degree (Macaulay2Doc), can be applied.

Ways to use degStats:
=====================

  * "degStats(List)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1001:0.

degStats(...,Verbose=>...) -- optional input to request verbose feedback
************************************************************************

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

Some of the functions that use this option by default exclude zero ideals when
computing statistics on a set of ideals, while others do not. If Verbose =>
true, then the functions will display this type of additional informational.
The default value is false.

+-----------------------------------------------------------+
|i1 : n=3;D=3;p=0.0;N=3;                                    |
+-----------------------------------------------------------+
|i5 : ideals = randomMonomialIdeals(n,D,p,N)                |
|                                                           |
|o5 = {monomialIdeal (), monomialIdeal (), monomialIdeal ()}|
|                                                           |
|o5 : List                                                  |
+-----------------------------------------------------------+
|i6 : regStats(ideals)                                      |
|                                                           |
|o6 = (-infinity, 0)                                        |
|                                                           |
|o6 : Sequence                                              |
+-----------------------------------------------------------+
|i7 : CMStats(ideals)                                       |
|                                                           |
|o7 = 1                                                     |
|                                                           |
|o7 : QQ                                                    |
+-----------------------------------------------------------+

In the examples above, one may wonder, for example, why 3 out of 3 ideals in
the list are Cohen-Macaulay. In order to view the additional information, set
Verbose => true:

+-----------------------------------------------------------------------------+
|i8 : regStats(ideals, Verbose => true)                                       |
|All ideals in this list are the zero ideal.                                  |
|                                                                             |
|o8 = (-infinity, 0)                                                          |
|                                                                             |
|o8 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i9 : CMStats(ideals, Verbose => true)                                        |
|There are 3 ideals in this sample. Of those, 3 are the zero ideal.           |
|The zero ideals are included in the reported count of Cohen-Macaulay quotient|
|3 out of 3 ideals in the given sample are Cohen-Macaulay.                    |
|                                                                             |
|o9 = 1                                                                       |
|                                                                             |
|o9 : QQ                                                                      |
|-----------------------------------------------------------------------------|
|rings.                                                                       |
+-----------------------------------------------------------------------------+

Other functions that have this option are as follows. Let us look at a list of
nontrivial ideals to see more interesting statistics.

+-----------------------------------------------------------------------------+
|i10 : n=3;D=3;p=0.1;N=3;                                                     |
+-----------------------------------------------------------------------------+
|i14 : ideals = randomMonomialIdeals(n,D,p,N)                                 |
|                                                                             |
|                           3                                                 |
|o14 = {monomialIdeal (x , x , x ), monomialIdeal (), monomialIdeal (x x ,    |
|                       1   2   3                                     2 3     |
|      -----------------------------------------------------------------------|
|       2                                                                     |
|      x )}                                                                   |
|       3                                                                     |
|                                                                             |
|o14 : List                                                                   |
+-----------------------------------------------------------------------------+
|i15 : regStats(ideals, Verbose => true)                                      |
|There are 3 ideals in this sample. Of those, 1 are the zero ideal.           |
|The zero ideals were extracted from the sample before reporting the          |
|                                                                             |
|o15 = (2.5, .5)                                                              |
|                                                                             |
|o15 : Sequence                                                               |
|-----------------------------------------------------------------------------|
|regularity statistics.                                                       |
+-----------------------------------------------------------------------------+
|i16 : CMStats(ideals, Verbose => true)                                       |
|There are 3 ideals in this sample. Of those, 1 are the zero ideal.           |
|The zero ideals are included in the reported count of Cohen-Macaulay quotient|
|2 out of 3 ideals in the given sample are Cohen-Macaulay.                    |
|                                                                             |
|      2                                                                      |
|o16 = -                                                                      |
|      3                                                                      |
|                                                                             |
|o16 : QQ                                                                     |
|-----------------------------------------------------------------------------|
|rings.                                                                       |
+-----------------------------------------------------------------------------+
|i17 : degStats(ideals, Verbose => true)                                      |
|There are 3 ideals in this sample. Of those, 1 are the zero ideal.           |
|The degree statistics do include those for the zero ideals.                  |
|                                                                             |
|o17 = (1.66667, .942809)                                                     |
|                                                                             |
|o17 : Sequence                                                               |
+-----------------------------------------------------------------------------+
|i18 : dimStats(ideals, Verbose=>true)                                        |
|There are 3 ideals in this sample. Of those, 1 are the zero ideal.           |
|The Krull dimension statistics do include those for the zero ideals.         |
|                                                                             |
|o18 = (1.66667, 1.24722)                                                     |
|                                                                             |
|o18 : Sequence                                                               |
+-----------------------------------------------------------------------------+
|i19 : borelFixedStats(ideals, Verbose => true)                               |
|There are 3 ideals in this sample. Of those, 1 are the zero ideal.           |
|The zero ideals are included in the reported count of Borel-fixed monomial   |
|1 out of 3 monomial ideals in the given sample are Borel-fixed.              |
|                                                                             |
|      1                                                                      |
|o19 = -                                                                      |
|      3                                                                      |
|                                                                             |
|o19 : QQ                                                                     |
|-----------------------------------------------------------------------------|
|ideals.                                                                      |
+-----------------------------------------------------------------------------+
|i20 : mingenStats(ideals, Verbose=>true)                                     |
|There are 3 ideals in this sample. Of those, 1 are the zero ideal.           |
|The statistics returned (mean and standard deviation of # of min gens and    |
|                                                                             |
|o20 = (2.5, .5, 2.5, .5)                                                     |
|                                                                             |
|o20 : Sequence                                                               |
|-----------------------------------------------------------------------------|
|mean and standard deviation of degree complexity) do NOT include those for   |
|-----------------------------------------------------------------------------|
|the zero ideals.                                                             |
+-----------------------------------------------------------------------------+
|i21 : bettiStats(ideals, Verbose => true)                                    |
|There are 3 ideals in this sample. Of those, 1 are the zero ideal.           |
|The Betti statistics do include those for the zero ideals.                   |
|                                                                             |
|              0       1       2       3         0       1       2       3    |
|o21 = (total: 1       1       1 .333333, total: 1 1.66667 1.33333 .333333,   |
|           0: 1 .333333 .333333       .      0: 1 .666667 .333333       .    |
|           1: . .333333 .333333       .      1: . .666667 .333333       .    |
|           2: . .333333 .333333 .333333      2: . .333333 .666667 .333333    |
|      -----------------------------------------------------------------------|
|                   1       2       3                                         |
|      total: 2.35702 1.88562 .471405)                                        |
|          0: .942809 .471405       .                                         |
|          1: .942809 .471405       .                                         |
|          2: .471405 .942809 .471405                                         |
|                                                                             |
|o21 : Sequence                                                               |
+-----------------------------------------------------------------------------+
|i22 : M = randomMonomialSets(n,D,p,N);                                       |
+-----------------------------------------------------------------------------+
|i23 : idealsFromGeneratingSets(M, Verbose => true)                           |
|There are 3 ideals in this sample. Of those, 1 are the zero ideal.           |
|                                                                             |
|                             2                                               |
|o23 = {monomialIdeal (x x , x ), monomialIdeal (), monomialIdeal(x x )}      |
|                       1 2   3                                    2 3        |
|                                                                             |
|o23 : List                                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * degStats -- statistics on the degrees of a list of objects
  * pdimStats -- statistics on projective dimension of a list
    of objects
  * dimStats -- statistics on the Krull dimension of a list of
    objects
  * idealsFromGeneratingSets -- creates ideals
    from sets of monomials
  * regStats -- statistics on the regularities of a list of
    objects
  * CMStats -- fraction of monomial ideals (or other objects)
    in the given list whose quotient ring is Cohen-Macaulay
  * borelFixedStats -- fraction of Borel-fixed monomial
    ideals in the given list
  * mingenStats -- statistics on the minimal generators of
    a list of ideals: number and degree complexity

Functions with optional argument named Verbose:
===============================================

  * "check(...,Verbose=>...)" -- see check (Macaulay2Doc), --
    perform tests of a package
  * "copyDirectory(...,Verbose=>...)" -- see
    copyDirectory(String,String) (Macaulay2Doc),
  * "copyFile(...,Verbose=>...)" -- see copyFile(String,String) (Macaulay2Doc),
  * "bettiStats(...,Verbose=>...)"
  * "borelFixedStats(...,Verbose=>...)"
  * "CMStats(...,Verbose=>...)"
  * degStats(...,Verbose=>...)
    -- optional input to request
    verbose feedback
  * "dimStats(...,Verbose=>...)"
  * "idealsFromGeneratingSets(...,Verbose=>...)"
  * "mingenStats(...,Verbose=>...)"
  * "pdimStats(...,Verbose=>...)"
  * "regStats(...,Verbose=>...)"
  * "findProgram(...,Verbose=>...)" -- see findProgram (Macaulay2Doc),
    -- load external program
  * "installPackage(...,Verbose=>...)" -- see installPackage (Macaulay2Doc),
    -- load and install a package and its
    documentation
  * "moveFile(...,Verbose=>...)" -- see moveFile(String,String) (Macaulay2Doc),
  * "runProgram(...,Verbose=>...)" -- see runProgram (Macaulay2Doc),
    -- run an external program
  * "symlinkDirectory(...,Verbose=>...)" -- see
    symlinkDirectory(String,String) (Macaulay2Doc),
    -- make symbolic links
    for all files in a directory tree

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

  * Default value: false (Macaulay2Doc),
  * Function: degStats, -- statistics on the degrees of a list
    of objects
  * Option key: Verbose (Macaulay2Doc), -- an optional argument
-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1613:0.

dimStats -- statistics on the Krull dimension of a list of objects
******************************************************************

  * Usage:
        dimStats(List)
  * Inputs:
      * ideals, a list (Macaulay2Doc), of objects of type
        MonomialIdeal (Macaulay2Doc), or any type to which
        dim (Macaulay2Doc), can be applied.
  * Optional inputs (Macaulay2Doc),:
      * ShowTally, => ..., default value false, optional input
        to choose if the tally is to be returned
      * Verbose, => ...,
        default value false, optional input to request verbose feedback
  * Outputs:
      * a sequence (Macaulay2Doc), whose first entry is the
        average Krull dimension of a list of monomial ideals, the second entry
        is the standard deviation of the Krull dimension, and third entry (if
        option turned on) is the Krull dimension tally

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

The function dimStats computes the average and standard deviation of the Krull
dimension for a list of monomial ideals.

+--------------------------------------------------------------+
|i1 : R=ZZ/101[a,b,c];                                         |
+--------------------------------------------------------------+
|i2 : ideals = {monomialIdeal"a3,b,c2", monomialIdeal"a3,b,ac"}|
|                                                              |
|                      3      2                   3            |
|o2 = {monomialIdeal (a , b, c ), monomialIdeal (a , b, a*c)}  |
|                                                              |
|o2 : List                                                     |
+--------------------------------------------------------------+
|i3 : dimStats(ideals)                                         |
|                                                              |
|o3 = (.5, .5)                                                 |
|                                                              |
|o3 : Sequence                                                 |
+--------------------------------------------------------------+

The following examples use the existing functions randomMonomialSets,
and idealsFromGeneratingSets,
or randomMonomialIdeals,
to automatically generate a list of ideals, rather than creating the list
manually:

+-----------------------------------------------------------------------------+
|i4 : ideals = idealsFromGeneratingSets(randomMonomialSets(4,3,1.0,3))        |
|                                                                             |
|o4 = {monomialIdeal (x , x , x , x ), monomialIdeal (x , x , x , x ),        |
|                      1   2   3   4                   1   2   3   4          |
|     ------------------------------------------------------------------------|
|     monomialIdeal (x , x , x , x )}                                         |
|                     1   2   3   4                                           |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : dimStats(ideals)                                                        |
|                                                                             |
|o5 = (0, 0)                                                                  |
|                                                                             |
|o5 : Sequence                                                                |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
|i6 : ideals = randomMonomialIdeals(4,3,1.0,3)                                |
|                                                                             |
|o6 = {monomialIdeal (x , x , x , x ), monomialIdeal (x , x , x , x ),        |
|                      1   2   3   4                   1   2   3   4          |
|     ------------------------------------------------------------------------|
|     monomialIdeal (x , x , x , x )}                                         |
|                     1   2   3   4                                           |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+
|i7 : dimStats(ideals)                                                        |
|                                                                             |
|o7 = (0, 0)                                                                  |
|                                                                             |
|o7 : Sequence                                                                |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
|i8 : ideals = idealsFromGeneratingSets(randomMonomialSets(3,7,0.01,10))      |
|                                                                             |
|                     4 2                     5   2 4                         |
|o8 = {monomialIdeal(x x x ), monomialIdeal (x , x x ), monomialIdeal (),     |
|                     1 2 3                   1   1 2                         |
|     ------------------------------------------------------------------------|
|                                       5         4                  2 3      |
|     monomialIdeal (), monomialIdeal (x x x , x x ), monomialIdeal(x x ),    |
|                                       1 2 3   1 3                  2 3      |
|     ------------------------------------------------------------------------|
|                    2                      2 3                               |
|     monomialIdeal(x x ), monomialIdeal(x x x ), monomialIdeal (),           |
|                    1 3                  1 2 3                               |
|     ------------------------------------------------------------------------|
|                    4 3                                                      |
|     monomialIdeal(x x )}                                                    |
|                    2 3                                                      |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+
|i9 : dimStats(ideals)                                                        |
|                                                                             |
|o9 = (2.3, .458258)                                                          |
|                                                                             |
|o9 : Sequence                                                                |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
|i10 : ideals = randomMonomialIdeals(5,7,0.05,8)                              |
|                                                                             |
|                       2     2 3   5     2           3           2     3     |
|o10 = {monomialIdeal (x x , x x , x x , x x x , x x x x , x x x x , x x ,    |
|                       2 3   1 3   1 4   1 3 4   1 2 3 4   1 2 3 4   3 4     |
|      -----------------------------------------------------------------------|
|       2 5   4       4                   4       4       4 2     3 2     4 2 |
|      x x , x x x , x x x , x x x x , x x x , x x x x , x x x , x x x , x x ,|
|       1 4   1 2 5   1 3 5   1 2 3 5   1 3 5   2 3 4 5   1 4 5   3 4 5   2 5 |
|      -----------------------------------------------------------------------|
|       2 2 2     2 2   2 2   2   2 2 2     4 2     3   2   3   3   3       4 |
|      x x x , x x x , x x x x , x x x , x x x , x x , x x x , x x x , x x x ,|
|       1 3 5   2 3 5   1 2 4 5   1 4 5   2 4 5   2 5   1 3 5   3 4 5   3 4 5 |
|      -----------------------------------------------------------------------|
|       2 4                   3     2 3   7       2   3   4     6             |
|      x x ), monomialIdeal (x x , x x , x , x x x , x , x x , x x , x x x x ,|
|       4 5                   1 2   1 2   2   1 2 3   3   1 4   2 4   1 2 3 4 |
|      -----------------------------------------------------------------------|
|       2   2   2 2 2     3           2 2   2   2   4   2 4       5   2 5     |
|      x x x , x x x , x x , x x x , x x x x , x x x , x x , x x x , x x ,    |
|       1 2 4   2 3 4   1 4   2 4 5   1 3 4 5   1 3 5   4 5   1 2 5   2 5     |
|      -----------------------------------------------------------------------|
|       2 5                   4   6   3         2   2 4     2 2 2   2 3       |
|      x x ), monomialIdeal (x , x , x x , x x x , x x x , x x x , x x ,      |
|       3 5                   1   2   1 3   1 2 3   1 3 4   1 3 4   2 4       |
|      -----------------------------------------------------------------------|
|       2     3   3 2     2       4         4       3   2     3 3       3     |
|      x x x x , x x x , x x x , x x x , x x x x , x x x x , x x x , x x x ,  |
|       1 2 3 4   1 2 5   2 3 5   2 4 5   1 3 4 5   1 2 4 5   1 4 5   3 4 5   |
|      -----------------------------------------------------------------------|
|         4     4 2   3   2         2   3 2 2       3     3     2 3   2 4     |
|      x x x , x x , x x x , x x x x , x x x , x x x , x x , x x x , x x ,    |
|       2 4 5   3 5   1 4 5   2 3 4 5   3 4 5   1 2 5   3 5   1 4 5   1 5     |
|      -----------------------------------------------------------------------|
|         6                   6   3 3   2     2 2       5     5 2   2   4     |
|      x x ), monomialIdeal (x , x x , x x , x x x , x x x , x x , x x x ,    |
|       2 5                   1   2 3   2 4   1 3 4   1 3 4   3 4   1 2 4     |
|      -----------------------------------------------------------------------|
|         5     2     4     2     2   2           2       5     2             |
|      x x , x x x , x x , x x , x x x x , x x x x x , x x x , x ),           |
|       3 4   1 2 5   2 5   3 5   1 3 4 5   1 2 3 4 5   2 4 5   5             |
|      -----------------------------------------------------------------------|
|                          3 4   4 2     3 3     3   2   4 2   2 3     2 3    |
|      monomialIdeal (x , x x , x x x , x x x , x x x , x x , x x , x x x ,   |
|                      2   1 3   1 3 4   1 3 4   1 3 4   3 4   1 4   1 3 4    |
|      -----------------------------------------------------------------------|
|             4     2                   4       5             2   3     6     |
|      x x , x x , x ), monomialIdeal (x x , x x , x x x , x x , x x , x x ,  |
|       3 5   4 5   5                   1 2   1 2   1 2 3   1 3   2 4   3 4   |
|      -----------------------------------------------------------------------|
|       2 2       3     4     6   3     5       2       2 2 2       2   2 2   |
|      x x , x x x , x x , x x , x x , x x x , x x x , x x x , x x x , x x ,  |
|       1 4   1 2 4   1 4   2 4   1 5   2 3 5   3 4 5   1 2 5   1 4 5   4 5   |
|      -----------------------------------------------------------------------|
|       2 4                         4 2   2 3     2 2     2 2   3 2   5       |
|      x x ), monomialIdeal (x x , x x , x x , x x x , x x x , x x , x ,      |
|       2 5                   1 3   2 3   2 3   1 2 4   2 3 4   3 4   4       |
|      -----------------------------------------------------------------------|
|       3         2     2 4     4   2   2 2 2     3                           |
|      x x x , x x x , x x x , x x x , x x x , x x ), monomialIdeal (x ,      |
|       1 2 5   1 2 5   3 4 5   3 4 5   1 4 5   4 5                   2       |
|      -----------------------------------------------------------------------|
|       2         2       3   7     4 2   4 3     4                           |
|      x x x , x x x , x x , x , x x x , x x , x x )}                         |
|       1 3 4   1 3 4   3 4   4   1 3 5   4 5   4 5                           |
|                                                                             |
|o10 : List                                                                   |
+-----------------------------------------------------------------------------+
|i11 : dimStats(ideals)                                                       |
|                                                                             |
|o11 = (1.75, .433013)                                                        |
|                                                                             |
|o11 : Sequence                                                               |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
|i12 : ideals = idealsFromGeneratingSets(randomMonomialSets(5,7,1,10))        |
|791                                                                          |
|791                                                                          |
|791                                                                          |
|791                                                                          |
|791                                                                          |
|791                                                                          |
|791                                                                          |
|791                                                                          |
|791                                                                          |
|791                                                                          |
|                                                                             |
|                        2                  2 4                      2 3      |
|o12 = {monomialIdeal(x x ), monomialIdeal(x x ), monomialIdeal(x x x x ),    |
|                      1 5                  1 2                  1 2 3 5      |
|      -----------------------------------------------------------------------|
|                       3                      3 3                            |
|      monomialIdeal(x x x x ), monomialIdeal(x x ),                          |
|                     1 2 3 4                  2 3                            |
|      -----------------------------------------------------------------------|
|                     2     2                    2                            |
|      monomialIdeal(x x x x x ), monomialIdeal(x x ), monomialIdeal(x x x ), |
|                     1 2 3 4 5                  2 4                  2 3 4   |
|      -----------------------------------------------------------------------|
|                     5                        2 4                            |
|      monomialIdeal(x x x ), monomialIdeal(x x x )}                          |
|                     2 4 5                  2 3 4                            |
|                                                                             |
|o12 : List                                                                   |
+-----------------------------------------------------------------------------+
|i13 : dimStats(ideals)                                                       |
|                                                                             |
|o13 = (4, 0)                                                                 |
|                                                                             |
|o13 : Sequence                                                               |
+-----------------------------------------------------------------------------+

Ways to use dimStats:
=====================

  * "dimStats(List)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1399:0.

ER -- model for sampling from Erdos-Renyi type distributions on monomials
*************************************************************************

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

An Erdos-Renyi type model on monomials is a distribution over sets of
monomials. When generating a monomial set, each monomial considered is added to
the set with a fixed probability. The monomials are chosen from a given
polynomial ring and are bounded by degree.

+-----------------------------------------------------------------------------+
|i1 : n=4; D=8; p=0.05;                                                       |
+-----------------------------------------------------------------------------+
|i4 : myModel = ER(n,D,p)                                                     |
|                                                                             |
|o4 = Model{Generate => FunctionClosure[../../../../../Macaulay2/packages/    |
|           Name => Erdos-Renyi                                               |
|           Parameters => (4, 8, .05)                                         |
|                                                                             |
|o4 : Model                                                                   |
|-----------------------------------------------------------------------------|
|RandomMonomialIdeals.m2:134:20-134:48]}                                      |
+-----------------------------------------------------------------------------+

See also
========

  * randomMonomialSets -- randomly generates lists
    of monomials in fixed number of variables up to a given degree

Ways to use ER:
===============

  * ER(PolynomialRing,ZZ,List), --
    Graded Erdos-Renyi type distribution on monomials over (R,D,L)
  * ER(PolynomialRing,ZZ,RR), --
    Erdos-Renyi type distribution on monomials over (R,D,p)
  * ER(PolynomialRing,ZZ,ZZ), --
    Erdos-Renyi type distribution on monomials over (R,D,M)
  * ER(ZZ,ZZ,List) -- Graded Erdos-Renyi type
    distribution on monomials over (n,D,L)
  * ER(ZZ,ZZ,RR) -- Erdos-Renyi type distribution
    on monomials over (n,D,p)
  * ER(ZZ,ZZ,ZZ) -- Erdos-Renyi type distribution
    on monomials over (n,D,M)

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

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

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1909:0.

ER(PolynomialRing,ZZ,List) -- Graded Erdos-Renyi type distribution on monomials over (R,D,L)
********************************************************************************************

  * Function: ER,
  * Usage:
        ER(PolynomialRing,ZZ,List)
  * Inputs:
      * R, a polynomial ring (Macaulay2Doc), the ring in
        which monomials are chosen from
      * D, an integer (Macaulay2Doc), maximum degree
      * L, a list (Macaulay2Doc), of real numbers whose i-th entry
        is the probability of selecting a monomial of degree i, or of integers
        whose i-th entry is the number of monomials of degree i in each set
  * Outputs:
      * an instance of the type Model, Erdos-Renyi type model

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

Creates a graded ER-type model for sampling monomials of degree at most $D$
from the ring $R$.

+-----------------------------------------------------------------------------+
|i1 : D1=4; L1={0.1,0.2,0.3,0.4};                                             |
+-----------------------------------------------------------------------------+
|i3 : D2=4; L2={1,2,2,1};                                                     |
+-----------------------------------------------------------------------------+
|i5 : myModel1 = ER(ZZ/101[a..d],D1,L1)                                       |
|                                                                             |
|o5 = Model{Generate => FunctionClosure[../../../../../Macaulay2/packages/    |
|           Name => Erdos-Renyi                                               |
|                           ZZ                                                |
|           Parameters => (---[a..d], 4, {.1, .2, .3, .4})                    |
|                          101                                                |
|                                                                             |
|o5 : Model                                                                   |
|-----------------------------------------------------------------------------|
|RandomMonomialIdeals.m2:189:20-189:51]}                                      |
+-----------------------------------------------------------------------------+
|i6 : myModel2 = ER(ZZ/101[a..d],D2,L2)                                       |
|                                                                             |
|o6 = Model{Generate => FunctionClosure[../../../../../Macaulay2/packages/    |
|           Name => Erdos-Renyi                                               |
|                           ZZ                                                |
|           Parameters => (---[a..d], 4, {1, 2, 2, 1})                        |
|                          101                                                |
|                                                                             |
|o6 : Model                                                                   |
|-----------------------------------------------------------------------------|
|RandomMonomialIdeals.m2:189:20-189:51]}                                      |
+-----------------------------------------------------------------------------+

See also
========

  * randomMonomialSets -- randomly generates lists
    of monomials in fixed number of variables up to a given degree

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

  * ER(PolynomialRing,ZZ,List), --
    Graded Erdos-Renyi type distribution on monomials over (R,D,L)
-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:2077:0.

ER(PolynomialRing,ZZ,RR) -- Erdos-Renyi type distribution on monomials over (R,D,p)
***********************************************************************************

  * Function: ER,
  * Usage:
        ER(PolynomialRing,ZZ,RR)
  * Inputs:
      * R, a polynomial ring (Macaulay2Doc), the ring in
        which monomials are chosen from
      * D, an integer (Macaulay2Doc), maximum degree
      * p, a real number (Macaulay2Doc), the probability of selecting
        a monomial
  * Outputs:
      * an instance of the type Model, Erdos-Renyi type model

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

Creates an ER-type model for sampling monomials of degree at most $D$ from the
ring $R$ independently with probability $p$.

+-----------------------------------------------------------------------------+
|i1 : D=4; p=0.1;                                                             |
+-----------------------------------------------------------------------------+
|i3 : myModel = ER(ZZ/101[a..d],D,p)                                          |
|                                                                             |
|o3 = Model{Generate => FunctionClosure[../../../../../Macaulay2/packages/    |
|           Name => Erdos-Renyi                                               |
|                           ZZ                                                |
|           Parameters => (---[a..d], 4, .1)                                  |
|                          101                                                |
|                                                                             |
|o3 : Model                                                                   |
|-----------------------------------------------------------------------------|
|RandomMonomialIdeals.m2:143:20-143:48]}                                      |
+-----------------------------------------------------------------------------+

See also
========

  * randomMonomialSets -- randomly generates lists
    of monomials in fixed number of variables up to a given degree

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

  * ER(PolynomialRing,ZZ,RR), --
    Erdos-Renyi type distribution on monomials over (R,D,p)
-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1963:0.

ER(PolynomialRing,ZZ,ZZ) -- Erdos-Renyi type distribution on monomials over (R,D,M)
***********************************************************************************

  * Function: ER,
  * Usage:
        ER(PolynomialRing,ZZ,ZZ)
  * Inputs:
      * R, a polynomial ring (Macaulay2Doc), the ring in
        which monomials are chosen from
      * D, an integer (Macaulay2Doc), maximum degree
      * M, an integer (Macaulay2Doc), number of monomials in the set
  * Outputs:
      * an instance of the type Model, Erdos-Renyi type model

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

Creates an ER-type model for sampling a set of $M$ monomials of degree at most
$D$ from the ring $R$.

+-----------------------------------------------------------------------------+
|i1 : D=4; M=5;                                                               |
+-----------------------------------------------------------------------------+
|i3 : myModel = ER(ZZ/101[a..d],4,5)                                          |
|                                                                             |
|o3 = Model{Generate => FunctionClosure[../../../../../Macaulay2/packages/    |
|           Name => Erdos-Renyi                                               |
|                           ZZ                                                |
|           Parameters => (---[a..d], 4, 5)                                   |
|                          101                                                |
|                                                                             |
|o3 : Model                                                                   |
|-----------------------------------------------------------------------------|
|RandomMonomialIdeals.m2:162:20-162:48]}                                      |
+-----------------------------------------------------------------------------+

See also
========

  * randomMonomialSets -- randomly generates lists
    of monomials in fixed number of variables up to a given degree

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

  * ER(PolynomialRing,ZZ,ZZ), --
    Erdos-Renyi type distribution on monomials over (R,D,M)
-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:2017:0.

ER(ZZ,ZZ,List) -- Graded Erdos-Renyi type distribution on monomials over (n,D,L)
********************************************************************************

  * Function: ER,
  * Usage:
        ER(ZZ,ZZ,List)
  * Inputs:
      * n, an integer (Macaulay2Doc), number of variables
      * D, an integer (Macaulay2Doc), maximum degree
      * L, a list (Macaulay2Doc), of real numbers whose i-th entry
        is the probability of selecting a monomial of degree i, or of integers
        whose i-th entry is the number of monomials of degree i in each set
  * Outputs:
      * an instance of the type Model, Erdos-Renyi type model

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

Creates a graded ER-type model for sampling monomials in $n$ variables of
degree at most $D$.

+-----------------------------------------------------------------------------+
|i1 : n1=3; D1=4; L1={0.1,0.2,0.3,0.4};                                       |
+-----------------------------------------------------------------------------+
|i4 : n2=3; D2=4; L2={1,2,2,1};                                               |
+-----------------------------------------------------------------------------+
|i7 : myModel1 = ER(n1,D1,L1)                                                 |
|                                                                             |
|o7 = Model{Generate => FunctionClosure[../../../../../Macaulay2/packages/    |
|           Name => Erdos-Renyi                                               |
|           Parameters => (3, 4, {.1, .2, .3, .4})                            |
|                                                                             |
|o7 : Model                                                                   |
|-----------------------------------------------------------------------------|
|RandomMonomialIdeals.m2:176:20-176:51]}                                      |
+-----------------------------------------------------------------------------+
|i8 : myModel2 = ER(n2,D2,L2)                                                 |
|                                                                             |
|o8 = Model{Generate => FunctionClosure[../../../../../Macaulay2/packages/    |
|           Name => Erdos-Renyi                                               |
|           Parameters => (3, 4, {1, 2, 2, 1})                                |
|                                                                             |
|o8 : Model                                                                   |
|-----------------------------------------------------------------------------|
|RandomMonomialIdeals.m2:176:20-176:51]}                                      |
+-----------------------------------------------------------------------------+

See also
========

  * randomMonomialSets -- randomly generates lists
    of monomials in fixed number of variables up to a given degree

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

  * ER(ZZ,ZZ,List) -- Graded Erdos-Renyi type
    distribution on monomials over (n,D,L)
-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:2047:0.

ER(ZZ,ZZ,RR) -- Erdos-Renyi type distribution on monomials over (n,D,p)
***********************************************************************

  * Function: ER,
  * Usage:
        ER(ZZ,ZZ,RR)
  * Inputs:
      * n, an integer (Macaulay2Doc), number of variables
      * D, an integer (Macaulay2Doc), maximum degree
      * p, a real number (Macaulay2Doc), the probability of selecting
        a monomial
  * Outputs:
      * an instance of the type Model, Erdos-Renyi type model

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

Creates an ER-type model for sampling monomials in $n$ variables of degree at
most $D$ independently with probability $p$.

+-----------------------------------------------------------------------------+
|i1 : n=3; D=4; p=0.1;                                                        |
+-----------------------------------------------------------------------------+
|i4 : myModel = ER(n,D,p)                                                     |
|                                                                             |
|o4 = Model{Generate => FunctionClosure[../../../../../Macaulay2/packages/    |
|           Name => Erdos-Renyi                                               |
|           Parameters => (3, 4, .1)                                          |
|                                                                             |
|o4 : Model                                                                   |
|-----------------------------------------------------------------------------|
|RandomMonomialIdeals.m2:134:20-134:48]}                                      |
+-----------------------------------------------------------------------------+

See also
========

  * randomMonomialSets -- randomly generates lists
    of monomials in fixed number of variables up to a given degree

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

  * ER(ZZ,ZZ,RR) -- Erdos-Renyi type distribution
    on monomials over (n,D,p)
-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1936:0.

ER(ZZ,ZZ,ZZ) -- Erdos-Renyi type distribution on monomials over (n,D,M)
***********************************************************************

  * Function: ER,
  * Usage:
        ER(ZZ,ZZ,ZZ)
  * Inputs:
      * n, an integer (Macaulay2Doc), number of variables
      * D, an integer (Macaulay2Doc), maximum degree
      * M, an integer (Macaulay2Doc), number of monomials in the set
  * Outputs:
      * an instance of the type Model, Erdos-Renyi type model

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

Creates an ER-type model for sampling a set of $M$ monomials in $n$ variables
of degree at most $D$.

+-----------------------------------------------------------------------------+
|i1 : n=3; D=4; M=5;                                                          |
+-----------------------------------------------------------------------------+
|i4 : myModel = ER(n,D,M)                                                     |
|                                                                             |
|o4 = Model{Generate => FunctionClosure[../../../../../Macaulay2/packages/    |
|           Name => Erdos-Renyi                                               |
|           Parameters => (3, 4, 5)                                           |
|                                                                             |
|o4 : Model                                                                   |
|-----------------------------------------------------------------------------|
|RandomMonomialIdeals.m2:154:20-154:48]}                                      |
+-----------------------------------------------------------------------------+

See also
========

  * randomMonomialSets -- randomly generates lists
    of monomials in fixed number of variables up to a given degree

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

  * ER(ZZ,ZZ,ZZ) -- Erdos-Renyi type distribution
    on monomials over (n,D,M)
-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1990:0.

Generate -- model construct function
************************************

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

An object of type Model consists of a model name, a set of parameters, and a
generating function, stored under the corresponding keys in the hash table. The
key Generate points to the function that is used to generate random elements
according to the given model.

+-----------------------------------------------------------------------------+
|i1 : myModel = ER(2,2,0.5)                                                   |
|                                                                             |
|o1 = Model{Generate => FunctionClosure[../../../../../Macaulay2/packages/    |
|           Name => Erdos-Renyi                                               |
|           Parameters => (2, 2, .5)                                          |
|                                                                             |
|o1 : Model                                                                   |
|-----------------------------------------------------------------------------|
|RandomMonomialIdeals.m2:134:20-134:48]}                                      |
+-----------------------------------------------------------------------------+

See also
========

  * Model -- a type used to store a statistical model and its
    parameters

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

The object Generate, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1816:0.

getData -- get the underlying samples
*************************************

  * Usage:
        Data = getData(Sample)
  * Inputs:
      * S, an instance of the type Sample, to extract data from
  * Outputs:
      * Data, a list (Macaulay2Doc), of all samples in object

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

An object of type Sample contains several pieces of information about the
random sample, namely: the name of the model used to generate the sample,
values of the model's parameters used to generate the sample, the size of the
sample (that is, the number of data points in it), and the data itself. The
function getData is used to extract the sample data.

In the example below, we obtain a sample of size $5$ from the ER model with
parameter values $(3,4,0.1)$

+-----------------------------------------------------------------------------+
|i1 : s = sample(ER(3,4,0.1),5)                                               |
|                                                                             |
|o1 = Sample{...4...}                                                         |
|                                                                             |
|o1 : Sample                                                                  |
+-----------------------------------------------------------------------------+
|i2 : getData s                                                               |
|                                                                             |
|            2   2 2     3     2   3     2   2         3       2     3        |
|o2 = {{x , x , x x , x x }, {x , x , x x , x x x , x x , x x x }, {x x ,     |
|        3   2   1 3   1 2     3   2   2 3   1 2 3   1 2   1 2 3     1 2      |
|     ------------------------------------------------------------------------|
|      3     2 2                                                              |
|     x x , x x }, {x , x x }, {x x , x x x }}                                |
|      1 3   2 3     2   2 3     1 2   1 2 3                                  |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

Ways to use getData:
====================

  * "getData(Sample)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1892:0.

Histogram -- a summary statistic for a list of objects
******************************************************

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

The symbol Histogram is used as a key in the hash table returned by the
function statistics. It one of the summary statistics for a
given data sample.

+-----------------------------------------+
|i1 : s=sample(ER(6,3,0.2),100);          |
+-----------------------------------------+
|i2 : myStats = statistics(s, dim@@ideal);|
+-----------------------------------------+
|i3 : myStats.Histogram                   |
|                                         |
|o3 = Tally{1 => 20}                      |
|           2 => 61                       |
|           3 => 17                       |
|           4 => 2                        |
|                                         |
|o3 : Tally                               |
+-----------------------------------------+

See also
========

  * statistics -- generate statistics for a sample
  * ShowTally -- optional input to choose if the tally is to
    be returned

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

The object Histogram, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:2182:0.

idealsFromGeneratingSets -- creates ideals from sets of monomials
*****************************************************************

  * Usage:
        idealsFromGeneratingSets(List)
  * Inputs:
      * B, a list (Macaulay2Doc), of sets of monomials
  * Optional inputs (Macaulay2Doc),:
      * IncludeZeroIdeals, => ..., default value true,
        optional input to choose whether zero ideals should be included
      * Verbose, => ...,
        default value false, optional input to request verbose feedback
  * Outputs:
      * a list (Macaulay2Doc), of monomial ideals

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

Given a list of sets of monomials, the function converts each set into a
monomial ideal.

+-----------------------------------------------------------------------------+
|i1 : n=4; D=2; p=1.0; N=3;                                                   |
+-----------------------------------------------------------------------------+
|i5 : B=randomMonomialSets(n,D,p,N); B/print                                  |
|                  2                     2               2         2          |
|{x , x , x , x , x , x x , x x , x x , x , x x , x x , x , x x , x }         |
|  1   2   3   4   1   1 2   1 3   1 4   2   2 3   2 4   3   3 4   4          |
|                  2                     2               2         2          |
|{x , x , x , x , x , x x , x x , x x , x , x x , x x , x , x x , x }         |
|  1   2   3   4   1   1 2   1 3   1 4   2   2 3   2 4   3   3 4   4          |
|                  2                     2               2         2          |
|{x , x , x , x , x , x x , x x , x x , x , x x , x x , x , x x , x }         |
|  1   2   3   4   1   1 2   1 3   1 4   2   2 3   2 4   3   3 4   4          |
|                                                                             |
|o6 = {, , }                                                                  |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+
|i7 : idealsFromGeneratingSets(B)                                             |
|                                                                             |
|o7 = {monomialIdeal (x , x , x , x ), monomialIdeal (x , x , x , x ),        |
|                      1   2   3   4                   1   2   3   4          |
|     ------------------------------------------------------------------------|
|     monomialIdeal (x , x , x , x )}                                         |
|                     1   2   3   4                                           |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+

In case the option IncludeZeroIdeals is set to false, the function also counts
how many sets are converted to the zero ideal.

See also
========

  * randomMonomialIdeals -- generates random sets
    of monomial ideals

Ways to use idealsFromGeneratingSets:
=====================================

  * "idealsFromGeneratingSets(List)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1223:0.

IncludeZeroIdeals -- optional input to choose whether zero ideals should be included
************************************************************************************

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

When the option is used with the function randomMonomialIdeals,
if IncludeZeroIdeals => true (the default), then zero
ideals will be included in the list of random monomial ideals. If
IncludeZeroIdeals => false, then any zero ideals produced will be excluded,
along with the number of them.

+-------------------------------------------+
|i1 : n=2;D=2;p=0.0;N=1;                    |
+-------------------------------------------+
|i5 : ideals = randomMonomialIdeals(n,D,p,N)|
|                                           |
|o5 = {monomialIdeal ()}                    |
|                                           |
|o5 : List                                  |
+-------------------------------------------+

The 0 listed is the zero ideal:

+--------------------------------+
|i6 : ideals_0                   |
|                                |
|o6 = monomialIdeal ()           |
|                                |
|o6 : MonomialIdeal of QQ[x ..x ]|
|                          1   2 |
+--------------------------------+

In the example below, in contrast, the list of ideals returned is empty since
the single zero ideal generated is excluded:

+-----------------------------------------------------------+
|i7 : randomMonomialIdeals(n,D,p,N,IncludeZeroIdeals=>false)|
|                                                           |
|o7 = ({}, 1)                                               |
|                                                           |
|o7 : Sequence                                              |
+-----------------------------------------------------------+

The option can also be used with the function bettiStats. If
ideals contains zero ideals, you may wish to exclude them when computing the
Betti table statistics. In this case, use the optional input as follows:

+-----------------------------------------------------------------------------+
|i8 : R=ZZ/101[a..c]                                                          |
|                                                                             |
|o8 = R                                                                       |
|                                                                             |
|o8 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i9 : L={monomialIdeal (a^2*b,b*c), monomialIdeal(a*b,b*c^3),monomialIdeal    |
|-----------------------------------------------------------------------------|
|0_R};                                                                        |
+-----------------------------------------------------------------------------+
|i10 : apply(L,i->betti res i)                                                |
|                                                                             |
|              0 1 2         0 1 2         0                                  |
|o10 = {total: 1 2 1, total: 1 2 1, total: 1}                                 |
|           0: 1 . .      0: 1 . .      0: 1                                  |
|           1: . 1 .      1: . 1 .                                            |
|           2: . 1 1      2: . . .                                            |
|                         3: . 1 1                                            |
|                                                                             |
|o10 : List                                                                   |
+-----------------------------------------------------------------------------+
|i11 : bettiStats(L,IncludeZeroIdeals=>false)                                 |
|The Betti statistics do not include those for the zero ideals.               |
|                                                                             |
|              0  1  2         0  1  2          1  2                          |
|o11 = (total: 1  2  1, total: 1  2  1, total:  1  1)                         |
|           0: 1  .  .      0: 1  .  .      2: .5 .5                          |
|           1: .  1  .      1: .  1  .      3: .5 .5                          |
|           2: . .5 .5      2: . .5 .5                                        |
|           3: . .5 .5      3: . .5 .5                                        |
|                                                                             |
|o11 : Sequence                                                               |
+-----------------------------------------------------------------------------+
|i12 : bettiStats(L,IncludeZeroIdeals=>false,Verbose=>true)                   |
|There are 3 ideals in this sample. Of those, 1 are the zero ideal.           |
|The Betti statistics do not include those for the zero ideals.               |
|                                                                             |
|              0  1  2         0  1  2          1  2                          |
|o12 = (total: 1  2  1, total: 1  2  1, total:  1  1)                         |
|           0: 1  .  .      0: 1  .  .      2: .5 .5                          |
|           1: .  1  .      1: .  1  .      3: .5 .5                          |
|           2: . .5 .5      2: . .5 .5                                        |
|           3: . .5 .5      3: . .5 .5                                        |
|                                                                             |
|o12 : Sequence                                                               |
+-----------------------------------------------------------------------------+

See also
========

  * randomMonomialIdeals -- generates random sets
    of monomial ideals
  * bettiStats -- statistics on Betti tables of a sample of
    monomial ideals or list of objects
  * idealsFromGeneratingSets -- creates ideals
    from sets of monomials
  * Verbose (Macaulay2Doc) -- an optional argument

Functions with optional argument named IncludeZeroIdeals:
=========================================================

  * "bettiStats(...,IncludeZeroIdeals=>...)"
  * "idealsFromGeneratingSets(...,IncludeZeroIdeals=>...)"
  * "randomMonomialIdeals(...,IncludeZeroIdeals=>...)"

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

The object IncludeZeroIdeals, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1360:0.

Mean -- a summary statistic for a list of objects
*************************************************

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

A sample mean is one of the basic summary statistics for a sample of randomly
generated objects (or any list of objects in general). The mean value statistic
for some property of a list of objects is stored under the key Mean in the hash
table returned by the function statistics.

+--------------------------------------------+
|i1 : s=sample(ER(6,3,0.2),100);             |
+--------------------------------------------+
|i2 : myStats = statistics(s, degree@@ideal);|
+--------------------------------------------+
|i3 : myStats.Mean                           |
|                                            |
|     89                                     |
|o3 = --                                     |
|     20                                     |
|                                            |
|o3 : QQ                                     |
+--------------------------------------------+

The last line returns the average degree of the 100 ideals in the sample $s$.

See also
========

  * statistics -- generate statistics for a sample

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

The object Mean, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:2140:0.

mingenStats -- statistics on the minimal generators of a list of ideals: number and degree complexity
*****************************************************************************************************

  * Usage:
        mingenStats(List)
  * Inputs:
      * ideals, a list (Macaulay2Doc), of objects of type
        MonomialIdeal (Macaulay2Doc), or Ideal (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * ShowTally, => ..., default value false, optional input
        to choose if the tally is to be returned
      * Verbose, => ...,
        default value false, optional input to request verbose feedback
  * Outputs:
      * a sequence (Macaulay2Doc), with the following entries:
        the average number of minimal generators, the standard deviation of the
        number of minimal generators, the average degree complexity, and the
        standard deviation of the degree complexity. If the option ShowTally is
        turned on, then the output sequence also includes the tallies of the
        two numbers following their standard deviation.

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

This function removes zero ideals from the list of ideals, then calculates the
average and the standard deviation for the number of minimal generators and
degree complexity of the list of nonzero ideals.

+-------------------------------------+
|i1 : n=4; D=3; p={0.0,1.0,0.0}; N=3; |
+-------------------------------------+
|i5 : B=randomMonomialIdeals(n,D,p,N);|
+-------------------------------------+
|i6 : mingenStats(B)                  |
|                                     |
|o6 = (10, 0, 2, 0)                   |
|                                     |
|o6 : Sequence                        |
+-------------------------------------+

If the list given is a list of all zero ideals, mingenStats returns -infinity
for the mean number of minimal generators and mean degree complexity.

+---------------------------------------+
|i7 : B=randomMonomialIdeals(3,3,0.0,1);|
+---------------------------------------+
|i8 : mingenStats(B)                    |
|                                       |
|o8 = (-infinity, 0, -infinity, 0)      |
|                                       |
|o8 : Sequence                          |
+---------------------------------------+

Caveat
======

The function mingenStats removes zero ideals from the list of ideals before
computing the two values.

Ways to use mingenStats:
========================

  * "mingenStats(List)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1256:0.

Model -- a type used to store a statistical model and its parameters
********************************************************************

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

In order to generate and study random algebraic objects formally, one should
define a statistical model for such objects. A model captures the random
generating process of the objects. It consists of a name, a set of parameters,
and a generating function, stored under the corresponding keys in the hash
table.

+-----------------------------------------------------------------------------+
|i1 : ER(3,2,0.2)                                                             |
|                                                                             |
|o1 = Model{Generate => FunctionClosure[../../../../../Macaulay2/packages/    |
|           Name => Erdos-Renyi                                               |
|           Parameters => (3, 2, .2)                                          |
|                                                                             |
|o1 : Model                                                                   |
|-----------------------------------------------------------------------------|
|RandomMonomialIdeals.m2:134:20-134:48]}                                      |
+-----------------------------------------------------------------------------+

Combined with the type Sample, the type Model defined here stores such
information and allows for a streamlined way to sample random objects, store
the data as a proper statistical sample, and study their algebraic properties
under the probabilistic regime.

See also
========

  * Sample -- a type used to store a data sample from a
    statistical model
  * statistics -- generate statistics for a sample

Functions and methods returning an object of class Model:
=========================================================

  * ER -- model for sampling from Erdos-Renyi type distributions on
    monomials
  * model -- creates a new model for random objects with a given
    list of parameters and generating function

Methods that use an object of class Model:
==========================================

  * "sample(Model,ZZ)" -- see sample, -- generates a sample from
    the given model

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

The object Model, is a type (Macaulay2Doc), with
ancestor classes HashTable (Macaulay2Doc), < Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1656:0.

model -- creates a new model for random objects with a given list of parameters and generating function
*******************************************************************************************************

  * Usage:
        model(L,f,name)
  * Inputs:
      * L, a list (Macaulay2Doc), of parameter values chosen for
        the model
      * f, a function closure (Macaulay2Doc), function
        that generates random elements in this model
      * name, a string (Macaulay2Doc), of the model constructed
  * Outputs:
      * an instance of the type Model, with those fixed parameter
        values

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

To create your own model for random polynomials or other algebraic objects, use
the model method as follows. Suppose you wish to construct a set of M random
polynomials in 3 variables of degree 2. You may use Macaulay2's built-in random
function:

+--------------------------------------------------------+
|i1 : f=(D,n,M)->(R=QQ[x_1..x_n];apply(M,i->random(D,R)))|
|                                                        |
|o1 = f                                                  |
|                                                        |
|o1 : FunctionClosure                                    |
+--------------------------------------------------------+

To formalize the study of these random polynomials, embed this function into an
object of type Model,:

+-----------------------------------------------------------------------------+
|i2 : myModel = model({2,3,4},f,"rand(D,n,M): M random polynomials in n variab|
|                                                                             |
|o2 = Model{Generate => FunctionClosure[../../../../../Macaulay2/packages/Rand|
|           Name => rand(D,n,M): M random polynomials in n variables of degree|
|           Parameters => {2, 3, 4}                                           |
|                                                                             |
|o2 : Model                                                                   |
|-----------------------------------------------------------------------------|
|les of degree D")                                                            |
|                                                                             |
|omMonomialIdeals.m2:120:20-120:40]}                                          |
| D                                                                           |
+-----------------------------------------------------------------------------+

Now obtain the data about such random polynomials from the sample (that is, the
actual sample in the statistical sense) as follows:

+-----------------------------------------------------------------------------+
|i3 : N=2;                                                                    |
+-----------------------------------------------------------------------------+
|i4 : mySample = sample(myModel,N);                                           |
+-----------------------------------------------------------------------------+
|i5 : peek mySample                                                           |
|                                                                             |
|o5 = Sample{ModelName => rand(D,n,M): M random polynomials in n variables of |
|            Parameters => {2, 3, 4}                                          |
|            SampleSize => 2                                                  |
|                      9 2   9       7 2   3       7        7 2   7 2   7     |
|            Data => {{-x  + -x x  + -x  + -x x  + -x x  + --x , --x  + -x x  |
|                      2 1   4 1 2   4 2   4 1 3   9 2 3   10 3  10 1   3 1 2 |
|-----------------------------------------------------------------------------|
|degree D                                                                     |
|                                                                             |
|                                                                             |
|  3 2           6         2  5 2   2       3 2    3               10 2     2 |
|+ -x  + 7x x  + -x x  + 6x , -x  + -x x  + -x  + --x x  + 5x x  + --x , 10x  |
|  7 2     1 3   7 2 3     3  4 1   9 1 2   7 2   10 1 3     2 3    9 3     1 |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|  3       5 2   7               2 2    5 2   7       6 2   2       5         |
|+ -x x  + -x  + -x x  + 5x x  + -x }, {-x  + -x x  + -x  + -x x  + -x x  +   |
|  2 1 2   6 2   8 1 3     2 3   5 3    3 1   2 1 2   5 2   5 1 3   7 2 3     |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|5 2  5 2    1       3 2   4        9       4 2  5 2   5         2   6        |
|-x , -x  + --x x  + -x  + -x x  + --x x  + -x , -x  + -x x  + 6x  + -x x  +  |
|9 3  3 1   10 1 2   7 2   3 1 3   10 2 3   7 3  9 1   9 1 2     2   7 1 3    |
|-----------------------------------------------------------------------------|
|                                                       }                     |
|                                                                             |
|                                                                             |
|5       2 2  8 2   9       9 2   2       1       10 2                        |
|-x x  + -x , -x  + -x x  + -x  + -x x  + -x x  + --x }}                      |
|4 2 3   9 3  5 1   4 1 2   8 2   9 1 3   8 2 3    3 3                        |
+-----------------------------------------------------------------------------+

See also
========

  * sample -- generates a sample from the given model
  * statistics -- generate statistics for a sample

Ways to use model:
==================

  * "model(List,FunctionClosure,String)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1762:0.

ModelName -- name of the model used to generate a given sample
**************************************************************

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

An object of type Sample contains several pieces of information about the
random sample, namely: the name of the model used to generate the sample,
values of the model's parameters used to generate the sample, the size of the
sample (that is, the number of data points in it), and the data itself. As each
of these is a hash table entry, one obtains the model name by using the hash
key ModelName:

+--------------------------------------+
|i1 : (sample(ER(2,2,0.5),2)).ModelName|
|                                      |
|o1 = Erdos-Renyi                      |
+--------------------------------------+

See also
========

  * Sample -- a type used to store a data sample from a
    statistical model

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

The object ModelName, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1780:0.

Parameters -- values of the model parameters that were used to generate a given sample
**************************************************************************************

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

An object of type Sample contains several pieces of information about the
random sample, namely: the name of the model used to generate the sample,
values of the model's parameters used to generate the sample, the size of the
sample (that is, the number of data points in it), and the data itself. As each
of these is a hash table entry, one obtains the value of the parameters that
were used to generate the given sample via the hash key Parameters:

+---------------------------------------+
|i1 : (sample(ER(2,2,0.5),2)).Parameters|
|                                       |
|o1 = (2, 2, .5)                        |
|                                       |
|o1 : Sequence                          |
+---------------------------------------+

See also
========

  * sample -- generates a sample from the given model

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

The object Parameters, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1799:0.

pdimStats -- statistics on projective dimension of a list of objects
********************************************************************

  * Usage:
        pdimStats(List)
  * Inputs:
      * ideals, a list (Macaulay2Doc), of objects of type
        MonomialIdeal (Macaulay2Doc), or any type to which
        pdim (Macaulay2Doc), can be applied.
  * Optional inputs (Macaulay2Doc),:
      * ShowTally, => ..., default value false, optional input
        to choose if the tally is to be returned
      * Verbose, => ...,
        default value false, optional input to request verbose feedback
  * Outputs:
      * a sequence (Macaulay2Doc), whose first entry is the
        mean projective dimension, the second entry is the standard deviation
        of the projective dimension, and third entry (if option turned on) is
        the projective dimension tally for quotient rings of ideals in the list
        ideals.

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

The function pdimStats computes the mean and standard deviation of the
projective dimension of elements in the list:

+------------------------------------------------------------------+
|i1 : R=ZZ/101[a,b,c];                                             |
+------------------------------------------------------------------+
|i2 : ideals = {monomialIdeal(a^3,b,c^2), monomialIdeal(a^3,b,a*c)}|
|                                                                  |
|                      3      2                   3                |
|o2 = {monomialIdeal (a , b, c ), monomialIdeal (a , b, a*c)}      |
|                                                                  |
|o2 : List                                                         |
+------------------------------------------------------------------+
|i3 : pdimStats(ideals)                                            |
|                                                                  |
|o3 = (3, 0)                                                       |
|                                                                  |
|o3 : Sequence                                                     |
+------------------------------------------------------------------+

The function can also output the projective dimension tally as follows:

+----------------------------------------------------------------------------+
|i4 : R=ZZ/101[a,b,c];                                                       |
+----------------------------------------------------------------------------+
|i5 : ideals = {monomialIdeal(a,c),monomialIdeal(b),monomialIdeal(a^2*b,b^2)}|
|                                                                            |
|                                                             2    2         |
|o5 = {monomialIdeal (a, c), monomialIdeal b, monomialIdeal (a b, b )}       |
|                                                                            |
|o5 : List                                                                   |
+----------------------------------------------------------------------------+
|i6 : pdimStats(ideals, ShowTally=>true)                                     |
|                                                                            |
|o6 = (1.66667, .471405, Tally{1 => 1})                                      |
|                              2 => 2                                        |
|                                                                            |
|o6 : Sequence                                                               |
+----------------------------------------------------------------------------+

The following examples use the existing functions randomMonomialIdeals,
to automatically generate a list of ideals, rather than
creating the list manually:

+-----------------------------------------------------------------------------+
|i7 : ideals = randomMonomialIdeals(4,3,1.0,3)                                |
|                                                                             |
|o7 = {monomialIdeal (x , x , x , x ), monomialIdeal (x , x , x , x ),        |
|                      1   2   3   4                   1   2   3   4          |
|     ------------------------------------------------------------------------|
|     monomialIdeal (x , x , x , x )}                                         |
|                     1   2   3   4                                           |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+
|i8 : pdimStats(ideals)                                                       |
|                                                                             |
|o8 = (4, 0)                                                                  |
|                                                                             |
|o8 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i9 : ideals = randomMonomialIdeals(4,6,0.01,10)                              |
|                                                                             |
|                     2 3                       2     3                       |
|o9 = {monomialIdeal(x x x ), monomialIdeal (x x x , x x x ), monomialIdeal   |
|                     2 3 4                   1 2 4   1 3 4                   |
|     ------------------------------------------------------------------------|
|                         5       3   2                    2 2                |
|     (), monomialIdeal (x x , x x , x x ), monomialIdeal(x x ),              |
|                         2 3   2 3   1 4                  2 3                |
|     ------------------------------------------------------------------------|
|                    2 2                   5       4       2   2              |
|     monomialIdeal(x x ), monomialIdeal (x x , x x x , x x x x ),            |
|                    1 4                   1 3   2 3 4   1 2 3 4              |
|     ------------------------------------------------------------------------|
|                      2                   3       2 2     2                  |
|     monomialIdeal(x x ), monomialIdeal (x x x , x x x , x ),                |
|                    2 3                   1 3 4   1 3 4   4                  |
|     ------------------------------------------------------------------------|
|                      3                                                      |
|     monomialIdeal(x x x )}                                                  |
|                    2 3 4                                                    |
|                                                                             |
|o9 : List                                                                    |
+-----------------------------------------------------------------------------+
|i10 : pdimStats(ideals)                                                      |
|                                                                             |
|o10 = (1.6, 1.0198)                                                          |
|                                                                             |
|o10 : Sequence                                                               |
+-----------------------------------------------------------------------------+

See also
========

  * ShowTally -- optional input to choose if the tally is to
    be returned

Ways to use pdimStats:
======================

  * "pdimStats(List)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1477:0.

randomMonomialIdeals -- generates random sets of monomial ideals
****************************************************************

  * Usage:
        randomMonomialIdeals(ZZ,ZZ,RR,ZZ)
        randomMonomialIdeals(ZZ,ZZ,ZZ,ZZ)
        randomMonomialIdeals(ZZ,ZZ,List,ZZ)
  * Inputs:
      * n, an integer (Macaulay2Doc), number of variables
      * D, an integer (Macaulay2Doc), maximum degree
      * p, a real number (Macaulay2Doc), probability to select a
        monomial in the Erdos-Renyi-type model, OR
      * M, an integer (Macaulay2Doc), the number of monomials, up to
        the maximum number of monomials in $n$ variables of degree at most $D$,
        used to generate each ideal, OR
      * a list (Macaulay2Doc), of real numbers whose $i$-th entry
        is the probability of selecting a monomial of degree $i$, OR
      * a list (Macaulay2Doc), of integers whose $i$-th entry is
        the number of monomials of degree $i$ used to generate each ideal, up
        to the maximum number of monomials in $n$ variables of degree exactly
        $i$.
      * N, an integer (Macaulay2Doc), the number of random monomial
        ideals to be generated
  * Optional inputs (Macaulay2Doc),:
      * Coefficients, => ..., default value QQ, optional
        input to choose the coefficients of the ambient polynomial ring
      * IncludeZeroIdeals, => ..., default value true,
        optional input to choose whether zero ideals should be included
      * Strategy,
        => ..., default value "ER", optional input to choose the strategy for
        generating the random monomial set
      * VariableName, => ..., default value "x", optional
        input to choose the indexed variable name for the polynomial ring
  * Outputs:
      * a list (Macaulay2Doc), list of randomly generated monomial
        ideals, and the number of zero ideals removed from the sample, if any

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

This function creates $N$ random monomial ideals, with each monomial generator
having degree $d$, $1\leq d\leq D$, in $n$ variables. If $p$ is a real number,
it generates each of these ideals according to the Erdos-Renyi-type model (see
https://arxiv.org/abs/1701.07130): from the list of all monomials of degree
$1,\dots,D$ in $n$ variables, it selects each one, independently, with
probability $p$.

+-----------------------------------------------------------------------------+
|i1 : n=2; D=3; p=0.2; N=10;                                                  |
+-----------------------------------------------------------------------------+
|i5 : randomMonomialIdeals(n,D,p,N)                                           |
|                                                                             |
|                      2   3                                    2             |
|o5 = {monomialIdeal (x , x ), monomialIdeal x , monomialIdeal x ,            |
|                      1   2                  2                 2             |
|     ------------------------------------------------------------------------|
|                     3   2       2   3                                       |
|     monomialIdeal (x , x x , x x , x ), monomialIdeal x , monomialIdeal (x ,|
|                     1   1 2   1 2   2                  1                  1 |
|     ------------------------------------------------------------------------|
|      2                  2                                    2     2        |
|     x ), monomialIdeal x , monomialIdeal x , monomialIdeal (x x , x ),      |
|      2                  1                 2                  1 2   2        |
|     ------------------------------------------------------------------------|
|                     2                                                       |
|     monomialIdeal (x , x )}                                                 |
|                     1   2                                                   |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : randomMonomialIdeals(5,3,0.4,4)                                         |
|                                                                             |
|                                      2       2                       2      |
|o6 = {monomialIdeal (x x , x , x x , x x , x x , x ), monomialIdeal (x ,     |
|                      1 2   3   1 4   2 4   2 4   5                   1      |
|     ------------------------------------------------------------------------|
|            2   2   2                                       3                |
|     x x , x , x , x , x x , x x x , x x ), monomialIdeal (x , x , x , x x , |
|      1 2   2   3   4   1 5   2 3 5   4 5                   1   2   3   1 4  |
|     ------------------------------------------------------------------------|
|      2   2             2   3                   3   2     2   2       2   3  |
|     x , x x , x x , x x , x ), monomialIdeal (x , x x , x , x x , x x , x , |
|      4   1 5   4 5   1 5   5                   1   1 2   2   1 3   2 3   3  |
|     ------------------------------------------------------------------------|
|                            2     2       2     2                            |
|     x x , x x x , x x x , x x , x x , x x , x x )}                          |
|      1 4   2 3 4   1 2 5   3 5   4 5   1 5   4 5                            |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+

Note that this model does not generate the monomial $1$:

+------------------------------------+
|i7 : randomMonomialIdeals(3,2,1.0,1)|
|                                    |
|o7 = {monomialIdeal (x , x , x )}   |
|                      1   2   3     |
|                                    |
|o7 : List                           |
+------------------------------------+

If $M$ is an integer, then the function creates $N$ random monomial with $M$
(not necessarily minimal) generators: randomly select $M$ monomials from the
list of all monomials of degree $1,\dots,D$ in $n$ variables, then generate the
corresponding ideal.

+-----------------------------------------------------------------------------+
|i8 : n=8; D=4; M=7; N=3;                                                     |
+-----------------------------------------------------------------------------+
|i12 : randomMonomialIdeals(n,D,M,N)                                          |
|494                                                                          |
|494                                                                          |
|494                                                                          |
|                                                                             |
|                       3   3     2         2   2         2     3             |
|o12 = {monomialIdeal (x , x x , x x x , x x , x x x , x x , x x ),           |
|                       1   3 6   4 5 6   4 6   5 6 7   2 8   5 8             |
|      -----------------------------------------------------------------------|
|                        3     2     3             2         2                |
|      monomialIdeal (x x , x x x , x x , x x x , x x x , x x x , x x x ),    |
|                      1 2   2 3 4   3 4   5 6 7   4 5 8   2 6 8   6 7 8      |
|      -----------------------------------------------------------------------|
|                        3   2                                                |
|      monomialIdeal (x x , x x x , x x , x x x x , x x x x )}                |
|                      2 4   2 3 6   5 6   1 2 5 7   1 2 6 8                  |
|                                                                             |
|o12 : List                                                                   |
+-----------------------------------------------------------------------------+

Note that each generating set of each ideal has at most $M = 7$ monomials. If
one monomial divides another monomial that was generated, it will not be in the
generating set.

The input of type List (Macaulay2Doc), controls the number of
monomials in the generating set of each degree for the graded ER model.
Specifically, this input is either a list of real numbers between 0 and 1,
inclusive, whose i-th entry is the probability of including a monomial of
degree i in the monomial set, or it is a list of nonnegative integers whose
i-th entry is the number of monomials of each degree to include in the monomial
set. Consider the following two examples: If $p=p_1,\dots,p_D$ is a list of
real numbers of length $D$, then randomMonomialSet generates the set utilizing
the graded Erdos-Renyi-type model: select each monomial of degree $1\le d\le
D$, independently, with probability $p_d$.

+-------------------------------------------------+
|i13 : randomMonomialIdeals(2,3,{0.0, 1.0, 1.0},1)|
|                                                 |
|                       2         2               |
|o13 = {monomialIdeal (x , x x , x )}             |
|                       1   1 2   2               |
|                                                 |
|o13 : List                                       |
+-------------------------------------------------+

Note that no monomials of degree 1 were generated, since the first probability
vector entry, $p_1$, is 0.

If $M=M_1,\dots,M_D$ is a list of integers of length $D$, then the function
creates a list of objects of type MonomialIdeal (Macaulay2Doc),
where at most $M_d$ monomials are of degree $d$.

+-----------------------------------------+
|i14 : randomMonomialIdeals(3,3,{1,1,1},1)|
|                                         |
|                             2           |
|o14 = {monomialIdeal (x , x x )}         |
|                       2   1 3           |
|                                         |
|o14 : List                               |
+-----------------------------------------+

Observe that there are at most one degree-1, one degree-2, and one degree-3
monomials generating each ideal.

If Strategy=>"ER", which is the default setting for the graded fixed number of
generators version of the function, each set of monomials used to generate a
monomial ideal in the list is not necessarily minimal. Else if Strategy=>
"Minimal" then each monomial ideal in the list is generated by minimal sets of
$M_d$ monomials, or maximum number possible, of total degree $d$, starting from
the smallest degree.

+--------------------------------------------------------------+
|i15 : randomMonomialIdeals(3,3,{1,1,1},1, Strategy=>"Minimal")|
|                                                              |
|                       2   3                                  |
|o15 = {monomialIdeal (x , x , x )}                            |
|                       1   2   3                              |
|                                                              |
|o15 : List                                                    |
+--------------------------------------------------------------+

Observe that there are at most one degree-1, one degree-2, and one degree-3
monomials generating each ideal. Also observe that Strategy=>"Minimal"
generally gives more generators than the default Strategy=>"ER".

Caveat
======

Since the function returns a list of objects of type MonomialIdeal (Macaulay2Doc),
s, only the minimal generating set will be
displayed. In contrast, the function randomMonomialSet,
will display the full (not necessarily minimal) generating
set produced by the model.

See also
========

  * randomMonomialSets -- randomly generates lists
    of monomials in fixed number of variables up to a given degree
  * idealsFromGeneratingSets -- creates ideals
    from sets of monomials

Ways to use randomMonomialIdeals:
=================================

  * "randomMonomialIdeals(ZZ,ZZ,List,ZZ)"
  * "randomMonomialIdeals(ZZ,ZZ,RR,ZZ)"
  * "randomMonomialIdeals(ZZ,ZZ,ZZ,ZZ)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1093:0.

randomMonomialSet -- randomly generates a list of monomials in fixed number of variables up to a given degree
*************************************************************************************************************

  * Usage:
        randomMonomialSet(ZZ,ZZ,RR)
        randomMonomialSet(PolynomialRing,ZZ,RR)
        randomMonomialSet(ZZ,ZZ,ZZ)
        randomMonomialSet(PolynomialRing,ZZ,ZZ)
        randomMonomialSet(ZZ,ZZ,List)
        randomMonomialSet(PolynomialRing,ZZ,List)
  * Inputs:
      * n, an integer (Macaulay2Doc), number of variables, OR
      * a polynomial ring (Macaulay2Doc), the ring in
        which monomials are to live if $n$ is not specified
      * D, an integer (Macaulay2Doc), maximum degree
      * p, a real number (Macaulay2Doc), the probability of selecting
        a monomial, OR
      * M, an integer (Macaulay2Doc), number of monomials in the set,
        up to the maximum number of monomials in $n$ variables of degree at
        most $D$  OR
      * a list (Macaulay2Doc), of real numbers whose $i$-th entry
        is the probability of selecting a monomial of degree $i$, OR
      * a list (Macaulay2Doc), of integers whose $i$-th entry is
        the number of monomials of degree $i$ in each set, up to the maximum
        number of monomials in $n$ variables of degree exactly $i$
  * Optional inputs (Macaulay2Doc),:
      * Coefficients, => ..., default value QQ, optional
        input to choose the coefficients of the ambient polynomial ring
      * Strategy,
        => ..., default value "ER", optional input to choose the strategy for
        generating the random monomial set
      * VariableName, => ..., default value "x", optional
        input to choose the indexed variable name for the polynomial ring
  * Outputs:
      * a list (Macaulay2Doc), random set of monomials

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

The function randomMonomialSet creates a list of monomials, up to a given
degree $d$, $1\leq d\leq D$, in $n$ variables. If $p$ is a real number, it
generates the set according to the Erdos-Renyi-type model, that is, based on a
Binomial distribution: from the list of all monomials of degree $1,\dots,D$ in
$n$ variables, it selects each one, independently, with probability $p$.

+-------------------------------+
|i1 : n=2; D=3; p=0.2;          |
+-------------------------------+
|i4 : randomMonomialSet(n,D,p)  |
|                               |
|       2   2     3             |
|o4 = {x , x x , x }            |
|       1   1 2   2             |
|                               |
|o4 : List                      |
+-------------------------------+
|i5 : randomMonomialSet(3,2,0.6)|
|                               |
|               2   2           |
|o5 = {x , x , x , x }          |
|       2   3   2   3           |
|                               |
|o5 : List                      |
+-------------------------------+

Note that this model does not generate the monomial $1$:

+-----------------------------------------------+
|i6 : randomMonomialSet(3,2,1.0)                |
|                                               |
|                   2               2         2 |
|o6 = {x , x , x , x , x x , x x , x , x x , x }|
|       1   2   3   1   1 2   1 3   2   2 3   3 |
|                                               |
|o6 : List                                      |
+-----------------------------------------------+

If $M$ is an integer, then the function creates a list of monomials of length
$M$: randomly select $M$ monomials from the list of all monomials of degree
$1,\dots,D$ in $n$ variables.

+-------------------------------------------+
|i7 : n=10; D=5; M=4;                       |
+-------------------------------------------+
|i10 : randomMonomialSet(n,D,M)             |
|3002                                       |
|                                           |
|          2       2             2      2 2 |
|o10 = {x x x x , x x x x , x x x x  , x x }|
|        6 7 8 9   2 3 5 9   3 5 9 10   4 8 |
|                                           |
|o10 : List                                 |
+-------------------------------------------+

Note that it returns a set with $M = 4$ monomials.

If $M$ is greater than the total number of monomials in $n$ variables of degree
at most $D$, then the function will return all those monomials (and not $M$ of
them). For example:

+-------------------------------+
|i11 : randomMonomialSet(2,2,10)|
|5                              |
|                               |
|            2   2              |
|o11 = {x , x , x , x x , x }   |
|        2   2   1   1 2   1    |
|                               |
|o11 : List                     |
+-------------------------------+

returns 5 monomials in a generating set, and not 10, since there are fewer than
10 monomials to choose from.

The input of type List (Macaulay2Doc), controls the number of
monomials in the generating set of each degree for the graded ER model.
Specifically, this input is either a list of real numbers between 0 and 1,
inclusive, whose i-th entry is the probability of including a monomial of
degree i in the monomial set, or it is a list of nonnegative integers whose
i-th entry is the number of monomials of each degree to include in the monomial
set.

Consider the following two examples: If $p=p_1,\dots,p_D$ is a list of real
numbers of length $D$, then the function generates the set utilizing the graded
Erdos-Renyi-type model: select each monomial of degree $1\le d\le D$,
independently, with probability $p_d$.

+--------------------------------------------+
|i12 : randomMonomialSet(2,3,{0.0, 1.0, 1.0})|
|                                            |
|        2         2   3   2       2   3     |
|o12 = {x , x x , x , x , x x , x x , x }    |
|        1   1 2   2   1   1 2   1 2   2     |
|                                            |
|o12 : List                                  |
+--------------------------------------------+

Note that the degree-1 monomials were not generated, since the first
probability vector entry is 0.

If $M=M_1,\dots,M_D$ is a list of integers of length $D$, then the function
creates a list of monomials, where $M_d$ monomials are of degree $d$.

+------------------------------------+
|i13 : randomMonomialSet(2,3,{2,1,1})|
|                                    |
|                      3             |
|o13 = {x , x , x x , x }            |
|        1   2   1 2   1             |
|                                    |
|o13 : List                          |
+------------------------------------+

Observe that there are two degree-1, one degree-2, and one degree-3 monomials.

If Strategy=>"ER", the default setting for the graded fixed number of
generators version of the function, the set of monomials we obtain will not
necessarily be minimal. Else if Strategy=> "Minimal" then the set of monomials
constitutes a minimal generating set which is build up of $M_d$ monomials, or
the maximum number possible, of total degree $d$, for $d$ from 1 to $D$,
starting from $d=1$.

+---------------------------------------------------------+
|i14 : randomMonomialSet(3,3,{1,1,1}, Strategy=>"Minimal")|
|                                                         |
|                  3                                      |
|o14 = {x , x x , x }                                     |
|        3   1 2   2                                      |
|                                                         |
|o14 : List                                               |
+---------------------------------------------------------+

Observe that there are at most one degree-1, one degree-2, and one degree-3
monomials.

Sometimes we are already working in a specific ring and would like the random
sets of monomials to live in the same ring:

+-----------------------------------------------+
|i15 : D=3;p=.5; R=ZZ/101[a,b,c];               |
+-----------------------------------------------+
|i18 : randomMonomialSet(R,D,p)                 |
|                                               |
|           2   2   3   2    2      2     2   3 |
|o18 = {a, a , c , a , a b, a c, a*b , a*c , c }|
|                                               |
|o18 : List                                     |
+-----------------------------------------------+
|i19 : ring oo_0                                |
|                                               |
|o19 = R                                        |
|                                               |
|o19 : PolynomialRing                           |
+-----------------------------------------------+

See also
========

  * randomMonomialSets -- randomly generates lists
    of monomials in fixed number of variables up to a given degree

Ways to use randomMonomialSet:
==============================

  * "randomMonomialSet(PolynomialRing,ZZ,List)"
  * "randomMonomialSet(PolynomialRing,ZZ,RR)"
  * "randomMonomialSet(PolynomialRing,ZZ,ZZ)"
  * "randomMonomialSet(ZZ,ZZ,List)"
  * "randomMonomialSet(ZZ,ZZ,RR)"
  * "randomMonomialSet(ZZ,ZZ,ZZ)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1196:0.

randomMonomialSet(...,Strategy=>...) -- optional input to choose the strategy for generating the random monomial set
********************************************************************************************************************

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

Put Strategy => "ER" or Strategy => "Minimal" as an argument in the function
randomMonomialSet, randomMonomialSets,
or randomMonomialIdeals. "ER" draws random sets of
monomials from the ER-type distribution $\mathcal B(n,D,p)$, while "Minimal"
saves computation time by using quotient rings to exclude any non-minimal
generators from the list. For randomMonomialSets,
with the number of generators of pre-specified degrees is the input, choosing
Strategy => "Minimal" will result in larger minimal generating sets.

Functions with optional argument named Strategy:
================================================

  * "addHook(...,Strategy=>...)" -- see addHook (Macaulay2Doc),
    -- add a hook function to an object for later processing
  * annihilator(...,Strategy=>...) (missing documentation)
  * "basis(...,Strategy=>...)" -- see basis (Macaulay2Doc), --
    basis or generating set of all or part of a ring, ideal or module
  * "mingens(...,Strategy=>...)" -- see Complement (Macaulay2Doc),
    -- a Strategy option value
  * "trim(...,Strategy=>...)" -- see Complement (Macaulay2Doc),
    -- a Strategy option value
  * "compose(Module,Module,Module,Strategy=>...)" -- see compose (Macaulay2Doc),
    -- composition as a pairing on Hom-modules
  * decompose(Ideal,Strategy=>...) (missing documentation)
  * determinant(...,Strategy=>...) (Macaulay2Doc)
    -- choose
    between Bareiss, Cofactor and Dynamic algorithms
  * "dual(MonomialIdeal,List,Strategy=>...)" -- see
    dual(MonomialIdeal,Strategy=>...) (Macaulay2Doc),
  * "dual(MonomialIdeal,RingElement,Strategy=>...)" -- see
    dual(MonomialIdeal,Strategy=>...) (Macaulay2Doc),
  * dual(MonomialIdeal,Strategy=>...) (Macaulay2Doc)
  * "End(...,Strategy=>...)" -- see End (Macaulay2Doc), -- module of
    endomorphisms
  * exteriorPower(...,Strategy=>...) (Macaulay2Doc)
    -- choose
    between Bareiss, Cofactor and Dynamic algorithms
  * "gb(...,Strategy=>...)" -- see gb (Macaulay2Doc), -- compute a
    Gröbner basis
  * "GF(...,Strategy=>...)" -- see GF (Macaulay2Doc), -- make a finite
    field
  * "groebnerBasis(...,Strategy=>...)" -- see groebnerBasis (Macaulay2Doc),
    -- Gröbner basis, as a matrix
  * hilbertFunction(...,Strategy=>...) (missing documentation)
  * "Hom(...,Strategy=>...)" -- see Hom (Macaulay2Doc), -- module of
    homomorphisms
  * "homomorphism'(...,Strategy=>...)" -- see homomorphism' (Macaulay2Doc),
    -- get the element of Hom from a homomorphism
  * "hooks(...,Strategy=>...)" -- see hooks (Macaulay2Doc), -- list
    hooks attached to a key
  * "intersect(Ideal,Ideal,Strategy=>...)" -- see intersect(Ideal,Ideal) (Macaulay2Doc),
    -- compute an intersection of a
    sequence of ideals or modules
  * "intersect(Module,Module,Strategy=>...)" -- see
    intersect(Ideal,Ideal) (Macaulay2Doc), --
    compute an intersection of a sequence of ideals or modules
  * isPrime(Ideal,Strategy=>...) (missing documentation)
  * kernel(...,Strategy=>...) (Macaulay2Doc)
    -- strategy for
    Groebner Basis computations used in kernel computations
  * "match(...,Strategy=>...)" -- see match (Macaulay2Doc), --
    regular expression matching
  * minors(...,Strategy=>...) (Macaulay2Doc)
    -- choose
    between Bareiss, Cofactor and Dynamic algorithms
  * normalCone(Ideal,RingElement,Strategy=>...) (missing documentation)
  * normalCone(Ideal,Strategy=>...) (missing documentation)
  * "parallelApply(...,Strategy=>...)" -- see parallelApply (Macaulay2Doc),
    -- apply a function to each element in
    parallel
  * "pushForward(...,Strategy=>...)" -- see pushForward(RingMap,Module) (Macaulay2Doc),
    -- compute the pushforward
    of a module along a ring map
  * quotient'(...,Strategy=>...) (missing documentation)
  * quotient(...,Strategy=>...) (missing documentation)
  * "randomMonomialIdeals(...,Strategy=>...)"
  * randomMonomialSet(...,Strategy=>...)
    -- optional input
    to choose the strategy for generating the random monomial set
  * "randomMonomialSets(...,Strategy=>...)"
  * saturate(...,Strategy=>...) (missing documentation)
  * "syz(...,Strategy=>...)" -- see syz(Matrix) (Macaulay2Doc),
    -- compute the syzygy matrix

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

  * Default value: ER
  * Function: randomMonomialSet, -- randomly generates
    a list of monomials in fixed number of variables up to a given degree
  * Option key: Strategy (Macaulay2Doc), -- an optional argument
-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1319:0.

randomMonomialSets -- randomly generates lists of monomials in fixed number of variables up to a given degree
*************************************************************************************************************

  * Usage:
        randomMonomialSets(ZZ,ZZ,RR,ZZ)
        randomMonomialSets(PolynomialRing,ZZ,RR,ZZ)
        randomMonomialSets(ZZ,ZZ,ZZ,ZZ)
        randomMonomialSets(PolynomialRing,ZZ,ZZ,ZZ)
        randomMonomialSets(ZZ,ZZ,List,ZZ)
        randomMonomialSets(PolynomialRing,ZZ,List,ZZ)
  * Inputs:
      * n, an integer (Macaulay2Doc), number of variables, OR
      * a polynomial ring (Macaulay2Doc), the ring in
        which the monomials are to live if $n$ is not specified
      * D, an integer (Macaulay2Doc), maximum degree
      * p, a real number (Macaulay2Doc), the probability of selecting
        a monomial, OR
      * M, an integer (Macaulay2Doc), number of monomials in the set,
        up to the maximum number of monomials in $n$ variables of degree at
        most $D$  OR
      * a list (Macaulay2Doc), of real numbers whose $i$-th entry
        is the probability of selecting a monomial of degree $i$, OR
      * a list (Macaulay2Doc), of integers whose $i$-th entry is
        the number of monomials of degree $i$ in each set, up to the maximum
        number of monomials in $n$ variables of degree exactly $i$
      * N, an integer (Macaulay2Doc), number of sets to be generated
  * Optional inputs (Macaulay2Doc),:
      * Coefficients, => ..., default value QQ, optional
        input to choose the coefficients of the ambient polynomial ring
      * Strategy,
        => ..., default value "ER", optional input to choose the strategy for
        generating the random monomial set
      * VariableName, => ..., default value "x", optional
        input to choose the indexed variable name for the polynomial ring
  * Outputs:
      * a list (Macaulay2Doc), random generating sets of monomials

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

This function creates $N$ random sets of monomials of degree $d$, $1\leq d\leq
D$, in $n$ variables. It does so by calling randomMonomialSet,
$N$ times.

See also
========

  * randomMonomialSet -- randomly generates a list of
    monomials in fixed number of variables up to a given degree

Ways to use randomMonomialSets:
===============================

  * "randomMonomialSets(PolynomialRing,ZZ,List,ZZ)"
  * "randomMonomialSets(PolynomialRing,ZZ,RR,ZZ)"
  * "randomMonomialSets(PolynomialRing,ZZ,ZZ,ZZ)"
  * "randomMonomialSets(ZZ,ZZ,List,ZZ)"
  * "randomMonomialSets(ZZ,ZZ,RR,ZZ)"
  * "randomMonomialSets(ZZ,ZZ,ZZ,ZZ)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:881:0.

regStats -- statistics on the regularities of a list of objects
***************************************************************

  * Usage:
        regStats(List)
  * Inputs:
      * a list (Macaulay2Doc), of objects of type
        MonomialIdeal (Macaulay2Doc), or any type to which
        regularity (Macaulay2Doc), can be applied.
  * Optional inputs (Macaulay2Doc),:
      * ShowTally, => ..., default value false, optional input
        to choose if the tally is to be returned
      * Verbose, => ...,
        default value false, optional input to request verbose feedback
  * Outputs:
      * a sequence (Macaulay2Doc), whose first entry is the
        mean regularity of a list of monomial ideals, second entry is the
        standard deviation of the regularities, and third entry (if option is
        turned on) is the regularity tally.

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

This function removes zero ideals from the list of ideals, then calculates the
average and the standard deviation of the regularity of the list of nonzero
ideals.

+------------------------------------------------------------------+
|i1 : R=ZZ/101[a,b,c];                                             |
+------------------------------------------------------------------+
|i2 : ideals = {monomialIdeal(a^3,b,c^2), monomialIdeal(a^3,b,a*c)}|
|                                                                  |
|                      3      2                   3                |
|o2 = {monomialIdeal (a , b, c ), monomialIdeal (a , b, a*c)}      |
|                                                                  |
|o2 : List                                                         |
+------------------------------------------------------------------+
|i3 : regStats(ideals)                                             |
|                                                                  |
|o3 = (3.5, .5)                                                    |
|                                                                  |
|o3 : Sequence                                                     |
+------------------------------------------------------------------+

If the list given is a list of all zero ideals, regStats returns -infinity for
the mean regularity.

+--------------------------------------+
|i4 : B=randomMonomialIdeals(3,3,0.0,1)|
|                                      |
|o4 = {monomialIdeal ()}               |
|                                      |
|o4 : List                             |
+--------------------------------------+
|i5 : regStats(B)                      |
|                                      |
|o5 = (-infinity, 0)                   |
|                                      |
|o5 : Sequence                         |
+--------------------------------------+

Caveat
======

The function removes zero ideals from the list of ideals before computing the
two values.

See also
========

  * ShowTally -- optional input to choose if the tally is to
    be returned

Ways to use regStats:
=====================

  * "regStats(List)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1511:0.

Sample -- a type used to store a data sample from a statistical model
*********************************************************************

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

A sample of algebraic objects is a set of data collected by a random generating
process, necessarily captured by a formal statistical model. The type Sample
defined here stores a set of data generated using an object of type Model. This
allows for a streamlined way to sample random objects, store the data as a
proper statistical sample, and study their algebraic properties under the
probabilistic regime.

An object of type Sample is a hash table with the following keys: name of the
model used to generate the sample, values of the model's parameters used to
generate the sample, the size of the sample (that is, the number of data points
in it), and the data itself.

+-----------------------------------------------------------------------------+
|i1 : peek sample(ER(3,2,0.2),4)                                              |
|                                                                             |
|o1 = Sample{ModelName => Erdos-Renyi                                         |
|            Parameters => (3, 2, .2)                                         |
|            SampleSize => 4                                                  |
|                           2   2     2           2         2                 |
|            Data => {{x , x , x }, {x }, {x x , x , x x , x }, {x , x x ,    |
|                       3   2   3     2     1 3   2   2 3   3     1   1 2     |
|-----------------------------------------------------------------------------|
|    }                                                                        |
|                                                                             |
|                                                                             |
| 2                                                                           |
|x }}                                                                         |
| 2                                                                           |
+-----------------------------------------------------------------------------+

See also
========

  * Model -- a type used to store a statistical model and its
    parameters
  * statistics -- generate statistics for a sample

Functions and methods returning an object of class Sample:
==========================================================

  * sample -- generates a sample from the given model

Methods that use an object of class Sample:
===========================================

  * "getData(Sample)" -- see getData, -- get the underlying
    samples
  * "statistics(Sample,Function)" -- see statistics, --
    generate statistics for a sample
  * "writeSample(Sample,String)" -- see writeSample, --
    write sample data to a directory

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

The object Sample, is a type (Macaulay2Doc), with
ancestor classes MutableHashTable (Macaulay2Doc), <
HashTable (Macaulay2Doc) < Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1635:0.

sample -- generates a sample from the given model
*************************************************

  * Usage:
        sample(Model,ZZ)
  * Inputs:
      * M, an instance of the type Model, to be sampled from
      * N, an integer (Macaulay2Doc), sample size
  * Outputs:
      * an instance of the type Sample, a sample of size $N$
        from the given model $M$

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

This function generates $N$ realizations of the random variable that has the
distribution specified by the given model.

+----------------------------+
|i1 : s=sample(ER(3,2,0.2),4)|
|                            |
|o1 = Sample{...4...}        |
|                            |
|o1 : Sample                 |
+----------------------------+

One obtains the data from the object of type Sample, (that is,
the actual sample in the statistical sense) as follows:

+---------------------------------------------------------------+
|i2 : getData s                                                 |
|                                                               |
|            2   2     2           2         2               2  |
|o2 = {{x , x , x }, {x }, {x x , x , x x , x }, {x , x x , x }}|
|        3   2   3     2     1 3   2   2 3   3     1   1 2   2  |
|                                                               |
|o2 : List                                                      |
+---------------------------------------------------------------+

The actual sample contains more information than just the data itself:

+-----------------------------------------------------------------------------+
|i3 : peek s                                                                  |
|                                                                             |
|o3 = Sample{ModelName => Erdos-Renyi                                         |
|            Parameters => (3, 2, .2)                                         |
|            SampleSize => 4                                                  |
|                           2   2     2           2         2                 |
|            Data => {{x , x , x }, {x }, {x x , x , x x , x }, {x , x x ,    |
|                       3   2   3     2     1 3   2   2 3   3     1   1 2     |
|-----------------------------------------------------------------------------|
|    }                                                                        |
|                                                                             |
|                                                                             |
| 2                                                                           |
|x }}                                                                         |
| 2                                                                           |
+-----------------------------------------------------------------------------+

and one can easily obtain sample statistics:

+------------------------------------------+
|i4 : statistics(s,degree@@ideal)          |
|                                          |
|o4 = HashTable{Histogram => Tally{2 => 4}}|
|               Mean => 2                  |
|               StdDev => 0                |
|                                          |
|o4 : HashTable                            |
+------------------------------------------+

See also
========

  * statistics -- generate statistics for a sample
  * getData -- get the underlying samples

Ways to use sample:
===================

  * "sample(Model,ZZ)"
  * sample(String) -- creates an object of type
    Sample from a sample stored in a directory on disk

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

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

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1694:0.

sample(String) -- creates an object of type Sample from a sample stored in a directory on disk
**********************************************************************************************

  * Function: sample,
  * Usage:
        sample(String)
  * Inputs:
      * a string (Macaulay2Doc), name of the directory where the
        sample is stored
  * Outputs:
      * an instance of the type Sample, Sample read from the
        specified directory

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

A random sample of objects can be generated from an arbitrary model and stored
to a directory on disk using the function writeSample. This shows how to
retrieve that stored sample and have it loaded as an object of type Sample:

+-----------------------------------------------------------------+
|i1 : writeSample(sample(ER(2,3,0.1),5), "testDirectory")         |
+-----------------------------------------------------------------+
|i2 : mySample = sample("testDirectory")                          |
|                                                                 |
|o2 = Sample{...4...}                                             |
|                                                                 |
|o2 : Sample                                                      |
+-----------------------------------------------------------------+
|i3 : peek mySample                                               |
|                                                                 |
|o3 = Sample{ModelName => Erdos-Renyi                            }|
|            Parameters => (2, 3, .1)                             |
|            SampleSize => 5                                      |
|                       2   2            2       2          2     |
|            Data => {{x , x x }, {0}, {x x , x x }, {0}, {x x }} |
|                       1   1 2          1 2   1 2          1 2   |
+-----------------------------------------------------------------+

See also
========

  * Sample -- a type used to store a data sample from a
    statistical model
  * writeSample -- write sample data to a directory
  * Model -- a type used to store a statistical model and its
    parameters

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

  * sample(String) -- creates an object of type
    Sample from a sample stored in a directory on disk
-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1722:0.

SampleSize -- size of the random sample
***************************************

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

An object of type Sample contains several pieces of information about the
random sample, namely: the name of the model used to generate the sample,
values of the model's parameters used to generate the sample, the size of the
sample (that is, the number of data points in it), and the data itself. As each
of these is a hash table entry, one obtains the sample size by using the hash
key SampleSize:

+-------------------------------+
|i1 : s = sample(ER(1,1,0.0),10)|
|                               |
|o1 = Sample{...4...}           |
|                               |
|o1 : Sample                    |
+-------------------------------+
|i2 : s.SampleSize              |
|                               |
|o2 = 10                        |
+-------------------------------+

See also
========

  * Sample -- a type used to store a data sample from a
    statistical model

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

The object SampleSize, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1835:0.

SaveBettis -- optional input to store all Betti tables computed
***************************************************************

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

The function that computes statistics on Betti tables has an option to save all
of the Betti tables to a file. This may be useful if the computation from the
resolution, which is what is called from bettiStats, takes
too long.

+-----------------------------------------------------------------------------+
|i1 : ZZ/101[a..e];                                                           |
+-----------------------------------------------------------------------------+
|i2 : L={monomialIdeal"a2b,bc", monomialIdeal"ab,bc3",monomialIdeal"ab,ac,bd,b|
|                                                                             |
|                      2                                3                   3 |
|o2 = {monomialIdeal (a b, b*c), monomialIdeal (a*b, b*c ), monomialIdeal (a ,|
|     ------------------------------------------------------------------------|
|           3        3             3                  3                       |
|     a*b, b , a*c, c , b*d, c*d, d , a*e, b*e, c*e, e )}                     |
|                                                                             |
|o2 : List                                                                    |
|-----------------------------------------------------------------------------|
|e,ae,cd,ce,a3,b3,c3,d3,e3"}                                                  |
+-----------------------------------------------------------------------------+
|i3 : bettiStats (L,SaveBettis=>"myBettiDiagrams")                            |
|                                                                             |
|             0       1       2       3       4       5         0       1     |
|o3 = (total: 1       2       2 1.33333 1.33333 .333333, total: 1 5.33333     |
|          0: 1       .       .       .       .       .      0: 1       .     |
|          1: .       1 .333333 .333333 .333333       .      1: .       3     |
|          2: . .666667 .666667 .333333 .333333       .      2: .       2     |
|          3: . .333333 .666667 .333333 .333333       .      3: . .333333     |
|          4: .       . .333333 .333333 .333333 .333333      4: .       .     |
|     ------------------------------------------------------------------------|
|           2       3       4 5               1       2       3       4       |
|     10.3333      10       5 1, total: 5.46008 13.4481 14.1421 7.07107       |
|           .       .       . .      1: 2.82843 5.18545 2.82843 .471405       |
|     3.66667       2 .333333 .      2: 2.16025 6.37704 6.12826 1.88562       |
|           5 4.33333 1.33333 .      3: .471405 .471405 .942809 .471405       |
|     .666667 .666667 .333333 .      4:       . 1.41421 4.24264 4.24264       |
|           1       3       3 1                                               |
|     ------------------------------------------------------------------------|
|           5                                                                 |
|     1.41421)                                                                |
|           .                                                                 |
|           .                                                                 |
|           .                                                                 |
|     1.41421                                                                 |
|                                                                             |
|o3 : Sequence                                                                |
+-----------------------------------------------------------------------------+

See also
========

  * bettiStats -- statistics on Betti tables of a sample of
    monomial ideals or list of objects
  * CountPure -- optional input to show the number of objects
    in the list whose Betti tables are pure
  * Verbose (Macaulay2Doc) -- an optional argument
  * IncludeZeroIdeals -- optional input to choose
    whether zero ideals should be included

Functions with optional argument named SaveBettis:
==================================================

  * "bettiStats(...,SaveBettis=>...)"

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

The object SaveBettis, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:945:0.

ShowTally -- optional input to choose if the tally is to be returned
********************************************************************

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

If ShowTally => false (the default value), then only the 2 basic statistics -
mean and standard deviation - of the function will be returned. If ShowTally =>
true, then both the statistics and the tally will be returned.

+--------------------------------------------------------------------+
|i1 : R=ZZ/101[a,b,c];                                               |
+--------------------------------------------------------------------+
|i2 :       ideals = {monomialIdeal"a3,b,c2", monomialIdeal"a3,b,ac"}|
|                                                                    |
|                      3      2                   3                  |
|o2 = {monomialIdeal (a , b, c ), monomialIdeal (a , b, a*c)}        |
|                                                                    |
|o2 : List                                                           |
+--------------------------------------------------------------------+
|i3 :       dimStats(ideals)                                         |
|                                                                    |
|o3 = (.5, .5)                                                       |
|                                                                    |
|o3 : Sequence                                                       |
+--------------------------------------------------------------------+
|i4 : mingenStats(ideals)                                            |
|                                                                    |
|o4 = (3, 0, 3, 0)                                                   |
|                                                                    |
|o4 : Sequence                                                       |
+--------------------------------------------------------------------+

In order to view the tally, ShowTally must be set to true (ShowTally => true)
when the function is called:

+-----------------------------------------------+
|i5 : degStats(ideals)                          |
|                                               |
|o5 = (3.5, 2.5)                                |
|                                               |
|o5 : Sequence                                  |
+-----------------------------------------------+
|i6 : pdimStats(ideals)                         |
|                                               |
|o6 = (3, 0)                                    |
|                                               |
|o6 : Sequence                                  |
+-----------------------------------------------+
|i7 : dimStats(ideals,ShowTally=>true)          |
|                                               |
|o7 = (.5, .5, Tally{0 => 1})                   |
|                    1 => 1                     |
|                                               |
|o7 : Sequence                                  |
+-----------------------------------------------+
|i8 : mingenStats(ideals,ShowTally=>true)       |
|                                               |
|o8 = (3, 0, Tally{3 => 2}, 3, 0, Tally{3 => 2})|
|                                               |
|o8 : Sequence                                  |
+-----------------------------------------------+
|i9 : degStats(ideals,ShowTally=>true)          |
|                                               |
|o9 = (3.5, 2.5, Tally{1 => 1})                 |
|                      6 => 1                   |
|                                               |
|o9 : Sequence                                  |
+-----------------------------------------------+

See also
========

  * dimStats -- statistics on the Krull dimension of a list of
    objects
  * mingenStats -- statistics on the minimal generators of
    a list of ideals: number and degree complexity
  * degStats -- statistics on the degrees of a list of objects
  * regStats -- statistics on the regularities of a list of
    objects
  * pdimStats -- statistics on projective dimension of a list
    of objects

Functions with optional argument named ShowTally:
=================================================

  * "degStats(...,ShowTally=>...)"
  * "dimStats(...,ShowTally=>...)"
  * "mingenStats(...,ShowTally=>...)"
  * "pdimStats(...,ShowTally=>...)"
  * "regStats(...,ShowTally=>...)"

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

The object ShowTally, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1438:0.

statistics -- generate statistics for a sample
**********************************************

  * Usage:
        statistics(S,f)
  * Inputs:
      * S, an instance of the type Sample, containing randomly
        generated objects from an object of type Model,
      * f, a function (Macaulay2Doc), that is computed for each
        data point in the sample S
  * Outputs:
      * a hash table (Macaulay2Doc), containing the basic
        statistics for the function f applied to the sample s

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

This function generates statistics for the sample by applying the given
function to each sample point and computing some basic summary statistics.
Specifically, the function $f$ is applied to each element in the sample, and --
provided that the function has output of type either numerical (ZZ) or
BettiTally -- its result is then used to calculate a mean, standard deviation,
and a histogram.

+-------------------------------------------+
|i1 : s=sample(ER(6,3,0.2),15);             |
+-------------------------------------------+
|i2 : statistics(s, degree@@ideal)          |
|                                           |
|o2 = HashTable{Histogram => Tally{1 => 4 }}|
|                                  2 => 3   |
|                                  3 => 2   |
|                                  4 => 3   |
|                                  5 => 1   |
|                                  10 => 1  |
|                                  15 => 1  |
|                       58                  |
|               Mean => --                  |
|                       15                  |
|               StdDev => 3.72141           |
|                                           |
|o2 : HashTable                             |
+-------------------------------------------+

The output above shows the histogram of the degrees of ideals in the sample, as
well as mean degree and its standard deviation. The same kind of output is
produced by the following statistics:

+---------------------------------------------------+
|i3 : s=sample(ER(2,2,0.8),10)                      |
|                                                   |
|o3 = Sample{...4...}                               |
|                                                   |
|o3 : Sample                                        |
+---------------------------------------------------+
|i4 : statistics(s,betti@@gens@@ideal)              |
|                                                   |
|                                         0 1       |
|o4 = HashTable{Histogram => Tally{total: 1 3 => 1}}|
|                                      0: 1 2       |
|                                      1: . 1       |
|                                         0 1       |
|                                  total: 1 3 => 3  |
|                                      0: 1 1       |
|                                      1: . 2       |
|                                         0 1       |
|                                  total: 1 4 => 2  |
|                                      0: 1 1       |
|                                      1: . 3       |
|                                         0 1       |
|                                  total: 1 5 => 4  |
|                                      0: 1 2       |
|                                      1: . 3       |
|                              0   1                |
|               Mean => total: 1   4                |
|                           0: 1 1.5                |
|                           1: . 2.5                |
|                                      1            |
|               StdDev => total: 1.17082            |
|                             0:      .5            |
|                             1:  .67082            |
|                                                   |
|o4 : HashTable                                     |
+---------------------------------------------------+

In the example above, the entry Mean is the average - entry-wise - of the Betti
tables of the random ideals in the sample. An adventurous user my wish to get
statistics of other functions applied to the sample. If the output of f is not
ZZ or BettiTally, the method will tally the sample data:

+-----------------------------------------------------------------------------+
|i5 : statistics(s,mingens@@ideal)                                            |
|Warning: the statistics method is returning only the Tally                   |
|                your function applied to the sample data.                    |
|                standard deviation, then ensure you use a                    |
|                                                                             |
|o5 = Tally{| x_1 x_2^2 | => 3}                                               |
|           | x_2 | => 1                                                      |
|           | x_2 x_1 | => 5                                                  |
|           | x_2 x_1^2 | => 1                                                |
|                                                                             |
|o5 : Tally                                                                   |
|-----------------------------------------------------------------------------|
| of the outputs of                                                           |
|If you want more information, such as mean and                               |
|function with numerical (ZZ) or BettiTally output.                           |
+-----------------------------------------------------------------------------+

Caveat
======

In fact, anything that can be run through "tally" can be used as the input
function f to this method.

Ways to use statistics:
=======================

  * "statistics(Sample,Function)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:2119:0.

StdDev -- a summary statistic for a list of objects
***************************************************

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

A sample standard deviation is -- along with sample mean -- one of the basic
summary statistics for a sample of randomly generated objects (or any list of
objects in general). The standard deviation value statistic for some property
of a list of objects is stored under the key StdDev in the hash table returned
by the function statistics.

+--------------------------------------------+
|i1 : s=sample(ER(6,3,0.2),100);             |
+--------------------------------------------+
|i2 : myStats = statistics(s, degree@@ideal);|
+--------------------------------------------+
|i3 : myStats.StdDev                         |
|                                            |
|o3 = 5.113462623311135                      |
|                                            |
|o3 : RR (of precision 53)                   |
+--------------------------------------------+

The last line returns the standard deviation of the degrees of the 100 ideals
in the sample $s$. Note that it is more meaningful to look at this value along
with the mean value rather than as a stand-alone statistic.

See also
========

  * Mean -- a summary statistic for a list of objects
  * statistics -- generate statistics for a sample

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

The object StdDev, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:2164:0.

VariableName -- optional input to choose the indexed variable name for the polynomial ring
******************************************************************************************

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

Put VariableName => x for a choice of string or symbol x as an argument in the
function randomMonomialSet, randomMonomialSets,
or randomMonomialIdeals,

+-----------------------------------------------+
|i1 : n=2; D=3; p=0.2;                          |
+-----------------------------------------------+
|i4 : randomMonomialSet(n,D,p)                  |
|                                               |
|       2   2     3                             |
|o4 = {x , x x , x }                            |
|       1   1 2   2                             |
|                                               |
|o4 : List                                      |
+-----------------------------------------------+
|i5 : randomMonomialSet(n,D,p,VariableName => y)|
|                                               |
|       2                                       |
|o5 = {y y }                                    |
|       1 2                                     |
|                                               |
|o5 : List                                      |
+-----------------------------------------------+

See also
========

  * randomMonomialSet -- randomly generates a list of
    monomials in fixed number of variables up to a given degree
  * randomMonomialSets -- randomly generates lists
    of monomials in fixed number of variables up to a given degree
  * randomMonomialIdeals -- generates random sets
    of monomial ideals

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

  * "randomMonomialIdeals(...,VariableName=>...)"
  * "randomMonomialSet(...,VariableName=>...)"
  * "randomMonomialSets(...,VariableName=>...)"

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

The object VariableName, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1302:0.

writeSample -- write sample data to a directory
***********************************************

  * Usage:
        writeSample(Sample,String)
  * Inputs:
      * S, an instance of the type Sample, to be written to a
        file
      * DirName, a string (Macaulay2Doc), name of the directory
        where the sample data should be stored

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

Write a random sample to a directory on disk. This function creates a directory
in which the model and data are stored: one text file contains the information
about the model used to generate the sample, and another text file contains the
information about the sample itself.

+-----------------------------------------------------------------+
|i1 : writeSample(sample(ER(2,3,0.1),5), "testDirectory")         |
+-----------------------------------------------------------------+
|i2 : mySample = sample("testDirectory")                          |
|                                                                 |
|o2 = Sample{...4...}                                             |
|                                                                 |
|o2 : Sample                                                      |
+-----------------------------------------------------------------+
|i3 : peek mySample                                               |
|                                                                 |
|o3 = Sample{ModelName => Erdos-Renyi                            }|
|            Parameters => (2, 3, .1)                             |
|            SampleSize => 5                                      |
|                       2   2            2       2          2     |
|            Data => {{x , x x }, {0}, {x x , x x }, {0}, {x x }} |
|                       1   1 2          1 2   1 2          1 2   |
+-----------------------------------------------------------------+

See also
========

  * Sample -- a type used to store a data sample from a
    statistical model
  * Model -- a type used to store a statistical model and its
    parameters
  * sample(String) -- creates an object of type
    Sample from a sample stored in a directory on disk

Ways to use writeSample:
========================

  * "writeSample(Sample,String)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RandomMonomialIdeals.m2:1864:0.