This directory includes sources to perform experiments on
chunking and POS tagging tasks for Maximum Entropy.
These sources generate Figures 2 and 4 in the following paper:

Fang-Lan Huang, Cho-Jui Hsieh, Kai-Wei Chang, and Chih-Jen Lin.
Iterative Scaling and Coordinate Descent Methods for
Maximum Entropy Models, 2009.

This code is extended from OpenNLP (http://opennlp.sourceforge.net/).
Please read the LICENSE before using this tool.

Installation for Experiments
============================

The compiled java library are already provided in the 'build' directory.

To rebuild the library, follow the instructions to generate and compile the
codes modified from OpenNLP.

1. Set the "JAVA_HOME" environment property.

On Windows: Type

C:\> set JAVA_HOME=C:\jdk1.2.2

On Linux/Unix: Type

$ setenv JAVA_HOME /usr/lib/jvm/java-6-sun
  (csh)
$ JAVA_HOME=/usr/lib/jvm/java-6-sun; export JAVA_HOME
  (ksh, bash)

2. Type

$ sh install_maxent_exp.sh

to build the codes.

The installation script will generate 'trove.jar', 'maxent-2.5.1.jar', 
and 'opennlp-tools-1.4.1.jar' in the 'build' directory.


Type

rm -r tools maxent

to clean the installation code if you encounter problems.

Compare Maxent Solvers: GIS, SCGIS, CD, CDD, LBFGS, TRON
========================================================

Type

% python compare_maxent_solver.py

to compare these implementations. The results are stored in the 'log'
directory. Use the values in columns 'time', 'f', 'g' and 'Accuracy'/'F1'
to generate Figures 2 and 4.

Note that the F1 measure results of chunking task are generated by 'conlleval.pl'
which is a Perl script provided by the host of Conll2000 competition
(http://www.cnts.ua.ac.be/conll2000/chunking/conlleval.txt).

Information about Directories and Files
=======================================

In the 'opennlp-package' directory, we include the following two packages
downloaded form http://opennlp.sourceforge.net

maxent-2.5.1.tar: OpenNLP Maxent version 2.5.1 and

opennlp-tools-1.4.1.tar:  OpenNLP Tools version 1.4.1.

To add solvers to OpenNLP, we provide two patch files 'maxent.patch' 
and 'tools.patch' to modify the packages. The commands to
patch the files are included in 'install_maxent_exp.sh'.

The file 'GISTrainer_origin.java' in the 'preprocess' directory
implements GIS, SCGIS, CD, CDD, LBFGS, and TRON methods. 
For convenience, we define macros to implement SCGIS, CD and CDD. 
The macros can be preprocessed by 'preprocessing.py' in the same directory.

In the 'data' directory, 'conll2000chunkertr' and 'conll2000chunkerte' are the
training and testing files of Conll2000 chunking task downloaded from
http://www.cnts.ua.ac.be/conll2000/chunking/. 'conll2000tr' and 'conll2000te'
are the training and testing files of Conll2000 POS tagging task. This data are
retrieved from Conll2000 chunking task. 'brown.train' and
'brown.test' are the training and testing files of Brown POS tagging task. They
are preprocessed as described in the paper. The original Brown corpora is 
available at http://www.nltk.org/data/.
