name: RelevanceVectorMachine
synopsis:

>     g++ [flags ...] file ... -l /isip/tools/lib/$ISIP_BINARY/lib_pr.a

>     #include <RelevanceVectorMachine.h>

>     ALGORITHM getAlgorithm();
>     boolean setAlgorithm(ALGORITHM arg);
>     IMPLEMENTATION getImplementation();
>     boolean setImplementation(IMPLEMENTATION arg);
>     boolean setDegree(float arg);
>     boolean setKappa(float arg);
>     boolean setDelta(float arg);
>     boolean setGamma(float arg);
>     boolean setVerbosity(Integral::DEBUG verbosity);
>     boolean setOutputFile(Filename& arg);
>     boolean setOutputType(TYPE arg);
>     boolean loadFeatures(Sdb& in_sdb, Sdb& out_sdb);
>     boolean train(RVMTrainData& tdata, ALGORITHM mode = DEF_ALGORITHM);
>     boolean writeModel();

quick start:

>     Sdb pos_sdb;
>     Sdb neg_sdb;

>     rvm.loadFeatures(pos_sdb, neg_sdb);
>     rvm.train(RVMTrainData& tdata);
>     rvm.writeModel();

description:
This class computes the relevance vectors give a list of in-class and out-of-class observation using the relevance determination.
References:
[1] M. E. Tipping, "Sparse Bayesian Learning and the Relevance Vector Machine," Journal of Machine Learning Research, vol 1, pp. 211-244, June 2001.
[2] David J. C. MacKay, "Probable Networks and Plausible Predictions - A Review of Practical Bayesian Methods for Supervised Neural Networks," Network: Computation in Neural Systems, vol. 6, no. 3, pp. 469-505, 1995.
[3] A. Faul and M. E. Tipping, "Analysis of Sparse Bayesian Learning," Proceedings of the 2001 Neural Information Processing Systems, 2001.
br> dependencies:

- String.h
- VectorDouble.h
- Vector.h
- File.h
- FeatureFile.h

public constants:

- define algorithm and implementation choices:

      enum ALGORITHM { FULL = 0, ITERATIVE_REFINEMENT, TIPPING_CONSTRUCTIVE, DEF_ALGORITHM = FULL};

      enum IMPLEMENTATION { LINEAR = 0, POLYNOMIAL, RBF, SIGMOID, DEF_IMPLEMENTATION = LINEAR };

      enum TYPE { TEXT = 0, BINARY, DEF_TYPE = BINARY };

- define name maps:

      static const String CLASS_NAME;

      static const NameMap IMPL_MAP;

      static const NameMap ALGO_MAP;

      static const NameMap TYPE_MAP;

- define i/o parameters:

      static const String DEF_PARAM;

      static const String DEF_COMMENT_TAG;

      static const String PARAM_OUTPUT_TYPE;

      static const String PARAM_OUTPUT_FILE;

      static const String PARAM_AUDIO_DB;

      static const String PARAM_POLYNOMIAL_DEGREE;

      static const String PARAM_RBF_GAMMA;

      static const String PARAM_SIGMOID_KAPPA;

      static const String PARAM_SIGMOID_DELTA;

      static const String PARAM_ALGORITHM;

      static const String PARAM_IMPLEMENTATION;

      static const String PARAM_ALPHA_THRESH;

      static const String PARAM_MIN_ALLOWED_WEIGHT;

      static const String PARAM_MAX_RVM_ITS;

      static const String PARAM_MAX_UPDATE_ITS;

      static const String PARAM_MIN_THETA;

      static const String PARAM_MOMENTUM;

      static const String PARAM_MAX_ADDITIONS;

- define public constants:

      static const long DEF_ALPHA_THRESH = 1e8;

      static const long DEF_MIN_ALLOWED_WEIGHT = 1e-8;

      static const float DEF_CV_SETS = 1;

      static const float DEF_CV_PERCENT = 80;

      static const float DEF_BIAS= 0.0;

      static const float DEF_POLYNOMIAL_DEGREE = 3.0;

      static const float DEF_RBF_GAMMA = 0.5;

      static const float DEF_SIGMOID_KAPPA = 1.0;

      static const float DEF_SIGMOID_DELTA = 1.0;

error codes:

- error codes indicating general errors:

protected data:

- algorithm name:

      ALGORITHM algorithm_d;

- implementation name:

      IMPLEMENTATION implementation_d;

- output type:

      TYPE output_type_d;

- output file:

      Filename output_file_d;

- audio database file:

      Filename audio_db_file_d;

- audio database:

      AudioDatabase audio_db_d;

- kernel function: we assume that the same kernel is used for all training points. this only makes sense though since anything else would mean different training points operating in different spaces.:

      Kernel kernel_d;

- default polynomial degree:

      Float polynomial_degree_d;

- default rbf gamma:

      Float rbf_gamma_d;

- default sigmoid kappa:

      Float sigmoid_kappa_d;

- default sigmoid delta:

      Float sigmoid_delta_d;

- default bias parameter:

      Float bias_d;

- error cache parameter:

      VectorFloat error_cache_d;

- input observations and their labels:

      Vector<VectorFloat> points_d;

      VectorFloat target_d;

- verbosity:

      static Integral::DEBUG verbosity_d;

- declare the debugging parameters:

      static Integral::DEBUG debug_level_d;

- declare the memory manager:

      static MemoryManager mgr_d;

required public methods:

- static methods:

      static const String& name();

- debug methods:

      static boolean diagnose(Integral::DEBUG debug_level);

      static boolean setDebug(Integral::DEBUG level);

      boolean debug(const unichar* msg) const;

- destructor/constructor(s):

      ~RelevanceVectorMachine();

      RelevanceVectorMachine();

      RelevanceVectorMachine(const RelevanceVectorMachine& arg);

- assign methods:

      boolean assign(const RelevanceVectorMachine& copy_node);

- operator= method:

      RelevanceVectorMachine& operator= (const RelevanceVectorMachine& arg);

- i/o methods:

      long sofSize() const;

      boolean read(Sof& sof, long tag, const String& name = CLASS_NAME);

      boolean write(Sof& sof, long tag, const String& name = CLASS_NAME) const;

      boolean readData(Sof& sof, const String& pname = DEF_PARAM, long size = SofParser::FULL_OBJECT, boolean param = true, boolean nested = false);

      boolean writeData(Sof& sof, const String& pname = DEF_PARAM) const;

- equality methods:

      boolean eq(const RelevanceVectorMachine& arg) const;

- memory management methods:

      static void* operator new(size_t size);

      static void* operator new[](size_t size);

      static void operator delete(void* ptr);

      static void operator delete[](void* ptr);

      static boolean setGrowSize(long grow_size);

      boolean clear(Integral::CMODE cmode = Integral::DEF_CMODE);

class-specific public methods:

- declare class specific methods:

      ALGORITHM getAlgorithm();

      boolean setAlgorithm(ALGORITHM arg);

      IMPLEMENTATION getImplementation();

      boolean setImplementation(IMPLEMENTATION arg);

      boolean setPenalty(float arg);

      boolean setEpsilon(float arg);

      boolean setTolerance (float arg);

      boolean setDegree(float arg);

      boolean setKappa(float arg);

      boolean setDelta(float arg);

      boolean setGamma(float arg);

      boolean setVerbosity(Integral::DEBUG verbosity);

      boolean setOutputFile(Filename& arg);

      boolean setOutputType(TYPE arg);

      boolean initKernel();

      boolean loadFeatures(Sdb& in_sdb, Sdb& out_sdb);

      boolean train(RVMTrainData& tdata, ALGORITHM mode = DEF_ALGORITHM);

      boolean writeModel();

private methods:

