Abstract base of the feature-ranking methods: scores features one by one, then turns the ranking into a feature subset. More...

#include <search_ranking.hpp>

Inheritance diagram for FST::Search_Ranking< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >:

Classes
struct	OneFeature
	Structure to hold [feature,criterion value] pair while ranking features. More...

Public Types
typedef Search< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >	parent
	the abstract Search interface this class implements
typedef std::shared_ptr< CRITERION >	PCriterion
	shared pointer to the criterion the search optimizes
typedef std::shared_ptr< SUBSET >	PSubset
	shared pointer to a feature subset
typedef Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >	EVALUATORENGINE
	the injected candidate-evaluation engine interface driving individual-feature evaluation
typedef std::shared_ptr< EVALUATORENGINE >	PEvaluatorEngine
Public Types inherited from FST::Search< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >
typedef std::shared_ptr< CRITERION >	PCriterion
	shared pointer to the criterion the search optimizes
typedef std::shared_ptr< SUBSET >	PSubset
	shared pointer to a feature subset
typedef std::shared_ptr< Result_Tracker< RETURNTYPE, SUBSET > >	PResultTracker
	shared pointer to the result tracker enabled via enable_result_tracking()
typedef Search_Observer< RETURNTYPE, SUBSET >	OBSERVER
	the observer interface type this search reports through (see Search_Observer)
typedef std::shared_ptr< OBSERVER >	PObserver
	shared pointer to an OBSERVER, as set via set_observer()

Public Member Functions
	Search_Ranking (PEvaluatorEngine engine=PEvaluatorEngine())
