Model is an interface for reranking models. More...

#include <model.H>

Inheritance diagram for reranker::Model:

Classes
class	Hook
	An interface for specifying a hook to be run by a Model instance. More...

class	UpdatePredicate
	An inner interface for a predicate that tests whether a Model needs to be updated based on the current training example. More...

class	Updater
	An inner interface specifying an update function for a model. More...

Public Member Functions
	Model ()
	Constructs a new instance with the empty string for its name and a NULL kernel function. More...

	Model (const string &name)
	Constructs a new instance with a NULL kernel function. More...

	Model (const string &name, KernelFunction *kernel_fn)
	Constructs a new instance with the specified kernel function. More...

	Model (const string &name, KernelFunction kernel_fn, Symbols symbols)
	Constructs a new instance with the specified kernel function and symbol table. More...

virtual	~Model ()
	Destroys this model and its associated kernel function. More...

const string &	name () const
	Returns the unique name for this model instance. More...

Symbols *	symbols () const
	Returns the symbol table for this model. More...

const Time &	time () const
	Returns the current training time of this model: number of epochs, number of time steps in the current epoch and total number of time steps (which is equal to the total number of training examples seen). More...

virtual int	best_model_epoch () const =0

int	num_updates () const
	Returns the number of updates made by this model. More...

const vector< int > &	num_training_errors_per_epoch ()
	Returns the number of training errors made for each epoch. More...

int	num_training_errors () const
	Returns the number of training errors made by this model. More...

int	min_epochs () const
	Returns the minimum number of epochs to train. More...

int	max_epochs () const
	Returns the maximum number of epochs to train. More...

const vector< double > &	loss_per_epoch ()
	Returns the loss per epoch for epoch of training that was evaluated. More...

virtual const string &	model_spec () const =0
	Returns the spec string for constructing a default instance of this model so it may be properly de-serialized by its ModelProtoReader. More...

virtual const string &	proto_reader_spec () const =0
	Returns the spec string for contructing an instance of a ModelProtoReader capable of de-serializing this Model implementation. More...

virtual const string &	proto_writer_spec () const =0
	Returns the spec string for contructing an instance of a ModelProtoWriter capable of serializing this Model implementation. More...

virtual shared_ptr < Candidate::Comparator >	score_comparator ()
	Returns a pointer to the score comparator used by this model. More...

virtual shared_ptr < Candidate::Comparator >	gold_comparator ()
	Returns a pointer to the gold comparator used by this model. More...

virtual bool	NeedToKeepTraining ()=0
	Returns whether more training epochs are required for this model. More...

virtual void	Train (CandidateSetIterator &examples, CandidateSetIterator &development_test)=0
	Trains this model on a collection of training examples, where each training example is a set of candidates, possibly with a distinguished "gold candidate" that is the reference against which other candidates are scored. More...

virtual void	NewEpoch ()=0

virtual void	EndOfEpoch ()=0

virtual void	TrainOneEpoch (CandidateSetIterator &examples)=0
	Trains this model for one epoch, i.e., a single pass through the specified set of training examples. More...

virtual void	TrainOnExample (CandidateSet &example)=0
	Trains this model on the specified training example. More...

virtual bool	NeedToUpdate (CandidateSet &example)=0
	Indicates whether the current model needs to be updated. More...

virtual void	Update (CandidateSet &example)=0
	Updates the current model based on the specified set of candidates. More...

virtual double	Evaluate (CandidateSetIterator &development_test)=0
	Evaluates this model on the specified set of held-out development test data. More...

virtual void	ScoreCandidates (CandidateSet &candidates, bool training)=0
	Scores the specified set of candidates according to either the raw or averaged version of this perceptron model. More...

virtual double	ScoreCandidate (Candidate &candidate, bool training)=0
	Scores a candidate according to either the raw or averaged version of this perceptron model. More...

virtual void	set_min_epochs (int min_epochs)
	Sets the minimum number of epochs to train. More...

virtual void	set_max_epochs (int max_epochs)
	Sets the maximum number of epochs to train. More...

virtual void	CompactifyFeatureUids ()=0
	Renumbers the potentially sparse feature uid’s so that they occupy the interval `[0,n-1]` densely, for `n` non-zero features in use by this model. More...

virtual void	set_end_of_epoch_hook (Hook *end_of_epoch_hook)

virtual bool	use_weighted_loss ()

virtual void	set_use_weighted_loss (bool use_weighted_loss)

