Implements Divergence (distance) based on normal (gaussian) model to serve as feature selection criterion. More...

#include <criterion_normal_divergence.hpp>

Inheritance diagram for FST::Criterion_Normal_Divergence< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR >:

Public Types
typedef Criterion_Normal< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR >	parent
	base class: the normal-model template-method skeleton
typedef Clonable_Impl< Criterion_Normal_Divergence, parent >	parent_impl
	implements clone(); sharing/stateless_clone throw in Criterion
typedef std::shared_ptr< DATAACCESSOR >	PDataAccessor
	shared pointer to the data accessor the model is learned from
typedef std::shared_ptr< SUBSET >	PSubset
	shared pointer to the feature subset being evaluated
Public Types inherited from FST::Criterion_Normal< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR >
typedef std::shared_ptr< DATAACCESSOR >	PDataAccessor
	shared pointer to the data accessor the model is learned from
typedef std::shared_ptr< SUBSET >	PSubset
	shared pointer to the feature subset being evaluated
Public Types inherited from FST::Criterion_Filter< RETURNTYPE, SUBSET >
typedef std::shared_ptr< SUBSET >	PSubset
	shared pointer to the feature subset being evaluated
Public Types inherited from FST::Criterion< RETURNTYPE, SUBSET >
typedef std::shared_ptr< SUBSET >	PSubset
	shared pointer to the feature subset being evaluated

Protected Member Functions
virtual const char *	criterion_name () const override
	class name, used in output and error messages
virtual void	allocate_buffers () override
	(re)allocate criterion-specific work buffers for get_n() features (use the alloc_* helpers)
virtual void	update_derived_model () override
virtual bool	evaluate_narrowed (RETURNTYPE &result, const PSubset sub) override
	narrow remaining buffers to sub, redim work buffers to get_d(), compute the criterion value. On entry _model and _meandif have ALREADY been narrowed to `sub` by evaluate(), so the implementation sees only the d selected features; get_d() is that d, and _meandif->at(i) addresses the narrowed positions. `sub` is non-empty (evaluate() rejects d==0 before the call).
Protected Member Functions inherited from FST::Criterion_Normal< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR >
	Criterion_Normal (const Criterion_Normal &cn)
	Copy-constructor; deep-copies _model and _meandif (subclasses copy their own buffers separately).
void	alloc_vector (std::unique_ptr< Indexed_Vector< DATATYPE, DIMTYPE, SUBSET > > &v)
	lazy (re)allocation of a work vector for get_n() features, for use from allocate_buffers()
template<typename MATRIXVALUETYPE>
void	alloc_matrix (std::unique_ptr< Indexed_Matrix< MATRIXVALUETYPE, DIMTYPE, SUBSET > > &m, const bool LUstorage=false)
	lazy (re)allocation of a work matrix for get_n() features; LUstorage as required by Indexed_Matrix::LUdecompose() temp storage
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)

Private Member Functions
	Criterion_Normal_Divergence (const Criterion_Normal_Divergence &cnd)
	Copy-constructor; deep-copies the four criterion-specific work buffers (base _model/_meandif copied by parent_impl).

Private Attributes
friend	parent_impl
std::unique_ptr< Indexed_Vector< DATATYPE, DIMTYPE, SUBSET > >	_diag
	per-feature diagonal of cov1^-1cov2 + cov2^-1cov1, summed into the trace term of the divergence
std::unique_ptr< Indexed_Matrix< REALTYPE, DIMTYPE, SUBSET > >	_invbuf1
	inverse of the narrowed class-1 covariance
std::unique_ptr< Indexed_Matrix< REALTYPE, DIMTYPE, SUBSET > >	_invbuf2
	inverse of the narrowed class-2 covariance
std::unique_ptr< Indexed_Matrix< REALTYPE, DIMTYPE, SUBSET > >	_LUtemp
	scratch LU-decomposition storage, reused for each matrix inversion

Additional Inherited Members
Public Member Functions inherited from FST::Clonable_Impl< Criterion_Normal_Divergence< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR >, Criterion_Normal< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR > >
Criterion_Normal< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR > *	clone () const override
	dispatches to the DEEP_KIND mechanism (default CLONE_DEEP: Derived's copy-constructor)
Criterion_Normal< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR > *	sharing_clone () const override
	dispatches to the SHARING_KIND mechanism (default CLONE_INHERIT: defers to Base, which throws by family convention)
Criterion_Normal< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, 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::Criterion_Normal< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR >
virtual bool	initialize (PDataAccessor da)
	template method: learn model, compute _meandif, then allocate_buffers() + update_derived_model().
virtual bool	evaluate (RETURNTYPE &result, const PSubset sub) override
	template method: narrow model and _meandif to sub, then evaluate_narrowed()
virtual bool	is_monotonic () const override
DIMTYPE	get_n () const
	the full (raw, unnarrowed) feature count the model was learned for
DIMTYPE	get_d () const
	the currently active (narrowed) feature count, see evaluate()
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::Criterion< RETURNTYPE, SUBSET >
Criterion *	sharing_clone () const override
Criterion *	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 Attributes inherited from FST::Criterion_Normal< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR >
std::unique_ptr< Model_Normal< DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR > >	_model
	the learned per-class normal (mean/covariance) model, narrowed in evaluate()
std::unique_ptr< Indexed_Vector< DATATYPE, DIMTYPE, SUBSET > >	_meandif
	mean[0]-mean[1], shared by all two-class normal criteria

Detailed Description

template<class RETURNTYPE, typename DATATYPE, typename REALTYPE, typename IDXTYPE, typename DIMTYPE, class SUBSET, class DATAACCESSOR>
class FST::Criterion_Normal_Divergence< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR >

Implements Divergence (distance) based on normal (gaussian) model to serve as feature selection criterion.

The symmetric Kullback divergence between the two classes modelled as Gaussians (mu0,S0) and (mu1,S1) restricted to the d selected features, with m = mu0-mu1:

J = 1/2 * m^T (S0^-1 + S1^-1) m  +  1/2 * ( tr(S0^-1 S1 + S1^-1 S0) - 2d )

The first term measures mean separation in the metric of both inverse covariances, the second the dissimilarity of the covariances themselves. The -2d offset makes the second term vanish for equal covariances: S0 == S1 gives S0^-1 S1 = S1^-1 S0 = I, whose two traces add up to exactly 2d. Higher is better, and the criterion is non-negative.

Note: Defined for two-class problems only

Warning: Divergence is cardinality-monotonic in theory, so is_monotonic() reports true and Branch & Bound accepts it, but the two matrix inversions per evaluation make it numerically fragile: on ill-conditioned data the computed values can breach monotonicity and Branch & Bound may then miss the optimum. Prefer Criterion_Normal_Bhattacharyya (one inversion) whenever an optimal search is used.

Note: Requires non-singular per-class covariances on the evaluated subset - a subset of constant, duplicate or linearly dependent features, or one larger than a class's training sample count, makes the criterion undefined.

Member Function Documentation

◆ allocate_buffers()

template<class RETURNTYPE, typename DATATYPE, typename REALTYPE, typename IDXTYPE, typename DIMTYPE, class SUBSET, class DATAACCESSOR>

virtual void FST::Criterion_Normal_Divergence< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR >::allocate_buffers ( )

inlineoverrideprotectedvirtual

(re)allocate criterion-specific work buffers for get_n() features (use the alloc_* helpers)

Implements FST::Criterion_Normal< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR >.

◆ criterion_name()

template<class RETURNTYPE, typename DATATYPE, typename REALTYPE, typename IDXTYPE, typename DIMTYPE, class SUBSET, class DATAACCESSOR>

virtual const char * FST::Criterion_Normal_Divergence< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR >::criterion_name ( ) const

inlineoverrideprotectedvirtual

class name, used in output and error messages

Implements FST::Criterion_Normal< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR >.

◆ evaluate_narrowed()

template<class RETURNTYPE, typename DATATYPE, typename REALTYPE, typename IDXTYPE, typename DIMTYPE, class SUBSET, class DATAACCESSOR>

bool FST::Criterion_Normal_Divergence< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR >::evaluate_narrowed	(	RETURNTYPE &	result,
		const PSubset	sub )

overrideprotectedvirtual

narrow remaining buffers to sub, redim work buffers to get_d(), compute the criterion value. On entry _model and _meandif have ALREADY been narrowed to sub by evaluate(), so the implementation sees only the d selected features; get_d() is that d, and _meandif->at(i) addresses the narrowed positions. sub is non-empty (evaluate() rejects d==0 before the call).

Implements FST::Criterion_Normal< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR >.

◆ update_derived_model()

template<class RETURNTYPE, typename DATATYPE, typename REALTYPE, typename IDXTYPE, typename DIMTYPE, class SUBSET, class DATAACCESSOR>

virtual void FST::Criterion_Normal_Divergence< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR >::update_derived_model ( )

inlineoverrideprotectedvirtual

precompute criterion-specific derivations of the freshly learned model (_meandif is already computed)

Implements FST::Criterion_Normal< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR >.

Member Data Documentation

◆ parent_impl

template<class RETURNTYPE, typename DATATYPE, typename REALTYPE, typename IDXTYPE, typename DIMTYPE, class SUBSET, class DATAACCESSOR>

friend FST::Criterion_Normal_Divergence< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR >::parent_impl

private

grants Clonable_Impl access to the copy-constructor

The documentation for this class was generated from the following file:

/Users/psms/dev/devtest1/_src_criteria/criterion_normal_divergence.hpp

Public Types

Protected Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ allocate_buffers()

◆ criterion_name()

◆ evaluate_narrowed()

◆ update_derived_model()

Member Data Documentation

◆ parent_impl