Implements multinomial (softmax) logistic regression classifier. More...

#include <classifier_logreg.hpp>

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

Public Types
typedef Clonable_Impl< Classifier_Logistic_Regression, Classifier< RETURNTYPE, DIMTYPE, SUBSET, DATAACCESSOR > >	parent_impl
	implements clone() via the (implicit, member-wise) copy-constructor - all members are value-semantic
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 trained/classified on
typedef DATAACCESSOR::PPattern	PPattern
	one data sample as exposed by DATAACCESSOR (a raw pointer to its feature vector)
Public Types inherited from FST::Classifier< 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_lambda (const REALTYPE lambda)
	sets the L2 weight penalty (must be >=0); default 0.01
void	set_max_iter (const unsigned int max_iter)
	sets the damped-Newton iteration cap (must be >=1); default 100
void	set_tolerance (const REALTYPE tol)
	sets the gradient infinity-norm stopping tolerance (must be >0); default 1e-6
REALTYPE	get_lambda () const
	current L2 weight penalty
unsigned int	get_max_iter () const
	current Newton iteration cap
REALTYPE	get_tolerance () const
	current gradient infinity-norm stopping tolerance
void	initialize (const PDataAccessor da)
	Records data shape (classes, raw feature count) and resets to "no model yet". Must be called before train() or test() (and whenever the training set's shape changes).
virtual bool	classify (DIMTYPE &cls, const PPattern &pattern) override
virtual bool	classify_scores (std::vector< RETURNTYPE > &scores, const PPattern &pattern) override
virtual bool	train (const PDataAccessor da, const PSubset sub) override
	learns from designated training part of data
DIMTYPE	get_n () const
	raw (full) feature count, as recorded by initialize()
DIMTYPE	get_d () const
	current subset dimensionality, as recorded by the last train()
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< Classifier_Logistic_Regression< RETURNTYPE, DATATYPE, REALTYPE, IDXTYPE, DIMTYPE, SUBSET, DATAACCESSOR >, Classifier< RETURNTYPE, DIMTYPE, SUBSET, DATAACCESSOR > >
Classifier< RETURNTYPE, DIMTYPE, SUBSET, DATAACCESSOR > *	clone () const override
	dispatches to the DEEP_KIND mechanism (default CLONE_DEEP: Derived's copy-constructor)
Classifier< 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)
Classifier< 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::Classifier< RETURNTYPE, DIMTYPE, SUBSET, DATAACCESSOR >
virtual bool	test (RETURNTYPE &result, const PDataAccessor da)
virtual bool	test_confusion (std::vector< RETURNTYPE > &confusion, DIMTYPE &classes, const PDataAccessor da)
virtual bool	test_scores (std::vector< std::pair< RETURNTYPE, DIMTYPE > > &scores, const PDataAccessor da)
virtual bool	test_scores_matrix (std::vector< RETURNTYPE > &scores, std::vector< DIMTYPE > &labels, DIMTYPE &classes, const PDataAccessor da)
virtual bool	test_metric (RETURNTYPE &result, const PDataAccessor da, const Metric_Spec< RETURNTYPE > &spec)
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
REALTYPE	_lambda
	L2 weight penalty (biases unpenalized).
unsigned int	_max_iter
	Newton iteration cap.
REALTYPE	_tol
	gradient infinity-norm stopping tolerance
DIMTYPE	_classes
	number of classes, as recorded by initialize()
DIMTYPE	_features
	raw (full) feature count, as recorded by initialize()
DIMTYPE	_subfeatures
	d = current subset size
std::vector< DIMTYPE >	_index
	subset position -> raw feature index (first d entries valid)
std::vector< REALTYPE >	_mean
	standardization shift per subset position
std::vector< REALTYPE >	_scale
	standardization scale per subset position (1 for constant features)
std::vector< REALTYPE >	_W
	classes x (d+1) row-major; column d = bias
std::vector< REALTYPE >	_Z
	N x (d+1) standardized training data, last column fixed 1 (bias coordinate).
std::vector< DIMTYPE >	_y
	N training labels.
std::vector< REALTYPE >	_P
	N x classes posterior cache for Hessian assembly.
std::vector< REALTYPE >	_H
	Newton system, m x m, m=classes*(d+1) (lower triangle used).
std::vector< REALTYPE >	_grad
	objective gradient at the current Newton iterate (see eval_objective())
std::vector< REALTYPE >	_step
	Newton step solved from the Hessian system (see assemble_hessian()).
std::vector< REALTYPE >	_Wtry
	trial weights during step-halving line search in train()
std::vector< REALTYPE >	_sc
	per-class softmax score scratch used by eval_objective() (sized max(classes,d+1))

Private Member Functions
REALTYPE	eval_objective (const std::vector< REALTYPE > &W, const bool want_grad)
void	assemble_hessian (const std::size_t m, const REALTYPE extra_ridge)

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)

Detailed Description

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

Implements multinomial (softmax) logistic regression classifier.

One weight matrix W of shape classes x (d+1) (bias per class) trained by minimizing mean cross-entropy + (lambda/2)*||weights||^2 (biases unpenalized) with damped Newton iterations; the Newton system is solved by an internal Cholesky factorization, so no external linear-algebra dependency is needed.

Note: train() standardizes the selected features internally (mean/std computed on the current split's TRAIN part); classify() applies the stored transform. Constant features are inert (their weight stays exactly 0), so degenerate data that breaks the normal-model filters is safe here.; Training is deterministic: no random number generator is consumed, weights initialize to zero, and data is traversed in fixed order - repeated runs give identical results, whatever the seed or the thread count.; Convergence contract: iterate until the gradient infinity-norm drops below tolerance or max_iter is reached; step halving guarantees monotone descent on this convex objective. Defaults: lambda=0.01, max_iter=100, tolerance=1e-6.; Cost: each iteration assembles a K(d+1) x K(d+1) Hessian in O(N*(K(d+1))^2) and solves it in O((K(d+1))^3) - comparable to a kNN wrapper evaluation for typical wrapper-FS subset sizes; many classes combined with large subsets is the expensive corner (guarded, see train()).