The user guide consists of the these sections:
Start using MaltParser |
Controlling MaltParser |
Configuration |
Single Malt configuration |
Input and output format |
Parsing algorithms |
Feature model |
References |
This section contains a short guide to get familiar with MaltParser. We start by running MaltParser without any arguments by typing the following at the command line prompt (it is important that you are in the malt-1.0.3 directory):
prompt> java -jar malt.jarThis command will display the following output:
----------------------------------------------------------------------------- MaltParser 1.0.3 ----------------------------------------------------------------------------- MALT (Models and Algorithms for Language Technology) Group School of Mathematics and Systems Engineering (MSI) Vaxjo University, Sweden ----------------------------------------------------------------------------- Usage: java -jar malt.jar -fHere you can see the basic usage and options. To get all available options:java -jar malt.jar -h for more help and options help ( -h) : Show options ----------------------------------------------------------------------------- option_file ( -f) : Path to option file ----------------------------------------------------------------------------- verbosity ( -v) : Verbosity level debug - Logging of debugging messages error - Logging of error events fatal - Logging of very severe error events info - Logging of informational messages off - Logging turned off warn - Logging of harmful situations ----------------------------------------------------------------------------- Documentation: docs/index.html
prompt> java -jar malt.jar -hAll these options are also described in a short documentation and in a full documentation.
Now we are ready to train our first parsing model. In the directory examples/data there are two data files talbanken05_train.conll and talbanken05_test.conll, which contain very small portions of the Swedish treebank Talbanken05. The example data sets are formatted according to the CoNLL data format. Note that these data sets are very small and that you need more training data to create a useful parsing model.
To train a default parsing model with MaltParser type the following at the command line prompt:
prompt> java -jar malt.jar -c test -i examples/data/talbanken05_train.conll -m learnThis line tells MaltParser to create a parsing model named test.mco (also know as a Single Malt configuration file) from the data in the file examples/data/talbanken05_train.conll. The parsing model gets its name from the configuration name, which is specified by the option flag -c without the file suffix .mco. The configuration name is a name of your own choice. The option flag -i tells the parser where to find the input data. The last option flag -m specifies the processing mode learn (as opposed to parse), since in this case we want to induce a model by using the default learning method (LIBSVM).
MaltParser outputs the following information:
Started: Wed Nov 07 15:37:40 CET 2007 Initialize the parsing algorithm... Reading sentences from 'examples/data/talbanken05_train.conll':1 Number of sentences: 32 Creating all models Creating LIBSVM model libsvm.mod Saving the symbol table... Saving the configuration specific options... Creates configuration file 'test.mco' ... Finished: Wed Nov 07 15:37:43 CET 2007 Learning time: 00:00:02 (2297 ms)Most of the logging information is self-explaining: it tells you that the parser is started at a certain time and date and that it reads sentences from a specified file containing 32 sentences. It continues with information about the learning models that are created, in this case only one LIBSVM model. It then saves the symbol table and all options (which cannot be changed later during parsing) and stores everything in a configuration file named test.mco. Finally, the parser informs you about the learning time.
We have now created a parsing model that we can use for parsing new sentences from the same language. It is important that unparsed sentences are formatted according to the format that was used during training (except that the output columns for head and dependency relation are missing). In this case tokens are represented by the first six columns of the CoNLL data format. To parse type the following:
prompt> $ java -jar malt.jar -c test -i examples/data/talbanken05_test.conll -o out.conll -m parsewhere -c test is the name of the configuration (the prefix file name of test.mco), -i examples/data/talbanken05_test.conll tells the parser where to find the input data, -o out.conll is the output file name, and finally -m parse specifies that the parser should be executed in parsing mode.
MaltParser can be controlled by specifying values for a range of different options. The values for these option can be specified in different ways:
Method | Description | Example |
---|---|---|
Command-line option flag | Uses the option flag with a dash (-) before the option flag and a blank between the option flag and the value | -c test |
Command-line option group and option name | Uses both the option group name and the option name to specify the option, with two dashes (--) before the option group name and one dash (-) to separate the option group name and the option name. The equality sign (=) is used for separating the option and the value. | --config-name=test |
Command-line option name | Is a shorter version of Command-line option group and option name and can only be used when the option name is unambiguous. | --name=test |
Option file | The option settings are specified in a option file, formatted in XML. To tell MaltParser to read the option file the option flag -f is used. Note that command line option settings override the settings in the option file if options are specified twice. |
<?xml version="1.0" encoding="UTF-8"?> <experiment> <optioncontainer> <optiongroup groupname="config"> <option name="name" value="test"/> </optiongroup> </optioncontainer> </experiment> |
An option file is useful when you have many options that differ from the default value, as is often the case when you are training a parsing model. The option file should have the following XML format:
Element | Description |
---|---|
experiment | All other elements must be enclosed by an experiment element. |
optioncontainer | It is possible to have one or more option containers, but MaltParser 1.0.3 only uses the first option container. Later releases may make use of multiple option containers, for instance, to build ensemble systems. |
optiongroup | There can be one or more option group elements within an option container. The attribute groupname specifies the option group name (see description of all available options). |
option | An option group can consist of one or more option. The element option has two attributes: name that corresponds to an option name and value that is the value of the option. Please consult the description of all available options to see all legal option names and values. |
Here is an example (examples/optionexample.xml):
<?xml version="1.0" encoding="UTF-8"?> <experiment> <optioncontainer> <optiongroup groupname="config"> <option name="name" value="example1"/> </optiongroup> <optiongroup groupname="singlemalt"> <option name="mode" value="learn"/> <option name="parsing_algorithm" value="nivrestandard"/> </optiongroup> <optiongroup groupname="input"> <option name="infile" value="examples/data/talbanken05_train.conll"/> </optiongroup> <optiongroup groupname="nivre"> <option name="root_handling" value="strict"/> </optiongroup> <optiongroup groupname="libsvm"> <option name="libsvm_options" value="-s_0_-t_1_-d_2_-g_0.2_-c_1.0_-r_0.4_-e_0.1"/> </optiongroup> <optiongroup groupname="guide"> <option name="data_split_column" value="POSTAG"/> <option name="data_split_structure" value="Input[0]"/> <option name="data_split_threshold" value="100"/> </optiongroup> </optioncontainer> </experiment>
To run MaltParser with the above option file type:
prompt> java -jar malt.jar -f examples/optionexample.xmlThis command will create a configuration file example1.mco based on the settings in the option file. It is possible to override the options by command-line options, for example:
prompt> java -jar malt.jar -f examples/optionexample.xml -a nivreeagerwhich will create a configuration based on the same setting except the parsing algorithm is now nivreeager instead of nivrestandard. If you want to create a configuration that has the same settings as the option file with command-line options, you need to type:
prompt> java -jar malt.jar -c example1 -m learn -i examples/data/talbanken05_train.conll -a nivrestandard -r strict -lso -s_0_-t_1_-d_2_-g_0.2_-c_1.0_-r_0.4_-e_0.1 -d POSTAG -s Input[0] -T 100To parse using one of the three configurations you simply type:
prompt> java -jar malt.jar -c example1 -m parse -i examples/data/talbanken05_test.conll -o out1.conll
The purpose of the configuration is to gather information about all settings and files into one file. During learning, the configuration is created and stored in a configuration file with the file suffix .mco. This configuration file can later be reused whenever the trained model is used to parse new data. Potentially there can be several types of configuration, but MaltParser 1.0.3 only knows one type: the Single Malt configuration (singlemalt).
A Single Malt configuration creates a parsing model based on one set of option values. It can be executed in six different modes:
Mode | Description |
---|---|
learn | Creates a configuration and induces a parsing model from input data. |
parse | Parses sentences using a configuration. |
info | Prints information about a configuration. |
unpack | Unpacks a configuration into a directory with the same name. |
proj | Creates a configuration and projectivizes input data without inducing a parsing model. |
deproj | Deprojectivizes input data using a configuration. |
Sometimes it is useful to get information about a configuration, for instance, to know which settings have been used when creating the configuration. To get this information you type:
prompt> java -jar malt.jar -c test -m infoThis will output a lot of information about the configuration:
CONFIGURATION Configuration name: test Configuration type: singlemalt Created: Wed Nov 07 15:37:40 CET 2007 SYSTEM Operating system architecture: x86 Operating system name: Windows XP JRE vendor name: Sun Microsystems Inc. JRE version number: 1.6.0_03 MALTPARSER Version: 1.0.3 Build date: November 7 2007 SETTINGS config workingdir ( -w) user.dir name ( -c) test logging ( -cl) info type ( -t) singlemalt logfile (-lfi) stdout url ( -u) covington allow_root ( -cr) true allow_shift ( -cs) false graph max_sentence_length (-gsl) 256 root_label (-grl) ROOT guide data_split_structure ( -s) learner ( -l) libsvm kbest ( -k) -1 features ( -F) classitem_separator (-gcs) _ prediction_strategy (-gps) combined data_split_column ( -d) data_split_threshold ( -T) 50 input infile ( -i) examples/data/talbanken05_train.conll reader ( -ir) tab charset ( -ic) UTF-8 format ( -if) /appdata/dataformat/conllx.xml libsvm libsvm_external (-lsx) save_instance_files (-lsi) false libsvm_options (-lso) malt0.4 depset (-mcd) behavior (-mcb) false posset (-mcp) cposset (-mcc) nivre root_handling ( -r) normal post_processing (-npp) false output charset ( -oc) UTF-8 format ( -of) /appdata/dataformat/conllx.xml writer ( -ow) tab outfile ( -o) pproj covered_root (-pcr) none marking_strategy ( -pp) none singlemalt parsing_algorithm ( -a) nivreeager null_value ( -nv) one mode ( -m) learn DEPENDENCIES --guide-features ( -F) /appdata/features/NivreEager.xml FEATURE MODEL InputColumn(POSTAG, Stack[0]) InputColumn(POSTAG, Input[0]) InputColumn(POSTAG, Input[1]) InputColumn(POSTAG, Input[2]) InputColumn(POSTAG, Input[3]) InputColumn(POSTAG, Stack[1]) OutputColumn(DEPREL, Stack[0]) OutputColumn(DEPREL, ldep(Stack[0])) OutputColumn(DEPREL, rdep(Stack[0])) OutputColumn(DEPREL, ldep(Input[0])) InputColumn(FORM, Stack[0]) InputColumn(FORM, Input[0]) InputColumn(FORM, Input[1]) InputColumn(FORM, head(Stack[0])) LIBSVM INTERFACE LIBSVM version: 2.85 SVM-param string: LIBSVM SETTINGS SVM type : C_SVC (0) Kernel : POLY (1) Degree : 2 Gamma : 0.2 Coef0 : 0.0 Cache Size : 100.0 MB C : 1.0 Eps : 1.0 Shrinking : 1 Probability : 0 #Weight : 0The information is grouped into different categories:
Category | Description |
---|---|
CONFIGURATION | The name and type of the configuration and the date when it was created. |
SYSTEM | Information about the system that was used when creating the configuration, such as processor, operating system and version of Java Runtime Environment (JRE). |
MALTPARSER | Version of MaltParser and when it was built. |
SETTINGS | All option settings divided into several categories. |
DEPENDENCIES | In some cases the parser self-corrects when an illegal combination of options is specified or some option is missing. In the example above the feature specification file is not specified and the parser uses the default feature specification file for the Nivre arc-eager parsing algorithm. |
FEATURE MODEL | Outputs the content of the feature specification file. |
<LEARNER> INTERFACE | Information about the interface to the learner, in this case LIBSVM. |
<LEARNER> SETTINGS | All settings of specific learner options, in this case LIBSVM. |
It is possible to unpack the configuration file test.mco by typing:
prompt> java -jar malt.jar -c test -m unpackThis command will create a new directory test containing the following files:
File | Description |
---|---|
libsvm.mod | The LIBSVM model that is used for predicting the next parsing action. |
savedoptions.sop | All option settings that cannot be changed during parsing. |
symboltables.sym | All distinct symbols in the training data, divided into different columns. For example, the column POSTAG in the CoNLL format has its own symbol table with all distinct values occurring in the training data. |
test_singlemalt.info | Information about the configuration (same as described above). |
It is possible to projectivize an input file, with or without involving parsing.
All non-projective arcs in the input file are replaced by projective arcs by applying a lifting operation. The lifts are encoded in the dependency labels of the lifted arcs. The encoding scheme can be varied using the flag -pp (marking_strategy), and there are currently five of them: none, baseline, head, path and head+path. (See Nivre & Nilsson (2005) for more details concerning the encoding schemes.) A dependency file can be projectivized using the head encoding by typing:
prompt> java -jar malt.jar -c pproj -m proj -i examples/data/talbanken05_test.conll -o projectivized.conll -pp head
There is one additional option for the projectivization called covered_root, which is mainly used for handling dangling punctuation. Depending on the treebank, a punctuation token located in the middle of a sentence can attach directly to the root, which entails that all arcs crossing the head arc of the punctuation token are non-projective. This, in turn, results in lots of (unnecessary) lifts, and can be avoided by using the covered_root flag -pcr. This option has four values: none, left, right and head. For the last three values, tokens like dangling punctuation are then attached to one of the tokens connected by the shortest arc covering the token, either the leftmost (left), rightmost (right), or head (head) token of the covering arc. This will prevent all the unnecessary lifts.
The projecitivization and deprojectivization (below), including the encoding schemes, are know as pseudo-projective transformations and are described in more detail in Nivre & Nilsson (2005). The only difference compared to Nivre & Nilsson is that it is the most deeply nested non-projective arc that is lifted first, not the shortest one. Lifting the most deeply nested arc first is likely to result in fewer lifts when two or more non-projective arcs interact. In practice, however, this will probably have little impact for the parsing accuracy.
prompt> java -jar malt.jar -c pproj -m deproj -i projectivized.conll -o deprojectivized.conllThe file deprojectivized.conll will contain the deprojectivized data. Note that is is only the encoding schemes head, path and head+path that actively try to recover the non-projective arcs.
The format and encoding of the input and output data is controlled by the format, reader, writer and charset options in the input and output option group. The CoNLL and Malt-TAB data format specification files are already included in the MaltParser jar-file (malt.jar) in the appdata/dataformat directory. The CoNLL data format specification file looks like this:
<?xml version="1.0" encoding="UTF-8"?> <dataformat name="conllx"> <column name="ID" category="INPUT" type="ECHO"/> <column name="FORM" category="INPUT" type="STRING"/> <column name="LEMMA" category="INPUT" type="STRING"/> <column name="CPOSTAG" category="INPUT" type="STRING"/> <column name="POSTAG" category="INPUT" type="STRING"/> <column name="FEATS" category="INPUT" type="STRING"/> <column name="HEAD" category="HEAD" type="INTEGER"/> <column name="DEPREL" category="OUTPUT" type="STRING"/> <column name="PHEAD" category="HEAD" type="IGNORE" default="_"/> <column name="PDEPREL" category="OUTPUT" type="IGNORE" default="_"/> </dataformat>
A data format specification file has two types of XML elements. First, there is the dataformat element with the attribute name, which gives the data format a name. The dataformat element encloses one or more column elements, which contain information about individual columns. The column elements have three attributes:
Attribute | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
name | The column name. Note that the column name can be used by an option and within a feature model specification as an identifier of the column. | ||||||||||
category | The column category, one of the following:
| ||||||||||
type | Defines the data type of the column and/or its treatment during learning and parsing:
| ||||||||||
default | The default output for columns that have the column type IGNORE. |
It is possible to define your own input/output format and then supply the data format specification file with the format option.
Currently, MaltParser only supports tab-separated data files, which means that a sentence in a data file in the CoNLL data format could look like this:
1 Den _ PO PO DP 2 SS _ _ 2 blir _ V BV PS 0 ROOT _ _ 3 gemensam _ AJ AJ _ 2 SP _ _ 4 för _ PR PR _ 2 OA _ _ 5 alla _ PO PO TP 6 DT _ _ 6 inkomsttagare _ N NN HS 4 PA _ _ 7 oavsett _ PR PR _ 2 AA _ _ 8 civilstånd _ N NN SS 7 PA _ _ 9 . _ P IP _ 2 IP _ _
Finally, the character encoding can be specified with the charset option and this option is used by MaltParser to define the java class Charset.
Any deterministic parsing algorithm compatible with the MaltParser architecture can be implemented in the MaltParser package. MaltParser 1.0.3 contains two families of parsing algorithm: Nivre and Covington, both with two members.
Nivre's algorithm (Nivre 2003, Nivre 2004) is a linear-time algorithm limited to projective dependency structures. It can be run in arc-eager (-a nivreeager) or arc-standard (-a nivrestandard) mode. In addition, the root handling option can be used to change the algorithm's behavior with respect to root tokens, i.e., tokens of the input sentence that are not dependent on another token.
Nivre's algorithm uses two data structures:
Covington's algorithm (Covington 2001) is a quadratic-time algorithm for unrestricted dependency structures, which proceeds by trying to link each new token to each preceding token. It can be run in a projective (-a covproj) mode, where the linking operation is restricted to projective dependency structures, or in a non-projective (-a covnonproj) mode, allowing non-projective (but acyclic) dependency structures. In addition, there are two options, allow shift and allow root, that controls the behavior of Covington's algorithm.
Covington's algorithm uses four data structures:
MaltParser uses history-based feature models for predicting the next action in the deterministic derivation of a dependency
structure, which means that it uses features of the partially built dependency structure together with features of
the (tagged) input string. Features that make use of the partially built dependency structure corresponds to the OUTPUT category of
the data format, for example DEPREL
in the CoNLL data format, and features of the input string corresponds to the INPUT
category of the data format, for example CPOSTAG
and FORM
.
The feature model specification must be specified in an XML file according to the format below or in a text file formatted according to the specification
given by the MaltParser 0.x user guide. The latter specification format should be saved in a text file where the file name must end
with the file suffix .par
.
Below you can see an example of the new XML format (Nivre arc-eager default feature model):
<?xml version="1.0" encoding="UTF-8"?> <featuremodels> <featuremodel name="nivreeager"> <feature>InputColumn(POSTAG, Stack[0])</feature> <feature>InputColumn(POSTAG, Input[0])</feature> <feature>InputColumn(POSTAG, Input[1])</feature> <feature>InputColumn(POSTAG, Input[2])</feature> <feature>InputColumn(POSTAG, Input[3])</feature> <feature>InputColumn(POSTAG, Stack[1])</feature> <feature>OutputColumn(DEPREL, Stack[0])</feature> <feature>OutputColumn(DEPREL, ldep(Stack[0]))</feature> <feature>OutputColumn(DEPREL, rdep(Stack[0]))</feature> <feature>OutputColumn(DEPREL, ldep(Input[0]))</feature> <feature>InputColumn(FORM, Stack[0])</feature> <feature>InputColumn(FORM, Input[0])</feature> <feature>InputColumn(FORM, Input[1])</feature> <feature>InputColumn(FORM, head(Stack[0]))</feature> </featuremodel> </featuremodels>
Each feature is defined using a functional notation with three types of functions:
Type | Description | ||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Feature function | A feature function returns a particular attribute of a token or graph node and
takes two arguments: a column name and an address funtion. There are two feature functions available:
| ||||||||||||||||||||||
Address function | There are two types of address functions: parsing algorithm specific functions and dependency graph functions.
The parsing algorithm specific functions have the form Data-structure[i], where Data-structure is a data structure used by a specific parsing algorithm
and i is an offset from the start position in this data structure. The following data structures are available for different parsing algorithms:
| ||||||||||||||||||||||
Feature map function | Maps a feature value onto a new set of values and takes as arguments a feature specification
and one or more arguments that control the mapping. There is one feature map function:
|
MaltParser is equipped with a default feature model specification for each parsing algorithm and it automatically identifies the corresponding feature model specification. It is possible to define your own feature model specification using the description above and using the --guide-features option to specify the feature model specification file.