aGrUM 3.3.2
a C++ library for (probabilistic) graphical models
KTBNAdaptiveLearner_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 <cmath>
52#include <filesystem>
53#include <format>
54#include <fstream>
55#include <memory>
56
69
70#include <unordered_map>
71
72namespace gum::learning {
73
74 // =========================================================================
75 // Constructors / Destructors
76 // =========================================================================
77
78 template < GUM_Numeric GUM_SCALAR >
80 std::string_view dirPath,
81 std::string_view csvBaseName,
82 Size nbSamples,
83 Size kMax,
84 const std::unordered_set< std::string >& atemporalVars,
85 const std::vector< std::string >& missingSymbols,
86 bool induceTypes) :
87 _dirPath_(dirPath), _csvBaseName_(csvBaseName), _nbSamples_(nbSamples), _kMax_(kMax),
88 _atemporalVars_(atemporalVars), _missingSymbols_(missingSymbols), _induceTypes_(induceTypes) {
89 // cheap argument checks first, so bad calls fail before touching the disk
91 if (nbSamples < 1) GUM_ERROR(InvalidArgument, "KTBNAdaptiveLearner requires nbSamples >= 1")
92
93 // Load the base-variable names (the CSV columns) so the constraint setters can
94 // reject unknown names eagerly. Only the header row is needed, so we parse a
95 // single line instead of loading and typing the whole file. The column order
96 // matches what every per-k KTBNLearner reads from the same header at
97 // learnKTBN() time.
98 namespace fs = std::filesystem;
99 const fs::path firstCSV = fs::path{dirPath} / (std::string{csvBaseName} + "1.csv");
100 std::ifstream is(firstCSV, std::ifstream::in);
101 if (!is.is_open()) GUM_ERROR(IOError, "Cannot open " << firstCSV.string())
102
103 CSVParser parser(is, firstCSV.string());
104 if (!parser.next())
105 GUM_ERROR(IOError, "Empty trajectory file (no header row): " << firstCSV.string())
106 const std::vector< std::string >& header = parser.current();
107 _baseNames_.insert(header.begin(), header.end());
108
109 // every declared atemporal variable must actually be one of those columns
110 for (const std::string& aname: _atemporalVars_)
111 if (!_baseNames_.contains(aname))
113 "atemporal variable '" << aname << "' not found in the CSV header")
114
115 GUM_CONSTRUCTOR(KTBNAdaptiveLearner)
116 }
117
118 template < GUM_Numeric GUM_SCALAR >
120 std::string_view dirPath,
121 std::string_view csvBaseName,
122 Size nbSamples,
123 Size kMax,
124 const std::vector< std::string >& missingSymbols,
125 bool induceTypes) :
126 // _inferAtemporalVars_ checks kMax>=2 and nbSamples>=1 itself, before
127 // opening anything (see its declaration) — this initialiser-list call
128 // runs before the delegated-to constructor's own body, so those checks
129 // cannot be left to that body the way the explicit constructor does.
130 // Delegates to the explicit-atemporalVars constructor for the rest
131 // (header read); _inferAtemporalVars_ needs nbSamples, unlike the
132 // header-only read above, since one trajectory alone cannot show that a
133 // value stays constant.
135 dirPath,
136 csvBaseName,
137 nbSamples,
138 kMax,
139 _inferAtemporalVars_(dirPath, csvBaseName, nbSamples, kMax, missingSymbols),
140 missingSymbols,
141 induceTypes) {}
142
143 template < GUM_Numeric GUM_SCALAR >
145 std::string_view dirPath,
146 std::string_view csvBaseName,
147 Size nbSamples,
148 Size kMax,
149 const std::vector< std::string >& missingSymbols) {
151 if (nbSamples < 1) GUM_ERROR(InvalidArgument, "KTBNAdaptiveLearner requires nbSamples >= 1")
153 csvBaseName,
154 nbSamples,
155 missingSymbols);
156 }
157
158 template < GUM_Numeric GUM_SCALAR >
160 std::string_view dirPath,
161 std::string_view csvBaseName,
162 Size nbSamples,
163 Size kMax,
164 const BayesNet< GUM_SCALAR >& bn,
165 const std::unordered_set< std::string >& atemporalVars,
166 const std::vector< std::string >& missingSymbols) :
167 _dirPath_(dirPath), _csvBaseName_(csvBaseName), _nbSamples_(nbSamples), _kMax_(kMax),
168 _atemporalVars_(atemporalVars), _missingSymbols_(missingSymbols), _induceTypes_(false),
169 _prior_bn_(std::make_unique< BayesNet< GUM_SCALAR > >(bn)) {
171 if (nbSamples < 1) GUM_ERROR(InvalidArgument, "KTBNAdaptiveLearner requires nbSamples >= 1")
172
173 // the schema BN is the authoritative variable universe here (not the CSV
174 // header): take the base names from it, so the constraint setters validate
175 // against the same variables every per-k KTBNLearner will use. The CSV is
176 // read only later, at learnKTBN() time.
177 for (const NodeId node: bn.nodes())
178 _baseNames_.insert(bn.variable(node).name());
179
180 // every declared atemporal variable must be a node of the schema BN
181 for (const std::string& aname: _atemporalVars_)
182 if (!_baseNames_.contains(aname))
184 "atemporal variable '" << aname << "' not found in the schema BN")
185
186 GUM_CONSTRUCTOR(KTBNAdaptiveLearner)
187 }
188
189 template < GUM_Numeric GUM_SCALAR >
193
194 // =========================================================================
195 // Main learning methods
196 // =========================================================================
197
198 template < GUM_Numeric GUM_SCALAR >
200 // Explore every candidate order _kMin_.._kMax_ and keep the k-TBN with the
201 // best cross-k model-selection score (BIC by default; see useOrderScore*).
202 // _kMin_ -- 2 unless raised by a constraint naming a concrete slice, see
203 // _recomputeKMin_ -- skips candidates that would only drop that constraint.
204 // Each candidate is a full fixed-k problem: a fresh KTBNLearner on the same
205 // trajectories, replaying the recorded configuration and constraints (those
206 // whose slices do not fit that k are dropped by _applyConstraints_).
207 // Reset first: a re-entry, or a throw below, must not leave a stale selection
208 // readable through bestK() / latentVariables().
209 _bestK_ = 0;
210 _bestLatentVariables_.clear();
211 _scorePerCandidateK_.clear();
212 KTBN< GUM_SCALAR > best;
213 Size bestK = 0; // local; committed to _bestK_ only if the whole sweep succeeds
214 double bestScore = 0.0; // unread until the first candidate sets it
215 double logN = 0.0; // log2 of the total number of observations
216 std::vector< std::pair< Size, double > > scores; // per-k scores, committed at the end
217 std::vector< std::pair< std::string, std::string > >
218 bestLatents; // winner's latent pairs, committed at the end
219
220 for (Size k = _kMin_; k <= _kMax_; ++k) {
221 // build this candidate's fixed-k learner: from the schema BN when one was
222 // supplied (domains fixed explicitly), else from the CSV (domains inferred).
223 // KTBNLearner is non-movable, so hold it through a unique_ptr.
224 std::unique_ptr< KTBNLearner< GUM_SCALAR > > learnerPtr
225 = _prior_bn_ ? std::make_unique< KTBNLearner< GUM_SCALAR > >(_dirPath_,
228 k,
229 *_prior_bn_,
233 : std::make_unique< KTBNLearner< GUM_SCALAR > >(_dirPath_,
236 k,
241 KTBNLearner< GUM_SCALAR >& learner = *learnerPtr;
242
243 // Refused here rather than deep inside structure learning: learnDag_ would
244 // otherwise raise its own generic message only after this candidate's
245 // databases had been built. Every candidate reads the same trajectories, so
246 // the verdict on the first holds for all.
247 if (!_ignoreMissingSymbols_ && learner.hasMissingValues())
249 "the trajectories contain missing values. Neither aGrUM's structure learning "
250 "nor the cross-k order score can evaluate an incomplete window. Call "
251 "ignoreMissingSymbols() to learn and score on the fully observed data only "
252 "(see its warning: dropping skews the selection towards larger k).")
253
254 // sample size for the BIC penalty: the total number of time-slice rows over
255 // all trajectories. Independent of k, so it is computed once on the first
256 // candidate and reused — it must stay fixed for the scores to compare.
257 if (logN == 0.0) {
258 Size nbObs = 0;
259 for (const Size len: learner.nbRows())
260 nbObs += len;
261 logN = std::log2(nbObs);
262 }
263
264 _applyConfig_(learner);
265 _applyConstraints_(learner, k);
266
267 KTBN< GUM_SCALAR > candidate = learner.learnKTBN();
268
269 // Cross-k model selection by the recorded order score (BIC by default):
270 // it must be comparable across k, unlike the per-k structure score, so it
271 // is computed here on the whole learned k-TBN rather than read off the
272 // internal learners. bestK == 0 means nothing is selected yet, so the
273 // first candidate is always taken; a strict '>' afterwards keeps the
274 // smallest k on ties (mild parsimony).
275 const double score = _orderSelectionScore_(candidate, logN);
276 scores.emplace_back(k, score);
277 if (bestK == 0 || score > bestScore) {
278 bestScore = score;
279 best = std::move(candidate);
280 bestK = k;
281 // capture the winner's latent-variable annotations while its learner is
282 // still alive (only MIIC produces them; other algos leave the set empty)
283 bestLatents = (_algo_ == IBNLearner::AlgoType::MIIC)
284 ? learner.latentVariables()
285 : std::vector< std::pair< std::string, std::string > >{};
286 }
287 }
288
289 // Commit only after every candidate has succeeded. An exception thrown above
290 // (e.g. a trajectory too short for some candidate k) leaves the members at
291 // their reset state, so bestK() / latentVariables() / scorePerCandidateK()
292 // keep reporting "not learned" — the all-or-nothing guarantee promised above.
293 _bestK_ = bestK;
294 _scorePerCandidateK_ = std::move(scores);
295 _bestLatentVariables_ = std::move(bestLatents);
296 return best;
297 }
298
299 template < GUM_Numeric GUM_SCALAR >
301 // _bestK_ stays at its sentinel 0 (never a valid order: candidates are >= 2)
302 // until learnKTBN() selects one, so 0 means no learning has run yet.
303 if (_bestK_ == 0)
305 "bestK() is undefined: call learnKTBN() before querying the selected order.")
306 return _bestK_;
307 }
308
309 template < GUM_Numeric GUM_SCALAR >
310 const std::vector< std::pair< std::string, std::string > >&
312 // gated on the same sentinel as bestK(): 0 means learnKTBN() has not run.
313 if (_bestK_ == 0)
314 GUM_ERROR(OperationNotAllowed, "latentVariables() is undefined: call learnKTBN() first.")
316 }
317
318 template < GUM_Numeric GUM_SCALAR >
319 const std::vector< std::pair< Size, double > >&
321 // same sentinel gate as bestK()/latentVariables(): 0 means learnKTBN() has not run.
322 if (_bestK_ == 0)
323 GUM_ERROR(
325 "scorePerCandidateK() is undefined: call learnKTBN() before querying the per-k scores.")
327 }
328
329 // =========================================================================
330 // Diagnostics
331 // =========================================================================
332
333 template < GUM_Numeric GUM_SCALAR >
337
338 template < GUM_Numeric GUM_SCALAR >
340 // constraint-based algorithms (MIIC, PC, FCI) consume no score, so no score/prior clash
341 // is possible. (Mirrors IBNLearner::isConstraintBased.)
342 const auto algo = _algo_;
344 || algo == IBNLearner::AlgoType::FCI)
345 return "";
346
347 // map the recorded prior to the internal PriorType. The adaptive learner only
348 // ever records NO_prior or SMOOTHING (its sole prior setter is useSmoothingPrior).
352
353 // delegate to the very same per-score static checks BNLearner uses
354 switch (_score_) {
363 default : return ""; // K2 is never recorded by this learner's setters
364 }
365 }
366
367 template < GUM_Numeric GUM_SCALAR >
368 std::vector< std::tuple< std::string, std::string, std::string > >
370 std::vector< std::tuple< std::string, std::string, std::string > > vals;
371 const auto add = [&](std::string k, std::string v, std::string c = "") {
372 vals.emplace_back(std::move(k), std::move(v), std::move(c));
373 };
374 // render a set of engine-name pairs as "{a->b, c->d}"
375 const auto arcs = [](const std::set< std::pair< std::string, std::string > >& s) {
376 std::string r = "{";
377 bool first = true;
378 for (const auto& [a, b]: s) {
379 if (!first) r += ", ";
380 first = false;
381 r += a + "->" + b;
382 }
383 return r + "}";
384 };
385 const auto names = [](const std::set< std::string >& s) {
386 std::string r = "{";
387 bool first = true;
388 for (const auto& n: s) {
389 if (!first) r += ", ";
390 first = false;
391 r += n;
392 }
393 return r + "}";
394 };
395 // render a set of (tailBase, headBase, lag) triples as "{a->b (lag 1), ...}"
396 const auto kernelArcs = [](const std::set< std::tuple< std::string, std::string, int > >& s) {
397 std::string r = "{";
398 bool first = true;
399 for (const auto& [a, b, lag]: s) {
400 if (!first) r += ", ";
401 first = false;
402 r += a + "->" + b + " (lag " + std::to_string(lag) + ")";
403 }
404 return r + "}";
405 };
406
407 add("Candidate orders", std::to_string(_kMin_) + ".." + std::to_string(_kMax_));
408 add("Selected k", _bestK_ == 0 ? "not learned yet" : std::to_string(_bestK_));
409 add("Base variables", std::to_string(_baseNames_.size()));
410 add("Atemporal variables", names({_atemporalVars_.begin(), _atemporalVars_.end()}));
411
412 const auto algo = _algo_;
413 switch (algo) {
414 case IBNLearner::AlgoType::MIIC : add("Algorithm", "MIIC"); break;
415 case IBNLearner::AlgoType::PC : add("Algorithm", "PC"); break;
416 case IBNLearner::AlgoType::FCI : add("Algorithm", "FCI"); break;
418 add("Algorithm", "Greedy Thick Thinning");
419 break;
421 add("Algorithm", "Greedy Hill Climbing");
422 break;
424 add("Algorithm", "Extended Greedy Hill Climbing");
425 break;
427 add("Algorithm", "Local Search with Tabu List");
428 add("Tabu list size", std::to_string(_tabuSize_));
429 add("Tabu nb decrease", std::to_string(_nbDecrease_));
430 break;
431 default : add("Algorithm", "(other)"); break;
432 }
433
434 if (algo == IBNLearner::AlgoType::MIIC) {
435 switch (_correction_) {
436 case CorrectedMutualInformation::KModeTypes::MDL : add("Correction", "MDL"); break;
437 case CorrectedMutualInformation::KModeTypes::NML : add("Correction", "NML"); break;
439 add("Correction", "No correction");
440 break;
441 }
442 } else if (algo != IBNLearner::AlgoType::PC && algo != IBNLearner::AlgoType::FCI) {
443 switch (_score_) {
444 case IBNLearner::ScoreType::AIC : add("Structure score", "AIC"); break;
445 case IBNLearner::ScoreType::BD : add("Structure score", "BD"); break;
446 case IBNLearner::ScoreType::BDeu : add("Structure score", "BDeu"); break;
447 case IBNLearner::ScoreType::BIC : add("Structure score", "BIC"); break;
448 case IBNLearner::ScoreType::fNML : add("Structure score", "fNML"); break;
450 add("Structure score", "Log2Likelihood");
451 break;
452 case IBNLearner::ScoreType::MDL : add("Structure score", "MDL"); break;
453 default : add("Structure score", "(other)"); break;
454 }
455 }
456
457 // the outer, cross-k criterion — distinct from the per-k structure score above
458 switch (_orderScore_) {
459 case OrderScoreType::BIC : add("Order selection score", "BIC"); break;
460 case OrderScoreType::AIC : add("Order selection score", "AIC"); break;
461 case OrderScoreType::fNML : add("Order selection score", "fNML"); break;
462 }
463
465 add("Prior", "Smoothing", checkScorePriorCompatibility());
466 add("Prior weight", std::to_string(_priorWeight_));
467 } else {
468 add("Prior", "no prior is set", checkScorePriorCompatibility());
469 }
470
471 if (!_forbiddenArcs_.empty()) add("Forbidden arcs", arcs(_forbiddenArcs_));
472 if (!_mandatoryArcs_.empty()) add("Mandatory arcs", arcs(_mandatoryArcs_));
473 if (!_forbiddenKernelArcs_.empty())
474 add("Forbidden kernel arcs", kernelArcs(_forbiddenKernelArcs_));
475 if (!_mandatoryKernelArcs_.empty())
476 add("Mandatory kernel arcs", kernelArcs(_mandatoryKernelArcs_));
477 if (!_possibleEdges_.empty()) add("Possible edges", arcs(_possibleEdges_));
478 if (!_forbiddenIntraSliceArcs_.empty())
479 add("Forbidden intra-slice arcs", arcs(_forbiddenIntraSliceArcs_));
480 if (!_forbiddenArcsAllSlices_.empty())
481 add("Forbidden all-slices arcs", arcs(_forbiddenArcsAllSlices_));
482 if (!_noParentNodes_.empty()) add("No-parent nodes", names(_noParentNodes_));
483 if (!_noChildrenNodes_.empty()) add("No-children nodes", names(_noChildrenNodes_));
484 if (_maxIndegree_ != std::numeric_limits< Size >::max())
485 add("Max in-degree", std::to_string(_maxIndegree_));
486 if (!_allowAdditions_) add("Arc additions", "forbidden");
487 if (!_allowDeletions_) add("Arc deletions", "forbidden");
488 if (!_allowReversals_) add("Arc reversals", "forbidden");
489
490 return vals;
491 }
492
493 template < GUM_Numeric GUM_SCALAR >
495 // aligned "key : value (comment)" listing, same layout as BNLearner::toString
496 const auto st = state();
497 std::size_t maxkey = 0;
498 for (const auto& t: st)
499 maxkey = std::max(maxkey, std::get< 0 >(t).length());
500
501 std::string s;
502 for (const auto& t: st) {
503 s += std::format("{:<{}} : {}", std::get< 0 >(t), maxkey, std::get< 1 >(t));
504 if (!std::get< 2 >(t).empty()) s += std::format(" ({})", std::get< 2 >(t));
505 s += '\n';
506 }
507 return s;
508 }
509
510 // =========================================================================
511 // Score selection
512 // =========================================================================
513
514 template < GUM_Numeric GUM_SCALAR >
519
520 template < GUM_Numeric GUM_SCALAR >
525
526 template < GUM_Numeric GUM_SCALAR >
531
532 template < GUM_Numeric GUM_SCALAR >
537
538 template < GUM_Numeric GUM_SCALAR >
543
544 template < GUM_Numeric GUM_SCALAR >
549
550 template < GUM_Numeric GUM_SCALAR >
554
555 // =========================================================================
556 // Order selection (cross-k model selection)
557 // =========================================================================
558
559 template < GUM_Numeric GUM_SCALAR >
564
565 template < GUM_Numeric GUM_SCALAR >
570
571 template < GUM_Numeric GUM_SCALAR >
576
577 // =========================================================================
578 // Missing values
579 // =========================================================================
580
581 template < GUM_Numeric GUM_SCALAR >
584 _ignoreMissingSymbols_ = ignore;
585 return *this;
586 }
587
588 template < GUM_Numeric GUM_SCALAR >
592
593 // =========================================================================
594 // Algorithm selection
595 // =========================================================================
596
597 template < GUM_Numeric GUM_SCALAR >
602
603 template < GUM_Numeric GUM_SCALAR >
609
610 template < GUM_Numeric GUM_SCALAR >
616
617 template < GUM_Numeric GUM_SCALAR >
623
624 template < GUM_Numeric GUM_SCALAR >
627 Size nb_decrease) {
629 _tabuSize_ = tabu_size;
630 _nbDecrease_ = nb_decrease;
631 return *this;
632 }
633
634 template < GUM_Numeric GUM_SCALAR >
639
640 template < GUM_Numeric GUM_SCALAR >
645
646 template < GUM_Numeric GUM_SCALAR >
651
652 template < GUM_Numeric GUM_SCALAR >
657
658 // =========================================================================
659 // MIIC correction
660 // =========================================================================
661
662 template < GUM_Numeric GUM_SCALAR >
667
668 template < GUM_Numeric GUM_SCALAR >
673
674 template < GUM_Numeric GUM_SCALAR >
679
680 // =========================================================================
681 // Prior selection
682 // =========================================================================
683
684 template < GUM_Numeric GUM_SCALAR >
688
689 template < GUM_Numeric GUM_SCALAR >
696
697 // =========================================================================
698 // Structural constraints
699 // =========================================================================
700
701 template < GUM_Numeric GUM_SCALAR >
704 std::string_view headNode) {
705 const auto [tailBase, tailSlice] = _determineNode_(std::string{tailNode});
706 const auto [headBase, headSlice] = _determineNode_(std::string{headNode});
707 _verifyBase_(tailBase, tailSlice);
708 _verifyBase_(headBase, headSlice);
709 _forbiddenArcs_.emplace(std::string{tailNode}, std::string{headNode});
710 // no _checkArcTemporallyFeasible_ call on this path (forbidding an
711 // already-impossible backward arc is a harmless no-op), so head is not
712 // guaranteed >= tail here: both slices must be checked.
713 _raiseKMinForSlice_(tailSlice);
714 _raiseKMinForSlice_(headSlice);
715 return *this;
716 }
717
718 template < GUM_Numeric GUM_SCALAR >
721 int tailSlice,
722 std::string_view headBase,
723 int headSlice) {
724 // validate before _encode_ flattens the slice (a negative one would
725 // silently read back as atemporal, losing the real error)
726 _verifyBase_(tailBase, tailSlice);
727 _verifyBase_(headBase, headSlice);
728 return addForbiddenArc(_encode_(tailBase, tailSlice), _encode_(headBase, headSlice));
729 }
730
731 template < GUM_Numeric GUM_SCALAR >
734 std::string_view headNode) {
735 const auto [tailBase, tailSlice] = _determineNode_(std::string{tailNode});
736 const auto [headBase, headSlice] = _determineNode_(std::string{headNode});
737 _verifyBase_(tailBase, tailSlice);
738 _verifyBase_(headBase, headSlice);
739 this->_checkArcTemporallyFeasible_(tailNode, headNode, "un-forbid the arc");
740 _forbiddenArcs_.erase({std::string{tailNode}, std::string{headNode}});
742 return *this;
743 }
744
745 template < GUM_Numeric GUM_SCALAR >
748 int tailSlice,
749 std::string_view headBase,
750 int headSlice) {
751 // validate before _encode_ flattens the slice (a negative one would
752 // silently read back as atemporal, losing the real error)
753 _verifyBase_(tailBase, tailSlice);
754 _verifyBase_(headBase, headSlice);
755 return eraseForbiddenArc(_encode_(tailBase, tailSlice), _encode_(headBase, headSlice));
756 }
757
758 template < GUM_Numeric GUM_SCALAR >
761 std::string_view headNode) {
762 const auto [tailBase, tailSlice] = _determineNode_(std::string{tailNode});
763 const auto [headBase, headSlice] = _determineNode_(std::string{headNode});
764 _verifyBase_(tailBase, tailSlice);
765 _verifyBase_(headBase, headSlice);
766 // a mandatory arc must be feasible: reject up front the arcs the k-TBN can
767 // never contain (same check KTBNLearner::addMandatoryArc runs)
768 this->_checkArcTemporallyFeasible_(tailNode, headNode, "force the mandatory arc");
769 _mandatoryArcs_.emplace(std::string{tailNode}, std::string{headNode});
770 // the feasibility check above just rejected headSlice < tailSlice, so
771 // headSlice >= tailSlice is guaranteed here: it alone determines _kMin_.
772 _raiseKMinForSlice_(headSlice);
773 return *this;
774 }
775
776 template < GUM_Numeric GUM_SCALAR >
779 int tailSlice,
780 std::string_view headBase,
781 int headSlice) {
782 // validate before _encode_ flattens the slice (a negative one would
783 // silently read back as atemporal, losing the real error)
784 _verifyBase_(tailBase, tailSlice);
785 _verifyBase_(headBase, headSlice);
786 return addMandatoryArc(_encode_(tailBase, tailSlice), _encode_(headBase, headSlice));
787 }
788
789 template < GUM_Numeric GUM_SCALAR >
792 std::string_view headNode) {
793 const auto [tailBase, tailSlice] = _determineNode_(std::string{tailNode});
794 const auto [headBase, headSlice] = _determineNode_(std::string{headNode});
795 _verifyBase_(tailBase, tailSlice);
796 _verifyBase_(headBase, headSlice);
797 // no feasibility check: erasing a never-forced arc is a harmless no-op
798 // (mirrors KTBNLearner::eraseMandatoryArc)
799 _mandatoryArcs_.erase({std::string{tailNode}, std::string{headNode}});
801 return *this;
802 }
803
804 template < GUM_Numeric GUM_SCALAR >
807 int tailSlice,
808 std::string_view headBase,
809 int headSlice) {
810 // validate before _encode_ flattens the slice (a negative one would
811 // silently read back as atemporal, losing the real error)
812 _verifyBase_(tailBase, tailSlice);
813 _verifyBase_(headBase, headSlice);
814 return eraseMandatoryArc(_encode_(tailBase, tailSlice), _encode_(headBase, headSlice));
815 }
816
817 // =========================================================================
818 // Kernel-relative arcs
819 // =========================================================================
820
821 template < GUM_Numeric GUM_SCALAR >
824 int lag,
825 std::string_view headBase) {
826 _verifyKernelArc_(tailBase, headBase, lag);
827 _forbiddenKernelArcs_.emplace(std::string{tailBase}, std::string{headBase}, lag);
829 return *this;
830 }
831
832 template < GUM_Numeric GUM_SCALAR >
835 int lag,
836 std::string_view headBase) {
837 _verifyKernelArc_(tailBase, headBase, lag);
838 _forbiddenKernelArcs_.erase({std::string{tailBase}, std::string{headBase}, lag});
840 return *this;
841 }
842
843 template < GUM_Numeric GUM_SCALAR >
846 int lag,
847 std::string_view headBase) {
848 _verifyKernelArc_(tailBase, headBase, lag);
849 // no separate feasibility check: lag >= 0 (just verified) already guarantees
850 // headSlice = k-1 >= k-1-lag = tailSlice for every candidate, so this can
851 // never be a backward-in-time arc (see addMandatoryKernelArc's doc comment)
852 _mandatoryKernelArcs_.emplace(std::string{tailBase}, std::string{headBase}, lag);
854 return *this;
855 }
856
857 template < GUM_Numeric GUM_SCALAR >
860 int lag,
861 std::string_view headBase) {
862 _verifyKernelArc_(tailBase, headBase, lag);
863 _mandatoryKernelArcs_.erase({std::string{tailBase}, std::string{headBase}, lag});
865 return *this;
866 }
867
868 template < GUM_Numeric GUM_SCALAR >
871 std::string_view headBase) {
872 // these constraints carry no single slice, so no slice range is checked;
873 // an atemporal base has no intra-slice position and is rejected eagerly
874 // here, where KTBNLearner would throw at its own setter (expanding to "C[t]")
875 _checkBaseIsTemporal_(tailBase, "an intra-slice constraint");
876 _checkBaseIsTemporal_(headBase, "an intra-slice constraint");
877 // record the base pair; unlike KTBNLearner it cannot be expanded per-slice
878 // now (k is not fixed) — learnKTBN() expands it for each candidate k
879 _forbiddenIntraSliceArcs_.emplace(std::string{tailBase}, std::string{headBase});
880 return *this;
881 }
882
883 template < GUM_Numeric GUM_SCALAR >
886 std::string_view headBase) {
887 // same eager rejection as addForbiddenIntraSliceArc: such a constraint can
888 // never have been recorded
889 _checkBaseIsTemporal_(tailBase, "an intra-slice constraint");
890 _checkBaseIsTemporal_(headBase, "an intra-slice constraint");
891 _forbiddenIntraSliceArcs_.erase({std::string{tailBase}, std::string{headBase}});
892 return *this;
893 }
894
895 template < GUM_Numeric GUM_SCALAR >
898 std::string_view headBase) {
901 // record the base pair; learnKTBN() expands it over every causally-possible
902 // slice pair for each candidate k (k is not fixed here)
903 _forbiddenArcsAllSlices_.emplace(std::string{tailBase}, std::string{headBase});
904 return *this;
905 }
906
907 template < GUM_Numeric GUM_SCALAR >
910 std::string_view headBase) {
913 _forbiddenArcsAllSlices_.erase({std::string{tailBase}, std::string{headBase}});
914 return *this;
915 }
916
917 template < GUM_Numeric GUM_SCALAR >
919 KTBNAdaptiveLearner< GUM_SCALAR >::addNoParentNode(std::string_view base, int slice) {
920 // validate before _encode_ flattens the slice (see the arc overloads above)
921 _verifyBase_(base, slice);
922 return addNoParentNode(_encode_(base, slice));
923 }
924
925 template < GUM_Numeric GUM_SCALAR >
928 const auto [base, slice] = _determineNode_(std::string{name});
929 _verifyBase_(base, slice);
930 _noParentNodes_.insert(std::string{name});
931 _raiseKMinForSlice_(slice);
932 return *this;
933 }
934
935 template < GUM_Numeric GUM_SCALAR >
938 // validate before _encode_ flattens the slice (see the arc overloads above)
939 _verifyBase_(base, slice);
940 return eraseNoParentNode(_encode_(base, slice));
941 }
942
943 template < GUM_Numeric GUM_SCALAR >
946 const auto [base, slice] = _determineNode_(std::string{name});
947 _verifyBase_(base, slice);
948 _noParentNodes_.erase(std::string{name});
950 return *this;
951 }
952
953 template < GUM_Numeric GUM_SCALAR >
956 // validate before _encode_ flattens the slice (see the arc overloads above)
957 _verifyBase_(base, slice);
958 return addNoChildrenNode(_encode_(base, slice));
959 }
960
961 template < GUM_Numeric GUM_SCALAR >
964 const auto [base, slice] = _determineNode_(std::string{name});
965 _verifyBase_(base, slice);
966 _noChildrenNodes_.insert(std::string{name});
967 _raiseKMinForSlice_(slice);
968 return *this;
969 }
970
971 template < GUM_Numeric GUM_SCALAR >
974 // validate before _encode_ flattens the slice (see the arc overloads above)
975 _verifyBase_(base, slice);
976 return eraseNoChildrenNode(_encode_(base, slice));
977 }
978
979 template < GUM_Numeric GUM_SCALAR >
982 const auto [base, slice] = _determineNode_(std::string{name});
983 _verifyBase_(base, slice);
984 _noChildrenNodes_.erase(std::string{name});
986 return *this;
987 }
988
989 template < GUM_Numeric GUM_SCALAR >
992 int tailSlice,
993 std::string_view headBase,
994 int headSlice) {
995 // validate before _encode_ flattens the slice (a negative one would
996 // silently read back as atemporal, losing the real error)
997 _verifyBase_(tailBase, tailSlice);
998 _verifyBase_(headBase, headSlice);
999 return addPossibleEdge(_encode_(tailBase, tailSlice), _encode_(headBase, headSlice));
1000 }
1001
1002 template < GUM_Numeric GUM_SCALAR >
1005 std::string_view head) {
1006 const auto [tailBase, tailSlice] = _determineNode_(std::string{tail});
1007 const auto [headBase, headSlice] = _determineNode_(std::string{head});
1008 _verifyBase_(tailBase, tailSlice);
1009 _verifyBase_(headBase, headSlice);
1010 // an edge is undirected (BNLearner stores it as a gum::Edge), so the pair is
1011 // normalized alphabetically: (A,B) and (B,A) are one and the same record
1012 std::string first{tail}, second{head};
1013 if (second < first) std::swap(first, second);
1014 _possibleEdges_.emplace(std::move(first), std::move(second));
1015 // an edge is undirected and unchecked, so neither slice dominates: both
1016 // must be checked (tailSlice/headSlice, decoded above the swap, are
1017 // unaffected by it).
1018 _raiseKMinForSlice_(tailSlice);
1019 _raiseKMinForSlice_(headSlice);
1020 return *this;
1021 }
1022
1023 template < GUM_Numeric GUM_SCALAR >
1026 int tailSlice,
1027 std::string_view headBase,
1028 int headSlice) {
1029 // validate before _encode_ flattens the slice (a negative one would
1030 // silently read back as atemporal, losing the real error)
1031 _verifyBase_(tailBase, tailSlice);
1032 _verifyBase_(headBase, headSlice);
1033 return erasePossibleEdge(_encode_(tailBase, tailSlice), _encode_(headBase, headSlice));
1034 }
1035
1036 template < GUM_Numeric GUM_SCALAR >
1039 std::string_view head) {
1040 const auto [tailBase, tailSlice] = _determineNode_(std::string{tail});
1041 const auto [headBase, headSlice] = _determineNode_(std::string{head});
1042 _verifyBase_(tailBase, tailSlice);
1043 _verifyBase_(headBase, headSlice);
1044 // same alphabetical normalization as addPossibleEdge, so erasing (B,A)
1045 // removes the edge recorded as (A,B)
1046 std::string first{tail}, second{head};
1047 if (second < first) std::swap(first, second);
1048 _possibleEdges_.erase({std::move(first), std::move(second)});
1050 return *this;
1051 }
1052
1053 template < GUM_Numeric GUM_SCALAR >
1056 _allowAdditions_ = allow;
1057 return *this;
1058 }
1059
1060 template < GUM_Numeric GUM_SCALAR >
1063 _allowDeletions_ = allow;
1064 return *this;
1065 }
1066
1067 template < GUM_Numeric GUM_SCALAR >
1070 _allowReversals_ = allow;
1071 return *this;
1072 }
1073
1074 template < GUM_Numeric GUM_SCALAR >
1077 _maxIndegree_ = max_indegree;
1078 return *this;
1079 }
1080
1081 // =========================================================================
1082 // Name encoding
1083 // =========================================================================
1084
1085 template < GUM_Numeric GUM_SCALAR >
1086 const std::unordered_set< std::string >&
1090
1091 template < GUM_Numeric GUM_SCALAR >
1092 bool KTBNAdaptiveLearner< GUM_SCALAR >::_isKnownBase_(std::string_view base) const {
1093 return _baseNames_.contains(std::string{base});
1094 }
1095
1096 // =========================================================================
1097 // Validation
1098 // =========================================================================
1099
1100 template < GUM_Numeric GUM_SCALAR >
1101 void KTBNAdaptiveLearner< GUM_SCALAR >::_verifyBase_(std::string_view base, int slice) const {
1102 if (!_baseNames_.contains(std::string{base}))
1104 "unknown base variable '" << base << "': it is not one of the data columns")
1105 // an atemporal variable's only valid slice is ATEMPORAL; reject eagerly
1106 // rather than recording e.g. "C[1]" and failing later at learnKTBN() time
1107 if (_atemporalVars_.contains(std::string{base})) {
1108 if (slice != KTBN< GUM_SCALAR >::ATEMPORAL)
1110 "atemporal variable '" << base << "' cannot be given a time slice (got " << slice
1111 << "): use KTBN::ATEMPORAL")
1112 return;
1113 }
1114 // temporal: valid slices are [0, kMax). A negative value other than
1115 // ATEMPORAL must be caught here -- _encode_ would turn it into "X[-5]",
1116 // which reads back as atemporal and slips past the slice-fit rule.
1117 if (slice != KTBN< GUM_SCALAR >::ATEMPORAL && slice < 0)
1119 "negative time slice " << slice << " for '" << base
1120 << "': slices start at 0 (use KTBN::ATEMPORAL to address an "
1121 "atemporal variable)")
1122 if (slice >= static_cast< int >(_kMax_))
1124 "time slice " << slice << " for '" << base
1125 << "' is out of range: it must be < kMax (" << _kMax_ << ")")
1126 }
1127
1128 template < GUM_Numeric GUM_SCALAR >
1130 std::string_view headBase,
1131 int lag) const {
1132 // an atemporal variable has a single instance, not a per-slice one, so it
1133 // has no kernel slice to anchor a lag against: same rule as the intra-slice
1134 // setters, hence the same shared check
1135 for (const std::string_view base: {tailBase, headBase})
1136 _checkBaseIsTemporal_(base, "a kernel-relative arc");
1137 // lag < 0 would place the tail AFTER the kernel slice (the last slice by
1138 // definition), which can never happen
1139 if (lag < 0) GUM_ERROR(InvalidArgument, "negative kernel lag " << lag << ": lag must be >= 0")
1140 // some candidate k in [2,kMax] must be able to place the tail at slice
1141 // k-1-lag >= 0, i.e. lag <= k-1 <= kMax-1
1142 if (lag >= static_cast< int >(_kMax_))
1144 "kernel lag " << lag << " is out of range: it must be < kMax (" << _kMax_
1145 << "), so some candidate k can place the tail at slice k-1-lag >= 0")
1146 }
1147
1148 // =========================================================================
1149 // Candidate-range bookkeeping
1150 // =========================================================================
1151
1152 template < GUM_Numeric GUM_SCALAR >
1154 if (slice != KTBN< GUM_SCALAR >::ATEMPORAL)
1155 _kMin_ = std::max(_kMin_, static_cast< Size >(slice) + 1);
1156 }
1157
1158 template < GUM_Numeric GUM_SCALAR >
1160 // kMin = 1 + the largest recorded slice (fits()'s "slice < k" rule means a
1161 // smaller k would drop that constraint). An erase can lower kMin, unlike a
1162 // single _raiseKMinForSlice_ call, so this rebuilds from scratch rather
1163 // than adjusting in place.
1164 _kMin_ = 2;
1165 for (const auto& [tail, head]: _forbiddenArcs_) {
1168 }
1169 for (const auto& [tail, head]: _mandatoryArcs_) {
1172 }
1173 for (const auto& [tail, head]: _possibleEdges_) {
1176 }
1177 for (const auto& node: _noParentNodes_)
1179 for (const auto& node: _noChildrenNodes_)
1181 // kernel-relative arcs: the lag itself is what must fit (the head's slice is
1182 // always the kernel k-1, which trivially fits any k), so raise on the lag
1183 // directly rather than decoding an engine name that doesn't exist yet.
1184 for (const auto& t: _forbiddenKernelArcs_)
1185 _raiseKMinForSlice_(std::get< 2 >(t));
1186 for (const auto& t: _mandatoryKernelArcs_)
1187 _raiseKMinForSlice_(std::get< 2 >(t));
1188 // _forbiddenIntraSliceArcs_ / _forbiddenArcsAllSlices_ carry no slice (they
1189 // are base-name pairs, expanded per-k by the fixed-k learner) and so are
1190 // left out: they never make a candidate drop anything, whatever k is.
1191 }
1192
1193 // =========================================================================
1194 // Configuration replay (learnKTBN helpers)
1195 // =========================================================================
1196
1197 template < GUM_Numeric GUM_SCALAR >
1199 // The algorithm is always set explicitly (the preferred algorithm of the configuration
1200 // may differ from the one of a fresh KTBNLearner). The other knobs are touched only when
1201 // they differ from their default (BDeu / MDL / NO_prior), and only if the chosen algorithm
1202 // actually consumes them.
1203 bool scoreBased = false;
1204 switch (_algo_) {
1206 learner.useMIIC();
1207 // MIIC uses a correction (not a score); apply it only when it is not the default MDL.
1208 switch (_correction_) {
1211 case CorrectedMutualInformation::KModeTypes::MDL : break; // default
1212 }
1213 break;
1215 learner.useGreedyHillClimbing();
1216 scoreBased = true;
1217 break;
1220 scoreBased = true;
1221 break;
1224 scoreBased = true;
1225 break;
1227 learner.useGreedyThickThinning();
1228 scoreBased = true;
1229 break;
1230 case IBNLearner::AlgoType::PC : learner.usePC(); break;
1231 case IBNLearner::AlgoType::FCI : learner.useFCI(); break;
1232 default : break; // K2 is never recorded by our setters
1233 }
1234
1235 // score-based algos consume a score; apply it only when it is not the default BDeu
1236 if (scoreBased && _score_ != IBNLearner::ScoreType::BDeu) {
1237 switch (_score_) {
1238 case IBNLearner::ScoreType::AIC : learner.useScoreAIC(); break;
1239 case IBNLearner::ScoreType::BD : learner.useScoreBD(); break;
1240 case IBNLearner::ScoreType::BIC : learner.useScoreBIC(); break;
1242 case IBNLearner::ScoreType::MDL : learner.useScoreMDL(); break;
1243 case IBNLearner::ScoreType::fNML : learner.useScorefNML(); break;
1244 default : break; // BDeu (guarded out) and K2 (never recorded)
1245 }
1246 }
1247
1248 // the prior feeds parameter estimation whatever the algorithm, so it is applied
1249 // independently of the score/correction split, again only when non-default
1252 }
1253
1254 template < GUM_Numeric GUM_SCALAR >
1256 Size k) const {
1257 const int ik = static_cast< int >(k);
1258 // an engine-name endpoint fits candidate k iff its slice is < k (ATEMPORAL == -1
1259 // always fits); a constraint touching a slice this candidate does not have is
1260 // skipped for this k only.
1261 auto fits = [&](const std::string& node) { return _determineNode_(node).second < ik; };
1262
1263 for (const auto& [tail, head]: _forbiddenArcs_)
1264 if (fits(tail) && fits(head)) learner.addForbiddenArc(tail, head);
1265 for (const auto& [tail, head]: _mandatoryArcs_)
1266 if (fits(tail) && fits(head)) learner.addMandatoryArc(tail, head);
1267 for (const auto& [tail, head]: _possibleEdges_)
1268 if (fits(tail) && fits(head)) learner.addPossibleEdge(tail, head);
1269 for (const auto& node: _noParentNodes_)
1270 if (fits(node)) learner.addNoParentNode(node);
1271 for (const auto& node: _noChildrenNodes_)
1272 if (fits(node)) learner.addNoChildrenNode(node);
1273
1274 // kernel-relative arcs: resolve the lag against this candidate's kernel
1275 // slice (k-1) into an explicit (base, slice) arc. Always fits once k >=
1276 // _kMin_ (guaranteed by _raiseKMinForSlice_/_recomputeKMin_ above), but the
1277 // guard mirrors fits()'s defensive style above rather than assuming it.
1278 for (const auto& [tailBase, headBase, lag]: _forbiddenKernelArcs_) {
1279 const int tailSlice = ik - 1 - lag;
1280 if (tailSlice >= 0) learner.addForbiddenArc(tailBase, tailSlice, headBase, ik - 1);
1281 }
1282 for (const auto& [tailBase, headBase, lag]: _mandatoryKernelArcs_) {
1283 const int tailSlice = ik - 1 - lag;
1284 if (tailSlice >= 0) learner.addMandatoryArc(tailBase, tailSlice, headBase, ik - 1);
1285 }
1286
1287 // base-only constraints: hand them to the fixed-k learner, which expands them
1288 // over its own slices (no manual expansion / no slice filtering needed here).
1289 for (const auto& [tailBase, headBase]: _forbiddenIntraSliceArcs_)
1290 learner.addForbiddenIntraSliceArc(tailBase, headBase);
1291 for (const auto& [tailBase, headBase]: _forbiddenArcsAllSlices_)
1292 learner.addForbiddenArcAllSlices(tailBase, headBase);
1293
1294 // structural-search knobs, applied only when the user changed them from default
1295 if (!_allowAdditions_) learner.allowArcAdditions(false);
1296 if (!_allowDeletions_) learner.allowArcDeletions(false);
1297 if (!_allowReversals_) learner.allowArcReversals(false);
1298 if (_maxIndegree_ != std::numeric_limits< Size >::max()) learner.setMaxIndegree(_maxIndegree_);
1299 }
1300
1301 // =========================================================================
1302 // Model selection
1303 // =========================================================================
1304
1305 template < GUM_Numeric GUM_SCALAR >
1306 template < typename PerInstance, typename PerNodeFinal >
1308 PerInstance perInstance,
1309 PerNodeFinal perNodeFinal) const {
1310 namespace fs = std::filesystem;
1311 const int k = static_cast< int >(net.k());
1312
1313 // Precomputed scorer for one template node, reused across every row of
1314 // every trajectory so the inner loop never rebuilds an Instantiation
1315 // (~3.7x the cost of one chgVal) or re-decodes a variable name. selfDom /
1316 // counts carry the accumulator a reduction criterion (fNML) closes over
1317 // in perNodeFinal; likelihood-style reductions ignore them.
1318 struct NodeEval {
1319 const Tensor< GUM_SCALAR >* cpt;
1320 Instantiation inst; // slaved to *cpt
1321 std::vector< std::string > dimName; // cpt.variable(d).name()
1322 std::vector< std::pair< std::string, int > > dimNode; // _determineNode_(name)
1323 Size selfDom; // |node| (CPT dim 0 is the node)
1324 std::unordered_map< Size, double > counts; // parent-config index -> #obs
1325 };
1326
1327 auto makeEval = [&](const Tensor< GUM_SCALAR >& cpt) {
1328 NodeEval e;
1329 e.cpt = &cpt;
1330 e.inst = Instantiation(cpt);
1331 e.selfDom = cpt.variable(0).domainSize(); // the node varies fastest (dim 0)
1332 e.dimName.reserve(cpt.nbrDim());
1333 e.dimNode.reserve(cpt.nbrDim());
1334 for (Idx d = 0; d < cpt.nbrDim(); ++d) {
1335 std::string name = cpt.variable(d).name();
1336 e.dimNode.push_back(_determineNode_(name));
1337 e.dimName.push_back(std::move(name));
1338 }
1339 return e;
1340 };
1341
1342 // one evaluator per (temporal base, slice), indexed by slice in 0..k-1: the
1343 // node scored at absolute time t uses slice min(t, k-1) (see childSlice below)
1344 const auto& temporalBases = net.temporalVarNames();
1345 std::vector< std::vector< NodeEval > > temporalEvals(k);
1346 for (int slice = 0; slice < k; ++slice) {
1347 temporalEvals[slice].reserve(temporalBases.size());
1348 for (const auto& base: temporalBases)
1349 temporalEvals[slice].push_back(makeEval(net.cpt(base, slice)));
1350 }
1351
1352 // one evaluator per atemporal node (scored once per trajectory)
1353 std::vector< NodeEval > atemporalEvals;
1354 atemporalEvals.reserve(net.atemporalVarNames().size());
1355 for (const auto& base: net.atemporalVarNames())
1356 atemporalEvals.push_back(makeEval(net.cpt(base, KTBN< GUM_SCALAR >::ATEMPORAL)));
1357
1358 // one circular buffer of k rows, reused across trajectories: the row for
1359 // absolute time t lives at slot (t % k), so the k live rows never move —
1360 // reading a new row overwrites the stalest slot (which held time t-k).
1361 std::vector< std::vector< std::string > > window(k);
1362
1363 // missing-value markers, as a set for O(1) tests in the inner loop
1364 const std::unordered_set< std::string > missing(_missingSymbols_.begin(),
1365 _missingSymbols_.end());
1366
1367 for (Size s = 0; s < _nbSamples_; ++s) {
1368 const fs::path file = fs::path{_dirPath_} / (_csvBaseName_ + std::to_string(s + 1) + ".csv");
1369
1370 // ---- pre-pass: column index, and the atemporal values of this trajectory ----
1371 // An atemporal variable is constant down the file, but the row that
1372 // happens to carry a missing marker teaches nothing, so its value is the
1373 // first *informative* one rather than row 0's. The scan stops as soon as
1374 // every atemporal column is resolved (row 0 in the usual case), so it
1375 // costs one row unless the data actually has holes. It cannot be folded
1376 // into the main pass: a value resolved at row 12 must already be known
1377 // when row 0 is scored, and buffering the rows instead would defeat the
1378 // width-k window that bounds this function's memory.
1379 std::unordered_map< std::string, std::size_t > colOf;
1380 std::unordered_map< std::string, std::string > atempVal;
1381 {
1382 std::ifstream pis(file, std::ifstream::in);
1383 if (!pis.is_open()) GUM_ERROR(IOError, "Cannot open " << file.string())
1384 CSVParser pre(pis, file.string());
1385 if (!pre.next()) GUM_ERROR(IOError, "empty trajectory file '" << file.string() << "'") {
1386 const auto& header = pre.current();
1387 for (std::size_t c = 0; c < header.size(); ++c)
1388 colOf[header[c]] = c;
1389 }
1390 const std::size_t nbAtemp = net.atemporalVarNames().size();
1391 while (atempVal.size() < nbAtemp && pre.next()) {
1392 const auto& row = pre.current();
1393 for (const auto& c: net.atemporalVarNames()) {
1394 if (atempVal.contains(c)) continue;
1395 const std::string& tok = row[colOf.at(c)];
1396 if (!missing.contains(tok)) atempVal[c] = tok;
1397 }
1398 }
1399 }
1400
1401 std::ifstream is(file, std::ifstream::in);
1402 if (!is.is_open()) GUM_ERROR(IOError, "Cannot open " << file.string())
1403 CSVParser parser(is, file.string());
1404 parser.next(); // skip the header, already consumed by the pre-pass
1405
1406 // Label observed in the data for one CPT dimension (varBase, varSlice) —
1407 // the scored node itself or one of its parents — while scoring the node
1408 // whose template slice is scoredSlice at absolute time scoredTime.
1409 // Returns nullptr when the value is missing (or, for an atemporal
1410 // variable, never observed in this trajectory); the caller then drops the
1411 // whole instance. A pointer rather than a value: both sources are stable
1412 // strings, and this is the innermost loop of the order selection.
1413 auto labelOf = [&](const std::string& varBase,
1414 int varSlice,
1415 int scoredTime,
1416 int scoredSlice) -> const std::string* {
1417 // atemporal variable: constant down the trajectory, read the captured value
1418 if (varSlice == KTBN< GUM_SCALAR >::ATEMPORAL) {
1419 const auto it = atempVal.find(varBase);
1420 return (it == atempVal.end()) ? nullptr : &it->second;
1421 }
1422 // temporal variable: it lags (scoredSlice - varSlice) steps behind the
1423 // scored node, so its value was observed at that earlier absolute time
1424 const int varTime = scoredTime - (scoredSlice - varSlice);
1425 // fetch that row from the circular buffer (slot = time modulo k)
1426 const std::string& tok = window[varTime % k][colOf.at(varBase)];
1427 return missing.contains(tok) ? nullptr : &tok;
1428 };
1429
1430 int t = 0; // absolute time == data-row index
1431 while (parser.next()) {
1432 const auto& cur = parser.current();
1433 window[t % k].assign(cur.begin(), cur.end());
1434
1435 // first k-1 slices use their own initial CPT; from slice k-1 on the
1436 // transition kernel (template slice k-1) is reused for every step
1437 const int childSlice = (t < k - 1) ? t : (k - 1);
1438 for (NodeEval& e: temporalEvals[childSlice]) {
1439 // an instance counts only if its WHOLE family is observed: the node
1440 // and every parent, each read at its own lag. One missing value drops
1441 // this instance alone — the other nodes of the same row are unaffected.
1442 bool complete = true;
1443 for (std::size_t d = 0; d < e.dimName.size(); ++d) {
1444 const auto& [vbase, vslice] = e.dimNode[d];
1445 const std::string* lbl = labelOf(vbase, vslice, t, childSlice);
1446 if (lbl == nullptr) {
1447 complete = false;
1448 break;
1449 }
1450 e.inst.chgVal(e.dimName[d], *lbl);
1451 }
1452 if (complete) perInstance(e);
1453 }
1454 ++t;
1455 }
1456
1457 // atemporal nodes: scored once per trajectory (parents are atemporal too).
1458 // An atemporal column left unresolved by the pre-pass drops every instance
1459 // that reads it, here and in the temporal loop above — for THIS trajectory
1460 // only, the others still scoring normally.
1461 if (t > 0)
1462 for (NodeEval& e: atemporalEvals) {
1463 bool complete = true;
1464 for (std::size_t d = 0; d < e.dimName.size(); ++d) {
1465 const auto it = atempVal.find(e.dimNode[d].first);
1466 if (it == atempVal.end()) {
1467 complete = false;
1468 break;
1469 }
1470 e.inst.chgVal(e.dimName[d], it->second);
1471 }
1472 if (complete) perInstance(e);
1473 }
1474 }
1475
1476 // per-node closing pass over every evaluator (all slices + atemporal), for
1477 // criteria that reduce the accumulated per-node state after the whole walk
1478 for (auto& slice: temporalEvals)
1479 for (NodeEval& e: slice)
1480 perNodeFinal(e);
1481 for (NodeEval& e: atemporalEvals)
1482 perNodeFinal(e);
1483 }
1484
1485 template < GUM_Numeric GUM_SCALAR >
1486 double KTBNAdaptiveLearner< GUM_SCALAR >::_log2Likelihood_(const KTBN< GUM_SCALAR >& net) const {
1487 // sum log2 of the CPT entry over every visited node instance; no per-node
1488 // closing reduction is needed (the likelihood is fully additive per instance)
1489 double logL = 0.0;
1491 net,
1492 [&logL](auto& e) { logL += std::log2((*e.cpt)[e.inst]); },
1493 [](auto&) {});
1494 return logL;
1495 }
1496
1497 template < GUM_Numeric GUM_SCALAR >
1498 double KTBNAdaptiveLearner< GUM_SCALAR >::_fNMLScore_(const KTBN< GUM_SCALAR >& net) const {
1499 // one data walk: per instance, accumulate log2L AND bucket the observation by
1500 // its parent configuration; per node, close over the buckets with the
1501 // multinomial parametric complexity log2Cnr, exactly the per-node regret term
1502 // aGrUM's ScorefNML subtracts. Fused (rather than a separate _log2Likelihood_
1503 // call plus a separate penalty pass) so fNML order-selection reads every
1504 // trajectory once per candidate k, not twice.
1505 double logL = 0.0, penalty = 0.0;
1507 net,
1508 [&logL](auto& e) {
1509 logL += std::log2((*e.cpt)[e.inst]);
1510 // linear index over the parent dims (1..nbrDim-1); the node is dim 0
1511 Size idx = 0;
1512 for (Idx d = 1; d < e.cpt->nbrDim(); ++d)
1513 idx = idx * e.cpt->variable(d).domainSize() + e.inst.val(e.cpt->variable(d));
1514 e.counts[idx] += 1.0;
1515 },
1516 [this, &penalty](auto& e) {
1517 for (const auto& [cfg, n]: e.counts)
1518 penalty += _ctable_.log2Cnr(e.selfDom, n);
1519 });
1520 return logL - penalty;
1521 }
1522
1523 template < GUM_Numeric GUM_SCALAR >
1524 double KTBNAdaptiveLearner< GUM_SCALAR >::_countParameters_(const KTBN< GUM_SCALAR >& net) const {
1525 // Free parameters of the template: for each node, (|node| - 1) independent
1526 // entries per joint parent configuration. Summed over every template node
1527 // (initial slices, kernel slice, atemporal nodes), this is the k-TBN's total
1528 // parameter count — it rises with k, which is what the BIC penalty needs.
1529 double df = 0.0;
1530 for (const auto& [base, slice]: net.nodes()) {
1531 double cell = net.variable(base, slice).domainSize() - 1.0;
1532 for (const auto& [pbase, pslice]: net.parents(base, slice))
1533 cell *= net.variable(pbase, pslice).domainSize();
1534 df += cell;
1535 }
1536 return df;
1537 }
1538
1539 template < GUM_Numeric GUM_SCALAR >
1541 double logN) const {
1542 // BIC/AIC share a log2-likelihood term plus a data-free parameter-count
1543 // penalty, so both read the trajectories once via _log2Likelihood_. fNML
1544 // needs the likelihood too, but paired with a data-dependent per-node regret
1545 // over the very same walk, so it is fused into a single _forEachScoredNode_
1546 // pass (_fNMLScore_) instead of calling _log2Likelihood_ a second time.
1547 switch (_orderScore_) {
1548 case OrderScoreType::BIC :
1549 // reward fit, penalise complexity: log2L − ½·df·log2(N)
1550 return _log2Likelihood_(net) - 0.5 * _countParameters_(net) * logN;
1551 case OrderScoreType::AIC :
1552 // lighter, sample-size-independent penalty: log2L − df
1553 return _log2Likelihood_(net) - _countParameters_(net);
1555 // per-node multinomial parametric complexity (regret): log2L − Σ log2Cnr
1556 return _fNMLScore_(net);
1557 }
1558 // every criterion returns above; unreachable while OrderScoreType is exhausted
1559 return _log2Likelihood_(net) - 0.5 * _countParameters_(net) * logN;
1560 }
1561
1562} // namespace gum::learning
Class for fast parsing of CSV file (never more than one line in application memory).
A k-TBN learner that also selects the order k from the data.
Class representing a Bayesian network.
Definition BayesNet.h:99
Exception : input/output problem.
Class for assigning/browsing values to tuples of discrete variables.
Instantiation()
Default constructor: creates an empty tuple.
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
Error: The database contains some missing values.
Exception : operation not allowed.
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
const std::vector< std::string > & current() const
returns the current parsed line
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 (order k + structure + parameters) from trajectory CSVs.
std::string toString() const
Human-readable summary of the recorded configuration (candidate order range, algorithm / score / corr...
KTBNAdaptiveLearner< GUM_SCALAR > & addForbiddenArcAllSlices(std::string_view tailBase, std::string_view headBase) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
bool _induceTypes_
whether numeric columns are retyped (see KTBNLearner); unused (and forced false) when a schema BN is ...
std::set< std::string > _noParentNodes_
root nodes (no parents), as engine names
KTBNAdaptiveLearner< GUM_SCALAR > & allowArcAdditions(bool allow=true) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
std::vector< std::string > _missingSymbols_
symbols in the CSVs to interpret as missing values
std::unordered_set< std::string > _atemporalVars_
base names of the atemporal (static) variables
bool _allowAdditions_
recorded graph-change permissions / indegree cap
void _verifyKernelArc_(std::string_view tailBase, std::string_view headBase, int lag) const
Throw InvalidArgument unless tailBase and headBase are known, temporal base variables (a kernel-relat...
KTBNAdaptiveLearner< GUM_SCALAR > & useOrderScoreBIC()
Select k by BIC (the default): keep the k whose learned model maximises .
std::unique_ptr< BayesNet< GUM_SCALAR > > _prior_bn_
optional variable-schema BN (set by the BN constructor): when present, each per-k KTBNLearner is buil...
Size _bestK_
k selected by the last learnKTBN() call, or 0 as a sentinel while no learning has happened yet....
std::string _dirPath_
directory holding the trajectory CSV files
Size _kMax_
largest order to explore (candidates are kMin..kMax)
KTBNAdaptiveLearner< GUM_SCALAR > & addMandatoryArc(std::string_view tailNode, std::string_view headNode) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
bool _isKnownBase_(std::string_view base) const override
whether base is one of this learner's variables; the base names read at construction,...
KTBNAdaptiveLearner< GUM_SCALAR > & eraseForbiddenArcAllSlices(std::string_view tailBase, std::string_view headBase) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
KTBNAdaptiveLearner< GUM_SCALAR > & useNMLCorrection() override
void _applyConstraints_(KTBNLearner< GUM_SCALAR > &learner, Size k) const
Replay the recorded structural constraints onto learner (built for order k). Engine-name constraints ...
std::vector< std::pair< std::string, std::string > > _bestLatentVariables_
latent-variable arcs (engine-name pairs) reported by the winning candidate's MIIC run,...
IBNLearner::BNLearnerPriorType _prior_
recorded prior and its weight
double _orderSelectionScore_(const KTBN< GUM_SCALAR > &net, double logN) const
The cross-k order-selection score of net under the recorded orderScore criterion, given logN = log2 o...
const std::vector< std::pair< std::string, std::string > > & latentVariables() const
Engine-name (tail, head) pairs of arcs the selected model's MIIC run flagged as hiding a latent varia...
std::set< std::string > _noChildrenNodes_
leaf nodes (no children), as engine names
double _priorWeight_
always written by the useXxxPrior() methods, which read learning.priorWeight when no weight is given
KTBNAdaptiveLearner< GUM_SCALAR > & useGreedyHillClimbing() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
double _fNMLScore_(const KTBN< GUM_SCALAR > &net) const
fNML order score of net over the recorded trajectories: , with the node's domain size and the count...
KTBNAdaptiveLearner< GUM_SCALAR > & eraseForbiddenIntraSliceArc(std::string_view tailBase, std::string_view headBase) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
void _forEachScoredNode_(const KTBN< GUM_SCALAR > &net, PerInstance perInstance, PerNodeFinal perNodeFinal) const
Stream every scored template-node instance of net over the recorded trajectories, driving both the li...
~KTBNAdaptiveLearner()
Constructor — the candidate orders are kMin..kMax.
KTBNAdaptiveLearner< GUM_SCALAR > & eraseMandatoryArc(std::string_view tailNode, std::string_view headNode) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
IBNLearner::AlgoType _algo_
recorded structure-learning algorithm ; it is initialized from the configuration, see IBNLearner::pre...
KTBNAdaptiveLearner< GUM_SCALAR > & addMandatoryKernelArc(std::string_view tailBase, int lag, std::string_view headBase)
Force an arc from tailBase, lag slices before the kernel, to headBase in the kernel....
OrderScoreType _orderScore_
recorded cross-k order-selection criterion (the outer score used by learnKTBN() to pick the best k; i...
Size kMax() const
Largest order explored (the kMax argument of the constructor).
KTBNAdaptiveLearner< GUM_SCALAR > & useLocalSearchWithTabuList(Size tabu_size, Size nb_decrease) override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNAdaptiveLearner< GUM_SCALAR > & allowArcDeletions(bool allow=true) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
KTBNAdaptiveLearner< GUM_SCALAR > & erasePossibleEdge(std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
KTBNAdaptiveLearner(std::string_view dirPath, std::string_view csvBaseName, Size nbSamples, Size kMax, const std::unordered_set< std::string > &atemporalVars, const std::vector< std::string > &missingSymbols={"?"}, bool induceTypes=true)
Constructor — the candidate orders are kMin..kMax.
bool _ignoreMissingSymbols_
whether incomplete rows/instances are dropped (see ignoreMissingSymbols())
KTBNAdaptiveLearner< GUM_SCALAR > & addNoChildrenNode(std::string_view base, int slice) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
KTBNAdaptiveLearner< GUM_SCALAR > & addPossibleEdge(std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
std::set< std::pair< std::string, std::string > > _forbiddenArcsAllSlices_
forbidden all-slices arcs, as (tailBase, headBase) pairs
KTBNAdaptiveLearner< GUM_SCALAR > & addForbiddenIntraSliceArc(std::string_view tailBase, std::string_view headBase) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
std::set< std::pair< std::string, std::string > > _mandatoryArcs_
mandatory arcs, as (tail, head) engine-name pairs
std::set< std::pair< std::string, std::string > > _possibleEdges_
MIIC candidate edges, as (tail, head) engine-name pairs.
const std::vector< std::pair< Size, double > > & scorePerCandidateK() const
Per-candidate cross-k scores from the last learnKTBN() call, as (k, score) pairs for k = kMin....
const std::unordered_set< std::string > & _atemporalVarNames_() const override
atemporal base names for IKTBNLearner's shared encode/_determineNode_; the set recorded at constructi...
IBNLearner::ScoreType _score_
recorded per-k structure score (the inner score, replayed on each candidate)
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreBDeu() override
std::set< std::pair< std::string, std::string > > _forbiddenArcs_
forbidden arcs, as (tail, head) engine-name pairs
std::set< std::pair< std::string, std::string > > _forbiddenIntraSliceArcs_
forbidden intra-slice arcs, as (tailBase, headBase) pairs
KTBNAdaptiveLearner< GUM_SCALAR > & addForbiddenArc(std::string_view tailNode, std::string_view headNode) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
Size bestK() const
Order k selected by the last learnKTBN() call.
bool isIgnoringMissingSymbols() const
Whether incomplete rows and instances are dropped. False by default.
Size _nbSamples_
number of CSV files to read
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreMDL() override
double _log2Likelihood_(const KTBN< GUM_SCALAR > &net) const
Factorized log2-likelihood of net over the recorded trajectories, comparable across candidate k (the ...
KTBNAdaptiveLearner< GUM_SCALAR > & eraseForbiddenKernelArc(std::string_view tailBase, int lag, std::string_view headBase)
Undo a previous addForbiddenKernelArc (same (tailBase, lag, headBase) triple).
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreAIC() override
void _applyConfig_(KTBNLearner< GUM_SCALAR > &learner) const
Apply the recorded score / algorithm / correction / prior onto a freshly-built learner....
KTBNAdaptiveLearner< GUM_SCALAR > & eraseMandatoryKernelArc(std::string_view tailBase, int lag, std::string_view headBase)
Undo a previous addMandatoryKernelArc (same (tailBase, lag, headBase) triple).
KTBNAdaptiveLearner< GUM_SCALAR > & useGreedyThickThinning() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNAdaptiveLearner< GUM_SCALAR > & useExtendedGreedyHillClimbing() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
Size _kMin_
smallest order worth exploring (candidates are kMin..kMax). Starts at 2 and is recomputed by recomput...
std::set< std::tuple< std::string, std::string, int > > _mandatoryKernelArcs_
mandatory kernel-relative arcs, same shape as forbiddenKernelArcs
log_2 where the penalty replaces BIC s KTBNAdaptiveLearner< GUM_SCALAR > & useOrderScorefNML()
by a sum of per-node, per-parent-configuration multinomial parametric complexities (regret) – data-de...
KTBNAdaptiveLearner< GUM_SCALAR > & eraseForbiddenArc(std::string_view tailNode, std::string_view headNode) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
KTBNAdaptiveLearner< GUM_SCALAR > & useSmoothingPrior(double weight) override
the default weight (key priorWeight of the section learning)
void _recomputeKMin_()
Recompute kMin from scratch: max(2, 1 + the largest concrete slice named by any recorded forbidden/ma...
KTBNAdaptiveLearner< GUM_SCALAR > & useMDLCorrection() override
std::vector< std::pair< Size, double > > _scorePerCandidateK_
per-candidate (k, order-score) pairs from the last learnKTBN() run, in ascending k....
VariableLog2ParamComplexity _ctable_
cache of log2 of the multinomial parametric complexity C^r_n, used by the fNML order penalty....
KTBNAdaptiveLearner< GUM_SCALAR > & useSmoothingPrior()
the default weight (key priorWeight of the section learning)
double _countParameters_(const KTBN< GUM_SCALAR > &net) const
Number of free parameters of net's template: summed over every template node (all initial slices,...
KTBNAdaptiveLearner< GUM_SCALAR > & allowArcReversals(bool allow=true) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
std::vector< std::tuple< std::string, std::string, std::string > > state() const
The recorded configuration as (key, value, comment) tuples (mirrors KTBNLearner::state()); toString()...
KTBNAdaptiveLearner< GUM_SCALAR > & useLocalSearchWithTabuList()
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNAdaptiveLearner< GUM_SCALAR > & usePC() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBN< GUM_SCALAR > learnKTBN() override
Learns the best k in [kMin, kMax] together with the structure and the CPTs: one KTBNLearner is built ...
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreLog2Likelihood() override
std::unordered_set< std::string > _baseNames_
all base variable names (temporal + atemporal), read from the first trajectory CSV header at construc...
KTBNAdaptiveLearner< GUM_SCALAR > & eraseNoParentNode(std::string_view base, int slice) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
KTBNAdaptiveLearner< GUM_SCALAR > & ignoreMissingSymbols(bool ignore=true)
Learn and score on the fully observed data only, dropping every row and every scoring instance that c...
void _raiseKMinForSlice_(int slice)
Raise kMin, if needed, so that kMin > slice: a smaller candidate would silently drop a constraint nam...
KTBNAdaptiveLearner< GUM_SCALAR > & useOrderScoreAIC()
Select k by AIC: keep the k whose learned model maximises (a lighter, sample-size-independent comple...
void _verifyBase_(std::string_view base, int slice) const
Throw InvalidArgument unless base is a known base variable and slice is valid for it: base must be in...
std::string _csvBaseName_
stem of each trajectory file name
Size _tabuSize_
tabu-list parameters (meaningful when the algorithm is LOCAL_SEARCH_WITH_TABU_LIST)....
static std::unordered_set< std::string > _inferAtemporalVars_(std::string_view dirPath, std::string_view csvBaseName, Size nbSamples, Size kMax, const std::vector< std::string > &missingSymbols)
checks kMax >= 2 and nbSamples >= 1, then delegates to the shared IKTBNLearner::scanConstantColumns()...
KTBNAdaptiveLearner< GUM_SCALAR > & setMaxIndegree(Size max_indegree) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreBD() override
KTBNAdaptiveLearner< GUM_SCALAR > & addNoParentNode(std::string_view base, int slice) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreBIC() override
CorrectedMutualInformation::KModeTypes _correction_
recorded MIIC correction
KTBNAdaptiveLearner< GUM_SCALAR > & addForbiddenKernelArc(std::string_view tailBase, int lag, std::string_view headBase)
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
KTBNAdaptiveLearner< GUM_SCALAR > & useNoCorrection() override
KTBNAdaptiveLearner< GUM_SCALAR > & useMIIC() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNAdaptiveLearner< GUM_SCALAR > & eraseNoChildrenNode(std::string_view base, int slice) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
std::set< std::tuple< std::string, std::string, int > > _forbiddenKernelArcs_
forbidden kernel-relative arcs, as (tailBase, headBase, lag) triples: tailBase at slice k-1-lag -> he...
KTBNAdaptiveLearner< GUM_SCALAR > & useFCI() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
std::string checkScorePriorCompatibility() const
Warning string if the recorded score and prior are incompatible, empty otherwise. Data-free: it evalu...
Learns a k-TBN (structure and/or parameters) from trajectory CSVs.
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)
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").
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)
KTBNLearner< GUM_SCALAR > & useScoreLog2Likelihood() override
Returns a warning string if the current score and prior are incompatible, empty string otherwise.
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...
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).
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)
KTBNLearner< GUM_SCALAR > & useNoCorrection() override
Engine-name pairs (tail, head) of arcs flagged as hiding a latent variable by MIIC (merged from all i...
KTBNLearner< GUM_SCALAR > & allowArcAdditions(bool allow=true) override
Allow or forbid arc additions during structure search.
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.
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 > & 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").
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).
KTBNLearner< GUM_SCALAR > & useLocalSearchWithTabuList(Size tabu_size, Size nb_decrease) override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNLearner< GUM_SCALAR > & addNoParentNode(std::string_view base, int slice) override
Declare a single (base, slice) node as a root (no parents).
KTBNLearner< GUM_SCALAR > & useFCI() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
std::string isPriorCompatible() const final
indicates whether the prior is compatible (meaningful) with the score
std::string isPriorCompatible() const final
indicates whether the prior is compatible (meaningful) with the score
std::string isPriorCompatible() const final
indicates whether the prior is compatible (meaningful) with the score
std::string isPriorCompatible() const final
indicates whether the prior is compatible (meaningful) with the score
std::string isPriorCompatible() const final
indicates whether the prior is compatible (meaningful) with the score
std::string isPriorCompatible() const final
indicates whether the prior is compatible (meaningful) with the score
Typed, documented, sectioned configuration singleton read from an .ini content.
#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 Idx
Type for indexes.
Definition types.h:79
Size NodeId
Type for node ids.
Header files of gum::Instantiation.
include the inlined functions if necessary
Definition CSVParser.h:55
STL namespace.
the base class for all a priori
the class for computing AIC scores
the class for computing Bayesian Dirichlet (BD) log2 scores
the class for computing BDeu scores
the class for computing BIC scores
the class for computing Log2-likelihood scores
the class for computing MDL scores
the class for computing fNML scores