Generates a database of trajectories from a k-DBN (one CSV per trajectory). More...

#include <agrum/KTBN/database/KTBNDatabaseGenerator.h>

Inheritance diagram for gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >:

Collaboration diagram for gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >:

Classes
struct	ParentRef
	a parent of a template node, precompiled for fast sampling More...
struct	NodeRef
	a template node, precompiled for fast sampling More...

Public Types
enum class	DiscretizedLabelMode : char { INTERVAL , MEDIAN , RANDOM }
	rendering of discretized variables when labels are requested More...
enum class	VarOrderMode : char { RANDOM , TOPOLOGICAL , ANTI_TOPOLOGICAL }
	column order used for the exported CSV More...

Public Member Functions
Constructors / Destructors
	KTBNDatabaseGenerator (const KTBN< GUM_SCALAR > &kdbn)
	Constructor.
	~KTBNDatabaseGenerator ()
	destructor
Accessors / Modifiers
std::vector< double >	drawSamples (Size nbSamples, Size nbTimeSlices, std::string_view dirPath, std::string_view csvBaseName, VarOrderMode mode=VarOrderMode::RANDOM, bool useLabels=true, std::string csvSeparator=",")
	Generates `nbSamples` independent trajectories, writing one CSV file per trajectory into `dirPath`.
std::vector< double >	drawSamples (const std::vector< Size > &nbTimeSlices, std::string_view dirPath, std::string_view csvBaseName, VarOrderMode mode=VarOrderMode::RANDOM, bool useLabels=true, std::string csvSeparator=",")
	Like drawSamples(), but every trajectory may have its own horizon.
void	setDiscretizedLabelModeRandom ()
	set discretized-label rendering to a uniform random draw in the interval (this is the default; each labelled export then differs)
void	setDiscretizedLabelModeMedian ()
	set discretized-label rendering to the (deterministic) interval median
void	setDiscretizedLabelModeInterval ()
	set discretized-label rendering to the interval label "[min,max["
Size	nbVars () const
	returns the number of base variable columns

Public Attributes
Signaler< Size, double >	onProgress
	Progression (percent) and time.
Signaler< std::string_view >	onStop
	with a possible explanation for stopping

Private Member Functions
void	_build_ (const KTBN< GUM_SCALAR > &kdbn)
	one-shot initialisation called by the constructor: fills the column index (baseCols, nbVars), the topological node/parent cache (nodes, kernel), the per-column representatives (vars), and the shared instantiation (inst). All cached pointers refer to template.
Idx	_drawVar_ (const DiscreteVariable &var, const Tensor< GUM_SCALAR > &cpt, double &log2likelihood)
	inverse-CDF draw of `var` given the parents already set in inst; accumulates log2(P(drawn value)) into `log2likelihood`
std::string	_label_ (Idx col, Idx idx) const
	renders the label of modality `idx` of base column `col` (taking the discretized-label mode into account)
void	_writeTrajectory_ (std::string_view csvFileURL, const std::vector< Idx > &traj, Size nbTimeSlices, bool useLabels, const std::string &csvSeparator, const std::vector< Idx > &colOrder) const
	writes one trajectory CSV (header + T rows) to `csvFileURL`. `traj` is the flat row-major buffer (T x nbVars) in canonical column order; `colOrder` gives the output column order.
void	setVarOrderRandomized (std::vector< Idx > &colOrder) const
	builds a uniformly random column order
void	setVarOrderTopological (std::vector< Idx > &colOrder) const
	builds a topological column order (transition-kernel projection)
void	setVarOrderAntiTopological (std::vector< Idx > &colOrder) const
	builds the reverse of setVarOrderTopological()
std::vector< double >	_drawSamples_ (Size nbSamples, Size fixedLen, const std::vector< Size > *perTraj, std::string_view dirPath, std::string_view csvBaseName, VarOrderMode mode, bool useLabels, const std::string &csvSeparator)
	the single worker behind both drawSamples() overloads. Trajectory i's horizon is read from `perTraj` (when non-null) else from `fixedLen`; samples each trajectory and writes it straight to its own CSV file.
	KTBNDatabaseGenerator (const KTBNDatabaseGenerator &)=delete
	KTBNDatabaseGenerator (KTBNDatabaseGenerator &&)=delete
KTBNDatabaseGenerator &	operator= (const KTBNDatabaseGenerator &)=delete
KTBNDatabaseGenerator &	operator= (KTBNDatabaseGenerator &&)=delete

Static Private Member Functions
static std::pair< std::string, int >	_decode_ (const std::string &name, const std::unordered_set< std::string > &temporalSet)
	decodes a template node name into (base, slice): "B[t]" with B a known temporal process -> (B, t); anything else (bare or bracket-named atemporal node) -> (name, ATEMPORAL).

