1 /**
2  *
3  *   Copyright (c) 2005-2021 by Pierre-Henri WUILLEMIN(_at_LIP6) & Christophe GONZALES(_at_AMU)
4  *   info_at_agrum_dot_org
5  *
6  *  This library is free software: you can redistribute it and/or modify
7  *  it under the terms of the GNU Lesser General Public License as published by
8  *  the Free Software Foundation, either version 3 of the License, or
9  *  (at your option) any later version.
10  *
11  *  This library is distributed in the hope that it will be useful,
12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  *  GNU Lesser General Public License for more details.
15  *
16  *  You should have received a copy of the GNU Lesser General Public License
17  *  along with this library.  If not, see <http://www.gnu.org/licenses/>.
18  *
19  */
20 
21 
22 /** @file
23  * @brief The K2 algorithm
24  *
25  * @author Christophe GONZALES(_at_AMU) and Pierre-Henri WUILLEMIN(_at_LIP6)
26  */
27 #ifndef GUM_LEARNING_K2_H
28 #define GUM_LEARNING_K2_H
29 
30 #include <string>
31 #include <vector>
32 
33 #include <agrum/BN/BayesNet.h>
34 #include <agrum/tools/core/sequence.h>
35 #include <agrum/tools/graphs/DAG.h>
36 #include <agrum/BN/learning/greedyHillClimbing.h>
37 
38 namespace gum {
39 
40   namespace learning {
41 
42     /** @class K2
43      * @brief The K2 algorithm
44      * @ingroup learning_group
45      */
46     class K2: private GreedyHillClimbing {
47       public:
48       // ##########################################################################
49       /// @name Constructors / Destructors
50       // ##########################################################################
51       /// @{
52 
53       /// default constructor
54       K2();
55 
56       /// copy constructor
57       K2(const K2& from);
58 
59       /// move constructor
60       K2(K2&& from);
61 
62       /// destructor
63       ~K2();
64 
65       /// @}
66 
67       // ##########################################################################
68       /// @name Operators
69       // ##########################################################################
70       /// @{
71 
72       /// copy operator
73       K2& operator=(const K2& from);
74 
75       /// move operator
76       K2& operator=(K2&& from);
77 
78       /// @}
79 
80       // ##########################################################################
81       /// @name Accessors / Modifiers
82       // ##########################################################################
83       /// @{
84 
85       /// returns the approximation policy of the learning algorithm
86       ApproximationScheme& approximationScheme();
87 
88       /// sets the order on the variables
89       void setOrder(const Sequence< NodeId >& order);
90 
91       /// sets the order on the variables
92       void setOrder(const std::vector< NodeId >& order);
93 
94       /// returns the current order
95       const Sequence< NodeId >& order() const noexcept;
96 
97       /// learns the structure of a Bayes net
98       /**
99        * @param selector A selector class that computes the best changes that
100        * can be applied and that enables the user to get them very easily.
101        * Typically, the selector is a GraphChangesSelector4DiGraph<SCORE,
102        * STRUCT_CONSTRAINT, GRAPH_CHANGES_GENERATOR>.
103        * @param initial_dag the DAG we start from for our learning */
104       template < typename GRAPH_CHANGES_SELECTOR >
105       DAG learnStructure(GRAPH_CHANGES_SELECTOR& selector, DAG initial_dag = DAG());
106 
107       /// learns the structure and the parameters of a BN
108       template < typename GUM_SCALAR, typename GRAPH_CHANGES_SELECTOR, typename PARAM_ESTIMATOR >
109       BayesNet< GUM_SCALAR > learnBN(GRAPH_CHANGES_SELECTOR& selector,
110                                      PARAM_ESTIMATOR&        estimator,
111                                      DAG                     initial_dag = DAG());
112 
113       private:
114       /// the order on the variable used for learning
115       Sequence< NodeId > _order_;
116 
117       /** @brief checks that the order passed to K2 is coherent with the
118        * variables
119        * as specified by their modalities */
120       void _checkOrder_(const std::vector< Size >& modal);
121       /// @}
122     };
123 
124   } /* namespace learning */
125 
126 } /* namespace gum */
127 
128 /// include the inlined functions if necessary
129 #ifndef GUM_NO_INLINE
130 #  include <agrum/BN/learning/K2_inl.h>
131 #endif /* GUM_NO_INLINE */
132 
133 /// always include templated methods
134 #include <agrum/BN/learning/K2_tpl.h>
135 
136 #endif /* GUM_LEARNING_K2_H */
137