KTBNAdaptiveLearner.h

Go to the documentation of this file.

/****************************************************************************
 *   This file is part of the aGrUM/pyAgrum library.                        *
 *                                                                          *
 *   Copyright (c) 2005-2026 by                                             *
 *       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 *
 *       - Christophe GONZALES(_at_AMU)                                     *
 *                                                                          *
 *   The aGrUM/pyAgrum library is free software; you can redistribute it    *
 *   and/or modify it under the terms of either :                           *
 *                                                                          *
 *    - the GNU Lesser General Public License as published by               *
 *      the Free Software Foundation, either version 3 of the License,      *
 *      or (at your option) any later version,                              *
 *    - the MIT license (MIT),                                              *
 *    - or both in dual license, as here.                                   *
 *                                                                          *
 *   (see https://agrum.gitlab.io/articles/dual-licenses-lgplv3mit.html)    *
 *                                                                          *
 *   This aGrUM/pyAgrum library is distributed in the hope that it will be  *
 *   useful, but WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,          *
 *   INCLUDING BUT NOT LIMITED TO THE WARRANTIES MERCHANTABILITY or FITNESS *
 *   FOR A PARTICULAR PURPOSE  AND NONINFRINGEMENT. IN NO EVENT SHALL THE   *
 *   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER *
 *   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,        *
 *   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR  *
 *   OTHER DEALINGS IN THE SOFTWARE.                                        *
 *                                                                          *
 *   See LICENCES for more details.                                         *
 *                                                                          *
 *   SPDX-FileCopyrightText: Copyright 2005-2026                            *
 *       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 *
 *       - Christophe GONZALES(_at_AMU)                                     *
 *   SPDX-License-Identifier: LGPL-3.0-or-later OR MIT                      *
 *                                                                          *
 *   Contact  : info_at_agrum_dot_org                                       *
 *   homepage : http://agrum.gitlab.io                                      *
 *   gitlab   : https://gitlab.com/agrumery/agrum                           *
 *                                                                          *
 ****************************************************************************/
 

 
#ifndef GUM_LEARNING_KTBN_ADAPTIVE_LEARNER_H
#define GUM_LEARNING_KTBN_ADAPTIVE_LEARNER_H
 
#include <limits>
#include <memory>
#include <set>
#include <string>
#include <tuple>
#include <utility>
#include <vector>
 
#include <agrum/agrum.h>
 
#include <agrum/KTBN/KTBN.h>
#include <agrum/KTBN/learning/KTBNLearner.h>
 
#include <string_view>
#include <unordered_set>
 
namespace gum {
 
  namespace learning {

    template < GUM_Numeric GUM_SCALAR >
    class KTBNAdaptiveLearner: public IKTBNLearner< GUM_SCALAR > {
      public:
      // #######################################################################
      // #######################################################################

      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);

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

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

      // #######################################################################
      // #######################################################################

      KTBN< GUM_SCALAR > learnKTBN() override;

      Size bestK() const;

      const std::vector< std::pair< Size, double > >& scorePerCandidateK() const;

      const std::vector< std::pair< std::string, std::string > >& latentVariables() const;

      // #######################################################################
      // #######################################################################

      enum class OrderScoreType { BIC, AIC, fNML };

      KTBNAdaptiveLearner< GUM_SCALAR >& useOrderScoreBIC();

      KTBNAdaptiveLearner< GUM_SCALAR >& useOrderScoreAIC();

      KTBNAdaptiveLearner< GUM_SCALAR >& useOrderScorefNML();

      // #######################################################################
      // #######################################################################

      KTBNAdaptiveLearner< GUM_SCALAR >& ignoreMissingSymbols(bool ignore = true);

      bool isIgnoringMissingSymbols() const;

      // #######################################################################
      // #######################################################################

      Size kMax() const;

      std::string checkScorePriorCompatibility() const;

      std::string toString() const;

      std::vector< std::tuple< std::string, std::string, std::string > > state() const;

      // #######################################################################
      // #######################################################################
 
