PLearn 0.1
Public Member Functions | Static Public Member Functions | Public Attributes | Static Public Attributes | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Private Types | Private Member Functions
PLearn::GenericNearestNeighbors Class Reference

#include <GenericNearestNeighbors.h>

Inheritance diagram for PLearn::GenericNearestNeighbors:
Inheritance graph
[legend]
Collaboration diagram for PLearn::GenericNearestNeighbors:
Collaboration graph
[legend]

List of all members.

Public Member Functions

 GenericNearestNeighbors ()
 Default constructor.
virtual void build ()
 Simply calls inherited::build() then build_().
virtual void makeDeepCopyFromShallowCopy (CopiesMap &copies)
 Transforms a shallow copy into a deep copy.
virtual GenericNearestNeighborsdeepCopy (CopiesMap &copies) const
virtual int outputsize () const
 Returns the size of this learner's output, (which typically may depend on its inputsize(), targetsize() and set options).

Static Public Member Functions

static string _classname_ ()
static OptionList_getOptionList_ ()
static RemoteMethodMap_getRemoteMethodMap_ ()
static bool _isa_ (const Object *o)
static void _static_initialize_ ()
static const PPathdeclaringFile ()

Public Attributes

int num_neighbors
 Number of nearest-neighbors to compute.
bool copy_input
 If true, the output contains a copy of the found input vector(s).
bool copy_target
 If true, the output contains a copy of the found target vector(s).
bool copy_weight
 If true, the output contains a copy of the found weight.
bool copy_index
 If true, the output contains the index of the found neighbor (as the row number, zero-based, in the training set.)
Ker distance_kernel
 An optional alternative to the Euclidean distance (DistanceKernel with n=2 and pow_distance=1).

Static Public Attributes

static StaticInitializer _static_initializer_

Protected Member Functions

void constructOutputVector (const TVec< int > &indices, Vec &output, const Mat &train_mat_override=Mat()) const
 From a vector of indexes into the training set, expand them into an output vector for the learner, and take into account all the options.

Static Protected Member Functions

static void declareOptions (OptionList &ol)
 Declares this class' options.

Protected Attributes

Vec currow
 Internal buffer for constructing the output vector.

Private Types

typedef PLearner inherited

Private Member Functions

void build_ ()
 This does the actual building.

Detailed Description

Definition at line 93 of file GenericNearestNeighbors.h.


Member Typedef Documentation

Reimplemented from PLearn::PLearner.

Reimplemented in PLearn::BallTreeNearestNeighbors, and PLearn::ExhaustiveNearestNeighbors.

Definition at line 95 of file GenericNearestNeighbors.h.


Constructor & Destructor Documentation

PLearn::GenericNearestNeighbors::GenericNearestNeighbors ( )

Default constructor.

Definition at line 96 of file GenericNearestNeighbors.cc.

    : num_neighbors(1),
      copy_input(false),
      copy_target(true),
      copy_weight(false),
      copy_index(false)
{ }

Member Function Documentation

string PLearn::GenericNearestNeighbors::_classname_ ( ) [static]

Reimplemented from PLearn::PLearner.

Reimplemented in PLearn::BallTreeNearestNeighbors, and PLearn::ExhaustiveNearestNeighbors.

Definition at line 94 of file GenericNearestNeighbors.cc.

OptionList & PLearn::GenericNearestNeighbors::_getOptionList_ ( ) [static]

Reimplemented from PLearn::PLearner.

Reimplemented in PLearn::BallTreeNearestNeighbors, and PLearn::ExhaustiveNearestNeighbors.

Definition at line 94 of file GenericNearestNeighbors.cc.

RemoteMethodMap & PLearn::GenericNearestNeighbors::_getRemoteMethodMap_ ( ) [static]

Reimplemented from PLearn::PLearner.

Reimplemented in PLearn::BallTreeNearestNeighbors, and PLearn::ExhaustiveNearestNeighbors.

Definition at line 94 of file GenericNearestNeighbors.cc.

bool PLearn::GenericNearestNeighbors::_isa_ ( const Object o) [static]

Reimplemented from PLearn::PLearner.

Reimplemented in PLearn::BallTreeNearestNeighbors, and PLearn::ExhaustiveNearestNeighbors.

Definition at line 94 of file GenericNearestNeighbors.cc.

StaticInitializer GenericNearestNeighbors::_static_initializer_ & PLearn::GenericNearestNeighbors::_static_initialize_ ( ) [static]

Reimplemented from PLearn::PLearner.

Reimplemented in PLearn::BallTreeNearestNeighbors, and PLearn::ExhaustiveNearestNeighbors.

Definition at line 94 of file GenericNearestNeighbors.cc.

void PLearn::GenericNearestNeighbors::build ( ) [virtual]

Simply calls inherited::build() then build_().

Reimplemented from PLearn::PLearner.

Reimplemented in PLearn::BallTreeNearestNeighbors, and PLearn::ExhaustiveNearestNeighbors.

Definition at line 184 of file GenericNearestNeighbors.cc.

References PLearn::PLearner::build(), and build_().

Referenced by PLearn::ExhaustiveNearestNeighbors::build(), and PLearn::BallTreeNearestNeighbors::build().

Here is the call graph for this function:

Here is the caller graph for this function:

void PLearn::GenericNearestNeighbors::build_ ( ) [private]

This does the actual building.

Just some sanity checking on the options

Reimplemented from PLearn::PLearner.

Reimplemented in PLearn::BallTreeNearestNeighbors, and PLearn::ExhaustiveNearestNeighbors.

Definition at line 168 of file GenericNearestNeighbors.cc.

References copy_index, copy_input, copy_target, copy_weight, distance_kernel, num_neighbors, and PLERROR.

Referenced by build().

{
    if (num_neighbors <= 0)
        PLERROR("GenericNearestNeighbors::build_: the option \"num_neighbors\" "
                "must be strictly positive");
    if (! (copy_input || copy_target || copy_weight || copy_index))
        PLERROR("GenericNearestNeighbors::build_: at least one of the options "
                "\"copy_input\", \"copy_target\", \"copy_weight\", \"copy_index\" "
                "must be specified (i.e. true)");
    if (!distance_kernel)
        // Default is ordinary Euclidean squared distance (i.e. sum of square differences).
        distance_kernel = new DistanceKernel(2,true);
}

Here is the caller graph for this function:

void PLearn::GenericNearestNeighbors::constructOutputVector ( const TVec< int > &  indices,
Vec output,
const Mat train_mat_override = Mat() 
) const [protected]

From a vector of indexes into the training set, expand them into an output vector for the learner, and take into account all the options.

One can pass less than num_neighbors indices, in which case the rest of the output vector is filled with missings. In addition, one can pass a Mat from which the data will be obtained instead of the (virtual matrix) training set. This is faster.

Definition at line 221 of file GenericNearestNeighbors.cc.

References std::copy(), copy_index, copy_input, copy_target, copy_weight, currow, PLearn::TVec< T >::data(), PLearn::TVec< T >::end(), i, PLearn::PLearner::inputsize(), PLearn::TMat< T >::isNotNull(), PLearn::min(), MISSING_VALUE, n, num_neighbors, outputsize(), PLASSERT, PLearn::TVec< T >::resize(), PLearn::TVec< T >::size(), PLearn::PLearner::targetsize(), PLearn::PLearner::train_set, PLearn::PLearner::weightsize(), and PLearn::VMat::width().

Referenced by PLearn::ExhaustiveNearestNeighbors::computeOutput(), PLearn::BallTreeNearestNeighbors::computeOutput(), PLearn::BallTreeNearestNeighbors::computeOutputAndCosts(), and PLearn::ExhaustiveNearestNeighbors::computeOutputAndCosts().

{
    // PLASSERT( output.size() == outputsize() );
    output.resize(outputsize());

    int i, n=min(num_neighbors, indices.size());
    int inputsize = train_set->inputsize();
    int targetsize = train_set->targetsize();
    int weightsize = train_set->weightsize();
    real* output_data = output.data();

    currow.resize(train_set.width());
    for (i=0 ; i<n ; ++i) {
        real* currow_data = 0;
        if (train_mat_override.isNotNull())
            currow_data = train_mat_override[indices[i]];
        else {
            train_set->getRow(indices[i], currow);
            currow_data = currow.data();
        }
        PLASSERT( currow_data );

        if(copy_input) {
            copy(currow_data, currow_data+inputsize, output_data);
            output_data += inputsize;
        }
        currow_data += inputsize;
    
        if(copy_target) {
            copy(currow_data, currow_data+targetsize, output_data);
            output_data += targetsize;
        }
        currow_data += targetsize;
    
        if(copy_weight) {
            if(weightsize) {
                copy(currow_data, currow_data+weightsize, output_data);
                output_data += weightsize;
            }
            else
                *output_data++ = 1.0;
        }

        if (copy_index)
            *output_data++ = real(indices[i]);
    }

    if (n < num_neighbors)
        fill(output_data, output.end(), MISSING_VALUE);
}

