aGrUM 3.3.2
a C++ library for (probabilistic) graphical models
gum::learning::KTBNAdaptiveLearner< GUM_SCALAR > Class Template Reference

Learns a k-TBN (order k + structure + parameters) from trajectory CSVs. More...

#include <agrum/KTBN/learning/KTBNAdaptiveLearner.h>

Inheritance diagram for gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >:
[legend]
Collaboration diagram for gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >:
[legend]

Public Member Functions

Constructors / Destructors
 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.
 KTBNAdaptiveLearner (std::string_view dirPath, std::string_view csvBaseName, Size nbSamples, Size kMax, const std::vector< std::string > &missingSymbols={"?"}, bool induceTypes=true)
 Structure-learning constructor — atemporal variables inferred from the CSVs.
 KTBNAdaptiveLearner (std::string_view dirPath, std::string_view csvBaseName, Size nbSamples, Size kMax, const BayesNet< GUM_SCALAR > &bn, const std::unordered_set< std::string > &atemporalVars={}, const std::vector< std::string > &missingSymbols={"?"})
 Variable-schema constructor — types and domains supplied via a BN.
 ~KTBNAdaptiveLearner ()
 Constructor — the candidate orders are kMin..kMax.
Main learning methods
KTBN< GUM_SCALAR > learnKTBN () override
 Learns the best k in [kMin, kMax] together with the structure and the CPTs: one KTBNLearner is built and run per candidate k, the recorded configuration is replayed on each, and the k-TBN with the best model-selection score is returned. kMin starts at 2 and is raised by the structural-constraint setters (see class doc).
Size bestK () const
 Order k selected by the last learnKTBN() call.
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..kMax in ascending k order — the values the order selection compared to choose bestK() (higher is better; the argmax is bestK()). Under the default useOrderScoreBIC() each score is \(\log_2 L - \tfrac{1}{2}\,d\,\log_2 N\) of the k-TBN learned for that k.
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 variable. Empty when the recorded algorithm is not MIIC (only MIIC produces latent-variable annotations) or when none were found.
Missing values
KTBNAdaptiveLearner< GUM_SCALAR > & ignoreMissingSymbols (bool ignore=true)
 Learn and score on the fully observed data only, dropping every row and every scoring instance that carries a missing symbol.
bool isIgnoringMissingSymbols () const
 Whether incomplete rows and instances are dropped. False by default.
Diagnostics
Size kMax () const
 Largest order explored (the kMax argument of the constructor).
std::string checkScorePriorCompatibility () const
 Warning string if the recorded score and prior are incompatible, empty otherwise. Data-free: it evaluates the recorded (score, prior) pair exactly as KTBNLearner/BNLearner would, so an incompatible combination can be caught before learnKTBN() reads any trajectory.
std::string toString () const
 Human-readable summary of the recorded configuration (candidate order range, algorithm / score / correction / prior, structural constraints) plus the selected k once learnKTBN() has run.
std::vector< std::tuple< std::string, std::string, std::string > > state () const
 The recorded configuration as (key, value, comment) tuples (mirrors KTBNLearner::state()); toString() is a formatted view of it.
Score selection (recorded, replayed on each candidate k)
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreAIC () override
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreBD () override
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreBDeu () override
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreBIC () override
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreLog2Likelihood () override
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreMDL () override
void useScorefNML () override
Algorithm selection (recorded, replayed on each candidate k)
KTBNAdaptiveLearner< GUM_SCALAR > & useGreedyHillClimbing () 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)
KTBNAdaptiveLearner< GUM_SCALAR > & useLocalSearchWithTabuList (Size tabu_size, Size nb_decrease) override
 the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNAdaptiveLearner< GUM_SCALAR > & useLocalSearchWithTabuList ()
 the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNAdaptiveLearner< GUM_SCALAR > & useLocalSearchWithTabuList (Size tabu_size)
 the default number of decreasing changes (key tabuNbDecrease)
KTBNAdaptiveLearner< GUM_SCALAR > & useMIIC () override
 the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNAdaptiveLearner< GUM_SCALAR > & useGreedyThickThinning () override
 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)
KTBNAdaptiveLearner< GUM_SCALAR > & useFCI () override
 the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
MIIC correction (recorded, replayed on each candidate k)
KTBNAdaptiveLearner< GUM_SCALAR > & useNMLCorrection () override
KTBNAdaptiveLearner< GUM_SCALAR > & useMDLCorrection () override
KTBNAdaptiveLearner< GUM_SCALAR > & useNoCorrection () override
Prior selection (recorded, replayed on each candidate k)
KTBNAdaptiveLearner< GUM_SCALAR > & useSmoothingPrior (double weight) override
 the default weight (key priorWeight of the section learning)
KTBNAdaptiveLearner< GUM_SCALAR > & useSmoothingPrior ()
 the default weight (key priorWeight of the section learning)
