Stores the info on currently selected features, enables generating permutations, etc. More...

#include <subset.hpp>

Classes
class	Feature_Range
	Read-only forward range over feature indices. More...

Public Member Functions
	Subset (const DIMTYPE n)
	Subset (const Subset< BINTYPE, DIMTYPE > &sub)
	Copy constructor: allocates its own marker array and reproduces `sub's` selection, its forward/frozen mode and its selected-feature cursor. The state of a candidate-subset traversal in progress is NOT reproduced, so a copy must not be used to continue one – start a fresh getFirstCandidateSubset() on the copy instead.
void	stateless_copy (Subset< BINTYPE, DIMTYPE > &sub)
	Overwrites this subset's selection state from `sub's` currently selected features (via getFirstFeature()/getNextFeature()). Every feature ends up exactly id_sel or id_desel (frozen features are left frozen); `sub's` own internal iteration/traversal state and forward/frozen mode are NOT copied – only which features are selected. `this` must have get_n_raw() >= `sub's`.
bool	equivalent (const Subset< BINTYPE, DIMTYPE > &sub)
	tests whether sub represents the same subset (ignoring internal state)
void	select (const DIMTYPE i)
	mark i-th feature as selected
void	select (const DIMTYPE _from, const DIMTYPE _to)
	mark features _from,..,_to as selected
void	select_all ()
	mark all (non-frozen) features as selected
void	deselect (const DIMTYPE i)
	mark i-th feature as deselected
void	deselect (const DIMTYPE _from, const DIMTYPE _to)
	mark features _from,..,_to as deselected
void	deselect_all ()
	mark all (non-frozen) features as deselected
DIMTYPE	get_n () const
	the number of features select()/deselect() address: get_n_raw() minus currently frozen features
DIMTYPE	get_d () const
	number of currently selected, non-frozen features (get_d_raw() minus frozen ones)
void	select_raw (const DIMTYPE i)
	mark i-th feature as selected
void	select_raw (Subset< BINTYPE, DIMTYPE > &sub)
	select those features that are selected in sub
void	select_all_raw ()
	mark all features (including frozen ones) as selected
void	deselect_raw (const DIMTYPE i)
	mark i-th feature as deselected
void	deselect_raw (Subset< BINTYPE, DIMTYPE > &sub)
	deselect those features that are selected in sub
void	deselect_all_raw ()
	mark all features (including frozen ones) as deselected
DIMTYPE	get_n_raw () const
	the full allocation size (max_n passed to the constructor), regardless of frozen features
DIMTYPE	get_d_raw () const
	number of features whose raw marker is positive: selected/traversed/frozen in forward mode, or deselected in backward mode (see set_forward_mode()) – NOT simply "selected", and mode-dependent unlike get_d()
bool	selected_raw (const DIMTYPE i) const
	true if raw feature index `i` is currently selected (or frozen); false (not an error) for an out-of-range index
void	make_random_subset (const DIMTYPE d)
	Generate random subset of exactly `d` features. Draws from the library PRNG (FST::fst_rand(), seeded through FST::fst_srand()), so a fixed seed reproduces the same subsets on every platform. Frozen features are left untouched and do not count towards `d`, which must satisfy 1 <= d <= get_n().
void	make_random_subset (const DIMTYPE lo_d, const DIMTYPE hi_d)
	Generate a random subset whose size is uniformly drawn from [lo_d,hi_d], then filled as make_random_subset(DIMTYPE) does. Requires lo_d < hi_d, both within 1..get_n().
void	make_random_subset (const float d_prob)
	Generate a random subset of random size; `d_prob` in (0,1], mean size over many calls is d_prob times the full feature count. Each non-frozen feature is selected independently with probability `d_prob`. The empty outcome is rejected and the whole draw repeated, so the result always has at least one selected feature; the size distribution is therefore binomial conditioned on being non-zero, not exactly binomial.
void	set_forward_mode (const bool forward=true)
	Flips the sign convention of id_sel/id_desel/id_traverse/id_frozen (forward: selected>0; backward: selected<0). Lets SFS-style (forward) and SBS-style (backward) algorithms share the same representation. Precondition: no feature/candidate-subset traversal in progress, and NOT in frozen mode (freeze/unfreeze with getFirstCandidateSubset()'s `reverse` parameter instead if direction needs to change while frozen).
bool	get_forward_mode () const
	true if in forward mode (the constructor default); see set_forward_mode()
void	set_frozen_mode (const bool freeze=false)
	Freezes (or unfreezes) the currently selected features, excluding them from further select()/deselect()/get_n()/get_d(). Freezing converts every id_sel (and id_traverse) feature to id_frozen; unfreezing converts every id_frozen (and id_traverse) feature back to id_sel. Frozen features are still visible to the get*Feature() traversals and count in get_n_raw()/get_d_raw(), just not in get_n()/get_d() or the adaptable select()/deselect() indexing. Precondition: no feature/candidate-subset traversal in progress, and `freeze` must differ from the current mode (repeated calls with the same value are asserted against, not idempotent).
bool	get_frozen_mode () const
	true if currently frozen; see set_frozen_mode()
bool	getFirstFeature (DIMTYPE &feat, bool selected=true, const int looplevel=0)
bool	getNextFeature (DIMTYPE &feat)
bool	getFirstCandidateSubset (const DIMTYPE g, bool reverse=false)
	begins traversal of all g-tuples of currently DESELECTED features (candidates to ADD) if `reverse` is false, or of currently SELECTED features (candidates to REMOVE) if true; each tuple is marked via tmp_id_traverse, read through getFirstTemporaryFeature()/temporary_features()
bool	getNextCandidateSubset ()
	advances to the next g-tuple begun by getFirstCandidateSubset(); returns false once exhausted
DIMTYPE	getNoOfCandidateSubsets (const DIMTYPE g, bool reverse=false)
bool	getFirstTemporaryFeature (DIMTYPE &feat)
bool	getNextTemporaryFeature (DIMTYPE &feat)
DIMTYPE	getNoOfTemporaryFeatures ()
	the number of features currently marked tmp_id_traverse (the g-tuple size of the CandidateSubset traversal in progress)
Feature_Range	selected_features () const
	reentrant range over all currently selected features (id_sel, id_frozen, id_traverse - as with getFirstFeature())
Feature_Range	temporary_features () const
	reentrant range over temporary features in the current CandidateSubset (as with getFirstTemporaryFeature())

Private Member Functions
DIMTYPE	get_combinations (const DIMTYPE n, const DIMTYPE k)
	Number of size-`k` combinations of `n` features (n choose k); throws if the result overflows DIMTYPE (or a 64-bit intermediate).

Private Attributes
const DIMTYPE	_n
	max. No. of features (full set size)
const std::unique_ptr< BINTYPE[]>	_bin
	default format to store subset info
BINTYPE	id_sel
	the marker value for a selected feature; sign flips with set_forward_mode()
BINTYPE	id_desel
	the marker value for a deselected feature; sign flips with set_forward_mode()
BINTYPE	id_traverse
	the marker value for a feature in the g-tuple currently being traversed by getFirstCandidateSubset()/getNextCandidateSubset()
BINTYPE	id_frozen
	the marker value for a frozen feature (see set_frozen_mode())
BINTYPE	tmp_id_sel
	id_sel/id_desel/id_traverse as resolved for the CURRENT getFirstCandidateSubset() call's `reverse` direction (independent of set_forward_mode()); local to get*CandidateSubset()
BINTYPE	tmp_id_desel
	see tmp_id_sel; local to get*CandidateSubset()
BINTYPE	tmp_id_traverse
bool	_forward_mode
	set by set_forward_mode(); read by get_forward_mode()
bool	_frozen_mode
	set by set_frozen_mode(); read by get_frozen_mode()
DIMTYPE	_gen_features
	the g-tuple size of the getFirstCandidateSubset() traversal in progress, or 0 if none
DIMTYPE	_enum_temporary
	cursor state for the deprecated getFirstTemporaryFeature()/getNextTemporaryFeature() pair
DIMTYPE	_enum_selected
	cursor state for the deprecated getFirstFeature()/getNextFeature() pair

Friends
std::ostream &	operator<< (std::ostream &os, const Subset< BINTYPE, DIMTYPE > &tdb)
	Streams a subset's selected features to `os` (as its print(), see the .cpp-side definition).

Detailed Description

template<class BINTYPE, typename DIMTYPE>
class FST::Subset< BINTYPE, DIMTYPE >

Stores the info on currently selected features, enables generating permutations, etc.

Note: the actual subset info is stored in _bin[],; negative values mark de-selected features, positive values mark selected features. 0 is undefined.; Basic identifier meaning: -1 feature deselected, 1 feature selected, 3 feature temporarily selected during traversal, 9 frozen feature (temporarily selected and protected from any changes); Those four concrete values are the FORWARD-mode convention (the constructor default). set_forward_mode(false) flips the sign of all of them: the step operations always write id_sel to the features they "select", so in backward mode selecting a candidate writes -1 and thereby REMOVES it from the subset. Membership itself is mode-independent - a feature is in the subset iff its marker is positive (get_d(), selected_features(), stateless_copy() and every consumer rely on that). Code that drives traversal or steps directly must compare against id_sel/id_desel/id_traverse/id_frozen, never against literals.

Examples: demo10.cpp, demo52t.cpp, and demo55.cpp.