- declare private methods:

      boolean trainFull(RVMTrainData& tdata, boolean is_init = false);

      boolean trainIterativeRefinement(RVMTrainData& tdata, boolean is_init = false);

      boolean trainTippingConstructive(RVMTrainData& tdata, boolean is_init = false);

      boolean initFull(RVMTrainData& tdata);

      boolean initIterativeRefinement(RVMTrainData& tdata);

      boolean irlsTrain(RVMTrainData& tdata);

      boolean computeSigma(RVMTrainData& tdata);

      boolean updateHyperparameters(boolean& updated, RVMTrainData& tdata, ALGORITHM = FULL, boolean use_mackay = true);

      boolean updateHyperparametersFull(boolean& updated, RVMTrainData& tdata, boolean use_mackay = true);

      boolean updateHyperparametersIncremental(boolean& updated, RVMTrainData& tdata);

      boolean pruneWeights(RVMTrainData& tdata);

      boolean pruneAndUpdate(RVMTrainData& tdata);

      boolean finalizeTraining(RVMTrainData& tdata, ALGORITHM mode);

      boolean reinitialize(RVMTrainData& tdata);

      boolean getPhiRow(VectorFloat& ovec, long index);

      float computeLikelihood(RVMTrainData& tdata) const;

      boolean computeVarianceCholesky(RVMTrainData& tdata);

      boolean readRestartData(RVMTrainData& tdata);

      boolean writeRestartData(RVMTrainData& tdata);

      boolean rebuildPhiCache(RVMTrainData& tdata);

      boolean getPhiRowFromCache(VectorFloat& ovec, long index, RVMTrainData& tdata);

      boolean resetActiveParams(RVMTrainData& tdata);

      boolean initializeRVSubsets(RVMTrainData& tdata);

      boolean initializeSubsetRVM(RelevanceVectorMachine& training_rvm, RVMTrainData& subset_data, RVMTrainData& global_data);

      boolean updateSubsetRVM(RVMTrainData& global_data, RelevanceVectorMachine& training_rvm, RVMTrainData& subset_data);

examples:

      // open the positive examples file
      //
      Sof pos_sof;
      if (!pos_sof.open(L"positive_examples_list.sof", File::READ_ONLY)) {
        output.assign(L"\ncannot open file: ");
        output.concat(pos_example_list);
        output.concat(L", bailing out...");
        Console::put(output);
        Integral::exit();
      }

      // read the list of positive examples
      //
      Sdb pos_sdb;
      if (!pos_sdb.read(pos_sof, (long)0)) {
        output.assign(L"\ncannot read file: ");
        output.concat(pos_example_list);
        output.concat(L", bailing out...");
        Console::put(output);
        Integral::exit();
      }

      // open the negative examples file
      //
      Sof neg_sof;
      if (!neg_sof.open(L"negative_examples_list.sof", File::READ_ONLY)) {
        output.assign(L"\ncannot open file: ");
        output.concat(neg_example_list);
        output.concat(L", bailing out...");
        Console::put(output);
        Integral::exit();
      }

      // read the list of positive examples
      //
      Sdb neg_sdb;
      if (!neg_sdb.read(neg_sof, (long)0)) {
        output.assign(L"\ncannot read file: ");
        output.concat(neg_example_list);
        output.concat(L", bailing out...");
        Console::put(output);
        Integral::exit();
      }

      // open the relevance vector parameter file
      //
      if (verbosity >= Integral::BRIEF) {
        Console::increaseIndention();
        output.assign(L"\nloading parameter file: ");
        output.concat(params_file);
        Console::put(output);
        Console::decreaseIndention();
      }

      Sof param_sof;
      if (!param_sof.open(params_file, File::READ_ONLY)) {
        output.assign(L"\ncannot open file: ");
        output.concat(params_file);
        output.concat(L", bailing out...");
        Console::put(output);
        Integral::exit();
      }

      // read the relevance vector parameters
      //
      if (!rvm.read(param_sof, (long)0)) {
        output.assign(L"\nerror reading parameter file: ");
        output.concat(params_file);
        output.concat(L", bailing out...");
        Console::put(output);
        Integral::exit();
      }

      // load the features from file
      //
      rvm.loadFeatures(pos_sdb, neg_sdb);

      // start training
      //
      rvm.train();

      // write the relevance vector model
      //
      rvm.writeModel();

notes:

- The relevance vector machine trainer is also employed by the isip_verify to compute the relevance vector model.