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

Learns a k-TBN (structure and/or parameters) from trajectory CSVs. More...

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

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

Public Member Functions

Constructors / Destructors
 KTBNLearner (std::string_view dirPath, std::string_view csvBaseName, Size nbSamples, Size k, const std::unordered_set< std::string > &atemporalVars, const std::vector< std::string > &missingSymbols={"?"}, bool induceTypes=true, bool ignoreMissingSymbols=false)
 Structure-learning constructor — variable roles supplied explicitly.
 KTBNLearner (std::string_view dirPath, std::string_view csvBaseName, Size nbSamples, Size k, const std::vector< std::string > &missingSymbols={"?"}, bool induceTypes=true, bool ignoreMissingSymbols=false)
 Structure-learning constructor — atemporal variables inferred from the CSVs.
 KTBNLearner (std::string_view dirPath, std::string_view csvBaseName, Size nbSamples, Size k, const BayesNet< GUM_SCALAR > &bn, const std::unordered_set< std::string > &atemporalVars={}, const std::vector< std::string > &missingSymbols={"?"}, bool ignoreMissingSymbols=false)
 Variable-schema constructor — types and domains supplied via a BN.
 ~KTBNLearner ()
 destructor
Main learning methods
KTBN< GUM_SCALAR > learnKTBN () override
 Full learning (structure + CPTs). Mirrors BNLearner::learnBN().
KTBN< GUM_SCALAR > learnParameters (const KTBN< GUM_SCALAR > &structure, bool takeIntoAccountScore=true)
 CPTs only, using the arc structure of structure. structure must have the same base variables (names and domains) as those used to construct this learner; mismatches throw at learn time.
Score selection (applied to all internal learners)
KTBNLearner< GUM_SCALAR > & useScoreAIC () override
 Returns a warning string if the current score and prior are incompatible, empty string otherwise.
KTBNLearner< GUM_SCALAR > & useScoreBD () override
 Returns a warning string if the current score and prior are incompatible, empty string otherwise.
KTBNLearner< GUM_SCALAR > & useScoreBDeu () override
 Returns a warning string if the current score and prior are incompatible, empty string otherwise.
KTBNLearner< GUM_SCALAR > & useScoreBIC () override
 Returns a warning string if the current score and prior are incompatible, empty string otherwise.
KTBNLearner< GUM_SCALAR > & useScoreLog2Likelihood () override
 Returns a warning string if the current score and prior are incompatible, empty string otherwise.
KTBNLearner< GUM_SCALAR > & useScoreMDL () override
 Returns a warning string if the current score and prior are incompatible, empty string otherwise.
void useScorefNML () override
 Returns a warning string if the current score and prior are incompatible, empty string otherwise.
std::string checkScorePriorCompatibility () const
 Returns a warning string if the current score and prior are incompatible, empty string otherwise.
Algorithm selection (applied to all internal learners)
KTBNLearner< GUM_SCALAR > & useGreedyHillClimbing () override
 the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNLearner< GUM_SCALAR > & useExtendedGreedyHillClimbing () override
 the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNLearner< GUM_SCALAR > & useLocalSearchWithTabuList (Size tabu_size, Size nb_decrease) override
 the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNLearner< GUM_SCALAR > & useLocalSearchWithTabuList ()
 the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNLearner< GUM_SCALAR > & useLocalSearchWithTabuList (Size tabu_size)
 the default number of decreasing changes (key tabuNbDecrease)
KTBNLearner< GUM_SCALAR > & useMIIC () override
 the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNLearner< GUM_SCALAR > & useGreedyThickThinning () override
 the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNLearner< GUM_SCALAR > & usePC () override
 the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNLearner< GUM_SCALAR > & useFCI () override
 the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
MIIC correction (applied to all internal learners)
KTBNLearner< GUM_SCALAR > & useNMLCorrection () override
 Engine-name pairs (tail, head) of arcs flagged as hiding a latent variable by MIIC (merged from all internal learners). Returned as names rather than Arc/NodeId pairs because the internal learners live in independent NodeId spaces, so a bare NodeId would be ambiguous.
KTBNLearner< GUM_SCALAR > & useMDLCorrection () override
 Engine-name pairs (tail, head) of arcs flagged as hiding a latent variable by MIIC (merged from all internal learners). Returned as names rather than Arc/NodeId pairs because the internal learners live in independent NodeId spaces, so a bare NodeId would be ambiguous.
KTBNLearner< GUM_SCALAR > & useNoCorrection () override
 Engine-name pairs (tail, head) of arcs flagged as hiding a latent variable by MIIC (merged from all internal learners). Returned as names rather than Arc/NodeId pairs because the internal learners live in independent NodeId spaces, so a bare NodeId would be ambiguous.
std::vector< std::pair< std::string, std::string > > latentVariables () const
 Engine-name pairs (tail, head) of arcs flagged as hiding a latent variable by MIIC (merged from all internal learners). Returned as names rather than Arc/NodeId pairs because the internal learners live in independent NodeId spaces, so a bare NodeId would be ambiguous.
Prior selection (applied to all internal learners)
KTBNLearner< GUM_SCALAR > & useSmoothingPrior (double weight) override
 the default weight (key priorWeight of the section learning)
KTBNLearner< GUM_SCALAR > & useSmoothingPrior ()
 the default weight (key priorWeight of the section learning)
Structural constraints (base names, translated to the relevant internal learner(s))
KTBNLearner< GUM_SCALAR > & addForbiddenArc (std::string_view tailNode, std::string_view headNode) override
 Forbid tailNode from ever parenting headNode (engine names, e.g. "X[1]", "C").
KTBNLearner< GUM_SCALAR > & addForbiddenArc (std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice) override
 Forbid one (base, slice) -> (base, slice) arc (KTBN::ATEMPORAL for static). A backward arc (tailSlice > headSlice) is accepted but has no effect: such an arc is already impossible, so forbidding it is a harmless no-op.
KTBNLearner< GUM_SCALAR > & eraseForbiddenArc (std::string_view tailNode, std::string_view headNode) override
 Undo a previous addForbiddenArc (engine names, e.g. "X[1]", "C").
KTBNLearner< GUM_SCALAR > & eraseForbiddenArc (std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice) override
 Undo a previous addForbiddenArc for a specific (base, slice) pair.
KTBNLearner< GUM_SCALAR > & addMandatoryArc (std::string_view tailNode, std::string_view headNode) override
 Force tailNode to be a parent of headNode (engine names, e.g. "X[1]", "C").
KTBNLearner< GUM_SCALAR > & addMandatoryArc (std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice) override
 Force one arc, lag stated explicitly via slices (KTBN::ATEMPORAL for static).
KTBNLearner< GUM_SCALAR > & eraseMandatoryArc (std::string_view tailNode, std::string_view headNode) override
 Undo a previous addMandatoryArc (engine names, e.g. "X[1]", "C").
KTBNLearner< GUM_SCALAR > & eraseMandatoryArc (std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice) override
 Undo a previous addMandatoryArc.
KTBNLearner< GUM_SCALAR > & addForbiddenIntraSliceArc (std::string_view tailBase, std::string_view headBase) override
 Forbid tailBase -> headBase at every intra-slice position (i.e. tailBase[t] -> headBase[t] for all t in [0, k-1]).
KTBNLearner< GUM_SCALAR > & eraseForbiddenIntraSliceArc (std::string_view tailBase, std::string_view headBase) override
 Undo a previous addForbiddenIntraSliceArc.
KTBNLearner< GUM_SCALAR > & addForbiddenArcAllSlices (std::string_view tailBase, std::string_view headBase) override
 Forbid tailBase -> headBase at every causally-possible slice pair (every lag, not just matching slices): tailBase can never be an ancestor of headBase in the learned k-TBN. A temporal->atemporal pair is a no-op (already structurally impossible).
KTBNLearner< GUM_SCALAR > & eraseForbiddenArcAllSlices (std::string_view tailBase, std::string_view headBase) override
 Undo a previous addForbiddenArcAllSlices.
KTBNLearner< GUM_SCALAR > & addNoParentNode (std::string_view base, int slice) override
 Declare a single (base, slice) node as a root (no parents).
KTBNLearner< GUM_SCALAR > & addNoParentNode (std::string_view name) override
 Declare a single node (bracket notation, e.g. "X[2]" or "C") as a root.
KTBNLearner< GUM_SCALAR > & eraseNoParentNode (std::string_view base, int slice) override
 Undo a previous addNoParentNode for a single (base, slice) node.
KTBNLearner< GUM_SCALAR > & eraseNoParentNode (std::string_view name) override
 Undo addNoParentNode for a node given by bracket notation.
KTBNLearner< GUM_SCALAR > & addNoChildrenNode (std::string_view base, int slice) override
 Declare a single (base, slice) node as a leaf (no children).
KTBNLearner< GUM_SCALAR > & addNoChildrenNode (std::string_view name) override
 Declare a single node (bracket notation, e.g. "X[2]" or "C") as a leaf.
KTBNLearner< GUM_SCALAR > & eraseNoChildrenNode (std::string_view base, int slice) override
 Undo a previous addNoChildrenNode for a single (base, slice) node.
KTBNLearner< GUM_SCALAR > & eraseNoChildrenNode (std::string_view name) override
 Undo addNoChildrenNode for a node given by bracket notation.
KTBNLearner< GUM_SCALAR > & addPossibleEdge (std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice) override
 Add a candidate edge for MIIC (only edges explicitly listed are explored).
KTBNLearner< GUM_SCALAR > & addPossibleEdge (std::string_view tail, std::string_view head) override
 Add a candidate edge for MIIC using engine names (e.g. "X[1]", "C").
KTBNLearner< GUM_SCALAR > & erasePossibleEdge (std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice) override
 Undo a previous addPossibleEdge.
KTBNLearner< GUM_SCALAR > & erasePossibleEdge (std::string_view tail, std::string_view head) override
 Undo a previous addPossibleEdge using engine names (e.g. "X[1]", "C").
KTBNLearner< GUM_SCALAR > & allowArcAdditions (bool allow=true) override
 Allow or forbid arc additions during structure search.
KTBNLearner< GUM_SCALAR > & allowArcDeletions (bool allow=true) override
 Allow or forbid arc deletions during structure search.
KTBNLearner< GUM_SCALAR > & allowArcReversals (bool allow=true) override
 Allow or forbid arc reversals during structure search.
KTBNLearner< GUM_SCALAR > & setMaxIndegree (Size max_indegree) override
 Cap the number of parents of any single node.
Diagnostics
Size k () const
 Order \(k\) of the k-TBN being learned.
Size nbCols () const
 Number of columns in each CSV, i.e. of base variables (temporal + atemporal).
std::vector< Size > nbRows () const
 Number of time steps in each trajectory CSV (one entry per sample, in load order). This is the raw trajectory length; the transition table's sliding-window row count for trajectory i is nbRows()[i] - k + 1.
bool isConstraintBased () const
 True if the current structure-learning algorithm is constraint-based (e.g. MIIC).
bool isScoreBased () const
 True if the current structure-learning algorithm is score-based (e.g. BIC, AIC).
std::string toString () const
 Human-readable summary of the learner's current configuration.
std::vector< std::tuple< std::string, std::string, std::string > > state () const
 Settings as a vector of (key, value, comment) tuples (mirrors BNLearner::state()).
void copyState (const KTBNLearner< GUM_SCALAR > &learner)
 Copy all score/algorithm/prior/constraint settings from another KTBNLearner (does not copy the database).
