genericBNLearner.h

Go to the documentation of this file.

/***************************************************************************
 *   Copyright (C) 2005 by Christophe GONZALES and Pierre-Henri WUILLEMIN  *
 *   {prenom.nom}@lip6.fr                                                  *
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 *   This program is distributed in the hope that it wil be useful,        *
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
 *   GNU General Public License for more details.                          *
 *                                                                         *
 *   You should have received a copy of the GNU General Public License     *
 *   along with this program; if not, write to the                         *
 *   Free Software Foundation, Inc.,                                       *
 *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
 ***************************************************************************/
#ifndef GUM_LEARNING_GENERIC_BN_LEARNER_H
#define GUM_LEARNING_GENERIC_BN_LEARNER_H

#include <sstream>
#include <memory>

#include <agrum/BN/BayesNet.h>
#include <agrum/agrum.h>
#include <agrum/core/bijection.h>
#include <agrum/core/sequence.h>
#include <agrum/graphs/DAG.h>

#include <agrum/learning/database/DBTranslator4LabelizedVariable.h>
#include <agrum/learning/database/DBRowGeneratorParser.h>
#include <agrum/learning/database/DBInitializerFromCSV.h>
#include <agrum/learning/database/databaseTable.h>
#include <agrum/learning/database/DBRowGeneratorParser.h>
#include <agrum/learning/database/DBRowGenerator4CompleteRows.h>
#include <agrum/learning/database/DBRowGeneratorEM.h>
#include <agrum/learning/database/DBRowGeneratorSet.h>

#include <agrum/learning/scores_and_tests/scoreAIC.h>
#include <agrum/learning/scores_and_tests/scoreBD.h>
#include <agrum/learning/scores_and_tests/scoreBDeu.h>
#include <agrum/learning/scores_and_tests/scoreBIC.h>
#include <agrum/learning/scores_and_tests/scoreK2.h>
#include <agrum/learning/scores_and_tests/scoreLog2Likelihood.h>

#include <agrum/learning/aprioris/aprioriDirichletFromDatabase.h>
#include <agrum/learning/aprioris/aprioriNoApriori.h>
#include <agrum/learning/aprioris/aprioriSmoothing.h>
#include <agrum/learning/aprioris/aprioriBDeu.h>

#include <agrum/learning/constraints/structuralConstraintDAG.h>
#include <agrum/learning/constraints/structuralConstraintDiGraph.h>
#include <agrum/learning/constraints/structuralConstraintForbiddenArcs.h>
#include <agrum/learning/constraints/structuralConstraintIndegree.h>
#include <agrum/learning/constraints/structuralConstraintMandatoryArcs.h>
#include <agrum/learning/constraints/structuralConstraintSetStatic.h>
#include <agrum/learning/constraints/structuralConstraintSliceOrder.h>
#include <agrum/learning/constraints/structuralConstraintTabuList.h>

#include <agrum/learning/structureUtils/graphChange.h>
#include <agrum/learning/structureUtils/graphChangesGenerator4DiGraph.h>
#include <agrum/learning/structureUtils/graphChangesGenerator4K2.h>
#include <agrum/learning/structureUtils/graphChangesSelector4DiGraph.h>

#include <agrum/learning/paramUtils/DAG2BNLearner.h>
#include <agrum/learning/paramUtils/paramEstimatorML.h>

#include <agrum/core/approximations/IApproximationSchemeConfiguration.h>
#include <agrum/core/approximations/approximationSchemeListener.h>

#include <agrum/learning/K2.h>
#include <agrum/learning/Miic.h>
#include <agrum/learning/greedyHillClimbing.h>
#include <agrum/learning/localSearchWithTabuList.h>

#include <agrum/core/signal/signaler.h>

namespace gum {

  namespace learning {

    class BNLearnerListener;

    class genericBNLearner : public gum::IApproximationSchemeConfiguration {
      // private:
      public:
      enum class ScoreType { AIC, BD, BDeu, BIC, K2, LOG2LIKELIHOOD };

      enum class ParamEstimatorType { ML };

      enum class AprioriType {
        NO_APRIORI,
        SMOOTHING,
        DIRICHLET_FROM_DATABASE,
        BDEU
      };

      enum class AlgoType {
        K2,
        GREEDY_HILL_CLIMBING,
        LOCAL_SEARCH_WITH_TABU_LIST,
        MIIC_THREE_OFF_TWO
      };


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


        explicit Database(const std::string&                file,
                          const std::vector< std::string >& missing_symbols);


        explicit Database(const DatabaseTable<>& db);


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


        template < typename GUM_SCALAR >
        Database(const std::string&                 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(const std::string& 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;

        protected:
        DatabaseTable<> __database;

        DBRowGeneratorParser<>* __parser{nullptr};

        std::vector< std::size_t > __domain_sizes;

        Bijection< NodeId, std::size_t > __nodeId2cols;

#if defined(_OPENMP) && !defined(GUM_DEBUG_MODE)
        Size __max_threads_number{getMaxNumberOfThreads()};
#else
        Size __max_threads_number{1};
#endif /* GUM_DEBUG_MODE */

        Size __min_nb_rows_per_thread{100};

        private:
        // returns the set of variables as a BN. This is convenient for
        // the constructors of apriori Databases
        template < typename GUM_SCALAR >
        BayesNet< GUM_SCALAR > __BNVars() const;
      };

      void __setAprioriWeight(double weight);

      public:
      // ##########################################################################
      // ##########################################################################


      genericBNLearner(const std::string&                filename,
                       const std::vector< std::string >& missing_symbols);
      genericBNLearner(const DatabaseTable<>& db);

      template < typename GUM_SCALAR >
      genericBNLearner(const std::string&                 filename,
                       const gum::BayesNet< GUM_SCALAR >& src,
                       const std::vector< std::string >&  missing_symbols);

      genericBNLearner(const genericBNLearner&);

      genericBNLearner(genericBNLearner&&);

      virtual ~genericBNLearner();


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

      genericBNLearner& operator=(const genericBNLearner&);

      genericBNLearner& operator=(genericBNLearner&&);


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

      DAG learnDAG();

      MixedGraph learnMixedStructure();

      void setInitialDAG(const DAG&);

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

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


      NodeId idFromName(const std::string& var_name) const;

      const DatabaseTable<>& database() const;

      void setDatabaseWeight(const double new_weight);

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


      template < template < typename > class XALLOC >
      void useDatabaseRanges(
         const std::vector< std::pair< std::size_t, std::size_t >,
                            XALLOC< 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(const NodeId                 id1,
                                       const NodeId                 id2,
                                       const std::vector< NodeId >& knowing = {});
      std::pair< double, double >
         chi2(const std::string&                name1,
              const std::string&                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 = {});


      Size nbCols() const;

      Size nbRows() const;

      void useEM(const double epsilon);

      bool hasMissingValues() const;


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

      void useScoreAIC();

      void useScoreBD();

      void useScoreBDeu();

      void useScoreBIC();

      void useScoreK2();

      void useScoreLog2Likelihood();


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

      void useNoApriori();


      void useAprioriBDeu(double weight = 1);


      void useAprioriSmoothing(double weight = 1);

      void useAprioriDirichlet(const std::string& filename, double weight = 1);



      std::string checkScoreAprioriCompatibility();

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

      void useGreedyHillClimbing();


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

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

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

      void use3off2();

      void useMIIC();


      // ##########################################################################
      // ##########################################################################
      void useNML();
      void useMDL();
      void useNoCorr();

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

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

      void setMaxIndegree(Size max_indegree);

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

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

      void setForbiddenArcs(const ArcSet& set);

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

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

      void setMandatoryArcs(const ArcSet& set);

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

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


      protected:
      ScoreType __score_type{ScoreType::BDeu};

      Score<>* __score{nullptr};

      ParamEstimatorType __param_estimator_type{ParamEstimatorType::ML};

      double __EMepsilon{0.0};

      CorrectedMutualInformation<>* __mutual_info{nullptr};

      AprioriType __apriori_type{AprioriType::NO_APRIORI};

      Apriori<>* __apriori{nullptr};

      AprioriNoApriori<>* __no_apriori{nullptr};

      double __apriori_weight{1.0f};

      StructuralConstraintSliceOrder __constraint_SliceOrder;

      StructuralConstraintIndegree __constraint_Indegree;

      StructuralConstraintTabuList __constraint_TabuList;

      StructuralConstraintForbiddenArcs __constraint_ForbiddenArcs;

      StructuralConstraintMandatoryArcs __constraint_MandatoryArcs;

      AlgoType __selected_algo{AlgoType::GREEDY_HILL_CLIMBING};

      K2 __K2;

      Miic __miic_3off2;

      typename CorrectedMutualInformation<>::KModeTypes __3off2_kmode{
         CorrectedMutualInformation<>::KModeTypes::MDL};

      DAG2BNLearner<> __Dag2BN;

      GreedyHillClimbing __greedy_hill_climbing;

      LocalSearchWithTabuList __local_search_with_tabu_list;

      Database __score_database;

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

      Database* __apriori_database{nullptr};

      std::string __apriori_dbname;

      DAG __initial_dag;

      // the current algorithm as an approximationScheme
      const ApproximationScheme* __current_algorithm{nullptr};

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

      static void __checkFileName(const std::string& filename);

      void __createApriori();

      void __createScore();

      ParamEstimator<>*
         __createParamEstimator(DBRowGeneratorParser<>& parser,
                                bool take_into_account_score = true);

      DAG __learnDAG();

      MixedGraph __prepare_miic_3off2();

      const std::string& __getAprioriType() const;

      void __createCorrectedMutualInformation();


      public:
      // ##########################################################################
      // ##########################################################################
      // in order to not pollute the proper code of genericBNLearner, we
      // directly
      // implement those
      // very simples methods here.
      INLINE void setCurrentApproximationScheme(
         const ApproximationScheme* approximationScheme) {
        __current_algorithm = approximationScheme;
      }

      INLINE void
         distributeProgress(const ApproximationScheme* approximationScheme,
                            Size                       pourcent,
                            double                     error,
                            double                     time) {
        setCurrentApproximationScheme(approximationScheme);

        if (onProgress.hasListener()) GUM_EMIT3(onProgress, pourcent, error, time);
      };

      INLINE void distributeStop(const ApproximationScheme* approximationScheme,
                                 std::string                message) {
        setCurrentApproximationScheme(approximationScheme);

        if (onStop.hasListener()) GUM_EMIT1(onStop, message);
      };

      void setEpsilon(double eps) {
        __K2.approximationScheme().setEpsilon(eps);
        __greedy_hill_climbing.setEpsilon(eps);
        __local_search_with_tabu_list.setEpsilon(eps);
        __Dag2BN.setEpsilon(eps);
      };

      double epsilon() const {
        if (__current_algorithm != nullptr)
          return __current_algorithm->epsilon();
        else
          GUM_ERROR(FatalError, "No chosen algorithm for learning");
      };

      void disableEpsilon() {
        __K2.approximationScheme().disableEpsilon();
        __greedy_hill_climbing.disableEpsilon();
        __local_search_with_tabu_list.disableEpsilon();
        __Dag2BN.disableEpsilon();
      };

      void enableEpsilon() {
        __K2.approximationScheme().enableEpsilon();
        __greedy_hill_climbing.enableEpsilon();
        __local_search_with_tabu_list.enableEpsilon();
        __Dag2BN.enableEpsilon();
      };

      bool isEnabledEpsilon() const {
        if (__current_algorithm != nullptr)
          return __current_algorithm->isEnabledEpsilon();
        else
          GUM_ERROR(FatalError, "No chosen algorithm for learning");
      };

      void setMinEpsilonRate(double rate) {
        __K2.approximationScheme().setMinEpsilonRate(rate);
        __greedy_hill_climbing.setMinEpsilonRate(rate);
        __local_search_with_tabu_list.setMinEpsilonRate(rate);
        __Dag2BN.setMinEpsilonRate(rate);
      };

      double minEpsilonRate() const {
        if (__current_algorithm != nullptr)
          return __current_algorithm->minEpsilonRate();
        else
          GUM_ERROR(FatalError, "No chosen algorithm for learning");
      };

      void disableMinEpsilonRate() {
        __K2.approximationScheme().disableMinEpsilonRate();
        __greedy_hill_climbing.disableMinEpsilonRate();
        __local_search_with_tabu_list.disableMinEpsilonRate();
        __Dag2BN.disableMinEpsilonRate();
      };
      void enableMinEpsilonRate() {
        __K2.approximationScheme().enableMinEpsilonRate();
        __greedy_hill_climbing.enableMinEpsilonRate();
        __local_search_with_tabu_list.enableMinEpsilonRate();
        __Dag2BN.enableMinEpsilonRate();
      };
      bool isEnabledMinEpsilonRate() const {
        if (__current_algorithm != nullptr)
          return __current_algorithm->isEnabledMinEpsilonRate();
        else
          GUM_ERROR(FatalError, "No chosen algorithm for learning");
      };

      void setMaxIter(Size max) {
        __K2.approximationScheme().setMaxIter(max);
        __greedy_hill_climbing.setMaxIter(max);
        __local_search_with_tabu_list.setMaxIter(max);
        __Dag2BN.setMaxIter(max);
      };

      Size maxIter() const {
        if (__current_algorithm != nullptr)
          return __current_algorithm->maxIter();
        else
          GUM_ERROR(FatalError, "No chosen algorithm for learning");
      };

      void disableMaxIter() {
        __K2.approximationScheme().disableMaxIter();
        __greedy_hill_climbing.disableMaxIter();
        __local_search_with_tabu_list.disableMaxIter();
        __Dag2BN.disableMaxIter();
      };
      void enableMaxIter() {
        __K2.approximationScheme().enableMaxIter();
        __greedy_hill_climbing.enableMaxIter();
        __local_search_with_tabu_list.enableMaxIter();
        __Dag2BN.enableMaxIter();
      };
      bool isEnabledMaxIter() const {
        if (__current_algorithm != nullptr)
          return __current_algorithm->isEnabledMaxIter();
        else
          GUM_ERROR(FatalError, "No chosen algorithm for learning");
      };


      void setMaxTime(double timeout) {
        __K2.approximationScheme().setMaxTime(timeout);
        __greedy_hill_climbing.setMaxTime(timeout);
        __local_search_with_tabu_list.setMaxTime(timeout);
        __Dag2BN.setMaxTime(timeout);
      }

      double maxTime() const {
        if (__current_algorithm != nullptr)
          return __current_algorithm->maxTime();
        else
          GUM_ERROR(FatalError, "No chosen algorithm for learning");
      };

      double currentTime() const {
        if (__current_algorithm != nullptr)
          return __current_algorithm->currentTime();
        else
          GUM_ERROR(FatalError, "No chosen algorithm for learning");
      };

      void disableMaxTime() {
        __K2.approximationScheme().disableMaxTime();
        __greedy_hill_climbing.disableMaxTime();
        __local_search_with_tabu_list.disableMaxTime();
        __Dag2BN.disableMaxTime();
      };
      void enableMaxTime() {
        __K2.approximationScheme().enableMaxTime();
        __greedy_hill_climbing.enableMaxTime();
        __local_search_with_tabu_list.enableMaxTime();
        __Dag2BN.enableMaxTime();
      };
      bool isEnabledMaxTime() const {
        if (__current_algorithm != nullptr)
          return __current_algorithm->isEnabledMaxTime();
        else
          GUM_ERROR(FatalError, "No chosen algorithm for learning");
      };

      void setPeriodSize(Size p) {
        __K2.approximationScheme().setPeriodSize(p);
        __greedy_hill_climbing.setPeriodSize(p);
        __local_search_with_tabu_list.setPeriodSize(p);
        __Dag2BN.setPeriodSize(p);
      };

      Size periodSize() const {
        if (__current_algorithm != nullptr)
          return __current_algorithm->periodSize();
        else
          GUM_ERROR(FatalError, "No chosen algorithm for learning");
      };

      void setVerbosity(bool v) {
        __K2.approximationScheme().setVerbosity(v);
        __greedy_hill_climbing.setVerbosity(v);
        __local_search_with_tabu_list.setVerbosity(v);
        __Dag2BN.setVerbosity(v);
      };

      bool verbosity() const {
        if (__current_algorithm != nullptr)
          return __current_algorithm->verbosity();
        else
          GUM_ERROR(FatalError, "No chosen algorithm for learning");
      };


      ApproximationSchemeSTATE stateApproximationScheme() const {
        if (__current_algorithm != nullptr)
          return __current_algorithm->stateApproximationScheme();
        else
          GUM_ERROR(FatalError, "No chosen algorithm for learning");
      };

      Size nbrIterations() const {
        if (__current_algorithm != nullptr)
          return __current_algorithm->nbrIterations();
        else
          GUM_ERROR(FatalError, "No chosen algorithm for learning");
      };

      const std::vector< double >& history() const {
        if (__current_algorithm != nullptr)
          return __current_algorithm->history();
        else
          GUM_ERROR(FatalError, "No chosen algorithm for learning");
      };
    };

  } /* namespace learning */

} /* namespace gum */

#ifndef GUM_NO_INLINE
#  include <agrum/learning/BNLearnUtils/genericBNLearner_inl.h>
#endif /* GUM_NO_INLINE */

#include <agrum/learning/BNLearnUtils/genericBNLearner_tpl.h>

#endif /* GUM_LEARNING_GENERIC_BN_LEARNER_H */