virtual bool	evaluate_individuals (const DIMTYPE n, const PCriterion crit, std::ostream &os=std::cout)=0
	ranks all `n` features individually by `crit`, filling `bifs` descending by criterion value (the order within a group of equal values is the concrete method's own convention); called by search() itself, and required before getFirstFeature()/getNextFeature() are used on their own – implemented by the concrete ranking method (e.g. Search_Ranking_BIF)
virtual bool	search (const DIMTYPE target_d, RETURNTYPE &result, const PSubset sub, const PCriterion crit, std::ostream &os=std::cout) override
	ranks the features (evaluate_individuals()) and returns the target_d best-ranked ones, or - for target_d==0 - the best-valued prefix of the ranking; false if the ranking or one of the criterion evaluations failed. `target_d` must be smaller than the full feature count
bool	getFirstFeature (RETURNTYPE &value, DIMTYPE &feature) const
	iterator over `bifs` (the ranking built by evaluate_individuals()), highest-ranked feature first; returns false if `bifs` is empty
bool	getNextFeature (RETURNTYPE &value, DIMTYPE &feature) const
	continues the getFirstFeature() iteration; returns false once the ranking is exhausted. There is one cursor per object: it is protected against concurrent access in threaded builds, but two interleaved iterations of the same object still consume one another's positions
virtual std::ostream &	print (std::ostream &os) const override
	writes a human-readable identification of the search and its configuration; base default writes nothing
Public Member Functions inherited from FST::Search< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >
void	enable_result_tracking (PResultTracker tracker)
	assigns a result tracker to the search process, i.e., enables logging of all evaluated subsets for future reuse (re-evaluation, etc.)
void	disable_result_tracking ()
	detaches any result tracker (result_tracker_active() then returns false)
bool	result_tracker_active () const
	true if a result tracker was assigned via enable_result_tracking() and not since disabled
void	set_output_detail (OutputDetail detail)
	sets the amount of information that is logged to output stream throughout the course of search
OutputDetail	get_output_detail () const
	the currently configured output detail level
bool	output_normal () const
	true unless output detail is SILENT
bool	output_detailed () const
	true only at the DETAILED output level
void	set_observer (PObserver observer)
	redirects search progress reporting away from the default syncout text output to `observer`

Protected Types
typedef std::list< OneFeature >	FEATURELIST
	the individual-feature ranking built by evaluate_individuals(), sorted descending by critval

Protected Attributes
PEvaluatorEngine	_engine
FEATURELIST	bifs
	the individual-feature ranking; empty until evaluate_individuals() is called
Protected Attributes inherited from FST::Search< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >
PResultTracker	_tracker
	the assigned result tracker, or null (see enable_result_tracking()/result_tracker_active())
OutputDetail	_detail
	the output detail level set via set_output_detail(); read by output_normal()/output_detailed()
PObserver	_observer
	the attached progress observer, or null (see set_observer(), report(), report_solution())

Private Attributes
FEATURELIST::const_iterator	get_iter
	iteration cursor for getFirstFeature()/getNextFeature() (single shared cursor; see get_iter_mutex under FST_THREADED)
std::mutex	get_iter_mutex
	protects get_iter for thread-safe iteration

Additional Inherited Members
Protected Member Functions inherited from FST::Search< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >
void	report (std::ostream &os, const msgbuf &m) const
	delivers one pre-formatted progress message: to the observer if attached, otherwise as syncout text to os
void	report_solution (std::ostream &os, const RETURNTYPE value, const SUBSET &sub, const msgbuf &m) const
	like report(), for sites announcing a new (sub-)solution; fires on_solution instead

Detailed Description

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION>
class FST::Search_Ranking< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >

Abstract base of the feature-ranking methods: scores features one by one, then turns the ranking into a feature subset.

A concrete ranking method supplies evaluate_individuals() only, which fills the protected bifs list with one (feature, criterion value) record per feature, ordered by descending value; the order of features of equal value is decided by that method. Everything else - the two search() modes, the feature-list bookkeeping and the iteration over the ranking - lives here.

search() has two modes:

target_d>0: the target_d highest-ranked features form the result, which is evaluated once by the criterion; a result tracker receives that single record.
target_d==0: every prefix of the ranking is evaluated - the best feature alone, the best two features, and so on - and the best-valued prefix is returned; equal values leave the shorter prefix in place. Here every evaluated prefix is reported to the result tracker.

target_d must be smaller than the full feature count. Note that a ranking of individually evaluated features ignores feature interactions by construction; its subsets are generally weaker than those found by the subset search methods, which is the price for the linear number of criterion evaluations.

Member Typedef Documentation

◆ PEvaluatorEngine

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION>

typedef std::shared_ptr<EVALUATORENGINE> FST::Search_Ranking< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::PEvaluatorEngine

shared pointer to an EVALUATORENGINE, as passed to the constructor

Constructor & Destructor Documentation

◆ Search_Ranking()

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION>

FST::Search_Ranking< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::Search_Ranking ( PEvaluatorEngine engine = PEvaluatorEngine() )

inlineexplicit

Parameters

engine evaluation-strategy engine used to evaluate candidate features; defaults to a fresh Candidate_Evaluator_Sequential (inject Candidate_Evaluator_Threaded for a thread-pooled search() dimensionality-optimization phase)

Member Function Documentation

◆ evaluate_individuals()

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION>

virtual bool FST::Search_Ranking< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::evaluate_individuals	(	const DIMTYPE	n,
		const PCriterion	crit,
		std::ostream &	os = std::cout )

pure virtual

ranks all n features individually by crit, filling bifs descending by criterion value (the order within a group of equal values is the concrete method's own convention); called by search() itself, and required before getFirstFeature()/getNextFeature() are used on their own – implemented by the concrete ranking method (e.g. Search_Ranking_BIF)

Implemented in FST::Search_Ranking_BIF< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

◆ print()

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION>

virtual std::ostream & FST::Search_Ranking< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::print ( std::ostream & os ) const

inlineoverridevirtual

writes a human-readable identification of the search and its configuration; base default writes nothing

Reimplemented from FST::Search< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

Reimplemented in FST::Search_Ranking_BIF< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

◆ search()

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION>

bool FST::Search_Ranking< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::search	(	const DIMTYPE	target_d,
		RETURNTYPE &	result,
		const PSubset	sub,
		const PCriterion	crit,
		std::ostream &	os = std::cout )

overridevirtual

ranks the features (evaluate_individuals()) and returns the target_d best-ranked ones, or - for target_d==0 - the best-valued prefix of the ranking; false if the ranking or one of the criterion evaluations failed. target_d must be smaller than the full feature count

Implements FST::Search< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

Member Data Documentation

◆ _engine

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION>

PEvaluatorEngine FST::Search_Ranking< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::_engine

protected

injected evaluation strategy (sequential-inline or thread-pooled)

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

/Users/psms/dev/devtest1/_src_search/search_ranking.hpp

Classes

Public Types

Public Member Functions

Protected Types

Protected Attributes

Private Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ PEvaluatorEngine

Constructor & Destructor Documentation

◆ Search_Ranking()

Member Function Documentation

◆ evaluate_individuals()

◆ print()

◆ search()

Member Data Documentation

◆ _engine