Database accessors
Size nbSamples () const
 Number of trajectory CSV files loaded (the constructor's nbSamples).
bool hasMissingValues () const
 True if any internal database contains missing values.
Size nbDroppedRows () const
 Number of rows dropped from the internal databases because they carried a missing symbol.
bool isIgnoringMissingSymbols () const
 Whether build() drops the rows carrying a missing symbol.
std::vector< std::string > names () const
 Base names (no slice suffix), one entry per base variable (temporal or atemporal), in the original CSV header order.
std::vector< std::size_t > domainSizes () const
 Domain sizes of the base variables, in the same column order as names().
Size domainSize (std::string_view base) const
 Domain size of the base variable base (e.g. "X", "C"). Engine names (e.g. "X[1]") are also accepted.

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

template<class F>
void _forEachLearner_ (F &&f)
 Apply f to each present internal learner (the atemporal one only when it exists). Factors out the fan-out shared by every score / algorithm / prior / correction / graph-change setter.
template<class F>
void _forOwningLearner_ (std::string_view tail, std::string_view head, F &&f)
 Apply f to the ONE internal learner that can learn the arc tail -> head, chosen by its head: a slice-(k-1) head belongs to the transition learner, an atemporal->atemporal arc to the atemporal learner, any other head (a past temporal slice) to the initial learner. The three cases are exclusive because build() forces every other node root in the learners that do not own it, so no arc is ever learnable in two of them.
template<class F>
void _forEachAllSlicesPair_ (std::string_view tailBase, std::string_view headBase, F &&f) const
 Apply f(tailSlice, headSlice) to every causally-possible slice pair of an all-slices constraint between tailBase and headBase. Four shapes: atemporal->atemporal is one pair; an atemporal tail reaches every slice of the head; a temporal tail into an atemporal head is structurally impossible and yields none; two temporal bases give every pair with tailSlice <= headSlice, i.e. every lag.
void _build_ (std::string_view dirPath, std::string_view csvBaseName, Size nbSamples, const std::vector< std::string > &missingSymbols)
 reads every trajectory, builds the three DatabaseTables (sliding window, initial-slice flattening, atemporal columns), constructs the BNLearners from them and applies the automatic temporal constraints (slice order, root past slices, temporal->atemporal forbids). Relies solely on prior_ktbn (already fully populated by the time it runs): the column order is read from the first trajectory's header and the atemporal columns are derived from prior_ktbn.atemporalVarNames(). Shared by both constructors.
const std::unordered_set< std::string > & _atemporalVarNames_ () const override
 atemporal base names for IKTBNLearner's shared encode/_determineNode_; read straight from the prior k-TBN (the single source of truth).
bool _isKnownBase_ (std::string_view base) const override
 whether base is one of this learner's variables; read straight from the prior k-TBN, like atemporalVarNames() above.
KTBN< GUM_SCALAR > _assemble_ (const BayesNet< GUM_SCALAR > &transitionBN, const BayesNet< GUM_SCALAR > &initialBN, const BayesNet< GUM_SCALAR > &atemporalBN) const
 glues the three parameter-learned BNs into a single k-TBN
 KTBNLearner (const KTBNLearner< GUM_SCALAR > &)=delete
 KTBNLearner (KTBNLearner< GUM_SCALAR > &&)=delete
KTBNLearner< GUM_SCALAR > & operator= (const KTBNLearner< GUM_SCALAR > &)=delete
KTBNLearner< GUM_SCALAR > & operator= (KTBNLearner< 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 k, const std::vector< std::string > &missingSymbols)
 checks k >= 2, then delegates the actual scan to the shared IKTBNLearner::scanConstantColumns() (also used by KTBNAdaptiveLearner, hence not duplicated here). The check happens first and here, not inside the shared scan: called once, in the member-initialiser list of the atemporal-inferring constructor, before prior_ktbn exists — before that constructor's body runs the equivalent check in buildPriorFromCSV — so without it here too, a bad k would only be caught after a wasted scan of every trajectory.
static KTBN< GUM_SCALAR > _buildPriorFromCSV_ (std::string_view dirPath, std::string_view csvBaseName, Size k, const std::unordered_set< std::string > &atemporalVars, const std::vector< std::string > &missingSymbols, bool induceTypes)
 called in the member-initialiser list of the k-CSV constructor: opens the first trajectory CSV, uses a temporary BNLearner to type the base variables (induceTypes promotes numeric columns to range/integer), builds and returns a KTBN with the right temporal/atemporal classification. Must be static because it is called before the object exists.
static KTBN< GUM_SCALAR > _buildPriorFromBN_ (Size k, const BayesNet< GUM_SCALAR > &bn, const std::unordered_set< std::string > &atemporalVars)
 called in the member-initialiser list of the BN constructor: builds and returns a KTBN whose variables are copied from bn (one node per base variable, right types/domains) and classified as temporal/atemporal according to atemporalVars. Must be static because it is called before the object exists.

Private Attributes

std::unique_ptr< BNLearner< GUM_SCALAR > > _transitionLearner_
 learns the transition kernel (arcs arriving at slice k-1)
std::unique_ptr< BNLearner< GUM_SCALAR > > _initialLearner_
 learns the initial slices 0..k-2
std::unique_ptr< BNLearner< GUM_SCALAR > > _atemporalLearner_
 learns the atemporal variables (arcs atemporal -> atemporal)
bool _ignoreMissingSymbols_ {false}
 prior k-TBN: the single source of truth for k, variable domains, temporal/atemporal classification and engine names. Everything else (base lists, column names) is derived from it on demand. Analogous to the prior BayesNet stored in BNLearner when a reference BN is given. whether build() drops incomplete rows rather than refusing the data
KTBN< GUM_SCALAR > _prior_ktbn_
Size _nbDroppedRows_ {0}
 number of time steps (rows) in each trajectory CSV, in load order. rows build() dropped because they carried a missing symbol
std::vector< Size > _nbTimeSlices_
 Captured once by build() and exposed by nbRows(). This is the raw trajectory length, not the sliding-window row count of the transition table (which is nbTimeSlices[i] - k + 1 summed over trajectories).
Size _nbTemporalPossibleEdges_ = 0
 counts of currently-active possible edges, split by kind: edges with at least one temporal endpoint, and edges between two atemporal variables. Maintained by add/erasePossibleEdge(). When a whitelist is active (temporal count > 0) but no atemporal->atemporal edge is whitelisted, the atemporal learner would otherwise stay unrestricted; learnKTBN() then suppresses it so the whitelist is honoured (no atemporal arc is produced).
Size _nbAtemporalPossibleEdges_ = 0

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::KTBNLearner< GUM_SCALAR >

Learns a k-TBN (structure and/or parameters) from trajectory CSVs.

See also
gum::learning::BNLearner, the static Bayesian-network counterpart whose API this class mirrors. KTBNLearner delegates score / algorithm / prior / constraint settings to three internal BNLearner instances (one per table).

Implements gum::learning::IKTBNLearner, the configuration interface shared with gum::learning::KTBNAdaptiveLearner (which learns k as well): here the setters apply each setting to the internal learners immediately, since k is fixed at construction.

Definition at line 115 of file KTBNLearner.h.

Constructor & Destructor Documentation

◆ KTBNLearner() [1/5]

template<GUM_Numeric GUM_SCALAR>
gum::learning::KTBNLearner< GUM_SCALAR >::KTBNLearner ( std::string_view dirPath,
std::string_view csvBaseName,
Size nbSamples,
Size k,
const std::unordered_set< std::string > & atemporalVars,
const std::vector< std::string > & missingSymbols = {"?"},
bool induceTypes = true,
bool ignoreMissingSymbols = false )

Structure-learning constructor — variable roles supplied explicitly.

Use this constructor when you want to learn the k-TBN structure from the data. The order \(k\) and the atemporal variable list must be given because they cannot be reliably inferred from the CSVs alone. Variable domains (modality counts) are read from the CSV data.

Internally calls _buildPriorFromCSV_() then _build_().

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.
kOrder of the k-TBN. Must be \(\geq 2\).
atemporalVarsBase names of the atemporal (static) variables. All other variables found in the CSV header are treated as temporal. 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 gum::learning::BNLearner.
ignoreMissingSymbolsWhen true, a row carrying a missing symbol is dropped rather than handed to the internal learners, which cannot cope with one (see nbDroppedRows() and its warning on the distortion this introduces). When false (the default), such data is refused outright.
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 132 of file KTBNLearner_tpl.h.

139 :
142 k,
145 induceTypes)) {
146 // k >= 2 is already enforced by _buildPriorFromCSV_ during member initialisation
147 if (nbSamples == 0) GUM_ERROR(InvalidArgument, "KTBNLearner needs at least one sample")
149 try {
151 } catch (const gum::UnknownLabelInDatabase&) {
152 // Domains are inferred from trajectory 1 alone, so a variable whose full
153 // domain is absent there fails once a later trajectory shows a new label.
154 // Atemporal variables are the usual culprits: constant within a trajectory,
155 // they reveal only one value per file. Re-throw with a KTBN-specific hint.
158 "KTBNLearner CSV constructor: an unknown label was encountered while "
159 "reading the trajectory CSVs. The variable domains are inferred from "
160 "the first CSV alone, so any variable whose modalities are not all "
161 "present in trajectory 1 will trigger this error (atemporal variables "
162 "are especially prone: each trajectory holds a single constant value "
163 "for them, so at most one label appears in trajectory 1). "
164 "Use the BN-schema constructor "
165 "KTBNLearner(dir, base, n, k, bn, atemporals) to supply the full "
166 "variable domains explicitly.")
167 } catch (...) {
169 throw;
170 }
171 }
Learns a k-TBN (structure and/or parameters) from trajectory CSVs.
static KTBN< GUM_SCALAR > _buildPriorFromCSV_(std::string_view dirPath, std::string_view csvBaseName, Size k, const std::unordered_set< std::string > &atemporalVars, const std::vector< std::string > &missingSymbols, bool induceTypes)
called in the member-initialiser list of the k-CSV constructor: opens the first trajectory CSV,...
void _build_(std::string_view dirPath, std::string_view csvBaseName, Size nbSamples, const std::vector< std::string > &missingSymbols)
reads every trajectory, builds the three DatabaseTables (sliding window, initial-slice flattening,...
bool _ignoreMissingSymbols_
prior k-TBN: the single source of truth for k, variable domains, temporal/atemporal classification an...
Size nbSamples() const
Number of trajectory CSV files loaded (the constructor's nbSamples).
KTBN< GUM_SCALAR > _prior_ktbn_
KTBNLearner(std::string_view dirPath, std::string_view csvBaseName, Size nbSamples, Size k, const std::unordered_set< std::string > &atemporalVars, const std::vector< std::string > &missingSymbols={"?"}, bool induceTypes=true, bool ignoreMissingSymbols=false)
Structure-learning constructor — variable roles supplied explicitly.
Size k() const
Order of the k-TBN being learned.

References KTBNLearner(), _build_(), _buildPriorFromCSV_(), _ignoreMissingSymbols_, _prior_ktbn_, GUM_ERROR, k(), and nbSamples().

Referenced by KTBNLearner(), KTBNLearner(), KTBNLearner(), KTBNLearner(), KTBNLearner(), ~KTBNLearner(), addForbiddenArc(), addForbiddenArc(), addMandatoryArc(), addMandatoryArc(), addNoChildrenNode(), addNoChildrenNode(), addNoParentNode(), addNoParentNode(), addPossibleEdge(), addPossibleEdge(), allowArcAdditions(), allowArcDeletions(), allowArcReversals(), copyState(), eraseForbiddenArc(), eraseMandatoryArc(), eraseNoChildrenNode(), eraseNoChildrenNode(), eraseNoParentNode(), eraseNoParentNode(), erasePossibleEdge(), erasePossibleEdge(), operator=(), operator=(), setMaxIndegree(), useExtendedGreedyHillClimbing(), useFCI(), useGreedyHillClimbing(), useGreedyThickThinning(), useLocalSearchWithTabuList(), useLocalSearchWithTabuList(), useMDLCorrection(), useMIIC(), useNMLCorrection(), useNoCorrection(), usePC(), useScoreAIC(), useScoreBD(), useScoreBDeu(), useScoreBIC(), useScoreLog2Likelihood(), useScoreMDL(), useSmoothingPrior(), and useSmoothingPrior().

Here is the call graph for this function:

◆ KTBNLearner() [2/5]

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

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

Same as the explicit-atemporalVars constructor, except the temporal/atemporal classification is inferred instead of supplied: a base variable is classified atemporal iff its value never changes across the rows of any single trajectory. It may still differ between trajectories — this matches the model's actual semantics (constant through time, not constant across samples) rather than requiring one global value, e.g. a per-individual static covariate such as an age or a site identifier. A column with too few non-missing values to ever witness a change is optimistically classified atemporal.

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

Warning
Variable domains are still discovered from trajectory 1 alone (see the explicit-atemporalVars constructor). An inferred atemporal variable is, by construction, one whose value may vary between trajectories — exactly the case most likely to reveal only one of several modalities in trajectory 1 and later throw UnknownLabelInDatabase. Use the BN-schema constructor if the full domain cannot be guaranteed present in the first trajectory.
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.
kOrder of the k-TBN. 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.
ignoreMissingSymbolsWhen true, a row carrying a missing symbol is dropped rather than handed to the internal learners, which cannot cope with one (see nbDroppedRows() and its warning on the distortion this introduces). When false (the default), such data is refused outright.

Definition at line 174 of file KTBNLearner_tpl.h.

180 :
181 // _inferAtemporalVars_ checks k>=2 itself, before opening anything (see
182 // its declaration) — this initialiser-list call runs before the
183 // delegated-to constructor's own body, so that check cannot be left to
184 // _buildPriorFromCSV_ the way the explicit constructor leaves it.
185 // Delegates to the explicit-atemporalVars constructor for the rest
186 // (including the UnknownLabelInDatabase hint); _inferAtemporalVars_
187 // needs nbSamples, unlike _buildPriorFromCSV_, since one trajectory
188 // alone cannot show that a value stays constant.
191 nbSamples,
192 k,
static std::unordered_set< std::string > _inferAtemporalVars_(std::string_view dirPath, std::string_view csvBaseName, Size nbSamples, Size k, const std::vector< std::string > &missingSymbols)
checks k >= 2, then delegates the actual scan to the shared IKTBNLearner::scanConstantColumns() (also...

References KTBNLearner(), _inferAtemporalVars_(), k(), and nbSamples().

Here is the call graph for this function:

◆ KTBNLearner() [3/5]

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

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

Use this constructor when the variable types and domains are already known (e.g. from a reference BN). The BN must contain exactly one node per base variable (temporal or atemporal), with the correct DiscreteVariable type and domain. Arcs in bn are ignored.

Internally calls _buildPriorFromBN_() then _build_().

Parameters
dirPathDirectory holding the trajectory CSV files.
csvBaseNameStem of each file name.
nbSamplesNumber of CSV files to read.
kOrder of the k-TBN. Must be \(\geq 2\).
bnA BayesNet with one node per base variable providing variable types and domains. Atemporal variables are identified by atemporalVars.
atemporalVarsBase names of the atemporal (static) variables present in bn.
missingSymbolsSymbols in the CSVs to interpret as missing values.
ignoreMissingSymbolsWhen true, a row carrying a missing symbol is dropped rather than handed to the internal learners, which cannot cope with one (see nbDroppedRows() and its warning on the distortion this introduces). When false (the default), such data is refused outright.

Definition at line 199 of file KTBNLearner_tpl.h.

206 :
209 // k >= 2 is already enforced by _buildPriorFromBN_ during member initialisation
210 if (nbSamples == 0) GUM_ERROR(InvalidArgument, "KTBNLearner needs at least one sample")
212 try {
214 } catch (...) {
216 throw;
217 }
218 }
static KTBN< GUM_SCALAR > _buildPriorFromBN_(Size k, const BayesNet< GUM_SCALAR > &bn, const std::unordered_set< std::string > &atemporalVars)
called in the member-initialiser list of the BN constructor: builds and returns a KTBN whose variable...

References KTBNLearner(), _build_(), _buildPriorFromBN_(), _ignoreMissingSymbols_, _prior_ktbn_, GUM_ERROR, k(), and nbSamples().

Here is the call graph for this function:

◆ ~KTBNLearner()

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

destructor

Definition at line 221 of file KTBNLearner_tpl.h.

221 {
223 }

References KTBNLearner().

Here is the call graph for this function:

◆ KTBNLearner() [4/5]

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

References KTBNLearner().

Here is the call graph for this function:

◆ KTBNLearner() [5/5]

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

References KTBNLearner().

Here is the call graph for this function:

Member Function Documentation

◆ _assemble_()

template<GUM_Numeric GUM_SCALAR>
KTBN< GUM_SCALAR > gum::learning::KTBNLearner< GUM_SCALAR >::_assemble_ ( const BayesNet< GUM_SCALAR > & transitionBN,
const BayesNet< GUM_SCALAR > & initialBN,
const BayesNet< GUM_SCALAR > & atemporalBN ) const
private

glues the three parameter-learned BNs into a single k-TBN

Definition at line 1347 of file KTBNLearner_tpl.h.

1349 {
1350 const int k = (int)_prior_ktbn_.k();
1351
1352 // 1. Base: initialBN provides slices 0..k-2 (temporal structure + CPTs, and
1353 // atemporal→temporal arcs). Atemporal variables enter only as forced roots;
1354 // steps 4 and 6 overwrite their mutual structure and CPTs from atemporalBN
1355 // (transitionBN repeats each atemporal value k-fold — not independent samples).
1357
1358 // 2. Add the slice k-1 variables from transitionBN (absent from initialBN).
1359 for (const auto& base: _prior_ktbn_.temporalVarNames()) {
1360 const std::string name = _encode_(base, k - 1);
1361 const NodeId transId = transitionBN.idFromName(name);
1362 bn.add(transitionBN.variable(transId));
1363 }
1364
1365 // 3. Add the arcs arriving at slice k-1 from transitionBN
1366 for (const auto& base: _prior_ktbn_.temporalVarNames()) {
1367 const std::string headName = _encode_(base, k - 1);
1368 const NodeId transHead = transitionBN.idFromName(headName);
1369 for (const NodeId transParent: transitionBN.parents(transHead)) {
1370 const std::string& parentName = transitionBN.variable(transParent).name();
1371 bn.addArc(parentName, headName);
1372 }
1373 }
1374
1375 // 4. Add the atemporal -> atemporal arcs from atemporalBN. Skipped when
1376 // atemporalBN is an empty placeholder: either <= 1 atemporal variable (no
1377 // learner is built, see _build_()) or the learner was suppressed by a
1378 // temporal-only possible-edge whitelist (see learnKTBN()). Either way the
1379 // atemporal variables already sit in bn as roots, via initialBN.
1380 if (atemporalBN.size() != 0) {
1381 for (const auto& atemBase: _prior_ktbn_.atemporalVarNames()) {
1382 const NodeId atemTail = atemporalBN.idFromName(atemBase);
1383 for (const NodeId atemChild: atemporalBN.children(atemTail)) {
1384 const std::string& childName = atemporalBN.variable(atemChild).name();
1385 bn.addArc(atemBase, childName);
1386 }
1387 }
1388 }
1389
1390 // 5. Fill the slice k-1 CPTs from transitionBN
1391 for (const auto& base: _prior_ktbn_.temporalVarNames()) {
1392 const std::string name = _encode_(base, k - 1);
1393 const NodeId bnId = bn.idFromName(name);
1394 const NodeId transId = transitionBN.idFromName(name);
1395 bn.cpt(bnId).fillWith(transitionBN.cpt(transId));
1396 }
1397
1398 // 6. Fill the atemporal CPTs from atemporalBN (same guard as step 4); when
1399 // skipped, the atemporal variables keep their initialBN marginal.
1400 if (atemporalBN.size() != 0) {
1401 for (const auto& atemBase: _prior_ktbn_.atemporalVarNames()) {
1402 const NodeId bnId = bn.idFromName(atemBase);
1403 const NodeId atemId = atemporalBN.idFromName(atemBase);
1404 bn.cpt(bnId).fillWith(atemporalBN.cpt(atemId));
1405 }
1406 }
1407
1408 // 7. Convert the assembled flat BN into a KTBN: fromBN infers k from the
1409 // highest bracket index and validates temporal causality.
1411 }
static KTBN< GUM_SCALAR > fromBN(const BayesNet< GUM_SCALAR > &bn, const std::unordered_set< std::string > &atemporalNodes={}, std::vector< std::string > *warnings=nullptr)
Builds a k-DBN from an existing gum::BayesNet, reading its node names under one of two mutually exclu...
Definition KTBN_tpl.h:881
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...

References gum::learning::IKTBNLearner< GUM_SCALAR >::_encode_(), _prior_ktbn_, gum::KTBN< GUM_SCALAR >::fromBN(), and k().

Referenced by learnKTBN(), and learnParameters().

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::KTBNLearner< GUM_SCALAR >::_atemporalVarNames_ ( ) const
overrideprivatevirtual

atemporal base names for IKTBNLearner's shared encode/_determineNode_; read straight from the prior k-TBN (the single source of truth).

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

Definition at line 1334 of file KTBNLearner_tpl.h.

1334 {
1335 return _prior_ktbn_.atemporalVarNames();
1336 }

References _prior_ktbn_.

◆ _build_()

template<GUM_Numeric GUM_SCALAR>
void gum::learning::KTBNLearner< GUM_SCALAR >::_build_ ( std::string_view dirPath,
std::string_view csvBaseName,
Size nbSamples,
const std::vector< std::string > & missingSymbols )
private

reads every trajectory, builds the three DatabaseTables (sliding window, initial-slice flattening, atemporal columns), constructs the BNLearners from them and applies the automatic temporal constraints (slice order, root past slices, temporal->atemporal forbids). Relies solely on prior_ktbn (already fully populated by the time it runs): the column order is read from the first trajectory's header and the atemporal columns are derived from prior_ktbn.atemporalVarNames(). Shared by both constructors.

Definition at line 1030 of file KTBNLearner_tpl.h.

1033 {
1034 Size k = _prior_ktbn_.k();
1035 Size nbTempVars = _prior_ktbn_.temporalVarNames().size();
1036 Size nbAtempVars = _prior_ktbn_.atemporalVarNames().size();
1037
1038 // tables are default-constructed here; translators are inserted per-column
1039 // in the i==0 block once the header (column order) is known
1043
1044 // Complete-case selection, at row granularity.
1045 //
1046 // aGrUM's structure learning refuses a database holding any missing value
1047 // outright (IBNLearner::learnDag_), so an incomplete row cannot simply be
1048 // handed over: learnKTBN() would throw on any trajectory with a gap. A row
1049 // that carries one is therefore dropped here, and everything downstream sees
1050 // a database with no missing value at all.
1051 //
1052 // This mirrors what the cross-k score already does per instance
1053 // (KTBNAdaptiveLearner::_forEachScoredNode_ skips any instance whose family
1054 // is not fully observed), so the two layers agree on which data counts.
1055 //
1056 // The unit differs per table: a transition row is a whole width-k window, so
1057 // one gap costs up to k windows; an initial or atemporal row is the whole
1058 // trajectory's contribution to that table.
1060 missingSymbols.end());
1063 for (const auto& cell: r)
1064 if (missingSet.contains(cell)) {
1066 return;
1067 }
1068 }
1069 table.insertRow(r);
1070 };
1071
1074
1078
1079 std::vector< std::string > header; // column order, captured from trajectory 1
1080 std::unordered_set< Size > atemVarsCols; // atemporal column indices
1081
1082 // reused across trajectories (capacity is kept between iterations)
1085 row.reserve(transRowSize);
1086 _nbTimeSlices_.reserve(nbSamples); // one raw length per trajectory (see nbRows())
1087
1088 for (Size i = 0; i < nbSamples; ++i) {
1089 // open the i-th trajectory (each file is opened exactly once)
1090 const std::filesystem::path file = dir / (stem + std::to_string(i + 1) + ".csv");
1092 if (!is.is_open()) GUM_ERROR(gum::IOError, "Cannot open " << file.string());
1093
1094 CSVParser parser(is, file.string());
1095 parser.next();
1096
1097 if (i == 0) {
1098 // first file only: capture the column order, derive the atemporal columns
1099 // from _prior_ktbn_, build the bracket-encoded names and finish setting up the
1100 // tables (must happen before any insertRow)
1101 const auto& rawHeader = parser.current();
1102 header.assign(rawHeader.begin(), rawHeader.end());
1103 for (std::size_t c = 0; c < header.size(); ++c)
1104 if (_prior_ktbn_.atemporalVarNames().contains(header[c])) atemVarsCols.insert(c);
1105
1106 // every schema variable must appear in the data, else _assemble_ (used
1107 // by both learnKTBN and learnParameters) would later fail with an
1108 // opaque NotFound when resolving bracket names
1109 {
1111 auto requirePresent = [&](const std::string& base) {
1112 if (!headerSet.contains(base))
1114 "schema variable '" << base << "' is absent from '" << file.string() << "'")
1115 };
1116 for (const auto& base: _prior_ktbn_.temporalVarNames())
1118 for (const auto& base: _prior_ktbn_.atemporalVarNames())
1120
1121 // conversely, every CSV column must be a known schema variable, else the
1122 // translator-insertion loop below would fail with an opaque NotFound
1123 // when resolving it against _prior_ktbn_
1124 for (const std::string& col: header)
1125 if (!_prior_ktbn_.exists(col))
1127 "CSV column '" << col << "' in '" << file.string()
1128 << "' is not declared as a variable of this KTBNLearner")
1129 }
1130
1131 // insert one translator per column into each table; every schema variable
1132 // has a concrete domain (user-supplied, or discovered by _buildPriorFromCSV_), so
1133 // insertTranslator picks the matching translator type from the variable.
1137 {
1138 auto insertTrans
1139 = [&](DatabaseTable& table, const std::string& base, int slice, std::size_t col) {
1140 table.insertTranslator(_prior_ktbn_.variable(base, slice), col, missingSymbols);
1141 };
1142
1143 // translators and their engine names are built in lockstep, column by
1144 // column, so a translator's table position and its name can never drift
1145 // apart (unlike keeping two separately-indexed passes in sync by hand).
1146 varNamesTran.reserve(transRowSize);
1147 varNamesInit.reserve(initRowSize);
1148 varNamesAtemp.reserve(atempRowSize);
1149
1150 std::size_t tcol = 0, icol = 0, acol = 0;
1151 for (std::size_t c = 0; c < header.size(); ++c) {
1152 const int slice = atemVarsCols.contains(c) ? KTBN< GUM_SCALAR >::ATEMPORAL : 0;
1154 varNamesTran.push_back(_encode_(header[c], slice));
1156 varNamesInit.push_back(_encode_(header[c], slice));
1157 if (atemVarsCols.contains(c)) {
1159 varNamesAtemp.push_back(header[c]);
1160 }
1161 }
1162 for (Size slice = 1; slice < k - 1; ++slice)
1163 for (std::size_t c = 0; c < header.size(); ++c)
1164 if (!atemVarsCols.contains(c)) {
1165 insertTrans(initTable, header[c], (int)slice, icol++);
1166 varNamesInit.push_back(_encode_(header[c], (int)slice));
1167 }
1168 for (Size slice = 1; slice < k; ++slice)
1169 for (std::size_t c = 0; c < header.size(); ++c)
1170 if (!atemVarsCols.contains(c)) {
1172 varNamesTran.push_back(_encode_(header[c], (int)slice));
1173 }
1174 }
1175
1176 transitionTable.setVariableNames(varNamesTran, false);
1177 initTable.setVariableNames(varNamesInit, false);
1178 atemporalTable.setVariableNames(varNamesAtemp, false);
1179 } else {
1180 // later files: validate the header against trajectory 1's without copying it
1181 const auto& raw = parser.current();
1182 bool same = (raw.size() == header.size());
1183 for (std::size_t c = 0; same && c < header.size(); ++c)
1184 same = (raw[c] == header[c]);
1185 if (!same)
1186 GUM_ERROR(InvalidArgument, "Header of " << file.string() << " differs from trajectory 1");
1187 }
1188
1189 buffer.clear();
1190 while (parser.next()) {
1191 const auto& tokens = parser.current();
1192 if (tokens.size() != header.size())
1194 "Trajectory " << (i + 1) << ", row " << parser.nbLine() << ": expected "
1195 << header.size() << " columns, got " << tokens.size());
1196 buffer.push_back({tokens.begin(), tokens.end()});
1197 }
1198
1199 if (buffer.size() < k)
1201 "Trajectory " << (i + 1) << " has " << buffer.size()
1202 << " time steps but at least k=" << k << " are required");
1203
1204 // record this trajectory's raw length (number of time steps), exposed by nbRows()
1205 _nbTimeSlices_.push_back(buffer.size());
1206
1207 // An atemporal column is constant down the trajectory, so any row carries
1208 // its value -- but row 0's may be the missing one, and reading row 0 blindly
1209 // would then drop every row this trajectory feeds. Resolve each once, from
1210 // its first non-missing occurrence. Same rule the score walk applies.
1212 for (const Size col: atemVarsCols)
1213 for (const auto& r: buffer)
1214 if (!missingSet.contains(r[col])) {
1215 atempValue[col] = r[col];
1216 break;
1217 }
1218
1219 // value of column col at time tt: the resolved constant for an atemporal
1220 // column, the row's own cell for a temporal one. A column missing all the
1221 // way down has no resolved value, so row 0's marker stands and the row is
1222 // dropped like any other incomplete one.
1223 const auto cellAt = [&](std::size_t tt, Size col) -> const std::string& {
1224 if (!atemVarsCols.contains(col)) return buffer[tt][col];
1225 const auto it = atempValue.find(col);
1226 return (it == atempValue.end()) ? buffer[0][col] : it->second;
1227 };
1228
1229 // transition table: sliding windows of width k
1230 for (std::size_t t = 0; t + k <= buffer.size(); ++t) {
1231 row.clear();
1232 // slice 0 carries the atemporal columns; later slices skip them so atemporal
1233 // variables aren't repeated k-1 times in each row
1234 for (Size col = 0; col < buffer[0].size(); ++col) {
1235 row.push_back(cellAt(t, col));
1236 }
1237 for (Size slice = 1; slice < k; ++slice) {
1238 for (Size col = 0; col < buffer[0].size(); ++col) {
1239 if (!atemVarsCols.contains(col)) { row.push_back(buffer[t + slice][col]); }
1240 }
1241 }
1243 }
1244
1245 // initial table: first k-1 slices, one row per trajectory
1246 row.clear();
1247 for (Size col = 0; col < buffer[0].size(); ++col) {
1248 row.push_back(cellAt(0, col));
1249 }
1250 for (Size slice = 1; slice < k - 1; ++slice) {
1251 for (Size col = 0; col < buffer[0].size(); ++col) {
1252 if (!atemVarsCols.contains(col)) { row.push_back(buffer[slice][col]); }
1253 }
1254 }
1256
1257 // atemporal table: one row per trajectory, atemporal columns only. Their
1258 // value is constant across the trajectory, so any time step works — take 0.
1259 // Skipped when fewer than 2 atemporal variables exist: a single atemporal
1260 // variable has no possible atemporal->atemporal arcs, so no learner is built.
1261 if (nbAtempVars > 1) {
1262 row.clear();
1263 for (Size col = 0; col < buffer[0].size(); ++col)
1264 if (atemVarsCols.contains(col)) row.push_back(cellAt(0, col));
1266 }
1267 }
1268
1269 // Dropping incomplete rows can empty a table outright -- every transition
1270 // window straddling a gap, or every trajectory's initial block incomplete.
1271 // The internal learner would then fail obscurely on an empty database, so
1272 // say what actually happened.
1275 "every row was dropped as incomplete ("
1277 << " in total): no fully observed transition window (or initial block) is left "
1278 "to learn from. The trajectories are too sparsely observed for k="
1279 << k << ".")
1280
1281 // Variables are already typed upstream (template / first-trajectory learner),
1282 // so no induceTypes pass is needed here — just canonicalize the value codes.
1285
1288
1289 if (nbAtempVars > 1) {
1290 atemporalTable.reorder();
1292 }
1293
1294
1295 // Impose k-TBN temporal constraints on structure learning:
1296 // - transition learner: past slices (0..k-2) are forced roots so only the
1297 // present slice (k-1) receives new arcs.
1298 // - atemporal variables are forced roots in transition/initial learners so
1299 // their mutual structure is learned exclusively by the atemporal learner.
1300 // No-parent in both learners covers every algorithm and also bans
1301 // temporal→atemporal arcs.
1302 // - initial learner: backward temporal arcs among past slices forbidden
1303 // explicitly (honoured by MIIC and score-based algorithms alike).
1304 // These constraints shape structure search in learnKTBN(); they are inert
1305 // for learnParameters.
1306 const int ki = (int)k;
1307 const auto& temporalVars = _prior_ktbn_.temporalVarNames();
1308 const auto& atemporalVars = _prior_ktbn_.atemporalVarNames();
1309
1310 for (const auto& base: temporalVars)
1311 for (int slice = 0; slice < ki - 1; ++slice)
1313
1314 for (const auto& atemBase: atemporalVars) {
1315 _transitionLearner_->addNoParentNode(atemBase);
1316 _initialLearner_->addNoParentNode(atemBase);
1317 }
1318
1319 if (k > 2) {
1320 // backward-in-time arcs among the past slices 0..k-2 are forbidden
1321 // explicitly: this is the only form MIIC honours (it ignores slice order),
1322 // and score-based algorithms respect it too, so it fully covers the
1323 // constraint. A setSliceOrder() mirror was dropped here as redundant.
1324 for (const auto& tailBase: temporalVars)
1325 for (const auto& headBase: temporalVars)
1326 for (int tailSlice = 1; tailSlice < ki - 1; ++tailSlice)
1327 for (int headSlice = 0; headSlice < tailSlice; ++headSlice)
1328 _initialLearner_->addForbiddenArc(_encode_(tailBase, tailSlice),
1330 }
1331 }
std::unique_ptr< BNLearner< GUM_SCALAR > > _initialLearner_
learns the initial slices 0..k-2
std::vector< Size > nbRows() const
Number of time steps in each trajectory CSV (one entry per sample, in load order)....
std::unique_ptr< BNLearner< GUM_SCALAR > > _transitionLearner_
learns the transition kernel (arcs arriving at slice k-1)
Size _nbDroppedRows_
number of time steps (rows) in each trajectory CSV, in load order. rows build() dropped because they ...
std::vector< Size > _nbTimeSlices_
Captured once by build() and exposed by nbRows(). This is the raw trajectory length,...
KTBNLearner< GUM_SCALAR > & addNoParentNode(std::string_view base, int slice) override
Declare a single (base, slice) node as a root (no parents).
std::unique_ptr< BNLearner< GUM_SCALAR > > _atemporalLearner_
learns the atemporal variables (arcs atemporal -> atemporal)

