PLearn 0.1
PLearner.h
Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 // PLearner.h
00004 //
00005 // Copyright (C) 1998-2002 Pascal Vincent
00006 // Copyright (C) 1999-2002 Yoshua Bengio, Nicolas Chapados, Charles Dugas, Rejean Ducharme, Universite de Montreal
00007 // Copyright (C) 2001,2002 Francis Pieraut, Jean-Sebastien Senecal
00008 // Copyright (C) 2002 Frederic Morin, Xavier Saint-Mleux, Julien Keable
00009 // Copyright (C) 2007 Xavier Saint-Mleux, ApSTAT Technologies inc.
00010 // 
00011 // Redistribution and use in source and binary forms, with or without
00012 // modification, are permitted provided that the following conditions are met:
00013 // 
00014 //  1. Redistributions of source code must retain the above copyright
00015 //     notice, this list of conditions and the following disclaimer.
00016 // 
00017 //  2. Redistributions in binary form must reproduce the above copyright
00018 //     notice, this list of conditions and the following disclaimer in the
00019 //     documentation and/or other materials provided with the distribution.
00020 // 
00021 //  3. The name of the authors may not be used to endorse or promote
00022 //     products derived from this software without specific prior written
00023 //     permission.
00024 // 
00025 // THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS OR
00026 // IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
00027 // OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
00028 // NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
00029 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
00030 // TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00031 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00032 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00033 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00034 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00035 // 
00036 // This file is part of the PLearn library. For more information on the PLearn
00037 // library, go to the PLearn Web site at www.plearn.org
00038 
00039 
00040  
00041 
00042 /* *******************************************************      
00043  * $Id: PLearner.h 10114 2009-04-13 19:06:24Z chapados $
00044  ******************************************************* */
00045 
00046 
00047 
00048 #ifndef PLearner_INC
00049 #define PLearner_INC
00050 
00051 #include <plearn/base/Object.h>
00052 #include <plearn/io/PPath.h>
00053 #include <plearn/math/PRandom.h>
00054 #include <plearn/math/VecStatsCollector.h>
00055 #include <plearn/vmat/VMat.h>
00056 
00057 namespace PLearn {
00058 using namespace std;
00059 
00085 class PLearner: public Object
00086 {
00087     typedef Object inherited;
00088 
00090     mutable int n_train_costs_;
00091 
00093     mutable int n_test_costs_;
00094 
00096     mutable Vec tmp_output;
00097 
00098 public:
00099     //#####  Build Options  ###################################################
00100 
00109     PPath expdir; 
00110 
00116     int seed_;
00117 
00125     int stage;
00126 
00135     int nstages;
00136 
00138     bool report_progress;
00139 
00145     int verbosity; 
00146 
00152     int nservers; 
00153 
00159     int test_minibatch_size;
00160 
00171     string save_trainingset_prefix;
00172 
00176     bool parallelize_here;
00177 
00183     bool master_sends_testset_rows;
00184 
00196     int use_a_separate_random_generator_for_testing;
00197 
00198 
00205     bool finalized;
00206 
00207 protected:
00208 
00217     VMat train_set;  
00218 
00220     VMat validation_set;
00221 
00222     //#####  Learnt Options  ##################################################
00223 
00225     int inputsize_;
00226 
00228     int targetsize_;
00229 
00231     int weightsize_;
00232 
00234     int n_examples;
00235 
00241     PP<VecStatsCollector> train_stats;
00242 
00247     bool forget_when_training_set_changes;
00248 
00256     mutable PP<PRandom> random_gen;
00257 
00258 public:
00260     PLearner();
00261 
00262 
00263     //#####  Experiment Context  ##############################################
00264     
00272     virtual void setTrainingSet(VMat training_set, bool call_forget=true);
00273 
00275     inline VMat getTrainingSet() const
00276     {
00277         return train_set;
00278     }
00279 
00282     virtual void setValidationSet(VMat validset);
00283 
00285     VMat getValidationSet() const
00286     {
00287         return validation_set;
00288     }
00289 
00295     virtual void setTrainStatsCollector(PP<VecStatsCollector> statscol);
00296 
00298     inline PP<VecStatsCollector> getTrainStatsCollector()
00299     {
00300         return train_stats;
00301     }
00302 
00308     virtual void setExperimentDirectory(const PPath& the_expdir);
00309 
00311     PPath getExperimentDirectory() const { return expdir; }
00312 
00314     virtual int inputsize() const;
00315 
00317     virtual int targetsize() const; 
00318 
00320     virtual int weightsize() const; 
00321 
00327     virtual int outputsize() const = 0;
00328 
00329 public:
00332     virtual void build();
00333 
00334 protected:
00336     virtual void build_from_train_set() { }
00337 
00355     bool initTrain();
00356 
00357 private:
00382     void build_();
00383 
00384 public:
00385     //#####  Training Protocol  ###############################################
00386     
00411     virtual void forget();
00412 
00420     virtual void finalize();
00421 
00458     virtual void train() =0;
00459 
00460 
00461     //#####  Output Computation  ##############################################
00462 
00469     virtual void computeOutput(const Vec& input, Vec& output) const;
00473     virtual void computeOutputs(const Mat& input, Mat& output) const;
00474 
00485     virtual void computeCostsFromOutputs(const Vec& input, const Vec& output, 
00486                                          const Vec& target, Vec& costs) const = 0;
00487     
00493     virtual void computeOutputAndCosts(const Vec& input, const Vec& target,
00494                                        Vec& output, Vec& costs) const;
00496     virtual void computeOutputsAndCosts(const Mat& input, const Mat& target,
00497                                         Mat& output, Mat& costs) const;
00498 
00504     virtual void computeCostsOnly(const Vec& input, const Vec& target, Vec& costs) const;
00505 
00519     virtual
00520     bool computeConfidenceFromOutput(const Vec& input, const Vec& output,
00521                                      real probability,
00522                                      TVec< pair<real,real> >& intervals) const;
00523 
00544     virtual void computeOutputCovMat(const Mat& inputs, Mat& outputs,
00545                                      TVec<Mat>& covariance_matrices) const;
00546     
00552     virtual
00553     void batchComputeOutputAndConfidence(VMat inputs, real probability,
00554                                          VMat outputs_and_confidence) const;
00555 
00561     virtual void use(VMat testset, VMat outputs) const;
00562 
00564     Mat computeInputOutputMat(VMat inputs) const;
00565 
00571     Mat computeInputOutputConfMat(VMat inputs, real probability) const;
00572 
00578     Mat computeOutputConfMat(VMat inputs, real probability) const;
00579     
00584     virtual void useOnTrain(Mat& outputs) const;
00585 
00589     virtual Mat remote_useOnTrain() const;
00590 
00599     virtual void test(VMat testset, PP<VecStatsCollector> test_stats, 
00600                       VMat testoutputs=0, VMat testcosts=0) const;
00601 
00607     virtual tuple<PP<VecStatsCollector>, VMat, VMat> sub_test(VMat testset, PP<VecStatsCollector> test_stats,
00608                                                       bool rtestoutputs, bool rtestcosts) const;
00609     
00613     virtual tuple<PP<VecStatsCollector>, VMat, VMat> remote_test(VMat testset, PP<VecStatsCollector> test_stats,
00614                                                       bool rtestoutputs, bool rtestcosts) const;
00615     
00616     
00617 
00624     virtual VMat processDataSet(VMat dataset) const;
00625 
00626     //#####  Cost Names  ######################################################
00627 
00634     virtual TVec<string> getTestCostNames() const =0;
00635 
00643     virtual TVec<string> getTrainCostNames() const =0;
00644 
00651     virtual TVec<string> getOutputNames() const;
00652 
00657     virtual int nTestCosts() const;
00658 
00663     virtual int nTrainCosts() const;
00664 
00669     int getTestCostIndex(const string& costname) const;
00670 
00676     int getTrainCostIndex(const string& costname) const;
00677 
00678 
00679     //#####  Stateful Learning  ###############################################
00680 
00683     virtual void resetInternalState();
00684 
00687     virtual bool isStatefulLearner() const;
00688 
00689 protected:
00691     static void declareOptions(OptionList& ol);
00692 
00694     static void declareMethods(RemoteMethodMap& rmm);
00695 
00697     virtual void makeDeepCopyFromShallowCopy(CopiesMap& copies);
00698 
00699 private:
00700     // List of methods that are called by Remote Method Invocation.  Our
00701     // convention is to have them start with the remote_ prefix.
00702     Vec remote_computeOutput(const Vec& input) const;
00703     Mat remote_computeOutputs(const Mat& input) const;
00704     pair<Mat, Mat> remote_computeOutputsAndCosts(const Mat& input,
00705                                                  const Mat& target) const;
00706     void remote_use(VMat inputs, string output_fname) const;
00707     Mat remote_use2(VMat inputs) const;
00708     tuple<Vec,Vec> remote_computeOutputAndCosts(const Vec& input, const Vec& target) const;
00709     Vec remote_computeCostsFromOutputs(const Vec& input,
00710                                        const Vec& output, const Vec& target) const;
00711     Vec remote_computeCostsOnly(const Vec& input, const Vec& target) const;
00712     TVec< pair<real,real> > remote_computeConfidenceFromOutput(const Vec& input,
00713                                                                const Vec& output,
00714                                                                real probability) const;
00715     tuple<Mat, TVec<Mat> > remote_computeOutputCovMat(const Mat& inputs) const;
00716     void remote_batchComputeOutputAndConfidence(VMat inputs, real probability,
00717                                                 string pmat_fname) const;
00718 protected:
00719     mutable Mat b_inputs, b_targets, b_outputs, b_costs;
00720     mutable Vec b_weights;
00721     
00722 public:
00723     PLEARN_DECLARE_ABSTRACT_OBJECT(PLearner);
00724 
00725 };
00726 
00727 DECLARE_OBJECT_PTR(PLearner);
00728 
00729 } // end of namespace PLearn
00730 
00731 #endif
00732 
00733 
00734 /*
00735   Local Variables:
00736   mode:c++
00737   c-basic-offset:4
00738   c-file-style:"stroustrup"
00739   c-file-offsets:((innamespace . 0)(inline-open . 0))
00740   indent-tabs-mode:nil
00741   fill-column:79
00742   End:
00743 */
00744 // vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:encoding=utf-8:textwidth=79 :
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines