RealMapping.h

Go to the documentation of this file.

// -*- C++ -*-

// PLearn (A C++ Machine Learning Library)
// Copyright (C) 1998 Pascal Vincent
// Copyright (C) 1999-2002 Pascal Vincent, Yoshua Bengio and University of Montreal
//

// 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: RealMapping.h,v 1.19 2004/07/21 16:30:50 chrish42 Exp $
   * This file is part of the PLearn library.
   ******************************************************* */

#ifndef RealMapping_INC
#define RealMapping_INC

//#include "general.h"
#include "Object.h"
#include <plearn/math/TMat.h>
#include <map>

namespace PLearn {
using namespace std;

class RealRange
  {
  public:
    real low;
    real high;
    char leftbracket; // either '[' (inclusive left) or ']' (exclusive left)
    char rightbracket; // // either '[' (exclusive right) or ']' (inclusive right)

  public:
    RealRange(): // default construvtor
      low(0), high(0), leftbracket(']'), rightbracket('[')
    {}
     

    RealRange(char leftbracket_, real low_, real high_, char rightbracket_):
      low(low_), high(high_), leftbracket(leftbracket_), rightbracket(rightbracket_)
    { checkbrackets(); } 

    real span(){return abs(high-low);}
    
    void checkbrackets() const
    {
      if( (leftbracket!='[' && leftbracket!=']') || (rightbracket!='[' && rightbracket!=']') )
        PLERROR("In RealRange: Brackets must be either '[' or ']'"); 
    }

    void print(ostream& out) const
    { out << leftbracket << low << ' ' << high << rightbracket; }

    void write(ostream& out) const
    { out << leftbracket << low << ' ' << high << rightbracket; }

    void read(istream& in)
    { in >> leftbracket >> low >> high >> rightbracket; checkbrackets(); }


    string getString() const;
    
    bool contains(real val) const;
    bool operator<(real x) const;
    bool operator>(real x) const;

/*    inline bool operator<(real x) const
    { return low < x || high == x && rightbracket == '['; }

    inline bool operator>(real x) const
    { return low > x || low == x && leftbracket == ']'; }

*/
    bool operator<(const RealRange& x) const;
    bool operator>(const RealRange& x) const;
    bool operator==(const RealRange& rr) const;
  };

  inline void write(ostream& out, const RealRange& range) { range.write(out); }
  inline ostream& operator<<(ostream& out, const RealRange& range) { range.print(out); return out; } 
  inline void read(istream& in, RealRange& range) { range.read(in); }

PStream& operator<<(PStream& out, const RealRange& x);
PStream& operator>>(PStream& in, RealRange &x);


  class RealMapping: public Object
  {
  protected: 
    static void declareOptions(OptionList& ol);

  public:
    typedef pair<RealRange, real> single_mapping_t;
    typedef TVec< single_mapping_t > ordered_mapping_t;
    typedef map<RealRange, real> mapping_t;
    typedef mapping_t::iterator iterator;
    typedef mapping_t::const_iterator const_iterator;
    mapping_t mapping; // defines mapping from real ranges to values
    // o_mapping contains the same mappings as 'mapping', but they are 
    // ordered so that the lower limits of ranges are in ascending order
    // NOTE : before any access, it must be created with a call to buildOrderedMapping()
    ordered_mapping_t o_mapping; 
    real missing_mapsto; // value to which to map missing values (can be missing value)
    bool keep_other_as_is; // if true, values not in mapping are left as is, otherwise they're mappred to other_mapsto
    real other_mapsto; // value to which to map values not inmapping, if keep_other_as_is is false 
    
  public:
    typedef Object inherited;
    PLEARN_DECLARE_OBJECT(RealMapping);
    
    RealMapping()
      :missing_mapsto(MISSING_VALUE),
       keep_other_as_is(true),
       other_mapsto(MISSING_VALUE)
    {}

    int size() const { return (int)mapping.size(); }
    int length() const { return (int)mapping.size(); }

    inline void clear() { mapping.clear(); }
    
    void buildOrderedMapping();

    bool checkConsistency();

    void removeMapping(const RealRange& range)
    { 
      mapping_t::iterator it= mapping.find(range);
      if(it != mapping.end())
        mapping.erase(it);
      else
        PLWARNING("In RealMapping::removeMapping  mapping not removed: does not exist.");
    }

    void removeMapping(real x) //remove range where x falls
    {
      mapping_t::iterator it= mapping.lower_bound(RealRange('[',x,x,']'));
      if(it != mapping.end() && it->first.contains(x))
        mapping.erase(it);
      else
        PLWARNING("In RealMapping::removeMapping  mapping not removed: does not exist.");
    }

    void addMapping(const RealRange& range, real val);

    void setMappingForMissing(real what_missing_mapsto)
    { missing_mapsto = what_missing_mapsto; }

    void setMappingForOther(real what_other_mapsto)
    { keep_other_as_is=false; other_mapsto = what_other_mapsto; }

    void keepOtherAsIs() 
    { keep_other_as_is=true; }

    // returns the mapped value corresponding to val
    real map(real val) const;

    // returns the number of the bin in which 'val' falls
    int binnumber(real val) const;

    // transforms v by applying the mapping on all its elements
    void transform(const Vec& v) const;

    pair<RealRange, real> lastMapping() 
    { return *(mapping.rbegin()); }
    //    { return mapping.lastElement(); }

    /***
     * map methods "forwarded"
     */

    iterator begin()
    { return mapping.begin(); }
    const_iterator begin() const
    { return mapping.begin(); }
    iterator end()
    { return mapping.end(); }
    const_iterator end() const
    { return mapping.end(); }
    void erase(iterator it) 
    { mapping.erase(it); }

    bool operator==(const RealMapping& rm) const;

    virtual void print(ostream& out) const;
    virtual void write(ostream& out) const;
    virtual void read(istream& in);

    real maxMappedToValue();

    Vec getCutPoints() const;

  };

  DECLARE_OBJECT_PTR(RealMapping);

} // end of namespace PLearn

#endif

---