IBNLearner.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_GENERIC_BN_LEARNER_H
#define GUM_LEARNING_GENERIC_BN_LEARNER_H
 
#include <memory>
#include <sstream>
 
#include <agrum/agrum.h>
 
#include <agrum/base/database/DBInitializerFromCSV.h>
#include <agrum/base/database/DBRowGenerator4CompleteRows.h>
#include <agrum/base/database/DBRowGeneratorEM.h>
#include <agrum/base/stattests/indepTestChi2.h>
#include <agrum/base/stattests/indepTestG2.h>
#include <agrum/base/stattests/priors/DirichletPriorFromDatabase.h>
#include <agrum/BN/algorithms/essentialGraph.h>
#include <agrum/BN/learning/constraints/structuralConstraintDAG.h>
#include <agrum/BN/learning/constraints/structuralConstraintForbiddenArcs.h>
#include <agrum/BN/learning/constraints/structuralConstraintIndegree.h>
#include <agrum/BN/learning/constraints/structuralConstraintMandatoryArcs.h>
#include <agrum/BN/learning/constraints/structuralConstraintNoChildrenNodes.h>
#include <agrum/BN/learning/constraints/structuralConstraintNoParentNodes.h>
#include <agrum/BN/learning/constraints/structuralConstraintPossibleEdges.h>
#include <agrum/BN/learning/constraints/structuralConstraintSliceOrder.h>
#include <agrum/BN/learning/constraints/structuralConstraintTabuList.h>
#include <agrum/BN/learning/constraints/structuralConstraintTotalOrder.h>
#include <agrum/BN/learning/FCI.h>
#include <agrum/BN/learning/greedyThickThinning.h>
#include <agrum/BN/learning/K2.h>
#include <agrum/BN/learning/localSearchWithTabuList.h>
#include <agrum/BN/learning/paramUtils/DAG2BNLearner.h>
#include <agrum/BN/learning/paramUtils/paramEstimatorML.h>
#include <agrum/BN/learning/PC.h>
#include <agrum/BN/learning/scores/scoreAIC.h>
#include <agrum/BN/learning/scores/scoreBD.h>
#include <agrum/BN/learning/scores/scoreBDeu.h>
#include <agrum/BN/learning/scores/scorefNML.h>
#include <agrum/BN/learning/scores/scoreK2.h>
#include <agrum/BN/learning/SimpleMiic.h>
#include <agrum/BN/learning/structureUtils/graphChangesGenerator4DiGraph.h>
#include <agrum/BN/learning/structureUtils/graphChangesGenerator4K2.h>
#include <agrum/BN/learning/structureUtils/graphChangesSelector4DiGraph.h>
 
namespace gum::learning {
  class BNLearnerListener;

  class GUM_PUBLIC_BN IBNLearner:
      public IApproximationSchemeConfiguration,
      public ThreadNumberManager {
    public:
    enum class ScoreType { AIC, BD, BDeu, BIC, fNML, K2, LOG2LIKELIHOOD, MDL };

    enum class ParamEstimatorType { ML };

    enum class BNLearnerPriorType {
      NO_prior,
      SMOOTHING,
      DIRICHLET_FROM_DATABASE,
      DIRICHLET_FROM_BAYESNET,
      BDEU
    };

    enum class AlgoType {
      K2,
      GREEDY_HILL_CLIMBING,
      LOCAL_SEARCH_WITH_TABU_LIST,
      MIIC,
      PC,
      FCI,
      EXTENDED_GREEDY_HILL_CLIMBING,
      GREEDY_THICK_THINNING
    };

    static constexpr double default_EM_noise{0.1};

    class GUM_PUBLIC_BN Database {
      public:
      // ########################################################################
      // ########################################################################


      explicit Database(std::string_view                  file,
                        const std::vector< std::string >& missing_symbols,
                        const bool                        induceTypes = false);


      explicit Database(const DatabaseTable& db);


      Database(std::string_view                  filename,
               const Database&                   score_database,
               const std::vector< std::string >& missing_symbols);


      template < GUM_Numeric GUM_SCALAR >
      Database(std::string_view                   filename,
               const gum::BayesNet< GUM_SCALAR >& bn,
               const std::vector< std::string >&  missing_symbols);

      Database(const Database& from);

      Database(Database&& from);

      ~Database();

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

      Database& operator=(const Database& from);

      Database& operator=(Database&& from);

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

      DBRowGeneratorParser& parser();

      const std::vector< std::size_t >& domainSizes() const;

      const std::vector< std::string >& names() const;

      NodeId idFromName(std::string_view var_name) const;

      const std::string& nameFromId(NodeId id) const;

      const DatabaseTable& databaseTable() const;

      void setDatabaseWeight(const double new_weight);

      const Bijection< NodeId, std::size_t >& nodeId2Columns() const;

      const std::vector< std::string >& missingSymbols() const;

      std::size_t nbRows() const;

      std::size_t size() const;


      void setWeight(const std::size_t i, const double weight);


      double weight(const std::size_t i) const;

      double weight() const;

 
      protected:
      DatabaseTable _database_;

      DBRowGeneratorParser* _parser_{nullptr};

      std::vector< std::size_t > _domain_sizes_;

      Bijection< NodeId, std::size_t > _nodeId2cols_;

      Size _max_threads_number_{gum::getNumberOfThreads()};

      Size _min_nb_rows_per_thread_{100};
 
      private:
      // returns the set of variables as a BN. This is convenient for
      // the constructors of prior Databases
      template < GUM_Numeric GUM_SCALAR >
      BayesNet< GUM_SCALAR > _BNVars_() const;
    };
 
    // ##########################################################################
    // ##########################################################################

    IBNLearner(std::string_view                  filename,
               const std::vector< std::string >& missingSymbols,
               bool                              induceTypes = true);
 
    explicit IBNLearner(const DatabaseTable& db);

    template < GUM_Numeric GUM_SCALAR >
    IBNLearner(std::string_view                   filename,
               const gum::BayesNet< GUM_SCALAR >& src,
               const std::vector< std::string >&  missing_symbols);

    IBNLearner(const IBNLearner&);

    IBNLearner(IBNLearner&&);

    ~IBNLearner() override;

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

    IBNLearner& operator=(const IBNLearner&);

    IBNLearner& operator=(IBNLearner&&);

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

    DAG learnDAG();

    PDAG learnPDAG();

    PAG learnPAG();

    void setInitialDAG(const DAG&);

    DAG initialDAG();

    const std::vector< std::string >& names() const;

    const std::vector< std::size_t >& domainSizes() const;
    Size                              domainSize(NodeId var) const;
    Size                              domainSize(std::string_view var) const;


    NodeId idFromName(std::string_view var_name) const;

    const DatabaseTable& database() const;

    void setDatabaseWeight(const double new_weight);


    void setRecordWeight(const std::size_t i, const double weight);


    double recordWeight(const std::size_t i) const;

    double databaseWeight() const;

    const std::string& nameFromId(NodeId id) const;


    void useDatabaseRanges(const std::vector< std::pair< std::size_t, std::size_t > >& new_ranges);

    void clearDatabaseRanges();


    const std::vector< std::pair< std::size_t, std::size_t > >& databaseRanges() const;


    std::pair< std::size_t, std::size_t > useCrossValidationFold(const std::size_t learning_fold,
                                                                 const std::size_t k_fold);
 

    std::pair< double, double >
        chi2(NodeId id1, NodeId id2, const std::vector< NodeId >& knowing = {});
    std::pair< double, double > chi2(std::string_view                  name1,
                                     std::string_view                  name2,
                                     const std::vector< std::string >& knowing = {});

    std::pair< double, double >
        G2(NodeId id1, NodeId id2, const std::vector< NodeId >& knowing = {});
    std::pair< double, double > G2(std::string_view                  name1,
                                   std::string_view                  name2,
                                   const std::vector< std::string >& knowing = {});

    double logLikelihood(const std::vector< NodeId >& vars,
                         const std::vector< NodeId >& knowing = {});

    double logLikelihood(const std::vector< std::string >& vars,
                         const std::vector< std::string >& knowing = {});

    double mutualInformation(NodeId id1, NodeId id2, const std::vector< NodeId >& knowing = {});

    double mutualInformation(std::string_view                  var1,
                             std::string_view                  var2,
                             const std::vector< std::string >& knowing = {});
 

    double correctedMutualInformation(NodeId                       id1,
                                      NodeId                       id2,
                                      const std::vector< NodeId >& knowing = {});

    double correctedMutualInformation(std::string_view                  var1,
                                      std::string_view                  var2,
                                      const std::vector< std::string >& knowing = {});

    double score(NodeId vars, const std::vector< NodeId >& knowing = {});

    double score(std::string_view vars, const std::vector< std::string >& knowing = {});

    std::vector< double > rawPseudoCount(const std::vector< NodeId >& vars);

    std::vector< double > rawPseudoCount(const std::vector< std::string >& vars);
    Size nbCols() const;

    Size nbRows() const;

    void useEM(const double epsilon, const double noise = default_EM_noise);

    void useEMWithRateCriterion(const double epsilon, const double noise = default_EM_noise);

    void useEMWithDiffCriterion(const double epsilon, const double noise = default_EM_noise);

    void forbidEM();

    bool isUsingEM() const;

    EMApproximationScheme& EM();

    ApproximationSchemeSTATE EMState() const;

    std::string EMStateMessage() const;

    bool hasMissingValues() const;

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

    void useScoreAIC();

    void useScoreBD();

    void useScoreBDeu();

    void useScoreBIC();

    void useScorefNML();

    void useScoreK2();

    void useScoreLog2Likelihood();

    void useScoreMDL();

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

    void useNoPrior();


    void useBDeuPrior(double weight = 1.0);


    void useSmoothingPrior(double weight = 1);

    void useDirichletPrior(std::string_view filename, double weight = 1);


    std::string checkScorePriorCompatibility() const;
 
    // ##########################################################################
    // ##########################################################################

    void useGreedyHillClimbing();


    void useExtendedGreedyHillClimbing();


    void useLocalSearchWithTabuList(Size tabu_size = 100, Size nb_decrease = 2);

    void useK2(const Sequence< NodeId >& order);

    void useK2(const std::vector< NodeId >& order);

    void useMIIC();

    void usePC();

    void useFCI();

    void useGreedyThickThinning();

    void setGreedyThickThinningReversals(bool allow);

    bool greedyThickThinningReversals() const;

    bool isConstraintBased() const;

    bool isScoreBased() const;
 
    // ##########################################################################
    // ##########################################################################

    void allowArcAdditions(bool allow = true);

    void allowArcDeletions(bool allow = true);

    void allowArcReversals(bool allow = true);

    void allowArcTriangleDeletions(bool allow = true);

 
    // ##########################################################################
    // ##########################################################################
    void useNMLCorrection();
    void useMDLCorrection();
    void useNoCorrection();

    std::vector< Arc > latentVariables() const;

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

    void useChi2Test();

    void useG2Test();

    void setPCAlpha(double alpha);

    void setPCStable(bool stable);

    void setPCMaxCondSetSize(Size max_k);

    void setPCUnshieldedColliderSorted(bool sorted);

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

    void useFCIChi2Test();

    void useFCIG2Test();

    void setFCIAlpha(double alpha);

    void setFCIMaxPathLength(Size max_len);

    void setFCIExhaustiveSepSet(bool exhaustive);

    bool fciExhaustiveSepSet() const;

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

    void setMaxIndegree(Size max_indegree);

    void setSliceOrder(const NodeProperty< NodeId >& slice_order);

    void setSliceOrder(const std::vector< std::vector< std::string > >& slices);

    void unsetSliceOrder();

    void setTotalOrder(const Sequence< NodeId >& order);
    void setTotalOrder(const std::vector< std::string >& order);

    void unsetTotalOrder();


    void setForbiddenArcs(const ArcSet& set);

    void addForbiddenArc(const Arc& arc);
    void addForbiddenArc(NodeId tail, NodeId head);
    void addForbiddenArc(std::string_view tail, std::string_view head);

    void eraseForbiddenArc(const Arc& arc);
    void eraseForbiddenArc(NodeId tail, NodeId head);
    void eraseForbiddenArc(std::string_view tail, std::string_view head);

    void setMandatoryArcs(const ArcSet& set);

    void addMandatoryArc(const Arc& arc);
    void addMandatoryArc(NodeId tail, NodeId head);
    void addMandatoryArc(std::string_view tail, std::string_view head);

    void eraseMandatoryArc(const Arc& arc);
    void eraseMandatoryArc(NodeId tail, NodeId head);
    void eraseMandatoryArc(std::string_view tail, std::string_view head);

    void addNoParentNode(NodeId node);
    void addNoParentNode(std::string_view node);

    void eraseNoParentNode(NodeId node);
    void eraseNoParentNode(std::string_view node);

    void addNoChildrenNode(NodeId node);
    void addNoChildrenNode(std::string_view node);

    void eraseNoChildrenNode(NodeId node);
    void eraseNoChildrenNode(std::string_view node);

    void setPossibleEdges(const EdgeSet& set);
    void setPossibleSkeleton(const UndiGraph& skeleton);

    void addPossibleEdge(const Edge& edge);
    void addPossibleEdge(NodeId tail, NodeId head);
    void addPossibleEdge(std::string_view tail, std::string_view head);

    void erasePossibleEdge(const Edge& edge);
    void erasePossibleEdge(NodeId tail, NodeId head);
    void erasePossibleEdge(std::string_view tail, std::string_view head);

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


    void setNumberOfThreads(Size nb) override;

 
    protected:
    PAG  learnPAG_();
    PDAG learnPDAG_();

    void _setPriorWeight_(double weight);

    bool inducedTypes_{false};

    ScoreType scoreType_{ScoreType::BDeu};

    Score* score_{nullptr};

    ParamEstimatorType paramEstimatorType_{ParamEstimatorType::ML};

    bool useEM_{false};

    double noiseEM_{0.1};

    CorrectedMutualInformation* mutualInfo_{nullptr};

    BNLearnerPriorType priorType_{BNLearnerPriorType::NO_prior};

    Prior* prior_{nullptr};
 
    NoPrior* noPrior_{nullptr};

    double priorWeight_{1.0f};

    StructuralConstraintSliceOrder constraintSliceOrder_;

    StructuralConstraintTotalOrder constraintTotalOrder_;

    StructuralConstraintIndegree constraintIndegree_;

    StructuralConstraintTabuList constraintTabuList_;

    StructuralConstraintForbiddenArcs constraintForbiddenArcs_;

    StructuralConstraintPossibleEdges constraintPossibleEdges_;

    StructuralConstraintMandatoryArcs constraintMandatoryArcs_;

    StructuralConstraintNoParentNodes constraintNoParentNodes_;

    StructuralConstraintNoChildrenNodes constraintNoChildrenNodes_;

    AlgoType selectedAlgo_{AlgoType::MIIC};

    bool allowArcAdditions_{true};

    bool allowArcDeletions_{true};

    bool allowArcReversals_{true};

    bool allowArcTriangleDeletions_{true};

    K2 algoK2_;

    SimpleMiic algoSimpleMiic_;

    Miic algoMiic_;

    typename CorrectedMutualInformation::KModeTypes kmodeMiic_{
        CorrectedMutualInformation::KModeTypes::MDL};

    gum::learning::PC algoPC_;

    enum class IndepTestType { Chi2, G2 };
    IndepTestType indepTestTypePC_{IndepTestType::Chi2};

    IndependenceTest* indepTestPC_{nullptr};

    double alphaPc_{0.05};
    bool   stablePc_{true};
    Size   maxCondSetSizePc_{Size(-1)};
    bool   sortedUCPc_{false};

    gum::learning::FCI algoFCI_;

    IndepTestType indepTestTypeFCI_{IndepTestType::Chi2};

    IndependenceTest* indepTestFCI_{nullptr};

    double alphaFci_{0.05};
    Size   maxPathLengthFci_{Size(-1)};
    bool   exhaustiveSepSetFci_{false};

    DAG2BNLearner dag2BN_;

    GreedyHillClimbing greedyHillClimbing_;

    GreedyHillClimbing extendedGreedyHillClimbing_;

    GreedyThickThinning greedyThickThinning_;

    LocalSearchWithTabuList localSearchWithTabuList_;

    Database scoreDatabase_;

    std::vector< std::pair< std::size_t, std::size_t > > ranges_;

    Database* priorDatabase_{nullptr};

    std::string priorDbname_;

    DAG initialDag_;

    std::string filename_{"-"};
 
    // size of the tabu list
    Size nbDecreasingChanges_{2};
 
    // the current algorithm as an approximationScheme
    const ApproximationScheme* currentAlgorithm_{nullptr};

    static DatabaseTable readFile_(std::string_view                  filename,
                                   const std::vector< std::string >& missing_symbols);

    static void isCSVFileName_(std::string_view filename);

    virtual void createPrior_() = 0;

    void createScore_();

    ParamEstimator* createParamEstimator_(const DBRowGeneratorParser& parser,
                                          bool take_into_account_score = true);

    DAG learnDag_();

    MixedGraph prepareSimpleMiic_();

    MixedGraph prepareMiic_();

    MixedGraph preparePC_();

    MixedGraph prepareFCI_();

    PriorType getPriorType_() const;

    void createCorrectedMutualInformation_();
 
    public:
    // ##########################################################################
    // ##########################################################################
    // in order to not pollute the proper code of IBNLearner, we
    // directly
    // implement those
    // very simples methods here.
    void setCurrentApproximationScheme(const ApproximationScheme* approximationScheme);
 
    void distributeProgress(const ApproximationScheme* approximationScheme,
                            Size                       pourcent,
                            double                     error,
                            double                     time);

    void distributeStop(const ApproximationScheme* approximationScheme, std::string_view message);


    void setEpsilon(double eps) override;

    double epsilon() const override;

    void disableEpsilon() override;

    void enableEpsilon() override;

    bool isEnabledEpsilon() const override;


    void setMinEpsilonRate(double rate) override;

    double minEpsilonRate() const override;

    void disableMinEpsilonRate() override;

    void enableMinEpsilonRate() override;

    bool isEnabledMinEpsilonRate() const override;


    void setMaxIter(Size max) override;

    Size maxIter() const override;

    void disableMaxIter() override;

    void enableMaxIter() override;

    bool isEnabledMaxIter() const override;



    void setMaxTime(double timeout) override;

    double maxTime() const override;

    double currentTime() const override;

    void disableMaxTime() override;
 
    void enableMaxTime() override;

    bool isEnabledMaxTime() const override;


    void setPeriodSize(Size p) override;
 
    Size periodSize() const override;


    void setVerbosity(bool v) override;
 
    bool verbosity() const override;


 
    ApproximationSchemeSTATE stateApproximationScheme() const override;

    Size nbrIterations() const override;

    const std::vector< double >& history() const override;

 


    void EMsetEpsilon(double eps);


    double EMEpsilon() const;

    void EMdisableEpsilon();

    void EMenableEpsilon();

    bool EMisEnabledEpsilon() const;

    void EMsetMinEpsilonRate(double rate);

    double EMMinEpsilonRate() const;

    void EMdisableMinEpsilonRate();

    void EMenableMinEpsilonRate();

    bool EMisEnabledMinEpsilonRate() const;

    void EMsetMaxIter(Size max);

    Size EMMaxIter() const;

    void EMdisableMaxIter();

    void EMenableMaxIter();

    bool EMisEnabledMaxIter() const;

    void EMsetMaxTime(double timeout);

    double EMMaxTime() const;

    double EMCurrentTime() const;

    void EMdisableMaxTime();
 
    void EMenableMaxTime();

    bool EMisEnabledMaxTime() const;

    void EMsetPeriodSize(Size p);
 
    Size EMPeriodSize() const;

    void EMsetVerbosity(bool v);

    bool EMVerbosity() const;

    ApproximationSchemeSTATE EMStateApproximationScheme() const;

    Size EMnbrIterations() const;

    const std::vector< double >& EMHistory() const;

  };
 
  /* namespace learning */
}   // namespace gum::learning

#ifndef GUM_NO_INLINE
#  include <agrum/BN/learning/BNLearnUtils/IBNLearner_inl.h>
#endif /* GUM_NO_INLINE */
 
#include <agrum/BN/learning/BNLearnUtils/IBNLearner_tpl.h>
 
#endif /* GUM_LEARNING_GENERIC_BN_LEARNER_H */