PLearn::Kernel Class Reference

#include <Kernel.h>

Inheritance diagram for PLearn::Kernel:

[legend]Collaboration diagram for PLearn::Kernel:

[legend]List of all members.


Public Member Functions
	Kernel (bool is__symmetric=true)
	Constructor.
	PLEARN_DECLARE_ABSTRACT_OBJECT (Kernel)
virtual real	evaluate (const Vec &x1, const Vec &x2) const =0
	returns K(x1,x2)
virtual void	setDataForKernelMatrix (VMat the_data)
	Subclasses may overload these methods to provide efficient kernel matrix access
virtual void	addDataForKernelMatrix (const Vec &newRow)
virtual int	dataInputsize ()
	Return data_inputsize.
virtual int	nExamples ()
	Return n_examples.
virtual real	evaluate_i_j (int i, int j) const
	returns evaluate(data(i),data(j))
virtual real	evaluate_i_x (int i, const Vec &x, real squared_norm_of_x=-1) const
virtual real	evaluate_x_i (const Vec &x, int i, real squared_norm_of_x=-1) const
	returns evaluate(x,data(i)) [default version calls evaluate_i_x if kernel is_symmetric]
virtual real	evaluate_i_x_again (int i, const Vec &x, real squared_norm_of_x=-1, bool first_time=false) const
	Return evaluate(data(i),x), where x is the same as in the precedent call to this same function (except if 'first_time' is true).
virtual real	evaluate_x_i_again (const Vec &x, int i, real squared_norm_of_x=-1, bool first_time=false) const
virtual void	computeGramMatrix (Mat K) const
	Call evaluate_i_j to fill each of the entries (i,j) of symmetric matrix K.
virtual void	setParameters (Vec paramvec)
	default version produces an error
virtual Vec	getParameters () const
	default version returns an empty Vec
void	apply (VMat m1, VMat m2, Mat &result) const
	result(i,j) = K(m1(i),m2(j))
Mat	apply (VMat m1, VMat m2) const
	same as above, but returns the result mat instead
void	apply (VMat m, const Vec &x, Vec &result) const
	result[i]=K(m[i],x)
void	apply (Vec x, VMat m, Vec &result) const
	result[i]=K(x,m[i])
void	evaluate_all_i_x (const Vec &x, Vec &k_xi_x, real squared_norm_of_x=-1, int istart=0) const
	Fill k_xi_x with K(x_i, x), for all i from istart to istart + k_xi_x.length() - 1.
void	evaluate_all_x_i (const Vec &x, Vec &k_x_xi, real squared_norm_of_x=-1, int istart=0) const
	Fill k_x_xi with K(x, x_i), for all i from istart to istart + k_x_xi.length() - 1.
real	operator() (const Vec &x1, const Vec &x2) const
bool	hasData ()
	Return true iif there is a data matrix set for this kernel.
VMat	getData ()
	Return the data matrix set for this kernel.
bool	isInData (const Vec &x, int *i=0) const
	Return true iff the point x is in the kernel dataset.
void	computeNearestNeighbors (const Vec &x, Mat &k_xi_x_sorted, int knn) const
	Fill 'k_xi_x_sorted' with the value of K(x, x_i) for all training points x_i in the first column (with the knn first ones being sorted according to increasing value of K(x, x_i)), and with the indices of the corresponding neighbors in the second column.
Mat	estimateHistograms (VMat d, real sameness_threshold, real minval, real maxval, int nbins) const
Mat	estimateHistograms (Mat input_and_class, real minval, real maxval, int nbins) const
real	test (VMat d, real threshold, real sameness_below_threshold, real sameness_above_threshold) const
virtual void	build ()
	Should call simply inherited::build(), then this class's build_().
virtual	~Kernel ()
virtual void	makeDeepCopyFromShallowCopy (CopiesMap &copies)
Static Public Member Functions
TMat< int >	computeKNNeighbourMatrixFromDistanceMatrix (const Mat &D, int knn, bool insure_self_first_neighbour=true, bool report_progress=false)
	Returns a Mat m such that m(i,j) is the index of jth closest neighbour of input i, according to the "distance" measures given by D(i,j).