Private Attributes
BayesNet< GUM_SCALAR >	_template_
	the \(k\)-slice template (a small copy, independent of the horizon)
Size	_k_
	the order \(k\) of the k-DBN
Size	_nbVars_
	number of base variable columns
std::vector< std::string >	_baseCols_
	col index -> base name (canonical column numbering)
std::vector< const DiscreteVariable * >	_vars_
	one representative variable per base column (same order as baseCols), pointing into template so it outlives the source k-DBN. Label rendering only.
std::vector< NodeRef >	_nodes_
	all template nodes in topological order (drives Phase 1, the bootstrap)
std::vector< Idx >	_kernel_
	indices, in nodes, of the slice-(k-1) nodes (the transition kernel, drives Phase 2); already in topological order
Instantiation	_inst_
	a shared instantiation over all template variables, so we don't have to rebuild it for every draw
DiscretizedLabelMode	_discretizedLabelMode_ = DiscretizedLabelMode::RANDOM
	rendering of discretized variables when labels are requested

Detailed Description

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

Generates a database of trajectories from a k-DBN (one CSV per trajectory).

See also: gum::learning::BNDatabaseGenerator, the (static) Bayesian-network counterpart. Same role and sampling principle, but it streams trajectories from the k-DBN template without unrolling and without keeping the whole database in memory.

Definition at line 108 of file KTBNDatabaseGenerator.h.

Member Enumeration Documentation

◆ DiscretizedLabelMode

template<GUM_Numeric GUM_SCALAR>

enum class gum::learning::KTBNDatabaseGenerator::DiscretizedLabelMode : char

strong

rendering of discretized variables when labels are requested

Enumerator
INTERVAL
MEDIAN
RANDOM

Definition at line 111 of file KTBNDatabaseGenerator.h.

111: char { INTERVAL, MEDIAN, RANDOM };

◆ VarOrderMode

template<GUM_Numeric GUM_SCALAR>

enum class gum::learning::KTBNDatabaseGenerator::VarOrderMode : char

strong

column order used for the exported CSV

Enumerator
RANDOM
TOPOLOGICAL
ANTI_TOPOLOGICAL

Definition at line 114 of file KTBNDatabaseGenerator.h.

114: char { RANDOM, TOPOLOGICAL, ANTI_TOPOLOGICAL };

Constructor & Destructor Documentation

◆ KTBNDatabaseGenerator() [1/3]

template<GUM_Numeric GUM_SCALAR>

gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::KTBNDatabaseGenerator ( const KTBN< GUM_SCALAR > & kdbn )

explicit

Constructor.

Parameters

kdbn	The k-DBN to sample from (only its \(k\)-slice template is copied, via toBN(); the k-DBN itself is not retained). The horizon is not fixed here; it is passed to drawSamples().

Definition at line 77 of file KTBNDatabaseGenerator_tpl.h.

                                                                                           :
      _template_(kdbn.toBN()), _k_(kdbn.k()) {
    GUM_CONSTRUCTOR(KTBNDatabaseGenerator)
    _build_(kdbn);
  }

References KTBNDatabaseGenerator(), _build_(), _k_, and _template_.

Referenced by KTBNDatabaseGenerator(), KTBNDatabaseGenerator(), KTBNDatabaseGenerator(), ~KTBNDatabaseGenerator(), operator=(), and operator=().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ~KTBNDatabaseGenerator()

template<GUM_Numeric GUM_SCALAR>

gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::~KTBNDatabaseGenerator ( )

destructor

Definition at line 84 of file KTBNDatabaseGenerator_tpl.h.

                                                              {
    GUM_DESTRUCTOR(KTBNDatabaseGenerator)
  }

References KTBNDatabaseGenerator().

Here is the call graph for this function:

◆ KTBNDatabaseGenerator() [2/3]

template<GUM_Numeric GUM_SCALAR>

gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::KTBNDatabaseGenerator ( const KTBNDatabaseGenerator< GUM_SCALAR > & )

privatedelete

References KTBNDatabaseGenerator().

Here is the call graph for this function:

◆ KTBNDatabaseGenerator() [3/3]

template<GUM_Numeric GUM_SCALAR>

gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::KTBNDatabaseGenerator ( KTBNDatabaseGenerator< GUM_SCALAR > && )

privatedelete

References KTBNDatabaseGenerator().

Here is the call graph for this function:

Member Function Documentation

◆ _build_()

template<GUM_Numeric GUM_SCALAR>

void gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::_build_ ( const KTBN< GUM_SCALAR > & kdbn )

private