virtual void	set_symbols (Symbols *symbols)
	Sets the Symbols instance for this Model to be the specified instance. More...

Public Member Functions inherited from reranker::FactoryConstructible
virtual	~FactoryConstructible ()

virtual void	RegisterInitializers (Initializers &initializers)

virtual void	Init (const Environment *env, const string &arg)

Protected Member Functions
void	set_name (const string &name)
	Sets the name of this Model instance. More...

void	set_kernel_fn (KernelFunction *kernel_fn)
	Sets the kernel function for this model. More...

void	set_score_comparator (shared_ptr< Candidate::Comparator > score_comparator)

void	set_gold_comparator (shared_ptr< Candidate::Comparator > gold_comparator)

void	SetDefaultObjects ()

void	SetDefaultComparators ()

void	SetDefaultCandidateSetScorer ()

shared_ptr< Candidate::Comparator >	GetComparator (const string &spec) const

shared_ptr< CandidateSet::Scorer >	GetCandidateSetScorer (const string &spec) const

shared_ptr< UpdatePredicate >	GetUpdatePredicate (const string &spec) const

shared_ptr< Updater >	GetUpdater (const string &spec) const

virtual void	CheckNumberOfTokens (const string &arg, const vector< string > &tokens, size_t min_expected_number, size_t max_expected_number, const string &class_name) const
	A helper method for implementing the Init method: throws a std::runtime_error if the number of tokens in the argument string is not the expected number. More...

Protected Attributes
string	name_
	This model’s unique name. More...

Time	time_
	The tiny object that holds the "training time" for this model (epoch, index and absolute time index). More...

KernelFunction *	kernel_fn_
	Yes, this is an interface, but we add the kernel function as a data member. More...

Symbols *	symbols_
	The symbol table for this model (may be NULL). More...

shared_ptr< Candidate::Comparator >	score_comparator_
	A comparator to provide an ordering for candidates based on score when scoring all candidates in a set. More...

shared_ptr< Candidate::Comparator >	gold_comparator_
	A comparator to provide an ordering for candidates to find the gold candidate in a set. More...

shared_ptr< CandidateSet::Scorer >	candidate_set_scorer_
	A scorer for CandidateSet instances. More...

shared_ptr< UpdatePredicate >	update_predicate_
	The update predicate for this model. More...

shared_ptr< Updater >	updater_
	The updater for this model. More...

vector< double >	loss_per_epoch_
	The average loss per epoch. More...

vector< int >	num_testing_errors_per_epoch_
	The number of testing errors made on held-out development test data for each epoch. More...

vector< int >	num_training_errors_per_epoch_
	The number of errors made on training examples during each epoch. More...

int	num_training_errors_
	The number of errors made on training examples. More...

int	num_updates_
	The number of times an update was performed on this model during training. More...

int	min_epochs_
	The minimum number of training epochs to execute. More...

int	max_epochs_
	The maximum number of training epochs to execute. More...

Hook *	end_of_epoch_hook_
	A hook to be performed at the end of every epoch. More...

bool	use_weighted_loss_
	Indicates whether this model should weight each candidate’s loss by the value returned by CandidateSet::loss_weight. More...

Detailed Description

Model is an interface for reranking models.

TODO(dbikel): Add factory for kernel functions. Remove all constructors but the zero-arg constructor from both Model and PerceptronModel.

Definition at line 141 of file model.H.

Constructor & Destructor Documentation

reranker::Model::Model ( )

inline

Constructs a new instance with the empty string for its name and a NULL kernel function.

Definition at line 145 of file model.H.

reranker::Model::Model ( const string & name )

inline

Constructs a new instance with a NULL kernel function.

Parameters

name	the unique name of this model instance

Definition at line 160 of file model.H.

reranker::Model::Model	(	const string &	name,
		KernelFunction *	kernel_fn
	)

inline

Constructs a new instance with the specified kernel function.

Parameters

name	the unique name of this model instance
kernel_fn	the kernel function for this model to use when applied to training or test instances

Definition at line 177 of file model.H.

reranker::Model::Model	(	const string &	name,
		KernelFunction *	kernel_fn,
		Symbols *	symbols
	)

inline

Constructs a new instance with the specified kernel function and symbol table.

Parameters

name	the unique name of this model instance
kernel_fn	the kernel function for this model to use when applied to training or test instances
symbols	the symbol table for this Model to use; this Model will be responsible for deleting this Symbols object

Definition at line 198 of file model.H.