      KTBNAdaptiveLearner< GUM_SCALAR >& useScoreAIC() override;
      KTBNAdaptiveLearner< GUM_SCALAR >& useScoreBD() override;
      KTBNAdaptiveLearner< GUM_SCALAR >& useScoreBDeu() override;
      KTBNAdaptiveLearner< GUM_SCALAR >& useScoreBIC() override;
      KTBNAdaptiveLearner< GUM_SCALAR >& useScoreLog2Likelihood() override;
      KTBNAdaptiveLearner< GUM_SCALAR >& useScoreMDL() override;
      void                               useScorefNML() override;

      // #######################################################################
      // #######################################################################
 
      KTBNAdaptiveLearner< GUM_SCALAR >& useGreedyHillClimbing() override;
      KTBNAdaptiveLearner< GUM_SCALAR >& useExtendedGreedyHillClimbing() override;
      KTBNAdaptiveLearner< GUM_SCALAR >& useLocalSearchWithTabuList(Size tabu_size   = 100,
                                                                    Size nb_decrease = 2) override;
      KTBNAdaptiveLearner< GUM_SCALAR >& useMIIC() override;

      // #######################################################################
      // #######################################################################
 
      KTBNAdaptiveLearner< GUM_SCALAR >& useNMLCorrection() override;
      KTBNAdaptiveLearner< GUM_SCALAR >& useMDLCorrection() override;
      KTBNAdaptiveLearner< GUM_SCALAR >& useNoCorrection() override;

      // #######################################################################
      // #######################################################################
 
      KTBNAdaptiveLearner< GUM_SCALAR >& useSmoothingPrior(double weight = 1.0) override;

      // #######################################################################
      // #######################################################################
 
      KTBNAdaptiveLearner< GUM_SCALAR >& addForbiddenArc(std::string_view tailNode,
                                                         std::string_view headNode) override;
      KTBNAdaptiveLearner< GUM_SCALAR >& addForbiddenArc(std::string_view tailBase,
                                                         int              tailSlice,
                                                         std::string_view headBase,
                                                         int              headSlice) override;
      KTBNAdaptiveLearner< GUM_SCALAR >& eraseForbiddenArc(std::string_view tailNode,
                                                           std::string_view headNode) override;
      KTBNAdaptiveLearner< GUM_SCALAR >& eraseForbiddenArc(std::string_view tailBase,
                                                           int              tailSlice,
                                                           std::string_view headBase,
                                                           int              headSlice) override;
 
      KTBNAdaptiveLearner< GUM_SCALAR >& addMandatoryArc(std::string_view tailNode,
                                                         std::string_view headNode) override;
      KTBNAdaptiveLearner< GUM_SCALAR >& addMandatoryArc(std::string_view tailBase,
                                                         int              tailSlice,
                                                         std::string_view headBase,
                                                         int              headSlice) override;
      KTBNAdaptiveLearner< GUM_SCALAR >& eraseMandatoryArc(std::string_view tailNode,
                                                           std::string_view headNode) override;
      KTBNAdaptiveLearner< GUM_SCALAR >& eraseMandatoryArc(std::string_view tailBase,
                                                           int              tailSlice,
                                                           std::string_view headBase,
                                                           int              headSlice) override;

      KTBNAdaptiveLearner< GUM_SCALAR >&
          addForbiddenKernelArc(std::string_view tailBase, int lag, std::string_view headBase);

      KTBNAdaptiveLearner< GUM_SCALAR >&
          eraseForbiddenKernelArc(std::string_view tailBase, int lag, std::string_view headBase);

      KTBNAdaptiveLearner< GUM_SCALAR >&
          addMandatoryKernelArc(std::string_view tailBase, int lag, std::string_view headBase);

      KTBNAdaptiveLearner< GUM_SCALAR >&
          eraseMandatoryKernelArc(std::string_view tailBase, int lag, std::string_view headBase);
 
      KTBNAdaptiveLearner< GUM_SCALAR >&
          addForbiddenIntraSliceArc(std::string_view tailBase, std::string_view headBase) override;
      KTBNAdaptiveLearner< GUM_SCALAR >&
          eraseForbiddenIntraSliceArc(std::string_view tailBase,
                                      std::string_view headBase) override;
 
      KTBNAdaptiveLearner< GUM_SCALAR >&
          addForbiddenArcAllSlices(std::string_view tailBase, std::string_view headBase) override;
      KTBNAdaptiveLearner< GUM_SCALAR >&
          eraseForbiddenArcAllSlices(std::string_view tailBase, std::string_view headBase) override;
 
      KTBNAdaptiveLearner< GUM_SCALAR >& addNoParentNode(std::string_view base, int slice) override;
      KTBNAdaptiveLearner< GUM_SCALAR >& addNoParentNode(std::string_view name) override;
      KTBNAdaptiveLearner< GUM_SCALAR >& eraseNoParentNode(std::string_view base,
                                                           int              slice) override;
      KTBNAdaptiveLearner< GUM_SCALAR >& eraseNoParentNode(std::string_view name) override;
 
      KTBNAdaptiveLearner< GUM_SCALAR >& addNoChildrenNode(std::string_view base,
                                                           int              slice) override;
      KTBNAdaptiveLearner< GUM_SCALAR >& addNoChildrenNode(std::string_view name) override;
      KTBNAdaptiveLearner< GUM_SCALAR >& eraseNoChildrenNode(std::string_view base,
                                                             int              slice) override;
      KTBNAdaptiveLearner< GUM_SCALAR >& eraseNoChildrenNode(std::string_view name) override;
 
      KTBNAdaptiveLearner< GUM_SCALAR >& addPossibleEdge(std::string_view tailBase,
                                                         int              tailSlice,
                                                         std::string_view headBase,
                                                         int              headSlice) override;
      KTBNAdaptiveLearner< GUM_SCALAR >& addPossibleEdge(std::string_view tail,
                                                         std::string_view head) override;
      KTBNAdaptiveLearner< GUM_SCALAR >& erasePossibleEdge(std::string_view tailBase,
                                                           int              tailSlice,
                                                           std::string_view headBase,
                                                           int              headSlice) override;
      KTBNAdaptiveLearner< GUM_SCALAR >& erasePossibleEdge(std::string_view tail,
                                                           std::string_view head) override;
 
      KTBNAdaptiveLearner< GUM_SCALAR >& allowArcAdditions(bool allow = true) override;
      KTBNAdaptiveLearner< GUM_SCALAR >& allowArcDeletions(bool allow = true) override;
      KTBNAdaptiveLearner< GUM_SCALAR >& allowArcReversals(bool allow = true) override;
      KTBNAdaptiveLearner< GUM_SCALAR >& setMaxIndegree(Size max_indegree) override;

 
      private:
      // ----- data source (kept so a KTBNLearner can be built per candidate k) -----

      std::string _dirPath_;

      std::string _csvBaseName_;

      Size _nbSamples_;

      Size _kMax_;

      Size _kMin_{2};

      std::unordered_set< std::string > _atemporalVars_;

      std::unordered_set< std::string > _baseNames_;

      std::vector< std::string > _missingSymbols_;

      bool _ignoreMissingSymbols_{false};

      bool _induceTypes_;

      std::unique_ptr< BayesNet< GUM_SCALAR > > _prior_bn_;
 
      // ----- recorded state parameters (replayed on each candidate k) -----
      // Defaults mirror IBNLearner's own defaults, so an unconfigured
      // KTBNAdaptiveLearner behaves like an unconfigured KTBNLearner.

      IBNLearner::ScoreType _score_{IBNLearner::ScoreType::BDeu};

      OrderScoreType _orderScore_{OrderScoreType::BIC};

      IBNLearner::AlgoType _algo_{IBNLearner::AlgoType::MIIC};

      Size _tabuSize_{100};
      Size _nbDecrease_{2};

      CorrectedMutualInformation::KModeTypes _correction_{
          CorrectedMutualInformation::KModeTypes::MDL};

      IBNLearner::BNLearnerPriorType _prior_{IBNLearner::BNLearnerPriorType::NO_prior};
      double                         _priorWeight_{1.0};

      bool _allowAdditions_{true};
      bool _allowDeletions_{true};
      bool _allowReversals_{true};
      Size _maxIndegree_{std::numeric_limits< Size >::max()};
 