one-shot initialisation called by the constructor: fills the column index (baseCols, nbVars), the topological node/parent cache (nodes, kernel), the per-column representatives (vars), and the shared instantiation (inst). All cached pointers refer to template.

Definition at line 108 of file KTBNDatabaseGenerator_tpl.h.

                                                                                  {
    const std::unordered_set< std::string >& temporalSet = kdbn.temporalVarNames();
 
    // 1) canonical column numbering: one column per base variable (temporal
    //    variables first, then atemporal ones).
    std::unordered_map< std::string, Idx > colByName;   // local: only needed during construction
    _nbVars_ = 0;
    for (const std::string& base: temporalSet) {
      _baseCols_.push_back(base);
      colByName.emplace(base, _nbVars_++);
    }
    for (const std::string& base: kdbn.atemporalVarNames()) {
      _baseCols_.push_back(base);
      colByName.emplace(base, _nbVars_++);
    }
 
    // 2) precompile every template node (and its parents) in topological order,
    //    so that drawSamples() never has to parse a name again. In the same pass we
    //    pick one representative variable per column (_vars_, for label rendering)
    //    and build the shared instantiation (_inst_, reused for every draw). All
    //    cached pointers refer to _template_ (our own copy), so they outlive the
    //    source k-DBN.
    _vars_.resize(_nbVars_);
    const int lastSlice = int(_k_) - 1;
    for (const NodeId n: _template_.topologicalOrder()) {
      const DiscreteVariable&     v   = _template_.variable(n);
      const Tensor< GUM_SCALAR >& cpt = _template_.cpt(n);
      const auto [base, slice]        = _decode_(v.name(), temporalSet);
 
      NodeRef nr;
      nr.var   = &v;
      nr.cpt   = &cpt;
      nr.slice = slice;
      nr.col   = colByName[base];
 
      for (Idx i = 1; i < cpt.nbrDim(); ++i) {
        const DiscreteVariable& pv = cpt.variable(i);
        const auto [pbase, pslice] = _decode_(pv.name(), temporalSet);
        const bool pAtemporal      = (pslice == KTBN< GUM_SCALAR >::ATEMPORAL);
 
        ParentRef pr;
        pr.var         = &pv;
        pr.col         = colByName[pbase];
        pr.isAtemporal = pAtemporal;
        pr.lag         = pAtemporal ? KTBN< GUM_SCALAR >::ATEMPORAL : slice - pslice;
        nr.parents.push_back(std::move(pr));
      }
 
      _vars_[nr.col] = &v;
      _inst_.add(v);
      if (slice == lastSlice) _kernel_.push_back(_nodes_.size());
      _nodes_.push_back(std::move(nr));
    }
  }

Referenced by KTBNDatabaseGenerator().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _decode_()

template<GUM_Numeric GUM_SCALAR>

std::pair< std::string, int > gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::_decode_	(	const std::string &	name,
		const std::unordered_set< std::string > &	temporalSet )

staticprivate

decodes a template node name into (base, slice): "B[t]" with B a known temporal process -> (B, t); anything else (bare or bracket-named atemporal node) -> (name, ATEMPORAL).

Definition at line 89 of file KTBNDatabaseGenerator_tpl.h.

                                                        {
    if (!name.empty() && name.back() == ']') {
      const auto p = name.rfind('[');
      if (p != std::string::npos && p + 1 < name.size() - 1) {
        const std::string base   = name.substr(0, p);
        const std::string digits = name.substr(p + 1, name.size() - p - 2);
        if (temporalSet.contains(base)
            && std::all_of(digits.begin(), digits.end(), [](unsigned char c) {
                 return std::isdigit(c) != 0;
               }))
          return {base, std::stoi(digits)};
      }
    }
    return {name, KTBN< GUM_SCALAR >::ATEMPORAL};
  }

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

Referenced by _build_().

Here is the caller graph for this function:

◆ _drawSamples_()

template<GUM_Numeric GUM_SCALAR>

std::vector< double > gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::_drawSamples_	(	Size	nbSamples,
		Size	fixedLen,
		const std::vector< Size > *	perTraj,
		std::string_view	dirPath,
		std::string_view	csvBaseName,
		VarOrderMode	mode,
		bool	useLabels,
		const std::string &	csvSeparator )

private

the single worker behind both drawSamples() overloads. Trajectory i's horizon is read from perTraj (when non-null) else from fixedLen; samples each trajectory and writes it straight to its own CSV file.

The single worker behind both public drawSamples() overloads. Trajectory i's horizon T is read from perTraj when given, else from the shared fixedLen. Each trajectory is sampled into a flat row-major buffer (T × nbVars, in canonical column order) in two phases and written straight to its own CSV:

