aGrUM 3.3.2
a C++ library for (probabilistic) graphical models
KTBNLearner_tpl.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
42#pragma once
43
44
50
51#include <filesystem>
52#include <fstream>
53#include <sstream>
54
59
60namespace gum::learning {
61
62 // =========================================================================
63 // Internal-learner fan-out helpers
64 // =========================================================================
65
66 template < GUM_Numeric GUM_SCALAR >
67 template < class F >
73
74 template < GUM_Numeric GUM_SCALAR >
75 template < class F >
77 std::string_view head,
78 F&& f) {
79 const int last = static_cast< int >(_prior_ktbn_.k()) - 1;
80 const int tailSlice = _determineNode_(std::string{tail}).second;
81 const int headSlice = _determineNode_(std::string{head}).second;
82 const bool bothAtemp = (tailSlice == KTBN< GUM_SCALAR >::ATEMPORAL
83 && headSlice == KTBN< GUM_SCALAR >::ATEMPORAL);
84 if (headSlice == last) f(*_transitionLearner_);
85 else if (bothAtemp && _atemporalLearner_) f(*_atemporalLearner_);
86 else if (tailSlice != last) f(*_initialLearner_);
87 // else: the head is at a past slice but the tail sits on the kernel one,
88 // i.e. a backward arc. No table can hold it -- the initial one has no
89 // slice k-1 column -- and the k-TBN forbids it anyway, so there is
90 // nothing to constrain. Silently nothing, as the old broadcast did
91 // through its "tailSlice != last && headSlice != last" guard.
92 }
93
94 template < GUM_Numeric GUM_SCALAR >
95 template < class F >
97 std::string_view headBase,
98 F&& f) const {
99 if (!_isKnownBase_(tailBase))
101 "unknown base variable '" << tailBase
102 << "': it is not one of this learner's variables")
103 if (!_isKnownBase_(headBase))
105 "unknown base variable '" << headBase
106 << "': it is not one of this learner's variables")
107
108 constexpr int AT = KTBN< GUM_SCALAR >::ATEMPORAL;
109 const int k = static_cast< int >(_prior_ktbn_.k());
110 const bool tailAtemp = _prior_ktbn_.atemporalVarNames().contains(std::string{tailBase});
111 const bool headAtemp = _prior_ktbn_.atemporalVarNames().contains(std::string{headBase});
112
113 if (tailAtemp && headAtemp) {
114 f(AT, AT);
115 } else if (tailAtemp) {
116 for (int hs = 0; hs < k; ++hs)
117 f(AT, hs);
118 } else if (headAtemp) {
119 // temporal tail -> atemporal head is already structurally impossible
120 } else {
121 for (int ts = 0; ts < k; ++ts)
122 for (int hs = ts; hs < k; ++hs)
123 f(ts, hs);
124 }
125 }
126
127 // =========================================================================
128 // Constructors / Destructors
129 // =========================================================================
130
131 template < GUM_Numeric GUM_SCALAR >
133 std::string_view csvBaseName,
135 Size k,
136 const std::unordered_set< std::string >& atemporalVars,
137 const std::vector< std::string >& missingSymbols,
138 bool induceTypes,
139 bool ignoreMissingSymbols) :
140 _ignoreMissingSymbols_(ignoreMissingSymbols), _prior_ktbn_(_buildPriorFromCSV_(dirPath,
141 csvBaseName,
142 k,
143 atemporalVars,
144 missingSymbols,
145 induceTypes)) {
146 // k >= 2 is already enforced by _buildPriorFromCSV_ during member initialisation
147 if (nbSamples == 0) GUM_ERROR(InvalidArgument, "KTBNLearner needs at least one sample")
148 GUM_CONSTRUCTOR(KTBNLearner)
149 try {
150 _build_(dirPath, csvBaseName, nbSamples, missingSymbols);
151 } catch (const gum::UnknownLabelInDatabase&) {
152 // Domains are inferred from trajectory 1 alone, so a variable whose full
153 // domain is absent there fails once a later trajectory shows a new label.
154 // Atemporal variables are the usual culprits: constant within a trajectory,
155 // they reveal only one value per file. Re-throw with a KTBN-specific hint.
156 GUM_DESTRUCTOR(KTBNLearner)
158 "KTBNLearner CSV constructor: an unknown label was encountered while "
159 "reading the trajectory CSVs. The variable domains are inferred from "
160 "the first CSV alone, so any variable whose modalities are not all "
161 "present in trajectory 1 will trigger this error (atemporal variables "
162 "are especially prone: each trajectory holds a single constant value "
163 "for them, so at most one label appears in trajectory 1). "
164 "Use the BN-schema constructor "
165 "KTBNLearner(dir, base, n, k, bn, atemporals) to supply the full "
166 "variable domains explicitly.")
167 } catch (...) {
168 GUM_DESTRUCTOR(KTBNLearner)
169 throw;
170 }
171 }
172
173 template < GUM_Numeric GUM_SCALAR >
175 std::string_view csvBaseName,
177 Size k,
178 const std::vector< std::string >& missingSymbols,
179 bool induceTypes,
180 bool ignoreMissingSymbols) :
181 // _inferAtemporalVars_ checks k>=2 itself, before opening anything (see
182 // its declaration) — this initialiser-list call runs before the
183 // delegated-to constructor's own body, so that check cannot be left to
184 // _buildPriorFromCSV_ the way the explicit constructor leaves it.
185 // Delegates to the explicit-atemporalVars constructor for the rest
186 // (including the UnknownLabelInDatabase hint); _inferAtemporalVars_
187 // needs nbSamples, unlike _buildPriorFromCSV_, since one trajectory
188 // alone cannot show that a value stays constant.
189 KTBNLearner(dirPath,
190 csvBaseName,
191 nbSamples,
192 k,
193 _inferAtemporalVars_(dirPath, csvBaseName, nbSamples, k, missingSymbols),
194 missingSymbols,
195 induceTypes,
196 ignoreMissingSymbols) {}
197
198 template < GUM_Numeric GUM_SCALAR >
200 std::string_view csvBaseName,
202 Size k,
203 const BayesNet< GUM_SCALAR >& bn,
204 const std::unordered_set< std::string >& atemporalVars,
205 const std::vector< std::string >& missingSymbols,
206 bool ignoreMissingSymbols) :
207 _ignoreMissingSymbols_(ignoreMissingSymbols),
208 _prior_ktbn_(_buildPriorFromBN_(k, bn, atemporalVars)) {
209 // k >= 2 is already enforced by _buildPriorFromBN_ during member initialisation
210 if (nbSamples == 0) GUM_ERROR(InvalidArgument, "KTBNLearner needs at least one sample")
211 GUM_CONSTRUCTOR(KTBNLearner)
212 try {
213 _build_(dirPath, csvBaseName, nbSamples, missingSymbols);
214 } catch (...) {
215 GUM_DESTRUCTOR(KTBNLearner)
216 throw;
217 }
218 }
219
220 template < GUM_Numeric GUM_SCALAR >
224
225 // =========================================================================
226 // Main learning methods
227 // =========================================================================
228
229 template < GUM_Numeric GUM_SCALAR >
231 // Honour the possible-edge whitelist for atemporal->atemporal arcs: when a
232 // whitelist is active (>=1 possible edge with a temporal endpoint) but no
233 // atemporal->atemporal edge was whitelisted, the atemporal learner has an
234 // empty (hence unrestricted) list. Skip it entirely so no atemporal arc is
235 // produced; _assemble_ then leaves the atemporal variables as roots.
236 const bool suppressAtemporal
238 BayesNet< GUM_SCALAR > transitionBN = _transitionLearner_->learnBN();
239 BayesNet< GUM_SCALAR > initialBN = _initialLearner_->learnBN();
240 BayesNet< GUM_SCALAR > atemporalBN = (_atemporalLearner_ && !suppressAtemporal)
241 ? _atemporalLearner_->learnBN()
242 : BayesNet< GUM_SCALAR >{};
243 return _assemble_(transitionBN, initialBN, atemporalBN);
244 }
245
246 template < GUM_Numeric GUM_SCALAR >
247 KTBN< GUM_SCALAR > KTBNLearner< GUM_SCALAR >::learnParameters(const KTBN< GUM_SCALAR >& structure,
248 bool takeIntoAccountScore) {
249 if (structure.k() != _prior_ktbn_.k())
251 "learnParameters: structure has k="
252 << structure.k() << " but this learner was built with k=" << _prior_ktbn_.k())
253 const int k = (int)_prior_ktbn_.k();
254
255 // Build one DAG per internal table, in that table's own NodeId space, by
256 // routing each of structure's (base, slice) arcs to the table that owns its
257 // head: slice k-1 goes to the transition table, atemporal heads go to the
258 // atemporal table (guaranteed atemporal-tailed too — a temporal variable can
259 // never be a parent of an atemporal one), everything else (slices 0..k-2,
260 // whether the tail is temporal or atemporal) goes to the initial table.
261 DAG transitionDAG;
262 DAG initialDAG;
263 DAG atemporalDAG;
264
265 const std::size_t nbTransNodes = _transitionLearner_->database().nbVariables();
266 for (std::size_t id = 0; id < nbTransNodes; ++id)
267 transitionDAG.addNodeWithId(NodeId(id));
268
269 const std::size_t nbInitNodes = _initialLearner_->database().nbVariables();
270 for (std::size_t id = 0; id < nbInitNodes; ++id)
271 initialDAG.addNodeWithId(NodeId(id));
272
273 if (_atemporalLearner_) {
274 const std::size_t nbAtemNodes = _atemporalLearner_->database().nbVariables();
275 for (std::size_t id = 0; id < nbAtemNodes; ++id)
276 atemporalDAG.addNodeWithId(NodeId(id));
277 }
278
279 for (const auto& [tail, head]: structure.arcs()) {
280 const auto& [tailBase, tailSlice] = tail;
281 const auto& [headBase, headSlice] = head;
282 const std::string tailName = _encode_(tailBase, tailSlice);
283 const std::string headName = _encode_(headBase, headSlice);
284
285 if (headSlice == k - 1) {
286 transitionDAG.addArc(_transitionLearner_->idFromName(tailName),
287 _transitionLearner_->idFromName(headName));
288 } else if (headSlice == KTBN< GUM_SCALAR >::ATEMPORAL) {
290 atemporalDAG.addArc(_atemporalLearner_->idFromName(tailName),
291 _atemporalLearner_->idFromName(headName));
292 } else {
293 initialDAG.addArc(_initialLearner_->idFromName(tailName),
294 _initialLearner_->idFromName(headName));
295 }
296 }
297
298 BayesNet< GUM_SCALAR > transitionBN
299 = _transitionLearner_->learnParameters(transitionDAG, takeIntoAccountScore);
300 BayesNet< GUM_SCALAR > initialBN
301 = _initialLearner_->learnParameters(initialDAG, takeIntoAccountScore);
302 BayesNet< GUM_SCALAR > atemporalBN
304 ? _atemporalLearner_->learnParameters(atemporalDAG, takeIntoAccountScore)
305 : BayesNet< GUM_SCALAR >{};
306
307 return _assemble_(transitionBN, initialBN, atemporalBN);
308 }
309
310 // =========================================================================
311 // Score selection
312 // =========================================================================
313
314
315 template < GUM_Numeric GUM_SCALAR >
317 _forEachLearner_([](BNLearner< GUM_SCALAR >& l) { l.useScoreAIC(); });
318 return *this;
319 }
320
321 template < GUM_Numeric GUM_SCALAR >
323 _forEachLearner_([](BNLearner< GUM_SCALAR >& l) { l.useScoreBD(); });
324 return *this;
325 }
326
327 template < GUM_Numeric GUM_SCALAR >
329 _forEachLearner_([](BNLearner< GUM_SCALAR >& l) { l.useScoreBDeu(); });
330 return *this;
331 }
332
333 template < GUM_Numeric GUM_SCALAR >
335 _forEachLearner_([](BNLearner< GUM_SCALAR >& l) { l.useScoreBIC(); });
336 return *this;
337 }
338
339 template < GUM_Numeric GUM_SCALAR >
341 _forEachLearner_([](BNLearner< GUM_SCALAR >& l) { l.useScoreLog2Likelihood(); });
342 return *this;
343 }
344
345 template < GUM_Numeric GUM_SCALAR >
347 _forEachLearner_([](BNLearner< GUM_SCALAR >& l) { l.useScoreMDL(); });
348 return *this;
349 }
350
351 template < GUM_Numeric GUM_SCALAR >
353 _forEachLearner_([](BNLearner< GUM_SCALAR >& l) { l.useScorefNML(); });
354 }
355
356 template < GUM_Numeric GUM_SCALAR >
358 // Every score/prior setter is applied uniformly to all internal learners, so
359 // their configurations are identical: a single check on the transition learner
360 // is representative of the whole KTBNLearner.
361 return _transitionLearner_->checkScorePriorCompatibility();
362 }
363
364 // =========================================================================
365 // Algorithm selection
366 // =========================================================================
367
368 template < GUM_Numeric GUM_SCALAR >
370 _forEachLearner_([](BNLearner< GUM_SCALAR >& l) { l.useGreedyHillClimbing(); });
371 return *this;
372 }
373
374 template < GUM_Numeric GUM_SCALAR >
376 _forEachLearner_([](BNLearner< GUM_SCALAR >& l) { l.useExtendedGreedyHillClimbing(); });
377 return *this;
378 }
379
380 template < GUM_Numeric GUM_SCALAR >
385
386 template < GUM_Numeric GUM_SCALAR >
391
392 template < GUM_Numeric GUM_SCALAR >
396 [&](BNLearner< GUM_SCALAR >& l) { l.useLocalSearchWithTabuList(tabu_size, nb_decrease); });
397 return *this;
398 }
399
400 template < GUM_Numeric GUM_SCALAR >
402 _forEachLearner_([](BNLearner< GUM_SCALAR >& l) { l.useMIIC(); });
403 return *this;
404 }
405
406 template < GUM_Numeric GUM_SCALAR >
408 _forEachLearner_([](BNLearner< GUM_SCALAR >& l) { l.useGreedyThickThinning(); });
409 return *this;
410 }
411
412 template < GUM_Numeric GUM_SCALAR >
414 _forEachLearner_([](BNLearner< GUM_SCALAR >& l) { l.usePC(); });
415 return *this;
416 }
417
418 template < GUM_Numeric GUM_SCALAR >
420 _forEachLearner_([](BNLearner< GUM_SCALAR >& l) { l.useFCI(); });
421 return *this;
422 }
423
424 // =========================================================================
425 // MIIC correction
426 // =========================================================================
427
428 template < GUM_Numeric GUM_SCALAR >
430 _forEachLearner_([](BNLearner< GUM_SCALAR >& l) { l.useNMLCorrection(); });
431 return *this;
432 }
433
434 template < GUM_Numeric GUM_SCALAR >
436 _forEachLearner_([](BNLearner< GUM_SCALAR >& l) { l.useMDLCorrection(); });
437 return *this;
438 }
439
440 template < GUM_Numeric GUM_SCALAR >
442 _forEachLearner_([](BNLearner< GUM_SCALAR >& l) { l.useNoCorrection(); });
443 return *this;
444 }
445
446 template < GUM_Numeric GUM_SCALAR >
447 std::vector< std::pair< std::string, std::string > >
449 // Each learner reports latent arcs in its own NodeId space, so translate each
450 // Arc to an (engine-name, engine-name) pair before merging. A pair among
451 // slices 0..k-2 can be flagged by both the transition and the initial learner,
452 // so deduplicate on a tab-joined key (engine names never contain a tab).
453 // Propagates BNLearner's OperationNotAllowed if MIIC is not selected.
454 std::vector< std::pair< std::string, std::string > > result;
455 std::unordered_set< std::string > seen;
456
457 auto collect = [&](const std::unique_ptr< BNLearner< GUM_SCALAR > >& learner) {
458 if (!learner) return;
459 for (const auto& arc: learner->latentVariables()) {
460 std::string tail = learner->nameFromId(arc.tail());
461 std::string head = learner->nameFromId(arc.head());
462 if (seen.insert(tail + '\t' + head).second)
463 result.emplace_back(std::move(tail), std::move(head));
464 }
465 };
466 collect(_transitionLearner_);
467 collect(_initialLearner_);
468 collect(_atemporalLearner_);
469 return result;
470 }
471
472 // =========================================================================
473 // Prior selection
474 // =========================================================================
475
476 template < GUM_Numeric GUM_SCALAR >
480
481 template < GUM_Numeric GUM_SCALAR >
483 _forEachLearner_([&](BNLearner< GUM_SCALAR >& l) { l.useSmoothingPrior(weight); });
484 return *this;
485 }
486
487 // =========================================================================
488 // Structural constraints
489 // =========================================================================
490
491 template < GUM_Numeric GUM_SCALAR >
493 std::string_view headNode) {
494 _forOwningLearner_(tailNode, headNode, [&](BNLearner< GUM_SCALAR >& l) {
495 l.addForbiddenArc(tailNode, headNode);
496 });
497 return *this;
498 }
499
500 template < GUM_Numeric GUM_SCALAR >
502 int tailSlice,
503 std::string_view headBase,
504 int headSlice) {
505 // wrapper: encode (base, slice) -> engine name and delegate to the string overload
506 return addForbiddenArc(_encode_(tailBase, tailSlice), _encode_(headBase, headSlice));
507 }
508
509 template < GUM_Numeric GUM_SCALAR >
512 std::string_view headNode) {
513 // refuse to lift an invariant the k-TBN definition enforces (shared with addMandatoryArc)
514 _checkArcTemporallyFeasible_(tailNode, headNode, "un-forbid the arc");
515
516 _forOwningLearner_(tailNode, headNode, [&](BNLearner< GUM_SCALAR >& l) {
517 l.eraseForbiddenArc(tailNode, headNode);
518 });
519 return *this;
520 }
521
522 template < GUM_Numeric GUM_SCALAR >
524 int tailSlice,
525 std::string_view headBase,
526 int headSlice) {
527 return eraseForbiddenArc(_encode_(tailBase, tailSlice), _encode_(headBase, headSlice));
528 }
529
530 template < GUM_Numeric GUM_SCALAR >
532 std::string_view headNode) {
533 // Unlike forbidding, a mandatory arc must be feasible: reject up front the arcs
534 // the k-TBN can never contain (shared with eraseForbiddenArc) rather than
535 // letting them crash later in the wrong learner. Kept here, not in
536 // _forOwningLearner_: the check is deliberately asymmetric across the four
537 // setters (see its declaration).
538 _checkArcTemporallyFeasible_(tailNode, headNode, "force the mandatory arc");
539
540 _forOwningLearner_(tailNode, headNode, [&](BNLearner< GUM_SCALAR >& l) {
541 l.addMandatoryArc(tailNode, headNode);
542 });
543 return *this;
544 }
545
546 template < GUM_Numeric GUM_SCALAR >
548 int tailSlice,
549 std::string_view headBase,
550 int headSlice) {
551 // wrapper: encode (base, slice) -> engine name and delegate to the string overload
552 return addMandatoryArc(_encode_(tailBase, tailSlice), _encode_(headBase, headSlice));
553 }
554
555 template < GUM_Numeric GUM_SCALAR >
558 std::string_view headNode) {
559 // no feasibility check: a backward-in-time arc can never have been added, so
560 // erasing it is harmless -- it resolves to a no-op on the owning learner.
561 _forOwningLearner_(tailNode, headNode, [&](BNLearner< GUM_SCALAR >& l) {
562 l.eraseMandatoryArc(tailNode, headNode);
563 });
564 return *this;
565 }
566
567 template < GUM_Numeric GUM_SCALAR >
569 int tailSlice,
570 std::string_view headBase,
571 int headSlice) {
572 return eraseMandatoryArc(_encode_(tailBase, tailSlice), _encode_(headBase, headSlice));
573 }
574
575 template < GUM_Numeric GUM_SCALAR >
578 std::string_view headBase) {
579 // validate both endpoints BEFORE touching any learner, so a rejected call
580 // leaves no partially-applied constraint behind
581 _checkBaseIsTemporal_(tailBase, "an intra-slice constraint");
582 _checkBaseIsTemporal_(headBase, "an intra-slice constraint");
583 const int k = static_cast< int >(_prior_ktbn_.k());
584 for (int t = 0; t < k; ++t)
585 addForbiddenArc(tailBase, t, headBase, t);
586 return *this;
587 }
588
589 template < GUM_Numeric GUM_SCALAR >
592 std::string_view headBase) {
593 _checkBaseIsTemporal_(tailBase, "an intra-slice constraint");
594 _checkBaseIsTemporal_(headBase, "an intra-slice constraint");
595 const int k = static_cast< int >(_prior_ktbn_.k());
596 for (int t = 0; t < k; ++t)
597 eraseForbiddenArc(tailBase, t, headBase, t);
598 return *this;
599 }
600
601 template < GUM_Numeric GUM_SCALAR >
604 std::string_view headBase) {
605 _forEachAllSlicesPair_(tailBase, headBase, [&](int ts, int hs) {
606 addForbiddenArc(tailBase, ts, headBase, hs);
607 });
608 return *this;
609 }
610
611 template < GUM_Numeric GUM_SCALAR >
614 std::string_view headBase) {
615 _forEachAllSlicesPair_(tailBase, headBase, [&](int ts, int hs) {
616 eraseForbiddenArc(tailBase, ts, headBase, hs);
617 });
618 return *this;
619 }
620
621 template < GUM_Numeric GUM_SCALAR >
623 int slice) {
624 return addNoParentNode(_encode_(base, slice));
625 }
626
627 template < GUM_Numeric GUM_SCALAR >
629 const int slice = _determineNode_(std::string{name}).second;
630 const bool isAtemp = (slice == KTBN< GUM_SCALAR >::ATEMPORAL);
631 if (isAtemp && _atemporalLearner_) {
632 // Atemporals are already forced roots in transition/initial learners by _build_.
633 // The user constraint is only meaningful in the atemporal learner.
634 _atemporalLearner_->addNoParentNode(name);
635 } else if (!isAtemp) {
636 _transitionLearner_->addNoParentNode(name);
637 if (slice < (int)_prior_ktbn_.k() - 1) _initialLearner_->addNoParentNode(name);
638 }
639 return *this;
640 }
641
642 template < GUM_Numeric GUM_SCALAR >
644 int slice) {
645 return eraseNoParentNode(_encode_(base, slice));
646 }
647
648 template < GUM_Numeric GUM_SCALAR >
650 const int slice = _determineNode_(std::string{name}).second;
651 const int last = (int)_prior_ktbn_.k() - 1;
652 const bool isAtemp = (slice == KTBN< GUM_SCALAR >::ATEMPORAL);
653 if (isAtemp && _atemporalLearner_) _atemporalLearner_->eraseNoParentNode(name);
654 else if (slice == last) _transitionLearner_->eraseNoParentNode(name);
655 else if (!isAtemp)
656 // Past slices keep their transition-learner root constraint (confines learning
657 // to the kernel); only lift the constraint in the initial learner.
658 _initialLearner_->eraseNoParentNode(name);
659 return *this;
660 }
661
662 template < GUM_Numeric GUM_SCALAR >
664 int slice) {
665 return addNoChildrenNode(_encode_(base, slice));
666 }
667
668 template < GUM_Numeric GUM_SCALAR >
670 const int slice = _determineNode_(std::string{name}).second;
671 const bool isAtemp = (slice == KTBN< GUM_SCALAR >::ATEMPORAL);
672 _transitionLearner_->addNoChildrenNode(name);
673 if (slice < (int)_prior_ktbn_.k() - 1) _initialLearner_->addNoChildrenNode(name);
674 if (isAtemp && _atemporalLearner_) _atemporalLearner_->addNoChildrenNode(name);
675 return *this;
676 }
677
678 template < GUM_Numeric GUM_SCALAR >
680 int slice) {
681 return eraseNoChildrenNode(_encode_(base, slice));
682 }
683
684 template < GUM_Numeric GUM_SCALAR >
686 const int slice = _determineNode_(std::string{name}).second;
687 const bool isAtemp = (slice == KTBN< GUM_SCALAR >::ATEMPORAL);
688 _transitionLearner_->eraseNoChildrenNode(name);
689 if (slice < (int)_prior_ktbn_.k() - 1) _initialLearner_->eraseNoChildrenNode(name);
690 if (isAtemp && _atemporalLearner_) _atemporalLearner_->eraseNoChildrenNode(name);
691 return *this;
692 }
693
694 template < GUM_Numeric GUM_SCALAR >
696 int tailSlice,
697 std::string_view headBase,
698 int headSlice) {
699 // encode (base, slice) -> engine name and delegate to the string overload, which
700 // owns the full routing (atemporal->atemporal to the atemporal learner, slice-k-1 guard)
701 return addPossibleEdge(_encode_(tailBase, tailSlice), _encode_(headBase, headSlice));
702 }
703
704 template < GUM_Numeric GUM_SCALAR >
706 int tailSlice,
707 std::string_view headBase,
708 int headSlice) {
709 return erasePossibleEdge(_encode_(tailBase, tailSlice), _encode_(headBase, headSlice));
710 }
711
712 template < GUM_Numeric GUM_SCALAR >
714 std::string_view head) {
715 const int last = (int)_prior_ktbn_.k() - 1;
716 const int tailSlice = _determineNode_(std::string{tail}).second;
717 const int headSlice = _determineNode_(std::string{head}).second;
718
719 // Atemporal names exist as forced roots in every table, so whitelisting them
720 // here too keeps the whole-model promise ("only listed edges are explored")
721 // even when the edge can fire in just one learner: the no-parent constraint
722 // on atemporal heads still vetoes it there (constraints compound, never
723 // override), so this can only shrink the candidate set, never widen it.
724 _transitionLearner_->addPossibleEdge(tail, head);
725 // forward to the initial learner only when both endpoints exist there, i.e. both
726 // are at a past slice (< k-1); atemporals (slice -1) satisfy this automatically.
727 if (tailSlice < last && headSlice < last) _initialLearner_->addPossibleEdge(tail, head);
728
729 if (tailSlice == KTBN< GUM_SCALAR >::ATEMPORAL && headSlice == KTBN< GUM_SCALAR >::ATEMPORAL) {
731 if (_atemporalLearner_) _atemporalLearner_->addPossibleEdge(tail, head);
732 } else {
734 }
735 return *this;
736 }
737
738 template < GUM_Numeric GUM_SCALAR >
740 std::string_view head) {
741 const int last = (int)_prior_ktbn_.k() - 1;
742 const int tailSlice = _determineNode_(std::string{tail}).second;
743 const int headSlice = _determineNode_(std::string{head}).second;
744
745 _transitionLearner_->erasePossibleEdge(tail, head);
746 if (tailSlice < last && headSlice < last) _initialLearner_->erasePossibleEdge(tail, head);
747
748 if (tailSlice == KTBN< GUM_SCALAR >::ATEMPORAL && headSlice == KTBN< GUM_SCALAR >::ATEMPORAL) {
750 if (_atemporalLearner_) _atemporalLearner_->erasePossibleEdge(tail, head);
751 } else {
753 }
754 return *this;
755 }
756
757 template < GUM_Numeric GUM_SCALAR >
759 _forEachLearner_([&](BNLearner< GUM_SCALAR >& l) { l.allowArcAdditions(allow); });
760 return *this;
761 }
762
763 template < GUM_Numeric GUM_SCALAR >
765 _forEachLearner_([&](BNLearner< GUM_SCALAR >& l) { l.allowArcDeletions(allow); });
766 return *this;
767 }
768
769 template < GUM_Numeric GUM_SCALAR >
771 _forEachLearner_([&](BNLearner< GUM_SCALAR >& l) { l.allowArcReversals(allow); });
772 return *this;
773 }
774
775 template < GUM_Numeric GUM_SCALAR >
777 _forEachLearner_([&](BNLearner< GUM_SCALAR >& l) { l.setMaxIndegree(max_indegree); });
778 return *this;
779 }
780
781 // =========================================================================
782 // Diagnostics
783 // =========================================================================
784
785 template < GUM_Numeric GUM_SCALAR >
787 return _prior_ktbn_.k();
788 }
789
790 template < GUM_Numeric GUM_SCALAR >
792 return _prior_ktbn_.nbTemporalVars() + _prior_ktbn_.nbAtemporalVars();
793 }
794
795 template < GUM_Numeric GUM_SCALAR >
796 std::vector< Size > KTBNLearner< GUM_SCALAR >::nbRows() const {
797 // Raw trajectory lengths captured by _build_(), one entry per sample. Unlike
798 // BNLearner::nbRows() (a single flat-table row count), a trajectory learner
799 // has one length per sequence, so the per-sample vector is the natural analog.
800 return _nbTimeSlices_;
801 }
802
803 template < GUM_Numeric GUM_SCALAR >
805 return _transitionLearner_->isConstraintBased();
806 }
807
808 template < GUM_Numeric GUM_SCALAR >
810 return _transitionLearner_->isScoreBased();
811 }
812
813 template < GUM_Numeric GUM_SCALAR >
815 // Emit a k-TBN-specific header, then delegate score/algo/prior/constraint
816 // details to each internal learner's toString().
817 std::stringstream s;
818 s << "k : " << k() << '\n';
819 s << "Variables : " << nbCols() << " (" << _prior_ktbn_.nbTemporalVars()
820 << " temporal, " << _prior_ktbn_.nbAtemporalVars() << " atemporal)" << '\n';
821 s << "Transition rows : " << _transitionLearner_->nbRows() << '\n';
822 s << "Initial rows : " << _initialLearner_->nbRows() << '\n';
823 s << '\n';
824 s << "=== Transition learner (arcs into slice " << (k() - 1) << ") ===" << '\n';
825 s << _transitionLearner_->toString();
826 s << '\n';
827 s << "=== Initial learner (slices 0.." << (k() - 2) << ") ===" << '\n';
828 s << _initialLearner_->toString();
829 if (_atemporalLearner_) {
830 s << '\n';
831 s << "=== Atemporal learner (atemporal->atemporal arcs) ===" << '\n';
832 s << _atemporalLearner_->toString();
833 }
834 return s.str();
835 }
836
837 template < GUM_Numeric GUM_SCALAR >
838 std::vector< std::tuple< std::string, std::string, std::string > >
840 // settings are applied identically to every internal learner, so the
841 // transition learner's state represents the whole KTBNLearner.
842 auto result = _transitionLearner_->state();
843
844 // The transition learner lists every slice of every temporal variable
845 // (e.g. "W[0][2], W[1][2], W[2][2], W[3][2]"). Replace that row with one
846 // entry per base variable (e.g. "W[2]") built directly from the KTBN's own
847 // variable sets — no string parsing, robust to any base name.
848 for (auto& [key, val, comment]: result) {
849 if (key != "Variables") continue;
850 // Build base -> domainSize from the prior KTBN (slice 0 for temporal, AT for atemporal).
851 std::string collapsed;
852 bool first = true;
853 auto emit = [&](const std::string& base, int slice) {
854 const auto& var = _prior_ktbn_.variable(base, slice);
855 if (!first) collapsed += ", ";
856 collapsed += base + "[" + std::to_string(var.domainSize()) + "]";
857 first = false;
858 };
859 for (const auto& base: _prior_ktbn_.temporalVarNames())
860 emit(base, 0);
861 for (const auto& base: _prior_ktbn_.atemporalVarNames())
863 val = collapsed;
864 break;
865 }
866 return result;
867 }
868
869 template < GUM_Numeric GUM_SCALAR >
871 // As in BNLearner::copyState, only score/algorithm/prior/constraint settings
872 // are copied, never the database. Both sides must be structurally compatible
873 // (same k, same temporal/atemporal partition) for the name-based constraints
874 // to mean the same thing. The atemporal learner is copied only when both
875 // sides have one (absent when there are <= 1 atemporal vars).
876 _transitionLearner_->copyState(*learner._transitionLearner_);
877 _initialLearner_->copyState(*learner._initialLearner_);
879 _atemporalLearner_->copyState(*learner._atemporalLearner_);
880
881 // KTBNLearner-only state (BNLearner::copyState can't carry it): learnKTBN reads
882 // these to suppress the atemporal learner under a temporal-only whitelist
885 }
886
887 // =========================================================================
888 // Database accessors
889 // =========================================================================
890
891 template < GUM_Numeric GUM_SCALAR >
893 // the initial table holds exactly one row per trajectory, so its row count
894 // is the number of trajectory files given to the constructor.
895 return _initialLearner_->nbRows();
896 }
897
898 template < GUM_Numeric GUM_SCALAR >
902
903 template < GUM_Numeric GUM_SCALAR >
907
908 template < GUM_Numeric GUM_SCALAR >
910 return _transitionLearner_->hasMissingValues() || _initialLearner_->hasMissingValues()
911 || (_atemporalLearner_ && _atemporalLearner_->hasMissingValues());
912 }
913
914 template < GUM_Numeric GUM_SCALAR >
915 std::vector< std::string > KTBNLearner< GUM_SCALAR >::names() const {
916 // The first nbCols() columns of the transition table are the base variables
917 // (slice-0 temporals then atemporals); the remaining columns are just later
918 // slices of those same temporals. So strip the slice suffix off the first
919 // nbCols() engine names to get each base variable exactly once.
920 const auto& engine = _transitionLearner_->names();
921 const Size n = nbCols();
922 std::vector< std::string > result;
923 result.reserve(n);
924 for (Size i = 0; i < n; ++i)
925 result.push_back(_determineNode_(engine[i]).first);
926 return result;
927 }
928
929 template < GUM_Numeric GUM_SCALAR >
930 std::vector< Size > KTBNLearner< GUM_SCALAR >::domainSizes() const {
931 // Mirror names(): the first nbCols() columns are the base variables (a temporal
932 // variable's domain size is the same across all its slices), so keep only those.
933 const auto& all = _transitionLearner_->domainSizes();
934 return std::vector< Size >(all.begin(), all.begin() + nbCols());
935 }
936
937 template < GUM_Numeric GUM_SCALAR >
938 Size KTBNLearner< GUM_SCALAR >::domainSize(std::string_view base) const {
939 // Resolve the base name to an engine name in the transition table: a temporal
940 // variable is addressed at slice 0, everything else keeps its bare name (which
941 // also lets a raw engine name pass through). An unknown name reaches
942 // domainSize() unchanged and throws MissingVariableInDatabase.
943 const std::string b{base};
944 const int slice
945 = _prior_ktbn_.temporalVarNames().contains(b) ? 0 : KTBN< GUM_SCALAR >::ATEMPORAL;
946 return _transitionLearner_->domainSize(_encode_(b, slice));
947 }
948
949 // =========================================================================
950 // Private helpers
951 // =========================================================================
952
953
954 template < GUM_Numeric GUM_SCALAR >
955 std::unordered_set< std::string > KTBNLearner< GUM_SCALAR >::_inferAtemporalVars_(
956 std::string_view dirPath,
957 std::string_view csvBaseName,
959 Size k,
960 const std::vector< std::string >& missingSymbols) {
963 csvBaseName,
964 nbSamples,
965 missingSymbols);
966 }
967
968 template < GUM_Numeric GUM_SCALAR >
970 std::string_view dirPath,
971 std::string_view csvBaseName,
972 Size k,
973 const std::unordered_set< std::string >& atemporalVars,
974 const std::vector< std::string >& missingSymbols,
975 bool induceTypes) {
977
978 namespace fs = std::filesystem;
979 const std::string firstCSV
980 = (fs::path{dirPath} / (std::string{csvBaseName} + "1.csv")).string();
981 // _build_() also reads trajectory 1 (its i=0 pass). The double-read is
982 // unavoidable: this function runs in the member-initialiser list, before
983 // the object (and hence _build_()) exists, and _build_() must read every
984 // trajectory.
985
986 // BNLearner construction runs induceTypes on the CSV and populates all
987 // column translators with properly-typed DiscreteVariables.
988 const BNLearner< GUM_SCALAR > tmpLearner(firstCSV, missingSymbols, induceTypes);
989
990 // Pull typed variables from the translator set. translatorSafe(i) bounds-checks,
991 // guarding against any names()/translator-set mismatch.
992 const DBTranslatorSet& translators = tmpLearner.database().translatorSet();
993 const std::vector< std::string >& names = tmpLearner.names();
994
995 KTBN< GUM_SCALAR > prior(k);
996 for (std::size_t i = 0; i < names.size(); ++i) {
997 prior.add(static_cast< const DiscreteVariable& >(*translators.translatorSafe(i).variable()),
998 !atemporalVars.contains(names[i]));
999 }
1000
1001 // Every declared atemporal name must appear in the CSV header.
1002 for (const std::string& aname: atemporalVars)
1003 if (!prior.exists(aname))
1005 "atemporal variable '" << aname << "' not found in the CSV header")
1006 return prior;
1007 }
1008
1009 template < GUM_Numeric GUM_SCALAR >
1011 Size k,
1012 const BayesNet< GUM_SCALAR >& bn,
1013 const std::unordered_set< std::string >& atemporalVars) {
1015
1016 KTBN< GUM_SCALAR > prior(k);
1017 // bn.nodes() iterates in hash order (unspecified). This is harmless because
1018 // KTBN looks up variables by name, not by insertion index.
1019 for (const NodeId node: bn.nodes()) {
1020 const DiscreteVariable& var = bn.variable(node);
1021 prior.add(var, !atemporalVars.contains(var.name()));
1022 }
1023 for (const std::string& aname: atemporalVars)
1024 if (!prior.exists(aname))
1025 GUM_ERROR(InvalidArgument, "atemporal variable '" << aname << "' not found in the BN")
1026 return prior;
1027 }
1028
1029 template < GUM_Numeric GUM_SCALAR >
1030 void KTBNLearner< GUM_SCALAR >::_build_(std::string_view dirPath,
1031 std::string_view csvBaseName,
1033 const std::vector< std::string >& missingSymbols) {
1034 Size k = _prior_ktbn_.k();
1035 Size nbTempVars = _prior_ktbn_.temporalVarNames().size();
1036 Size nbAtempVars = _prior_ktbn_.atemporalVarNames().size();
1037
1038 // tables are default-constructed here; translators are inserted per-column
1039 // in the i==0 block once the header (column order) is known
1040 DatabaseTable transitionTable(missingSymbols);
1041 DatabaseTable initTable(missingSymbols);
1042 DatabaseTable atemporalTable(missingSymbols);
1043
1044 // Complete-case selection, at row granularity.
1045 //
1046 // aGrUM's structure learning refuses a database holding any missing value
1047 // outright (IBNLearner::learnDag_), so an incomplete row cannot simply be
1048 // handed over: learnKTBN() would throw on any trajectory with a gap. A row
1049 // that carries one is therefore dropped here, and everything downstream sees
1050 // a database with no missing value at all.
1051 //
1052 // This mirrors what the cross-k score already does per instance
1053 // (KTBNAdaptiveLearner::_forEachScoredNode_ skips any instance whose family
1054 // is not fully observed), so the two layers agree on which data counts.
1055 //
1056 // The unit differs per table: a transition row is a whole width-k window, so
1057 // one gap costs up to k windows; an initial or atemporal row is the whole
1058 // trajectory's contribution to that table.
1059 const std::unordered_set< std::string > missingSet(missingSymbols.begin(),
1060 missingSymbols.end());
1061 const auto insertIfComplete = [&](DatabaseTable& table, const std::vector< std::string >& r) {
1063 for (const auto& cell: r)
1064 if (missingSet.contains(cell)) {
1066 return;
1067 }
1068 }
1069 table.insertRow(r);
1070 };
1071
1072 const std::filesystem::path dir{dirPath};
1073 const std::string stem{csvBaseName};
1074
1075 const std::size_t transRowSize = nbAtempVars + nbTempVars * k;
1076 const std::size_t initRowSize = nbAtempVars + nbTempVars * (k - 1);
1077 const std::size_t atempRowSize = nbAtempVars;
1078
1079 std::vector< std::string > header; // column order, captured from trajectory 1
1080 std::unordered_set< Size > atemVarsCols; // atemporal column indices
1081
1082 // reused across trajectories (capacity is kept between iterations)
1083 std::vector< std::vector< std::string > > buffer;
1084 std::vector< std::string > row;
1085 row.reserve(transRowSize);
1086 _nbTimeSlices_.reserve(nbSamples); // one raw length per trajectory (see nbRows())
1087
1088 for (Size i = 0; i < nbSamples; ++i) {
1089 // open the i-th trajectory (each file is opened exactly once)
1090 const std::filesystem::path file = dir / (stem + std::to_string(i + 1) + ".csv");
1091 std::ifstream is(file, std::ifstream::in);
1092 if (!is.is_open()) GUM_ERROR(gum::IOError, "Cannot open " << file.string());
1093
1094 CSVParser parser(is, file.string());
1095 parser.next();
1096
1097 if (i == 0) {
1098 // first file only: capture the column order, derive the atemporal columns
1099 // from _prior_ktbn_, build the bracket-encoded names and finish setting up the
1100 // tables (must happen before any insertRow)
1101 const auto& rawHeader = parser.current();
1102 header.assign(rawHeader.begin(), rawHeader.end());
1103 for (std::size_t c = 0; c < header.size(); ++c)
1104 if (_prior_ktbn_.atemporalVarNames().contains(header[c])) atemVarsCols.insert(c);
1105
1106 // every schema variable must appear in the data, else _assemble_ (used
1107 // by both learnKTBN and learnParameters) would later fail with an
1108 // opaque NotFound when resolving bracket names
1109 {
1110 const std::unordered_set< std::string > headerSet(header.begin(), header.end());
1111 auto requirePresent = [&](const std::string& base) {
1112 if (!headerSet.contains(base))
1114 "schema variable '" << base << "' is absent from '" << file.string() << "'")
1115 };
1116 for (const auto& base: _prior_ktbn_.temporalVarNames())
1117 requirePresent(base);
1118 for (const auto& base: _prior_ktbn_.atemporalVarNames())
1119 requirePresent(base);
1120
1121 // conversely, every CSV column must be a known schema variable, else the
1122 // translator-insertion loop below would fail with an opaque NotFound
1123 // when resolving it against _prior_ktbn_
1124 for (const std::string& col: header)
1125 if (!_prior_ktbn_.exists(col))
1127 "CSV column '" << col << "' in '" << file.string()
1128 << "' is not declared as a variable of this KTBNLearner")
1129 }
1130
1131 // insert one translator per column into each table; every schema variable
1132 // has a concrete domain (user-supplied, or discovered by _buildPriorFromCSV_), so
1133 // insertTranslator picks the matching translator type from the variable.
1134 std::vector< std::string > varNamesTran;
1135 std::vector< std::string > varNamesInit;
1136 std::vector< std::string > varNamesAtemp;
1137 {
1138 auto insertTrans
1139 = [&](DatabaseTable& table, const std::string& base, int slice, std::size_t col) {
1140 table.insertTranslator(_prior_ktbn_.variable(base, slice), col, missingSymbols);
1141 };
1142
1143 // translators and their engine names are built in lockstep, column by
1144 // column, so a translator's table position and its name can never drift
1145 // apart (unlike keeping two separately-indexed passes in sync by hand).
1146 varNamesTran.reserve(transRowSize);
1147 varNamesInit.reserve(initRowSize);
1148 varNamesAtemp.reserve(atempRowSize);
1149
1150 std::size_t tcol = 0, icol = 0, acol = 0;
1151 for (std::size_t c = 0; c < header.size(); ++c) {
1152 const int slice = atemVarsCols.contains(c) ? KTBN< GUM_SCALAR >::ATEMPORAL : 0;
1153 insertTrans(transitionTable, header[c], slice, tcol++);
1154 varNamesTran.push_back(_encode_(header[c], slice));
1155 insertTrans(initTable, header[c], slice, icol++);
1156 varNamesInit.push_back(_encode_(header[c], slice));
1157 if (atemVarsCols.contains(c)) {
1158 insertTrans(atemporalTable, header[c], KTBN< GUM_SCALAR >::ATEMPORAL, acol++);
1159 varNamesAtemp.push_back(header[c]);
1160 }
1161 }
1162 for (Size slice = 1; slice < k - 1; ++slice)
1163 for (std::size_t c = 0; c < header.size(); ++c)
1164 if (!atemVarsCols.contains(c)) {
1165 insertTrans(initTable, header[c], (int)slice, icol++);
1166 varNamesInit.push_back(_encode_(header[c], (int)slice));
1167 }
1168 for (Size slice = 1; slice < k; ++slice)
1169 for (std::size_t c = 0; c < header.size(); ++c)
1170 if (!atemVarsCols.contains(c)) {
1171 insertTrans(transitionTable, header[c], (int)slice, tcol++);
1172 varNamesTran.push_back(_encode_(header[c], (int)slice));
1173 }
1174 }
1175
1176 transitionTable.setVariableNames(varNamesTran, false);
1177 initTable.setVariableNames(varNamesInit, false);
1178 atemporalTable.setVariableNames(varNamesAtemp, false);
1179 } else {
1180 // later files: validate the header against trajectory 1's without copying it
1181 const auto& raw = parser.current();
1182 bool same = (raw.size() == header.size());
1183 for (std::size_t c = 0; same && c < header.size(); ++c)
1184 same = (raw[c] == header[c]);
1185 if (!same)
1186 GUM_ERROR(InvalidArgument, "Header of " << file.string() << " differs from trajectory 1");
1187 }
1188
1189 buffer.clear();
1190 while (parser.next()) {
1191 const auto& tokens = parser.current();
1192 if (tokens.size() != header.size())
1194 "Trajectory " << (i + 1) << ", row " << parser.nbLine() << ": expected "
1195 << header.size() << " columns, got " << tokens.size());
1196 buffer.push_back({tokens.begin(), tokens.end()});
1197 }
1198
1199 if (buffer.size() < k)
1201 "Trajectory " << (i + 1) << " has " << buffer.size()
1202 << " time steps but at least k=" << k << " are required");
1203
1204 // record this trajectory's raw length (number of time steps), exposed by nbRows()
1205 _nbTimeSlices_.push_back(buffer.size());
1206
1207 // An atemporal column is constant down the trajectory, so any row carries
1208 // its value -- but row 0's may be the missing one, and reading row 0 blindly
1209 // would then drop every row this trajectory feeds. Resolve each once, from
1210 // its first non-missing occurrence. Same rule the score walk applies.
1211 std::unordered_map< Size, std::string > atempValue;
1212 for (const Size col: atemVarsCols)
1213 for (const auto& r: buffer)
1214 if (!missingSet.contains(r[col])) {
1215 atempValue[col] = r[col];
1216 break;
1217 }
1218
1219 // value of column col at time tt: the resolved constant for an atemporal
1220 // column, the row's own cell for a temporal one. A column missing all the
1221 // way down has no resolved value, so row 0's marker stands and the row is
1222 // dropped like any other incomplete one.
1223 const auto cellAt = [&](std::size_t tt, Size col) -> const std::string& {
1224 if (!atemVarsCols.contains(col)) return buffer[tt][col];
1225 const auto it = atempValue.find(col);
1226 return (it == atempValue.end()) ? buffer[0][col] : it->second;
1227 };
1228
1229 // transition table: sliding windows of width k
1230 for (std::size_t t = 0; t + k <= buffer.size(); ++t) {
1231 row.clear();
1232 // slice 0 carries the atemporal columns; later slices skip them so atemporal
1233 // variables aren't repeated k-1 times in each row
1234 for (Size col = 0; col < buffer[0].size(); ++col) {
1235 row.push_back(cellAt(t, col));
1236 }
1237 for (Size slice = 1; slice < k; ++slice) {
1238 for (Size col = 0; col < buffer[0].size(); ++col) {
1239 if (!atemVarsCols.contains(col)) { row.push_back(buffer[t + slice][col]); }
1240 }
1241 }
1242 insertIfComplete(transitionTable, row);
1243 }
1244
1245 // initial table: first k-1 slices, one row per trajectory
1246 row.clear();
1247 for (Size col = 0; col < buffer[0].size(); ++col) {
1248 row.push_back(cellAt(0, col));
1249 }
1250 for (Size slice = 1; slice < k - 1; ++slice) {
1251 for (Size col = 0; col < buffer[0].size(); ++col) {
1252 if (!atemVarsCols.contains(col)) { row.push_back(buffer[slice][col]); }
1253 }
1254 }
1255 insertIfComplete(initTable, row);
1256
1257 // atemporal table: one row per trajectory, atemporal columns only. Their
1258 // value is constant across the trajectory, so any time step works — take 0.
1259 // Skipped when fewer than 2 atemporal variables exist: a single atemporal
1260 // variable has no possible atemporal->atemporal arcs, so no learner is built.
1261 if (nbAtempVars > 1) {
1262 row.clear();
1263 for (Size col = 0; col < buffer[0].size(); ++col)
1264 if (atemVarsCols.contains(col)) row.push_back(cellAt(0, col));
1265 insertIfComplete(atemporalTable, row);
1266 }
1267 }
1268
1269 // Dropping incomplete rows can empty a table outright -- every transition
1270 // window straddling a gap, or every trajectory's initial block incomplete.
1271 // The internal learner would then fail obscurely on an empty database, so
1272 // say what actually happened.
1273 if (_ignoreMissingSymbols_ && (transitionTable.nbRows() == 0 || initTable.nbRows() == 0))
1275 "every row was dropped as incomplete ("
1277 << " in total): no fully observed transition window (or initial block) is left "
1278 "to learn from. The trajectories are too sparsely observed for k="
1279 << k << ".")
1280
1281 // Variables are already typed upstream (template / first-trajectory learner),
1282 // so no induceTypes pass is needed here — just canonicalize the value codes.
1283 transitionTable.reorder();
1284 initTable.reorder();
1285
1286 _transitionLearner_ = std::make_unique< BNLearner< GUM_SCALAR > >(transitionTable);
1287 _initialLearner_ = std::make_unique< BNLearner< GUM_SCALAR > >(initTable);
1288
1289 if (nbAtempVars > 1) {
1290 atemporalTable.reorder();
1291 _atemporalLearner_ = std::make_unique< BNLearner< GUM_SCALAR > >(atemporalTable);
1292 }
1293
1294
1295 // Impose k-TBN temporal constraints on structure learning:
1296 // - transition learner: past slices (0..k-2) are forced roots so only the
1297 // present slice (k-1) receives new arcs.
1298 // - atemporal variables are forced roots in transition/initial learners so
1299 // their mutual structure is learned exclusively by the atemporal learner.
1300 // No-parent in both learners covers every algorithm and also bans
1301 // temporal→atemporal arcs.
1302 // - initial learner: backward temporal arcs among past slices forbidden
1303 // explicitly (honoured by MIIC and score-based algorithms alike).
1304 // These constraints shape structure search in learnKTBN(); they are inert
1305 // for learnParameters.
1306 const int ki = (int)k;
1307 const auto& temporalVars = _prior_ktbn_.temporalVarNames();
1308 const auto& atemporalVars = _prior_ktbn_.atemporalVarNames();
1309
1310 for (const auto& base: temporalVars)
1311 for (int slice = 0; slice < ki - 1; ++slice)
1312 _transitionLearner_->addNoParentNode(_encode_(base, slice));
1313
1314 for (const auto& atemBase: atemporalVars) {
1315 _transitionLearner_->addNoParentNode(atemBase);
1316 _initialLearner_->addNoParentNode(atemBase);
1317 }
1318
1319 if (k > 2) {
1320 // backward-in-time arcs among the past slices 0..k-2 are forbidden
1321 // explicitly: this is the only form MIIC honours (it ignores slice order),
1322 // and score-based algorithms respect it too, so it fully covers the
1323 // constraint. A setSliceOrder() mirror was dropped here as redundant.
1324 for (const auto& tailBase: temporalVars)
1325 for (const auto& headBase: temporalVars)
1326 for (int tailSlice = 1; tailSlice < ki - 1; ++tailSlice)
1327 for (int headSlice = 0; headSlice < tailSlice; ++headSlice)
1328 _initialLearner_->addForbiddenArc(_encode_(tailBase, tailSlice),
1329 _encode_(headBase, headSlice));
1330 }
1331 }
1332
1333 template < GUM_Numeric GUM_SCALAR >
1334 const std::unordered_set< std::string >& KTBNLearner< GUM_SCALAR >::_atemporalVarNames_() const {
1335 return _prior_ktbn_.atemporalVarNames();
1336 }
1337
1338 template < GUM_Numeric GUM_SCALAR >
1339 bool KTBNLearner< GUM_SCALAR >::_isKnownBase_(std::string_view base) const {
1340 const std::string b{base};
1341 return _prior_ktbn_.temporalVarNames().contains(b)
1342 || _prior_ktbn_.atemporalVarNames().contains(b);
1343 }
1344
1345 template < GUM_Numeric GUM_SCALAR >
1346 KTBN< GUM_SCALAR >
1347 KTBNLearner< GUM_SCALAR >::_assemble_(const BayesNet< GUM_SCALAR >& transitionBN,
1348 const BayesNet< GUM_SCALAR >& initialBN,
1349 const BayesNet< GUM_SCALAR >& atemporalBN) const {
1350 const int k = (int)_prior_ktbn_.k();
1351
1352 // 1. Base: initialBN provides slices 0..k-2 (temporal structure + CPTs, and
1353 // atemporal→temporal arcs). Atemporal variables enter only as forced roots;
1354 // steps 4 and 6 overwrite their mutual structure and CPTs from atemporalBN
1355 // (transitionBN repeats each atemporal value k-fold — not independent samples).
1356 BayesNet< GUM_SCALAR > bn(initialBN);
1357
1358 // 2. Add the slice k-1 variables from transitionBN (absent from initialBN).
1359 for (const auto& base: _prior_ktbn_.temporalVarNames()) {
1360 const std::string name = _encode_(base, k - 1);
1361 const NodeId transId = transitionBN.idFromName(name);
1362 bn.add(transitionBN.variable(transId));
1363 }
1364
1365 // 3. Add the arcs arriving at slice k-1 from transitionBN
1366 for (const auto& base: _prior_ktbn_.temporalVarNames()) {
1367 const std::string headName = _encode_(base, k - 1);
1368 const NodeId transHead = transitionBN.idFromName(headName);
1369 for (const NodeId transParent: transitionBN.parents(transHead)) {
1370 const std::string& parentName = transitionBN.variable(transParent).name();
1371 bn.addArc(parentName, headName);
1372 }
1373 }
1374
1375 // 4. Add the atemporal -> atemporal arcs from atemporalBN. Skipped when
1376 // atemporalBN is an empty placeholder: either <= 1 atemporal variable (no
1377 // learner is built, see _build_()) or the learner was suppressed by a
1378 // temporal-only possible-edge whitelist (see learnKTBN()). Either way the
1379 // atemporal variables already sit in bn as roots, via initialBN.
1380 if (atemporalBN.size() != 0) {
1381 for (const auto& atemBase: _prior_ktbn_.atemporalVarNames()) {
1382 const NodeId atemTail = atemporalBN.idFromName(atemBase);
1383 for (const NodeId atemChild: atemporalBN.children(atemTail)) {
1384 const std::string& childName = atemporalBN.variable(atemChild).name();
1385 bn.addArc(atemBase, childName);
1386 }
1387 }
1388 }
1389
1390 // 5. Fill the slice k-1 CPTs from transitionBN
1391 for (const auto& base: _prior_ktbn_.temporalVarNames()) {
1392 const std::string name = _encode_(base, k - 1);
1393 const NodeId bnId = bn.idFromName(name);
1394 const NodeId transId = transitionBN.idFromName(name);
1395 bn.cpt(bnId).fillWith(transitionBN.cpt(transId));
1396 }
1397
1398 // 6. Fill the atemporal CPTs from atemporalBN (same guard as step 4); when
1399 // skipped, the atemporal variables keep their initialBN marginal.
1400 if (atemporalBN.size() != 0) {
1401 for (const auto& atemBase: _prior_ktbn_.atemporalVarNames()) {
1402 const NodeId bnId = bn.idFromName(atemBase);
1403 const NodeId atemId = atemporalBN.idFromName(atemBase);
1404 bn.cpt(bnId).fillWith(atemporalBN.cpt(atemId));
1405 }
1406 }
1407
1408 // 7. Convert the assembled flat BN into a KTBN: fromBN infers k from the
1409 // highest bracket index and validates temporal causality.
1410 return KTBN< GUM_SCALAR >::fromBN(bn);
1411 }
1412
1413} // namespace gum::learning
Class for fast parsing of CSV file (never more than one line in application memory).
A structure/parameter learner for k-order dynamic Bayesian networks.
Base class for dag.
Definition DAG.h:121
void addArc(NodeId tail, NodeId head) final
insert a new arc into the directed graph
Definition DAG_inl.h:75
Base class for discrete random variable.
Exception: at least one argument passed to a function is not what was expected.
static constexpr int ATEMPORAL
Conventional time-slice value denoting an atemporal (static) variable.
Definition KTBN.h:204
static KTBN< GUM_SCALAR > fromBN(const BayesNet< GUM_SCALAR > &bn, const std::unordered_set< std::string > &atemporalNodes={}, std::vector< std::string > *warnings=nullptr)
Builds a k-DBN from an existing gum::BayesNet, reading its node names under one of two mutually exclu...
Definition KTBN_tpl.h:881
Error: A name of variable is not found in the database.
virtual void addNodeWithId(const NodeId id)
try to insert a node with the given id
Exception : operation not allowed.
Error: An unknown label is found in the database.
const std::string & name() const
returns the name of the variable
Class for fast parsing of CSV file (never more than one line in application memory).
Definition CSVParser.h:78
bool next()
gets the next line of the csv stream and parses it
std::size_t nbLine() const
returns the current line number within the stream
const std::vector< std::string > & current() const
returns the current parsed line
the class for packing together the translators used to preprocess the datasets
DBTranslator & translatorSafe(const std::size_t k)
returns the kth translator
virtual const Variable * variable() const =0
returns the variable stored into the translator
The class representing a tabular database as used by learning tasks.
void setVariableNames(const std::vector< std::string > &names, const bool from_external_object=true) override
sets the names of the variables
std::size_t insertTranslator(const DBTranslator &translator, const std::size_t input_column, const bool unique_column=true)
insert a new translator into the database table
void reorder(const std::size_t k, const bool k_is_input_col=false)
performs a reordering of the kth translator or of the first translator parsing the kth column of the ...
void insertRow(const std::vector< std::string > &new_row) override
insert a new row at the end of the database
std::size_t nbRows() const noexcept
returns the number of records (rows) in the database
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...
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...
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...
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...
static double defaultPriorWeight_()
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...
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...
Learns a k-TBN (structure and/or parameters) from trajectory CSVs.
static KTBN< GUM_SCALAR > _buildPriorFromCSV_(std::string_view dirPath, std::string_view csvBaseName, Size k, const std::unordered_set< std::string > &atemporalVars, const std::vector< std::string > &missingSymbols, bool induceTypes)
called in the member-initialiser list of the k-CSV constructor: opens the first trajectory CSV,...
std::vector< std::string > names() const
Base names (no slice suffix), one entry per base variable (temporal or atemporal),...
void copyState(const KTBNLearner< GUM_SCALAR > &learner)
Copy all score/algorithm/prior/constraint settings from another KTBNLearner (does not copy the databa...
KTBNLearner< GUM_SCALAR > & useNMLCorrection() override
Engine-name pairs (tail, head) of arcs flagged as hiding a latent variable by MIIC (merged from all i...
KTBNLearner< GUM_SCALAR > & useGreedyThickThinning() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
const std::unordered_set< std::string > & _atemporalVarNames_() const override
atemporal base names for IKTBNLearner's shared encode/_determineNode_; read straight from the prior k...
std::unique_ptr< BNLearner< GUM_SCALAR > > _initialLearner_
learns the initial slices 0..k-2
KTBNLearner< GUM_SCALAR > & eraseForbiddenArcAllSlices(std::string_view tailBase, std::string_view headBase) override
Undo a previous addForbiddenArcAllSlices.
void _build_(std::string_view dirPath, std::string_view csvBaseName, Size nbSamples, const std::vector< std::string > &missingSymbols)
reads every trajectory, builds the three DatabaseTables (sliding window, initial-slice flattening,...
KTBNLearner< GUM_SCALAR > & erasePossibleEdge(std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice) override
Undo a previous addPossibleEdge.
KTBN< GUM_SCALAR > learnKTBN() override
Full learning (structure + CPTs). Mirrors BNLearner::learnBN().
bool _ignoreMissingSymbols_
prior k-TBN: the single source of truth for k, variable domains, temporal/atemporal classification an...
std::vector< std::pair< std::string, std::string > > latentVariables() const
Engine-name pairs (tail, head) of arcs flagged as hiding a latent variable by MIIC (merged from all i...
KTBNLearner< GUM_SCALAR > & addForbiddenArc(std::string_view tailNode, std::string_view headNode) override
Forbid tailNode from ever parenting headNode (engine names, e.g. "X[1]", "C").
Size nbDroppedRows() const
Number of rows dropped from the internal databases because they carried a missing symbol.
KTBNLearner< GUM_SCALAR > & usePC() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNLearner< GUM_SCALAR > & useScoreAIC() override
Returns a warning string if the current score and prior are incompatible, empty string otherwise.
KTBNLearner< GUM_SCALAR > & useGreedyHillClimbing() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
static KTBN< GUM_SCALAR > _buildPriorFromBN_(Size k, const BayesNet< GUM_SCALAR > &bn, const std::unordered_set< std::string > &atemporalVars)
called in the member-initialiser list of the BN constructor: builds and returns a KTBN whose variable...
Size nbSamples() const
Number of trajectory CSV files loaded (the constructor's nbSamples).
KTBNLearner< GUM_SCALAR > & useScoreLog2Likelihood() override
Returns a warning string if the current score and prior are incompatible, empty string otherwise.
std::vector< Size > nbRows() const
Number of time steps in each trajectory CSV (one entry per sample, in load order)....
bool isConstraintBased() const
True if the current structure-learning algorithm is constraint-based (e.g. MIIC).
void _forOwningLearner_(std::string_view tail, std::string_view head, F &&f)
Apply f to the ONE internal learner that can learn the arc tail -> head, chosen by its head: a slice-...
KTBN< GUM_SCALAR > _assemble_(const BayesNet< GUM_SCALAR > &transitionBN, const BayesNet< GUM_SCALAR > &initialBN, const BayesNet< GUM_SCALAR > &atemporalBN) const
glues the three parameter-learned BNs into a single k-TBN
Size nbCols() const
Number of columns in each CSV, i.e. of base variables (temporal + atemporal).
void _forEachLearner_(F &&f)
Apply f to each present internal learner (the atemporal one only when it exists). Factors out the fan...
Size _nbTemporalPossibleEdges_
counts of currently-active possible edges, split by kind: edges with at least one temporal endpoint,...
KTBNLearner< GUM_SCALAR > & addForbiddenArcAllSlices(std::string_view tailBase, std::string_view headBase) override
Forbid tailBase -> headBase at every causally-possible slice pair (every lag, not just matching slice...
std::unique_ptr< BNLearner< GUM_SCALAR > > _transitionLearner_
learns the transition kernel (arcs arriving at slice k-1)
KTBNLearner< GUM_SCALAR > & useScoreBD() override
Returns a warning string if the current score and prior are incompatible, empty string otherwise.
KTBNLearner< GUM_SCALAR > & allowArcReversals(bool allow=true) override
Allow or forbid arc reversals during structure search.
KTBNLearner< GUM_SCALAR > & addNoChildrenNode(std::string_view base, int slice) override
Declare a single (base, slice) node as a leaf (no children).
std::vector< std::size_t > domainSizes() const
Domain sizes of the base variables, in the same column order as names().
KTBN< GUM_SCALAR > learnParameters(const KTBN< GUM_SCALAR > &structure, bool takeIntoAccountScore=true)
CPTs only, using the arc structure of structure. structure must have the same base variables (names a...
Size _nbDroppedRows_
number of time steps (rows) in each trajectory CSV, in load order. rows build() dropped because they ...
KTBN< GUM_SCALAR > _prior_ktbn_
KTBNLearner< GUM_SCALAR > & allowArcDeletions(bool allow=true) override
Allow or forbid arc deletions during structure search.
KTBNLearner< GUM_SCALAR > & useExtendedGreedyHillClimbing() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
std::string checkScorePriorCompatibility() const
Returns a warning string if the current score and prior are incompatible, empty string otherwise.
KTBNLearner< GUM_SCALAR > & useNoCorrection() override
Engine-name pairs (tail, head) of arcs flagged as hiding a latent variable by MIIC (merged from all i...
bool isScoreBased() const
True if the current structure-learning algorithm is score-based (e.g. BIC, AIC).
KTBNLearner< GUM_SCALAR > & allowArcAdditions(bool allow=true) override
Allow or forbid arc additions during structure search.
Size domainSize(std::string_view base) const
Domain size of the base variable base (e.g. "X", "C"). Engine names (e.g. "X[1]") are also accepted.
KTBNLearner< GUM_SCALAR > & eraseForbiddenArc(std::string_view tailNode, std::string_view headNode) override
Undo a previous addForbiddenArc (engine names, e.g. "X[1]", "C").
KTBNLearner< GUM_SCALAR > & useSmoothingPrior(double weight) override
the default weight (key priorWeight of the section learning)
KTBNLearner< GUM_SCALAR > & useScoreBIC() override
Returns a warning string if the current score and prior are incompatible, empty string otherwise.
bool isIgnoringMissingSymbols() const
Whether build() drops the rows carrying a missing symbol.
KTBNLearner< GUM_SCALAR > & useMIIC() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
void useScorefNML() override
Returns a warning string if the current score and prior are incompatible, empty string otherwise.
KTBNLearner< GUM_SCALAR > & useScoreMDL() override
Returns a warning string if the current score and prior are incompatible, empty string otherwise.
KTBNLearner< GUM_SCALAR > & useSmoothingPrior()
the default weight (key priorWeight of the section learning)
KTBNLearner< GUM_SCALAR > & eraseNoChildrenNode(std::string_view base, int slice) override
Undo a previous addNoChildrenNode for a single (base, slice) node.
static std::unordered_set< std::string > _inferAtemporalVars_(std::string_view dirPath, std::string_view csvBaseName, Size nbSamples, Size k, const std::vector< std::string > &missingSymbols)
checks k >= 2, then delegates the actual scan to the shared IKTBNLearner::scanConstantColumns() (also...
KTBNLearner< GUM_SCALAR > & eraseForbiddenIntraSliceArc(std::string_view tailBase, std::string_view headBase) override
Undo a previous addForbiddenIntraSliceArc.
std::string toString() const
Human-readable summary of the learner's current configuration.
std::vector< Size > _nbTimeSlices_
Captured once by build() and exposed by nbRows(). This is the raw trajectory length,...
std::vector< std::tuple< std::string, std::string, std::string > > state() const
Settings as a vector of (key, value, comment) tuples (mirrors BNLearner::state()).
KTBNLearner< GUM_SCALAR > & addMandatoryArc(std::string_view tailNode, std::string_view headNode) override
Force tailNode to be a parent of headNode (engine names, e.g. "X[1]", "C").
bool hasMissingValues() const
True if any internal database contains missing values.
KTBNLearner< GUM_SCALAR > & setMaxIndegree(Size max_indegree) override
Cap the number of parents of any single node.
KTBNLearner< GUM_SCALAR > & addForbiddenIntraSliceArc(std::string_view tailBase, std::string_view headBase) override
Forbid tailBase -> headBase at every intra-slice position (i.e. tailBase[t] -> headBase[t] for all t ...
KTBNLearner< GUM_SCALAR > & addPossibleEdge(std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice) override
Add a candidate edge for MIIC (only edges explicitly listed are explored).
bool _isKnownBase_(std::string_view base) const override
whether base is one of this learner's variables; read straight from the prior k-TBN,...
KTBNLearner< GUM_SCALAR > & useMDLCorrection() override
Engine-name pairs (tail, head) of arcs flagged as hiding a latent variable by MIIC (merged from all i...
KTBNLearner< GUM_SCALAR > & useLocalSearchWithTabuList()
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNLearner< GUM_SCALAR > & useLocalSearchWithTabuList(Size tabu_size, Size nb_decrease) override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNLearner< GUM_SCALAR > & useScoreBDeu() override
Returns a warning string if the current score and prior are incompatible, empty string otherwise.
KTBNLearner< GUM_SCALAR > & eraseMandatoryArc(std::string_view tailNode, std::string_view headNode) override
Undo a previous addMandatoryArc (engine names, e.g. "X[1]", "C").
KTBNLearner< GUM_SCALAR > & addNoParentNode(std::string_view base, int slice) override
Declare a single (base, slice) node as a root (no parents).
std::unique_ptr< BNLearner< GUM_SCALAR > > _atemporalLearner_
learns the atemporal variables (arcs atemporal -> atemporal)
KTBNLearner< GUM_SCALAR > & useFCI() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNLearner(std::string_view dirPath, std::string_view csvBaseName, Size nbSamples, Size k, const std::unordered_set< std::string > &atemporalVars, const std::vector< std::string > &missingSymbols={"?"}, bool induceTypes=true, bool ignoreMissingSymbols=false)
Structure-learning constructor — variable roles supplied explicitly.
Size k() const
Order of the k-TBN being learned.
KTBNLearner< GUM_SCALAR > & eraseNoParentNode(std::string_view base, int slice) override
Undo a previous addNoParentNode for a single (base, slice) node.
void _forEachAllSlicesPair_(std::string_view tailBase, std::string_view headBase, F &&f) const
Apply f(tailSlice, headSlice) to every causally-possible slice pair of an all-slices constraint betwe...
Typed, documented, sectioned configuration singleton read from an .ini content.
The class representing a tabular database stored in RAM.
#define GUM_ERROR(type, msg)
Definition exceptions.h:76
std::size_t Size
In aGrUM, hashed values are unsigned long int.
Definition types.h:74
Size NodeId
Type for node ids.
include the inlined functions if necessary
Definition CSVParser.h:55