Structural constraints (recorded, replayed on each candidate k)
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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
KTBNAdaptiveLearner< GUM_SCALAR > & addForbiddenArc (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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
KTBNAdaptiveLearner< GUM_SCALAR > & eraseForbiddenArc (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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
KTBNAdaptiveLearner< GUM_SCALAR > & addMandatoryArc (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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
KTBNAdaptiveLearner< GUM_SCALAR > & eraseMandatoryArc (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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
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 > & 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. See addForbiddenKernelArc for the (base, slice) vs. kernel-relative distinction; the validity constraints (lag range, temporal bases, kMin effect) are the same. Always temporally feasible by construction (lag >= 0 guarantees headSlice = k-1 >= k-1-lag = tailSlice), so unlike the plain addMandatoryArc there is no separate feasibility check to run.
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 > & 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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
KTBNAdaptiveLearner< GUM_SCALAR > & addNoParentNode (std::string_view name) override
 Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
KTBNAdaptiveLearner< GUM_SCALAR > & eraseNoParentNode (std::string_view name) override
 Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
KTBNAdaptiveLearner< GUM_SCALAR > & addNoChildrenNode (std::string_view name) override
 Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
KTBNAdaptiveLearner< GUM_SCALAR > & eraseNoChildrenNode (std::string_view name) override
 Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
KTBNAdaptiveLearner< GUM_SCALAR > & addPossibleEdge (std::string_view tail, std::string_view head) override
 Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
KTBNAdaptiveLearner< GUM_SCALAR > & erasePossibleEdge (std::string_view tail, std::string_view head) override
 Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.
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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Static Protected Member Functions

Default parameters (keys of the section <tt>learning</tt> of gum::Configuration)
static Size defaultTabuListSize_ ()
static Size defaultTabuNbDecrease_ ()
static double defaultPriorWeight_ ()

Private Member Functions

const std::unordered_set< std::string > & _atemporalVarNames_ () const override
 atemporal base names for IKTBNLearner's shared encode/_determineNode_; the set recorded at construction.
bool _isKnownBase_ (std::string_view base) const override
 whether base is one of this learner's variables; the base names read at construction, from the CSV header or the schema BN.
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 baseNames; an atemporal base requires slice == KTBN::ATEMPORAL, a temporal one requires slice in [0, kMax). Used by the constraint setters to reject unknown names / out-of-range slices eagerly.
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-relative arc has no meaning for an atemporal one: it has no kernel-slice instance) and lag is in [0, kMax) — so some candidate k in [2,kMax] can place tailBase at slice k-1-lag >= 0 and headBase at the kernel slice k-1. Used by the four kernel-arc setters (add/eraseForbiddenKernelArc, add/eraseMandatoryKernelArc) to reject bad calls eagerly.
void _raiseKMinForSlice_ (int slice)
 Raise kMin, if needed, so that kMin > slice: a smaller candidate would silently drop a constraint naming that slice (the "slice < k" rule applyConstraints's fits() filter uses). O(1), since adding a constraint can only push kMin up. No-op for KTBN::ATEMPORAL.
void _recomputeKMin_ ()
 Recompute kMin from scratch: max(2, 1 + the largest concrete slice named by any recorded forbidden/mandatory arc, possible edge, or no-parent/no-children node (the kinds fits() can drop). Intra-slice / all-slices constraints carry no slice and are excluded. Unlike raiseKMinForSlice, an erase can lower kMin with no O(1) way to tell, so every erase* setter runs this full rescan instead.
void _applyConfig_ (KTBNLearner< GUM_SCALAR > &learner) const
 Apply the recorded score / algorithm / correction / prior onto a freshly-built learner. Only knobs that differ from their default are touched, and only those the chosen algorithm actually consumes (a score-based algo takes a score; MIIC takes a correction) — so an unconfigured learner is left at its defaults and no irrelevant setting can trip checkScorePriorCompatibility().
void _applyConstraints_ (KTBNLearner< GUM_SCALAR > &learner, Size k) const
 Replay the recorded structural constraints onto learner (built for order k). Engine-name constraints whose slice does not fit k (slice >= k) are skipped for this candidate; the base-only intra-slice / all-slices constraints are handed to learner, which expands them for its own k. The allow-* flags and max-indegree are applied when non-default.
template<typename PerInstance, typename PerNodeFinal>
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 likelihood and the fNML penalty off one data walk, so the width-k window logic lives in one place.
double _log2Likelihood_ (const KTBN< GUM_SCALAR > &net) const
 Factorized log2-likelihood of net over the recorded trajectories, comparable across candidate k (the raw score types are not: their flattened tables differ from one k to another). The data is complete, so this is a closed-form sum of CPT lookups — no inference. A thin reduction over forEachScoredNode that sums log2 of the CPT entry over every visited node instance.
double _countParameters_ (const KTBN< GUM_SCALAR > &net) const
 Number of free parameters of net's template: summed over every template node (all initial slices, the kernel slice and the atemporal nodes), \((|X|-1)\prod_{P\in pa(X)}|P|\). This is the model-complexity term of the cross-k BIC and AIC scores used by learnKTBN(): it grows with \(k\) (a higher order adds initial-slice CPTs and can widen the kernel), which is what offsets the monotonic likelihood gain and prevents always picking the largest \(k\).
double _fNMLScore_ (const KTBN< GUM_SCALAR > &net) const
 fNML order score of net over the recorded trajectories: \(\log_2 L - \sum_i \sum_j \log_2 C^{r_i}_{N_{ij}}\), with \(r_i\) the node's domain size and \(N_{ij}\) the count for parent configuration \(j\). Unlike BIC/AIC the penalty is data-dependent, so the regret needs the same per-instance walk as the likelihood — both are accumulated in one forEachScoredNode pass. Mirrors aGrUM's ScorefNML.
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 of the sample size. The single dispatch point learnKTBN() uses to compare candidates; add a branch here for each new OrderScoreType.
 KTBNAdaptiveLearner (const KTBNAdaptiveLearner< GUM_SCALAR > &)=delete
 KTBNAdaptiveLearner (KTBNAdaptiveLearner< GUM_SCALAR > &&)=delete
KTBNAdaptiveLearner< GUM_SCALAR > & operator= (const KTBNAdaptiveLearner< GUM_SCALAR > &)=delete
KTBNAdaptiveLearner< GUM_SCALAR > & operator= (KTBNAdaptiveLearner< GUM_SCALAR > &&)=delete

Static Private Member Functions

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(). Called from the atemporal-inferring constructor's member-initialiser list, before this object exists, so the checks live here rather than in the body — otherwise a bad argument would only surface after a wasted scan.

Private Attributes

std::string _dirPath_
 directory holding the trajectory CSV files
std::string _csvBaseName_
 stem of each trajectory file name
Size _nbSamples_
 number of CSV files to read
Size _kMax_
 largest order to explore (candidates are kMin..kMax)
Size _kMin_ {2}
 smallest order worth exploring (candidates are kMin..kMax). Starts at 2 and is recomputed by recomputeKMin() from the recorded slice-bearing constraints every time one is added or erased; never set directly. See recomputeKMin() for why it must be a recompute rather than an incremental raise/lower.
std::unordered_set< std::string > _atemporalVars_
 base names of the atemporal (static) variables
std::unordered_set< std::string > _baseNames_
 all base variable names (temporal + atemporal), read from the first trajectory CSV header at construction. Authoritative universe used by the constraint setters to reject names that do not exist.
std::vector< std::string > _missingSymbols_
 symbols in the CSVs to interpret as missing values
bool _ignoreMissingSymbols_ {false}
 whether incomplete rows/instances are dropped (see ignoreMissingSymbols())
bool _induceTypes_
 whether numeric columns are retyped (see KTBNLearner); unused (and forced false) when a schema BN is supplied
std::unique_ptr< BayesNet< GUM_SCALAR > > _prior_bn_
 optional variable-schema BN (set by the BN constructor): when present, each per-k KTBNLearner is built from it so the variable domains are fixed explicitly instead of inferred from trajectory 1. Null in CSV mode.
IBNLearner::ScoreType _score_ {IBNLearner::ScoreType::BDeu}
 recorded per-k structure score (the inner score, replayed on each candidate)
OrderScoreType _orderScore_ {OrderScoreType::BIC}
 recorded cross-k order-selection criterion (the outer score used by learnKTBN() to pick the best k; independent of score)
IBNLearner::AlgoType _algo_ {IBNLearner::preferredAlgo()}
 recorded structure-learning algorithm ; it is initialized from the configuration, see IBNLearner::preferredAlgo()
Size _tabuSize_ {100}
 tabu-list parameters (meaningful when the algorithm is LOCAL_SEARCH_WITH_TABU_LIST). They are always written by useLocalSearchWithTabuList(), which reads learning.tabuListSize and learning.tabuNbDecrease when no value is given.
Size _nbDecrease_ {2}
CorrectedMutualInformation::KModeTypes _correction_
 recorded MIIC correction
IBNLearner::BNLearnerPriorType _prior_ {IBNLearner::BNLearnerPriorType::NO_prior}
 recorded prior and its weight
double _priorWeight_ {1.0}
 always written by the useXxxPrior() methods, which read learning.priorWeight when no weight is given
bool _allowAdditions_ {true}
 recorded graph-change permissions / indegree cap
bool _allowDeletions_ {true}
bool _allowReversals_ {true}
Size _maxIndegree_ {std::numeric_limits< Size >::max()}
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 > > _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.
std::set< std::pair< std::string, std::string > > _forbiddenIntraSliceArcs_
 forbidden intra-slice arcs, as (tailBase, headBase) pairs
std::set< std::pair< std::string, std::string > > _forbiddenArcsAllSlices_
 forbidden all-slices arcs, as (tailBase, headBase) pairs
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 -> headBase at the kernel slice k-1. Kept separate from forbiddenArcs (which stores resolved engine names) since the slice here is only known once a candidate k is fixed.
std::set< std::tuple< std::string, std::string, int > > _mandatoryKernelArcs_
 mandatory kernel-relative arcs, same shape as forbiddenKernelArcs
std::set< std::string > _noParentNodes_
 root nodes (no parents), as engine names
std::set< std::string > _noChildrenNodes_
 leaf nodes (no children), as engine names
Size _bestK_ {0}
 k selected by the last learnKTBN() call, or 0 as a sentinel while no learning has happened yet. 0 can never be a valid order (candidates are 2..kMax), so bestK() reads it to decide whether learnKTBN() has run.
std::vector< std::pair< std::string, std::string > > _bestLatentVariables_
 latent-variable arcs (engine-name pairs) reported by the winning candidate's MIIC run, captured by learnKTBN(); empty when the selected algorithm is not MIIC. Exposed by latentVariables().
std::vector< std::pair< Size, double > > _scorePerCandidateK_
 per-candidate (k, order-score) pairs from the last learnKTBN() run, in ascending k. One entry appended per candidate; read by scorePerCandidateK(). Cleared at the start of each learnKTBN() (empty while bestK == 0).
VariableLog2ParamComplexity _ctable_
 cache of log2 of the multinomial parametric complexity C^r_n, used by the fNML order penalty. Mutable because log2Cnr() memoizes; the const order-score helpers may therefore call it. Only touched under fNML.

Order selection (cross-k model selection)

enum class  OrderScoreType { BIC , AIC , fNML }
 The criterion learnKTBN() uses to pick the best \(k\) among the candidates — the outer score, distinct from the per-k structure score set by useScoreX(). Only criteria that are comparable across \(k\) belong here (raw score types are not). Extended as more are added. More...
log_2 C {r_i}_{N_{ij}}@f$
 Select k by fNML (factorized Normalized Maximum Likelihood): keep the k whose learned model maximises .
KTBNAdaptiveLearner< GUM_SCALAR > & useOrderScoreBIC ()
 Select k by BIC (the default): keep the k whose learned model maximises \(\log_2 L - \tfrac{1}{2}\,d\,\log_2 N\).
KTBNAdaptiveLearner< GUM_SCALAR > & useOrderScoreAIC ()
 Select k by AIC: keep the k whose learned model maximises \(\log_2 L - d\) (a lighter, sample-size-independent complexity penalty than BIC).
log_2 where the penalty replaces BIC s KTBNAdaptiveLearner< GUM_SCALAR > & useOrderScorefNML ()
 \(\tfrac{1}{2}\,d\,\log_2 N\) by a sum of per-node, per-parent-configuration multinomial parametric complexities (regret) – data-dependent, unlike BIC/AIC, matching aGrUM's ScorefNML.

Name encoding: (base, slice) <-> engine name

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 fixed-k learner, "kMax" for the adaptive one).
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 changes across the rows of a single trajectory (checked independently per trajectory, so the value may still differ between trajectories). Shared by every atemporal-inferring CSV constructor (KTBNLearner, KTBNAdaptiveLearner): identical scanning logic regardless of which subclass calls it, so duplicating it per subclass would only invite the two copies to drift. Callers are responsible for validating their own arguments (e.g. k/kMax >= 2) before calling this — it does no such check itself, only opens files, so a bad argument would otherwise only be caught after a wasted scan.
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 the atemporal test varies (via atemporalVarNames()).
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 fail early (before any internal learner is touched) with a uniform message. action is the verb phrase completing "cannot <action> <tail> -> <head>: ..." (e.g. "force the mandatory arc", "un-forbid the arc"). Two arcs are refused: a temporal -> atemporal arc (a time-varying variable can never parent a static one) and a backward-in-time arc (head strictly before tail).
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 <context>" (e.g. "an intra-slice constraint", "a kernel-relative arc"): every caller rejects an atemporal base for the same underlying reason – it has no per-slice instance – so they share the sentence and vary the setting.

Detailed Description

template<GUM_Numeric GUM_SCALAR>
class gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >

Learns a k-TBN (order k + structure + parameters) from trajectory CSVs.

See also
gum::learning::IKTBNLearner for the configuration interface, gum::learning::KTBNLearner for the fixed-k learner this class builds and drives once per candidate k.

Definition at line 103 of file KTBNAdaptiveLearner.h.

Member Enumeration Documentation

◆ OrderScoreType

template<GUM_Numeric GUM_SCALAR>
enum class gum::learning::KTBNAdaptiveLearner::OrderScoreType
strong

The criterion learnKTBN() uses to pick the best \(k\) among the candidates — the outer score, distinct from the per-k structure score set by useScoreX(). Only criteria that are comparable across \(k\) belong here (raw score types are not). Extended as more are added.

Enumerator
BIC 
AIC 
fNML 

Definition at line 265 of file KTBNAdaptiveLearner.h.

265{ BIC, AIC, fNML };

Constructor & Destructor Documentation

◆ KTBNAdaptiveLearner() [1/5]

template<GUM_Numeric GUM_SCALAR>
gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::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.

Mirrors the CSV constructor of gum::learning::KTBNLearner, except that no single order k is given: the learner explores every \(k \in [k_{min}, kMax]\) at learn time. \(k_{min}\) starts at 2 (k = 1 is a static BN; use BNLearner) and is raised by the structural-constraint setters — see the class doc.

Parameters
dirPathDirectory holding the trajectory CSV files.
csvBaseNameStem of each file name (1-based index and .csv appended, e.g. "traj" -> "traj1.csv", "traj2.csv", ...).
nbSamplesNumber of CSV files to read.
kMaxLargest order to explore. Must be \(\geq 2\).
atemporalVarsBase names of the atemporal (static) variables. Pass an empty set for "every variable is temporal"; it has no default, since omitting it selects the inferring overload below.
missingSymbolsSymbols in the CSVs to interpret as missing values.
induceTypesWhen true (default), columns whose values are all numeric are retyped (integer/range/continuous) instead of being treated as plain labels — same semantics as KTBNLearner.
Warning
A braced literal is ambiguous between this overload and the inferring one, since it could equally initialize either's fifth parameter. Name the type — std::unordered_set<std::string>{"C","D"} — or pass a named variable.

Definition at line 79 of file KTBNAdaptiveLearner_tpl.h.

86 :
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.
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();
108
109 // every declared atemporal variable must actually be one of those columns
110 for (const std::string& aname: _atemporalVars_)
113 "atemporal variable '" << aname << "' not found in the CSV header")
114
116 }
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...
Learns a k-TBN (order k + structure + parameters) from trajectory CSVs.
bool _induceTypes_
whether numeric columns are retyped (see KTBNLearner); unused (and forced false) when a schema BN is ...
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
std::string _dirPath_
directory holding the trajectory CSV files
Size _kMax_
largest order to explore (candidates are kMin..kMax)
Size kMax() const
Largest order explored (the kMax argument of the constructor).
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.
Size _nbSamples_
number of CSV files to read
std::unordered_set< std::string > _baseNames_
all base variable names (temporal + atemporal), read from the first trajectory CSV header at construc...
std::string _csvBaseName_
stem of each trajectory file name

References KTBNAdaptiveLearner(), _atemporalVars_, _baseNames_, gum::learning::IKTBNLearner< GUM_SCALAR >::_checkMinimalOrder_(), _csvBaseName_, _dirPath_, _induceTypes_, _kMax_, _missingSymbols_, _nbSamples_, gum::learning::CSVParser::current(), GUM_ERROR, kMax(), and gum::learning::CSVParser::next().

Referenced by KTBNAdaptiveLearner(), KTBNAdaptiveLearner(), KTBNAdaptiveLearner(), KTBNAdaptiveLearner(), KTBNAdaptiveLearner(), ~KTBNAdaptiveLearner(), operator=(), operator=(), useFCI(), useGreedyHillClimbing(), useGreedyThickThinning(), useMDLCorrection(), useMIIC(), useNMLCorrection(), useNoCorrection(), useOrderScoreAIC(), useOrderScoreBIC(), useOrderScorefNML(), usePC(), useScoreAIC(), useScoreBD(), useScoreBDeu(), useScoreBIC(), useScoreLog2Likelihood(), useScoreMDL(), and useSmoothingPrior().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ KTBNAdaptiveLearner() [2/5]

template<GUM_Numeric GUM_SCALAR>
gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::KTBNAdaptiveLearner ( std::string_view dirPath,
std::string_view csvBaseName,
Size nbSamples,
Size kMax,
const std::vector< std::string > & missingSymbols = {"?"},
bool induceTypes = true )

Structure-learning constructor — atemporal variables inferred from the CSVs.

Same as the explicit-atemporalVars constructor, except a base variable is classified atemporal iff its value never changes within a single trajectory (it may still differ between trajectories, e.g. a per-individual covariate such as age). A column with too few non-missing values to ever witness a change is classified atemporal optimistically.

This is a heuristic: a genuinely temporal variable that happens to hold one value throughout every sampled trajectory (short horizon, near-deterministic process) will be misclassified. Prefer the explicit-atemporalVars constructor when the classification is already known.

Warning
Domains are still discovered from trajectory 1 alone. An inferred atemporal variable, by construction, may vary between trajectories — exactly the case most likely to reveal only one of several modalities in trajectory 1 and later throw UnknownLabelInDatabase at learnKTBN() time. Use the BN-schema constructor if the full domain isn't guaranteed present in trajectory 1.
Unlike every other constructor, this one is not fully lazy: it keeps opening trajectories until every column has been falsified as a constancy candidate, so a missing/malformed file is usually (not always — an early-falsifying column set can stop the scan first) caught here rather than at learnKTBN().
Parameters
dirPathDirectory holding the trajectory CSV files.
csvBaseNameStem of each file name (1-based index and .csv appended, e.g. "traj" -> "traj1.csv", "traj2.csv", ...).
nbSamplesNumber of CSV files to read.
kMaxLargest order to explore. Must be \(\geq 2\).
missingSymbolsSymbols in the CSVs to interpret as missing values.
induceTypesWhen true (default), columns whose values are all numeric are retyped (integer/range/continuous) instead of being treated as plain labels.

Definition at line 119 of file KTBNAdaptiveLearner_tpl.h.

125 :
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,
137 nbSamples,
138 kMax,
141 induceTypes) {}
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()...

References KTBNAdaptiveLearner(), _inferAtemporalVars_(), and kMax().

Here is the call graph for this function:

◆ KTBNAdaptiveLearner() [3/5]

template<GUM_Numeric GUM_SCALAR>
gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::KTBNAdaptiveLearner ( std::string_view dirPath,
std::string_view csvBaseName,
Size nbSamples,
Size kMax,
const BayesNet< GUM_SCALAR > & bn,
const std::unordered_set< std::string > & atemporalVars = {},
const std::vector< std::string > & missingSymbols = {"?"} )

Variable-schema constructor — types and domains supplied via a BN.

The adaptive counterpart of gum::learning::KTBNLearner's BN constructor. Use it when a variable's full domain is not guaranteed to appear in the first trajectory — most notably atemporal variables, which are constant within a trajectory and so only ever reveal one value per file, and the CSV constructor would then infer an incomplete domain and later throw gum::UnknownLabelInDatabase. Each per-k KTBNLearner is built from bn so every variable's type and domain is fixed up front; induceTypes and the trajectory-1 domain inference are bypassed entirely.

Parameters
dirPathDirectory holding the trajectory CSV files.
csvBaseNameStem of each file name (index and .csv appended).
nbSamplesNumber of CSV files to read.
kMaxLargest order to explore. Must be \(\geq 2\).
bnA BayesNet with one node per base variable providing the variable types and domains. Arcs in bn are ignored.
atemporalVarsBase names of the atemporal (static) variables present in bn.
missingSymbolsSymbols in the CSVs to interpret as missing values.

Definition at line 159 of file KTBNAdaptiveLearner_tpl.h.

166 :
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.
179
180 // every declared atemporal variable must be a node of the schema BN
181 for (const std::string& aname: _atemporalVars_)
184 "atemporal variable '" << aname << "' not found in the schema BN")
185
187 }
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...

References KTBNAdaptiveLearner(), _atemporalVars_, _baseNames_, gum::learning::IKTBNLearner< GUM_SCALAR >::_checkMinimalOrder_(), _csvBaseName_, _dirPath_, _induceTypes_, _kMax_, _missingSymbols_, _nbSamples_, _prior_bn_, GUM_ERROR, and kMax().

Here is the call graph for this function:

◆ ~KTBNAdaptiveLearner()

template<GUM_Numeric GUM_SCALAR>
gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::~KTBNAdaptiveLearner ( )

Constructor — the candidate orders are kMin..kMax.

Mirrors the CSV constructor of gum::learning::KTBNLearner, except that no single order k is given: the learner explores every \(k \in [k_{min}, kMax]\) at learn time. \(k_{min}\) starts at 2 (k = 1 is a static BN; use BNLearner) and is raised by the structural-constraint setters — see the class doc.

Parameters
dirPathDirectory holding the trajectory CSV files.
csvBaseNameStem of each file name (1-based index and .csv appended, e.g. "traj" -> "traj1.csv", "traj2.csv", ...).
nbSamplesNumber of CSV files to read.
kMaxLargest order to explore. Must be \(\geq 2\).
atemporalVarsBase names of the atemporal (static) variables. Pass an empty set for "every variable is temporal"; it has no default, since omitting it selects the inferring overload below.
missingSymbolsSymbols in the CSVs to interpret as missing values.
induceTypesWhen true (default), columns whose values are all numeric are retyped (integer/range/continuous) instead of being treated as plain labels — same semantics as KTBNLearner.
Warning
A braced literal is ambiguous between this overload and the inferring one, since it could equally initialize either's fifth parameter. Name the type — std::unordered_set<std::string>{"C","D"} — or pass a named variable.

Definition at line 190 of file KTBNAdaptiveLearner_tpl.h.

References KTBNAdaptiveLearner().

Here is the call graph for this function:

◆ KTBNAdaptiveLearner() [4/5]

template<GUM_Numeric GUM_SCALAR>
gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::KTBNAdaptiveLearner ( const KTBNAdaptiveLearner< GUM_SCALAR > & )
privatedelete

References KTBNAdaptiveLearner().

Here is the call graph for this function:

◆ KTBNAdaptiveLearner() [5/5]

template<GUM_Numeric GUM_SCALAR>
gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::KTBNAdaptiveLearner ( KTBNAdaptiveLearner< GUM_SCALAR > && )
privatedelete

References KTBNAdaptiveLearner().

Here is the call graph for this function:

Member Function Documentation

◆ _applyConfig_()

template<GUM_Numeric GUM_SCALAR>
void gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConfig_ ( KTBNLearner< GUM_SCALAR > & learner) const
private

Apply the recorded score / algorithm / correction / prior onto a freshly-built learner. Only knobs that differ from their default are touched, and only those the chosen algorithm actually consumes (a score-based algo takes a score; MIIC takes a correction) — so an unconfigured learner is left at its defaults and no irrelevant setting can trip checkScorePriorCompatibility().

Definition at line 1198 of file KTBNAdaptiveLearner_tpl.h.

1198 {
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;
1216 scoreBased = true;
1217 break;
1220 scoreBased = true;
1221 break;
1224 scoreBased = true;
1225 break;
1228 scoreBased = true;
1229 break;
1230 case IBNLearner::AlgoType::PC : learner.usePC(); 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
1237 switch (_score_) {
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 }
KTBNAdaptiveLearner< GUM_SCALAR > & useNMLCorrection() override
IBNLearner::BNLearnerPriorType _prior_
recorded prior and its weight
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)
IBNLearner::AlgoType _algo_
recorded structure-learning algorithm ; it is initialized from the configuration, see IBNLearner::pre...
KTBNAdaptiveLearner< GUM_SCALAR > & useLocalSearchWithTabuList(Size tabu_size, Size nb_decrease) override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
IBNLearner::ScoreType _score_
recorded per-k structure score (the inner score, replayed on each candidate)
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreMDL() override
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreAIC() override
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)
KTBNAdaptiveLearner< GUM_SCALAR > & useSmoothingPrior(double weight) override
the default weight (key priorWeight of the section learning)
KTBNAdaptiveLearner< GUM_SCALAR > & usePC() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreLog2Likelihood() override
Size _tabuSize_
tabu-list parameters (meaningful when the algorithm is LOCAL_SEARCH_WITH_TABU_LIST)....
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreBD() override
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreBIC() override
CorrectedMutualInformation::KModeTypes _correction_
recorded MIIC correction
KTBNAdaptiveLearner< GUM_SCALAR > & useNoCorrection() override
KTBNAdaptiveLearner< GUM_SCALAR > & useMIIC() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNAdaptiveLearner< GUM_SCALAR > & useFCI() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)

References _algo_, _correction_, _nbDecrease_, _prior_, _priorWeight_, _score_, _tabuSize_, gum::learning::IBNLearner::AIC, gum::learning::IBNLearner::BD, gum::learning::IBNLearner::BDeu, gum::learning::IBNLearner::BIC, gum::learning::IBNLearner::EXTENDED_GREEDY_HILL_CLIMBING, gum::learning::IBNLearner::FCI, gum::learning::IBNLearner::fNML, gum::learning::IBNLearner::GREEDY_HILL_CLIMBING, gum::learning::IBNLearner::GREEDY_THICK_THINNING, gum::learning::IBNLearner::LOCAL_SEARCH_WITH_TABU_LIST, gum::learning::IBNLearner::LOG2LIKELIHOOD, gum::learning::CorrectedMutualInformation::MDL, gum::learning::IBNLearner::MDL, gum::learning::IBNLearner::MIIC, gum::learning::CorrectedMutualInformation::NML, gum::learning::IBNLearner::NO_prior, gum::learning::CorrectedMutualInformation::NoCorr, gum::learning::IBNLearner::PC, gum::learning::KTBNLearner< GUM_SCALAR >::useExtendedGreedyHillClimbing(), gum::learning::KTBNLearner< GUM_SCALAR >::useFCI(), gum::learning::KTBNLearner< GUM_SCALAR >::useGreedyHillClimbing(), gum::learning::KTBNLearner< GUM_SCALAR >::useGreedyThickThinning(), gum::learning::KTBNLearner< GUM_SCALAR >::useLocalSearchWithTabuList(), gum::learning::KTBNLearner< GUM_SCALAR >::useMIIC(), gum::learning::KTBNLearner< GUM_SCALAR >::useNMLCorrection(), gum::learning::KTBNLearner< GUM_SCALAR >::useNoCorrection(), gum::learning::KTBNLearner< GUM_SCALAR >::usePC(), gum::learning::KTBNLearner< GUM_SCALAR >::useScoreAIC(), gum::learning::KTBNLearner< GUM_SCALAR >::useScoreBD(), gum::learning::KTBNLearner< GUM_SCALAR >::useScoreBIC(), gum::learning::KTBNLearner< GUM_SCALAR >::useScorefNML(), gum::learning::KTBNLearner< GUM_SCALAR >::useScoreLog2Likelihood(), gum::learning::KTBNLearner< GUM_SCALAR >::useScoreMDL(), and gum::learning::KTBNLearner< GUM_SCALAR >::useSmoothingPrior().

Referenced by learnKTBN().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ _applyConstraints_()

template<GUM_Numeric GUM_SCALAR>
void gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConstraints_ ( KTBNLearner< GUM_SCALAR > & learner,
Size k ) const
private

Replay the recorded structural constraints onto learner (built for order k). Engine-name constraints whose slice does not fit k (slice >= k) are skipped for this candidate; the base-only intra-slice / all-slices constraints are handed to learner, which expands them for its own k. The allow-* flags and max-indegree are applied when non-default.

Definition at line 1255 of file KTBNAdaptiveLearner_tpl.h.

1256 {
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_)
1265 for (const auto& [tail, head]: _mandatoryArcs_)
1267 for (const auto& [tail, head]: _possibleEdges_)
1269 for (const auto& node: _noParentNodes_)
1271 for (const auto& node: _noChildrenNodes_)
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;
1281 }
1282 for (const auto& [tailBase, headBase, lag]: _mandatoryKernelArcs_) {
1283 const int tailSlice = ik - 1 - lag;
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_)
1291 for (const auto& [tailBase, headBase]: _forbiddenArcsAllSlices_)
1293
1294 // structural-search knobs, applied only when the user changed them from default
1299 }
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...
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...
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...
bool _allowAdditions_
recorded graph-change permissions / indegree cap
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...
std::set< std::string > _noChildrenNodes_
leaf nodes (no children), as engine names
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 > & 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.
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...
std::set< std::tuple< std::string, std::string, int > > _mandatoryKernelArcs_
mandatory kernel-relative arcs, same shape as forbiddenKernelArcs
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...
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 > & 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...
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...

References _allowAdditions_, _allowDeletions_, _allowReversals_, gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _forbiddenArcs_, _forbiddenArcsAllSlices_, _forbiddenIntraSliceArcs_, _forbiddenKernelArcs_, _mandatoryArcs_, _mandatoryKernelArcs_, _maxIndegree_, _noChildrenNodes_, _noParentNodes_, _possibleEdges_, gum::learning::KTBNLearner< GUM_SCALAR >::addForbiddenArc(), gum::learning::KTBNLearner< GUM_SCALAR >::addForbiddenArcAllSlices(), gum::learning::KTBNLearner< GUM_SCALAR >::addForbiddenIntraSliceArc(), gum::learning::KTBNLearner< GUM_SCALAR >::addMandatoryArc(), gum::learning::KTBNLearner< GUM_SCALAR >::addNoChildrenNode(), gum::learning::KTBNLearner< GUM_SCALAR >::addNoParentNode(), gum::learning::KTBNLearner< GUM_SCALAR >::addPossibleEdge(), gum::learning::KTBNLearner< GUM_SCALAR >::allowArcAdditions(), gum::learning::KTBNLearner< GUM_SCALAR >::allowArcDeletions(), gum::learning::KTBNLearner< GUM_SCALAR >::allowArcReversals(), and gum::learning::KTBNLearner< GUM_SCALAR >::setMaxIndegree().

Referenced by learnKTBN().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ _atemporalVarNames_()

template<GUM_Numeric GUM_SCALAR>
const std::unordered_set< std::string > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_atemporalVarNames_ ( ) const
overrideprivatevirtual

atemporal base names for IKTBNLearner's shared encode/_determineNode_; the set recorded at construction.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 1087 of file KTBNAdaptiveLearner_tpl.h.

1087 {
1088 return _atemporalVars_;
1089 }

References _atemporalVars_.

◆ _checkArcTemporallyFeasible_()

template<GUM_Numeric GUM_SCALAR>
void gum::learning::IKTBNLearner< GUM_SCALAR >::_checkArcTemporallyFeasible_ ( std::string_view tail,
std::string_view head,
std::string_view action ) const
protectedinherited

Reject an arc the k-TBN definition can never contain, so eraseForbiddenArc and addMandatoryArc both fail early (before any internal learner is touched) with a uniform message. action is the verb phrase completing "cannot <action> <tail> -> <head>: ..." (e.g. "force the mandatory arc", "un-forbid the arc"). Two arcs are refused: a temporal -> atemporal arc (a time-varying variable can never parent a static one) and a backward-in-time arc (head strictly before tail).

Definition at line 127 of file IKTBNLearner_tpl.h.

129 {
134 "cannot " << action << " " << tail << " -> " << head
135 << ": a temporal variable can never be a parent of an atemporal one; "
136 "this constraint is part of the k-TBN definition")
139 "cannot " << action << " " << tail << " -> " << head
140 << ": its head is at an earlier time slice than its tail, which "
141 "violates temporal causality")
142 }
Pure-virtual configuration interface shared by all k-TBN learners.

References _determineNode_(), gum::KTBN< GUM_SCALAR >::ATEMPORAL, and GUM_ERROR.

Referenced by _isKnownBase_(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addMandatoryArc(), gum::learning::KTBNLearner< GUM_SCALAR >::addMandatoryArc(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseForbiddenArc(), and gum::learning::KTBNLearner< GUM_SCALAR >::eraseForbiddenArc().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ _checkBaseIsTemporal_()

template<GUM_Numeric GUM_SCALAR>
void gum::learning::IKTBNLearner< GUM_SCALAR >::_checkBaseIsTemporal_ ( std::string_view base,
std::string_view context ) const
protectedinherited

Throw InvalidArgument unless base is a known temporal base. context completes "cannot appear in <context>" (e.g. "an intra-slice constraint", "a kernel-relative arc"): every caller rejects an atemporal base for the same underlying reason – it has no per-slice instance – so they share the sentence and vary the setting.

Definition at line 228 of file IKTBNLearner_tpl.h.

229 {
230 const std::string b{base};
231 if (!_isKnownBase_(b))
233 "unknown base variable '" << base
234 << "': it is not one of this learner's variables")
237 "atemporal variable '" << base << "' cannot appear in " << context
238 << ": it has no per-slice instance")
239 }
virtual bool _isKnownBase_(std::string_view base) const =0
Whether base is one of this learner's variables, temporal or atemporal. The second subclass-specific ...
virtual const std::unordered_set< std::string > & _atemporalVarNames_() const =0
The base names of the atemporal (static) variables. The only subclass-specific input to determineNode...

References _atemporalVarNames_(), _isKnownBase_(), gum::contains(), and GUM_ERROR.

