include/lwpr.hh

Go to the documentation of this file.

/*********************************************************************
LWPR: A library for incremental online learning
Copyright (C) 2007  Stefan Klanke, Sethu Vijayakumar
Contact: sethu.vijayakumar@ed.ac.uk

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either 
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Library General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*********************************************************************/

#ifndef __LWPR_HH
#define __LWPR_HH

#include <lwpr.h>
#include <lwpr_math.h>
#include <lwpr_binio.h>
#include <lwpr_xml.h>
#include <string.h>
#include <vector>

typedef std::vector<double> doubleVec;

class LWPR_Exception {
   public:
   
   typedef enum { 
      OUT_OF_MEMORY,    
      BAD_INPUT_DIM,    
      BAD_OUTPUT_DIM,   
      BAD_INIT_D,       
      UNKNOWN_KERNEL,   
      IO_ERROR,         
      OUT_OF_RANGE,     
      UNSPECIFIED_ERROR 
   } Code;
   
   LWPR_Exception(Code code) {
      this->code = code;
   }
   
   Code getCode() const { 
      return code;
   }

   const char *getString() const {
      switch(code) {
         case OUT_OF_MEMORY: 
            return "Insufficient memory to allocate storage.";
         case BAD_INPUT_DIM: 
            return "Input dimensionality does not match.";
         case BAD_OUTPUT_DIM: 
            return "Output dimensionality does not match.";
         case BAD_INIT_D: 
            return "Invalid initial distance metric (not positive definite).";
         case UNKNOWN_KERNEL:
            return "Passed kernel name was not recognised.";
         case IO_ERROR:
            return "An error occurred during I/O operations.";
         case OUT_OF_RANGE:
            return "Index parameter out of range.";
         default:
            return "Oops: Unspecified error.";
      }
   }
   
   private:
   
   Code code;
};

class LWPR_Object;


class LWPR_ReceptiveFieldObject {
   friend class LWPR_Object;
   
   public:
   
   int nReg() const { 
      return RF->nReg; 
   }
   
   doubleVec meanX() const {
      doubleVec mx(nIn);   
      memcpy(&mx[0], RF->mean_x, sizeof(double)*nIn);
      return mx;
   }   
   
   doubleVec varX() const {
      doubleVec vx(nIn);   
      memcpy(&vx[0], RF->var_x, sizeof(double)*nIn);
      return vx;
   } 
   
   doubleVec center() const {
      doubleVec c(nIn);
      memcpy(&c[0], RF->c, sizeof(double)*nIn);    
      return c;  
   }
   
   bool trustworthy() const {
      return (bool) RF->trustworthy;
   }

   std::vector<doubleVec> D() const {
      std::vector<doubleVec> ds(nIn);
      for (int i=0;i<nIn;i++) {
         ds[i].resize(nIn);
         memcpy(&ds[i][0], RF->D + i*nInS, sizeof(double)*nIn);    
      }
      return ds;
   }

   std::vector<doubleVec> M() const {
      std::vector<doubleVec> ms(nIn);
      for (int i=0;i<nIn;i++) {
         ms[i].resize(i+1);
         memcpy(&ms[i][0], RF->M + i*nInS, sizeof(double)*(i+1));    
      }
      return ms;
   }
   
   std::vector<doubleVec> U() const {
      std::vector<doubleVec> us(RF->nReg);
      for (int i=0;i<RF->nReg;i++) {
         us[i].resize(nIn);
         memcpy(&us[i][0], RF->U + i*nInS, sizeof(double)*nIn);
      }
      return us;
   }   
   
   std::vector<doubleVec> P() const {
      std::vector<doubleVec> ps(RF->nReg);
      for (int i=0;i<RF->nReg;i++) {
         ps[i].resize(nIn);
         memcpy(&ps[i][0], RF->P + i*nInS, sizeof(double)*nIn);
      }
      return ps;
   }   
   
   double beta0() const {
      return RF->beta0;
   }
   
   doubleVec beta() const {
      doubleVec be(RF->nReg);
      memcpy(&be[0], RF->beta, sizeof(double)*RF->nReg);      
      return be;
   }
   
   doubleVec numData() const {
      doubleVec nd(RF->nReg);
      memcpy(&nd[0], RF->n_data, sizeof(double)*RF->nReg);      
      return nd;
   }

   
   doubleVec slope() const {
      doubleVec s(nIn);
      doubleVec t(nIn);
      
      if (RF->slopeReady) {
         memcpy(&s[0], RF->slope, sizeof(double)*RF->nReg);
      } else {
         // calculate the slope by hand, without using any model-internal storage
         // we do this because we do not want this code to interfere with the "real"
         // LWPR_Model
         lwpr_math_scalar_vector(&s[0], RF->beta[0], RF->U, nIn);
         for (int i=1;i<RF->nReg;i++) {
            lwpr_math_scalar_vector(&t[0], RF->beta[i], RF->U + i*nInS, nIn);
            for (int j=i-1;j>=0;j--) {
               // left-multiply  (I - u_j * p_j^T)
               double dp = lwpr_math_dot_product(&t[0],RF->P + j*nInS, nIn);
               lwpr_math_add_scalar_vector(&t[0], dp, RF->U + j*nInS, nIn);
            }
            for (int m=0;m<nIn;m++) s[m]+=t[m];
         }
      }
      return s;
   }
   
