Learner.h

Go to the documentation of this file.

// -*- C++ -*-4 1999/10/29 20:41:34 dugas

// Learner.h
//
// Copyright (C) 1998-2002 Pascal Vincent
// Copyright (C) 1999-2002 Yoshua Bengio, Nicolas Chapados, Charles Dugas, Rejean Ducharme, Universite de Montreal
// Copyright (C) 2001,2002 Francis Pieraut, Jean-Sebastien Senecal
// Copyright (C) 2002 Frederic Morin, Xavier Saint-Mleux, Julien Keable
// 
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are met:
// 
//  1. Redistributions of source code must retain the above copyright
//     notice, this list of conditions and the following disclaimer.
// 
//  2. Redistributions in binary form must reproduce the above copyright
//     notice, this list of conditions and the following disclaimer in the
//     documentation and/or other materials provided with the distribution.
// 
//  3. The name of the authors may not be used to endorse or promote
//     products derived from this software without specific prior written
//     permission.
// 
// THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS OR
// IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
// OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
// NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
// TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
// 
// This file is part of the PLearn library. For more information on the PLearn
// library, go to the PLearn Web site at www.plearn.org


 

/* *******************************************************      
   * $Id: Learner.h,v 1.15 2004/07/21 16:30:56 chrish42 Exp $
   ******************************************************* */


#ifndef Learner_INC
#define Learner_INC

#include <plearn/measure/Measurer.h>
#include <plearn/ker/Kernel.h>
#include <plearn/math/VecStatsCollector.h>
#include <plearn/math/StatsIterator.h>
#include <plearn/vmat/VVec.h>
//#include "TimeMeasurer.h"

namespace PLearn {
using namespace std;

  class Learner: public Object, public Measurer//, public TimeMeasurer
  {
  protected:

    Vec tmpvec; // for temporary storage.

    // EN FAIRE UN POINTEUR AUSSI
    ofstream* train_objective_stream; 
    Array<ofstream*> test_results_streams; 

  private:

    static Vec tmp_input; // temporary input vec
    static Vec tmp_target; // temporary target vec
    static Vec tmp_weight; // temporary example weight vec
    static Vec tmp_output; // temporary output vec
    static Vec tmp_costs; // temporary costs vec

  protected:

    void openTrainObjectiveStream();
    
    ostream& getTrainObjectiveStream();

    void openTestResultsStreams();

    ostream& getTestResultsStream(int k);
    
    void freeTestResultsStreams();

    void outputResultLineToFile(const string & filename, const Vec& results,bool append,const string& names);

  protected:
    string expdir; 
    
    int epoch_;
    
    bool distributed_;


  public:

    string basename() const;
    
    typedef Object inherited;
    
    int inputsize_;  
    int targetsize_; 
    int outputsize_; 
    int weightsize_; //<! number of weight fields in the target vec (all_targets = actual_target & weights)

    bool dont_parallelize; //<! (default: false)

    //oassignstream testout;
    PStream testout;
    int test_every;
    Vec avg_objective; 
    Vec avgsq_objective; 
    VMat train_set; 
    Array<VMat> test_sets; 
    int minibatch_size; 

    int report_test_progress_every;

    Vec options;

    int earlystop_testsetnum; 
    int earlystop_testresultindex; 
    real earlystop_max_degradation; 
    real earlystop_min_value; 
    real earlystop_min_improvement; 
    bool earlystop_relative_changes;  
    bool earlystop_save_best; 
    int earlystop_max_degraded_steps; 

    bool save_at_every_epoch; 
    bool save_objective; //<! whether to save in basename()+".objective" the cost after each measure (e.g. after each epoch)
    int best_step; 

  protected:
    real earlystop_previousval;
  public:
    real earlystop_minval;

    // DPERECATED. Please use the expdir system from now on, through setExperimentDirectory
    string experiment_name;

  protected:
    //strstream earlystop_best_model; //!<  string stream where the currently best model is saved
    
    Array<Measurer*> measurers;
    
    bool measure_cpu_time_first; // the first el. in measure(..) will be cpu time instead of courant step

    bool each_cpu_saves_its_errors;
  public:
    Array<CostFunc> test_costfuncs;
    StatsItArray test_statistics;

    static int use_file_if_bigger; 



    static bool force_saving_on_all_processes; 

    static PStream& /*oassignstream&*/ default_vlog(); 
    //oassignstream vlog; //!<  The log stream to which all the verbose output from this learner should be sent
    //oassignstream objectiveout; //!<  The log stream to use to record the objective function during training
    PStream vlog; 
    PStream objectiveout; 

    Learner(int the_inputsize=0, int the_targetsize=0, int the_outputsize=0);

    virtual ~Learner();


    virtual void setExperimentDirectory(const string& the_expdir);
    string getExperimentDirectory() const { return expdir; }

    PLEARN_DECLARE_ABSTRACT_OBJECT(Learner);
    virtual void makeDeepCopyFromShallowCopy(CopiesMap& copies);

  private:
    void build_();
    
  public:
    virtual void build();

    virtual void setTrainingSet(VMat training_set) { train_set = training_set; }
    inline VMat getTrainingSet() { return train_set; }

    virtual void train(VMat training_set) =0; 


    virtual void newtrain(VecStatsCollector& train_stats);


    virtual void newtest(VMat testset, VecStatsCollector& test_stats, 
                         VMat testoutputs=0, VMat testcosts=0);

    /*
      virtual void useAndCost(Vec input, Vec target, Vec output, Vec cost)

      virtual void trainTest(VMat train, Array<VMat> testsets);
      virtual void trainKFold(VMat trainset, int k);
      virtual void trainBootstrap(VMat trainset, int k, Array<VMat> testsets);
      virtual void trainSequential(VMat dataset, sequence_spec);
      
    */

    virtual void train(VMat training_set, VMat accept_prob,
        real max_accept_prob=1.0, VMat weights=VMat())
    { PLERROR("This method is not implemented for this learner"); }

    virtual void use(const Vec& input, Vec& output) =0;
    virtual void use(const Mat& inputs, Mat outputs) 
    { 
      for (int i=0;i<inputs.length();i++) 
      {
        Vec input = inputs(i);
        Vec output = outputs(i);
        use(input,output);
      }
    }

    Vec vec_input;

    // NOTE: For backward compatibility, default version currently calls
    // deprecated method use which should ultimately be removed...
    virtual void computeOutput(const VVec& input, Vec& output);

    // NOTE: For backward compatibility, default version currently calls the
    // deprecated method computeCost which should ultimately be removed...
    virtual void computeCostsFromOutputs(const VVec& input, const Vec& output, 
                                         const VVec& target, const VVec& weight,
                                         Vec& costs);

                                
    virtual void computeOutputAndCosts(const VVec& input, VVec& target, const VVec& weight,
                                       Vec& output, Vec& costs);

    virtual void computeCosts(const VVec& input, VVec& target, VVec& weight, 
                              Vec& costs);
    

    virtual void setModel(const Vec& new_options);

    virtual void forget();

    virtual bool measure(int step, const Vec& costs);

    virtual void oldwrite(ostream& out) const;
    virtual void oldread(istream& in);

    void save(const string& filename="") const;
    void load(const string& filename="");

    virtual void stop_if_wanted();

    inline int inputsize() const { return inputsize_; }
    inline int targetsize() const { return targetsize_; }
    inline int outputsize() const { return outputsize_; }
    inline int weightsize() const { return weightsize_; }
    inline int epoch() const { return epoch_; }

    virtual int costsize() const;
  
    void setTestCostFunctions(Array<CostFunc> costfunctions)
      { test_costfuncs = costfunctions; }

    void setTestStatistics(StatsItArray statistics)
      { test_statistics = statistics; }

    virtual void setTestDuringTrain(ostream& testout, int every,
                            Array<VMat> testsets);

    virtual void setTestDuringTrain(Array<VMat> testsets);


    const Array<VMat>& getTestDuringTrain() const {
      return test_sets;
    }
      

    void setEarlyStopping(int which_testset, int which_testresult, 
                          real max_degradation, real min_value=-FLT_MAX, 
                          real min_improvement=0, bool relative_changes=true, 
                          bool save_best=true, int max_degraded_steps=-1);

    virtual void computeCost(const Vec& input, const Vec& target, const Vec& output, const Vec& cost);

    virtual void useAndCost(const Vec& input, const Vec& target, 
                            Vec output, Vec cost);

    virtual void useAndCostOnTestVec(const VMat& test_set, int i, const Vec& output, const Vec& cost);

    virtual void apply(const VMat& data, VMat outputs);

    virtual void applyAndComputeCosts(const VMat& data, VMat outputs, VMat costs);

    virtual void applyAndComputeCostsOnTestMat(const VMat& test_set, int i, const Mat& output_block, 
                                               const Mat& cost_block);

    virtual void computeCosts(const VMat& data, VMat costs);

    virtual void computeLeaveOneOutCosts(const VMat& data, VMat costs);

    virtual void computeLeaveOneOutCosts(const VMat& data, VMat costsmat, CostFunc costf);

    Vec computeTestStatistics(const VMat& costs);

    virtual Vec test(VMat test_set, const string& save_test_outputs="", 
                     const string& save_test_costs="");

    virtual Array<string> costNames() const;

    virtual Array<string> testResultsNames() const;

    virtual Array<string> trainObjectiveNames() const;

    void appendMeasurer(Measurer& measurer)
      { measurers.append(&measurer); }

  protected:
    static void declareOptions(OptionList& ol);

      void setTrainCost(Vec &cost)
          { train_cost.resize(cost.length()); train_cost << cost; };
      Vec train_cost;
  public:
      Vec getTrainCost() { return train_cost; };
  };

  DECLARE_OBJECT_PTR(Learner);

  typedef PP<Learner> PPLearner;
        
  inline void prettyprint_test_results(ostream& out, const Learner& learner, const Vec& results)
  {
    Array<string> names = learner.testResultsNames();
    for (int i=0; i<names.size(); i++)
      out << names[i] << ": " << results[i] << endl;
  }
  

} // end of namespace PLearn

#endif

---