Phase 1 — initial k slices (0..k-1): no history yet, so every node of the k-slice template is drawn from scratch in topological order by inverse-CDF.

Phase 2 — transition (slices k..T-1): only the slice-(k-1) nodes (the kernel, already topological) are drawn, each parent read from the row at time (t - lag).

Definition at line 229 of file KTBNDatabaseGenerator_tpl.h.

                                                                                                {
    // horizon of trajectory i: from perTraj when given, else the shared fixedLen
    const auto lengthAt = [&](Idx i) { return perTraj ? (*perTraj)[i] : fixedLen; };
 
    // validate everything up front, before any file is created
    if (csvSeparator.find('\n') != std::string::npos)
      GUM_ERROR(InvalidArgument, "csvSeparator must not contain end-line characters")
    for (Idx i = 0; i < nbSamples; ++i)
      if (lengthAt(i) < _k_)
        GUM_ERROR(OperationNotAllowed, "nbTimeSlices=" << lengthAt(i) << " must be >= k=" << _k_)
 
    // decide the column order once (shared by every trajectory file):
    // colOrder[i] is the canonical column written at output position i.
    std::vector< Idx > colOrder;
    switch (mode) {
      case VarOrderMode::RANDOM : setVarOrderRandomized(colOrder); break;
      case VarOrderMode::TOPOLOGICAL : setVarOrderTopological(colOrder); break;
      case VarOrderMode::ANTI_TOPOLOGICAL : setVarOrderAntiTopological(colOrder); break;
      default : GUM_ERROR(InvalidArgument, "unknown VarOrderMode")
    }
 
    const std::filesystem::path dir{dirPath};
    const std::string           stem{csvBaseName};
    std::filesystem::create_directories(dir);   // ensure the destination exists
 
    std::vector< double > log2Ls;
    log2Ls.reserve(nbSamples);
 
    const bool             hasListener = onProgress.hasListener();
    std::optional< Timer > timer;
    int                    progress = 0;
    if (hasListener) {
      timer.emplace();
      GUM_EMIT2(onProgress, 0, 0.0);
    }
 
    // generate one trajectory at a time; each is sampled then written to its file
    for (std::size_t i = 0; i < nbSamples; ++i) {
      const Size T = lengthAt(i);
 
      // flat trajectory buffer (row-major) in canonical column order: the value at
      // time t, base column c is traj[t * _nbVars_ + c]. Sampling uses the cached
      // integer columns (nr.col / pr.col) — no name lookup in the hot loop.
      std::vector< Idx > traj(T * _nbVars_);
      double             log2L = 0;
 
      // Phase 1: draw the first k time steps from scratch (no history available yet)
      for (const NodeRef& nr: _nodes_) {
        for (const ParentRef& pr: nr.parents) {
          // an atemporal parent has the same value on every row, stored at row 0
          const Size parentRow = pr.isAtemporal ? 0 : nr.slice - pr.lag;
          _inst_.chgVal(*pr.var, traj[parentRow * _nbVars_ + pr.col]);
        }
        const Idx drawn = _drawVar_(*nr.var, *nr.cpt, log2L);
        if (nr.slice == KTBN< GUM_SCALAR >::ATEMPORAL)
          for (Size t = 0; t < T; ++t)
            traj[t * _nbVars_ + nr.col] = drawn;
        else traj[nr.slice * _nbVars_ + nr.col] = drawn;
      }
 
      // Phase 2: extend to T-1 by sliding the transition kernel forward one step at a time
      for (Size t = _k_; t < T; ++t) {
        for (const Idx kernelIdx: _kernel_) {
          const NodeRef& nr = _nodes_[kernelIdx];
          for (const ParentRef& pr: nr.parents) {
            const Size parentRow = pr.isAtemporal ? 0 : t - pr.lag;
            _inst_.chgVal(*pr.var, traj[parentRow * _nbVars_ + pr.col]);
          }
          traj[t * _nbVars_ + nr.col] = _drawVar_(*nr.var, *nr.cpt, log2L);
        }
      }
 
      log2Ls.push_back(log2L);
      const std::filesystem::path file = dir / (stem + std::to_string(i + 1) + ".csv");
      _writeTrajectory_(file.string(), traj, T, useLabels, csvSeparator, colOrder);
 
      if (hasListener) {
        const int p = int((i * 100) / nbSamples);
        if (p != progress) {
          progress = p;
          GUM_EMIT2(onProgress, progress, timer->step());
        }
      }
    }
 
    if (hasListener) {
      std::stringstream ss;
      ss << nbSamples << " trajectories generated in " << timer->step() << " s.";
      GUM_EMIT1(onStop, ss.str());
    }
 
    return log2Ls;
  }

Referenced by drawSamples(), and drawSamples().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _drawVar_()

template<GUM_Numeric GUM_SCALAR>

Idx gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::_drawVar_	(	const DiscreteVariable &	var,
		const Tensor< GUM_SCALAR > &	cpt,
		double &	log2likelihood )

private

inverse-CDF draw of var given the parents already set in inst; accumulates log2(P(drawn value)) into log2likelihood

Definition at line 164 of file KTBNDatabaseGenerator_tpl.h.

                                                                                                 {
    const double threshold = gum::randomProba();
    double       cumulProb = 0.0;
    for (_inst_.setFirstVar(var); !_inst_.end(); _inst_.incVar(var)) {
      cumulProb += cpt[_inst_];
      if (cumulProb > threshold) break;
    }
    if (_inst_.end()) _inst_.setLastVar(var);
    log2likelihood += std::log2(cpt[_inst_]);
    return _inst_.val(var);
  }

References _inst_, and gum::randomProba().

Referenced by _drawSamples_().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _label_()

template<GUM_Numeric GUM_SCALAR>

std::string gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::_label_	(	Idx	col,
		Idx	idx ) const

private

renders the label of modality idx of base column col (taking the discretized-label mode into account)

Definition at line 346 of file KTBNDatabaseGenerator_tpl.h.

                                                                               {
    const DiscreteVariable& v = *_vars_[col];
    if (v.varType() == VarType::DISCRETIZED) {
      switch (_discretizedLabelMode_) {
        case DiscretizedLabelMode::MEDIAN : return std::to_string(v.numerical(idx));
        case DiscretizedLabelMode::RANDOM :
          return std::to_string(static_cast< const IDiscretizedVariable& >(v).draw(idx));
        case DiscretizedLabelMode::INTERVAL : return v.label(idx);
        default : GUM_ERROR(FatalError, "unknown DiscretizedLabelMode")
      }
    }
    return v.label(idx);
  }

References _discretizedLabelMode_, _vars_, gum::DISCRETIZED, GUM_ERROR, INTERVAL, gum::DiscreteVariable::label(), MEDIAN, gum::DiscreteVariable::numerical(), RANDOM, and gum::DiscreteVariable::varType().

Referenced by _writeTrajectory_().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _writeTrajectory_()

template<GUM_Numeric GUM_SCALAR>

void gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::_writeTrajectory_	(	std::string_view	csvFileURL,
		const std::vector< Idx > &	traj,
		Size	nbTimeSlices,
		bool	useLabels,
		const std::string &	csvSeparator,
		const std::vector< Idx > &	colOrder ) const

private

writes one trajectory CSV (header + T rows) to csvFileURL. traj is the flat row-major buffer (T x nbVars) in canonical column order; colOrder gives the output column order.

Definition at line 361 of file KTBNDatabaseGenerator_tpl.h.

                                              {
    std::ofstream os(std::filesystem::path{csvFileURL}, std::ofstream::out);
    if (!os) GUM_ERROR(IOError, "could not open '" << csvFileURL << "' for writing")
 
    // header: one column per base variable, in the chosen output order
    bool firstCol = true;
    for (const Idx col: colOrder) {
      if (!firstCol) os << csvSeparator;
      os << _baseCols_[col];
      firstCol = false;
    }
    os << "\n";
 
    for (Size t = 0; t < nbTimeSlices; ++t) {
      const Size base = t * _nbVars_;
      firstCol        = true;
      for (const Idx col: colOrder) {
        if (!firstCol) os << csvSeparator;
        os << (useLabels ? _label_(col, traj[base + col]) : std::to_string(traj[base + col]));
        firstCol = false;
      }
      os << "\n";
    }
  }

References _baseCols_, _label_(), _nbVars_, and GUM_ERROR.

Referenced by _drawSamples_().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ drawSamples() [1/2]

template<GUM_Numeric GUM_SCALAR>

std::vector< double > gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::drawSamples	(	const std::vector< Size > &	nbTimeSlices,
		std::string_view	dirPath,
		std::string_view	csvBaseName,
		VarOrderMode	mode = VarOrderMode::RANDOM,
		bool	useLabels = true,
		std::string	csvSeparator = "," )

Like drawSamples(), but every trajectory may have its own horizon.

Parameters

nbTimeSlices	One horizon per trajectory; its size is the number of trajectories. Every entry must be \(\geq k\).
dirPath	Directory to write the CSV files into.
csvBaseName	Stem for each file name (index and .csv appended).
mode	The column order of the base variables.
useLabels	Render values as variable labels (else modality index).
csvSeparator	Column separator (must not contain a newline).

Returns: The log2-likelihood of each generated trajectory.