   private:

   LWPR_ReceptiveFieldObject(LWPR_ReceptiveField *rf) {
      this->RF = rf;
      nIn = rf->model->nIn;
      nInS = rf->model->nInStore;
   }
   
   const LWPR_ReceptiveField *RF;
   int nIn;   
   int nInS;  
};


class LWPR_Object {
   public:
   
   LWPR_Object(int nIn, int nOut) {
      if (!lwpr_init_model(&model, nIn, nOut, NULL)) {
         throw LWPR_Exception(LWPR_Exception::OUT_OF_MEMORY);
      }
   }
   
   LWPR_Object(const LWPR_Object& otherObj) {
      if (!lwpr_duplicate_model(&(this->model), &(otherObj.model))) {
         throw LWPR_Exception(LWPR_Exception::OUT_OF_MEMORY);
      }
   }
   
   LWPR_Object(const char *filename) {
      int ok;
      // First try treating the file as binary
      ok = lwpr_read_binary(&model, filename);
      #if HAVE_LIBEXPAT
      if (!ok) {
         int numErr, numWar;
         numErr = lwpr_read_xml(&model, filename, &numWar);
         ok = (numErr == 0);
      }
      #endif
      if (!ok) throw LWPR_Exception(LWPR_Exception::IO_ERROR);
   }

   ~LWPR_Object() {
      lwpr_free_model(&model);
   }
   
   int writeXML(const char *filename) {
      return lwpr_write_xml(&model, filename);
   }
   
   int writeBinary(const char *filename) {
      return lwpr_write_binary(&model, filename);
   }
      
   doubleVec update(const doubleVec& x, const doubleVec& y) {
      doubleVec yp(model.nOut);
      
      if (x.size()!=(unsigned) model.nIn) {
         throw LWPR_Exception(LWPR_Exception::BAD_INPUT_DIM);
      }
      
      if (y.size()!=(unsigned) model.nOut) {
         throw LWPR_Exception(LWPR_Exception::BAD_OUTPUT_DIM);
      }

      if (!lwpr_update(&model, &x[0], &y[0], &yp[0], NULL)) {
         throw LWPR_Exception(LWPR_Exception::OUT_OF_MEMORY);
      }
      return yp;
   }
   
   doubleVec predict(const doubleVec& x, double cutoff = 0.001) {
      doubleVec yp(model.nOut);   

      if (x.size()!=(unsigned) model.nIn) {
         throw LWPR_Exception(LWPR_Exception::BAD_INPUT_DIM);
      }      

      lwpr_predict(&model, &x[0], cutoff, &yp[0], NULL, NULL);
      return yp;
   }
   
   doubleVec predict(const doubleVec& x, doubleVec& confidence, double cutoff = 0.001) {
      doubleVec yp(model.nOut);   
      
      if (x.size()!=(unsigned) model.nIn) {
         throw LWPR_Exception(LWPR_Exception::BAD_INPUT_DIM);
      }      
      if (confidence.size()!=(unsigned) model.nOut) confidence.resize(model.nOut);

      lwpr_predict(&model, &x[0], cutoff, &yp[0], &confidence[0], NULL);
      return yp;
   }  
   
   doubleVec predict(const doubleVec& x, doubleVec& confidence, doubleVec& maxW, double cutoff = 0.001) {
      doubleVec yp(model.nOut);   
      
      if (x.size()!=(unsigned) model.nIn) {
         throw LWPR_Exception(LWPR_Exception::BAD_INPUT_DIM);
      }      
      if (confidence.size()!=(unsigned) model.nOut) confidence.resize(model.nOut);
      if (maxW.size()!=(unsigned) model.nOut) maxW.resize(model.nOut);

      lwpr_predict(&model, &x[0], cutoff, &yp[0], &confidence[0], &maxW[0]);
      return yp;
   } 
   
   void setInitD(double delta) {
      if (!lwpr_set_init_D_spherical(&model,delta)) {
         throw LWPR_Exception(LWPR_Exception::BAD_INIT_D);
      }
   }