Here is the call graph for this function:

Here is the caller graph for this function:

void PLearn::GenericNearestNeighbors::declareOptions ( OptionList ol) [static, protected]

Declares this class' options.

Reimplemented from PLearn::PLearner.

Reimplemented in PLearn::BallTreeNearestNeighbors, and PLearn::ExhaustiveNearestNeighbors.

Definition at line 104 of file GenericNearestNeighbors.cc.

References PLearn::OptionBase::buildoption, copy_index, copy_input, copy_target, copy_weight, PLearn::declareOption(), PLearn::PLearner::declareOptions(), distance_kernel, PLearn::OptionBase::learntoption, num_neighbors, and PLearn::PLearner::train_set.

Referenced by PLearn::ExhaustiveNearestNeighbors::declareOptions(), and PLearn::BallTreeNearestNeighbors::declareOptions().

{
    /*  train_set is normally not saved in the PLearner base class. 
        But the current implementation of GenericNearestNeighbors, 
        unfortunately seems to require to keep it around. 
        Important note: if this requirement is some day removed (as it should),
        beware that subclasses such as ExhaustiveNearestNeighbor rely on the
        train_set being available. Thus the delareOption for train_set should
        then be moved to such sub-classes that need to access it.
    */
    declareOption(
        ol, "train_set", &GenericNearestNeighbors::train_set,
        OptionBase::learntoption,
        "train_set is normally not saved in the PLearner base class, \n"
        "But the current implementation of GenericNearestNeighbors, requires\n"
        "to keep it around. (see comment in .cc file if you plan to remove\n"
        "this unnecessary requirement)");

    declareOption(
        ol, "num_neighbors", &GenericNearestNeighbors::num_neighbors,
        OptionBase::buildoption,
        "Number of nearest-neighbors to compute.  This is usually called \"K\".\n"
        "The output vector is simply the concatenation of all found neighbors.\n"
        "(Default = 1)");

    declareOption(
        ol, "copy_input", &GenericNearestNeighbors::copy_input,
        OptionBase::buildoption,
        "If true, the output contains a copy of the found input vector(s).\n"
        "(Default = false)");

    declareOption(
        ol, "copy_target", &GenericNearestNeighbors::copy_target,
        OptionBase::buildoption,
        "If true, the output contains a copy of the found target vector(s).\n"
        "(Default = true)");

    declareOption(
        ol, "copy_weight", &GenericNearestNeighbors::copy_weight,
        OptionBase::buildoption,
        "If true, the output contains a copy of the found weight.  If no\n"
        "weight is present in the training set, a weight of 1.0 is put.\n"
        "(Default = true)");

    declareOption(
        ol, "copy_index", &GenericNearestNeighbors::copy_index,
        OptionBase::buildoption,
        "If true, the output contains the index of the found neighbor\n"
        "(as the row number, zero-based, in the training set.)\n"
        "(Default = false)");
  
    declareOption(
        ol, "distance_kernel", &GenericNearestNeighbors::distance_kernel,
        OptionBase::buildoption,
        "An optional alternative to the Euclidean distance (DistanceKernel with\n"
        "n=2 and pow_distance=1).  It should be a 'distance-like' kernel rather\n"
        "than a 'dot-product-like' kernel, i.e. small when the arguments are\n"
        "similar, and it should always be non-negative, and 0 only if arguments\n"
        "are equal.\n");

    // Now call the parent class' declareOptions
    inherited::declareOptions(ol);
}

Here is the call graph for this function:

Here is the caller graph for this function:

static const PPath& PLearn::GenericNearestNeighbors::declaringFile ( ) [inline, static]

Reimplemented from PLearn::PLearner.

Reimplemented in PLearn::BallTreeNearestNeighbors, and PLearn::ExhaustiveNearestNeighbors.

Definition at line 150 of file GenericNearestNeighbors.h.

:
    //#####  PLearner Methods  ################################################
GenericNearestNeighbors * PLearn::GenericNearestNeighbors::deepCopy ( CopiesMap copies) const [virtual]

Reimplemented from PLearn::PLearner.

Reimplemented in PLearn::BallTreeNearestNeighbors, and PLearn::ExhaustiveNearestNeighbors.

Definition at line 94 of file GenericNearestNeighbors.cc.

void PLearn::GenericNearestNeighbors::makeDeepCopyFromShallowCopy ( CopiesMap copies) [virtual]