Referenced by _isKnownBase_(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_verifyKernelArc_(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addForbiddenIntraSliceArc(), gum::learning::KTBNLearner< GUM_SCALAR >::addForbiddenIntraSliceArc(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseForbiddenIntraSliceArc(), and gum::learning::KTBNLearner< GUM_SCALAR >::eraseForbiddenIntraSliceArc().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ _checkMinimalOrder_()

template<GUM_Numeric GUM_SCALAR>
void gum::learning::IKTBNLearner< GUM_SCALAR >::_checkMinimalOrder_ ( Size order,
std::string_view label )
staticprotectedinherited

Throw InvalidArgument unless order is at least 2, label naming the offending parameter ("k" for the fixed-k learner, "kMax" for the adaptive one).

This is a learner constraint, not a model one – gum::KTBN, gum::KTBNGenerator and gum::KTBNInference all accept k = 1 – which is why it lives here rather than on the model. Static because four of its call sites are themselves static helpers invoked from member-initialiser lists, before any object exists.

Definition at line 242 of file IKTBNLearner_tpl.h.

242 {
243 if (order < 2)
245 "a k-TBN learner requires "
246 << label << " >= 2: k=1 is a static Bayesian network, use BNLearner instead")
247 }

References GUM_ERROR.

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::KTBNAdaptiveLearner(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::KTBNAdaptiveLearner(), gum::learning::KTBNLearner< GUM_SCALAR >::_buildPriorFromBN_(), gum::learning::KTBNLearner< GUM_SCALAR >::_buildPriorFromCSV_(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_inferAtemporalVars_(), gum::learning::KTBNLearner< GUM_SCALAR >::_inferAtemporalVars_(), and _isKnownBase_().

Here is the caller graph for this function:

◆ _countParameters_()

template<GUM_Numeric GUM_SCALAR>
double gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_countParameters_ ( const KTBN< GUM_SCALAR > & net) const
private

Number of free parameters of net's template: summed over every template node (all initial slices, the kernel slice and the atemporal nodes), \((|X|-1)\prod_{P\in pa(X)}|P|\). This is the model-complexity term of the cross-k BIC and AIC scores used by learnKTBN(): it grows with \(k\) (a higher order adds initial-slice CPTs and can widen the kernel), which is what offsets the monotonic likelihood gain and prevents always picking the largest \(k\).

Definition at line 1524 of file KTBNAdaptiveLearner_tpl.h.

1524 {
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 }

Referenced by _orderSelectionScore_().

Here is the caller graph for this function:

◆ _determineNode_()

template<GUM_Numeric GUM_SCALAR>
std::pair< std::string, int > gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_ ( const std::string & name) const
protectedinherited

engine name -> (base, slice); atemporal names map to KTBN::ATEMPORAL. Shared by every learner; only the atemporal test varies (via atemporalVarNames()).

Definition at line 96 of file IKTBNLearner_tpl.h.

96 {
97 // check atemporal set first: a name registered as atemporal always maps
98 // to ATEMPORAL, even if it syntactically looks like "base[t]"
100
101 // syntactic parse: look for a trailing "[digits]" suffix
102 const std::size_t bracketPos = name.rfind('[');
104
106 name.size() - bracketPos - 1};
107 if (bracketContent.empty() || bracketContent.back() != ']')
109
110 const std::string_view digits = bracketContent.substr(0, bracketContent.size() - 1);
111 if (digits.empty()) return {name, KTBN< GUM_SCALAR >::ATEMPORAL};
112 for (const char c: digits)
113 if (std::isdigit(static_cast< unsigned char >(c)) == 0)
115
116 int slice{};
117 try {
119 } catch (const std::out_of_range&) {
121 "Node name '" << name << "' has a slice index too large to represent as int.")
122 }
123 return {name.substr(0, bracketPos), slice};
124 }

References _atemporalVarNames_(), gum::KTBN< GUM_SCALAR >::ATEMPORAL, gum::contains(), and GUM_ERROR.

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConstraints_(), _checkArcTemporallyFeasible_(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_forEachScoredNode_(), gum::learning::KTBNLearner< GUM_SCALAR >::_forOwningLearner_(), _isKnownBase_(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_recomputeKMin_(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addForbiddenArc(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addMandatoryArc(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addNoChildrenNode(), gum::learning::KTBNLearner< GUM_SCALAR >::addNoChildrenNode(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addNoParentNode(), gum::learning::KTBNLearner< GUM_SCALAR >::addNoParentNode(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addPossibleEdge(), gum::learning::KTBNLearner< GUM_SCALAR >::addPossibleEdge(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseForbiddenArc(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseMandatoryArc(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseNoChildrenNode(), gum::learning::KTBNLearner< GUM_SCALAR >::eraseNoChildrenNode(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseNoParentNode(), gum::learning::KTBNLearner< GUM_SCALAR >::eraseNoParentNode(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::erasePossibleEdge(), gum::learning::KTBNLearner< GUM_SCALAR >::erasePossibleEdge(), and gum::learning::KTBNLearner< GUM_SCALAR >::names().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ _encode_()

template<GUM_Numeric GUM_SCALAR>
std::string gum::learning::IKTBNLearner< GUM_SCALAR >::_encode_ ( std::string_view base,
int slice ) const
protectedinherited

(base, slice) -> engine name ("A[1]" / atemporal engine name). Pure function, shared by every learner.

Definition at line 89 of file IKTBNLearner_tpl.h.

89 {
91 return std::string{base} + '[' + std::to_string(slice) + ']';
92 }

References gum::KTBN< GUM_SCALAR >::ATEMPORAL.

Referenced by gum::learning::KTBNLearner< GUM_SCALAR >::_assemble_(), gum::learning::KTBNLearner< GUM_SCALAR >::_build_(), _isKnownBase_(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addForbiddenArc(), gum::learning::KTBNLearner< GUM_SCALAR >::addForbiddenArc(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addMandatoryArc(), gum::learning::KTBNLearner< GUM_SCALAR >::addMandatoryArc(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addNoChildrenNode(), gum::learning::KTBNLearner< GUM_SCALAR >::addNoChildrenNode(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addNoParentNode(), gum::learning::KTBNLearner< GUM_SCALAR >::addNoParentNode(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addPossibleEdge(), gum::learning::KTBNLearner< GUM_SCALAR >::addPossibleEdge(), gum::learning::KTBNLearner< GUM_SCALAR >::domainSize(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseForbiddenArc(), gum::learning::KTBNLearner< GUM_SCALAR >::eraseForbiddenArc(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseMandatoryArc(), gum::learning::KTBNLearner< GUM_SCALAR >::eraseMandatoryArc(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseNoChildrenNode(), gum::learning::KTBNLearner< GUM_SCALAR >::eraseNoChildrenNode(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseNoParentNode(), gum::learning::KTBNLearner< GUM_SCALAR >::eraseNoParentNode(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::erasePossibleEdge(), gum::learning::KTBNLearner< GUM_SCALAR >::erasePossibleEdge(), and gum::learning::KTBNLearner< GUM_SCALAR >::learnParameters().

Here is the caller graph for this function:

◆ _fNMLScore_()

template<GUM_Numeric GUM_SCALAR>
double gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_fNMLScore_ ( const KTBN< GUM_SCALAR > & net) const
private

fNML order score of net over the recorded trajectories: \(\log_2 L - \sum_i \sum_j \log_2 C^{r_i}_{N_{ij}}\), with \(r_i\) the node's domain size and \(N_{ij}\) the count for parent configuration \(j\). Unlike BIC/AIC the penalty is data-dependent, so the regret needs the same per-instance walk as the likelihood — both are accumulated in one forEachScoredNode pass. Mirrors aGrUM's ScorefNML.

Definition at line 1498 of file KTBNAdaptiveLearner_tpl.h.

1498 {
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 }
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...
VariableLog2ParamComplexity _ctable_
cache of log2 of the multinomial parametric complexity C^r_n, used by the fNML order penalty....

References _ctable_, and _forEachScoredNode_().

Referenced by _orderSelectionScore_().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ _forEachScoredNode_()

template<GUM_Numeric GUM_SCALAR>
template<typename PerInstance, typename PerNodeFinal>
void gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_forEachScoredNode_ ( const KTBN< GUM_SCALAR > & net,
PerInstance perInstance,
PerNodeFinal perNodeFinal ) const
private

Stream every scored template-node instance of net over the recorded trajectories, driving both the likelihood and the fNML penalty off one data walk, so the width-k window logic lives in one place.

Each trajectory is streamed row by row through a width-k circular buffer (absolute time t at slot t % k): every temporal node X[t] is visited against net's template CPT for slice min(t, k-1), reading each parent from row t - lag; atemporal nodes are visited once per trajectory. perInstance runs once per instance with the observed labels loaded into e.inst; perNodeFinal runs once per template node after the stream, for criteria reducing accumulated per-node state (e.g. fNML's regret).

Definition at line 1307 of file KTBNAdaptiveLearner_tpl.h.

1309 {
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 {
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();
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)
1354 atemporalEvals.reserve(net.atemporalVarNames().size());
1355 for (const auto& base: net.atemporalVarNames())
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).
1362
1363 // missing-value markers, as a set for O(1) tests in the inner loop
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.
1381 {
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
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
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 }
Instantiation()
Default constructor: creates an empty tuple.

References gum::Instantiation::Instantiation(), _csvBaseName_, gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _dirPath_, _missingSymbols_, _nbSamples_, gum::KTBN< GUM_SCALAR >::ATEMPORAL, gum::learning::CSVParser::current(), GUM_ERROR, and gum::learning::CSVParser::next().

Referenced by _fNMLScore_(), and _log2Likelihood_().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ _inferAtemporalVars_()

template<GUM_Numeric GUM_SCALAR>
std::unordered_set< std::string > gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_inferAtemporalVars_ ( std::string_view dirPath,
std::string_view csvBaseName,
Size nbSamples,
Size kMax,
const std::vector< std::string > & missingSymbols )
staticprivate

checks kMax >= 2 and nbSamples >= 1, then delegates to the shared IKTBNLearner::scanConstantColumns(). Called from the atemporal-inferring constructor's member-initialiser list, before this object exists, so the checks live here rather than in the body — otherwise a bad argument would only surface after a wasted scan.

Definition at line 144 of file KTBNAdaptiveLearner_tpl.h.

149 {
151 if (nbSamples < 1) GUM_ERROR(InvalidArgument, "KTBNAdaptiveLearner requires nbSamples >= 1")
154 nbSamples,
156 }
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...

References gum::learning::IKTBNLearner< GUM_SCALAR >::_checkMinimalOrder_(), gum::learning::IKTBNLearner< GUM_SCALAR >::_scanConstantColumns_(), GUM_ERROR, and kMax().

Referenced by KTBNAdaptiveLearner().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ _isKnownBase_()

template<GUM_Numeric GUM_SCALAR>
bool gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_isKnownBase_ ( std::string_view base) const
overrideprivatevirtual

whether base is one of this learner's variables; the base names read at construction, from the CSV header or the schema BN.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 1092 of file KTBNAdaptiveLearner_tpl.h.

1092 {
1093 return _baseNames_.contains(std::string{base});
1094 }

References _baseNames_.

◆ _log2Likelihood_()

template<GUM_Numeric GUM_SCALAR>
double gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_log2Likelihood_ ( const KTBN< GUM_SCALAR > & net) const
private

Factorized log2-likelihood of net over the recorded trajectories, comparable across candidate k (the raw score types are not: their flattened tables differ from one k to another). The data is complete, so this is a closed-form sum of CPT lookups — no inference. A thin reduction over forEachScoredNode that sums log2 of the CPT entry over every visited node instance.

Definition at line 1486 of file KTBNAdaptiveLearner_tpl.h.

1486 {
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 }

References _forEachScoredNode_().

Referenced by _orderSelectionScore_().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ _orderSelectionScore_()

template<GUM_Numeric GUM_SCALAR>
double gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_orderSelectionScore_ ( const KTBN< GUM_SCALAR > & net,
double logN ) const
private

The cross-k order-selection score of net under the recorded orderScore criterion, given logN = log2 of the sample size. The single dispatch point learnKTBN() uses to compare candidates; add a branch here for each new OrderScoreType.

Definition at line 1540 of file KTBNAdaptiveLearner_tpl.h.

1541 {
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
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 }
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...
OrderScoreType _orderScore_
recorded cross-k order-selection criterion (the outer score used by learnKTBN() to pick the best k; i...
double _log2Likelihood_(const KTBN< GUM_SCALAR > &net) const
Factorized log2-likelihood of net over the recorded trajectories, comparable across candidate k (the ...
double _countParameters_(const KTBN< GUM_SCALAR > &net) const
Number of free parameters of net's template: summed over every template node (all initial slices,...

References _countParameters_(), _fNMLScore_(), _log2Likelihood_(), _orderScore_, AIC, BIC, and fNML.

Referenced by learnKTBN().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ _raiseKMinForSlice_()

template<GUM_Numeric GUM_SCALAR>
void gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_raiseKMinForSlice_ ( int slice)
private

Raise kMin, if needed, so that kMin > slice: a smaller candidate would silently drop a constraint naming that slice (the "slice < k" rule applyConstraints's fits() filter uses). O(1), since adding a constraint can only push kMin up. No-op for KTBN::ATEMPORAL.

Definition at line 1153 of file KTBNAdaptiveLearner_tpl.h.

1153 {
1155 _kMin_ = std::max(_kMin_, static_cast< Size >(slice) + 1);
1156 }
Size _kMin_
smallest order worth exploring (candidates are kMin..kMax). Starts at 2 and is recomputed by recomput...

References _kMin_, and gum::KTBN< GUM_SCALAR >::ATEMPORAL.

Referenced by _recomputeKMin_(), addForbiddenArc(), addForbiddenKernelArc(), addMandatoryArc(), addMandatoryKernelArc(), addNoChildrenNode(), addNoParentNode(), and addPossibleEdge().

Here is the caller graph for this function:

◆ _recomputeKMin_()

template<GUM_Numeric GUM_SCALAR>
void gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_recomputeKMin_ ( )
private

Recompute kMin from scratch: max(2, 1 + the largest concrete slice named by any recorded forbidden/mandatory arc, possible edge, or no-parent/no-children node (the kinds fits() can drop). Intra-slice / all-slices constraints carry no slice and are excluded. Unlike raiseKMinForSlice, an erase can lower kMin with no O(1) way to tell, so every erase* setter runs this full rescan instead.

Definition at line 1159 of file KTBNAdaptiveLearner_tpl.h.

1159 {
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_)
1186 for (const auto& t: _mandatoryKernelArcs_)
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 }
void _raiseKMinForSlice_(int slice)
Raise kMin, if needed, so that kMin > slice: a smaller candidate would silently drop a constraint nam...

References gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _forbiddenArcs_, _forbiddenKernelArcs_, _kMin_, _mandatoryArcs_, _mandatoryKernelArcs_, _noChildrenNodes_, _noParentNodes_, _possibleEdges_, and _raiseKMinForSlice_().

Referenced by eraseForbiddenArc(), eraseForbiddenKernelArc(), eraseMandatoryArc(), eraseMandatoryKernelArc(), eraseNoChildrenNode(), eraseNoParentNode(), and erasePossibleEdge().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ _scanConstantColumns_()

template<GUM_Numeric GUM_SCALAR>
std::unordered_set< std::string > gum::learning::IKTBNLearner< GUM_SCALAR >::_scanConstantColumns_ ( std::string_view dirPath,
std::string_view csvBaseName,
Size nbSamples,
const std::vector< std::string > & missingSymbols )
staticprotectedinherited

Scans every trajectory and returns the base names classified atemporal: those whose value never changes across the rows of a single trajectory (checked independently per trajectory, so the value may still differ between trajectories). Shared by every atemporal-inferring CSV constructor (KTBNLearner, KTBNAdaptiveLearner): identical scanning logic regardless of which subclass calls it, so duplicating it per subclass would only invite the two copies to drift. Callers are responsible for validating their own arguments (e.g. k/kMax >= 2) before calling this — it does no such check itself, only opens files, so a bad argument would otherwise only be caught after a wasted scan.

Column indices still "live" (not yet proven non-constant) are tracked as a shrinking list rather than rescanned from scratch, and scanning stops opening further trajectories once that list is empty — falsification is one-way, so nothing left to test can ever become atemporal again.

Definition at line 145 of file IKTBNLearner_tpl.h.

149 {
150 namespace fs = std::filesystem;
151 const fs::path dir{dirPath};
154
155 std::vector< std::string > header; // captured from trajectory 1
156 std::vector< std::size_t > candidates; // column indices not yet falsified; shrinks only
157 std::vector< std::string > firstSeen; // per column: first non-missing value THIS trajectory
159 haveFirstSeen; // per column: whether firstSeen[c] is set THIS trajectory
160
161 for (Size i = 0; i < nbSamples; ++i) {
162 // once every column has been falsified, nothing left to test can
163 // ever become atemporal again, so remaining trajectories are never
164 // even opened. Not part of the for-condition: `candidates` does not
165 // exist yet before trajectory 1 populates it.
166 if (i > 0 && candidates.empty()) break;
167
168 const fs::path file = dir / (stem + std::to_string(i + 1) + ".csv");
170 if (!is.is_open()) GUM_ERROR(IOError, "Cannot open " << file.string());
171
172 CSVParser parser(is, file.string());
173 parser.next();
174 const auto& raw = parser.current();
175
176 if (i == 0) {
177 header.assign(raw.begin(), raw.end());
178 candidates.resize(header.size());
179 std::iota(candidates.begin(), candidates.end(), std::size_t{0});
180 } else {
181 bool same = (raw.size() == header.size());
182 for (std::size_t c = 0; same && c < header.size(); ++c)
183 same = (raw[c] == header[c]);
184 if (!same)
186 "Header of " << file.string() << " differs from trajectory 1");
187 }
188
189 haveFirstSeen.assign(header.size(), false);
190 firstSeen.assign(header.size(), {});
191
192 while (parser.next()) {
193 const auto& tokens = parser.current();
194 if (tokens.size() != header.size())
196 "Trajectory " << (i + 1) << ", row " << parser.nbLine() << ": expected "
197 << header.size() << " columns, got " << tokens.size());
198 // iterate only the still-live candidates, swap-erasing any just
199 // falsified so later rows (and later trajectories) never revisit it
200 for (std::size_t idx = 0; idx < candidates.size();) {
201 const std::size_t c = candidates[idx];
202 if (missing.contains(tokens[c])) {
203 ++idx; // uninformative row for this column, still a candidate
204 continue;
205 }
206 if (!haveFirstSeen[c]) {
207 firstSeen[c] = tokens[c];
208 haveFirstSeen[c] = true;
209 ++idx;
210 } else if (tokens[c] != firstSeen[c]) {
211 candidates[idx] = candidates.back(); // falsified: drop, O(1)
212 candidates.pop_back();
213 } else {
214 ++idx;
215 }
216 }
217 if (candidates.empty()) break; // nothing left to test in this file either
218 }
219 }
220
222 for (const std::size_t c: candidates)
223 atemporalVars.insert(header[c]);
224 return atemporalVars;
225 }

References gum::learning::CSVParser::current(), GUM_ERROR, gum::learning::CSVParser::nbLine(), and gum::learning::CSVParser::next().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_inferAtemporalVars_(), gum::learning::KTBNLearner< GUM_SCALAR >::_inferAtemporalVars_(), and _isKnownBase_().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ _verifyBase_()

template<GUM_Numeric GUM_SCALAR>
void gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_verifyBase_ ( std::string_view base,
int slice ) const
private

Throw InvalidArgument unless base is a known base variable and slice is valid for it: base must be in baseNames; an atemporal base requires slice == KTBN::ATEMPORAL, a temporal one requires slice in [0, kMax). Used by the constraint setters to reject unknown names / out-of-range slices eagerly.

Definition at line 1101 of file KTBNAdaptiveLearner_tpl.h.

1101 {
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})) {
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 }

References _atemporalVars_, _baseNames_, _kMax_, gum::KTBN< GUM_SCALAR >::ATEMPORAL, and GUM_ERROR.

Referenced by addForbiddenArc(), addForbiddenArc(), addForbiddenArcAllSlices(), addMandatoryArc(), addMandatoryArc(), addNoChildrenNode(), addNoChildrenNode(), addNoParentNode(), addNoParentNode(), addPossibleEdge(), addPossibleEdge(), eraseForbiddenArc(), eraseForbiddenArc(), eraseForbiddenArcAllSlices(), eraseMandatoryArc(), eraseMandatoryArc(), eraseNoChildrenNode(), eraseNoChildrenNode(), eraseNoParentNode(), eraseNoParentNode(), erasePossibleEdge(), and erasePossibleEdge().

Here is the caller graph for this function:

◆ _verifyKernelArc_()

template<GUM_Numeric GUM_SCALAR>
void gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_verifyKernelArc_ ( std::string_view tailBase,
std::string_view headBase,
int lag ) const
private

Throw InvalidArgument unless tailBase and headBase are known, temporal base variables (a kernel-relative arc has no meaning for an atemporal one: it has no kernel-slice instance) and lag is in [0, kMax) — so some candidate k in [2,kMax] can place tailBase at slice k-1-lag >= 0 and headBase at the kernel slice k-1. Used by the four kernel-arc setters (add/eraseForbiddenKernelArc, add/eraseMandatoryKernelArc) to reject bad calls eagerly.

Definition at line 1129 of file KTBNAdaptiveLearner_tpl.h.

1131 {
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 }
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...

References gum::learning::IKTBNLearner< GUM_SCALAR >::_checkBaseIsTemporal_(), _kMax_, and GUM_ERROR.

Referenced by addForbiddenKernelArc(), addMandatoryKernelArc(), eraseForbiddenKernelArc(), and eraseMandatoryKernelArc().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ addForbiddenArc() [1/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addForbiddenArc ( std::string_view tailBase,
int tailSlice,
std::string_view headBase,
int headSlice )
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 720 of file KTBNAdaptiveLearner_tpl.h.

723 {
724 // validate before _encode_ flattens the slice (a negative one would
725 // silently read back as atemporal, losing the real error)
729 }
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...
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...

References gum::learning::IKTBNLearner< GUM_SCALAR >::_encode_(), _verifyBase_(), and addForbiddenArc().

Here is the call graph for this function:

◆ addForbiddenArc() [2/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addForbiddenArc ( std::string_view tailNode,
std::string_view headNode )
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 703 of file KTBNAdaptiveLearner_tpl.h.

704 {
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.
715 return *this;
716 }

References gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _forbiddenArcs_, _raiseKMinForSlice_(), and _verifyBase_().

Referenced by addForbiddenArc().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ addForbiddenArcAllSlices()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addForbiddenArcAllSlices ( std::string_view tailBase,
std::string_view headBase )
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 897 of file KTBNAdaptiveLearner_tpl.h.

898 {
901 // record the base pair; learnKTBN() expands it over every causally-possible
902 // slice pair for each candidate k (k is not fixed here)
904 return *this;
905 }

References _forbiddenArcsAllSlices_, _verifyBase_(), and gum::KTBN< GUM_SCALAR >::ATEMPORAL.

Here is the call graph for this function:

◆ addForbiddenIntraSliceArc()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addForbiddenIntraSliceArc ( std::string_view tailBase,
std::string_view headBase )
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 870 of file KTBNAdaptiveLearner_tpl.h.

871 {
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
880 return *this;
881 }

References gum::learning::IKTBNLearner< GUM_SCALAR >::_checkBaseIsTemporal_(), and _forbiddenIntraSliceArcs_.

Here is the call graph for this function:

◆ addForbiddenKernelArc()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::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 slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Definition at line 823 of file KTBNAdaptiveLearner_tpl.h.

825 {
829 return *this;
830 }
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...

References _forbiddenKernelArcs_, _raiseKMinForSlice_(), and _verifyKernelArc_().

Here is the call graph for this function:

◆ addMandatoryArc() [1/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addMandatoryArc ( std::string_view tailBase,
int tailSlice,
std::string_view headBase,
int headSlice )
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 778 of file KTBNAdaptiveLearner_tpl.h.

781 {
782 // validate before _encode_ flattens the slice (a negative one would
783 // silently read back as atemporal, losing the real error)
787 }

References gum::learning::IKTBNLearner< GUM_SCALAR >::_encode_(), _verifyBase_(), and addMandatoryArc().

Here is the call graph for this function:

◆ addMandatoryArc() [2/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addMandatoryArc ( std::string_view tailNode,
std::string_view headNode )
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 760 of file KTBNAdaptiveLearner_tpl.h.

761 {
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");
770 // the feasibility check above just rejected headSlice < tailSlice, so
771 // headSlice >= tailSlice is guaranteed here: it alone determines _kMin_.
773 return *this;
774 }
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...

References gum::learning::IKTBNLearner< GUM_SCALAR >::_checkArcTemporallyFeasible_(), gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _mandatoryArcs_, _raiseKMinForSlice_(), and _verifyBase_().

Referenced by addMandatoryArc().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ addMandatoryKernelArc()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::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. See addForbiddenKernelArc for the (base, slice) vs. kernel-relative distinction; the validity constraints (lag range, temporal bases, kMin effect) are the same. Always temporally feasible by construction (lag >= 0 guarantees headSlice = k-1 >= k-1-lag = tailSlice), so unlike the plain addMandatoryArc there is no separate feasibility check to run.

Definition at line 845 of file KTBNAdaptiveLearner_tpl.h.

847 {
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)
854 return *this;
855 }

References _mandatoryKernelArcs_, _raiseKMinForSlice_(), and _verifyKernelArc_().

Here is the call graph for this function:

◆ addNoChildrenNode() [1/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addNoChildrenNode ( std::string_view base,
int slice )
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 955 of file KTBNAdaptiveLearner_tpl.h.

955 {
956 // validate before _encode_ flattens the slice (see the arc overloads above)
959 }

References gum::learning::IKTBNLearner< GUM_SCALAR >::_encode_(), _verifyBase_(), and addNoChildrenNode().

Referenced by addNoChildrenNode().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ addNoChildrenNode() [2/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addNoChildrenNode ( std::string_view name)
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 963 of file KTBNAdaptiveLearner_tpl.h.

963 {
964 const auto [base, slice] = _determineNode_(std::string{name});
968 return *this;
969 }

References gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _noChildrenNodes_, _raiseKMinForSlice_(), and _verifyBase_().

Here is the call graph for this function:

◆ addNoParentNode() [1/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addNoParentNode ( std::string_view base,
int slice )
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 919 of file KTBNAdaptiveLearner_tpl.h.

919 {
920 // validate before _encode_ flattens the slice (see the arc overloads above)
923 }

References gum::learning::IKTBNLearner< GUM_SCALAR >::_encode_(), _verifyBase_(), and addNoParentNode().

Referenced by addNoParentNode().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ addNoParentNode() [2/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addNoParentNode ( std::string_view name)
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 927 of file KTBNAdaptiveLearner_tpl.h.

927 {
928 const auto [base, slice] = _determineNode_(std::string{name});
932 return *this;
933 }

References gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _noParentNodes_, _raiseKMinForSlice_(), and _verifyBase_().

Here is the call graph for this function:

◆ addPossibleEdge() [1/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addPossibleEdge ( std::string_view tail,
std::string_view head )
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 1004 of file KTBNAdaptiveLearner_tpl.h.

1005 {
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
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).
1020 return *this;
1021 }

References gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _possibleEdges_, _raiseKMinForSlice_(), and _verifyBase_().

Here is the call graph for this function:

◆ addPossibleEdge() [2/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::addPossibleEdge ( std::string_view tailBase,
int tailSlice,
std::string_view headBase,
int headSlice )
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 991 of file KTBNAdaptiveLearner_tpl.h.

994 {
995 // validate before _encode_ flattens the slice (a negative one would
996 // silently read back as atemporal, losing the real error)
1000 }

References gum::learning::IKTBNLearner< GUM_SCALAR >::_encode_(), _verifyBase_(), and addPossibleEdge().

Referenced by addPossibleEdge().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ allowArcAdditions()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::allowArcAdditions ( bool allow = true)
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 1055 of file KTBNAdaptiveLearner_tpl.h.

1055 {
1057 return *this;
1058 }

References _allowAdditions_.

◆ allowArcDeletions()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::allowArcDeletions ( bool allow = true)
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 1062 of file KTBNAdaptiveLearner_tpl.h.

1062 {
1064 return *this;
1065 }

References _allowDeletions_.

◆ allowArcReversals()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::allowArcReversals ( bool allow = true)
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 1069 of file KTBNAdaptiveLearner_tpl.h.

1069 {
1071 return *this;
1072 }

References _allowReversals_.

◆ bestK()

template<GUM_Numeric GUM_SCALAR>
Size gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::bestK ( ) const

Order k selected by the last learnKTBN() call.

Exceptions
OperationNotAllowedif learnKTBN() has not run yet.

Definition at line 300 of file KTBNAdaptiveLearner_tpl.h.

300 {
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.")
307 }
Size _bestK_
k selected by the last learnKTBN() call, or 0 as a sentinel while no learning has happened yet....

References _bestK_, and GUM_ERROR.

Referenced by learnKTBN().

Here is the caller graph for this function:

◆ checkScorePriorCompatibility()

template<GUM_Numeric GUM_SCALAR>
std::string gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::checkScorePriorCompatibility ( ) const

Warning string if the recorded score and prior are incompatible, empty otherwise. Data-free: it evaluates the recorded (score, prior) pair exactly as KTBNLearner/BNLearner would, so an incompatible combination can be caught before learnKTBN() reads any trajectory.

Definition at line 339 of file KTBNAdaptiveLearner_tpl.h.

339 {
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_;
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 }
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

References _algo_, _prior_, _priorWeight_, _score_, gum::learning::IBNLearner::AIC, gum::learning::IBNLearner::BD, gum::learning::IBNLearner::BDeu, gum::learning::IBNLearner::BIC, gum::learning::IBNLearner::FCI, gum::learning::IBNLearner::fNML, gum::learning::ScoreAIC::isPriorCompatible(), gum::learning::ScoreBD::isPriorCompatible(), gum::learning::ScoreBDeu::isPriorCompatible(), gum::learning::ScoreBIC::isPriorCompatible(), gum::learning::ScorefNML::isPriorCompatible(), gum::learning::ScoreLog2Likelihood::isPriorCompatible(), gum::learning::IBNLearner::LOG2LIKELIHOOD, gum::learning::IBNLearner::MDL, gum::learning::IBNLearner::MIIC, gum::learning::NoPriorType, gum::learning::IBNLearner::PC, gum::learning::IBNLearner::SMOOTHING, and gum::learning::SmoothingPriorType.

Referenced by state().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ defaultPriorWeight_()

template<GUM_Numeric GUM_SCALAR>
double gum::learning::IKTBNLearner< GUM_SCALAR >::defaultPriorWeight_ ( )
staticprotectedinherited
Returns
the key priorWeight, read when it is called

Definition at line 68 of file IKTBNLearner_tpl.h.

68 {
69 return gum::config().typed< double >("learning", "priorWeight");
70 }
T typed(std::string_view section, std::string_view key) const
Value of section.key converted according to its declared type.
Configuration & config()
A short name for Configuration::instance() : gum::config().epsilonStandard(). It is not inline so tha...

References gum::config(), and gum::Configuration::typed().

Referenced by setMaxIndegree(), useSmoothingPrior(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useSmoothingPrior(), and gum::learning::KTBNLearner< GUM_SCALAR >::useSmoothingPrior().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ defaultTabuListSize_()

template<GUM_Numeric GUM_SCALAR>
Size gum::learning::IKTBNLearner< GUM_SCALAR >::defaultTabuListSize_ ( )
staticprotectedinherited
Returns
the key tabuListSize, read when it is called

Definition at line 58 of file IKTBNLearner_tpl.h.

58 {
59 return static_cast< Size >(gum::config().typed< std::int64_t >("learning", "tabuListSize"));
60 }

References gum::config(), and gum::Configuration::typed().

Referenced by setMaxIndegree(), useLocalSearchWithTabuList(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useLocalSearchWithTabuList(), and gum::learning::KTBNLearner< GUM_SCALAR >::useLocalSearchWithTabuList().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ defaultTabuNbDecrease_()

template<GUM_Numeric GUM_SCALAR>
Size gum::learning::IKTBNLearner< GUM_SCALAR >::defaultTabuNbDecrease_ ( )
staticprotectedinherited
Returns
the key tabuNbDecrease, read when it is called

Definition at line 63 of file IKTBNLearner_tpl.h.

63 {
64 return static_cast< Size >(gum::config().typed< std::int64_t >("learning", "tabuNbDecrease"));
65 }

References gum::config(), and gum::Configuration::typed().

Referenced by setMaxIndegree(), useLocalSearchWithTabuList(), useLocalSearchWithTabuList(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useLocalSearchWithTabuList(), gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useLocalSearchWithTabuList(), gum::learning::KTBNLearner< GUM_SCALAR >::useLocalSearchWithTabuList(), and gum::learning::KTBNLearner< GUM_SCALAR >::useLocalSearchWithTabuList().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ eraseForbiddenArc() [1/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseForbiddenArc ( std::string_view tailBase,
int tailSlice,
std::string_view headBase,
int headSlice )
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 747 of file KTBNAdaptiveLearner_tpl.h.

750 {
751 // validate before _encode_ flattens the slice (a negative one would
752 // silently read back as atemporal, losing the real error)
756 }
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...

References gum::learning::IKTBNLearner< GUM_SCALAR >::_encode_(), _verifyBase_(), and eraseForbiddenArc().

Here is the call graph for this function:

◆ eraseForbiddenArc() [2/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseForbiddenArc ( std::string_view tailNode,
std::string_view headNode )
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 733 of file KTBNAdaptiveLearner_tpl.h.

734 {
739 this->_checkArcTemporallyFeasible_(tailNode, headNode, "un-forbid the arc");
742 return *this;
743 }
void _recomputeKMin_()
Recompute kMin from scratch: max(2, 1 + the largest concrete slice named by any recorded forbidden/ma...

References gum::learning::IKTBNLearner< GUM_SCALAR >::_checkArcTemporallyFeasible_(), gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _forbiddenArcs_, _recomputeKMin_(), and _verifyBase_().

Referenced by eraseForbiddenArc().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ eraseForbiddenArcAllSlices()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseForbiddenArcAllSlices ( std::string_view tailBase,
std::string_view headBase )
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 909 of file KTBNAdaptiveLearner_tpl.h.

References _forbiddenArcsAllSlices_, _verifyBase_(), and gum::KTBN< GUM_SCALAR >::ATEMPORAL.

Here is the call graph for this function:

◆ eraseForbiddenIntraSliceArc()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseForbiddenIntraSliceArc ( std::string_view tailBase,
std::string_view headBase )
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 885 of file KTBNAdaptiveLearner_tpl.h.

886 {
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");
892 return *this;
893 }

References gum::learning::IKTBNLearner< GUM_SCALAR >::_checkBaseIsTemporal_(), and _forbiddenIntraSliceArcs_.

Here is the call graph for this function:

◆ eraseForbiddenKernelArc()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseForbiddenKernelArc ( std::string_view tailBase,
int lag,
std::string_view headBase )

Undo a previous addForbiddenKernelArc (same (tailBase, lag, headBase) triple).

Definition at line 834 of file KTBNAdaptiveLearner_tpl.h.

References _forbiddenKernelArcs_, _recomputeKMin_(), and _verifyKernelArc_().

Here is the call graph for this function:

◆ eraseMandatoryArc() [1/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseMandatoryArc ( std::string_view tailBase,
int tailSlice,
std::string_view headBase,
int headSlice )
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 806 of file KTBNAdaptiveLearner_tpl.h.

809 {
810 // validate before _encode_ flattens the slice (a negative one would
811 // silently read back as atemporal, losing the real error)
815 }
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...

References gum::learning::IKTBNLearner< GUM_SCALAR >::_encode_(), _verifyBase_(), and eraseMandatoryArc().

Here is the call graph for this function:

◆ eraseMandatoryArc() [2/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseMandatoryArc ( std::string_view tailNode,
std::string_view headNode )
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 791 of file KTBNAdaptiveLearner_tpl.h.

792 {
797 // no feasibility check: erasing a never-forced arc is a harmless no-op
798 // (mirrors KTBNLearner::eraseMandatoryArc)
801 return *this;
802 }

References gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _mandatoryArcs_, _recomputeKMin_(), and _verifyBase_().

Referenced by eraseMandatoryArc().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ eraseMandatoryKernelArc()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseMandatoryKernelArc ( std::string_view tailBase,
int lag,
std::string_view headBase )

Undo a previous addMandatoryKernelArc (same (tailBase, lag, headBase) triple).

Definition at line 859 of file KTBNAdaptiveLearner_tpl.h.

References _mandatoryKernelArcs_, _recomputeKMin_(), and _verifyKernelArc_().

Here is the call graph for this function:

◆ eraseNoChildrenNode() [1/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseNoChildrenNode ( std::string_view base,
int slice )
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 973 of file KTBNAdaptiveLearner_tpl.h.

973 {
974 // validate before _encode_ flattens the slice (see the arc overloads above)
977 }
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...

References gum::learning::IKTBNLearner< GUM_SCALAR >::_encode_(), _verifyBase_(), and eraseNoChildrenNode().

Referenced by eraseNoChildrenNode().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ eraseNoChildrenNode() [2/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseNoChildrenNode ( std::string_view name)
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 981 of file KTBNAdaptiveLearner_tpl.h.

981 {
982 const auto [base, slice] = _determineNode_(std::string{name});
986 return *this;
987 }

References gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _noChildrenNodes_, _recomputeKMin_(), and _verifyBase_().

Here is the call graph for this function:

◆ eraseNoParentNode() [1/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseNoParentNode ( std::string_view base,
int slice )
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 937 of file KTBNAdaptiveLearner_tpl.h.

937 {
938 // validate before _encode_ flattens the slice (see the arc overloads above)
941 }
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...

References gum::learning::IKTBNLearner< GUM_SCALAR >::_encode_(), _verifyBase_(), and eraseNoParentNode().

Referenced by eraseNoParentNode().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ eraseNoParentNode() [2/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::eraseNoParentNode ( std::string_view name)
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 945 of file KTBNAdaptiveLearner_tpl.h.

945 {
946 const auto [base, slice] = _determineNode_(std::string{name});
950 return *this;
951 }

References gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _noParentNodes_, _recomputeKMin_(), and _verifyBase_().

Here is the call graph for this function:

◆ erasePossibleEdge() [1/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::erasePossibleEdge ( std::string_view tail,
std::string_view head )
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 1038 of file KTBNAdaptiveLearner_tpl.h.

1039 {
1044 // same alphabetical normalization as addPossibleEdge, so erasing (B,A)
1045 // removes the edge recorded as (A,B)
1050 return *this;
1051 }

References gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _possibleEdges_, _recomputeKMin_(), and _verifyBase_().

Here is the call graph for this function:

◆ erasePossibleEdge() [2/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::erasePossibleEdge ( std::string_view tailBase,
int tailSlice,
std::string_view headBase,
int headSlice )
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 1025 of file KTBNAdaptiveLearner_tpl.h.

1028 {
1029 // validate before _encode_ flattens the slice (a negative one would
1030 // silently read back as atemporal, losing the real error)
1034 }
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...

References gum::learning::IKTBNLearner< GUM_SCALAR >::_encode_(), _verifyBase_(), and erasePossibleEdge().

Referenced by erasePossibleEdge().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ignoreMissingSymbols()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::ignoreMissingSymbols ( bool ignore = true)

Learn and score on the fully observed data only, dropping every row and every scoring instance that carries a missing symbol.

Without this, learnKTBN() refuses trajectories containing missing values: aGrUM's structure learning cannot cope with them (gum::learning::IBNLearner::learnDag_ raises MissingValueInDatabase), so there is nothing sensible to hand it. With it, each candidate's databases are built by complete-case selection and the cross-k score skips any instance whose family is incomplete — the two agree on which data counts.

Warning
This inflates \(\log_2 L\), and inflates it more for larger \(k\) — so it biases the order selection this class exists to perform.

A row or instance is dropped as soon as one cell of its window is missing, so a single gap costs up to \(k\) of them. A larger \(k\) spans more rows per window and loses proportionally more.

\(\log_2 L\) is a sum of per-instance terms, each \(\leq 0\). Dropping instances removes negative terms and therefore raises the total: the candidate is not fitting better, it is being charged for less data. Since the larger \(k\) drops more, it gains more — precisely the comparison bestK() rests on.

The BIC penalty does not compensate. \(\log_2 N\) is computed once from the raw trajectory lengths (deliberately, so it is identical across candidates) and so describes a sample size the likelihood no longer uses; the penalty is unchanged while the likelihood is inflated.

The distortion grows with the missing-value rate. At a few percent it is usually harmless; on heavily incomplete trajectories bestK() can be pulled a full order upwards. Inspect scorePerCandidateK() rather than trusting bestK() alone, and prefer complete trajectories whenever the order itself is the question. gum::learning::KTBNLearner::nbDroppedRows() reports how much each candidate actually lost.

Definition at line 583 of file KTBNAdaptiveLearner_tpl.h.

583 {
585 return *this;
586 }
bool _ignoreMissingSymbols_
whether incomplete rows/instances are dropped (see ignoreMissingSymbols())

References _ignoreMissingSymbols_.

◆ isIgnoringMissingSymbols()

template<GUM_Numeric GUM_SCALAR>
INLINE bool gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::isIgnoringMissingSymbols ( ) const

Whether incomplete rows and instances are dropped. False by default.

Definition at line 589 of file KTBNAdaptiveLearner_tpl.h.

589 {
591 }

References _ignoreMissingSymbols_.

◆ kMax()

template<GUM_Numeric GUM_SCALAR>
Size gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::kMax ( ) const

Largest order explored (the kMax argument of the constructor).

Definition at line 334 of file KTBNAdaptiveLearner_tpl.h.

334 {
335 return _kMax_;
336 }

References _kMax_.

Referenced by KTBNAdaptiveLearner(), KTBNAdaptiveLearner(), KTBNAdaptiveLearner(), and _inferAtemporalVars_().

Here is the caller graph for this function:

◆ latentVariables()

template<GUM_Numeric GUM_SCALAR>
const std::vector< std::pair< std::string, std::string > > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::latentVariables ( ) const

Engine-name (tail, head) pairs of arcs the selected model's MIIC run flagged as hiding a latent variable. Empty when the recorded algorithm is not MIIC (only MIIC produces latent-variable annotations) or when none were found.

Exceptions
OperationNotAllowedif learnKTBN() has not run yet.

Definition at line 311 of file KTBNAdaptiveLearner_tpl.h.

311 {
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 }
std::vector< std::pair< std::string, std::string > > _bestLatentVariables_
latent-variable arcs (engine-name pairs) reported by the winning candidate's MIIC run,...

References _bestK_, _bestLatentVariables_, and GUM_ERROR.

◆ learnKTBN()

template<GUM_Numeric GUM_SCALAR>
KTBN< GUM_SCALAR > gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::learnKTBN ( )
overridevirtual

Learns the best k in [kMin, kMax] together with the structure and the CPTs: one KTBNLearner is built and run per candidate k, the recorded configuration is replayed on each, and the k-TBN with the best model-selection score is returned. kMin starts at 2 and is raised by the structural-constraint setters (see class doc).

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 199 of file KTBNAdaptiveLearner_tpl.h.

199 {
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();
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
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.
228 k,
229 *_prior_bn_,
236 k,
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;
262 }
263
266
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) {
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)
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;
296 return best;
297 }
void _applyConstraints_(KTBNLearner< GUM_SCALAR > &learner, Size k) const
Replay the recorded structural constraints onto learner (built for order k). Engine-name constraints ...
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...
Size bestK() const
Order k selected by the last learnKTBN() call.
void _applyConfig_(KTBNLearner< GUM_SCALAR > &learner) const
Apply the recorded score / algorithm / correction / prior onto a freshly-built learner....
std::vector< std::pair< Size, double > > _scorePerCandidateK_
per-candidate (k, order-score) pairs from the last learnKTBN() run, in ascending k....
KTBN< GUM_SCALAR > learnKTBN() override
Learns the best k in [kMin, kMax] together with the structure and the CPTs: one KTBNLearner is built ...

References _algo_, _applyConfig_(), _applyConstraints_(), _atemporalVars_, _bestK_, _bestLatentVariables_, _csvBaseName_, _dirPath_, _ignoreMissingSymbols_, _induceTypes_, _kMax_, _kMin_, _missingSymbols_, _nbSamples_, _orderSelectionScore_(), _prior_bn_, _scorePerCandidateK_, bestK(), GUM_ERROR, and gum::learning::IBNLearner::MIIC.

Here is the call graph for this function:

◆ operator=() [1/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::operator= ( const KTBNAdaptiveLearner< GUM_SCALAR > & )
privatedelete

References KTBNAdaptiveLearner().

Here is the call graph for this function:

◆ operator=() [2/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::operator= ( KTBNAdaptiveLearner< GUM_SCALAR > && )
privatedelete

References KTBNAdaptiveLearner().

Here is the call graph for this function:

◆ scorePerCandidateK()

template<GUM_Numeric GUM_SCALAR>
const std::vector< std::pair< Size, double > > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::scorePerCandidateK ( ) const

Per-candidate cross-k scores from the last learnKTBN() call, as (k, score) pairs for k = kMin..kMax in ascending k order — the values the order selection compared to choose bestK() (higher is better; the argmax is bestK()). Under the default useOrderScoreBIC() each score is \(\log_2 L - \tfrac{1}{2}\,d\,\log_2 N\) of the k-TBN learned for that k.

Exceptions
OperationNotAllowedif learnKTBN() has not run yet.

Definition at line 320 of file KTBNAdaptiveLearner_tpl.h.

320 {
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 }

References _bestK_, _scorePerCandidateK_, and GUM_ERROR.

◆ setMaxIndegree()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::setMaxIndegree ( Size max_indegree)
overridevirtual

Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at slice k-1-lag -> headBase at slice k-1, for whichever k is selected. The slice is not given directly but derived from lag relative to the kernel slice k-1, which moves with the candidate — so no absolute slice could express it at record time. Adaptive-only: the fixed-k learners have no moving kernel slice to anchor it to. lag must be in [0, kMax) and both bases temporal (an atemporal variable has no kernel-slice instance). Raises kMin to at least lag+1, like a constraint naming slice lag.

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 1076 of file KTBNAdaptiveLearner_tpl.h.

1076 {
1078 return *this;
1079 }

References _maxIndegree_.

◆ state()

template<GUM_Numeric GUM_SCALAR>
std::vector< std::tuple< std::string, std::string, std::string > > gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::state ( ) const

The recorded configuration as (key, value, comment) tuples (mirrors KTBNLearner::state()); toString() is a formatted view of it.

Definition at line 369 of file KTBNAdaptiveLearner_tpl.h.

369 {
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), ...}"
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
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 }
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_));
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 }
std::string checkScorePriorCompatibility() const
Warning string if the recorded score and prior are incompatible, empty otherwise. Data-free: it evalu...

References _algo_, _allowAdditions_, _allowDeletions_, _allowReversals_, _atemporalVars_, _baseNames_, _bestK_, _correction_, _forbiddenArcs_, _forbiddenArcsAllSlices_, _forbiddenIntraSliceArcs_, _forbiddenKernelArcs_, _kMax_, _kMin_, _mandatoryArcs_, _mandatoryKernelArcs_, _maxIndegree_, _nbDecrease_, _noChildrenNodes_, _noParentNodes_, _orderScore_, _possibleEdges_, _prior_, _priorWeight_, _score_, _tabuSize_, gum::learning::IBNLearner::AIC, AIC, gum::learning::IBNLearner::BD, gum::learning::IBNLearner::BDeu, gum::learning::IBNLearner::BIC, BIC, checkScorePriorCompatibility(), gum::learning::IBNLearner::EXTENDED_GREEDY_HILL_CLIMBING, gum::learning::IBNLearner::FCI, gum::learning::IBNLearner::fNML, fNML, gum::learning::IBNLearner::GREEDY_HILL_CLIMBING, gum::learning::IBNLearner::GREEDY_THICK_THINNING, gum::learning::IBNLearner::LOCAL_SEARCH_WITH_TABU_LIST, gum::learning::IBNLearner::LOG2LIKELIHOOD, gum::learning::CorrectedMutualInformation::MDL, gum::learning::IBNLearner::MDL, gum::learning::IBNLearner::MIIC, gum::learning::CorrectedMutualInformation::NML, gum::learning::CorrectedMutualInformation::NoCorr, gum::learning::IBNLearner::PC, and gum::learning::IBNLearner::SMOOTHING.

Referenced by toString().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ toString()

template<GUM_Numeric GUM_SCALAR>
std::string gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::toString ( ) const

Human-readable summary of the recorded configuration (candidate order range, algorithm / score / correction / prior, structural constraints) plus the selected k once learnKTBN() has run.

Definition at line 494 of file KTBNAdaptiveLearner_tpl.h.

494 {
495 // aligned "key : value (comment)" listing, same layout as BNLearner::toString
496 const auto st = state();
498 for (const auto& t: st)
500
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 }
std::vector< std::tuple< std::string, std::string, std::string > > state() const
The recorded configuration as (key, value, comment) tuples (mirrors KTBNLearner::state()); toString()...

References state().

Here is the call graph for this function:

◆ useExtendedGreedyHillClimbing()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useExtendedGreedyHillClimbing ( )
overridevirtual

the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 605 of file KTBNAdaptiveLearner_tpl.h.

605 {
607 return *this;
608 }

References _algo_, and gum::learning::IBNLearner::EXTENDED_GREEDY_HILL_CLIMBING.

◆ useFCI()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useFCI ( )
overridevirtual

the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 653 of file KTBNAdaptiveLearner_tpl.h.

653 {
655 return *this;
656 }

References KTBNAdaptiveLearner(), _algo_, and gum::learning::IBNLearner::FCI.

Here is the call graph for this function:

◆ useGreedyHillClimbing()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useGreedyHillClimbing ( )
overridevirtual

the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 598 of file KTBNAdaptiveLearner_tpl.h.

598 {
600 return *this;
601 }

References KTBNAdaptiveLearner(), _algo_, and gum::learning::IBNLearner::GREEDY_HILL_CLIMBING.

Here is the call graph for this function:

◆ useGreedyThickThinning()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useGreedyThickThinning ( )
overridevirtual

the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 641 of file KTBNAdaptiveLearner_tpl.h.

641 {
643 return *this;
644 }

References KTBNAdaptiveLearner(), _algo_, and gum::learning::IBNLearner::GREEDY_THICK_THINNING.

Here is the call graph for this function:

◆ useLocalSearchWithTabuList() [1/3]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useLocalSearchWithTabuList ( )

the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)

Definition at line 612 of file KTBNAdaptiveLearner_tpl.h.

References gum::learning::IKTBNLearner< GUM_SCALAR >::defaultTabuListSize_(), gum::learning::IKTBNLearner< GUM_SCALAR >::defaultTabuNbDecrease_(), and useLocalSearchWithTabuList().

Here is the call graph for this function:

◆ useLocalSearchWithTabuList() [2/3]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useLocalSearchWithTabuList ( Size tabu_size)

the default number of decreasing changes (key tabuNbDecrease)

Definition at line 619 of file KTBNAdaptiveLearner_tpl.h.

References gum::learning::IKTBNLearner< GUM_SCALAR >::defaultTabuNbDecrease_(), and useLocalSearchWithTabuList().

Here is the call graph for this function:

◆ useLocalSearchWithTabuList() [3/3]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useLocalSearchWithTabuList ( Size tabu_size,
Size nb_decrease )
overridevirtual

the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 626 of file KTBNAdaptiveLearner_tpl.h.

References _algo_, _nbDecrease_, _tabuSize_, and gum::learning::IBNLearner::LOCAL_SEARCH_WITH_TABU_LIST.

Referenced by useLocalSearchWithTabuList(), and useLocalSearchWithTabuList().

Here is the caller graph for this function:

◆ useMDLCorrection()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useMDLCorrection ( )
overridevirtual

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 669 of file KTBNAdaptiveLearner_tpl.h.

669 {
671 return *this;
672 }

References KTBNAdaptiveLearner(), _correction_, and gum::learning::CorrectedMutualInformation::MDL.

Here is the call graph for this function:

◆ useMIIC()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useMIIC ( )
overridevirtual

the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 635 of file KTBNAdaptiveLearner_tpl.h.

635 {
637 return *this;
638 }

References KTBNAdaptiveLearner(), _algo_, and gum::learning::IBNLearner::MIIC.

Here is the call graph for this function:

◆ useNMLCorrection()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useNMLCorrection ( )
overridevirtual

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 663 of file KTBNAdaptiveLearner_tpl.h.

663 {
665 return *this;
666 }

References KTBNAdaptiveLearner(), _correction_, and gum::learning::CorrectedMutualInformation::NML.

Here is the call graph for this function:

◆ useNoCorrection()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useNoCorrection ( )
overridevirtual

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 675 of file KTBNAdaptiveLearner_tpl.h.

675 {
677 return *this;
678 }

References KTBNAdaptiveLearner(), _correction_, and gum::learning::CorrectedMutualInformation::NoCorr.

Here is the call graph for this function:

◆ useOrderScoreAIC()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useOrderScoreAIC ( )

Select k by AIC: keep the k whose learned model maximises \(\log_2 L - d\) (a lighter, sample-size-independent complexity penalty than BIC).

Definition at line 566 of file KTBNAdaptiveLearner_tpl.h.

566 {
568 return *this;
569 }

References KTBNAdaptiveLearner(), _orderScore_, and AIC.

Here is the call graph for this function:

◆ useOrderScoreBIC()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useOrderScoreBIC ( )

Select k by BIC (the default): keep the k whose learned model maximises \(\log_2 L - \tfrac{1}{2}\,d\,\log_2 N\).

Definition at line 560 of file KTBNAdaptiveLearner_tpl.h.

560 {
562 return *this;
563 }

References KTBNAdaptiveLearner(), _orderScore_, and BIC.

Here is the call graph for this function:

◆ useOrderScorefNML()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useOrderScorefNML ( )

\(\tfrac{1}{2}\,d\,\log_2 N\) by a sum of per-node, per-parent-configuration multinomial parametric complexities (regret) – data-dependent, unlike BIC/AIC, matching aGrUM's ScorefNML.

Definition at line 572 of file KTBNAdaptiveLearner_tpl.h.

572 {
574 return *this;
575 }

References KTBNAdaptiveLearner(), _orderScore_, and fNML.

Here is the call graph for this function:

◆ usePC()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::usePC ( )
overridevirtual

the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 647 of file KTBNAdaptiveLearner_tpl.h.

647 {
649 return *this;
650 }

References KTBNAdaptiveLearner(), _algo_, and gum::learning::IBNLearner::PC.

Here is the call graph for this function:

◆ useScoreAIC()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useScoreAIC ( )
overridevirtual

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 515 of file KTBNAdaptiveLearner_tpl.h.

515 {
517 return *this;
518 }

References KTBNAdaptiveLearner(), _score_, and gum::learning::IBNLearner::AIC.

Here is the call graph for this function:

◆ useScoreBD()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useScoreBD ( )
overridevirtual

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 521 of file KTBNAdaptiveLearner_tpl.h.

521 {
523 return *this;
524 }

References KTBNAdaptiveLearner(), _score_, and gum::learning::IBNLearner::BD.

Here is the call graph for this function:

◆ useScoreBDeu()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useScoreBDeu ( )
overridevirtual

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 527 of file KTBNAdaptiveLearner_tpl.h.

527 {
529 return *this;
530 }

References KTBNAdaptiveLearner(), _score_, and gum::learning::IBNLearner::BDeu.

Here is the call graph for this function:

◆ useScoreBIC()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useScoreBIC ( )
overridevirtual

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 533 of file KTBNAdaptiveLearner_tpl.h.

533 {
535 return *this;
536 }

References KTBNAdaptiveLearner(), _score_, and gum::learning::IBNLearner::BIC.

Here is the call graph for this function:

◆ useScorefNML()

template<GUM_Numeric GUM_SCALAR>
void gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useScorefNML ( )
overridevirtual

◆ useScoreLog2Likelihood()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useScoreLog2Likelihood ( )
overridevirtual

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 539 of file KTBNAdaptiveLearner_tpl.h.

539 {
541 return *this;
542 }

References KTBNAdaptiveLearner(), _score_, and gum::learning::IBNLearner::LOG2LIKELIHOOD.

Here is the call graph for this function:

◆ useScoreMDL()

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useScoreMDL ( )
overridevirtual

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 545 of file KTBNAdaptiveLearner_tpl.h.

545 {
547 return *this;
548 }

References KTBNAdaptiveLearner(), _score_, and gum::learning::IBNLearner::MDL.

Here is the call graph for this function:

◆ useSmoothingPrior() [1/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useSmoothingPrior ( )

the default weight (key priorWeight of the section learning)

Definition at line 685 of file KTBNAdaptiveLearner_tpl.h.

References KTBNAdaptiveLearner(), gum::learning::IKTBNLearner< GUM_SCALAR >::defaultPriorWeight_(), and useSmoothingPrior().

Here is the call graph for this function:

◆ useSmoothingPrior() [2/2]

template<GUM_Numeric GUM_SCALAR>
KTBNAdaptiveLearner< GUM_SCALAR > & gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::useSmoothingPrior ( double weight)
overridevirtual

the default weight (key priorWeight of the section learning)

Implements gum::learning::IKTBNLearner< GUM_SCALAR >.

Definition at line 691 of file KTBNAdaptiveLearner_tpl.h.

691 {
694 return *this;
695 }

References _prior_, _priorWeight_, and gum::learning::IBNLearner::SMOOTHING.

Referenced by useSmoothingPrior().

Here is the caller graph for this function:

Member Data Documentation

◆ _algo_

template<GUM_Numeric GUM_SCALAR>
IBNLearner::AlgoType gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_algo_ {IBNLearner::preferredAlgo()}
private

◆ _allowAdditions_

template<GUM_Numeric GUM_SCALAR>
bool gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_allowAdditions_ {true}
private

recorded graph-change permissions / indegree cap

Definition at line 593 of file KTBNAdaptiveLearner.h.

Referenced by _applyConstraints_(), allowArcAdditions(), and state().

◆ _allowDeletions_

template<GUM_Numeric GUM_SCALAR>
bool gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_allowDeletions_ {true}
private

Definition at line 594 of file KTBNAdaptiveLearner.h.

Referenced by _applyConstraints_(), allowArcDeletions(), and state().

◆ _allowReversals_

template<GUM_Numeric GUM_SCALAR>
bool gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_allowReversals_ {true}
private

Definition at line 595 of file KTBNAdaptiveLearner.h.

Referenced by _applyConstraints_(), allowArcReversals(), and state().

◆ _atemporalVars_

template<GUM_Numeric GUM_SCALAR>
std::unordered_set< std::string > gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_atemporalVars_
private

base names of the atemporal (static) variables

Definition at line 539 of file KTBNAdaptiveLearner.h.

Referenced by KTBNAdaptiveLearner(), KTBNAdaptiveLearner(), _atemporalVarNames_(), _verifyBase_(), learnKTBN(), and state().

◆ _baseNames_

template<GUM_Numeric GUM_SCALAR>
std::unordered_set< std::string > gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_baseNames_
private

all base variable names (temporal + atemporal), read from the first trajectory CSV header at construction. Authoritative universe used by the constraint setters to reject names that do not exist.

Definition at line 544 of file KTBNAdaptiveLearner.h.

Referenced by KTBNAdaptiveLearner(), KTBNAdaptiveLearner(), _isKnownBase_(), _verifyBase_(), and state().

◆ _bestK_

template<GUM_Numeric GUM_SCALAR>
Size gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_bestK_ {0}
private

k selected by the last learnKTBN() call, or 0 as a sentinel while no learning has happened yet. 0 can never be a valid order (candidates are 2..kMax), so bestK() reads it to decide whether learnKTBN() has run.

Definition at line 637 of file KTBNAdaptiveLearner.h.

Referenced by bestK(), latentVariables(), learnKTBN(), scorePerCandidateK(), and state().

◆ _bestLatentVariables_

template<GUM_Numeric GUM_SCALAR>
std::vector< std::pair< std::string, std::string > > gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_bestLatentVariables_
private

latent-variable arcs (engine-name pairs) reported by the winning candidate's MIIC run, captured by learnKTBN(); empty when the selected algorithm is not MIIC. Exposed by latentVariables().

Definition at line 642 of file KTBNAdaptiveLearner.h.

Referenced by latentVariables(), and learnKTBN().

◆ _correction_

◆ _csvBaseName_

template<GUM_Numeric GUM_SCALAR>
std::string gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_csvBaseName_
private

stem of each trajectory file name

Definition at line 523 of file KTBNAdaptiveLearner.h.

Referenced by KTBNAdaptiveLearner(), KTBNAdaptiveLearner(), _forEachScoredNode_(), and learnKTBN().

◆ _ctable_

template<GUM_Numeric GUM_SCALAR>
VariableLog2ParamComplexity gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_ctable_
mutableprivate

cache of log2 of the multinomial parametric complexity C^r_n, used by the fNML order penalty. Mutable because log2Cnr() memoizes; the const order-score helpers may therefore call it. Only touched under fNML.

Definition at line 784 of file KTBNAdaptiveLearner.h.

Referenced by _fNMLScore_().

◆ _dirPath_

template<GUM_Numeric GUM_SCALAR>
std::string gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_dirPath_
private

directory holding the trajectory CSV files

Definition at line 520 of file KTBNAdaptiveLearner.h.

Referenced by KTBNAdaptiveLearner(), KTBNAdaptiveLearner(), _forEachScoredNode_(), and learnKTBN().

◆ _forbiddenArcs_

template<GUM_Numeric GUM_SCALAR>
std::set< std::pair< std::string, std::string > > gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_forbiddenArcs_
private

forbidden arcs, as (tail, head) engine-name pairs

Definition at line 605 of file KTBNAdaptiveLearner.h.

Referenced by _applyConstraints_(), _recomputeKMin_(), addForbiddenArc(), eraseForbiddenArc(), and state().

◆ _forbiddenArcsAllSlices_

template<GUM_Numeric GUM_SCALAR>
std::set< std::pair< std::string, std::string > > gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_forbiddenArcsAllSlices_
private

forbidden all-slices arcs, as (tailBase, headBase) pairs

Definition at line 617 of file KTBNAdaptiveLearner.h.

Referenced by _applyConstraints_(), addForbiddenArcAllSlices(), eraseForbiddenArcAllSlices(), and state().

◆ _forbiddenIntraSliceArcs_

template<GUM_Numeric GUM_SCALAR>
std::set< std::pair< std::string, std::string > > gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_forbiddenIntraSliceArcs_
private

forbidden intra-slice arcs, as (tailBase, headBase) pairs

Definition at line 614 of file KTBNAdaptiveLearner.h.

Referenced by _applyConstraints_(), addForbiddenIntraSliceArc(), eraseForbiddenIntraSliceArc(), and state().

◆ _forbiddenKernelArcs_

template<GUM_Numeric GUM_SCALAR>
std::set< std::tuple< std::string, std::string, int > > gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_forbiddenKernelArcs_
private

forbidden kernel-relative arcs, as (tailBase, headBase, lag) triples: tailBase at slice k-1-lag -> headBase at the kernel slice k-1. Kept separate from forbiddenArcs (which stores resolved engine names) since the slice here is only known once a candidate k is fixed.

Definition at line 623 of file KTBNAdaptiveLearner.h.

Referenced by _applyConstraints_(), _recomputeKMin_(), addForbiddenKernelArc(), eraseForbiddenKernelArc(), and state().

◆ _ignoreMissingSymbols_

template<GUM_Numeric GUM_SCALAR>
bool gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_ignoreMissingSymbols_ {false}
private

whether incomplete rows/instances are dropped (see ignoreMissingSymbols())

Definition at line 550 of file KTBNAdaptiveLearner.h.

Referenced by ignoreMissingSymbols(), isIgnoringMissingSymbols(), and learnKTBN().

◆ _induceTypes_

template<GUM_Numeric GUM_SCALAR>
bool gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_induceTypes_
private

whether numeric columns are retyped (see KTBNLearner); unused (and forced false) when a schema BN is supplied

Definition at line 554 of file KTBNAdaptiveLearner.h.

Referenced by KTBNAdaptiveLearner(), KTBNAdaptiveLearner(), and learnKTBN().

◆ _kMax_

template<GUM_Numeric GUM_SCALAR>
Size gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_kMax_
private

largest order to explore (candidates are kMin..kMax)

Definition at line 529 of file KTBNAdaptiveLearner.h.

Referenced by KTBNAdaptiveLearner(), KTBNAdaptiveLearner(), _verifyBase_(), _verifyKernelArc_(), kMax(), learnKTBN(), and state().

◆ _kMin_

template<GUM_Numeric GUM_SCALAR>
Size gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_kMin_ {2}
private

smallest order worth exploring (candidates are kMin..kMax). Starts at 2 and is recomputed by recomputeKMin() from the recorded slice-bearing constraints every time one is added or erased; never set directly. See recomputeKMin() for why it must be a recompute rather than an incremental raise/lower.

Definition at line 536 of file KTBNAdaptiveLearner.h.

Referenced by _raiseKMinForSlice_(), _recomputeKMin_(), learnKTBN(), and state().

◆ _mandatoryArcs_

template<GUM_Numeric GUM_SCALAR>
std::set< std::pair< std::string, std::string > > gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_mandatoryArcs_
private

mandatory arcs, as (tail, head) engine-name pairs

Definition at line 608 of file KTBNAdaptiveLearner.h.

Referenced by _applyConstraints_(), _recomputeKMin_(), addMandatoryArc(), eraseMandatoryArc(), and state().

◆ _mandatoryKernelArcs_

template<GUM_Numeric GUM_SCALAR>
std::set< std::tuple< std::string, std::string, int > > gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_mandatoryKernelArcs_
private

mandatory kernel-relative arcs, same shape as forbiddenKernelArcs

Definition at line 626 of file KTBNAdaptiveLearner.h.

Referenced by _applyConstraints_(), _recomputeKMin_(), addMandatoryKernelArc(), eraseMandatoryKernelArc(), and state().

◆ _maxIndegree_

template<GUM_Numeric GUM_SCALAR>
Size gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_maxIndegree_ {std::numeric_limits< Size >::max()}
private

Definition at line 596 of file KTBNAdaptiveLearner.h.

Referenced by _applyConstraints_(), setMaxIndegree(), and state().

◆ _missingSymbols_

template<GUM_Numeric GUM_SCALAR>
std::vector< std::string > gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_missingSymbols_
private

symbols in the CSVs to interpret as missing values

Definition at line 547 of file KTBNAdaptiveLearner.h.

Referenced by KTBNAdaptiveLearner(), KTBNAdaptiveLearner(), _forEachScoredNode_(), and learnKTBN().

◆ _nbDecrease_

template<GUM_Numeric GUM_SCALAR>
Size gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_nbDecrease_ {2}
private

Definition at line 580 of file KTBNAdaptiveLearner.h.

Referenced by _applyConfig_(), state(), and useLocalSearchWithTabuList().

◆ _nbSamples_

template<GUM_Numeric GUM_SCALAR>
Size gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_nbSamples_
private

number of CSV files to read

Definition at line 526 of file KTBNAdaptiveLearner.h.

Referenced by KTBNAdaptiveLearner(), KTBNAdaptiveLearner(), _forEachScoredNode_(), and learnKTBN().

◆ _noChildrenNodes_

template<GUM_Numeric GUM_SCALAR>
std::set< std::string > gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_noChildrenNodes_
private

leaf nodes (no children), as engine names

Definition at line 632 of file KTBNAdaptiveLearner.h.

Referenced by _applyConstraints_(), _recomputeKMin_(), addNoChildrenNode(), eraseNoChildrenNode(), and state().

◆ _noParentNodes_

template<GUM_Numeric GUM_SCALAR>
std::set< std::string > gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_noParentNodes_
private

root nodes (no parents), as engine names

Definition at line 629 of file KTBNAdaptiveLearner.h.

Referenced by _applyConstraints_(), _recomputeKMin_(), addNoParentNode(), eraseNoParentNode(), and state().

◆ _orderScore_

template<GUM_Numeric GUM_SCALAR>
OrderScoreType gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_orderScore_ {OrderScoreType::BIC}
private

recorded cross-k order-selection criterion (the outer score used by learnKTBN() to pick the best k; independent of score)

Definition at line 570 of file KTBNAdaptiveLearner.h.

Referenced by _orderSelectionScore_(), state(), useOrderScoreAIC(), useOrderScoreBIC(), and useOrderScorefNML().

◆ _possibleEdges_

template<GUM_Numeric GUM_SCALAR>
std::set< std::pair< std::string, std::string > > gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_possibleEdges_
private

MIIC candidate edges, as (tail, head) engine-name pairs.

Definition at line 611 of file KTBNAdaptiveLearner.h.

Referenced by _applyConstraints_(), _recomputeKMin_(), addPossibleEdge(), erasePossibleEdge(), and state().

◆ _prior_

template<GUM_Numeric GUM_SCALAR>
IBNLearner::BNLearnerPriorType gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_prior_ {IBNLearner::BNLearnerPriorType::NO_prior}
private

recorded prior and its weight

Definition at line 587 of file KTBNAdaptiveLearner.h.

Referenced by _applyConfig_(), checkScorePriorCompatibility(), state(), and useSmoothingPrior().

◆ _prior_bn_

template<GUM_Numeric GUM_SCALAR>
std::unique_ptr< BayesNet< GUM_SCALAR > > gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_prior_bn_
private

optional variable-schema BN (set by the BN constructor): when present, each per-k KTBNLearner is built from it so the variable domains are fixed explicitly instead of inferred from trajectory 1. Null in CSV mode.

Definition at line 559 of file KTBNAdaptiveLearner.h.

Referenced by KTBNAdaptiveLearner(), and learnKTBN().

◆ _priorWeight_

template<GUM_Numeric GUM_SCALAR>
double gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_priorWeight_ {1.0}
private

always written by the useXxxPrior() methods, which read learning.priorWeight when no weight is given

Definition at line 590 of file KTBNAdaptiveLearner.h.

Referenced by _applyConfig_(), checkScorePriorCompatibility(), state(), and useSmoothingPrior().

◆ _score_

template<GUM_Numeric GUM_SCALAR>
IBNLearner::ScoreType gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_score_ {IBNLearner::ScoreType::BDeu}
private

recorded per-k structure score (the inner score, replayed on each candidate)

Definition at line 566 of file KTBNAdaptiveLearner.h.

Referenced by _applyConfig_(), checkScorePriorCompatibility(), state(), useScoreAIC(), useScoreBD(), useScoreBDeu(), useScoreBIC(), useScorefNML(), useScoreLog2Likelihood(), and useScoreMDL().

◆ _scorePerCandidateK_

template<GUM_Numeric GUM_SCALAR>
std::vector< std::pair< Size, double > > gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_scorePerCandidateK_
private

per-candidate (k, order-score) pairs from the last learnKTBN() run, in ascending k. One entry appended per candidate; read by scorePerCandidateK(). Cleared at the start of each learnKTBN() (empty while bestK == 0).

Definition at line 647 of file KTBNAdaptiveLearner.h.

Referenced by learnKTBN(), and scorePerCandidateK().

◆ _tabuSize_

template<GUM_Numeric GUM_SCALAR>
Size gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_tabuSize_ {100}
private

tabu-list parameters (meaningful when the algorithm is LOCAL_SEARCH_WITH_TABU_LIST). They are always written by useLocalSearchWithTabuList(), which reads learning.tabuListSize and learning.tabuNbDecrease when no value is given.

Definition at line 579 of file KTBNAdaptiveLearner.h.

Referenced by _applyConfig_(), state(), and useLocalSearchWithTabuList().

◆ C

template<GUM_Numeric GUM_SCALAR>
log_2 gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::C {r_i}_{N_{ij}}@f$

Select k by fNML (factorized Normalized Maximum Likelihood): keep the k whose learned model maximises .

Definition at line 278 of file KTBNAdaptiveLearner.h.


The documentation for this class was generated from the following files: