Implements experimental regressor that produces weighted average of the predicted variable over neighbours, weighted by distance. More...

#include <regressor_weighted_neighbours.hpp>

Inheritance diagram for FST::Regressor_Weighted_Neighbours< RETURNTYPE, DATATYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR, DISTANCE >:

Public Types
typedef Regressor< RETURNTYPE, DIMTYPE, SUBSET, DATAACCESSOR >	parent
	the immediate abstract base
typedef Clonable_Impl< Regressor_Weighted_Neighbours, parent >	parent_impl
	implements clone(); sharing/stateless_clone throw in Regressor
typedef std::shared_ptr< DATAACCESSOR >	PDataAccessor
	shared pointer to the data accessor supplying train/test blocks
typedef std::shared_ptr< SUBSET >	PSubset
	shared pointer to the feature subset being trained/evaluated on
typedef DATAACCESSOR::PPattern	PPattern
	one data sample as exposed by DATAACCESSOR (a raw pointer to its feature vector)
Public Types inherited from FST::Regressor< RETURNTYPE, DIMTYPE, SUBSET, DATAACCESSOR >
typedef std::shared_ptr< DATAACCESSOR >	PDataAccessor
	shared pointer to the data accessor supplying train/test blocks
typedef std::shared_ptr< SUBSET > const	PSubset
	shared pointer to the (fixed, non-reassignable) feature subset being evaluated
typedef DATAACCESSOR::PPattern	PPattern
	one data sample as exposed by DATAACCESSOR (a raw pointer to its feature vector)

Public Member Functions
void	set_kernel_multiplier (const RETURNTYPE m)
	scales the Gaussian kernel width used by get_weight(); width = distance stddev * `m` (must be > 0)
RETURNTYPE	get_kernel_size () const
	the effective kernel width (training-set pairwise-distance stddev times the multiplier set by set_kernel_multiplier())
void	set_dependent_index (const IDXTYPE depvaridx)
	data column to predict; the (IDXTYPE)-1 default/sentinel selects the class label instead ("regression simulating classification")
virtual bool	predict (RETURNTYPE &depvar, const PPattern &pattern) override
	Predicts the dependent variable of one pattern into `depvar` (see the dependent-variable convention in the class documentation). Returns false when no prediction can be made at all - the regressor has not been trained, or the implementation hit an unrecoverable condition; false aborts the enclosing test loop.
virtual bool	train (const PDataAccessor da, const PSubset sub) override
virtual bool	test (RETURNTYPE &result, const PDataAccessor da) override
virtual bool	test_metric (RETURNTYPE &result, const PDataAccessor da, const Metric_Spec< RETURNTYPE > &spec) override
virtual std::ostream &	print (std::ostream &os) const override
	writes a human-readable identification of the object; base default writes nothing
Public Member Functions inherited from FST::Clonable_Impl< Regressor_Weighted_Neighbours< RETURNTYPE, DATATYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR, DISTANCE >, Regressor< RETURNTYPE, DIMTYPE, SUBSET, DATAACCESSOR > >
Regressor< RETURNTYPE, DIMTYPE, SUBSET, DATAACCESSOR > *	clone () const override
	dispatches to the DEEP_KIND mechanism (default CLONE_DEEP: Derived's copy-constructor)
Regressor< RETURNTYPE, DIMTYPE, SUBSET, DATAACCESSOR > *	sharing_clone () const override
	dispatches to the SHARING_KIND mechanism (default CLONE_INHERIT: defers to Base, which throws by family convention)
Regressor< RETURNTYPE, DIMTYPE, SUBSET, DATAACCESSOR > *	stateless_clone () const override
	dispatches to the STATELESS_KIND mechanism (default CLONE_INHERIT: defers to Base, which throws by family convention)
Public Member Functions inherited from FST::Regressor< RETURNTYPE, DIMTYPE, SUBSET, DATAACCESSOR >
virtual bool	train (const PDataAccessor da, const PSubset sub)=0
Regressor *	sharing_clone () const override
Regressor *	stateless_clone () const override
Public Member Functions inherited from FST::Clonable
bool	is_clone () const
bool	is_sharing () const
	true if this instance is a sharing_clone() result (referencing, not owning, the source's structures)
bool	is_sharing_clone () const
	true if this instance is BOTH a clone and sharing – i.e. specifically a sharing_clone() result, not a clone()/stateless_clone() one

Protected Member Functions
virtual RETURNTYPE	get_weight (RETURNTYPE dist)
	the (unnormalized) Gaussian kernel weight for a neighbour at distance `dist`, using get_kernel_size() as the kernel width
Protected Member Functions inherited from FST::Clonable
void	set_cloned (const bool cloned=true)
	marks/unmarks this instance as a clone; call from clone()/stateless_clone() overrides (Clonable_Impl does this automatically)
void	set_sharing (const bool sharing=true)
	marks/unmarks this instance as sharing (see is_sharing())
void	set_sharing_cloned (const bool cloned=true, const bool sharing=true)
	sets both flags at once; call from sharing_clone() overrides (Clonable_Impl does this automatically)

Protected Attributes
DIMTYPE	_dep_var_idx
	dependent-variable data column, or the (IDXTYPE)-1 sentinel meaning "use the class label"; set by set_dependent_index()
std::unique_ptr< DISTANCE >	_distance
	distance metric narrowed to the trained subspace, used by predict()/train() to weigh training neighbours
RETURNTYPE	_dist_mean
	mean of all pairwise training-set distances (in the trained subspace), computed by train()
RETURNTYPE	_dist_stddev
	standard deviation of all pairwise training-set distances, computed by train(); the kernel width before set_kernel_multiplier() scaling
RETURNTYPE	_kernel_multiplier
	scales _dist_stddev into the kernel width returned by get_kernel_size(); set by set_kernel_multiplier(), default 1
PDataAccessor	_da_train
	training data accessor cached by train() (RWN has no real training step); read back by predict()/test() to enumerate training neighbours

Private Member Functions
	Regressor_Weighted_Neighbours (const Regressor_Weighted_Neighbours &cknn)
	copy-constructor (clones _distance if allocated; scalar members are value-copied)

Private Attributes
friend	parent_impl
	grants Clonable_Impl access to the copy-constructor

Detailed Description

template<class RETURNTYPE, typename DATATYPE, typename IDXTYPE, typename DIMTYPE, class SUBSET, class DATAACCESSOR, class DISTANCE>
class FST::Regressor_Weighted_Neighbours< RETURNTYPE, DATATYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR, DISTANCE >

Implements experimental regressor that produces weighted average of the predicted variable over neighbours, weighted by distance.

A prediction is the Gaussian-kernel weighted average of the dependent variable over ALL training patterns (not the k nearest ones): weight(dist) falls off with the distance in the selected subspace, the kernel width being the standard deviation of the training set's pairwise distances times the multiplier set by set_kernel_multiplier().

EXPERIMENTAL means: the method is offered for exploration, not as a tuned or validated regressor. Specifically – the kernel width is derived from the data rather than cross-validated; every training pattern contributes to every prediction, so there is no locality parameter to tune; and no distance normalization across features is applied beyond whatever the DISTANCE template argument and the data scaler do.

Note: The DEPENDENT VARIABLE is by default the CLASS LABEL, not a data column: with the default (IDXTYPE)-1 sentinel the class index of each training pattern is the value being averaged ("regression simulating classification"), and test() then counts a prediction within 0.5 of the true label as correct, so its result reads like an accuracy. set_dependent_index() switches to a genuine data column, in which case train() excludes that column from the distance computation and test() returns the negated mean absolute error (FST4 always maximizes).

Warning: COST: train() computes ALL pairs of training-set distances, i.e. O(N^2) distance evaluations in the subset dimensionality, and keeps one value per pair in memory. predict() costs O(N) per pattern, so one test() pass over M test patterns costs O(M*N). This regressor is meant for small datasets.

Note: Degenerate data (all training patterns identical, or a kernel width of zero) leads to divisions by zero that are only caught by assertions – see train() and predict().