Exceptions

OperationNotAllowed if some entry of nbTimeSlices is smaller than \(k\).

Definition at line 200 of file KTBNDatabaseGenerator_tpl.h.

                                                                                              {
    // per-trajectory horizons: nbTimeSlices[i] is trajectory i's length
    return _drawSamples_(nbTimeSlices.size(),
                         0,
                         &nbTimeSlices,
                         dirPath,
                         csvBaseName,
                         mode,
                         useLabels,
                         csvSeparator);
  }

References _drawSamples_().

Here is the call graph for this function:

◆ drawSamples() [2/2]

template<GUM_Numeric GUM_SCALAR>

std::vector< double > gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::drawSamples	(	Size	nbSamples,
		Size	nbTimeSlices,
		std::string_view	dirPath,
		std::string_view	csvBaseName,
		VarOrderMode	mode = VarOrderMode::RANDOM,
		bool	useLabels = true,
		std::string	csvSeparator = "," )

Generates nbSamples independent trajectories, writing one CSV file per trajectory into dirPath.

File names are csvBaseName followed by the 1-based trajectory index and ".csv" (e.g. "traj1.csv", "traj2.csv", …). Each file has one column per base variable in the order chosen by mode, and nbTimeSlices data rows.

Parameters

nbSamples	The number of trajectories to generate.
nbTimeSlices	The horizon \(T\) shared by every trajectory. Must be \(\geq k\).
dirPath	Directory to write the CSV files into.
csvBaseName	Stem for each file name (index and .csv appended).
mode	The column order of the base variables.
useLabels	Render values as variable labels (else modality index).
csvSeparator	Column separator (must not contain a newline).

Returns: The log2-likelihood of each generated trajectory (size nbSamples).

Exceptions

OperationNotAllowed if nbTimeSlices is smaller than \(k\).

Definition at line 180 of file KTBNDatabaseGenerator_tpl.h.

                                                                                    {
    // fixed horizon: every trajectory shares nbTimeSlices (perTraj == nullptr)
    return _drawSamples_(nbSamples,
                         nbTimeSlices,
                         nullptr,
                         dirPath,
                         csvBaseName,
                         mode,
                         useLabels,
                         csvSeparator);
  }

References _drawSamples_().

Here is the call graph for this function:

◆ nbVars()

template<GUM_Numeric GUM_SCALAR>

INLINE Size gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::nbVars ( ) const

returns the number of base variable columns

Definition at line 72 of file KTBNDatabaseGenerator_tpl.h.

                                                                {
    return _nbVars_;
  }

References _nbVars_.

◆ operator=() [1/2]

template<GUM_Numeric GUM_SCALAR>

KTBNDatabaseGenerator & gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::operator= ( const KTBNDatabaseGenerator< GUM_SCALAR > & )

privatedelete

References KTBNDatabaseGenerator().

Here is the call graph for this function:

◆ operator=() [2/2]

template<GUM_Numeric GUM_SCALAR>

KTBNDatabaseGenerator & gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::operator= ( KTBNDatabaseGenerator< GUM_SCALAR > && )

privatedelete

References KTBNDatabaseGenerator().

Here is the call graph for this function:

◆ setDiscretizedLabelModeInterval()

template<GUM_Numeric GUM_SCALAR>

void gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::setDiscretizedLabelModeInterval ( )

set discretized-label rendering to the interval label "[min,max["

Definition at line 341 of file KTBNDatabaseGenerator_tpl.h.

                                                                            {
    _discretizedLabelMode_ = DiscretizedLabelMode::INTERVAL;
  }

References _discretizedLabelMode_, and INTERVAL.

◆ setDiscretizedLabelModeMedian()

template<GUM_Numeric GUM_SCALAR>

void gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::setDiscretizedLabelModeMedian ( )

set discretized-label rendering to the (deterministic) interval median

Definition at line 336 of file KTBNDatabaseGenerator_tpl.h.

                                                                          {
    _discretizedLabelMode_ = DiscretizedLabelMode::MEDIAN;
  }

References _discretizedLabelMode_, and MEDIAN.

◆ setDiscretizedLabelModeRandom()

template<GUM_Numeric GUM_SCALAR>

void gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::setDiscretizedLabelModeRandom ( )

set discretized-label rendering to a uniform random draw in the interval (this is the default; each labelled export then differs)

Definition at line 331 of file KTBNDatabaseGenerator_tpl.h.

                                                                          {
    _discretizedLabelMode_ = DiscretizedLabelMode::RANDOM;
  }

References _discretizedLabelMode_, and RANDOM.

◆ setVarOrderAntiTopological()

template<GUM_Numeric GUM_SCALAR>

void gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::setVarOrderAntiTopological ( std::vector< Idx > & colOrder ) const

private

builds the reverse of setVarOrderTopological()

Definition at line 460 of file KTBNDatabaseGenerator_tpl.h.

                                        {
    setVarOrderTopological(colOrder);
    std::reverse(colOrder.begin(), colOrder.end());
  }

References setVarOrderTopological().

Referenced by _drawSamples_().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setVarOrderRandomized()

template<GUM_Numeric GUM_SCALAR>

void gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::setVarOrderRandomized ( std::vector< Idx > & colOrder ) const

private

builds a uniformly random column order

Definition at line 393 of file KTBNDatabaseGenerator_tpl.h.

                                        {
    colOrder.resize(_nbVars_);
    std::iota(colOrder.begin(), colOrder.end(), 0);
    std::shuffle(colOrder.begin(), colOrder.end(), gum::randomGenerator());
  }

References _nbVars_, and gum::randomGenerator().

Referenced by _drawSamples_().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setVarOrderTopological()

template<GUM_Numeric GUM_SCALAR>

void gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::setVarOrderTopological ( std::vector< Idx > & colOrder ) const

private

builds a topological column order (transition-kernel projection)

Definition at line 401 of file KTBNDatabaseGenerator_tpl.h.

                                        {
    // The column order is a topological sort of the "contemporaneous" DAG over
    // base columns. Only two kinds of arc constrain the column order:
    //   * atemporal -> atemporal   — orders the atemporal block
    //   * same-slice kernel arcs   — lag-0 arcs at slice k-1; order the temporal block
    // Lagged arcs are resolved at sampling time, not here; atemporal -> temporal
    // arcs need no edge since every atemporal column already precedes every
    // temporal one (the blocks are emitted in that order below).
    std::vector< std::vector< Idx > > children(_nbVars_);
    std::vector< int >                indegree(_nbVars_, 0);
    std::vector< bool >               isAtemporal(_nbVars_, false);
 
    auto addEdge = [&](Idx parent, Idx child) {
      children[parent].push_back(child);
      ++indegree[child];
    };
 
    // (1) build the contemporaneous DAG, one arc set per block.
    const int lastSlice = int(_k_) - 1;
    for (const NodeRef& nf: _nodes_) {
      if (nf.slice == KTBN< GUM_SCALAR >::ATEMPORAL) {
        isAtemporal[nf.col] = true;
        for (const ParentRef& pr: nf.parents) {
          if (!pr.isAtemporal)
            GUM_ERROR(FatalError,
                      "temporal variable '"
                          << _baseCols_[pr.col] << "' is a parent of atemporal variable '"
                          << _baseCols_[nf.col] << "' — violates the k-DBN invariant")
          addEdge(pr.col, nf.col);
        }
      } else if (nf.slice == lastSlice) {
        for (const ParentRef& pr: nf.parents)
          if (!pr.isAtemporal && pr.lag == 0) addEdge(pr.col, nf.col);
      }
    }
 
    // (2) Kahn's sort of one block, seeded in ascending col order so the result
    //     is deterministic (the seed is canonical and edges follow _nodes_).
    auto topoSortBlock = [&](bool atempBlock) {
      std::queue< Idx > q;
      for (Idx c = 0; c < _nbVars_; ++c)
        if (isAtemporal[c] == atempBlock && indegree[c] == 0) q.push(c);
      while (!q.empty()) {
        const Idx cur = q.front();
        q.pop();
        colOrder.push_back(cur);
        for (const Idx ch: children[cur])
          if (--indegree[ch] == 0) q.push(ch);
      }
    };
 
    // (3) atemporal block first, then the temporal kernel order.
    colOrder.clear();
    topoSortBlock(true);
    topoSortBlock(false);
  }

References _baseCols_, _k_, _nbVars_, _nodes_, gum::KTBN< GUM_SCALAR >::ATEMPORAL, gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::ParentRef::col, GUM_ERROR, gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::ParentRef::isAtemporal, and gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::ParentRef::lag.

Referenced by _drawSamples_(), and setVarOrderAntiTopological().

Here is the caller graph for this function:

Member Data Documentation

◆ _baseCols_

template<GUM_Numeric GUM_SCALAR>

std::vector< std::string > gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::_baseCols_

private

col index -> base name (canonical column numbering)

Definition at line 227 of file KTBNDatabaseGenerator.h.

Referenced by _build_(), _writeTrajectory_(), and setVarOrderTopological().

◆ _discretizedLabelMode_

template<GUM_Numeric GUM_SCALAR>

DiscretizedLabelMode gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::_discretizedLabelMode_ = DiscretizedLabelMode::RANDOM

private

rendering of discretized variables when labels are requested

Definition at line 245 of file KTBNDatabaseGenerator.h.

Referenced by _label_(), setDiscretizedLabelModeInterval(), setDiscretizedLabelModeMedian(), and setDiscretizedLabelModeRandom().

◆ _inst_

template<GUM_Numeric GUM_SCALAR>

Instantiation gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::_inst_

private

a shared instantiation over all template variables, so we don't have to rebuild it for every draw

Definition at line 242 of file KTBNDatabaseGenerator.h.

Referenced by _build_(), _drawSamples_(), and _drawVar_().

◆ _k_

template<GUM_Numeric GUM_SCALAR>

Size gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::_k_

private

the order \(k\) of the k-DBN

Definition at line 221 of file KTBNDatabaseGenerator.h.

Referenced by KTBNDatabaseGenerator(), _build_(), _drawSamples_(), and setVarOrderTopological().

◆ _kernel_

template<GUM_Numeric GUM_SCALAR>

std::vector< Idx > gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::_kernel_

private

indices, in nodes, of the slice-(k-1) nodes (the transition kernel, drives Phase 2); already in topological order

Definition at line 238 of file KTBNDatabaseGenerator.h.

Referenced by _build_(), and _drawSamples_().

◆ _nbVars_

template<GUM_Numeric GUM_SCALAR>

Size gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::_nbVars_

private

number of base variable columns

Definition at line 224 of file KTBNDatabaseGenerator.h.

Referenced by _build_(), _drawSamples_(), _writeTrajectory_(), nbVars(), setVarOrderRandomized(), and setVarOrderTopological().

◆ _nodes_

template<GUM_Numeric GUM_SCALAR>

std::vector< NodeRef > gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::_nodes_

private

all template nodes in topological order (drives Phase 1, the bootstrap)

Definition at line 234 of file KTBNDatabaseGenerator.h.

Referenced by _build_(), _drawSamples_(), and setVarOrderTopological().

◆ _template_

template<GUM_Numeric GUM_SCALAR>

BayesNet< GUM_SCALAR > gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::_template_

private

the \(k\)-slice template (a small copy, independent of the horizon)

Definition at line 218 of file KTBNDatabaseGenerator.h.

Referenced by KTBNDatabaseGenerator(), and _build_().

◆ _vars_

template<GUM_Numeric GUM_SCALAR>

std::vector< const DiscreteVariable* > gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::_vars_

private

one representative variable per base column (same order as baseCols), pointing into template so it outlives the source k-DBN. Label rendering only.

Definition at line 231 of file KTBNDatabaseGenerator.h.

Referenced by _build_(), and _label_().

◆ onProgress

Signaler< Size, double > gum::ProgressNotifier::onProgress

inherited

Progression (percent) and time.

Definition at line 69 of file progressNotification.h.

Referenced by gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::_drawSamples_(), and gum::learning::BNDatabaseGenerator< GUM_SCALAR >::drawSamples().

◆ onStop

Signaler< std::string_view > gum::ProgressNotifier::onStop

inherited

with a possible explanation for stopping

Definition at line 72 of file progressNotification.h.

Referenced by gum::learning::KTBNDatabaseGenerator< GUM_SCALAR >::_drawSamples_(), and gum::learning::BNDatabaseGenerator< GUM_SCALAR >::drawSamples().

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

agrum/KTBN/database/KTBNDatabaseGenerator.h
agrum/KTBN/database/KTBNDatabaseGenerator_tpl.h

Classes

Public Types

Public Member Functions

Public Attributes

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ DiscretizedLabelMode

◆ VarOrderMode

Constructor & Destructor Documentation

◆ KTBNDatabaseGenerator() [1/3]

◆ ~KTBNDatabaseGenerator()

◆ KTBNDatabaseGenerator() [2/3]

◆ KTBNDatabaseGenerator() [3/3]

Member Function Documentation

◆ _build_()

◆ _decode_()

◆ _drawSamples_()

◆ _drawVar_()

◆ _label_()

◆ _writeTrajectory_()

◆ drawSamples() [1/2]

◆ drawSamples() [2/2]

◆ nbVars()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ setDiscretizedLabelModeInterval()

◆ setDiscretizedLabelModeMedian()

◆ setDiscretizedLabelModeRandom()

◆ setVarOrderAntiTopological()

◆ setVarOrderRandomized()

◆ setVarOrderTopological()

Member Data Documentation

◆ _baseCols_

◆ _discretizedLabelMode_

◆ _inst_

◆ _k_

◆ _kernel_

◆ _nbVars_

◆ _nodes_

◆ _template_

◆ _vars_

◆ onProgress

◆ onStop