      // ----- recorded constraints (replayed on each candidate k) -----
      // Everything is stored by name: NodeIds are meaningless here because the
      // internal NodeId spaces differ from one candidate k to another. Arcs and
      // edges are stored as engine-name pairs ("X[1]", "C", ...); the per-base
      // constraints (intra-slice / all-slices) are stored as base-name pairs.

      std::set< std::pair< std::string, std::string > > _forbiddenArcs_;

      std::set< std::pair< std::string, std::string > > _mandatoryArcs_;

      std::set< std::pair< std::string, std::string > > _possibleEdges_;

      std::set< std::pair< std::string, std::string > > _forbiddenIntraSliceArcs_;

      std::set< std::pair< std::string, std::string > > _forbiddenArcsAllSlices_;

      std::set< std::tuple< std::string, std::string, int > > _forbiddenKernelArcs_;

      std::set< std::tuple< std::string, std::string, int > > _mandatoryKernelArcs_;

      std::set< std::string > _noParentNodes_;

      std::set< std::string > _noChildrenNodes_;

      Size _bestK_{0};

      std::vector< std::pair< std::string, std::string > > _bestLatentVariables_;

      std::vector< std::pair< Size, double > > _scorePerCandidateK_;
 
      // ----- construction (runs once, in the constructor) -----

      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);
 
      // ----- name encoding -----

      const std::unordered_set< std::string >& _atemporalVarNames_() const override;

      bool _isKnownBase_(std::string_view base) const override;

      using IKTBNLearner< GUM_SCALAR >::_encode_;
      using IKTBNLearner< GUM_SCALAR >::_determineNode_;
      using IKTBNLearner< GUM_SCALAR >::_checkBaseIsTemporal_;
 
      // ----- validation -----

      void _verifyBase_(std::string_view base, int slice) const;

      void _verifyKernelArc_(std::string_view tailBase, std::string_view headBase, int lag) const;
 
      // ----- candidate-range bookkeeping -----

      void _raiseKMinForSlice_(int slice);

      void _recomputeKMin_();
 
      // ----- configuration replay (used by learnKTBN() for each candidate k) -----

      void _applyConfig_(KTBNLearner< GUM_SCALAR >& learner) const;

      void _applyConstraints_(KTBNLearner< GUM_SCALAR >& learner, Size k) const;
 
      // ----- model selection (learnKTBN() helper) -----

      template < typename PerInstance, typename PerNodeFinal >
      void _forEachScoredNode_(const KTBN< GUM_SCALAR >& net,
                               PerInstance               perInstance,
                               PerNodeFinal              perNodeFinal) const;

      double _log2Likelihood_(const KTBN< GUM_SCALAR >& net) const;

      double _countParameters_(const KTBN< GUM_SCALAR >& net) const;

      double _fNMLScore_(const KTBN< GUM_SCALAR >& net) const;

      double _orderSelectionScore_(const KTBN< GUM_SCALAR >& net, double logN) const;

      mutable VariableLog2ParamComplexity _ctable_;
 
      // forbidden copies / moves (same policy as KTBNLearner)
      KTBNAdaptiveLearner(const KTBNAdaptiveLearner< GUM_SCALAR >&) = delete;
      KTBNAdaptiveLearner(KTBNAdaptiveLearner< GUM_SCALAR >&&)      = delete;
      KTBNAdaptiveLearner< GUM_SCALAR >& operator=(const KTBNAdaptiveLearner< GUM_SCALAR >&)
          = delete;
      KTBNAdaptiveLearner< GUM_SCALAR >& operator=(KTBNAdaptiveLearner< GUM_SCALAR >&&) = delete;
    };
 
#ifndef GUM_NO_EXTERN_TEMPLATE_CLASS
    extern template class GUM_PUBLIC_KTBN KTBNAdaptiveLearner< double >;
#endif
 
  } /* namespace learning */
} /* namespace gum */
 
#include <agrum/KTBN/learning/KTBNAdaptiveLearner_tpl.h>
 
#endif /* GUM_LEARNING_KTBN_ADAPTIVE_LEARNER_H */