Transforms a shallow copy into a deep copy.

Reimplemented from PLearn::PLearner.

Reimplemented in PLearn::BallTreeNearestNeighbors, and PLearn::ExhaustiveNearestNeighbors.

Definition at line 191 of file GenericNearestNeighbors.cc.

References currow, PLearn::deepCopyField(), distance_kernel, and PLearn::PLearner::makeDeepCopyFromShallowCopy().

Referenced by PLearn::ExhaustiveNearestNeighbors::makeDeepCopyFromShallowCopy(), and PLearn::BallTreeNearestNeighbors::makeDeepCopyFromShallowCopy().

Here is the call graph for this function:

Here is the caller graph for this function:

int PLearn::GenericNearestNeighbors::outputsize ( ) const [virtual]

Returns the size of this learner's output, (which typically may depend on its inputsize(), targetsize() and set options).

Implements PLearn::PLearner.

Definition at line 200 of file GenericNearestNeighbors.cc.

References copy_index, copy_input, copy_target, copy_weight, num_neighbors, PLASSERT, and PLearn::PLearner::train_set.

Referenced by PLearn::BallTreeNearestNeighbors::computeCostsFromOutputs(), PLearn::ExhaustiveNearestNeighbors::computeCostsFromOutputs(), PLearn::BallTreeNearestNeighbors::computeOutput(), PLearn::BallTreeNearestNeighbors::computeOutputAndCosts(), and constructOutputVector().

{
    if (!train_set)
        // We do not have a training set yet.
        return -1;
    int base_outputsize = 0;
    if (copy_input)
        base_outputsize += train_set->inputsize();
    if (copy_target)
        base_outputsize += train_set->targetsize();
    if (copy_weight)
        base_outputsize += 1;
    if (copy_index)
        base_outputsize += 1;

    PLASSERT( num_neighbors > 0 );
    PLASSERT( base_outputsize > 0 );
  
    return num_neighbors * base_outputsize;
}

Here is the caller graph for this function:


Member Data Documentation

Reimplemented from PLearn::PLearner.

Reimplemented in PLearn::BallTreeNearestNeighbors, and PLearn::ExhaustiveNearestNeighbors.

Definition at line 150 of file GenericNearestNeighbors.h.

If true, the output contains the index of the found neighbor (as the row number, zero-based, in the training set.)

Definition at line 123 of file GenericNearestNeighbors.h.

Referenced by build_(), PLearn::BallTreeNearestNeighbors::computeCostsFromOutputs(), constructOutputVector(), declareOptions(), and outputsize().

If true, the output contains a copy of the found input vector(s).

(Default = false)

Definition at line 110 of file GenericNearestNeighbors.h.

Referenced by build_(), PLearn::BallTreeNearestNeighbors::computeCostsFromOutputs(), constructOutputVector(), declareOptions(), and outputsize().

If true, the output contains a copy of the found target vector(s).

(Default = true)

Definition at line 114 of file GenericNearestNeighbors.h.

Referenced by build_(), PLearn::BallTreeNearestNeighbors::computeCostsFromOutputs(), constructOutputVector(), declareOptions(), and outputsize().

If true, the output contains a copy of the found weight.

If no weight is present in the training set, a weight of 1.0 is put. (Default = true)

Definition at line 119 of file GenericNearestNeighbors.h.

Referenced by build_(), PLearn::BallTreeNearestNeighbors::computeCostsFromOutputs(), constructOutputVector(), declareOptions(), and outputsize().

Internal buffer for constructing the output vector.

Definition at line 99 of file GenericNearestNeighbors.h.

Referenced by constructOutputVector(), and makeDeepCopyFromShallowCopy().

An optional alternative to the Euclidean distance (DistanceKernel with n=2 and pow_distance=1).

It should be a 'distance-like' kernel rather than a 'dot-product-like' kernel, i.e. small when the arguments are similar, and it should always be non-negative, and 0 only if arguments are equal.

Definition at line 132 of file GenericNearestNeighbors.h.

Referenced by PLearn::BallTreeNearestNeighbors::anchorTrain(), PLearn::ExhaustiveNearestNeighbors::build_(), build_(), declareOptions(), PLearn::ExhaustiveNearestNeighbors::declareOptions(), PLearn::ExhaustiveNearestNeighbors::ExhaustiveNearestNeighbors(), PLearn::ExhaustiveNearestNeighbors::findNearestNeighbors(), and makeDeepCopyFromShallowCopy().


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines