70#ifndef GUM_LEARNING_KTBN_ADAPTIVE_LEARNER_H
71#define GUM_LEARNING_KTBN_ADAPTIVE_LEARNER_H
86#include <unordered_set>
102 template < GUM_Numeric GUM_SCALAR >
138 std::string_view csvBaseName,
141 const std::unordered_set< std::string >& atemporalVars,
142 const std::vector< std::string >& missingSymbols = {
"?"},
143 bool induceTypes =
true);
185 std::string_view csvBaseName,
188 const std::vector< std::string >& missingSymbols = {
"?"},
189 bool induceTypes =
true);
214 std::string_view csvBaseName,
217 const BayesNet< GUM_SCALAR >& bn,
218 const std::unordered_set< std::string >& atemporalVars = {},
219 const std::vector< std::string >& missingSymbols = {
"?"});
253 const std::vector< std::pair< std::string, std::string > >&
latentVariables()
const;
353 std::vector< std::tuple< std::string, std::string, std::string > >
state()
const;
378 Size nb_decrease)
override;
415 std::string_view headNode)
override;
418 std::string_view headBase,
419 int headSlice)
override;
421 std::string_view headNode)
override;
424 std::string_view headBase,
425 int headSlice)
override;
428 std::string_view headNode)
override;
431 std::string_view headBase,
432 int headSlice)
override;
434 std::string_view headNode)
override;
437 std::string_view headBase,
438 int headSlice)
override;
476 std::string_view headBase)
override;
498 std::string_view headBase,
499 int headSlice)
override;
501 std::string_view head)
override;
504 std::string_view headBase,
505 int headSlice)
override;
507 std::string_view head)
override;
656 static std::unordered_set< std::string >
658 std::string_view csvBaseName,
661 const std::vector< std::string >& missingSymbols);
686 void _verifyBase_(std::string_view base,
int slice)
const;
695 void _verifyKernelArc_(std::string_view tailBase, std::string_view headBase,
int lag)
const;
745 template <
typename PerInstance,
typename PerNodeFinal >
747 PerInstance perInstance,
748 PerNodeFinal perNodeFinal)
const;
773 double _fNMLScore_(
const KTBN< GUM_SCALAR >& net)
const;
794#ifndef GUM_NO_EXTERN_TEMPLATE_CLASS
Implementation of the KTBNAdaptiveLearner class.
A structure/parameter learner for k-order dynamic Bayesian networks.
the class for computing the log2 of the parametric complexity of an r-ary multinomial variable
AlgoType
an enumeration to select easily the learning algorithm to use
ScoreType
an enumeration enabling to select easily the score we wish to use
static AlgoType preferredAlgo()
the algorithm used by the learners when none is selected explicitly
BNLearnerPriorType
an enumeration to select the prior
Pure-virtual configuration interface shared by all k-TBN learners.
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...
std::string _encode_(std::string_view base, int slice) const
(base, slice) -> engine name ("A[1]" / atemporal engine name). Pure function, shared by every learner...
std::pair< std::string, int > _determineNode_(const std::string &name) const
engine name -> (base, slice); atemporal names map to KTBN::ATEMPORAL. Shared by every learner; only t...
Learns a k-TBN (order k + structure + parameters) from trajectory CSVs.
std::string toString() const
Human-readable summary of the recorded configuration (candidate order range, algorithm / score / corr...
KTBNAdaptiveLearner< GUM_SCALAR > & addForbiddenArcAllSlices(std::string_view tailBase, std::string_view headBase) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
bool _induceTypes_
whether numeric columns are retyped (see KTBNLearner); unused (and forced false) when a schema BN is ...
std::set< std::string > _noParentNodes_
root nodes (no parents), as engine names
KTBNAdaptiveLearner< GUM_SCALAR > & allowArcAdditions(bool allow=true) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
std::vector< std::string > _missingSymbols_
symbols in the CSVs to interpret as missing values
std::unordered_set< std::string > _atemporalVars_
base names of the atemporal (static) variables
bool _allowAdditions_
recorded graph-change permissions / indegree cap
void _verifyKernelArc_(std::string_view tailBase, std::string_view headBase, int lag) const
Throw InvalidArgument unless tailBase and headBase are known, temporal base variables (a kernel-relat...
KTBNAdaptiveLearner< GUM_SCALAR > & useOrderScoreBIC()
Select k by BIC (the default): keep the k whose learned model maximises .
std::unique_ptr< BayesNet< GUM_SCALAR > > _prior_bn_
optional variable-schema BN (set by the BN constructor): when present, each per-k KTBNLearner is buil...
Size _bestK_
k selected by the last learnKTBN() call, or 0 as a sentinel while no learning has happened yet....
std::string _dirPath_
directory holding the trajectory CSV files
Size _kMax_
largest order to explore (candidates are kMin..kMax)
KTBNAdaptiveLearner< GUM_SCALAR > & addMandatoryArc(std::string_view tailNode, std::string_view headNode) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
bool _isKnownBase_(std::string_view base) const override
whether base is one of this learner's variables; the base names read at construction,...
KTBNAdaptiveLearner< GUM_SCALAR > & eraseForbiddenArcAllSlices(std::string_view tailBase, std::string_view headBase) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
KTBNAdaptiveLearner< GUM_SCALAR > & useNMLCorrection() override
void _applyConstraints_(KTBNLearner< GUM_SCALAR > &learner, Size k) const
Replay the recorded structural constraints onto learner (built for order k). Engine-name constraints ...
std::vector< std::pair< std::string, std::string > > _bestLatentVariables_
latent-variable arcs (engine-name pairs) reported by the winning candidate's MIIC run,...
IBNLearner::BNLearnerPriorType _prior_
recorded prior and its weight
double _orderSelectionScore_(const KTBN< GUM_SCALAR > &net, double logN) const
The cross-k order-selection score of net under the recorded orderScore criterion, given logN = log2 o...
const std::vector< std::pair< std::string, std::string > > & latentVariables() const
Engine-name (tail, head) pairs of arcs the selected model's MIIC run flagged as hiding a latent varia...
std::set< std::string > _noChildrenNodes_
leaf nodes (no children), as engine names
double _priorWeight_
always written by the useXxxPrior() methods, which read learning.priorWeight when no weight is given
KTBNAdaptiveLearner< GUM_SCALAR > & useGreedyHillClimbing() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
double _fNMLScore_(const KTBN< GUM_SCALAR > &net) const
fNML order score of net over the recorded trajectories: , with the node's domain size and the count...
KTBNAdaptiveLearner< GUM_SCALAR > & eraseForbiddenIntraSliceArc(std::string_view tailBase, std::string_view headBase) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
void _forEachScoredNode_(const KTBN< GUM_SCALAR > &net, PerInstance perInstance, PerNodeFinal perNodeFinal) const
Stream every scored template-node instance of net over the recorded trajectories, driving both the li...
KTBNAdaptiveLearner< GUM_SCALAR > & eraseMandatoryArc(std::string_view tailNode, std::string_view headNode) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
IBNLearner::AlgoType _algo_
recorded structure-learning algorithm ; it is initialized from the configuration, see IBNLearner::pre...
KTBNAdaptiveLearner< GUM_SCALAR > & addMandatoryKernelArc(std::string_view tailBase, int lag, std::string_view headBase)
Force an arc from tailBase, lag slices before the kernel, to headBase in the kernel....
OrderScoreType _orderScore_
recorded cross-k order-selection criterion (the outer score used by learnKTBN() to pick the best k; i...
Size kMax() const
Largest order explored (the kMax argument of the constructor).
KTBNAdaptiveLearner< GUM_SCALAR > & useLocalSearchWithTabuList(Size tabu_size, Size nb_decrease) override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNAdaptiveLearner< GUM_SCALAR > & allowArcDeletions(bool allow=true) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
KTBNAdaptiveLearner< GUM_SCALAR > & erasePossibleEdge(std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
KTBNAdaptiveLearner(std::string_view dirPath, std::string_view csvBaseName, Size nbSamples, Size kMax, const std::unordered_set< std::string > &atemporalVars, const std::vector< std::string > &missingSymbols={"?"}, bool induceTypes=true)
Constructor — the candidate orders are kMin..kMax.
bool _ignoreMissingSymbols_
whether incomplete rows/instances are dropped (see ignoreMissingSymbols())
KTBNAdaptiveLearner< GUM_SCALAR > & addNoChildrenNode(std::string_view base, int slice) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
KTBNAdaptiveLearner< GUM_SCALAR > & addPossibleEdge(std::string_view tailBase, int tailSlice, std::string_view headBase, int headSlice) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
std::set< std::pair< std::string, std::string > > _forbiddenArcsAllSlices_
forbidden all-slices arcs, as (tailBase, headBase) pairs
KTBNAdaptiveLearner< GUM_SCALAR > & operator=(const KTBNAdaptiveLearner< GUM_SCALAR > &)=delete
KTBNAdaptiveLearner< GUM_SCALAR > & addForbiddenIntraSliceArc(std::string_view tailBase, std::string_view headBase) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
std::set< std::pair< std::string, std::string > > _mandatoryArcs_
mandatory arcs, as (tail, head) engine-name pairs
std::set< std::pair< std::string, std::string > > _possibleEdges_
MIIC candidate edges, as (tail, head) engine-name pairs.
const std::vector< std::pair< Size, double > > & scorePerCandidateK() const
Per-candidate cross-k scores from the last learnKTBN() call, as (k, score) pairs for k = kMin....
const std::unordered_set< std::string > & _atemporalVarNames_() const override
atemporal base names for IKTBNLearner's shared encode/_determineNode_; the set recorded at constructi...
IBNLearner::ScoreType _score_
recorded per-k structure score (the inner score, replayed on each candidate)
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreBDeu() override
std::set< std::pair< std::string, std::string > > _forbiddenArcs_
forbidden arcs, as (tail, head) engine-name pairs
std::set< std::pair< std::string, std::string > > _forbiddenIntraSliceArcs_
forbidden intra-slice arcs, as (tailBase, headBase) pairs
KTBNAdaptiveLearner< GUM_SCALAR > & addForbiddenArc(std::string_view tailNode, std::string_view headNode) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
Size bestK() const
Order k selected by the last learnKTBN() call.
KTBNAdaptiveLearner(KTBNAdaptiveLearner< GUM_SCALAR > &&)=delete
bool isIgnoringMissingSymbols() const
Whether incomplete rows and instances are dropped. False by default.
Size _nbSamples_
number of CSV files to read
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreMDL() override
double _log2Likelihood_(const KTBN< GUM_SCALAR > &net) const
Factorized log2-likelihood of net over the recorded trajectories, comparable across candidate k (the ...
void useScorefNML() override
KTBNAdaptiveLearner< GUM_SCALAR > & eraseForbiddenKernelArc(std::string_view tailBase, int lag, std::string_view headBase)
Undo a previous addForbiddenKernelArc (same (tailBase, lag, headBase) triple).
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreAIC() override
void _applyConfig_(KTBNLearner< GUM_SCALAR > &learner) const
Apply the recorded score / algorithm / correction / prior onto a freshly-built learner....
KTBNAdaptiveLearner< GUM_SCALAR > & eraseMandatoryKernelArc(std::string_view tailBase, int lag, std::string_view headBase)
Undo a previous addMandatoryKernelArc (same (tailBase, lag, headBase) triple).
KTBNAdaptiveLearner< GUM_SCALAR > & useGreedyThickThinning() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNAdaptiveLearner< GUM_SCALAR > & useExtendedGreedyHillClimbing() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
Size _kMin_
smallest order worth exploring (candidates are kMin..kMax). Starts at 2 and is recomputed by recomput...
std::set< std::tuple< std::string, std::string, int > > _mandatoryKernelArcs_
mandatory kernel-relative arcs, same shape as forbiddenKernelArcs
log_2 where the penalty replaces BIC s KTBNAdaptiveLearner< GUM_SCALAR > & useOrderScorefNML()
by a sum of per-node, per-parent-configuration multinomial parametric complexities (regret) – data-de...
OrderScoreType
The criterion learnKTBN() uses to pick the best among the candidates — the outer score,...
KTBNAdaptiveLearner< GUM_SCALAR > & eraseForbiddenArc(std::string_view tailNode, std::string_view headNode) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
KTBNAdaptiveLearner< GUM_SCALAR > & useSmoothingPrior(double weight) override
the default weight (key priorWeight of the section learning)
void _recomputeKMin_()
Recompute kMin from scratch: max(2, 1 + the largest concrete slice named by any recorded forbidden/ma...
KTBNAdaptiveLearner< GUM_SCALAR > & useMDLCorrection() override
std::vector< std::pair< Size, double > > _scorePerCandidateK_
per-candidate (k, order-score) pairs from the last learnKTBN() run, in ascending k....
VariableLog2ParamComplexity _ctable_
cache of log2 of the multinomial parametric complexity C^r_n, used by the fNML order penalty....
double _countParameters_(const KTBN< GUM_SCALAR > &net) const
Number of free parameters of net's template: summed over every template node (all initial slices,...
KTBNAdaptiveLearner< GUM_SCALAR > & allowArcReversals(bool allow=true) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
std::vector< std::tuple< std::string, std::string, std::string > > state() const
The recorded configuration as (key, value, comment) tuples (mirrors KTBNLearner::state()); toString()...
KTBNAdaptiveLearner< GUM_SCALAR > & usePC() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNAdaptiveLearner< GUM_SCALAR > & operator=(KTBNAdaptiveLearner< GUM_SCALAR > &&)=delete
KTBN< GUM_SCALAR > learnKTBN() override
Learns the best k in [kMin, kMax] together with the structure and the CPTs: one KTBNLearner is built ...
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreLog2Likelihood() override
std::unordered_set< std::string > _baseNames_
all base variable names (temporal + atemporal), read from the first trajectory CSV header at construc...
KTBNAdaptiveLearner< GUM_SCALAR > & eraseNoParentNode(std::string_view base, int slice) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
KTBNAdaptiveLearner< GUM_SCALAR > & ignoreMissingSymbols(bool ignore=true)
Learn and score on the fully observed data only, dropping every row and every scoring instance that c...
void _raiseKMinForSlice_(int slice)
Raise kMin, if needed, so that kMin > slice: a smaller candidate would silently drop a constraint nam...
KTBNAdaptiveLearner< GUM_SCALAR > & useOrderScoreAIC()
Select k by AIC: keep the k whose learned model maximises (a lighter, sample-size-independent comple...
void _verifyBase_(std::string_view base, int slice) const
Throw InvalidArgument unless base is a known base variable and slice is valid for it: base must be in...
std::string _csvBaseName_
stem of each trajectory file name
Size _tabuSize_
tabu-list parameters (meaningful when the algorithm is LOCAL_SEARCH_WITH_TABU_LIST)....
KTBNAdaptiveLearner(const KTBNAdaptiveLearner< GUM_SCALAR > &)=delete
static std::unordered_set< std::string > _inferAtemporalVars_(std::string_view dirPath, std::string_view csvBaseName, Size nbSamples, Size kMax, const std::vector< std::string > &missingSymbols)
checks kMax >= 2 and nbSamples >= 1, then delegates to the shared IKTBNLearner::scanConstantColumns()...
KTBNAdaptiveLearner< GUM_SCALAR > & setMaxIndegree(Size max_indegree) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreBD() override
KTBNAdaptiveLearner< GUM_SCALAR > & addNoParentNode(std::string_view base, int slice) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
KTBNAdaptiveLearner< GUM_SCALAR > & useScoreBIC() override
CorrectedMutualInformation::KModeTypes _correction_
recorded MIIC correction
KTBNAdaptiveLearner< GUM_SCALAR > & addForbiddenKernelArc(std::string_view tailBase, int lag, std::string_view headBase)
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
KTBNAdaptiveLearner< GUM_SCALAR > & useNoCorrection() override
KTBNAdaptiveLearner< GUM_SCALAR > & useMIIC() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
KTBNAdaptiveLearner< GUM_SCALAR > & eraseNoChildrenNode(std::string_view base, int slice) override
Forbid an arc from tailBase, lag slices before the kernel, to headBase in the kernel: tailBase at sli...
std::set< std::tuple< std::string, std::string, int > > _forbiddenKernelArcs_
forbidden kernel-relative arcs, as (tailBase, headBase, lag) triples: tailBase at slice k-1-lag -> he...
KTBNAdaptiveLearner< GUM_SCALAR > & useFCI() override
the default parameters (keys tabuListSize, tabuNbDecrease of the section learning)
std::string checkScorePriorCompatibility() const
Warning string if the recorded score and prior are incompatible, empty otherwise. Data-free: it evalu...
Learns a k-TBN (structure and/or parameters) from trajectory CSVs.
std::size_t Size
In aGrUM, hashed values are unsigned long int.
include the inlined functions if necessary
template class GUM_PUBLIC_KTBN KTBNAdaptiveLearner< double >
gum is the global namespace for all aGrUM entities