References _atemporalLearner_, gum::learning::IKTBNLearner< GUM_SCALAR >::_encode_(), _ignoreMissingSymbols_, _initialLearner_, _nbDroppedRows_, _nbTimeSlices_, _prior_ktbn_, _transitionLearner_, gum::KTBN< GUM_SCALAR >::ATEMPORAL, gum::learning::CSVParser::current(), GUM_ERROR, gum::learning::DatabaseTable::insertRow(), gum::learning::DatabaseTable::insertTranslator(), k(), gum::learning::CSVParser::nbLine(), gum::learning::IDatabaseTable< T_DATA >::nbRows(), nbSamples(), gum::learning::CSVParser::next(), gum::learning::DatabaseTable::reorder(), and gum::learning::DatabaseTable::setVariableNames().

Referenced by KTBNLearner(), and KTBNLearner().

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

◆ _buildPriorFromBN_()

template<GUM_Numeric GUM_SCALAR>
KTBN< GUM_SCALAR > gum::learning::KTBNLearner< GUM_SCALAR >::_buildPriorFromBN_ ( Size k,
const BayesNet< GUM_SCALAR > & bn,
const std::unordered_set< std::string > & atemporalVars )
staticprivate

called in the member-initialiser list of the BN constructor: builds and returns a KTBN whose variables are copied from bn (one node per base variable, right types/domains) and classified as temporal/atemporal according to atemporalVars. Must be static because it is called before the object exists.

Definition at line 1010 of file KTBNLearner_tpl.h.

1013 {
1015
1017 // bn.nodes() iterates in hash order (unspecified). This is harmless because
1018 // KTBN looks up variables by name, not by insertion index.
1019 for (const NodeId node: bn.nodes()) {
1020 const DiscreteVariable& var = bn.variable(node);
1021 prior.add(var, !atemporalVars.contains(var.name()));
1022 }
1023 for (const std::string& aname: atemporalVars)
1024 if (!prior.exists(aname))
1025 GUM_ERROR(InvalidArgument, "atemporal variable '" << aname << "' not found in the BN")
1026 return prior;
1027 }
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...

References gum::learning::IKTBNLearner< GUM_SCALAR >::_checkMinimalOrder_(), GUM_ERROR, k(), and gum::Variable::name().

Referenced by KTBNLearner().

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

◆ _buildPriorFromCSV_()

template<GUM_Numeric GUM_SCALAR>
KTBN< GUM_SCALAR > gum::learning::KTBNLearner< GUM_SCALAR >::_buildPriorFromCSV_ ( std::string_view dirPath,
std::string_view csvBaseName,
Size k,
const std::unordered_set< std::string > & atemporalVars,
const std::vector< std::string > & missingSymbols,
bool induceTypes )
staticprivate

called in the member-initialiser list of the k-CSV constructor: opens the first trajectory CSV, uses a temporary BNLearner to type the base variables (induceTypes promotes numeric columns to range/integer), builds and returns a KTBN with the right temporal/atemporal classification. Must be static because it is called before the object exists.

Definition at line 969 of file KTBNLearner_tpl.h.

975 {
977
978 namespace fs = std::filesystem;
980 = (fs::path{dirPath} / (std::string{csvBaseName} + "1.csv")).string();
981 // _build_() also reads trajectory 1 (its i=0 pass). The double-read is
982 // unavoidable: this function runs in the member-initialiser list, before
983 // the object (and hence _build_()) exists, and _build_() must read every
984 // trajectory.
985
986 // BNLearner construction runs induceTypes on the CSV and populates all
987 // column translators with properly-typed DiscreteVariables.
989
990 // Pull typed variables from the translator set. translatorSafe(i) bounds-checks,
991 // guarding against any names()/translator-set mismatch.
992 const DBTranslatorSet& translators = tmpLearner.database().translatorSet();
994
996 for (std::size_t i = 0; i < names.size(); ++i) {
997 prior.add(static_cast< const DiscreteVariable& >(*translators.translatorSafe(i).variable()),
998 !atemporalVars.contains(names[i]));
999 }
1000
1001 // Every declared atemporal name must appear in the CSV header.
1002 for (const std::string& aname: atemporalVars)
1003 if (!prior.exists(aname))
1005 "atemporal variable '" << aname << "' not found in the CSV header")
1006 return prior;
1007 }
std::vector< std::string > names() const
Base names (no slice suffix), one entry per base variable (temporal or atemporal),...

References gum::learning::IKTBNLearner< GUM_SCALAR >::_checkMinimalOrder_(), GUM_ERROR, k(), names(), gum::learning::DBTranslatorSet::translatorSafe(), and gum::learning::DBTranslator::variable().

Referenced by KTBNLearner().

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

◆ _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.
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...

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:

◆ _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:

◆ _forEachAllSlicesPair_()

template<GUM_Numeric GUM_SCALAR>
template<class F>
void gum::learning::KTBNLearner< GUM_SCALAR >::_forEachAllSlicesPair_ ( std::string_view tailBase,
std::string_view headBase,
F && f ) const
private

Apply f(tailSlice, headSlice) to every causally-possible slice pair of an all-slices constraint between tailBase and headBase. Four shapes: atemporal->atemporal is one pair; an atemporal tail reaches every slice of the head; a temporal tail into an atemporal head is structurally impossible and yields none; two temporal bases give every pair with tailSlice <= headSlice, i.e. every lag.

Validates that both bases exist – which the two callers used not to do, letting an unknown name reach a BNLearner as an opaque MissingVariableInDatabase – but deliberately NOT that they are temporal: an atemporal tail is one of the four shapes above.

Definition at line 96 of file KTBNLearner_tpl.h.

98 {
101 "unknown base variable '" << tailBase
102 << "': it is not one of this learner's variables")
105 "unknown base variable '" << headBase
106 << "': it is not one of this learner's variables")
107
109 const int k = static_cast< int >(_prior_ktbn_.k());
111 const bool headAtemp = _prior_ktbn_.atemporalVarNames().contains(std::string{headBase});
112
113 if (tailAtemp && headAtemp) {
114 f(AT, AT);
115 } else if (tailAtemp) {
116 for (int hs = 0; hs < k; ++hs)
117 f(AT, hs);
118 } else if (headAtemp) {
119 // temporal tail -> atemporal head is already structurally impossible
120 } else {
121 for (int ts = 0; ts < k; ++ts)
122 for (int hs = ts; hs < k; ++hs)
123 f(ts, hs);
124 }
125 }
bool _isKnownBase_(std::string_view base) const override
whether base is one of this learner's variables; read straight from the prior k-TBN,...

References _isKnownBase_(), _prior_ktbn_, gum::KTBN< GUM_SCALAR >::ATEMPORAL, GUM_ERROR, and k().

Referenced by addForbiddenArcAllSlices(), and eraseForbiddenArcAllSlices().

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

◆ _forEachLearner_()

template<GUM_Numeric GUM_SCALAR>
template<class F>
void gum::learning::KTBNLearner< GUM_SCALAR >::_forEachLearner_ ( F && f)
private

Apply f to each present internal learner (the atemporal one only when it exists). Factors out the fan-out shared by every score / algorithm / prior / correction / graph-change setter.

Definition at line 68 of file KTBNLearner_tpl.h.

References _atemporalLearner_, _initialLearner_, and _transitionLearner_.

Referenced by allowArcAdditions(), allowArcDeletions(), allowArcReversals(), setMaxIndegree(), useExtendedGreedyHillClimbing(), useFCI(), useGreedyHillClimbing(), useGreedyThickThinning(), useLocalSearchWithTabuList(), useMDLCorrection(), useMIIC(), useNMLCorrection(), useNoCorrection(), usePC(), useScoreAIC(), useScoreBD(), useScoreBDeu(), useScoreBIC(), useScorefNML(), useScoreLog2Likelihood(), useScoreMDL(), and useSmoothingPrior().

Here is the caller graph for this function:

◆ _forOwningLearner_()

template<GUM_Numeric GUM_SCALAR>
template<class F>
void gum::learning::KTBNLearner< GUM_SCALAR >::_forOwningLearner_ ( std::string_view tail,
std::string_view head,
F && f )
private

Apply f to the ONE internal learner that can learn the arc tail -> head, chosen by its head: a slice-(k-1) head belongs to the transition learner, an atemporal->atemporal arc to the atemporal learner, any other head (a past temporal slice) to the initial learner. The three cases are exclusive because build() forces every other node root in the learners that do not own it, so no arc is ever learnable in two of them.

The bothAtemp guard matters: without it an "X[0] -> C" arc would be routed to the atemporal learner, whose table has no X[0] column, and surface as MissingVariableInDatabase. It falls to the initial learner instead, where both endpoints exist and the arc is a harmless no-op.

Callers keep their own checkArcTemporallyFeasible call, which is deliberately asymmetric – forbidding an impossible arc is harmless while UN-forbidding it lifts an invariant, and forcing one must be refused while erasing a never-forced one is harmless – so it cannot be folded in here without flattening that asymmetry.

Definition at line 76 of file KTBNLearner_tpl.h.

78 {
79 const int last = static_cast< int >(_prior_ktbn_.k()) - 1;
86 else if (tailSlice != last) f(*_initialLearner_);
87 // else: the head is at a past slice but the tail sits on the kernel one,
88 // i.e. a backward arc. No table can hold it -- the initial one has no
89 // slice k-1 column -- and the k-TBN forbids it anyway, so there is
90 // nothing to constrain. Silently nothing, as the old broadcast did
91 // through its "tailSlice != last && headSlice != last" guard.
92 }

References _atemporalLearner_, gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _initialLearner_, _prior_ktbn_, _transitionLearner_, and gum::KTBN< GUM_SCALAR >::ATEMPORAL.

Referenced by addForbiddenArc(), addMandatoryArc(), eraseForbiddenArc(), and eraseMandatoryArc().

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::KTBNLearner< GUM_SCALAR >::_inferAtemporalVars_ ( std::string_view dirPath,
std::string_view csvBaseName,
Size nbSamples,
Size k,
const std::vector< std::string > & missingSymbols )
staticprivate

checks k >= 2, then delegates the actual scan to the shared IKTBNLearner::scanConstantColumns() (also used by KTBNAdaptiveLearner, hence not duplicated here). The check happens first and here, not inside the shared scan: called once, in the member-initialiser list of the atemporal-inferring constructor, before prior_ktbn exists — before that constructor's body runs the equivalent check in buildPriorFromCSV — so without it here too, a bad k would only be caught after a wasted scan of every trajectory.

Definition at line 955 of file KTBNLearner_tpl.h.

960 {
964 nbSamples,
966 }
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_(), k(), and nbSamples().

Referenced by KTBNLearner().

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::KTBNLearner< GUM_SCALAR >::_isKnownBase_ ( std::string_view base) const
overrideprivatevirtual

whether base is one of this learner's variables; read straight from the prior k-TBN, like atemporalVarNames() above.

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

Definition at line 1339 of file KTBNLearner_tpl.h.

1339 {
1340 const std::string b{base};
1341 return _prior_ktbn_.temporalVarNames().contains(b)
1342 || _prior_ktbn_.atemporalVarNames().contains(b);
1343 }

References _prior_ktbn_.

Referenced by _forEachAllSlicesPair_().

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:

◆ addForbiddenArc() [1/2]

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

Forbid one (base, slice) -> (base, slice) arc (KTBN::ATEMPORAL for static). A backward arc (tailSlice > headSlice) is accepted but has no effect: such an arc is already impossible, so forbidding it is a harmless no-op.

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

Definition at line 501 of file KTBNLearner_tpl.h.

504 {
505 // wrapper: encode (base, slice) -> engine name and delegate to the string overload
507 }
KTBNLearner< GUM_SCALAR > & addForbiddenArc(std::string_view tailNode, std::string_view headNode) override
Forbid tailNode from ever parenting headNode (engine names, e.g. "X[1]", "C").

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

Here is the call graph for this function:

◆ addForbiddenArc() [2/2]

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

Forbid tailNode from ever parenting headNode (engine names, e.g. "X[1]", "C").

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

Definition at line 492 of file KTBNLearner_tpl.h.

493 {
496 });
497 return *this;
498 }
void _forOwningLearner_(std::string_view tail, std::string_view head, F &&f)
Apply f to the ONE internal learner that can learn the arc tail -> head, chosen by its head: a slice-...

References KTBNLearner(), and _forOwningLearner_().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConstraints_(), addForbiddenArc(), addForbiddenArcAllSlices(), and addForbiddenIntraSliceArc().

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

◆ addForbiddenArcAllSlices()

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

Forbid tailBase -> headBase at every causally-possible slice pair (every lag, not just matching slices): tailBase can never be an ancestor of headBase in the learned k-TBN. A temporal->atemporal pair is a no-op (already structurally impossible).

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

Definition at line 603 of file KTBNLearner_tpl.h.

604 {
607 });
608 return *this;
609 }
void _forEachAllSlicesPair_(std::string_view tailBase, std::string_view headBase, F &&f) const
Apply f(tailSlice, headSlice) to every causally-possible slice pair of an all-slices constraint betwe...

References _forEachAllSlicesPair_(), and addForbiddenArc().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConstraints_().

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

◆ addForbiddenIntraSliceArc()

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

Forbid tailBase -> headBase at every intra-slice position (i.e. tailBase[t] -> headBase[t] for all t in [0, k-1]).

Exceptions
InvalidArgumentif either endpoint is unknown or atemporal (an atemporal variable has no intra-slice position).

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

Definition at line 577 of file KTBNLearner_tpl.h.

578 {
579 // validate both endpoints BEFORE touching any learner, so a rejected call
580 // leaves no partially-applied constraint behind
581 _checkBaseIsTemporal_(tailBase, "an intra-slice constraint");
582 _checkBaseIsTemporal_(headBase, "an intra-slice constraint");
583 const int k = static_cast< int >(_prior_ktbn_.k());
584 for (int t = 0; t < k; ++t)
586 return *this;
587 }
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_(), _prior_ktbn_, addForbiddenArc(), and k().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConstraints_().

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

◆ addMandatoryArc() [1/2]

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

Force one arc, lag stated explicitly via slices (KTBN::ATEMPORAL for static).

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

Definition at line 547 of file KTBNLearner_tpl.h.

550 {
551 // wrapper: encode (base, slice) -> engine name and delegate to the string overload
553 }
KTBNLearner< GUM_SCALAR > & addMandatoryArc(std::string_view tailNode, std::string_view headNode) override
Force tailNode to be a parent of headNode (engine names, e.g. "X[1]", "C").

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

Here is the call graph for this function:

◆ addMandatoryArc() [2/2]

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

Force tailNode to be a parent of headNode (engine names, e.g. "X[1]", "C").

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

Definition at line 531 of file KTBNLearner_tpl.h.

532 {
533 // Unlike forbidding, a mandatory arc must be feasible: reject up front the arcs
534 // the k-TBN can never contain (shared with eraseForbiddenArc) rather than
535 // letting them crash later in the wrong learner. Kept here, not in
536 // _forOwningLearner_: the check is deliberately asymmetric across the four
537 // setters (see its declaration).
538 _checkArcTemporallyFeasible_(tailNode, headNode, "force the mandatory arc");
539
542 });
543 return *this;
544 }
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 KTBNLearner(), gum::learning::IKTBNLearner< GUM_SCALAR >::_checkArcTemporallyFeasible_(), and _forOwningLearner_().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConstraints_(), and addMandatoryArc().

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

◆ addNoChildrenNode() [1/2]

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

Declare a single (base, slice) node as a leaf (no children).

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

Definition at line 663 of file KTBNLearner_tpl.h.

664 {
666 }
KTBNLearner< GUM_SCALAR > & addNoChildrenNode(std::string_view base, int slice) override
Declare a single (base, slice) node as a leaf (no children).

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

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConstraints_(), and 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>
KTBNLearner< GUM_SCALAR > & gum::learning::KTBNLearner< GUM_SCALAR >::addNoChildrenNode ( std::string_view name)
overridevirtual

Declare a single node (bracket notation, e.g. "X[2]" or "C") as a leaf.

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

Definition at line 669 of file KTBNLearner_tpl.h.

669 {
673 if (slice < (int)_prior_ktbn_.k() - 1) _initialLearner_->addNoChildrenNode(name);
674 if (isAtemp && _atemporalLearner_) _atemporalLearner_->addNoChildrenNode(name);
675 return *this;
676 }

References KTBNLearner(), _atemporalLearner_, gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _initialLearner_, _prior_ktbn_, _transitionLearner_, and gum::KTBN< GUM_SCALAR >::ATEMPORAL.

Here is the call graph for this function:

◆ addNoParentNode() [1/2]

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

Declare a single (base, slice) node as a root (no parents).

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

Definition at line 622 of file KTBNLearner_tpl.h.

623 {
625 }

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

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConstraints_(), and 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>
KTBNLearner< GUM_SCALAR > & gum::learning::KTBNLearner< GUM_SCALAR >::addNoParentNode ( std::string_view name)
overridevirtual

Declare a single node (bracket notation, e.g. "X[2]" or "C") as a root.

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

Definition at line 628 of file KTBNLearner_tpl.h.

628 {
632 // Atemporals are already forced roots in transition/initial learners by _build_.
633 // The user constraint is only meaningful in the atemporal learner.
634 _atemporalLearner_->addNoParentNode(name);
635 } else if (!isAtemp) {
636 _transitionLearner_->addNoParentNode(name);
637 if (slice < (int)_prior_ktbn_.k() - 1) _initialLearner_->addNoParentNode(name);
638 }
639 return *this;
640 }

References KTBNLearner(), _atemporalLearner_, gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _initialLearner_, _prior_ktbn_, _transitionLearner_, and gum::KTBN< GUM_SCALAR >::ATEMPORAL.

Here is the call graph for this function:

◆ addPossibleEdge() [1/2]

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

Add a candidate edge for MIIC using engine names (e.g. "X[1]", "C").

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

Definition at line 713 of file KTBNLearner_tpl.h.

714 {
715 const int last = (int)_prior_ktbn_.k() - 1;
718
719 // Atemporal names exist as forced roots in every table, so whitelisting them
720 // here too keeps the whole-model promise ("only listed edges are explored")
721 // even when the edge can fire in just one learner: the no-parent constraint
722 // on atemporal heads still vetoes it there (constraints compound, never
723 // override), so this can only shrink the candidate set, never widen it.
725 // forward to the initial learner only when both endpoints exist there, i.e. both
726 // are at a past slice (< k-1); atemporals (slice -1) satisfy this automatically.
727 if (tailSlice < last && headSlice < last) _initialLearner_->addPossibleEdge(tail, head);
728
731 if (_atemporalLearner_) _atemporalLearner_->addPossibleEdge(tail, head);
732 } else {
734 }
735 return *this;
736 }
Size _nbTemporalPossibleEdges_
counts of currently-active possible edges, split by kind: edges with at least one temporal endpoint,...
KTBNLearner< GUM_SCALAR > & addPossibleEdge(std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice) override
Add a candidate edge for MIIC (only edges explicitly listed are explored).

References KTBNLearner(), _atemporalLearner_, gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _initialLearner_, _nbAtemporalPossibleEdges_, _nbTemporalPossibleEdges_, _prior_ktbn_, _transitionLearner_, and gum::KTBN< GUM_SCALAR >::ATEMPORAL.

Here is the call graph for this function:

◆ addPossibleEdge() [2/2]

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

Add a candidate edge for MIIC (only edges explicitly listed are explored).

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

Definition at line 695 of file KTBNLearner_tpl.h.

698 {
699 // encode (base, slice) -> engine name and delegate to the string overload, which
700 // owns the full routing (atemporal->atemporal to the atemporal learner, slice-k-1 guard)
702 }

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

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConstraints_(), and addPossibleEdge().

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

◆ allowArcAdditions()

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

Allow or forbid arc additions during structure search.

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

Definition at line 758 of file KTBNLearner_tpl.h.

758 {
760 return *this;
761 }
void _forEachLearner_(F &&f)
Apply f to each present internal learner (the atemporal one only when it exists). Factors out the fan...
KTBNLearner< GUM_SCALAR > & allowArcAdditions(bool allow=true) override
Allow or forbid arc additions during structure search.

References KTBNLearner(), and _forEachLearner_().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConstraints_().

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

◆ allowArcDeletions()

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

Allow or forbid arc deletions during structure search.

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

Definition at line 764 of file KTBNLearner_tpl.h.

764 {
766 return *this;
767 }
KTBNLearner< GUM_SCALAR > & allowArcDeletions(bool allow=true) override
Allow or forbid arc deletions during structure search.

References KTBNLearner(), and _forEachLearner_().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConstraints_().

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

◆ allowArcReversals()

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

Allow or forbid arc reversals during structure search.

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

Definition at line 770 of file KTBNLearner_tpl.h.

770 {
772 return *this;
773 }
KTBNLearner< GUM_SCALAR > & allowArcReversals(bool allow=true) override
Allow or forbid arc reversals during structure search.

References KTBNLearner(), and _forEachLearner_().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConstraints_().

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

◆ checkScorePriorCompatibility()

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

Returns a warning string if the current score and prior are incompatible, empty string otherwise.

Definition at line 357 of file KTBNLearner_tpl.h.

357 {
358 // Every score/prior setter is applied uniformly to all internal learners, so
359 // their configurations are identical: a single check on the transition learner
360 // is representative of the whole KTBNLearner.
361 return _transitionLearner_->checkScorePriorCompatibility();
362 }

References _transitionLearner_.

◆ copyState()

template<GUM_Numeric GUM_SCALAR>
void gum::learning::KTBNLearner< GUM_SCALAR >::copyState ( const KTBNLearner< GUM_SCALAR > & learner)

Copy all score/algorithm/prior/constraint settings from another KTBNLearner (does not copy the database).

Definition at line 870 of file KTBNLearner_tpl.h.

870 {
871 // As in BNLearner::copyState, only score/algorithm/prior/constraint settings
872 // are copied, never the database. Both sides must be structurally compatible
873 // (same k, same temporal/atemporal partition) for the name-based constraints
874 // to mean the same thing. The atemporal learner is copied only when both
875 // sides have one (absent when there are <= 1 atemporal vars).
880
881 // KTBNLearner-only state (BNLearner::copyState can't carry it): learnKTBN reads
882 // these to suppress the atemporal learner under a temporal-only whitelist
885 }

References KTBNLearner(), _atemporalLearner_, _initialLearner_, _nbAtemporalPossibleEdges_, _nbTemporalPossibleEdges_, and _transitionLearner_.

Here is the call 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:

◆ domainSize()

template<GUM_Numeric GUM_SCALAR>
Size gum::learning::KTBNLearner< GUM_SCALAR >::domainSize ( std::string_view base) const

Domain size of the base variable base (e.g. "X", "C"). Engine names (e.g. "X[1]") are also accepted.

Note
KTBNLearner is deliberately name-only: it exposes no NodeId-based accessor (no domainSize(NodeId), idFromName or nameFromId). The three internal learners live in independent NodeId spaces, so a bare NodeId would be ambiguous — always address variables by name here.

Definition at line 938 of file KTBNLearner_tpl.h.

938 {
939 // Resolve the base name to an engine name in the transition table: a temporal
940 // variable is addressed at slice 0, everything else keeps its bare name (which
941 // also lets a raw engine name pass through). An unknown name reaches
942 // domainSize() unchanged and throws MissingVariableInDatabase.
943 const std::string b{base};
944 const int slice
945 = _prior_ktbn_.temporalVarNames().contains(b) ? 0 : KTBN< GUM_SCALAR >::ATEMPORAL;
947 }
Size domainSize(std::string_view base) const
Domain size of the base variable base (e.g. "X", "C"). Engine names (e.g. "X[1]") are also accepted.

References gum::learning::IKTBNLearner< GUM_SCALAR >::_encode_(), _prior_ktbn_, _transitionLearner_, and gum::KTBN< GUM_SCALAR >::ATEMPORAL.

Here is the call graph for this function:

◆ domainSizes()

template<GUM_Numeric GUM_SCALAR>
std::vector< Size > gum::learning::KTBNLearner< GUM_SCALAR >::domainSizes ( ) const

Domain sizes of the base variables, in the same column order as names().

Definition at line 930 of file KTBNLearner_tpl.h.

930 {
931 // Mirror names(): the first nbCols() columns are the base variables (a temporal
932 // variable's domain size is the same across all its slices), so keep only those.
933 const auto& all = _transitionLearner_->domainSizes();
934 return std::vector< Size >(all.begin(), all.begin() + nbCols());
935 }
Size nbCols() const
Number of columns in each CSV, i.e. of base variables (temporal + atemporal).
std::vector< std::size_t > domainSizes() const
Domain sizes of the base variables, in the same column order as names().

References _transitionLearner_, and nbCols().

Here is the call graph for this function:

◆ eraseForbiddenArc() [1/2]

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

Undo a previous addForbiddenArc for a specific (base, slice) pair.

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

Definition at line 523 of file KTBNLearner_tpl.h.

526 {
528 }
KTBNLearner< GUM_SCALAR > & eraseForbiddenArc(std::string_view tailNode, std::string_view headNode) override
Undo a previous addForbiddenArc (engine names, e.g. "X[1]", "C").

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

Here is the call graph for this function:

◆ eraseForbiddenArc() [2/2]

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

Undo a previous addForbiddenArc (engine names, e.g. "X[1]", "C").

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

Definition at line 511 of file KTBNLearner_tpl.h.

512 {
513 // refuse to lift an invariant the k-TBN definition enforces (shared with addMandatoryArc)
514 _checkArcTemporallyFeasible_(tailNode, headNode, "un-forbid the arc");
515
518 });
519 return *this;
520 }

References gum::learning::IKTBNLearner< GUM_SCALAR >::_checkArcTemporallyFeasible_(), and _forOwningLearner_().

Referenced by eraseForbiddenArc(), eraseForbiddenArcAllSlices(), and eraseForbiddenIntraSliceArc().

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

◆ eraseForbiddenArcAllSlices()

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

Undo a previous addForbiddenArcAllSlices.

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

Definition at line 613 of file KTBNLearner_tpl.h.

614 {
617 });
618 return *this;
619 }

References _forEachAllSlicesPair_(), and eraseForbiddenArc().

Here is the call graph for this function:

◆ eraseForbiddenIntraSliceArc()

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

Undo a previous addForbiddenIntraSliceArc.

Exceptions
InvalidArgumentunder the same conditions as addForbiddenIntraSliceArc.

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

Definition at line 591 of file KTBNLearner_tpl.h.

592 {
593 _checkBaseIsTemporal_(tailBase, "an intra-slice constraint");
594 _checkBaseIsTemporal_(headBase, "an intra-slice constraint");
595 const int k = static_cast< int >(_prior_ktbn_.k());
596 for (int t = 0; t < k; ++t)
598 return *this;
599 }

References gum::learning::IKTBNLearner< GUM_SCALAR >::_checkBaseIsTemporal_(), _prior_ktbn_, eraseForbiddenArc(), and k().

Here is the call graph for this function:

◆ eraseMandatoryArc() [1/2]

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

Undo a previous addMandatoryArc.

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

Definition at line 568 of file KTBNLearner_tpl.h.

571 {
573 }
KTBNLearner< GUM_SCALAR > & eraseMandatoryArc(std::string_view tailNode, std::string_view headNode) override
Undo a previous addMandatoryArc (engine names, e.g. "X[1]", "C").

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

Here is the call graph for this function:

◆ eraseMandatoryArc() [2/2]

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

Undo a previous addMandatoryArc (engine names, e.g. "X[1]", "C").

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

Definition at line 557 of file KTBNLearner_tpl.h.

558 {
559 // no feasibility check: a backward-in-time arc can never have been added, so
560 // erasing it is harmless -- it resolves to a no-op on the owning learner.
563 });
564 return *this;
565 }

References _forOwningLearner_().

Referenced by eraseMandatoryArc().

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

◆ eraseNoChildrenNode() [1/2]

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

Undo a previous addNoChildrenNode for a single (base, slice) node.

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

Definition at line 679 of file KTBNLearner_tpl.h.

680 {
682 }
KTBNLearner< GUM_SCALAR > & eraseNoChildrenNode(std::string_view base, int slice) override
Undo a previous addNoChildrenNode for a single (base, slice) node.

References KTBNLearner(), gum::learning::IKTBNLearner< GUM_SCALAR >::_encode_(), 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>
KTBNLearner< GUM_SCALAR > & gum::learning::KTBNLearner< GUM_SCALAR >::eraseNoChildrenNode ( std::string_view name)
overridevirtual

Undo addNoChildrenNode for a node given by bracket notation.

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

Definition at line 685 of file KTBNLearner_tpl.h.

685 {
689 if (slice < (int)_prior_ktbn_.k() - 1) _initialLearner_->eraseNoChildrenNode(name);
690 if (isAtemp && _atemporalLearner_) _atemporalLearner_->eraseNoChildrenNode(name);
691 return *this;
692 }

References KTBNLearner(), _atemporalLearner_, gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _initialLearner_, _prior_ktbn_, _transitionLearner_, and gum::KTBN< GUM_SCALAR >::ATEMPORAL.

Here is the call graph for this function:

◆ eraseNoParentNode() [1/2]

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

Undo a previous addNoParentNode for a single (base, slice) node.

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

Definition at line 643 of file KTBNLearner_tpl.h.

644 {
646 }
KTBNLearner< GUM_SCALAR > & eraseNoParentNode(std::string_view base, int slice) override
Undo a previous addNoParentNode for a single (base, slice) node.

References KTBNLearner(), gum::learning::IKTBNLearner< GUM_SCALAR >::_encode_(), 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>
KTBNLearner< GUM_SCALAR > & gum::learning::KTBNLearner< GUM_SCALAR >::eraseNoParentNode ( std::string_view name)
overridevirtual

Undo addNoParentNode for a node given by bracket notation.

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

Definition at line 649 of file KTBNLearner_tpl.h.

649 {
651 const int last = (int)_prior_ktbn_.k() - 1;
654 else if (slice == last) _transitionLearner_->eraseNoParentNode(name);
655 else if (!isAtemp)
656 // Past slices keep their transition-learner root constraint (confines learning
657 // to the kernel); only lift the constraint in the initial learner.
658 _initialLearner_->eraseNoParentNode(name);
659 return *this;
660 }

References KTBNLearner(), _atemporalLearner_, gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _initialLearner_, _prior_ktbn_, _transitionLearner_, and gum::KTBN< GUM_SCALAR >::ATEMPORAL.

Here is the call graph for this function:

◆ erasePossibleEdge() [1/2]

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

Undo a previous addPossibleEdge using engine names (e.g. "X[1]", "C").

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

Definition at line 739 of file KTBNLearner_tpl.h.

740 {
741 const int last = (int)_prior_ktbn_.k() - 1;
744
746 if (tailSlice < last && headSlice < last) _initialLearner_->erasePossibleEdge(tail, head);
747
750 if (_atemporalLearner_) _atemporalLearner_->erasePossibleEdge(tail, head);
751 } else {
753 }
754 return *this;
755 }
KTBNLearner< GUM_SCALAR > & erasePossibleEdge(std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice) override
Undo a previous addPossibleEdge.

References KTBNLearner(), _atemporalLearner_, gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _initialLearner_, _nbAtemporalPossibleEdges_, _nbTemporalPossibleEdges_, _prior_ktbn_, _transitionLearner_, and gum::KTBN< GUM_SCALAR >::ATEMPORAL.

Here is the call graph for this function:

◆ erasePossibleEdge() [2/2]

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

Undo a previous addPossibleEdge.

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

Definition at line 705 of file KTBNLearner_tpl.h.

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

Referenced by erasePossibleEdge().

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

◆ hasMissingValues()

template<GUM_Numeric GUM_SCALAR>
bool gum::learning::KTBNLearner< GUM_SCALAR >::hasMissingValues ( ) const

True if any internal database contains missing values.

Warning
Always false since build() performs complete-case selection: a row carrying a missing symbol is never inserted, so the databases hold no gap by construction. To learn whether the CSVs actually had any, read nbDroppedRows() instead.

Definition at line 909 of file KTBNLearner_tpl.h.

909 {
910 return _transitionLearner_->hasMissingValues() || _initialLearner_->hasMissingValues()
911 || (_atemporalLearner_ && _atemporalLearner_->hasMissingValues());
912 }

References _atemporalLearner_, _initialLearner_, and _transitionLearner_.

◆ isConstraintBased()

template<GUM_Numeric GUM_SCALAR>
bool gum::learning::KTBNLearner< GUM_SCALAR >::isConstraintBased ( ) const

True if the current structure-learning algorithm is constraint-based (e.g. MIIC).

Definition at line 804 of file KTBNLearner_tpl.h.

804 {
805 return _transitionLearner_->isConstraintBased();
806 }

References _transitionLearner_.

◆ isIgnoringMissingSymbols()

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

Whether build() drops the rows carrying a missing symbol.

See also
nbDroppedRows() for how much was dropped, and for the warning on the likelihood distortion this causes.

Definition at line 899 of file KTBNLearner_tpl.h.

899 {
901 }

References _ignoreMissingSymbols_.

◆ isScoreBased()

template<GUM_Numeric GUM_SCALAR>
bool gum::learning::KTBNLearner< GUM_SCALAR >::isScoreBased ( ) const

True if the current structure-learning algorithm is score-based (e.g. BIC, AIC).

Definition at line 809 of file KTBNLearner_tpl.h.

809 {
810 return _transitionLearner_->isScoreBased();
811 }

References _transitionLearner_.

◆ k()

template<GUM_Numeric GUM_SCALAR>
Size gum::learning::KTBNLearner< GUM_SCALAR >::k ( ) const

Order \(k\) of the k-TBN being learned.

Definition at line 786 of file KTBNLearner_tpl.h.

786 {
787 return _prior_ktbn_.k();
788 }

References _prior_ktbn_.

Referenced by KTBNLearner(), KTBNLearner(), KTBNLearner(), _assemble_(), _build_(), _buildPriorFromBN_(), _buildPriorFromCSV_(), _forEachAllSlicesPair_(), _inferAtemporalVars_(), addForbiddenIntraSliceArc(), eraseForbiddenIntraSliceArc(), learnParameters(), and toString().

Here is the caller graph for this function:

◆ latentVariables()

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

Engine-name pairs (tail, head) of arcs flagged as hiding a latent variable by MIIC (merged from all internal learners). Returned as names rather than Arc/NodeId pairs because the internal learners live in independent NodeId spaces, so a bare NodeId would be ambiguous.

Definition at line 448 of file KTBNLearner_tpl.h.

448 {
449 // Each learner reports latent arcs in its own NodeId space, so translate each
450 // Arc to an (engine-name, engine-name) pair before merging. A pair among
451 // slices 0..k-2 can be flagged by both the transition and the initial learner,
452 // so deduplicate on a tab-joined key (engine names never contain a tab).
453 // Propagates BNLearner's OperationNotAllowed if MIIC is not selected.
456
458 if (!learner) return;
459 for (const auto& arc: learner->latentVariables()) {
460 std::string tail = learner->nameFromId(arc.tail());
461 std::string head = learner->nameFromId(arc.head());
462 if (seen.insert(tail + '\t' + head).second)
463 result.emplace_back(std::move(tail), std::move(head));
464 }
465 };
469 return result;
470 }
std::vector< std::pair< std::string, std::string > > latentVariables() const
Engine-name pairs (tail, head) of arcs flagged as hiding a latent variable by MIIC (merged from all i...

References _atemporalLearner_, _initialLearner_, and _transitionLearner_.

◆ learnKTBN()

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

Full learning (structure + CPTs). Mirrors BNLearner::learnBN().

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

Definition at line 230 of file KTBNLearner_tpl.h.

230 {
231 // Honour the possible-edge whitelist for atemporal->atemporal arcs: when a
232 // whitelist is active (>=1 possible edge with a temporal endpoint) but no
233 // atemporal->atemporal edge was whitelisted, the atemporal learner has an
234 // empty (hence unrestricted) list. Skip it entirely so no atemporal arc is
235 // produced; _assemble_ then leaves the atemporal variables as roots.
236 const bool suppressAtemporal
241 ? _atemporalLearner_->learnBN()
244 }
KTBN< GUM_SCALAR > _assemble_(const BayesNet< GUM_SCALAR > &transitionBN, const BayesNet< GUM_SCALAR > &initialBN, const BayesNet< GUM_SCALAR > &atemporalBN) const
glues the three parameter-learned BNs into a single k-TBN

References _assemble_(), _atemporalLearner_, _initialLearner_, _nbAtemporalPossibleEdges_, _nbTemporalPossibleEdges_, and _transitionLearner_.

Here is the call graph for this function:

◆ learnParameters()

template<GUM_Numeric GUM_SCALAR>
KTBN< GUM_SCALAR > gum::learning::KTBNLearner< GUM_SCALAR >::learnParameters ( const KTBN< GUM_SCALAR > & structure,
bool takeIntoAccountScore = true )

CPTs only, using the arc structure of structure. structure must have the same base variables (names and domains) as those used to construct this learner; mismatches throw at learn time.

Definition at line 247 of file KTBNLearner_tpl.h.

248 {
249 if (structure.k() != _prior_ktbn_.k())
251 "learnParameters: structure has k="
252 << structure.k() << " but this learner was built with k=" << _prior_ktbn_.k())
253 const int k = (int)_prior_ktbn_.k();
254
255 // Build one DAG per internal table, in that table's own NodeId space, by
256 // routing each of structure's (base, slice) arcs to the table that owns its
257 // head: slice k-1 goes to the transition table, atemporal heads go to the
258 // atemporal table (guaranteed atemporal-tailed too — a temporal variable can
259 // never be a parent of an atemporal one), everything else (slices 0..k-2,
260 // whether the tail is temporal or atemporal) goes to the initial table.
264
266 for (std::size_t id = 0; id < nbTransNodes; ++id)
268
270 for (std::size_t id = 0; id < nbInitNodes; ++id)
272
275 for (std::size_t id = 0; id < nbAtemNodes; ++id)
276 atemporalDAG.addNodeWithId(NodeId(id));
277 }
278
279 for (const auto& [tail, head]: structure.arcs()) {
280 const auto& [tailBase, tailSlice] = tail;
281 const auto& [headBase, headSlice] = head;
284
285 if (headSlice == k - 1) {
286 transitionDAG.addArc(_transitionLearner_->idFromName(tailName),
287 _transitionLearner_->idFromName(headName));
290 atemporalDAG.addArc(_atemporalLearner_->idFromName(tailName),
291 _atemporalLearner_->idFromName(headName));
292 } else {
293 initialDAG.addArc(_initialLearner_->idFromName(tailName),
294 _initialLearner_->idFromName(headName));
295 }
296 }
297
306
308 }
KTBN< GUM_SCALAR > learnParameters(const KTBN< GUM_SCALAR > &structure, bool takeIntoAccountScore=true)
CPTs only, using the arc structure of structure. structure must have the same base variables (names a...

References _assemble_(), _atemporalLearner_, gum::learning::IKTBNLearner< GUM_SCALAR >::_encode_(), _initialLearner_, _prior_ktbn_, _transitionLearner_, gum::DAG::addArc(), gum::NodeGraphPart::addNodeWithId(), gum::KTBN< GUM_SCALAR >::ATEMPORAL, GUM_ERROR, and k().

Here is the call graph for this function:

◆ names()

template<GUM_Numeric GUM_SCALAR>
std::vector< std::string > gum::learning::KTBNLearner< GUM_SCALAR >::names ( ) const

Base names (no slice suffix), one entry per base variable (temporal or atemporal), in the original CSV header order.

Definition at line 915 of file KTBNLearner_tpl.h.

915 {
916 // The first nbCols() columns of the transition table are the base variables
917 // (slice-0 temporals then atemporals); the remaining columns are just later
918 // slices of those same temporals. So strip the slice suffix off the first
919 // nbCols() engine names to get each base variable exactly once.
920 const auto& engine = _transitionLearner_->names();
921 const Size n = nbCols();
923 result.reserve(n);
924 for (Size i = 0; i < n; ++i)
925 result.push_back(_determineNode_(engine[i]).first);
926 return result;
927 }

References gum::learning::IKTBNLearner< GUM_SCALAR >::_determineNode_(), _transitionLearner_, and nbCols().

Referenced by _buildPriorFromCSV_().

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

◆ nbCols()

template<GUM_Numeric GUM_SCALAR>
Size gum::learning::KTBNLearner< GUM_SCALAR >::nbCols ( ) const

Number of columns in each CSV, i.e. of base variables (temporal + atemporal).

Definition at line 791 of file KTBNLearner_tpl.h.

791 {
792 return _prior_ktbn_.nbTemporalVars() + _prior_ktbn_.nbAtemporalVars();
793 }

References _prior_ktbn_.

Referenced by domainSizes(), names(), and toString().

Here is the caller graph for this function:

◆ nbDroppedRows()

template<GUM_Numeric GUM_SCALAR>
INLINE Size gum::learning::KTBNLearner< GUM_SCALAR >::nbDroppedRows ( ) const

Number of rows dropped from the internal databases because they carried a missing symbol.

aGrUM's structure learning refuses a database holding any missing value (gum::learning::IBNLearner::learnDag_), so build() performs complete-case selection: a row is inserted only if every cell it needs is observed. This mirrors the cross-k score, which likewise skips any instance whose family is incomplete, so both layers agree on which data counts. hasMissingValues() is consequently always false.

The unit differs per table: a transition row is a whole width-k window, so one gap costs up to \(k\) of them; an initial or atemporal row is a whole trajectory's contribution.

Warning
Complete-case selection distorts any likelihood computed on the result, and it does so unevenly across \(k\).

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

That matters because \(\log_2 L\) is a sum of per-instance terms, every one of which is \(\leq 0\). Scoring fewer instances removes negative terms, so it raises the total — a model does not fit better, it is simply charged for less. Two consequences:

  • a \(\log_2 L\) obtained with dropping is not comparable to one obtained on complete data, nor to one obtained at a different missing-value rate;
  • comparing orders this way (gum::learning::KTBNAdaptiveLearner) skews towards larger \(k\), since the larger candidate both drops more instances and gains more from having dropped them. The BIC penalty does not offset it: \(\log_2 N\) is taken once from the raw trajectory length and held fixed across candidates, so the penalty describes a sample size the likelihood no longer uses.

The effect grows with the missing-value rate. Read bestK() and scorePerCandidateK() with that in mind, and prefer complete trajectories whenever the order itself is the question being asked.

Note
Independently of the above, complete-case selection is only unbiased when values are missing completely at random (MCAR). If missingness depends on the data, the retained rows are a biased sample and the learned CPTs inherit that bias.

Definition at line 904 of file KTBNLearner_tpl.h.

904 {
905 return _nbDroppedRows_;
906 }

References _nbDroppedRows_.

◆ nbRows()

template<GUM_Numeric GUM_SCALAR>
std::vector< Size > gum::learning::KTBNLearner< GUM_SCALAR >::nbRows ( ) const

Number of time steps in each trajectory CSV (one entry per sample, in load order). This is the raw trajectory length; the transition table's sliding-window row count for trajectory i is nbRows()[i] - k + 1.

Definition at line 796 of file KTBNLearner_tpl.h.

796 {
797 // Raw trajectory lengths captured by _build_(), one entry per sample. Unlike
798 // BNLearner::nbRows() (a single flat-table row count), a trajectory learner
799 // has one length per sequence, so the per-sample vector is the natural analog.
800 return _nbTimeSlices_;
801 }

References _nbTimeSlices_.

◆ nbSamples()

template<GUM_Numeric GUM_SCALAR>
Size gum::learning::KTBNLearner< GUM_SCALAR >::nbSamples ( ) const

Number of trajectory CSV files loaded (the constructor's nbSamples).

Definition at line 892 of file KTBNLearner_tpl.h.

892 {
893 // the initial table holds exactly one row per trajectory, so its row count
894 // is the number of trajectory files given to the constructor.
895 return _initialLearner_->nbRows();
896 }

References _initialLearner_.

Referenced by KTBNLearner(), KTBNLearner(), KTBNLearner(), _build_(), and _inferAtemporalVars_().

Here is the caller graph for this function:

◆ operator=() [1/2]

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

References KTBNLearner().

Here is the call graph for this function:

◆ operator=() [2/2]

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

References KTBNLearner().

Here is the call graph for this function:

◆ setMaxIndegree()

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

Cap the number of parents of any single node.

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

Definition at line 776 of file KTBNLearner_tpl.h.

776 {
778 return *this;
779 }
KTBNLearner< GUM_SCALAR > & setMaxIndegree(Size max_indegree) override
Cap the number of parents of any single node.

References KTBNLearner(), and _forEachLearner_().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConstraints_().

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

◆ state()

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

Settings as a vector of (key, value, comment) tuples (mirrors BNLearner::state()).

Definition at line 839 of file KTBNLearner_tpl.h.

839 {
840 // settings are applied identically to every internal learner, so the
841 // transition learner's state represents the whole KTBNLearner.
843
844 // The transition learner lists every slice of every temporal variable
845 // (e.g. "W[0][2], W[1][2], W[2][2], W[3][2]"). Replace that row with one
846 // entry per base variable (e.g. "W[2]") built directly from the KTBN's own
847 // variable sets — no string parsing, robust to any base name.
848 for (auto& [key, val, comment]: result) {
849 if (key != "Variables") continue;
850 // Build base -> domainSize from the prior KTBN (slice 0 for temporal, AT for atemporal).
852 bool first = true;
853 auto emit = [&](const std::string& base, int slice) {
854 const auto& var = _prior_ktbn_.variable(base, slice);
855 if (!first) collapsed += ", ";
856 collapsed += base + "[" + std::to_string(var.domainSize()) + "]";
857 first = false;
858 };
859 for (const auto& base: _prior_ktbn_.temporalVarNames())
860 emit(base, 0);
861 for (const auto& base: _prior_ktbn_.atemporalVarNames())
863 val = collapsed;
864 break;
865 }
866 return result;
867 }
std::vector< std::tuple< std::string, std::string, std::string > > state() const
Settings as a vector of (key, value, comment) tuples (mirrors BNLearner::state()).

References _prior_ktbn_, _transitionLearner_, and gum::KTBN< GUM_SCALAR >::ATEMPORAL.

◆ toString()

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

Human-readable summary of the learner's current configuration.

Definition at line 814 of file KTBNLearner_tpl.h.

814 {
815 // Emit a k-TBN-specific header, then delegate score/algo/prior/constraint
816 // details to each internal learner's toString().
818 s << "k : " << k() << '\n';
819 s << "Variables : " << nbCols() << " (" << _prior_ktbn_.nbTemporalVars()
820 << " temporal, " << _prior_ktbn_.nbAtemporalVars() << " atemporal)" << '\n';
821 s << "Transition rows : " << _transitionLearner_->nbRows() << '\n';
822 s << "Initial rows : " << _initialLearner_->nbRows() << '\n';
823 s << '\n';
824 s << "=== Transition learner (arcs into slice " << (k() - 1) << ") ===" << '\n';
826 s << '\n';
827 s << "=== Initial learner (slices 0.." << (k() - 2) << ") ===" << '\n';
829 if (_atemporalLearner_) {
830 s << '\n';
831 s << "=== Atemporal learner (atemporal->atemporal arcs) ===" << '\n';
833 }
834 return s.str();
835 }
std::string toString() const
Human-readable summary of the learner's current configuration.

References _atemporalLearner_, _initialLearner_, _prior_ktbn_, _transitionLearner_, k(), and nbCols().

Here is the call graph for this function:

◆ useExtendedGreedyHillClimbing()

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

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

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

Definition at line 375 of file KTBNLearner_tpl.h.

375 {
377 return *this;
378 }
KTBNLearner< GUM_SCALAR > & useExtendedGreedyHillClimbing() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)

References KTBNLearner(), and _forEachLearner_().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConfig_().

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

◆ useFCI()

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

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

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

Definition at line 419 of file KTBNLearner_tpl.h.

419 {
421 return *this;
422 }
KTBNLearner< GUM_SCALAR > & useFCI() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)

References KTBNLearner(), and _forEachLearner_().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConfig_().

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

◆ useGreedyHillClimbing()

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

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

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

Definition at line 369 of file KTBNLearner_tpl.h.

369 {
371 return *this;
372 }
KTBNLearner< GUM_SCALAR > & useGreedyHillClimbing() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)

References KTBNLearner(), and _forEachLearner_().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConfig_().

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

◆ useGreedyThickThinning()

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

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

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

Definition at line 407 of file KTBNLearner_tpl.h.

407 {
409 return *this;
410 }
KTBNLearner< GUM_SCALAR > & useGreedyThickThinning() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)

References KTBNLearner(), and _forEachLearner_().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConfig_().

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

◆ useLocalSearchWithTabuList() [1/3]

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

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

Definition at line 381 of file KTBNLearner_tpl.h.

381 {
384 }
KTBNLearner< GUM_SCALAR > & useLocalSearchWithTabuList(Size tabu_size, Size nb_decrease) override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)

References KTBNLearner(), 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>
KTBNLearner< GUM_SCALAR > & gum::learning::KTBNLearner< GUM_SCALAR >::useLocalSearchWithTabuList ( Size tabu_size)

the default number of decreasing changes (key tabuNbDecrease)

Definition at line 387 of file KTBNLearner_tpl.h.

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

Here is the call graph for this function:

◆ useLocalSearchWithTabuList() [3/3]

template<GUM_Numeric GUM_SCALAR>
KTBNLearner< GUM_SCALAR > & gum::learning::KTBNLearner< 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 394 of file KTBNLearner_tpl.h.

394 {
397 return *this;
398 }

References _forEachLearner_().

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

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

◆ useMDLCorrection()

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

Engine-name pairs (tail, head) of arcs flagged as hiding a latent variable by MIIC (merged from all internal learners). Returned as names rather than Arc/NodeId pairs because the internal learners live in independent NodeId spaces, so a bare NodeId would be ambiguous.

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

Definition at line 435 of file KTBNLearner_tpl.h.

435 {
437 return *this;
438 }
KTBNLearner< GUM_SCALAR > & useMDLCorrection() override
Engine-name pairs (tail, head) of arcs flagged as hiding a latent variable by MIIC (merged from all i...

References KTBNLearner(), and _forEachLearner_().

Here is the call graph for this function:

◆ useMIIC()

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

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

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

Definition at line 401 of file KTBNLearner_tpl.h.

401 {
403 return *this;
404 }
KTBNLearner< GUM_SCALAR > & useMIIC() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)

References KTBNLearner(), and _forEachLearner_().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConfig_().

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

◆ useNMLCorrection()

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

Engine-name pairs (tail, head) of arcs flagged as hiding a latent variable by MIIC (merged from all internal learners). Returned as names rather than Arc/NodeId pairs because the internal learners live in independent NodeId spaces, so a bare NodeId would be ambiguous.

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

Definition at line 429 of file KTBNLearner_tpl.h.

429 {
431 return *this;
432 }
KTBNLearner< GUM_SCALAR > & useNMLCorrection() override
Engine-name pairs (tail, head) of arcs flagged as hiding a latent variable by MIIC (merged from all i...

References KTBNLearner(), and _forEachLearner_().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConfig_().

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

◆ useNoCorrection()

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

Engine-name pairs (tail, head) of arcs flagged as hiding a latent variable by MIIC (merged from all internal learners). Returned as names rather than Arc/NodeId pairs because the internal learners live in independent NodeId spaces, so a bare NodeId would be ambiguous.

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

Definition at line 441 of file KTBNLearner_tpl.h.

441 {
443 return *this;
444 }
KTBNLearner< GUM_SCALAR > & useNoCorrection() override
Engine-name pairs (tail, head) of arcs flagged as hiding a latent variable by MIIC (merged from all i...

References KTBNLearner(), and _forEachLearner_().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConfig_().

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

◆ usePC()

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

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

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

Definition at line 413 of file KTBNLearner_tpl.h.

413 {
415 return *this;
416 }
KTBNLearner< GUM_SCALAR > & usePC() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)

References KTBNLearner(), and _forEachLearner_().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConfig_().

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

◆ useScoreAIC()

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

Returns a warning string if the current score and prior are incompatible, empty string otherwise.

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

Definition at line 316 of file KTBNLearner_tpl.h.

316 {
318 return *this;
319 }
KTBNLearner< GUM_SCALAR > & useScoreAIC() override
Returns a warning string if the current score and prior are incompatible, empty string otherwise.

References KTBNLearner(), and _forEachLearner_().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConfig_().

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

◆ useScoreBD()

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

Returns a warning string if the current score and prior are incompatible, empty string otherwise.

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

Definition at line 322 of file KTBNLearner_tpl.h.

322 {
324 return *this;
325 }
KTBNLearner< GUM_SCALAR > & useScoreBD() override
Returns a warning string if the current score and prior are incompatible, empty string otherwise.

References KTBNLearner(), and _forEachLearner_().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConfig_().

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

◆ useScoreBDeu()

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

Returns a warning string if the current score and prior are incompatible, empty string otherwise.

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

Definition at line 328 of file KTBNLearner_tpl.h.

328 {
330 return *this;
331 }
KTBNLearner< GUM_SCALAR > & useScoreBDeu() override
Returns a warning string if the current score and prior are incompatible, empty string otherwise.

References KTBNLearner(), and _forEachLearner_().

Here is the call graph for this function:

◆ useScoreBIC()

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

Returns a warning string if the current score and prior are incompatible, empty string otherwise.

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

Definition at line 334 of file KTBNLearner_tpl.h.

334 {
336 return *this;
337 }
KTBNLearner< GUM_SCALAR > & useScoreBIC() override
Returns a warning string if the current score and prior are incompatible, empty string otherwise.

References KTBNLearner(), and _forEachLearner_().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConfig_().

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

◆ useScorefNML()

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

Returns a warning string if the current score and prior are incompatible, empty string otherwise.

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

Definition at line 352 of file KTBNLearner_tpl.h.

352 {
354 }
void useScorefNML() override
Returns a warning string if the current score and prior are incompatible, empty string otherwise.

References _forEachLearner_().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConfig_().

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

◆ useScoreLog2Likelihood()

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

Returns a warning string if the current score and prior are incompatible, empty string otherwise.

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

Definition at line 340 of file KTBNLearner_tpl.h.

340 {
342 return *this;
343 }
KTBNLearner< GUM_SCALAR > & useScoreLog2Likelihood() override
Returns a warning string if the current score and prior are incompatible, empty string otherwise.

References KTBNLearner(), and _forEachLearner_().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConfig_().

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

◆ useScoreMDL()

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

Returns a warning string if the current score and prior are incompatible, empty string otherwise.

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

Definition at line 346 of file KTBNLearner_tpl.h.

346 {
348 return *this;
349 }
KTBNLearner< GUM_SCALAR > & useScoreMDL() override
Returns a warning string if the current score and prior are incompatible, empty string otherwise.

References KTBNLearner(), and _forEachLearner_().

Referenced by gum::learning::KTBNAdaptiveLearner< GUM_SCALAR >::_applyConfig_().

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

◆ useSmoothingPrior() [1/2]

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

the default weight (key priorWeight of the section learning)

Definition at line 477 of file KTBNLearner_tpl.h.

477 {
479 }
KTBNLearner< GUM_SCALAR > & useSmoothingPrior(double weight) override
the default weight (key priorWeight of the section learning)

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

Here is the call graph for this function:

◆ useSmoothingPrior() [2/2]

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

the default weight (key priorWeight of the section learning)

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

Definition at line 482 of file KTBNLearner_tpl.h.

482 {
484 return *this;
485 }

References KTBNLearner(), and _forEachLearner_().

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

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

Member Data Documentation

◆ _atemporalLearner_

template<GUM_Numeric GUM_SCALAR>
std::unique_ptr< BNLearner< GUM_SCALAR > > gum::learning::KTBNLearner< GUM_SCALAR >::_atemporalLearner_
private

◆ _ignoreMissingSymbols_

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

prior k-TBN: the single source of truth for k, variable domains, temporal/atemporal classification and engine names. Everything else (base lists, column names) is derived from it on demand. Analogous to the prior BayesNet stored in BNLearner when a reference BN is given. whether build() drops incomplete rows rather than refusing the data

Definition at line 596 of file KTBNLearner.h.

Referenced by KTBNLearner(), KTBNLearner(), _build_(), and isIgnoringMissingSymbols().

◆ _initialLearner_

template<GUM_Numeric GUM_SCALAR>
std::unique_ptr< BNLearner< GUM_SCALAR > > gum::learning::KTBNLearner< GUM_SCALAR >::_initialLearner_
private

◆ _nbAtemporalPossibleEdges_

template<GUM_Numeric GUM_SCALAR>
Size gum::learning::KTBNLearner< GUM_SCALAR >::_nbAtemporalPossibleEdges_ = 0
private

Definition at line 616 of file KTBNLearner.h.

Referenced by addPossibleEdge(), copyState(), erasePossibleEdge(), and learnKTBN().

◆ _nbDroppedRows_

template<GUM_Numeric GUM_SCALAR>
Size gum::learning::KTBNLearner< GUM_SCALAR >::_nbDroppedRows_ {0}
private

number of time steps (rows) in each trajectory CSV, in load order. rows build() dropped because they carried a missing symbol

Definition at line 602 of file KTBNLearner.h.

Referenced by _build_(), and nbDroppedRows().

◆ _nbTemporalPossibleEdges_

template<GUM_Numeric GUM_SCALAR>
Size gum::learning::KTBNLearner< GUM_SCALAR >::_nbTemporalPossibleEdges_ = 0
private

counts of currently-active possible edges, split by kind: edges with at least one temporal endpoint, and edges between two atemporal variables. Maintained by add/erasePossibleEdge(). When a whitelist is active (temporal count > 0) but no atemporal->atemporal edge is whitelisted, the atemporal learner would otherwise stay unrestricted; learnKTBN() then suppresses it so the whitelist is honoured (no atemporal arc is produced).

Definition at line 615 of file KTBNLearner.h.

Referenced by addPossibleEdge(), copyState(), erasePossibleEdge(), and learnKTBN().

◆ _nbTimeSlices_

template<GUM_Numeric GUM_SCALAR>
std::vector< Size > gum::learning::KTBNLearner< GUM_SCALAR >::_nbTimeSlices_
private

Captured once by build() and exposed by nbRows(). This is the raw trajectory length, not the sliding-window row count of the transition table (which is nbTimeSlices[i] - k + 1 summed over trajectories).

Definition at line 607 of file KTBNLearner.h.

Referenced by _build_(), and nbRows().

◆ _prior_ktbn_

◆ _transitionLearner_


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