Mat	computeNeighbourMatrixFromDistanceMatrix (const Mat &D, bool insure_self_first_neighbour=true, bool report_progress=false)
	Returns a Mat m such that m(i,j) is the index of jth closest neighbour of input i, according to the "distance" measures given by D(i,j) You should use computeKNNeighbourMatrixFromDistanceMatrix instead.
Public Attributes
bool	is_symmetric
	Build options.
int	report_progress
VMat	specify_dataset
Static Protected Member Functions
void	declareOptions (OptionList &ol)
	redefine this in subclasses: call declareOption(...) for each option, and then call inherited::declareOptions(options) ( see the declareOption function further down)
Protected Attributes
VMat	data
	data for kernel matrix, which will be used for calls to evaluate_i_j and the like
int	data_inputsize
int	n_examples
Private Types
typedef Object	inherited
Private Member Functions
void	build_ ()
Private Attributes
Vec	evaluate_xi
	Used to store data to save memory allocation.
Vec	evaluate_xj
	Used to store data to save memory allocation.
Vec	k_xi_x
	Used to store data to save memory allocation.
bool	lock_xi
	Used to make sure we do not accidentally overwrite some global data.
bool	lock_xj
	Used to make sure we do not accidentally overwrite some global data.
bool	lock_k_xi_x
	Used to make sure we do not accidentally overwrite some global data.

Member Typedef Documentation

Constructor & Destructor Documentation

PLearn::Kernel::Kernel ( bool is__symmetric = true )

Constructor.

Definition at line 57 of file Kernel.cc.

PLearn::Kernel::~Kernel ( ) [virtual]

Definition at line 52 of file Kernel.cc.

Member Function Documentation

void PLearn::Kernel::addDataForKernelMatrix ( const Vec & newRow ) [virtual]

This method is meant to be used any time the data matrix is appended a new row by an outer instance (e.g. SequentialKernel). Through this method, the kernel must update any data dependent internal structure. The internal structures should have consistent length with the data matrix, assuming a sequential growing of the vmat.
Reimplemented in PLearn::GaussianKernel, PLearn::PrecomputedKernel, and PLearn::SourceKernel.
Definition at line 148 of file Kernel.cc.
References data, and PLERROR.

void PLearn::Kernel::apply ( Vec x,

VMat m,

Vec & result

) const

result[i]=K(x,m[i])

Definition at line 441 of file Kernel.cc.
References evaluate(), PLearn::VMat::getSubRow(), PLearn::VMat::length(), PLearn::TVec< T >::resize(), PLearn::VMat::width(), and x.

void PLearn::Kernel::apply ( VMat m,

const Vec & x,

Vec & result

) const

result[i]=K(m[i],x)

Definition at line 425 of file Kernel.cc.
References evaluate(), PLearn::VMat::getSubRow(), PLearn::VMat::length(), PLearn::TVec< T >::resize(), PLearn::VMat::width(), and x.

Mat PLearn::Kernel::apply ( VMat m1,

VMat m2

) const

same as above, but returns the result mat instead

Definition at line 457 of file Kernel.cc.
References PLearn::apply().

void PLearn::Kernel::apply ( VMat m1,

VMat m2,

Mat & result

) const

result(i,j) = K(m1(i),m2(j))

Definition at line 359 of file Kernel.cc.
References PLearn::Object::classname(), count, evaluate(), PLearn::VMat::getSubRow(), is_symmetric, PLearn::VMat::length(), report_progress, PLearn::TMat< T >::resize(), PLearn::ProgressBar::update(), val, and PLearn::VMat::width().

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

Should call simply inherited::build(), then this class's build_().
This method should be callable again at later times, after modifying some option fields to change the "architecture" of the object.
Reimplemented from PLearn::Object.
Reimplemented in PLearn::AdditiveNormalizationKernel, PLearn::DivisiveNormalizationKernel, PLearn::GaussianKernel, PLearn::GeodesicDistanceKernel, PLearn::LLEKernel, PLearn::PrecomputedKernel, PLearn::ReconstructionWeightsKernel, and PLearn::SourceKernel.
Definition at line 99 of file Kernel.cc.
References build_().
Referenced by PLearn::RemoveDuplicateVMatrix::build_(), and PLearn::KNNVMatrix::build_().

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