virtual reranker::Model::~Model ( )

inlinevirtual

Destroys this model and its associated kernel function.

Definition at line 213 of file model.H.

Member Function Documentation

virtual int reranker::Model::best_model_epoch ( ) const

pure virtual

Implemented in reranker::PerceptronModel.

void reranker::Model::CheckNumberOfTokens	(	const string &	arg,
		const vector< string > &	tokens,
		size_t	min_expected_number,
		size_t	max_expected_number,
		const string &	class_name
	)		const

protectedvirtual

A helper method for implementing the Init method: throws a std::runtime_error if the number of tokens in the argument string is not the expected number.

Parameters

arg	the arg that was tokenized (for error reporting)
tokens	the tokens array to inspect for correct size
min_expected_number	the minimum expected number of tokens
max_expected_number	the maximum expected number of tokens
class_name	the name of the class invoking this method (for error reporting)

Definition at line 137 of file model.C.

virtual void reranker::Model::CompactifyFeatureUids ( )

pure virtual

Renumbers the potentially sparse feature uid’s so that they occupy the interval [0,n-1] densely, for n non-zero features in use by this model.

If the internal Symbols instance is non-NULL, then this method also adjusts it to reflect the new set of feature uid’s.

Implemented in reranker::PerceptronModel.

virtual void reranker::Model::EndOfEpoch ( )

pure virtual

Implemented in reranker::PerceptronModel.

virtual double reranker::Model::Evaluate ( CandidateSetIterator & development_test )

pure virtual

Evaluates this model on the specified set of held-out development test data.

Side effects:: This method is guaranteed to append a value to the internal loss_per_epoch_ vector.

Parameters

development_test a held-out set of examples to use for evaluation of this model (during training, this method is typically invoked after each epoch to determine when to stop)

Returns: the loss of this model when evaluated on the specified development test set

Implemented in reranker::PerceptronModel.

shared_ptr< CandidateSet::Scorer > reranker::Model::GetCandidateSetScorer ( const string & spec ) const

protected

Definition at line 163 of file model.C.

shared_ptr< Candidate::Comparator > reranker::Model::GetComparator ( const string & spec ) const

protected

Definition at line 155 of file model.C.

shared_ptr< Model::UpdatePredicate > reranker::Model::GetUpdatePredicate ( const string & spec ) const

protected

Definition at line 171 of file model.C.

shared_ptr< Model::Updater > reranker::Model::GetUpdater ( const string & spec ) const

protected

Definition at line 179 of file model.C.

virtual shared_ptr<Candidate::Comparator> reranker::Model::gold_comparator ( )

inlinevirtual

Returns a pointer to the gold comparator used by this model.

Definition at line 339 of file model.H.

const vector<double>& reranker::Model::loss_per_epoch ( )

inline

Returns the loss per epoch for epoch of training that was evaluated.

Definition at line 316 of file model.H.

int reranker::Model::max_epochs ( ) const

inline

Returns the maximum number of epochs to train.

Definition at line 313 of file model.H.

int reranker::Model::min_epochs ( ) const

inline

Returns the minimum number of epochs to train.

Definition at line 310 of file model.H.

virtual const string& reranker::Model::model_spec ( ) const

pure virtual

Returns the spec string for constructing a default instance of this model so it may be properly de-serialized by its ModelProtoReader.

Implemented in reranker::PerceptronModel.

const string& reranker::Model::name ( ) const

inline

Returns the unique name for this model instance.

Definition at line 281 of file model.H.

virtual bool reranker::Model::NeedToKeepTraining ( )

pure virtual

Returns whether more training epochs are required for this model.

Implementation advice:: Implementations of the Train method are strongly encouraged to have their main loop test be the return value of this method. Also, the return value of this method should respect the min_epochs and max_epochs values.

Implemented in reranker::PerceptronModel.

virtual bool reranker::Model::NeedToUpdate ( CandidateSet & example )

pure virtual

Indicates whether the current model needs to be updated.

For perceptron-style models, this is usually based on having scored the candidates and finding that the best-scoring candidate is not equal to the gold or reference candidate.

Implementation advice:: This method is typically implemented in terms of a UpdatePredicate instance.

Parameters

example the current training example

Implemented in reranker::PerceptronModel.

virtual void reranker::Model::NewEpoch ( )

pure virtual

Implemented in reranker::PerceptronModel.

int reranker::Model::num_training_errors ( ) const

inline

Returns the number of training errors made by this model.

In the case of the perceptron family of algorithms, this value is typically equal to the number of updates made during training.

Definition at line 307 of file model.H.

const vector<int>& reranker::Model::num_training_errors_per_epoch ( )

inline

Returns the number of training errors made for each epoch.

The last element of this vector is the number of training errors made during the most recent epoch of training.

Definition at line 301 of file model.H.

int reranker::Model::num_updates ( ) const

inline

Returns the number of updates made by this model.

In the case of the perceptron family of algorithms, this value is typically equal to the number of training errors.

Definition at line 297 of file model.H.

virtual const string& reranker::Model::proto_reader_spec ( ) const

pure virtual

Returns the spec string for contructing an instance of a ModelProtoReader capable of de-serializing this Model implementation.

Implemented in reranker::PerceptronModel.

virtual const string& reranker::Model::proto_writer_spec ( ) const

pure virtual

Returns the spec string for contructing an instance of a ModelProtoWriter capable of serializing this Model implementation.

Implemented in reranker::PerceptronModel.

virtual shared_ptr<Candidate::Comparator> reranker::Model::score_comparator ( )

inlinevirtual

Returns a pointer to the score comparator used by this model.

Definition at line 334 of file model.H.

virtual double reranker::Model::ScoreCandidate	(	Candidate &	candidate,
		bool	training
	)

pure virtual

Scores a candidate according to either the raw or averaged version of this perceptron model.

The specified candidate's score may be modified.

Parameters

[in,out]	candidate	the candidate to be scored by this model
	training	whether this is being called during training or evaluation of a model

Returns: the score of the specified candidate according to the specified model

Implemented in reranker::PerceptronModel.

virtual void reranker::Model::ScoreCandidates	(	CandidateSet &	candidates,
		bool	training
	)

pure virtual

Scores the specified set of candidates according to either the raw or averaged version of this perceptron model.

The scores of the specified set of candidates may be modified.

Parameters

[in,out]	candidates	the set of candidates to be scored
	training	whether this is being called during training or evaluation of a model

Implemented in reranker::PerceptronModel.

virtual void reranker::Model::set_end_of_epoch_hook ( Hook * end_of_epoch_hook )

inlinevirtual

Definition at line 462 of file model.H.

void reranker::Model::set_gold_comparator ( shared_ptr< Candidate::Comparator > gold_comparator )

inlineprotected

Definition at line 501 of file model.H.

void reranker::Model::set_kernel_fn ( KernelFunction * kernel_fn )

inlineprotected

Sets the kernel function for this model.

The kernel function instance will be owned by this Model instance.

Definition at line 491 of file model.H.

virtual void reranker::Model::set_max_epochs ( int max_epochs )

inlinevirtual

Sets the maximum number of epochs to train.

This value will only be respected if greater than 0.

Definition at line 453 of file model.H.

virtual void reranker::Model::set_min_epochs ( int min_epochs )

inlinevirtual

Sets the minimum number of epochs to train.

This value will only be respected if greater than 0.

Definition at line 449 of file model.H.

void reranker::Model::set_name ( const string & name )

inlineprotected

Sets the name of this Model instance.

Definition at line 487 of file model.H.

void reranker::Model::set_score_comparator ( shared_ptr< Candidate::Comparator > score_comparator )

inlineprotected

Definition at line 496 of file model.H.

virtual void reranker::Model::set_symbols ( Symbols * symbols )

inlinevirtual

Sets the Symbols instance for this Model to be the specified instance.

This Model will be responsible for destroying the specified Symbols instance.

Definition at line 478 of file model.H.

virtual void reranker::Model::set_use_weighted_loss ( bool use_weighted_loss )

inlinevirtual

Definition at line 471 of file model.H.

void reranker::Model::SetDefaultCandidateSetScorer ( )

inlineprotected

Definition at line 515 of file model.H.

void reranker::Model::SetDefaultComparators ( )

inlineprotected

Definition at line 510 of file model.H.

void reranker::Model::SetDefaultObjects ( )

inlineprotected

Definition at line 505 of file model.H.

Symbols* reranker::Model::symbols ( ) const

inline

Returns the symbol table for this model.

Definition at line 284 of file model.H.

const Time& reranker::Model::time ( ) const

inline

Returns the current training time of this model: number of epochs, number of time steps in the current epoch and total number of time steps (which is equal to the total number of training examples seen).

Definition at line 290 of file model.H.

