Maximum Entropy Modeling Toolkit
for Python and C++
Zhang Le
ejoy@xinhuanet.com
29th December 2004
Contents
1 What is it 4
1.1 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2 Todo List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3 Known Problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2 Building and Installation 6
2.1 System Requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.2 Building C++ Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2.1 Building on Unix Platform (Linux/*BSD/SunOS etc.) . . . . . . . . . . . . . . . . . . . . . . . 7
2.2.2 Building on Win32 Platform (BCC/MSVC/Intel C++ etc.) . . . . . . . . . . . . . . . . . . . . 8
2.2.2.1 Cygwin and MinGW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.2.2 Borland C++ with STLPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.2.3 Microsoft Visual C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.2.4 Intel C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.3 About Fortran Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3 Building Python Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3 Introduction to Maximum Entropy Modeling 10
3.1 The Modeling Problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.2 Parameter Estimation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.3 Further Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4 Tutorial 13
4.1 Representing Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.2 Create a Maxent Model Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3 Adding Events to Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.4 Training the Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.5 Using the Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.6 Case Study: Building a maxent Part-of-Speech Tagger . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.6.1 The Tagging Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.6.2 Feature Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
CONTENTS 2
4.6.3 Training The Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.6.4 Using The Tagger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5 Command Line Utility 23
5.1 The maxent Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.2 Data Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
6 API Reference 28
6.1 C++ API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.2 maxent Namespace Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.2.1 Detailed Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.2.2 Variable Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
6.2.2.1 int maxent::verbose = 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
6.3 maxent::MaxentModel Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
6.3.1 Detailed Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
6.3.2 Constructor & Destructor Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
6.3.2.1 maxent::MaxentModel::MaxentModel () . . . . . . . . . . . . . . . . . . . . . . . . . . 30
6.3.3 Member Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
6.3.3.1 void maxent::MaxentModel::add_event (const vector< string > & context, const
outcome_type & outcome, size_t count = 1) . . . . . . . . . . . . . . . . . . . . . . . 30
6.3.3.2 void maxent::MaxentModel::add_event (const context_type & context, const
outcome_type & outcome, size_t count = 1) . . . . . . . . . . . . . . . . . . . . . . . 31
6.3.3.3 template<typename Iterator> void maxent::MaxentModel::add_events (Iterator be-
gin, Iterator end) [inline] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
6.3.3.4 void maxent::MaxentModel::begin_add_event () . . . . . . . . . . . . . . . . . . . . . 31
6.3.3.5 void maxent::MaxentModel::end_add_event (size_t cutoff = 1) . . . . . . . . . . . . 31
6.3.3.6 double maxent::MaxentModel::eval (const vector< string > & context, const outcome_-
type & outcome) const . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
6.3.3.7 double maxent::MaxentModel::eval (const context_type & context, const outcome_-
type & outcome) const . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
6.3.3.8 void maxent::MaxentModel::eval_all (const vector< string > & context, std::vector<
pair< outcome_type, double > > & outcomes, bool sort_result = true) const . . . . 32
6.3.3.9 void maxent::MaxentModel::eval_all (const context_type & context, std::vector<
pair< outcome_type, double > > & outcomes, bool sort_result = true) const . . . . 32
6.3.3.10 void maxent::MaxentModel::load (const string & model) . . . . . . . . . . . . . . . . . 33
6.3.3.11 MaxentModel::outcome_type maxent::MaxentModel::predict (const vector< string >
& context) const . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.3.3.12 MaxentModel::outcome_type maxent::MaxentModel::predict (const context_type &
context) const . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.3.3.13 void maxent::MaxentModel::save (const string & model, bool binary = false) const . . 34
6.3.3.14 void maxent::MaxentModel::train (size_t iter = 15, const std::string & method =
"lbfgs", double sigma = 0.0, double tol = 1E-05) . . . . . . . . . . . . . . . . . . . . . 34
Generated on Sat Oct 4 09:49:54 2003 for maxent by Doxygen
CONTENTS 3
6.4 maxent::Trainer Class Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.4.1 Detailed Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.4.2 Member Function Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
6.4.2.1 void maxent::Trainer::set_training_data (shared_ptr< MEEventSpace > events,
shared_ptr< ParamsType > params, size_t n_theta, shared_array< double > theta,
shared_array< double > sigma, size_t n_outcomes, shared_ptr< MEEventSpace >
heldout_events = shared_ptr<MEEventSpace>()) . . . . . . . . . . . . . . . . . . . . 35
6.5 Python API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
7 Acknowledgment 36
Generated on Sat Oct 4 09:49:54 2003 for maxent by Doxygen
Chapter 1
What is it
This package provides a Maximum Entropy Modeling toolkit written in C++ with Python binding. In particular, it
includes:
• Conditional Maximum Entropy Model
• L-BFGS Parameter Estimation
• GIS Parameter Estimation
• Gaussian Prior Smoothing
• C++ API
• Python Extension module
• Document and Tutorial ;-)
If you do not know what Maximum Entropy Model (MaxEnt) is, please refer to chapter 3 for a brief introduction or
section 3.3 for some recommended papers.
This manual always refers to the features existed in the latest version. Changes between different releases are docu-
mented elsewhere in NEWS (major changes) and ChangeLog (minor changes).
1.1 License
This software grew out of an early attempt to port the Java maxent package (http://maxent.sourceforge.net) into
C++. Therefore it obeys the same license of the java maxent package. The library is freeware and is licensed under
the LGPL license (see LICENSE file for more detail, or visit http://www.gnu.org/copyleft/lesser.html). It is
distributed with full source code and document. Contributions and bug reports are always welcome.
1.2 Todo List
• orange binding (beta quality, see python/orange/)
• IFS feature selection
• Field Induction Algorithm
• Non-conditional Maximum Entropy Model (Random Fields)
• Include more materials on MaxEnt in the document