This method should be redefined in subclasses and do the actual building of the object according to previously set option fields. Constructors can just set option fields, and then call build_. This method is NOT virtual, and will typically be called only from three places: a constructor, the public virtual build() method, and possibly the public virtual read method (which calls its parent's read). build_() can assume that it's parent's build_ has already been called.
Reimplemented from PLearn::Object.
Reimplemented in PLearn::AdditiveNormalizationKernel, PLearn::DivisiveNormalizationKernel, PLearn::GaussianKernel, PLearn::GeodesicDistanceKernel, PLearn::LLEKernel, PLearn::PrecomputedKernel, PLearn::ReconstructionWeightsKernel, and PLearn::SourceKernel.
Definition at line 107 of file Kernel.cc.
References setDataForKernelMatrix(), and specify_dataset.
Referenced by build().

void PLearn::Kernel::computeGramMatrix ( Mat K ) const [virtual]

Call evaluate_i_j to fill each of the entries (i,j) of symmetric matrix K.

Reimplemented in PLearn::AdditiveNormalizationKernel, PLearn::DivisiveNormalizationKernel, PLearn::LLEKernel, and PLearn::SourceKernel.
Definition at line 303 of file Kernel.cc.
References PLearn::Object::classname(), count, data, evaluate_i_j(), PLearn::VMat::length(), PLearn::TMat< T >::mod(), PLERROR, report_progress, and PLearn::ProgressBar::update().
Referenced by PLearn::RemoveDuplicateVMatrix::build_(), and PLearn::KNNVMatrix::build_().

TMat< int > PLearn::Kernel::computeKNNeighbourMatrixFromDistanceMatrix ( const Mat & D,

int knn,

bool insure_self_first_neighbour = true,

bool report_progress = false

) [static]

Returns a Mat m such that m(i,j) is the index of jth closest neighbour of input i, according to the "distance" measures given by D(i,j).
Only knn neighbours are computed.
Definition at line 497 of file Kernel.cc.
References PLearn::TMat< T >::column(), PLearn::TMat< T >::length(), PLearn::partialSortRows(), and PLearn::ProgressBar::update().

void PLearn::Kernel::computeNearestNeighbors ( const Vec & x,

Mat & k_xi_x_sorted,

int knn

) const

Fill 'k_xi_x_sorted' with the value of K(x, x_i) for all training points x_i in the first column (with the knn first ones being sorted according to increasing value of K(x, x_i)), and with the indices of the corresponding neighbors in the second column.

Definition at line 275 of file Kernel.cc.
References evaluate_all_i_x(), k_xi_x, lock_k_xi_x, PLearn::Mat, n_examples, PLearn::partialSortRows(), PLearn::TMat< T >::resize(), PLearn::TVec< T >::resize(), and x.

Mat PLearn::Kernel::computeNeighbourMatrixFromDistanceMatrix ( const Mat & D,

bool insure_self_first_neighbour = true,

bool report_progress = false

) [static]

Returns a Mat m such that m(i,j) is the index of jth closest neighbour of input i, according to the "distance" measures given by D(i,j) You should use computeKNNeighbourMatrixFromDistanceMatrix instead.

Definition at line 536 of file Kernel.cc.
References PLearn::TMat< T >::column(), PLearn::TMat< T >::length(), PLearn::sortRows(), and PLearn::ProgressBar::update().
Referenced by PLearn::KNNVMatrix::build_().

virtual int PLearn::Kernel::dataInputsize ( ) [inline, virtual]

Return data_inputsize.

Definition at line 109 of file Kernel.h.
References data_inputsize.

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

redefine this in subclasses: call declareOption(...) for each option, and then call inherited::declareOptions(options) ( see the declareOption function further down)
ex: static void declareOptions(OptionList& ol) { declareOption(ol, "inputsize", &MyObject::inputsize_, OptionBase::buildoption, "the size of the input\n it must be provided"); declareOption(ol, "weights", &MyObject::weights, OptionBase::learntoption, "the learnt model weights"); inherited::declareOptions(ol); }
Reimplemented from PLearn::Object.
Reimplemented in PLearn::AdditiveNormalizationKernel, PLearn::ClassErrorCostFunction, PLearn::ClassMarginCostFunction, PLearn::CompactVMatrixGaussianKernel, PLearn::CompactVMatrixPolynomialKernel, PLearn::ConvexBasisKernel, PLearn::DistanceKernel, PLearn::DivisiveNormalizationKernel, PLearn::GaussianDensityKernel, PLearn::GaussianKernel, PLearn::GeneralizedDistanceRBFKernel, PLearn::GeodesicDistanceKernel, PLearn::LaplacianKernel, PLearn::LiftBinaryCostFunction, PLearn::LLEKernel, PLearn::LogOfGaussianDensityKernel, PLearn::NegKernel, PLearn::NegLogProbCostFunction, PLearn::NormalizedDotProductKernel, PLearn::PolynomialKernel, PLearn::PowDistanceKernel, PLearn::PrecomputedKernel, PLearn::PricingTransactionPairProfitFunction, PLearn::QuadraticUtilityCostFunction, PLearn::ReconstructionWeightsKernel, PLearn::ScaledGaussianKernel, PLearn::ScaledGeneralizedDistanceRBFKernel, PLearn::SelectedOutputCostFunction, PLearn::SigmoidalKernel, PLearn::SigmoidPrimitiveKernel, PLearn::SourceKernel, PLearn::SquaredErrorCostFunction, and PLearn::WeightedCostFunction.
Definition at line 70 of file Kernel.cc.
References PLearn::declareOption(), and PLearn::OptionList.

Mat PLearn::Kernel::estimateHistograms ( Mat input_and_class,

real minval,

real maxval,

int nbins

) const

Definition at line 608 of file Kernel.cc.
References PLearn::TMat< T >::column(), PLearn::dist(), evaluate(), PLearn::TVec< T >::length(), PLearn::TMat< T >::length(), PLearn::TMat< T >::subMatColumns(), PLearn::sum(), and PLearn::TMat< T >::width().

Mat PLearn::Kernel::estimateHistograms ( VMat d,

real sameness_threshold,

real minval,

real maxval,

int nbins

) const

Definition at line 571 of file Kernel.cc.
References evaluate(), PLearn::VMat::length(), PLearn::TVec< T >::subVec(), and PLearn::VMat::width().

void PLearn::Kernel::evaluate_all_i_x ( const Vec & x,

Vec & k_xi_x,

real squared_norm_of_x = -1,

int istart = 0

) const

Fill k_xi_x with K(x_i, x), for all i from istart to istart + k_xi_x.length() - 1.

Definition at line 246 of file Kernel.cc.
References evaluate_i_x_again(), PLearn::TVec< T >::length(), and x.
Referenced by computeNearestNeighbors().

void PLearn::Kernel::evaluate_all_x_i ( const Vec & x,

Vec & k_x_xi,

real squared_norm_of_x = -1,

int istart = 0

) const

Fill k_x_xi with K(x, x_i), for all i from istart to istart + k_x_xi.length() - 1.

Definition at line 257 of file Kernel.cc.
References evaluate_x_i_again(), PLearn::TVec< T >::length(), and x.

real PLearn::Kernel::evaluate_i_j ( int i,

int j

) const [virtual]

returns evaluate(data(i),data(j))

Reimplemented in PLearn::AdditiveNormalizationKernel, PLearn::DistanceKernel, PLearn::DivisiveNormalizationKernel, PLearn::DotProductKernel, PLearn::GaussianKernel, PLearn::GeodesicDistanceKernel, PLearn::LLEKernel, PLearn::PolynomialKernel, PLearn::PrecomputedKernel, PLearn::ReconstructionWeightsKernel, and PLearn::SourceKernel.
Definition at line 163 of file Kernel.cc.
References data, data_inputsize, evaluate(), evaluate_xi, evaluate_xj, PLearn::VMat::getSubRow(), lock_xi, lock_xj, and PLearn::TVec< T >::resize().
Referenced by computeGramMatrix().

real PLearn::Kernel::evaluate_i_x ( int i,

const Vec & x,

real squared_norm_of_x = -1

) const [virtual]

returns evaluate(data(i),x) [squared_norm_of_x is just a hint that may allow to speed up computation if it is already known, but it's optional]
Reimplemented in PLearn::AdditiveNormalizationKernel, PLearn::DivisiveNormalizationKernel, PLearn::DotProductKernel, PLearn::GaussianKernel, PLearn::GeodesicDistanceKernel, PLearn::LLEKernel, PLearn::PolynomialKernel, PLearn::PrecomputedKernel, PLearn::ReconstructionWeightsKernel, and PLearn::SourceKernel.
Definition at line 190 of file Kernel.cc.
References data, data_inputsize, evaluate(), evaluate_xi, PLearn::VMat::getSubRow(), lock_xi, PLearn::TVec< T >::resize(), and x.
Referenced by evaluate_i_x_again(), and evaluate_x_i().

real PLearn::Kernel::evaluate_i_x_again ( int i,

const Vec & x,

real squared_norm_of_x = -1,

bool first_time = false

) const [virtual]

Return evaluate(data(i),x), where x is the same as in the precedent call to this same function (except if 'first_time' is true).
This can be used to speed up successive computations of K(x_i, x) (default version just calls evaluate_i_x).
Reimplemented in PLearn::AdditiveNormalizationKernel, PLearn::DivisiveNormalizationKernel, PLearn::GeodesicDistanceKernel, and PLearn::LLEKernel.
Definition at line 232 of file Kernel.cc.
References evaluate_i_x(), and x.
Referenced by evaluate_all_i_x().

real PLearn::Kernel::evaluate_x_i ( const Vec & x,

int i,

real squared_norm_of_x = -1

) const [virtual]

returns evaluate(x,data(i)) [default version calls evaluate_i_x if kernel is_symmetric]

Reimplemented in PLearn::AdditiveNormalizationKernel, PLearn::DivisiveNormalizationKernel, PLearn::DotProductKernel, PLearn::GaussianKernel, PLearn::PolynomialKernel, PLearn::PrecomputedKernel, PLearn::ReconstructionWeightsKernel, and PLearn::SourceKernel.
Definition at line 209 of file Kernel.cc.
References data, data_inputsize, evaluate(), evaluate_i_x(), evaluate_xi, PLearn::VMat::getSubRow(), is_symmetric, lock_xi, PLearn::TVec< T >::resize(), and x.
Referenced by evaluate_x_i_again().

real PLearn::Kernel::evaluate_x_i_again ( const Vec & x,

int i,

real squared_norm_of_x = -1,

bool first_time = false

) const [virtual]

Reimplemented in PLearn::AdditiveNormalizationKernel, PLearn::DivisiveNormalizationKernel, and PLearn::ReconstructionWeightsKernel.
Definition at line 239 of file Kernel.cc.
References evaluate_x_i(), and x.
Referenced by evaluate_all_x_i().

VMat PLearn::Kernel::getData ( ) [inline]

Return the data matrix set for this kernel.

Definition at line 165 of file Kernel.h.
References data.

Vec PLearn::Kernel::getParameters ( ) const [virtual]

default version returns an empty Vec

Reimplemented in PLearn::SourceKernel.
Definition at line 346 of file Kernel.cc.
References PLearn::Vec.

bool PLearn::Kernel::hasData ( )

Return true iif there is a data matrix set for this kernel.

Definition at line 352 of file Kernel.cc.
References data.

bool PLearn::Kernel::isInData ( const Vec & x,

int * i = 0

) const

Return true iff the point x is in the kernel dataset.
If provided, i will be filled with the index of the point if it is in the dataset, and with -1 otherwise.
Definition at line 268 of file Kernel.cc.
References data, and x.

void PLearn::Kernel::makeDeepCopyFromShallowCopy ( CopiesMap & copies ) [virtual]

Does the necessary operations to transform a shallow copy (this) into a deep copy by deep-copying all the members that need to be. Typical implementation:
void CLASS_OF_THIS::makeDeepCopyFromShallowCopy(CopiesMap& copies) { SUPERCLASS_OF_THIS::makeDeepCopyFromShallowCopy(copies); member_ptr = member_ptr->deepCopy(copies); member_smartptr = member_smartptr->deepCopy(copies); member_mat.makeDeepCopyFromShallowCopy(copies); member_vec.makeDeepCopyFromShallowCopy(copies); ... }
Reimplemented from PLearn::Object.
Definition at line 116 of file Kernel.cc.
References PLearn::CopiesMap, data, PLearn::deepCopyField(), evaluate_xi, evaluate_xj, k_xi_x, and specify_dataset.

virtual int PLearn::Kernel::nExamples ( ) [inline, virtual]

Return n_examples.

Definition at line 114 of file Kernel.h.
References n_examples.

real PLearn::Kernel::operator() ( const Vec & x1,

const Vec & x2

) const [inline]

Definition at line 158 of file Kernel.h.

PLearn::Kernel::PLEARN_DECLARE_ABSTRACT_OBJECT ( Kernel )

void PLearn::Kernel::setDataForKernelMatrix ( VMat the_data ) [virtual]

** Subclasses may overload these methods to provide efficient kernel matrix access **
This method sets the data VMat that will be used to define the kernel matrix. It may precompute values from this that may later accelerate the evaluation of a kernel matrix element
Reimplemented in PLearn::AdditiveNormalizationKernel, PLearn::DistanceKernel, PLearn::DivisiveNormalizationKernel, PLearn::GaussianKernel, PLearn::GeodesicDistanceKernel, PLearn::LLEKernel, PLearn::PrecomputedKernel, PLearn::ReconstructionWeightsKernel, and PLearn::SourceKernel.
Definition at line 129 of file Kernel.cc.
References data, data_inputsize, PLearn::VMat::length(), n_examples, and PLearn::VMat::width().
Referenced by build_().

void PLearn::Kernel::setParameters ( Vec paramvec ) [virtual]

default version produces an error

Reimplemented in PLearn::CompactVMatrixGaussianKernel, PLearn::GaussianKernel, and PLearn::SourceKernel.
Definition at line 340 of file Kernel.cc.
References PLERROR.

real PLearn::Kernel::test ( VMat d,

real threshold,

real sameness_below_threshold,

real sameness_above_threshold

) const

Definition at line 467 of file Kernel.cc.
References evaluate(), PLearn::VMat::length(), PLearn::TVec< T >::subVec(), and PLearn::VMat::width().

Member Data Documentation

VMat PLearn::Kernel::data [protected]

data for kernel matrix, which will be used for calls to evaluate_i_j and the like

Definition at line 68 of file Kernel.h.
Referenced by addDataForKernelMatrix(), computeGramMatrix(), evaluate_i_j(), evaluate_i_x(), evaluate_x_i(), getData(), hasData(), isInData(), makeDeepCopyFromShallowCopy(), and setDataForKernelMatrix().

int PLearn::Kernel::data_inputsize [protected]

Definition at line 69 of file Kernel.h.
Referenced by dataInputsize(), evaluate_i_j(), evaluate_i_x(), evaluate_x_i(), and setDataForKernelMatrix().

Vec PLearn::Kernel::evaluate_xi [mutable, private]

Used to store data to save memory allocation.

Definition at line 61 of file Kernel.h.
Referenced by evaluate_i_j(), evaluate_i_x(), evaluate_x_i(), and makeDeepCopyFromShallowCopy().

Vec PLearn::Kernel::evaluate_xj [mutable, private]

Used to store data to save memory allocation.

Definition at line 61 of file Kernel.h.
Referenced by evaluate_i_j(), and makeDeepCopyFromShallowCopy().

bool PLearn::Kernel::is_symmetric

Build options.

Definition at line 77 of file Kernel.h.
Referenced by apply(), and evaluate_x_i().

Vec PLearn::Kernel::k_xi_x [mutable, private]

Used to store data to save memory allocation.

Definition at line 61 of file Kernel.h.
Referenced by computeNearestNeighbors(), and makeDeepCopyFromShallowCopy().

bool PLearn::Kernel::lock_k_xi_x [mutable, private]

Used to make sure we do not accidentally overwrite some global data.

Definition at line 64 of file Kernel.h.
Referenced by computeNearestNeighbors().

bool PLearn::Kernel::lock_xi [mutable, private]

Used to make sure we do not accidentally overwrite some global data.

Definition at line 64 of file Kernel.h.
Referenced by evaluate_i_j(), evaluate_i_x(), and evaluate_x_i().

bool PLearn::Kernel::lock_xj [mutable, private]

Used to make sure we do not accidentally overwrite some global data.

Definition at line 64 of file Kernel.h.
Referenced by evaluate_i_j().