/****************************************************************************
 *   This file is part of the aGrUM/pyAgrum library.                        *
 *                                                                          *
 *   Copyright (c) 2005-2025 by                                             *
 *       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 *
 *       - Christophe GONZALES(_at_AMU)                                     *
 *                                                                          *
 *   The aGrUM/pyAgrum library is free software; you can redistribute it    *
 *   and/or modify it under the terms of either :                           *
 *                                                                          *
 *    - the GNU Lesser General Public License as published by               *
 *      the Free Software Foundation, either version 3 of the License,      *
 *      or (at your option) any later version,                              *
 *    - the MIT license (MIT),                                              *
 *    - or both in dual license, as here.                                   *
 *                                                                          *
 *   (see https://agrum.gitlab.io/articles/dual-licenses-lgplv3mit.html)    *
 *                                                                          *
 *   This aGrUM/pyAgrum library is distributed in the hope that it will be  *
 *   useful, but WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,          *
 *   INCLUDING BUT NOT LIMITED TO THE WARRANTIES MERCHANTABILITY or FITNESS *
 *   FOR A PARTICULAR PURPOSE  AND NONINFRINGEMENT. IN NO EVENT SHALL THE   *
 *   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER *
 *   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,        *
 *   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR  *
 *   OTHER DEALINGS IN THE SOFTWARE.                                        *
 *                                                                          *
 *   See LICENCES for more details.                                         *
 *                                                                          *
 *   SPDX-FileCopyrightText: Copyright 2005-2025                            *
 *       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 *
 *       - Christophe GONZALES(_at_AMU)                                     *
 *   SPDX-License-Identifier: LGPL-3.0-or-later OR MIT                      *
 *                                                                          *
 *   Contact  : info_at_agrum_dot_org                                       *
 *   homepage : http://agrum.gitlab.io                                      *
 *   gitlab   : https://gitlab.com/agrumery/agrum                           *
 *                                                                          *
 ****************************************************************************/






%feature("docstring") gum::learning::BNDatabaseGenerator
"
BNDatabaseGenerator is used to easily generate databases from a pyagrum.BayesNet.

Parameters
----------
bn: pyagrum.BayesNet
  the Bayesian network used to generate data.
"

%feature("docstring") gum::learning::BNDatabaseGenerator::drawSamples
"
Generate and stock a database generated by sampling the Bayesian network.

If `evs` is specified, the samples are stored only if there are compatible with these observations.

Returns the log2likelihood of this database.

Parameters
----------
nbSamples : int
	the number of samples that will be generated
evs : gum::Instantiation or Dict[int|str,int|str]
  (optional) The evidence that will be observed by the resulting samples.
timeout : int
  (optional) The maximum time in seconds to generate the samples (default 600)

Warning
-------
`nbSamples` is not the number of generated samples but the size of the database.It may happen that the evidence is very rare (or even impossible). In this case, the generation process may be *very* slow (it may even not stop). For this case a timeout is provided (default 600 seconds) and then the size of the database can be smaller than `nbSamples` (even equal to 0).

Warning
-------
For discretized variable, aGrum/pyAgrum defines 3 behaviors when generating sample with labels :
- RANDOM (default) : the value is chosen randomly in the interval
- MEDIAN : the value is the median of the interval
- INTERVAL : the value is the interval itself (for instance `« [0,1[ »`)

The behavior can be set using `setDiscretizedLabelMode{Random|Median|Interval}`.

Examples
--------
>>> import pyagrum as gum
>>> bn=gum.fastBN('A->B{yes|maybe|no}<-C->D->E<-F[1,1.5,3,10.2]<-B')
>>> g=gum.BNDatabaseGenerator(bn)
>>> g.setRandomVarOrder()
>>> g.drawSamples(5,
...               {'B':'yes','E':'1'})
-122.98754206579288
>>> g.setDiscretizedLabelModeRandom() # By default
>>> g.to_pandas()
     B         F  A  C  E  D
0  yes  2.802302  0  0  1  0
1  yes  1.761605  0  0  1  0
2  yes  2.507535  0  0  1  1
3  yes  2.815282  0  1  1  0
4  yes  5.548571  1  0  1  1
>>> g.setDiscretizedLabelModeMedian()
>>> g.to_pandas()
     B         F  A  C  E  D
0  yes  2.250000  0  0  1  0
1  yes  2.250000  0  0  1  0
2  yes  2.250000  0  0  1  1
3  yes  2.250000  0  1  1  0
4  yes  6.600000  1  0  1  1
>>> g.setDiscretizedLabelModeInterval()
>>> g.to_pandas()
     B         F  A  C  E  D
0  yes   [1.5;3[  0  0  1  0
1  yes   [1.5;3[  0  0  1  0
2  yes   [1.5;3[  0  0  1  1
3  yes   [1.5;3[  0  1  1  0
4  yes  [3;10.2]  1  0  1  1
"

%feature("docstring") gum::learning::BNDatabaseGenerator::toCSV
"
generates csv representing the generated database.

Parameters
----------
csvFilename: str
  the name of the csv file
useLabels: bool
  whether label or id in the csv file (default true)
append: bool
  append in the file or rewrite the file (default false)
csvSeparator: str
  separator in the csv file (default ',')
"

%feature("docstring") gum::learning::BNDatabaseGenerator::samplesNbRows
"
return the number of rows in the samples
"

%feature("docstring") gum::learning::BNDatabaseGenerator::samplesNbCols
"
return the number of columns in the samples
"

%feature("docstring") gum::learning::BNDatabaseGenerator::bn
"
Get the Bayesian network used to generate the samples

Returns
-------
pyagrum.BayesNet
  The Bayesian network

"

%feature("docstring") gum::learning::BNDatabaseGenerator::log2likelihood
"
Get the  log2likelihood of the generated database

Raises
------
pyagrum.OperationNotAllowed
  if nothing has been sampled yet (using `gum.BNDatabaseGenerator.drawSamples()` for instance)

Returns
-------
float
  the log2likelihood
"

%feature("docstring") gum::learning::BNDatabaseGenerator::samplesAt
"
Get the value of the database in (row,col)

Parameters
----------
row : int
  the row
col : int
  the column (using the ordered list of variables)

Returns
-------
int
  the index of the modality of the variable in this position
"

%feature("docstring") gum::learning::BNDatabaseGenerator::samplesLabelAt
"
Get the label of the database in (row,col)

Parameters
----------
row : int
  the row
col : int
  the column (using the ordered list of variables)

Returns
-------
str
  the label of the modality of the variable in this position
"

%feature("docstring") gum::learning::BNDatabaseGenerator::setAntiTopologicalVarOrder
"
Select an anti-topological order for the variables in the database.
"

%feature("docstring") gum::learning::BNDatabaseGenerator::setRandomVarOrder
"
Select an random order for the variables in the database.
"

%feature("docstring") gum::learning::BNDatabaseGenerator::setTopologicalVarOrder
"
Select a topological order for the variables in the database.
"

%feature("docstring") gum::learning::BNDatabaseGenerator::setVarOrder
"
Set a specific order with a list of names

Parameters
----------
vars : List[str]
  order specified by the list of variable names.
"

%feature("docstring") gum::learning::BNDatabaseGenerator::setVarOrderFromCSV
"
Set the same order than in a csv file

Parameters
----------
filename:str
  the name of the CSV file
"

%feature("docstring") gum::learning::BNDatabaseGenerator::varOrder
"
The actual order for the variable (as a tuple of NodeId)

Returns
-------
Tuple[int]
  the tuple of NodeId
"

%feature("docstring") gum::learning::BNDatabaseGenerator::varOrderNames
"
The actual order for the variable (as a tuple of NodeId)

Returns
-------
Tuple[str]
  the tuple of names
"

%feature("docstring") gum::learning::BNDatabaseGenerator::setDiscretizedLabelModeInterval
"
Set the discretized label mode to INTERVAL : sampling a `pyagrum.discretizedVariable` will give a deterministic value : the string representation of the interval.

Examples
--------
>>> import pyagrum as gum
>>> bn=gum.fastBN('A->B{yes|maybe|no}<-C->D->E<-F[1,1.5,3,10.2]<-B')
>>> g=gum.BNDatabaseGenerator(bn)
>>> g.setRandomVarOrder()
>>> g.drawSamples(5,
...               {'B':'yes','E':'1'})
-122.98754206579288
>>> g.setDiscretizedLabelModeInterval()
>>> g.to_pandas()
     B         F  A  C  E  D
0  yes   [1.5;3[  0  0  1  0
1  yes   [1.5;3[  0  0  1  0
2  yes   [1.5;3[  0  0  1  1
3  yes   [1.5;3[  0  1  1  0
4  yes  [3;10.2]  1  0  1  1
"

%feature("docstring") gum::learning::BNDatabaseGenerator::setDiscretizedLabelModeMedian
"
Set the discretized label mode to MEDIAN : sampling a `pyagrum.discretizedVariable` will give a deterministic value : the median of the uniform distribution on that interval.

Examples
--------
>>> import pyagrum as gum
>>> bn=gum.fastBN('A->B{yes|maybe|no}<-C->D->E<-F[1,1.5,3,10.2]<-B')
>>> g=gum.BNDatabaseGenerator(bn)
>>> g.setRandomVarOrder()
>>> g.drawSamples(5,
...               {'B':'yes','E':'1'})
-122.98754206579288
>>> g.setDiscretizedLabelModeMedian()
>>> g.to_pandas()
     B         F  A  C  E  D
0  yes  2.250000  0  0  1  0
1  yes  2.250000  0  0  1  0
2  yes  2.250000  0  0  1  1
3  yes  2.250000  0  1  1  0
4  yes  6.600000  1  0  1  1
"

%feature("docstring") gum::learning::BNDatabaseGenerator::setDiscretizedLabelModeRandom
"
Set the discretized label mode to RANDOM (default mode) : sampling a `pyagrum.discretizedVariable` will give a random value from the uniform distribution on that interval.

Examples
--------
>>> import pyagrum as gum
>>> bn=gum.fastBN('A->B{yes|maybe|no}<-C->D->E<-F[1,1.5,3,10.2]<-B')
>>> g=gum.BNDatabaseGenerator(bn)
>>> g.setRandomVarOrder()
>>> g.drawSamples(5,
...               {'B':'yes','E':'1'})
-122.98754206579288
>>> g.setDiscretizedLabelModeRandom() # By default
>>> g.to_pandas()
     B         F  A  C  E  D
0  yes  2.802302  0  0  1  0
1  yes  1.761605  0  0  1  0
2  yes  2.507535  0  0  1  1
3  yes  2.815282  0  1  1  0
4  yes  5.548571  1  0  1  1
"
