Collects multiple results. Enables eventual selection of alternative solution based on secondary criterion. More...

#include <result_tracker_regularizer.hpp>

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

Public Types
typedef Result_Tracker_Dupless< RETURNTYPE, IDXTYPE, DIMTYPE, SUBSET >	parent
	base class alias
typedef Clonable_Impl< Result_Tracker_Regularizer, parent, CLONE_INHERIT, CLONE_INHERIT, CLONE_DEEP >	parent_impl
	implements stateless_clone() via Clonable_Impl; clone()/sharing_clone() defer to Result_Tracker's throwing defaults (see CLONE_INHERIT)
typedef parent::ResultRec	ResultRec
	one tracked [value,subset] result record, as defined by Result_Tracker
typedef ResultRec *	PResultRec
	raw pointer to a ResultRec
typedef std::shared_ptr< SUBSET >	PSubset
	shared pointer to a feature subset
typedef std::shared_ptr< CRITERION >	PCriterion
	shared pointer to a criterion (the secondary criterion used to re-rank tracked results)
Public Types inherited from FST::Result_Tracker_Dupless< RETURNTYPE, IDXTYPE, DIMTYPE, SUBSET >
typedef Result_Tracker< RETURNTYPE, SUBSET >	parent
	the abstract Result_Tracker interface this class implements
typedef Clonable_Impl< Result_Tracker_Dupless, parent, CLONE_INHERIT, CLONE_INHERIT, CLONE_DEEP >	parent_impl
	implements stateless_clone() via the copy-constructor (CLONE_DEEP); clone()/sharing_clone() are inherited from Result_Tracker, which throws for both
typedef parent::ResultRec	ResultRec
	see Result_Tracker::ResultRec
typedef parent::PResultRec	PResultRec
	see Result_Tracker::PResultRec
typedef std::shared_ptr< SUBSET >	PSubset
typedef std::list< ResultRec >::const_iterator	CONSTRESULTSITER
	read-only iterator over results, for use by subclasses/friends inspecting the collected results
typedef std::list< ResultRec >::iterator	RESULTSITER
	mutable iterator over results, as returned by begin()/end()
Public Types inherited from FST::Result_Tracker< RETURNTYPE, SUBSET >
typedef std::shared_ptr< SUBSET >	PSubset
	shared pointer to a tracked feature subset
typedef ResultRec *	PResultRec
	raw pointer to a ResultRec, as used by get_first()/get_next() iteration

Public Member Functions
	Result_Tracker_Regularizer (const IDXTYPE capacity_limit=0)
	`capacity_limit` forwarded to Result_Tracker_Dupless (0 = unlimited)
	Result_Tracker_Regularizer (const Result_Tracker_Regularizer &rtr)
	the copy starts with a fresh (non-searching) equivalence-group cursor; _crit/_prevmax/_iter are not copied
virtual bool	optimize_within_margin (const RETURNTYPE margin, RETURNTYPE &result1, RETURNTYPE &result2, PSubset &sub, const PCriterion crit)
	Re-ranks the tracked results within `margin` of the best tracked (primary) value by a secondary `crit`, returning the one `crit` ranks highest.
virtual bool	optimize_within_first_equivalence_group (RETURNTYPE &result1, RETURNTYPE &result2, PSubset &sub, const PCriterion crit)
	Starts a group-by-group scan: returns the subset of the first equivalence group (the tracked subsets sharing the highest primary criterion value) that `crit` ranks highest.
