aGrUM 3.3.2
a C++ library for (probabilistic) graphical models
BNLearner.h
Go to the documentation of this file.
1/****************************************************************************
2 * This file is part of the aGrUM/pyAgrum library. *
3 * *
4 * Copyright (c) 2005-2026 by *
5 * - Pierre-Henri WUILLEMIN(_at_LIP6) *
6 * - Christophe GONZALES(_at_AMU) *
7 * *
8 * The aGrUM/pyAgrum library is free software; you can redistribute it *
9 * and/or modify it under the terms of either : *
10 * *
11 * - the GNU Lesser General Public License as published by *
12 * the Free Software Foundation, either version 3 of the License, *
13 * or (at your option) any later version, *
14 * - the MIT license (MIT), *
15 * - or both in dual license, as here. *
16 * *
17 * (see https://agrum.gitlab.io/articles/dual-licenses-lgplv3mit.html) *
18 * *
19 * This aGrUM/pyAgrum library is distributed in the hope that it will be *
20 * useful, but WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, *
21 * INCLUDING BUT NOT LIMITED TO THE WARRANTIES MERCHANTABILITY or FITNESS *
22 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE *
23 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER *
24 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, *
25 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR *
26 * OTHER DEALINGS IN THE SOFTWARE. *
27 * *
28 * See LICENCES for more details. *
29 * *
30 * SPDX-FileCopyrightText: Copyright 2005-2026 *
31 * - Pierre-Henri WUILLEMIN(_at_LIP6) *
32 * - Christophe GONZALES(_at_AMU) *
33 * SPDX-License-Identifier: LGPL-3.0-or-later OR MIT *
34 * *
35 * Contact : info_at_agrum_dot_org *
36 * homepage : http://agrum.gitlab.io *
37 * gitlab : https://gitlab.com/agrumery/agrum *
38 * *
39 ****************************************************************************/
40
41
50#ifndef GUM_LEARNING_BN_LEARNER_H
51#define GUM_LEARNING_BN_LEARNER_H
52
53#include <algorithm>
54#include <sstream>
55#include <vector>
56
57#include <agrum/agrum.h>
58
61
62namespace gum::learning {
64
72 template < GUM_Numeric GUM_SCALAR >
73 class BNLearner final: public IBNLearner {
74 public:
75 // ##########################################################################
77 // ##########################################################################
79
81
94 BNLearner(std::string_view filename,
95 const std::vector< std::string >& missingSymbols = {"?"},
96 const bool induceTypes = true);
97
99
106
111 BNLearner(std::string_view filename,
113 const std::vector< std::string >& missing_symbols = {"?"});
114
117
120
122 ~BNLearner() override;
123
125
126 // ##########################################################################
128 // ##########################################################################
130
133
136
138
140 BayesNet< GUM_SCALAR > learnBN();
141
163 BayesNet< GUM_SCALAR > learnParameters(const DAG& dag, bool takeIntoAccountScore = true);
164
195 BayesNet< GUM_SCALAR > learnParameters(const BayesNet< GUM_SCALAR >& bn,
196 bool takeIntoAccountScore = true);
197
220 BayesNet< GUM_SCALAR > learnParameters(bool take_into_account_score = true);
221
223 std::string toString() const;
224
226 std::vector< std::tuple< std::string, std::string, std::string > > state() const;
227
232 void copyState(const BNLearner< GUM_SCALAR >& learner);
233
234 //=== === add return to certain methods in order to chain command
235 BNLearner< GUM_SCALAR >& setInitialDAG(const DAG& dag);
236
257 BNLearner< GUM_SCALAR >& useEM(const double epsilon, const double noise);
258
261 BNLearner< GUM_SCALAR >& useEM(const double epsilon);
262
280 BNLearner< GUM_SCALAR >& useEMWithRateCriterion(const double epsilon, const double noise);
281
284 BNLearner< GUM_SCALAR >& useEMWithRateCriterion(const double epsilon);
285
300 BNLearner< GUM_SCALAR >& useEMWithDiffCriterion(const double epsilon, const double noise);
301
304 BNLearner< GUM_SCALAR >& useEMWithDiffCriterion(const double epsilon);
305
307 BNLearner< GUM_SCALAR >& forbidEM();
308
317 BNLearner< GUM_SCALAR >& EMsetEpsilon(const double eps);
318
320 BNLearner< GUM_SCALAR >& EMdisableEpsilon();
321
327 BNLearner< GUM_SCALAR >& EMenableEpsilon();
328
337 BNLearner< GUM_SCALAR >& EMsetMinEpsilonRate(const double rate);
338
341
348
354 BNLearner< GUM_SCALAR >& EMsetMaxIter(const Size max);
355
357 BNLearner< GUM_SCALAR >& EMdisableMaxIter();
358
360 BNLearner< GUM_SCALAR >& EMenableMaxIter();
361
367 BNLearner< GUM_SCALAR >& EMsetMaxTime(const double timeout);
368
370 BNLearner< GUM_SCALAR >& EMdisableMaxTime();
371
373 BNLearner< GUM_SCALAR >& EMenableMaxTime();
374
379 BNLearner< GUM_SCALAR >& EMsetPeriodSize(const Size p);
380
381 // for pyagrum support
383
385 BNLearner< GUM_SCALAR >& EMsetVerbosity(const bool v);
386
387 BNLearner< GUM_SCALAR >& useScoreAIC();
388
389 BNLearner< GUM_SCALAR >& useScoreBD();
390
391 BNLearner< GUM_SCALAR >& useScoreBDeu();
392
393 BNLearner< GUM_SCALAR >& useScoreBIC();
394
395 BNLearner< GUM_SCALAR >& useScoreK2();
396
398
399 BNLearner< GUM_SCALAR >& useNoPrior();
400
401 BNLearner< GUM_SCALAR >& useBDeuPrior(double weight);
402
404 BNLearner< GUM_SCALAR >& useBDeuPrior();
405
406 BNLearner< GUM_SCALAR >& useSmoothingPrior(double weight);
407
409 BNLearner< GUM_SCALAR >& useSmoothingPrior();
410
411 BNLearner< GUM_SCALAR >& useDirichletPrior(std::string_view filename, double weight);
412
414 BNLearner< GUM_SCALAR >& useDirichletPrior(std::string_view filename);
415
416 BNLearner< GUM_SCALAR >& useDirichletPrior(const gum::BayesNet< GUM_SCALAR >& bn,
417 double weight);
418
420 BNLearner< GUM_SCALAR >& useDirichletPrior(const gum::BayesNet< GUM_SCALAR >& bn);
421
423
425
427
428 BNLearner< GUM_SCALAR >& setGreedyThickThinningReversals(bool allow);
429
431
432 BNLearner< GUM_SCALAR >& useLocalSearchWithTabuList(Size tabu_size, Size nb_decrease);
433
436 BNLearner< GUM_SCALAR >& useLocalSearchWithTabuList(Size tabu_size);
437
441
442 BNLearner< GUM_SCALAR >& useK2(const Sequence< NodeId >& order);
443
444 BNLearner< GUM_SCALAR >& useK2(const std::vector< NodeId >& order);
445
446 BNLearner< GUM_SCALAR >& useMIIC();
447
448 BNLearner< GUM_SCALAR >& usePC();
449
450 BNLearner< GUM_SCALAR >& useFCI();
451
452 BNLearner< GUM_SCALAR >& useFCIChi2Test();
453
454 BNLearner< GUM_SCALAR >& useFCIG2Test();
455
456 BNLearner< GUM_SCALAR >& setFCIAlpha(double alpha);
457
458 BNLearner< GUM_SCALAR >& setFCIMaxPathLength(Size max_len);
459
460 BNLearner< GUM_SCALAR >& setFCIExhaustiveSepSet(bool exhaustive);
461
463
464 BNLearner< GUM_SCALAR >& useChi2Test();
465
466 BNLearner< GUM_SCALAR >& useG2Test();
467
468 BNLearner< GUM_SCALAR >& setPCAlpha(double alpha);
469
470 BNLearner< GUM_SCALAR >& setPCStable(bool stable);
471
472 BNLearner< GUM_SCALAR >& setPCMaxCondSetSize(Size max_k);
473
474 BNLearner< GUM_SCALAR >& setPCUnshieldedColliderSorted(bool sorted);
475
476 BNLearner< GUM_SCALAR >& useNMLCorrection();
477
478 BNLearner< GUM_SCALAR >& useMDLCorrection();
479
480 BNLearner< GUM_SCALAR >& useNoCorrection();
481
482 BNLearner< GUM_SCALAR >& setMaxIndegree(Size max_indegree);
483
484 BNLearner< GUM_SCALAR >& setSliceOrder(const NodeProperty< NodeId >& slice_order);
485
486 BNLearner< GUM_SCALAR >& setSliceOrder(const std::vector< std::vector< std::string > >& slices);
487
488 BNLearner< GUM_SCALAR >& setTotalOrder(const std::vector< std::string >& order);
489
490 BNLearner< GUM_SCALAR >& setTotalOrder(const Sequence< NodeId >& order);
491
492 BNLearner< GUM_SCALAR >& setForbiddenArcs(const ArcSet& set);
493
494 BNLearner< GUM_SCALAR >& addForbiddenArc(const Arc& arc);
495
496 BNLearner< GUM_SCALAR >& addForbiddenArc(NodeId tail, NodeId head);
497
498 BNLearner< GUM_SCALAR >& addForbiddenArc(std::string_view tail, std::string_view head);
499
500 BNLearner< GUM_SCALAR >& eraseForbiddenArc(const Arc& arc);
501
502 BNLearner< GUM_SCALAR >& eraseForbiddenArc(NodeId tail, NodeId head);
503
504 BNLearner< GUM_SCALAR >& eraseForbiddenArc(std::string_view tail, std::string_view head);
505
506 BNLearner< GUM_SCALAR >& addMandatoryArc(const Arc& arc);
507
508 BNLearner< GUM_SCALAR >& addMandatoryArc(NodeId tail, NodeId head);
509
510 BNLearner< GUM_SCALAR >& addMandatoryArc(std::string_view tail, std::string_view head);
511
512 BNLearner< GUM_SCALAR >& eraseMandatoryArc(const Arc& arc);
513
514 BNLearner< GUM_SCALAR >& eraseMandatoryArc(NodeId tail, NodeId head);
515
516 BNLearner< GUM_SCALAR >& eraseMandatoryArc(std::string_view tail, std::string_view head);
517
518 BNLearner< GUM_SCALAR >& addPossibleEdge(const Edge& edge);
519
520 BNLearner< GUM_SCALAR >& addPossibleEdge(NodeId tail, NodeId head);
521
522 BNLearner< GUM_SCALAR >& addPossibleEdge(std::string_view tail, std::string_view head);
523
524 BNLearner< GUM_SCALAR >& erasePossibleEdge(const Edge& edge);
525
526 BNLearner< GUM_SCALAR >& erasePossibleEdge(NodeId tail, NodeId head);
527
528 BNLearner< GUM_SCALAR >& erasePossibleEdge(std::string_view tail, std::string_view head);
529
530 BNLearner< GUM_SCALAR >& setMandatoryArcs(const ArcSet& set);
531
532 BNLearner< GUM_SCALAR >& setPossibleEdges(const EdgeSet& set);
533
534 BNLearner< GUM_SCALAR >& setPossibleSkeleton(const UndiGraph& skeleton);
535
536 BNLearner< GUM_SCALAR >& addNoParentNode(NodeId node);
537
538 BNLearner< GUM_SCALAR >& addNoParentNode(std::string_view name);
539
540 BNLearner< GUM_SCALAR >& eraseNoParentNode(NodeId node);
541
542 BNLearner< GUM_SCALAR >& eraseNoParentNode(std::string_view name);
543
544 BNLearner< GUM_SCALAR >& addNoChildrenNode(NodeId node);
545
546 BNLearner< GUM_SCALAR >& addNoChildrenNode(std::string_view name);
547
549
550 BNLearner< GUM_SCALAR >& eraseNoChildrenNode(std::string_view name);
551
552 BNLearner< GUM_SCALAR >& allowArcAdditions(bool allow);
553
554 BNLearner< GUM_SCALAR >& allowArcDeletions(bool allow);
555
556 BNLearner< GUM_SCALAR >& allowArcReversals(bool allow);
557
558 BNLearner< GUM_SCALAR >& allowArcTriangleDeletions(bool allow);
559
560 bool isConstraintBased() const;
561
562 bool isScoreBased() const;
563
564 protected:
566 void createPrior_() override;
567
568 private:
569 BayesNet< GUM_SCALAR > _prior_bn_;
570
572 NodeProperty< Sequence< std::string > > _labelsFromBN_(std::string_view filename,
573 const BayesNet< GUM_SCALAR >& src);
574
581 void _checkDAGCompatibility_(const DAG& dag);
582
601 BayesNet< GUM_SCALAR > _learnParameters_(const DAG& dag, bool takeIntoAccountScore);
602
622 std::pair< std::shared_ptr< ParamEstimator >, std::shared_ptr< ParamEstimator > >
623 _initializeEMParameterLearning_(const DAG& dag, bool takeIntoAccountScore);
624
645 BayesNet< GUM_SCALAR > _learnParametersWithEM_(const DAG& dag, bool takeIntoAccountScore);
646
673 BayesNet< GUM_SCALAR > _learnParametersWithEM_(const BayesNet< GUM_SCALAR >& bn,
674 bool takeIntoAccountScore);
675 };
676
678 template < GUM_Numeric GUM_SCALAR >
679 std::ostream& operator<<(std::ostream& output, const BNLearner< GUM_SCALAR >& learner);
680} // namespace gum::learning
681
683#include <agrum/BN/learning/BNLearner_tpl.h>
684
685#endif /* GUM_LEARNING_BN_LEARNER_H */
A dirichlet priori: computes its N'_ijk from a bayesian network.
A class for generic framework of learning algorithms that can easily be used.
The base class for all directed edges.
Class representing a Bayesian network.
Definition BayesNet.h:99
Base class for dag.
Definition DAG.h:121
The base class for all undirected edges.
The generic class for storing (ordered) sequences of objects.
Definition sequence.h:994
Base class for undirected graphs.
Definition undiGraph.h:134
A class that redirects gum_signal from algorithms to the listeners of BNLearn.
A pack of learning algorithms that can easily be used.
Definition BNLearner.h:73
BNLearner< GUM_SCALAR > & useNoPrior()
BNLearner< GUM_SCALAR > & EMdisableMaxIter()
Disable stopping criterion on max iterations.
BNLearner< GUM_SCALAR > & useFCIChi2Test()
BNLearner< GUM_SCALAR > & EMenableMinEpsilonRate()
Enable the log-likelihood evolution rate stopping criterion.
BNLearner< GUM_SCALAR > & useGreedyThickThinning()
BNLearner< GUM_SCALAR > & addForbiddenArc(const Arc &arc)
BNLearner< GUM_SCALAR > & useScoreAIC()
BNLearner< GUM_SCALAR > & eraseMandatoryArc(const Arc &arc)
BNLearner< GUM_SCALAR > & setTotalOrder(const std::vector< std::string > &order)
BNLearner< GUM_SCALAR > & EMdisableEpsilon()
Disable the min log-likelihood diff stopping criterion.
BNLearner< GUM_SCALAR > & addPossibleEdge(const Edge &edge)
BNLearner< GUM_SCALAR > & useScoreBD()
BNLearner< GUM_SCALAR > & allowArcReversals(bool allow)
std::vector< std::tuple< std::string, std::string, std::string > > state() const
BNLearner< GUM_SCALAR > & setPCStable(bool stable)
BNLearner< GUM_SCALAR > & addMandatoryArc(const Arc &arc)
BNLearner< GUM_SCALAR > & useDirichletPrior(std::string_view filename, double weight)
BNLearner< GUM_SCALAR > & useScoreBIC()
BNLearner< GUM_SCALAR > & usePC()
BNLearner< GUM_SCALAR > & useNoCorrection()
std::pair< std::shared_ptr< ParamEstimator >, std::shared_ptr< ParamEstimator > > _initializeEMParameterLearning_(const DAG &dag, bool takeIntoAccountScore)
initializes EM and returns a pair containing, first, a bootstrap estimator and, second,...
BNLearner< GUM_SCALAR > & useG2Test()
BNLearner< GUM_SCALAR > & setFCIMaxPathLength(Size max_len)
BNLearner(std::string_view filename, const gum::BayesNet< GUM_SCALAR > &src, const std::vector< std::string > &missing_symbols={"?"})
Wrapper for BNLearner (filename,modalities,parse_database) using a bn to find those modalities and no...
BNLearner< GUM_SCALAR > & EMdisableMinEpsilonRate()
Disable the log-likelihood evolution rate stopping criterion.
BNLearner(std::string_view filename, const std::vector< std::string > &missingSymbols={"?"}, const bool induceTypes=true)
default constructor
BNLearner(const BNLearner &)
copy constructor
BNLearner< GUM_SCALAR > & erasePossibleEdge(const Edge &edge)
BNLearner< GUM_SCALAR > & setGreedyThickThinningReversals(bool allow)
BNLearner & operator=(BNLearner &&) noexcept
move operator
BNLearner< GUM_SCALAR > & setPossibleSkeleton(const UndiGraph &skeleton)
BayesNet< GUM_SCALAR > _learnParameters_(const DAG &dag, bool takeIntoAccountScore)
learns a BN (its parameters) with the structure passed in argument using a single pass estimation (no...
BNLearner(BNLearner &&)
move constructor
~BNLearner() override
destructor
BNLearner< GUM_SCALAR > & EMenableEpsilon()
Enable the log-likelihood min diff stopping criterion in EM.
BNLearner< GUM_SCALAR > & setPCMaxCondSetSize(Size max_k)
BNLearner< GUM_SCALAR > & setPossibleEdges(const EdgeSet &set)
BNLearner< GUM_SCALAR > & allowArcDeletions(bool allow)
BNLearner< GUM_SCALAR > & useEM(const double epsilon, const double noise)
use The EM algorithm to learn parameters
BNLearner< GUM_SCALAR > & setFCIExhaustiveSepSet(bool exhaustive)
BNLearner< GUM_SCALAR > & EMenableMaxTime()
enable EM's timeout stopping criterion
BayesNet< GUM_SCALAR > _learnParametersWithEM_(const DAG &dag, bool takeIntoAccountScore)
learns a BN (its parameters) with the structure passed in argument using the EM algorithm initialized...
BNLearner< GUM_SCALAR > & addNoChildrenNode(NodeId node)
BNLearner< GUM_SCALAR > & EMsetEpsilon(const double eps)
sets the stopping criterion of EM as being the minimal difference between two consecutive log-likelih...
BNLearner< GUM_SCALAR > & EMdisableMaxTime()
Disable EM's timeout stopping criterion.
BNLearner & operator=(const BNLearner &)
copy operator
bool greedyThickThinningReversals() const
BNLearner< GUM_SCALAR > & useGreedyHillClimbing()
BNLearner< GUM_SCALAR > & forbidEM()
prevent using the EM algorithm for parameter learning
BNLearner< GUM_SCALAR > & useK2(const Sequence< NodeId > &order)
BNLearner< GUM_SCALAR > & useExtendedGreedyHillClimbing()
BNLearner< GUM_SCALAR > & useScoreK2()
BNLearner< GUM_SCALAR > & setMandatoryArcs(const ArcSet &set)
BNLearner< GUM_SCALAR > & eraseNoChildrenNode(NodeId node)
BNLearner< GUM_SCALAR > & useMIIC()
bool fciExhaustiveSepSet() const
BNLearner< GUM_SCALAR > & EMsetPeriodSize(const Size p)
how many samples between 2 stoppings isEnabled
BayesNet< GUM_SCALAR > learnBN()
learn a Bayes Net from a file (must have read the db before)
BNLearner< GUM_SCALAR > & useEMWithDiffCriterion(const double epsilon, const double noise)
use The EM algorithm to learn parameters with the diff stopping criterion
BNLearner< GUM_SCALAR > & setForbiddenArcs(const ArcSet &set)
bool isConstraintBased() const
BNLearner< GUM_SCALAR > & setInitialDAG(const DAG &dag)
BNLearner< GUM_SCALAR > & addNoParentNode(NodeId node)
BNLearner< GUM_SCALAR > & setPCAlpha(double alpha)
BNLearner< GUM_SCALAR > & useScoreLog2Likelihood()
BNLearner< GUM_SCALAR > & useLocalSearchWithTabuList(Size tabu_size, Size nb_decrease)
BayesNet< GUM_SCALAR > _prior_bn_
Definition BNLearner.h:569
BNLearner< GUM_SCALAR > & useBDeuPrior(double weight)
BNLearner< GUM_SCALAR > & EMsetMaxIter(const Size max)
add a max iteration stopping criterion
BNLearner< GUM_SCALAR > & useFCI()
BNLearner(const DatabaseTable &db)
default constructor
BNLearner< GUM_SCALAR > & EMsetMinEpsilonRate(const double rate)
sets the stopping criterion of EM as being the minimal log-likelihood's evolution rate
BNLearner< GUM_SCALAR > & allowArcTriangleDeletions(bool allow)
NodeProperty< Sequence< std::string > > _labelsFromBN_(std::string_view filename, const BayesNet< GUM_SCALAR > &src)
read the first line of a file to find column names
BNLearner< GUM_SCALAR > & useMDLCorrection()
BNLearner< GUM_SCALAR > & eraseNoParentNode(NodeId node)
BNLearner< GUM_SCALAR > & allowArcAdditions(bool allow)
BNLearner< GUM_SCALAR > & useSmoothingPrior(double weight)
BNLearner< GUM_SCALAR > & EMsetVerbosity(const bool v)
sets or unsets EM's verbosity
BNLearner< GUM_SCALAR > & eraseForbiddenArc(const Arc &arc)
BayesNet< GUM_SCALAR > learnParameters(const DAG &dag, bool takeIntoAccountScore=true)
learns a BN (its parameters) with the structure passed in argument
BNLearner< GUM_SCALAR > & setFCIAlpha(double alpha)
BNLearner< GUM_SCALAR > & useFCIG2Test()
void _checkDAGCompatibility_(const DAG &dag)
check that the database contains the nodes of the dag, else raise an exception
BNLearner< GUM_SCALAR > & useNMLCorrection()
BNLearner< GUM_SCALAR > & useEMWithRateCriterion(const double epsilon, const double noise)
use The EM algorithm to learn parameters with the rate stopping criterion
BNLearner< GUM_SCALAR > & setSliceOrder(const NodeProperty< NodeId > &slice_order)
std::string toString() const
void createPrior_() override
create the prior used for learning
BNLearner< GUM_SCALAR > & EMsetMaxTime(const double timeout)
add a stopping criterion on timeout
void copyState(const BNLearner< GUM_SCALAR > &learner)
copy the states of the BNLearner
BNLearner< GUM_SCALAR > & setPCUnshieldedColliderSorted(bool sorted)
BNLearner< GUM_SCALAR > & EMenableMaxIter()
Enable stopping criterion on max iterations.
BNLearner< GUM_SCALAR > & useChi2Test()
BNLearner< GUM_SCALAR > & useScoreBDeu()
BNLearner< GUM_SCALAR > & setMaxIndegree(Size max_indegree)
The class representing a tabular database as used by learning tasks.
double epsilon() const override
Get the value of epsilon.
IBNLearner(std::string_view filename, const std::vector< std::string > &missingSymbols, bool induceTypes=true)
read the database file for the score / parameter estimation and var names
The base class for estimating parameters of CPTs.
Complete concept for GUM_SCALAR template parameter.
Definition concepts.h:148
std::size_t Size
In aGrUM, hashed values are unsigned long int.
Definition types.h:74
Set< Edge > EdgeSet
Some typdefs and define for shortcuts ...
Size NodeId
Type for node ids.
Set< Arc > ArcSet
Some typdefs and define for shortcuts ...
HashTable< NodeId, VAL > NodeProperty
Property on graph elements.
include the inlined functions if necessary
Definition CSVParser.h:55
gum is the global namespace for all aGrUM entities
Definition agrum.h:46
STL namespace.