   void setInitD(const doubleVec& initD) {
      if (initD.size()==(unsigned) model.nIn) {
         if (!lwpr_set_init_D_diagonal(&model,&initD[0])) {
            throw LWPR_Exception(LWPR_Exception::BAD_INIT_D);
         }
      } else if (initD.size()==(unsigned) (model.nIn*model.nIn)) {
         if (!lwpr_set_init_D(&model,&initD[0],model.nIn)) {
            throw LWPR_Exception(LWPR_Exception::BAD_INIT_D);
         }
      } else {
         throw LWPR_Exception(LWPR_Exception::BAD_INPUT_DIM);
      }
   }
   
   void setInitAlpha(double alpha) {
      lwpr_set_init_alpha(&model,alpha);
   }
   
   void wGen(double w_gen) { model.w_gen = w_gen; }
   
   void wPrune(double w_prune) { model.w_prune = w_prune; }

   void penalty(double pen) { model.penalty = pen; }
   
   void initLambda(double iLam) { model.init_lambda = iLam; }
   
   void tauLambda(double tLam) { model.tau_lambda = tLam; }
      
   void finalLambda(double fLam) { model.final_lambda = fLam; }
   
   void initS2(double init_s2) { model.init_S2 = init_s2; }
   
   void updateD(bool update) { model.update_D = update ? 1:0; }
   
   void diagOnly(bool dOnly) { model.diag_only = dOnly ? 1:0; }
   
   void useMeta(bool meta) { model.meta = meta ? 1:0; }
   
   void metaRate(double rate) { model.meta_rate = rate; }
   
   void kernel(LWPR_Kernel kern) { model.kernel = kern; }
   
   void kernel(const char *str) {
      if (!strcmp(str,"Gaussian")) {
         model.kernel = LWPR_GAUSSIAN_KERNEL;
         return;
      }
      if (!strcmp(str,"BiSquare")) {
         model.kernel = LWPR_BISQUARE_KERNEL;
         return;
      }
      throw LWPR_Exception(LWPR_Exception::UNKNOWN_KERNEL);
   }
   
   int nData() const { return model.n_data; }
   
   int nIn() const { return model.nIn; }
   
   int nOut() const { return model.nOut; }
   
   double wGen() const { return model.w_gen; }
   
   double wPrune() const { return model.w_prune; }   
   
   double penalty() const { return model.penalty; }
   
   double initLambda() const { return model.init_lambda; }

   double tauLambda() const { return model.tau_lambda; }

   double finalLambda() const { return model.final_lambda; }
   
   double initS2() const { return model.init_S2; }
   
   bool updateD() { return (bool) model.update_D; }

   bool diagOnly() { return (bool) model.diag_only; }
   
   bool useMeta() { return (bool) model.meta; }
   
   double metaRate() { return model.meta_rate; }

   LWPR_Kernel kernel() { return model.kernel; }
   
   doubleVec meanX() {
      doubleVec mx(model.nIn);
      memcpy(model.mean_x,&mx[0],sizeof(double)*model.nIn);
      return mx;
   }

   doubleVec varX() {
      doubleVec vx(model.nIn);
      memcpy(model.var_x, &vx[0],sizeof(double)*model.nIn);
      return vx;
   }
   
   void normIn(const doubleVec& norm) {
      if (norm.size()!=(unsigned) model.nIn) {
         throw LWPR_Exception(LWPR_Exception::BAD_INPUT_DIM);      
      }
      memcpy(model.norm_in,&norm[0],sizeof(double)*model.nIn);
   }

   doubleVec normIn() const {
      doubleVec norm(model.nIn);
      memcpy(&norm[0],model.norm_in,sizeof(double)*model.nIn);
      return norm;
   }
   
   void normOut(const doubleVec& norm) {
      if (norm.size()!=(unsigned) model.nOut) {
         throw LWPR_Exception(LWPR_Exception::BAD_OUTPUT_DIM);
      }
      memcpy(model.norm_out,&norm[0],sizeof(double)*model.nOut);
   }

   doubleVec normOut() const {
      doubleVec norm(model.nOut);
      memcpy(&norm[0],model.norm_out,sizeof(double)*model.nOut);
      return norm;
   }
   
   int numRFS(int outDim) {
      if (outDim < 0 || outDim >= model.nOut) return 0;
      return model.sub[outDim].numRFS;
   }
   
   std::vector<int> numRFS() {
      std::vector<int> num(model.nOut);
      for (int i=0;i<model.nOut;i++) num[i] = model.sub[i].numRFS;
      return num;
   }
   
   LWPR_ReceptiveFieldObject getRF(int outDim, int index) const {
      if (outDim < 0 || outDim >= model.nOut) {
         throw LWPR_Exception(LWPR_Exception::OUT_OF_RANGE);
      }
      if (index < 0 || index >= model.sub[outDim].numRFS) { 
         throw LWPR_Exception(LWPR_Exception::OUT_OF_RANGE);
      }
      return LWPR_ReceptiveFieldObject(model.sub[outDim].rf[index]);
   }
   
   LWPR_Model model;
};

#endif

---