virtual bool	optimize_within_next_equivalence_group (RETURNTYPE &result1, RETURNTYPE &result2, PSubset &sub)
	Continues the scan started by optimize_within_first_equivalence_group(): returns the best subset of the next equivalence group (the next lower primary criterion value), ranked by the criterion given there.
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< Result_Tracker_Regularizer< RETURNTYPE, IDXTYPE, DIMTYPE, SUBSET, CRITERION >, Result_Tracker_Dupless< RETURNTYPE, IDXTYPE, DIMTYPE, SUBSET >, CLONE_INHERIT, CLONE_INHERIT, CLONE_DEEP >
Result_Tracker_Dupless< RETURNTYPE, IDXTYPE, DIMTYPE, SUBSET > *	clone () const override
	dispatches to the DEEP_KIND mechanism (default CLONE_DEEP: Derived's copy-constructor)
Result_Tracker_Dupless< RETURNTYPE, IDXTYPE, DIMTYPE, SUBSET > *	sharing_clone () const override
	dispatches to the SHARING_KIND mechanism (default CLONE_INHERIT: defers to Base, which throws by family convention)
Result_Tracker_Dupless< RETURNTYPE, IDXTYPE, DIMTYPE, SUBSET > *	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::Result_Tracker_Dupless< RETURNTYPE, IDXTYPE, DIMTYPE, SUBSET >
	Result_Tracker_Dupless (const IDXTYPE capacity_limit=0)
	Result_Tracker_Dupless (const Result_Tracker_Dupless &rtd)
	copies the configuration (margin, cardinality restriction, capacity limit) only; the `results` list is NOT copied (starts empty) – this constructor backs stateless_clone() (CLONE_DEEP), which by contract does not replicate exact object state
virtual bool	add (const RETURNTYPE value, const PSubset sub) override
	Offers one (value, subset) result for inclusion; `sub` is copied, the caller keeps ownership of its own object.
virtual void	clear () override
	discards all recorded results
virtual std::size_t	size () const override
	number of results currently held (std::size_t rather than 'long': on LLP64 platforms 'long' is 32 bits and would narrow the container's own size type)
virtual std::size_t	size (const RETURNTYPE margin) const
	number of currently held results whose value is within `margin` of the best (first, highest-value) held result
virtual bool	get_first (PResultRec &r) override
	starts iteration at the best held result; false if nothing is held. The returned pointer refers into this tracker's own storage and is invalidated by add(), join() and clear()
virtual bool	get_next (PResultRec &r) override
	hands out the next result in descending-value order; false when the iteration is exhausted. There is one shared cursor per tracker, so nested or concurrent iterations of the same tracker interfere
virtual void	join (Result_Tracker< RETURNTYPE, SUBSET > &src) override
	merges the results held by `src` into this tracker, keeping the ordering and skipping duplicates exactly as add() does, then re-applies the capacity limit and the margin to the merged list. Consumes `src's` iteration cursor; `src` itself is left unchanged
void	set_inclusion_margin (const RETURNTYPE margin=0)
	restrict adding to only subsets with criterion value within given distance (margin) from best known
void	set_inclusion_cardinality_restriction (const DIMTYPE d)
	for d>0 restricts adding only to subsets of size d, for d=0 subset size restriction is removed
RESULTSITER	begin ()
	iterator to the best (first) held result
RESULTSITER	end ()
	iterator past the last held result
Public Member Functions inherited from FST::Result_Tracker< RETURNTYPE, SUBSET >
	Result_Tracker (const Result_Tracker &rt)
	copies the output-detail setting only – concrete trackers copy their own collected results separately
Result_Tracker *	clone () const override
Result_Tracker *	sharing_clone () const override
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
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

Private Member Functions
bool	optimize_within_equivalence_group (RETURNTYPE &result1, RETURNTYPE &result2, PSubset &sub)
	building block for optimize_within_*_equivalence_group

Private Attributes
PCriterion	_crit
	the secondary criterion set by optimize_within_first_equivalence_group(), reused by subsequent optimize_within_next_equivalence_group() calls
RETURNTYPE	_prevmax
	the primary value of the equivalence group currently being scanned; helper of optimize_within_equivalence_group()
parent::CONSTRESULTSITER	_iter
	cursor into the tracked results list, carried across optimize_within_*_equivalence_group() calls so scanning resumes where the previous call left off; adding to the tracker during a scan may invalidate it
bool	_searching
	true while an equivalence-group scan is in progress, i.e. optimize_within_next_equivalence_group() may still find further groups

Additional Inherited Members
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 inherited from FST::Result_Tracker_Dupless< RETURNTYPE, IDXTYPE, DIMTYPE, SUBSET >
std::list< ResultRec >	results
	held results, sorted descending by value (ties broken toward the smaller subset); see add() for the exact insertion/dedup/trim rule
RETURNTYPE	_margin
	set via set_inclusion_margin(); 0 = no margin restriction
DIMTYPE	_restrict_to_d
	set via set_inclusion_cardinality_restriction(); 0 = no subset-size restriction
const IDXTYPE	_capacity_limit
	set by the constructor; 0 = unlimited
Protected Attributes inherited from FST::Result_Tracker< RETURNTYPE, SUBSET >
OutputDetail	_detail
	the output detail level set via set_output_detail(); read by output_normal()/output_detailed()

Detailed Description

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

Collects multiple results. Enables eventual selection of alternative solution based on secondary criterion.

Enables selecting a different subset than the one yielded by the search procedure, e.g., with the aim to reduce overfitting or to take into account known feature acquisition cost.

The idea is to consider all known subsets with criterion value close enough to the maximum as effectively equal - then another criterion is used to choose among those alternative solutions. This technique can improve generalization/robustness and reduce overfitting, as well as open up other possibilities, like preferring a subset being almost equal to the primarily selected, but with considerably lower feature value acquisition cost, etc. For details see paper "Somol, Grim, Pudil: The Problem of Fragile Feature Subset Preference in Feature Selection Methods and A Proposal of Algorithmic Workaround. In Proc. ICPR 2010. IEEE Computer Society, 2010".

Examples: demo52t.cpp.

Member Function Documentation

◆ optimize_within_first_equivalence_group()

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

bool FST::Result_Tracker_Regularizer< RETURNTYPE, IDXTYPE, DIMTYPE, SUBSET, CRITERION >::optimize_within_first_equivalence_group	(	RETURNTYPE &	result1,
		RETURNTYPE &	result2,
		PSubset &	sub,
		const PCriterion	crit )

virtual

Starts a group-by-group scan: returns the subset of the first equivalence group (the tracked subsets sharing the highest primary criterion value) that crit ranks highest.

crit must be non-null and already initialize()d, sub must be non-null. Ties in crit are broken in favor of the smaller cardinality. crit is remembered for the subsequent optimize_within_next_equivalence_group() calls.

Returns: false if the tracker holds no result, or if a crit evaluation failed; the scan is then not in progress and the next-group call returns false too.

◆ optimize_within_margin()

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

bool FST::Result_Tracker_Regularizer< RETURNTYPE, IDXTYPE, DIMTYPE, SUBSET, CRITERION >::optimize_within_margin	(	const RETURNTYPE	margin,
		RETURNTYPE &	result1,
		RETURNTYPE &	result2,
		PSubset &	sub,
		const PCriterion	crit )

virtual

Re-ranks the tracked results within margin of the best tracked (primary) value by a secondary crit, returning the one crit ranks highest.

Assumes the tracked list is sorted with the best (primary) value first, as Result_Tracker_Dupless maintains it, and stops scanning once a tracked value drops below best_primary_value - margin. Among the subsets within the margin, picks the one with the highest crit value, breaking ties in favor of the smaller cardinality.

Parameters

margin	non-negative margin (0 restricts the scan to the primary-best value only).
result1	receives the primary (originally tracked) value of the returned subset.
result2	receives the secondary `crit's` value of the returned subset.
sub	receives the chosen subset.
crit	the secondary criterion used to re-rank candidates within margin; must be non-null and already initialize()d.

Returns: false if the tracker is empty or a crit evaluation fails.

◆ optimize_within_next_equivalence_group()

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

bool FST::Result_Tracker_Regularizer< RETURNTYPE, IDXTYPE, DIMTYPE, SUBSET, CRITERION >::optimize_within_next_equivalence_group	(	RETURNTYPE &	result1,
		RETURNTYPE &	result2,
		PSubset &	sub )

virtual

Continues the scan started by optimize_within_first_equivalence_group(): returns the best subset of the next equivalence group (the next lower primary criterion value), ranked by the criterion given there.

Returns: false if no scan is in progress (the first-group call was never made, failed, or the previous call consumed the last group), or if a criterion evaluation failed.

Warning: The scan holds a cursor into the tracked list. Do not add() to the tracker (nor join() into it) between the calls: trimming by the capacity limit or the margin can erase the record the cursor points to.

◆ print()

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

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

inlineoverridevirtual

writes a human-readable identification of the object; base default writes nothing

Reimplemented from FST::Result_Tracker_Dupless< RETURNTYPE, IDXTYPE, DIMTYPE, SUBSET >.

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

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

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ optimize_within_first_equivalence_group()

◆ optimize_within_margin()

◆ optimize_within_next_equivalence_group()

◆ print()