virtual void reranker::Model::Train	(	CandidateSetIterator &	examples,
		CandidateSetIterator &	development_test
	)

pure virtual

Trains this model on a collection of training examples, where each training example is a set of candidates, possibly with a distinguished "gold candidate" that is the reference against which other candidates are scored.

Typically, invoking this method indicates to train a model until convergence.

Parameters

examples	the set of training examples on which to train this model
development_test	the set of held-out examples to use to evaluate the model after each epoch

Implemented in reranker::PerceptronModel.

virtual void reranker::Model::TrainOneEpoch ( CandidateSetIterator & examples )

pure virtual

Trains this model for one epoch, i.e., a single pass through the specified set of training examples.

Typically the Train method will be implemented in terms of this method.

Parameters

examples the set of training examples on which to train this model

Implemented in reranker::PerceptronModel.

virtual void reranker::Model::TrainOnExample ( CandidateSet & example )

pure virtual

Trains this model on the specified training example.

Typically, the TrainOneEpoch method will be implemented in terms of this method.

Parameters

example the example on which to train

Implemented in reranker::PerceptronModel.

virtual void reranker::Model::Update ( CandidateSet & example )

pure virtual

Updates the current model based on the specified set of candidates.

TrainOnExample will be implemented in terms of this method.

Implementation advice:: This method is typically implemented in terms of a Updater instance.

Parameters

example the current training example

Implemented in reranker::PerceptronModel.

virtual bool reranker::Model::use_weighted_loss ( )

inlinevirtual

Definition at line 469 of file model.H.

Member Data Documentation

shared_ptr<CandidateSet::Scorer> reranker::Model::candidate_set_scorer_

protected

A scorer for CandidateSet instances.

Definition at line 565 of file model.H.

Hook* reranker::Model::end_of_epoch_hook_

protected

A hook to be performed at the end of every epoch.

Definition at line 590 of file model.H.

shared_ptr<Candidate::Comparator> reranker::Model::gold_comparator_

protected

A comparator to provide an ordering for candidates to find the gold candidate in a set.

Definition at line 563 of file model.H.

KernelFunction* reranker::Model::kernel_fn_

protected

Yes, this is an interface, but we add the kernel function as a data member.

Definition at line 555 of file model.H.

vector<double> reranker::Model::loss_per_epoch_

protected

The average loss per epoch.

Definition at line 571 of file model.H.

int reranker::Model::max_epochs_

protected

The maximum number of training epochs to execute.

Definition at line 588 of file model.H.

int reranker::Model::min_epochs_

protected

The minimum number of training epochs to execute.

Definition at line 586 of file model.H.

string reranker::Model::name_

protected

This model’s unique name.

Definition at line 547 of file model.H.

vector<int> reranker::Model::num_testing_errors_per_epoch_

protected

The number of testing errors made on held-out development test data for each epoch.

Definition at line 574 of file model.H.

int reranker::Model::num_training_errors_

protected

The number of errors made on training examples.

This value may be identical to num_updates_ in the case of the perceptron family of algorithms.

Definition at line 580 of file model.H.

vector<int> reranker::Model::num_training_errors_per_epoch_

protected

The number of errors made on training examples during each epoch.

Definition at line 576 of file model.H.

int reranker::Model::num_updates_

protected

The number of times an update was performed on this model during training.

This value may be identical to num_training_errors_ in the case of the perceptron family of algorithms.

Definition at line 584 of file model.H.

shared_ptr<Candidate::Comparator> reranker::Model::score_comparator_

protected

A comparator to provide an ordering for candidates based on score when scoring all candidates in a set.

Definition at line 560 of file model.H.

Symbols* reranker::Model::symbols_

protected

The symbol table for this model (may be NULL).

Definition at line 557 of file model.H.

Time reranker::Model::time_

protected

The tiny object that holds the "training time" for this model (epoch, index and absolute time index).

Note that the absolute time index should always equal the total number of training examples seen during training.

Definition at line 552 of file model.H.

shared_ptr<UpdatePredicate> reranker::Model::update_predicate_

protected

The update predicate for this model.

Definition at line 567 of file model.H.

shared_ptr<Updater> reranker::Model::updater_

protected

The updater for this model.

Definition at line 569 of file model.H.

bool reranker::Model::use_weighted_loss_

protected

Indicates whether this model should weight each candidate’s loss by the value returned by CandidateSet::loss_weight.

Definition at line 593 of file model.H.

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

Classes

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation