aGrUM 3.3.2
a C++ library for (probabilistic) graphical models
IKTBNLearner.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
76
77#ifndef GUM_LEARNING_IKTBN_LEARNER_H
78#define GUM_LEARNING_IKTBN_LEARNER_H
79
80#include <cctype>
81#include <filesystem>
82#include <fstream>
83#include <numeric>
84#include <string>
85#include <utility>
86#include <vector>
87
88#include <agrum/agrum.h>
89
91#include <agrum/KTBN/KTBN.h>
92
93#include <string_view>
94#include <unordered_set>
95
96namespace gum {
97
98 namespace learning {
99
109 template < GUM_Numeric GUM_SCALAR >
111 public:
113 virtual ~IKTBNLearner() = default;
114
115 // #######################################################################
117 // #######################################################################
119
123 virtual KTBN< GUM_SCALAR > learnKTBN() = 0;
124
126 // #######################################################################
128 // #######################################################################
130
137 virtual void useScorefNML() = 0;
138
140 // #######################################################################
142 // #######################################################################
144
148 Size nb_decrease) = 0;
159
161 // #######################################################################
163 // #######################################################################
165
169
171 // #######################################################################
173 // #######################################################################
175
180
182 // #######################################################################
184 // #######################################################################
186
188 virtual IKTBNLearner< GUM_SCALAR >& addForbiddenArc(std::string_view tailNode,
189 std::string_view headNode) = 0;
190
192 virtual IKTBNLearner< GUM_SCALAR >& addForbiddenArc(std::string_view tailBase,
193 int tailSlice,
194 std::string_view headBase,
195 int headSlice) = 0;
196
198 virtual IKTBNLearner< GUM_SCALAR >& eraseForbiddenArc(std::string_view tailNode,
199 std::string_view headNode) = 0;
200
202 virtual IKTBNLearner< GUM_SCALAR >& eraseForbiddenArc(std::string_view tailBase,
203 int tailSlice,
204 std::string_view headBase,
205 int headSlice) = 0;
206
208 virtual IKTBNLearner< GUM_SCALAR >& addMandatoryArc(std::string_view tailNode,
209 std::string_view headNode) = 0;
210
212 virtual IKTBNLearner< GUM_SCALAR >& addMandatoryArc(std::string_view tailBase,
213 int tailSlice,
214 std::string_view headBase,
215 int headSlice) = 0;
216
218 virtual IKTBNLearner< GUM_SCALAR >& eraseMandatoryArc(std::string_view tailNode,
219 std::string_view headNode) = 0;
220
222 virtual IKTBNLearner< GUM_SCALAR >& eraseMandatoryArc(std::string_view tailBase,
223 int tailSlice,
224 std::string_view headBase,
225 int headSlice) = 0;
226
228 virtual IKTBNLearner< GUM_SCALAR >& addForbiddenIntraSliceArc(std::string_view tailBase,
229 std::string_view headBase) = 0;
230
232 virtual IKTBNLearner< GUM_SCALAR >& eraseForbiddenIntraSliceArc(std::string_view tailBase,
233 std::string_view headBase)
234 = 0;
235
237 virtual IKTBNLearner< GUM_SCALAR >& addForbiddenArcAllSlices(std::string_view tailBase,
238 std::string_view headBase) = 0;
239
241 virtual IKTBNLearner< GUM_SCALAR >& eraseForbiddenArcAllSlices(std::string_view tailBase,
242 std::string_view headBase) = 0;
243
245 virtual IKTBNLearner< GUM_SCALAR >& addNoParentNode(std::string_view base, int slice) = 0;
246
248 virtual IKTBNLearner< GUM_SCALAR >& addNoParentNode(std::string_view name) = 0;
249
251 virtual IKTBNLearner< GUM_SCALAR >& eraseNoParentNode(std::string_view base, int slice) = 0;
252
254 virtual IKTBNLearner< GUM_SCALAR >& eraseNoParentNode(std::string_view name) = 0;
255
257 virtual IKTBNLearner< GUM_SCALAR >& addNoChildrenNode(std::string_view base, int slice) = 0;
258
260 virtual IKTBNLearner< GUM_SCALAR >& addNoChildrenNode(std::string_view name) = 0;
261
263 virtual IKTBNLearner< GUM_SCALAR >& eraseNoChildrenNode(std::string_view base, int slice) = 0;
264
266 virtual IKTBNLearner< GUM_SCALAR >& eraseNoChildrenNode(std::string_view name) = 0;
267
269 virtual IKTBNLearner< GUM_SCALAR >& addPossibleEdge(std::string_view tailBase,
270 int tailSlice,
271 std::string_view headBase,
272 int headSlice) = 0;
273
275 virtual IKTBNLearner< GUM_SCALAR >& addPossibleEdge(std::string_view tail,
276 std::string_view head) = 0;
277
279 virtual IKTBNLearner< GUM_SCALAR >& erasePossibleEdge(std::string_view tailBase,
280 int tailSlice,
281 std::string_view headBase,
282 int headSlice) = 0;
283
285 virtual IKTBNLearner< GUM_SCALAR >& erasePossibleEdge(std::string_view tail,
286 std::string_view head) = 0;
287
289 virtual IKTBNLearner< GUM_SCALAR >& allowArcAdditions(bool allow = true) = 0;
290
292 virtual IKTBNLearner< GUM_SCALAR >& allowArcDeletions(bool allow = true) = 0;
293
295 virtual IKTBNLearner< GUM_SCALAR >& allowArcReversals(bool allow = true) = 0;
296
299
301
302 protected:
303 // #######################################################################
305 // #######################################################################
307
309 static Size defaultTabuListSize_();
313 static double defaultPriorWeight_();
314
316
317 // #######################################################################
319 // #######################################################################
321
326 virtual const std::unordered_set< std::string >& _atemporalVarNames_() const = 0;
327
334 virtual bool _isKnownBase_(std::string_view base) const = 0;
335
338 std::string _encode_(std::string_view base, int slice) const;
339
343 std::pair< std::string, int > _determineNode_(const std::string& name) const;
344
352 void _checkArcTemporallyFeasible_(std::string_view tail,
353 std::string_view head,
354 std::string_view action) const;
355
361 void _checkBaseIsTemporal_(std::string_view base, std::string_view context) const;
362
372 static void _checkMinimalOrder_(Size order, std::string_view label);
373
391 static std::unordered_set< std::string >
392 _scanConstantColumns_(std::string_view dirPath,
393 std::string_view csvBaseName,
394 Size nbSamples,
395 const std::vector< std::string >& missingSymbols);
396
398 };
399
400#ifndef GUM_NO_EXTERN_TEMPLATE_CLASS
401 extern template class GUM_PUBLIC_KTBN IKTBNLearner< double >;
402#endif
403
404 } /* namespace learning */
405} /* namespace gum */
406
408
409#endif /* GUM_LEARNING_IKTBN_LEARNER_H */
Class for fast parsing of CSV file (never more than one line in application memory).
Template implementation of the IKTBNLearner class.
Class representing k-order dynamic Bayesian networks (k-DBN).
Pure-virtual configuration interface shared by all k-TBN learners.
virtual IKTBNLearner< GUM_SCALAR > & erasePossibleEdge(std::string_view tail, std::string_view head)=0
Undo a previous addPossibleEdge using engine names (e.g. "X[1]", "C").
virtual IKTBNLearner< GUM_SCALAR > & eraseNoParentNode(std::string_view base, int slice)=0
Undo a previous addNoParentNode for a single (base, slice) node.
virtual IKTBNLearner< GUM_SCALAR > & useNMLCorrection()=0
virtual IKTBNLearner< GUM_SCALAR > & allowArcReversals(bool allow=true)=0
Allow or forbid arc reversals during structure search.
virtual bool _isKnownBase_(std::string_view base) const =0
Whether base is one of this learner's variables, temporal or atemporal. The second subclass-specific ...
virtual IKTBNLearner< GUM_SCALAR > & addForbiddenIntraSliceArc(std::string_view tailBase, std::string_view headBase)=0
Forbid tailBase -> headBase at every intra-slice position.
virtual IKTBNLearner< GUM_SCALAR > & useSmoothingPrior(double weight)=0
smoothing prior with the default weight (key priorWeight of the section learning of gum::Configuratio...
virtual IKTBNLearner< GUM_SCALAR > & addForbiddenArc(std::string_view tailNode, std::string_view headNode)=0
Forbid tailNode -> headNode (engine names, e.g. "X[1]", "C").
void _checkBaseIsTemporal_(std::string_view base, std::string_view context) const
Throw InvalidArgument unless base is a known temporal base. context completes "cannot appear in <cont...
virtual IKTBNLearner< GUM_SCALAR > & eraseMandatoryArc(std::string_view tailNode, std::string_view headNode)=0
Undo a previous addMandatoryArc (engine names).
virtual IKTBNLearner< GUM_SCALAR > & useScoreMDL()=0
virtual IKTBNLearner< GUM_SCALAR > & useExtendedGreedyHillClimbing()=0
local search with tabu list, with the default number of decreasing changes (key tabuNbDecrease of the...
void _checkArcTemporallyFeasible_(std::string_view tail, std::string_view head, std::string_view action) const
Reject an arc the k-TBN definition can never contain, so eraseForbiddenArc and addMandatoryArc both f...
virtual IKTBNLearner< GUM_SCALAR > & useScoreBD()=0
static std::unordered_set< std::string > _scanConstantColumns_(std::string_view dirPath, std::string_view csvBaseName, Size nbSamples, const std::vector< std::string > &missingSymbols)
Scans every trajectory and returns the base names classified atemporal: those whose value never chang...
virtual const std::unordered_set< std::string > & _atemporalVarNames_() const =0
The base names of the atemporal (static) variables. The only subclass-specific input to determineNode...
virtual IKTBNLearner< GUM_SCALAR > & addNoParentNode(std::string_view name)=0
Declare a single node (bracket notation, e.g. "X[2]" or "C") as a root.
static void _checkMinimalOrder_(Size order, std::string_view label)
Throw InvalidArgument unless order is at least 2, label naming the offending parameter ("k" for the f...
virtual IKTBNLearner< GUM_SCALAR > & eraseForbiddenIntraSliceArc(std::string_view tailBase, std::string_view headBase)=0
Undo a previous addForbiddenIntraSliceArc.
static double defaultPriorWeight_()
virtual IKTBNLearner< GUM_SCALAR > & useMIIC()=0
local search with tabu list, with the default number of decreasing changes (key tabuNbDecrease of the...
virtual IKTBNLearner< GUM_SCALAR > & addMandatoryArc(std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice)=0
Force one arc, lag stated explicitly via slices (KTBN::ATEMPORAL for static).
virtual IKTBNLearner< GUM_SCALAR > & eraseNoParentNode(std::string_view name)=0
Undo addNoParentNode for a node given by bracket notation.
virtual IKTBNLearner< GUM_SCALAR > & useGreedyThickThinning()=0
local search with tabu list, with the default number of decreasing changes (key tabuNbDecrease of the...
virtual IKTBNLearner< GUM_SCALAR > & useGreedyHillClimbing()=0
local search with tabu list, with the default number of decreasing changes (key tabuNbDecrease of the...
virtual void useScorefNML()=0
virtual IKTBNLearner< GUM_SCALAR > & eraseNoChildrenNode(std::string_view base, int slice)=0
Undo a previous addNoChildrenNode for a single (base, slice) node.
virtual IKTBNLearner< GUM_SCALAR > & useMDLCorrection()=0
virtual IKTBNLearner< GUM_SCALAR > & addNoParentNode(std::string_view base, int slice)=0
Declare a single (base, slice) node as a root (no parents).
virtual IKTBNLearner< GUM_SCALAR > & addForbiddenArc(std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice)=0
Forbid one (base, slice) -> (base, slice) arc (KTBN::ATEMPORAL for static).
virtual IKTBNLearner< GUM_SCALAR > & usePC()=0
local search with tabu list, with the default number of decreasing changes (key tabuNbDecrease of the...
virtual IKTBNLearner< GUM_SCALAR > & eraseForbiddenArcAllSlices(std::string_view tailBase, std::string_view headBase)=0
Undo a previous addForbiddenArcAllSlices.
virtual IKTBNLearner< GUM_SCALAR > & eraseMandatoryArc(std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice)=0
Undo a previous addMandatoryArc.
virtual IKTBNLearner< GUM_SCALAR > & useScoreBIC()=0
virtual IKTBNLearner< GUM_SCALAR > & addNoChildrenNode(std::string_view name)=0
Declare a single node (bracket notation, e.g. "X[2]" or "C") as a leaf.
virtual IKTBNLearner< GUM_SCALAR > & addPossibleEdge(std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice)=0
Add a candidate edge for MIIC (only edges explicitly listed are explored).
virtual IKTBNLearner< GUM_SCALAR > & eraseForbiddenArc(std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice)=0
Undo a previous addForbiddenArc for a specific (base, slice) pair.
virtual IKTBNLearner< GUM_SCALAR > & eraseNoChildrenNode(std::string_view name)=0
Undo addNoChildrenNode for a node given by bracket notation.
virtual IKTBNLearner< GUM_SCALAR > & setMaxIndegree(Size max_indegree)=0
Cap the number of parents of any single node.
virtual IKTBNLearner< GUM_SCALAR > & allowArcAdditions(bool allow=true)=0
Allow or forbid arc additions during structure search.
std::string _encode_(std::string_view base, int slice) const
(base, slice) -> engine name ("A[1]" / atemporal engine name). Pure function, shared by every learner...
virtual IKTBNLearner< GUM_SCALAR > & eraseForbiddenArc(std::string_view tailNode, std::string_view headNode)=0
Undo a previous addForbiddenArc (engine names).
virtual IKTBNLearner< GUM_SCALAR > & addForbiddenArcAllSlices(std::string_view tailBase, std::string_view headBase)=0
Forbid tailBase -> headBase at every causally-possible slice pair.
virtual IKTBNLearner< GUM_SCALAR > & addPossibleEdge(std::string_view tail, std::string_view head)=0
Add a candidate edge for MIIC using engine names (e.g. "X[1]", "C").
virtual IKTBNLearner< GUM_SCALAR > & useScoreLog2Likelihood()=0
virtual IKTBNLearner< GUM_SCALAR > & useLocalSearchWithTabuList(Size tabu_size, Size nb_decrease)=0
local search with tabu list, with the default number of decreasing changes (key tabuNbDecrease of the...
virtual IKTBNLearner< GUM_SCALAR > & useScoreBDeu()=0
virtual IKTBNLearner< GUM_SCALAR > & useNoCorrection()=0
virtual IKTBNLearner< GUM_SCALAR > & addMandatoryArc(std::string_view tailNode, std::string_view headNode)=0
Force tailNode to be a parent of headNode (engine names).
virtual IKTBNLearner< GUM_SCALAR > & allowArcDeletions(bool allow=true)=0
Allow or forbid arc deletions during structure search.
virtual IKTBNLearner< GUM_SCALAR > & useFCI()=0
local search with tabu list, with the default number of decreasing changes (key tabuNbDecrease of the...
virtual IKTBNLearner< GUM_SCALAR > & addNoChildrenNode(std::string_view base, int slice)=0
Declare a single (base, slice) node as a leaf (no children).
virtual KTBN< GUM_SCALAR > learnKTBN()=0
Learn a k-TBN (structure + CPTs) with the recorded configuration. The fixed-k learner learns for its ...
virtual IKTBNLearner< GUM_SCALAR > & erasePossibleEdge(std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice)=0
Undo a previous addPossibleEdge.
virtual ~IKTBNLearner()=default
virtual destructor (polymorphic base class)
std::pair< std::string, int > _determineNode_(const std::string &name) const
engine name -> (base, slice); atemporal names map to KTBN::ATEMPORAL. Shared by every learner; only t...
virtual IKTBNLearner< GUM_SCALAR > & useScoreAIC()=0
std::size_t Size
In aGrUM, hashed values are unsigned long int.
Definition types.h:74
include the inlined functions if necessary
Definition CSVParser.h:55
template class GUM_PUBLIC_KTBN IKTBNLearner< double >
gum is the global namespace for all aGrUM entities
Definition agrum.h:46