Graphical User Interface	Command Line Interface
Erculator GUI	Erculator CLI

Project Overview

Erculator is web-based software that lets you create Optimality Theoretic (OT) tableaux, check their consistency, make inferences about winning candidates and plausible constraint rankings within and across tableaux, explore language typologies, and generate images (png, ps, pdf, Latex) of tableaux for direct inclusion in Word, LaTeX, and other documents.

Bug Reports

Please email any bug reports to etking at this_university period edu
Here is the bug page. [page]

News

• Nov 29, 2007 Full support for IPA in images of tableaux has been completed. Try it out and tell us where the bugs are.
• Dec 17, 2006 The lab will be giving a talk entitled “Efficiently Computing OT Typologies” at the 2007 annual meeting of the Linguistic Society of America, in which we’ll present some results obtained while working on Erculator. The talk will also include a demonstration of Erculator itself.

Erculator User’s Manual

version 1.0.0 — Summer 2007

Table of Contents

1 Overview and Features 1.1 Distribution and Installation 2 Some Phonological Theory 3 The Software 3.1 Using erculator-cli 3.1.1 Getting Started 3.1.2 Creating a Model and its Tableaux 3.2 Using erculator-web 3.2.1 Getting Started 3.2.2 Registration 3.2.3 Logging In 3.2.4 Models and Tableaux 3.2.5 The Model Browser 3.2.6 Editing Models 3.2.7 Editing Tablea 3.2.8 The IPA Palette 3.2.9 Output Formatting 3.2.10 Tutorial on erculator-web 3.3 Using liberculator 3.3.1 liberculator Reference 4 cPhon XML Specification 4.1 Introduction 4.1.1 Elements 4.1.2 Global IDs 4.1.3 Attributes 4.2 Models 4.3 Constraints 4.3.1 description 4.3.2 abbrev 4.3.3 ref 4.3.4 regexp 4.3.5 fsa

4 cPhon XML Specification 4.4 Tableaux 4.4.1 input 4.4.2 candidates 4.5 cDistributions 4.6 Grammars 4.6.1 fixedRankings 4.6.2 ercs 4.6.3 rankingValues 4.6.4 disharmonyValues 4.6.5 ewcs 4.6.6 weightingConditions 4.6.7 trials 4.6.8 evaluationNoise 4.6.9 plasticity 4.6.10 relPlasticitySpreading 4.6.11 tolerance 4.6.12 multiplier 4.6.13 parameterPairs 4.6.14 textblock 4.7 Displays 4.7.1 candidateDisplayOrder 4.7.2 constraintDisplayOrder 4.7.3 tableauxDisplayOrder 4.7.4 layouts 4.8 Tags 4.9 Conclusion 5 Downloads 6 Project Publications

1 Overview and Features

Erculator is software that lets you create Optimality Theoretic (OT) candidate tableaux, check their consistency, make inferences about winning candidates and plausible constraint rankings, explore the typology of possible languages, and format your tableaux for direct inclusion in Word, LATEX, and other documents. Through either erculator-cli or erculator-web, two interactive interfaces provided by Erculator, the user may accomplish the following. Create tableaux describing the constraint violations incurred by the candidate output forms from some input.

• Generate the elementary ranking conditions (ERCs) implied by a tableau.
• Detect logical inconsistencies in tableaux.
• Identify harmonically bounded candidates.
• Group tableaux over the same constraints into full OT models of phenomena.
• Specify possible rankings of a model’s constraints, either through a collection of partial ordering statements (e.g., DepC >> MaxV), or as a set of ERCs.
• Determine the possible winning candidates under the possible rankings and mark them.
• Infer possible rankings from hand-chosen winners.
• Generate the resulting typology of languages under possible constraint rankings.
• Export your tableaux for use in other programs, like Word, Excel, and LaTeX.

With liberculator, a Python software library included with Erculator, a programmer can incorporate all of these capabilities into his or her own Python applications.

1.1 Distribution and Installation

For Unix systems, Erculator is distributed as a collection of Python source code and docu mentation, together with a standard Python-style script to build and install the software. For Windows, the distribution is an executable program which handles all the details of in stallation. Both are available on the Erculator main page. In both cases, the user is required to already have working installations of Python (version 2.4.x or better) and Turbogears (0.8.9 or better). The source distribution includes a file README.txt with more details on building and installing the software, as well as notes on the organization of the source code. Erculator and its source are distributed by the Chicago Language Modeling Lab (CLML) under the terms of the GNU General Public License, Version 2, the body of which is included in the distribution as COPYING.txt.

2 Some Phonological Theory

Coming soon

3 The Software

The Erculator package consists of several software tools for linguists working under Opti mality Theory: a textual, command line-oriented program (erculator-cli), a graphically friendly, web-based program (erculator-web), and a programmer’s library of source code written in the Python programming language (liberculator). On a machine that has installed the Erculator distribution, the user may run the erculator-cli program as a textual interface to Erculator’s capabilities. Alternatively, a user on any machine with an internet connection may direct his or her web browser to any server which has installed the distribution, and thereby use the web interface. One such server is operated by the CLML at http://clml.uchicago.edu/erculator.

3.1 Using erculator-cli

3.1.1 Getting Started

When the Erculator distribution is installed, the setup script attempts to place the erculator-cli program into the system PATH, so that to start it, the user need simply invoke

erculator-cli.py

from a terminal command prompt (or, on a Windows system, double-click the installed shortcut to the program). Additionally, erculator-web provides a simple in-browser GUI2 to erculator-cli (at http://clml.uchicago.edu/erculator/erculator gui/), which itself runs erculator-cli.py as the server-side backend code. On startup, the program displays a brief version and copyright statement, and then shows the main menu:

--=== Main ===--[n] New Model[s] Select Model[l] Load Model[m] Merge Models---------------[i] Import Tableaux---------------[x] Exit ERCulator[?] Help>

The majority of the user’s interaction with erculator-cli is through menus like this. Each menu lists a set of actions that the user can perform. The > prompt indicates that the program is awaiting user input, which should consist of an action’s tag (indicated in the listing in [ ] brackets) followed by Enter.4 For example, at the main menu, typing n followed by Enter invokes the New Model action, while x prompts you to save any unsaved changes and then exits the program. Every menu in erculator-cli includes a special Help action, activated with ?. This shows general notes on what can be done from the current menu followed by concise de scriptions of each available action. For example, here is the result of invoking ? from the main menu:

--=== Main ===--[n] New Model[s] Select Model[l] Load Model[m] Merge Models---------------[i] Import Tableaux---------------[x] Exit ERCulator[?] Help>

The majority of the user’s interaction with erculator-cli is through menus like this. Each menu lists a set of actions that the user can perform. The > prompt indicates that the program is awaiting user input, which should consist of an action’s tag (indicated in the listing in [ ] brackets) followed by Enter.4 For example, at the main menu, typing n followed by Enter invokes the New Model action, while x prompts you to save any unsaved changes and then exits the program. Every menu in erculator-cli includes a special Help action, activated with ?. This shows general notes on what can be done from the current menu followed by concise de scriptions of each available action. For example, here is the result of invoking ? from the main menu:

> ?--=== Help for "Main" ===--ERCulator-cli is a command-line interface tool for working withcandidate tableaux in Optimality Theory.Tip: If you work with large tableaux, be sure your console or terminalis configured with a sufficient scroll buffer.At any menu you may enter the ’?’ help command for a summary of whatcan be done from that menu. For fuller documentation on usingERCulator-cli, please see the manual which is distributed with it.Available Actions in Menu "Main":[n] New Model -- Create a new model.[s] Select Model -- Select a loaded model for further actions.[l] Load Model -- Read a previously created model from disk.[m] Merge Models -- Merge two models over the same constraints.[i] Import Tableaux -- Import one or more tableaux from a CommaSeparated Values (CSV) file.[x] Exit ERCulator -- Exits the program.>

The > prompt is also used to solicit the user’s input for purposes other than selecting a menu action. For instance, if we wish to create a new OT model (essentially a group of related tableaux), we input n and are met with the following response:

New model’s name:>

Here the user is being prompted to enter some text. The response should look something like:

New model’s name:> Tutorial Model

The remainder of this section will take the form of a tutorial which will guide the user through the creation of a model, its candidate tableaux, and how to perform various typical actions on those tableaux.

3.1.2 Creating a Model and its Tableaux

To create a model, first open erculator-cli. When you have done this, type n in the > prompt. The program will ask you to name your model. For this tutorial, name it Tutorial Model CLI. After you have entered the name of your new model, you will be prompted to enter constraints separated by commas. Once your constraints have been entered, you are met with the following output, which is the model main menu :

--=== Tutorial Model CLI ===--Constraints (2): *VV, Max-IO(V)Tableaux (0):Ranking: {}[s] Save Model[d] Delete Model---------------[p] Model Properties[c] Add Constraints[r] Remove Constraints[k] Set Constraint Ranking---------------[n] Add a New Tableau[t] Select Tableau---------------[a] Analyze Model---------------[b] Go back[?] Help

If you would like to save your model, you must be logged in. If you are, you may save by entering s at the > prompt. Doing this will show your user directory and its contents. Follow the on-screen instructions to save your model. For this example, we have entered Tutorial Model CLI in the > prompt. If you wish to delete your model, you may type d at the > prompt. The program will ask, Really delete “yourmodelname”?. If you type y or yes, your model will be deleted; any other input will cause the program not to delete the model. If you would like to see properties of your model, type p at the > prompt. This will display various properties about your model and allow you to add or delete properties using the onscreen instructions. For now, let’s add a constraint. To add a constraint, type c at the > prompt. The program will ask you to enter constraints in the same way in which you did at the beginning of this tutorial. Let’s add *CC. Type this in at the > prompt, and the program will take you back to the model main menu. Let’s remove that constraint. Type r at the > prompt, and when the program asks which constraint(s) you would like to remove, type in the name *CC. This removes the constraint and displays the model main menu. Now, let’s make some progress and set a constraint ranking. Type k at the > prompt. The program will give you instructions on two methods for entering constraint rankings. Instead of pursuing the first option and entering elementary ranking conditions (ERCs), let’s pursue the second option and enter the following ranking: *VV > Max-IO(V). When you have accomplished this, you are taken back to the model main menu, and now the Ranking field is filled in. It is now time to create a tableau. Type n at the > prompt and you will be prompted to Enter the input form for this tableau. At this point, enter the input VVC. When you have entered the input, press Enter, choose a name for your tableau (for this example, you can simply enter Tableau 1), and press Enter again. You will notice that the tableau you just created has an input and ranked constraints, but no candidate forms. You are now looking at the tableau main menu :

--=== Tableau "Tableau 1" ===--VVC|*VV|Max-IO(V)|---|---|---------|[d] Delete Tableau[e] Export Tableau---------------[m] Modify Tableau[p] Tableau Properties[a] Analyze Tableau---------------[b] Go back[?] Help

To add candidates, type m and press Enter to modify the tableau. After doing this, you will be shown the modify tableau menu with the option to add a candidate entry:

--=== Modify "Tableau 1" ===--VVC|*VV|Max-IO(V)|---|---|---------|[a] Add a candidate entry[r] Remove a candidate entry[v] Set a candidate’s violations[w] Set the winning candidate---------------[b] Go back[?] Help

Type a in the > prompt and press Enter. When it asks for your candidate’s form, type in VVC. The program will ask how many times this candidate violates each constraint. Enter a cardinal number such as 0, 1, 2, etc. to answer the program. For the first constraint, *VV, the input VVC incurs 1 violation. Enter this number as your answer. For the next constraint, Max-IO(V), VVC incurs 0 violations. Enter this number as your answer. Finally, when the program has been told how many violations each constraint incurs, it will ask if this candidate should be considered optional. This prompt accepts yes or no as valid inputs. For this example, answer no. Now, repeat this process with the candidate VC. It incurs 0 violations of *VV and 1 violation of Max-IO(V). It is the optimal candidate, so answer yes when the program asks. At this point, if you would like to modify the violations a candidate receives or set a different winner, you may do so through the modify tableau menu that you have come back to. If you type v to modify the violations a candidate receives, you will need to enter the form of the candidate. Let us modify the candidate VC. Now, the program will ask you to enter the violations the candidate receives for each constraint just as it did when you entered the candidate the first time. To keep your tableau accurate, answer 0 for *VV and 1 for Max-IO(V). If you would like to reset which candidate is the winner (i.e. is optimal), you can do so through a similar process by typing w at the modify tableau menu and entering the appropriate candidate form. The output will show you what the tableau looked like before your modification and what it looks like now. Finally, type b at the > prompt to go back. Now you are ready to export a short tableau that you produced using erculator-cli to your favorite word processor. To do this, type e at the tableau main menu. Doing this will allow you to choose to export a Comma Separated Value (CSV) output, an HTML output, or a LATEX output. Select your favorite option, and the program will prompt you to save the output as a new file with the appropriate form. Simply enter a file name, and you have successfully exported your first tableau for inclusion into your work! If you would like to analyze your tableau further, type b to go back to the tableau main menu. If you would like to see properties of your tableau, type p to see properties displayed in the same way as for the model. To analyze your tableau, type a to have the program present you with the following analysis options:

--=== Analyze Tableau "Tableau 1" ===--[w] Calculate possible winners[r] Calculate constraint ranking[c] Print ranking as CNF---------------[m] Minimize entries’ ERC-sets[k] Minimize the model’s ranking arguments---------------[t] Generate Typology---------------[b] Go back[?] Help

By typing w at the > prompt, you may have Erculator calculate possible winners. The program gives you the option to set these winners as such by asking for a yes or no answer. If you answer yes, the program will respond with a hearty Aye, aye!. You may also type r at the > prompt to ask the program to analyze possible constraint rankings. Erculator will ask you if you would like to adopt its output as your ranking, and you may answer either yes or no. In a similar fashion, you may minimize your entries’ ERC-sets or minimize the model’s ranking arguments. Finally, you may have Erculator generate language typologies by typing t at the > prompt. With this option, you may choose to generate the number of possible languages considering the already existing ranking (by answering yes when the program asks if you would like to restrict the typology) or disregarding it (by answering no when the program asks about restricting the typology). The program will then ask if you would like to save the results to a text file, to which you may answer yes or no. At this point, you have made a basic model. Type b to go back to the tableau main menu, and then type b again to go back to the model main menu. Now, you are ready to analyze your entire model. Type a at the > prompt to analyze your model exactly as you would analyze a single tableau. For this tutorial, the model analysis will look the same as your tableau analysis since, at this point, the model contains just a single tableau. Type b to go back to the model main menu. Now, save your model by typing s. You may overwrite your previous save and save your model as Tutorial Model CLI. Congratulations! You have successfully created an OT model using erculator-cli.

3.2 Using erculator-web

erculator-web is a wrapper around erculator-cli which adds a web-based frontend GUI to its functionality.

3.2.1 Getting Started

To access erculator-web, click the gui button on the navigation sidebar of the CLML website. This will open the Model Browser. The Model Browser may be navigated with a series of tabs. If you are logged in, the first tab will show your models; if you are not logged in, you will see the set of public-access models. At present, you may only edit models which you own, as well as the anonymous models. However, you may not save models to the anonymous account. It is also possible to copy models from other users to your own user workspace.

3.2.2 Registration

While not necessary, if you wish to ensure that your models and tableaux cannot be edited by other users, you should create an account. Registration is free and simple: just click the register link on the navigation sidebar. The system will notify you if you attempt to register with a username or email address that is already taken. Activation instructions will be emailed to the address you provide.

3.2.3 Logging In

Once you have registered, you may log in by clicking the log in link. If the username and password you supply are correct, the navigation sidebar will change to indicate the username you are logged in under. You will also see two additional links: log out and user settings. log out is self-explanatory; user settings is currently unimplemented. After logging in, you may return to browsing other portions of the site. To access erculator-web, click on the gui link in the navigation sidebar.

3.2.4 Models and Tableaux

A tableau is a list of output candidates, given on the y-axis, and a list of constraints, given on the x-axis. The cells contain the violation marks incurred by a given candidate for each of the constraints in the top row. In addition to the tableau, Erculator employs a metastructure called a model. A model consists of one or more tableaux, each with their own candidates, rankings, and winner(s). Collecting multiple tableaux into models allows Erculator to compute information such as:

1. The set of possible winning candidates in each tableau under the model’s current ranking specification.
2. The model’s possible ranking arguments under the marked winners of the tableaux.
3. The typology of languages implied by the model’s tableaux.

These functions will be detailed when they are implemented into the GUI. Their func tionality is currently available using erculator-cli.5

3.2.5 The Model Browser

The Model Browser displays all the available models stored on the server. If you are logged in, the default tab will display models in your home directory; these models cannot be modified by other users. The remaining tab will allow you to browse models in other users’ directories. If you are not logged in, the default tab will display the anonymous user’s models. These models may be edited, but not saved, by anyone. To explore a particular model, simply click on the model name. This will allow you to edit and delete various properties of the model and its attendant tableaux. If you wish to create a new model while logged in, click on the Create New Model button. This will open a pop-up window prompting you to name the new model. After naming the model, you will be allowed to edit the model’s properties, as described in the tutorial section in 3.2.10. After selecting a model to edit, the interface changes to display the tableaux contained by the model. The Edit interface allows the user to edit two types of ob jects: models and individual tableaux.

3.2.6 Editing Models

The parameters of the currently selected model are displayed at the top of the editing interface. The interface displays four tabs: Constraints, Tableaux, Properties, and Analyze. The Constraints tab is selected by default. This tab displays the constraints that are active for all tableaux in the model. The Tableaux tab lists all of the tableaux subsumed by the selected model. This is also where you can add a new tableau to the model. Clicking on the Add New Tableau button brings up a text box prompting you for the name of the new tableau. The Properties tab lists properties associated with the model. The Analyze tab will soon be implemented. Clicking on the Back to Model Browser button returns to the user’s model overview. The model interface also provides functions to alter all the tableaux in a model simulta neously. Click on Minimize ’em or Maximize ’em to shrink or expand all the tableaux in a model. Clicking Edit ’em renders all the tableaux in a model simultaneously editable. To edit a model’s constraints or properties, click on the Edit button to the right of the model name. To save your changes, click the Save Changes button; to discard all changes, click on the Revert Changes button. IMPORTANT! Changes will not automatically be saved: you must click the Save Changes button to avoid losing all your edits and unsaved work! To delete a model and all its associated tableaux, click the trashcan icon next to the name of the model. You will be prompted to confirm before the model is deleted.

3.2.7 Editing Tableaux

In order to render a tableau editable, you must click either the Edit button next to the tableau name, or the model’s Edit ’em link, which renders all the tableaux in a model simultaneously editable. Individual tableaux have three tabs associated with them: Tableau, Properties, and Analyze (to be implemented soon). The Tableau tab (selected by default) shows the constraints, candidates, violations, and winner(s) for the tableau. When editable, you may enter constraint names, candidates, and numbers of violations. To change the winner, simply grab the OT winner hand and drag it as appropriate. The Properties tab shows the tableau’s properties, such as candidate order, name, and caption. The Analyze tab will be implemented soon.

3.2.8 The IPA Palette

The erculator-web GUI is fully Unicode compliant. This means that users may enter UTF-8 characters into the constraint and candidate text fields using their favorite input method. For users who do not have access to a Unicode input method, erculator-web provides a simple IPA input palette. To show or hide the palette, click the Show/Hide IPA Palette link. Clicking on a character in the palette inserts that character into the currently focused text input field.

3.2.9 Output Formatting

erculator-web supports a number of visualization options to make time-consuming for matting of OT tableaux a thing of the past. Beneath each tableau is a set of links: To HTML, To CSV, To PNG, To PDF, and To LaTeX. Clicking on a link will open a new window containing either an image file (for PNG and PDF) or the tableau in the appropriate markup (for HTML, CSV, and LATEX). This image/markup can be copied and pasted or dragged to your preferred word processing application.

3.2.10 Tutorial on erculator-web

The following section is a quick walk-through on how to get started using erculator-web, the Erculator’s GUI, by creating a model and a tableau. First, log in (or register, if you have not done so already) in order to save the new model that will be created. Regardless of log in status, click on the Create New Model button beneath the anonymous or ’’yourusername’’ tab. When the window pops up asking you to give the model a name, call it Tutorial Model GUI. As soon as you have entered this and the pop-up window has disappeared, the Edit interface is on and the Constraints tab is highlighted. Let’s add some constraints. Click on the New Constraint button under the Constraints tab, highlight the default text that says Constraint 1, and enter *VV. Now, repeat this process, deleting the default text, and typing in Max-IO(V). Now the constraints you need to create a simple tableau are entered. If you are logged in, be sure to save your changes and then click the Edit button again to return to the editing interface. Now you are ready to add a tableau. Highlight the Tableaux tab and click on the Add New Tableau button. When you are prompted to enter the new tableau’s name, call it Tableau 1. When you have entered this name, your new tableau will appear below the constraints tab with a box in which to enter the tableau’s input form. For this example, enter VVC as the input. After entering your input, you are ready to add some candidates. Click on the link below the input that says New Candidate. Now you are able to add your first candidate and mark its violations. For the first candidate, type VC. It violates Max-IO(V), so type in one * below that constraint in the appropriate box. VC does not violate *VV, so leave the field beneath that constraint blank. Now let’s add another candidate. Repeat the process by clicking on the New Candidate link below your first candidate and entering VVC. Then, enter violations for the constraints as you did before. Type nothing beneath Max-IO(V) since it is not violated by this candidate, and type one * beneath *VV since the candidate violates it once. Now you are done entering candidates. Click the Save and Check button above your tableau. Then, click the Save Changes button above your model. If you would like to add a Caption to your tableau, you may do so by clicking the Edit button above your tableau, then going to the Properties tab and adding a new property. Delete the text that is filled in by default which says property 2 (or something similar) and replace it with the word caption. Then, in the box next to that label, write your caption. When you are finished, click the Save and Check button above your tableau. Your tableau now has a caption. Captions are useful for explaining what your tableau is trying to show or prove or providing information to other users about how your model differs from the standard model implemented by Erculator. An explanation on how to add constraint rankings will be added soon.

3.3 Using liberculator

3.3.1 liberculator Reference

4 cPhon XML Specification

4.1 Introduction

This section gives an overview of the CLML cPhon XML specification (version 0.5). It is not a description of the scheme itself, which is implemented using the W3C XML Schema language (XSD), but the information given here is consistent with the constraints of the scheme.

4.1.1 Elements

A cPhon XML document contains one model element, which specifies analysis-independent information about a model ob ject. Models contain constraints and tableaux, and are dis cussed in detail in 4.2. The file may also contain information on cDistributions, which can specify information such as winning candidates. cDistributions are discussed in 4.5. 4.6 discusses grammar elements, which allow for the specification of various types of grammars, and 4.7 gives information on display elements.

4.1.2 Global IDs

The cPhon XML schema requires that all IDs in the document be globally unique. This means that you cannot give a constraint an ID of c2 and also give a candidate the ID c2.

4.1.3 Attributes

The scheme also restricts the usage of element attributes. In general, nested elements are preferred to attributes for purposes of readability and hierarchical clarity. Usage of attributes is largely reserved for globally unique IDs and element names.

4.2 Models

The basic element of a cPhon file is the model. There can only be one model per file. Models receive an ID and name. It is also possible to specify a document creation date and any number of authors.

<model id="model1" name="Model Name"> <author id="a1">King Arthur</author><author id="a2">H. Martinet</author><date>6/25/07</date></model>

Model elements may contain two types of subelements: constraints and tableaux. These elements specify the particulars of the constraints used in the model, the candidate inputs and outputs, and the record of constraint violations. The information contained between model tags does not specify winners, grammars, or layout data, as these notions are concep tually distinct. The model block simply contains the ‘raw data’ and is agnostic regarding analysis.

4.3 Constraints

The constraints block contains the description of any number of constraints.

<constraints> <constraint id="c1" name="Ident-IO"><abbrev>ID-IO</abbrev><description>Some text string</description><ref>http://www.somewhere.com</ref></constraint><constraint id="c2" name="NoCoda"><abbrev>NC</abbrev><description>Some text string</description><ref>http://www.somewhere.com</ref><regexp>$"D["</regexp></constraint><constraint id="c3" name="Nonfinality"><abbrev>NonFinal</abbrev><fsa>replace([]:@, [fr,eos], [(? -eos)*, eow])</fsa></constraint></constraints>

A constraints block must contain one or more instances of a constraint. Each constraint has two attributes, id and name. Constraints may also contain up to five optional sub- elements.

4.3.1 description

The description sub-element contains a prose description of the constraints.

4.3.2 abbrev

The abbrev sub-element contains an abbreviated constraint description.

4.3.3 ref

The ref sub-element specifies a reference where more information regarding the constraint can be found, e.g. a Wiki, website, text reference, etc.

4.3.4 regexp

The regexp sub-element gives the constraint encoded using some regular expression calculus.

4.3.5 fsa

The fsa sub-element gives some finite state representation of the constraint.

4.4 Tableaux

In addition to constraints, model specifications may include any number of tableau sub elements, which are contained in a single element.

<tableaux> <tableau id="t1" name="Pap tableau"><input>pap</input><candidates><candidate id="t1c1" name="pap"><violations of="c1">0</violations><violations of="c2">1</violations></candidate><candidate id="t1c2" name="pa"><violations of="c1">1</violations><violations of="c2">0</violations></candidate></candidates></tableau><tableau id="t2" name="Pa tableau"><input>pa</input><candidates><candidate id="t2c1" name="pap"><violations of="c1">1</violations><violations of="c2">1</violations></candidate><candidate id="t2c2" name="pa"><violations of="c1">0</violations><violations of="c2">0</violations></candidate></candidates></tableau></tableaux>

Like other elements with attributes, tableau elements have a unique id and a name. Tableau elements have two types of sub-elements, input and candidates.

4.4.1 input

The input sub-element gives the input for the tableau.

4.4.2 candidates

The candidates sub-element contains one or more candidate elements. Each candidate has a name and a unique id attribute, and contains a number of violations sub-elements equal to the number of constraint sub-elements of constraint. Each violation element has an of attribute, the value of which specifies a unique constraint id.

<violations of="c1">1</violations>

The violations tags contain an integer value corresponding to the number of times the candidate id violates the constraint specified by the of attribute. The violations tags contain an integer value corresponding to the number of times the candidate id violates the constraint specified by the of attribute.

4.5 cDistributions

The cDistributions block is used to specify additional information about candidates, such as probability distributions over surface forms, frequency data, ‘winners’, etc.

<cDistributions> <cDistribution id="distro1" name="OT winners" src="grammar2"><candidate id="t1c1" name="pap">1</candidate><candidate id="t1c2" name="pa">0</candidate></cDistribution><cDistribution id="distro2" name="Stochastic OT probabilities"><candidate id="t1c1" name="pap">0.7</candidate><candidate id="t1c2" name="pa">0.3</candidate></cDistribution><cDistribution id="distro3" name="Foobar winner scheme"><candidate id="t1c1" name="pap">foo</candidate><candidate id="t1c2" name="pa">bar</candidate></cDistribution></cDistributions>

The cDistributions block can contain any number of cDistribution sub-elements, each with its own name and unique id. Each of these cDistribution elements may encode dif ferent or even conflicting sets of information about the candidates. The only restriction is that each cDistribution block must contain a number of constraint elements equal to the number of constraint sub-elements of the model’s constraints block. In addition to the usual name and id attributes, cDistribution elements may specify an optional src attribute. If specified, this attribute will have a grammar id as its value. This feature allows users to note when the values of a cDistribution were produced using a grammar. An analogous attribute is available for grammar elements (see below).

4.6 Grammars

The grammars section of a cPhon file contains one or more grammar blocks.

<grammars> <grammar id="grammar1" name="OT Grammar" src="distro2"><fixedRankings><ranking id="r1">c2, c1</ranking></fixedRankings><ercs><erc id="erc1" tableau="t1" winner="t1c1">w,l</erc><erc id="erc2" tableau="t1" winner="t1c2">l,w</erc><erc id="erc3" tableau="t1" winner="t2c1">e,l</erc><erc id="erc4" tableau="t1" winner="t2c2">e,w</erc></ercs></grammar></grammars>

Like other elements, each grammar element has a name and a unique id attribute. Like cDistribution elements, each grammar may also optionally specify a src, which in this case would be a cDistribution id specifying the distribution over surface forms from which the was derived. At present, the cPhon scheme defines 14 possible sub-elements of grammar, many of which are mutually incompatible. However, in the interest of extensibility, we have elected to place as few restrictions on the make-up of grammars as possible. If you find that you cannot express your grammar formalism adequately, please contact us to discuss extensions to the schema. In addition, it is possible to simply use the textblock sub-element (defined in 4.6.14) which allows for the inclusion of arbitrary amounts of plain text.

4.6.1 fixedRankings

A fixedRanking element contains one or more ranking sub-elements, each of which is specified by a unique id attribute. Each ranking sub-element contains a comma-separated constraint id pair. The constraint to the left of the comma is interpreted as strictly outranking the constraint to the right of the comma.

<fixedRankings> <ranking id="r1">c2, c1</ranking><ranking id="r2">c6, c4</ranking><ranking id="r3">c1, c5</ranking></fixedRankings>

4.6.2 ercs

An ercs element contains one or more erc sub-elements specifiying Elementary Ranking Conditions (ERCs). Each erc sub-element contains id, tableau, and winner attributes. The id attribute is a globally unique identifier; the tableau attribute specifies the tableau id to which the ERC refers; and winner gives the winner’s id. The content specified between the tags consists of a comma-delimited series of symbols drawn from the alphabet {e, w, l}; the string must contain a number of these symbols equal to the number of constraint sub-elements of constraints.

<ercs> <erc id="erc1" tableau="t1" winner="t1c1">w,l</erc><erc id="erc2" tableau="t1" winner="t1c2">l,w</erc><erc id="erc3" tableau="t1" winner="t2c1">e,l</erc><erc id="erc4" tableau="t1" winner="t2c2">e,w</erc></ercs>

4.6.3 rankingValues

A rankingValues element contains one or more rankingValue sub-elements which specify a stochastic ranking value for a constraint. Each rankingValue element has an obligatory constraint attribute, the value of which specifies the id of the constraint in question.

<rankingValues> <rankingValue constraint="c1">100</rankingValue><rankingValue constraint="c2">10</rankingValue></rankingValues>

4.6.4 disharmonyValues

A disharmonyValues element contains one or more disharmonyValue sub-elements which spec ify the disharmony score for a constraint (where disharmony is usually calculated as ranking value + noise). Each disharmonyValue sub-element has an obligatory constraint attribute, the value of which specifies the id of the constraint in question.

<disharmonyValues> <disharmonyValue constraint="c1">100</disharmonyValue><disharmonyValue constraint="c2">10</disharmonyValue></disharmonyValues>

4.6.5 ewcs

An ewcs element contains one or more ewc sub-elements specifiying Elementary Weighting Conditions (EWCs). Each ewc sub-element contains id, tableau, and winner attributes. The id attribute is a globally unique identifier; the tableau attribute specifies the tableau id to which the EWC refers; and winner gives the winner’s id. The content specified between the tags consists of a comma-delimited series of symbols drawn from the set of integers greater than or equal to 0, which specify the minimal integer weightings for the data; the string must contain a number of these symbols equal to the number of constraint sub-elements of constraints. If the string contains a zero (0), this means that the weighting is infeasible in the sense of Potts et. al. 2007: there exists no possible weighting of constraints that would result in the specified winner. See the UMass HaLP site for more details.

<ewcs> <ewc id="erc1" tableau="t1" winner="t1c1">3,1</ewc><ewc id="erc2" tableau="t1" winner="t1c2">2,1</ewc><ewc id="erc3" tableau="t1" winner="t2c1">1,1</ewc><ewc id="erc4" tableau="t1" winner="t2c2">0,0</ewc></ewcs>

4.6.6 weightingConditions

A weightingConditions element specifies a number of condition sub-elements. These ele ments allow the user to specify text strings expressing the same information as an EWC, but expressed as, for example, an inequality. In the examples above, the weighting conditions which must hold such that candidate t2c1 wins over candidate t2c2 on input t2:name are that the weight of constraint c1 must be greater than or equal to the sum of 1.5 times the weight of constraint c2 plus the weight of constraint c3. Each condition element contains three obligatory attributes: winner, which gives the id of the winning candidate; loser, which gives the id of a single candidate that winner is superior to; and input, which specifies the name (text string) of an input to a tableau.

<weightingConditions> <condition winner="t2c1" loser="t2c2" input="t2:name">w(c1) >= 1.5 (w (c2) + w(c3) )</condition><condition winner="t2c1" loser="t2c2" input="t2:name">w(c1) >= w(c2) + w(c3)</condition></weightingConditions>

4.6.7 trials

The trials element specifies the number of trials in a Stochastic OT grammar.

<trials>1000</trials>

4.6.8 evaluationNoise

The evaluationNoise element specifies the evaluation noise in a Stochastic OT grammar.

<evaluationNoise>2.0</evaluationNoise>

4.6.9 plasticity

The plasticity element specifies the learning plasticity in a Stochastic OT grammar.

<plasticity>0.1</plasticity>

4.6.10 relPlasticitySpreading

The relPlasticitySpreading element specifies the relative plasticity spreading in a Stochastic OT grammar.

<relPlasticitySpreading>0.1</relPlasticitySpreading>

4.6.11 tolerance

The tolerance element gives the tolerance of imperfection accepted in hill-climbing for a MaxEnt grammar.

<tolerance>0.1</tolerance>

4.6.12 multiplier

The multiplier element gives the value of the Lagrange multiplier λi for the parametric form of a MaxEnt grammar.

<multiplier>0.1</multiplier>

4.6.13 parameterPairs

The parameterPairs element contains some number of parameterPair sub-elements, each of which has an obligatory constraint attribute. A parameterPair contains sub-elements sigma and mu.8

<parameterPairs> <parameterPair constraint="c2"><sigma>0.3</sigma><mu>4.1</mu></parameterPair></parameterPairs>

4.6.14 textblock

The textblock element is provided to allow for quick-and-dirty extendability.

<textblock> This is where you can include anything you want!</textblock>

4.7 Displays

The displays block contains any number of display sub-elements, each of which can contain different types of information regarding the visual display of models and associated data. Each display element is identified by a unique id attribute.

<displays> <display id="display1"><candidateDisplayOrder>t1c1, t1c2</candidateDisplayOrder><constraintDisplayOrder>c2, c1</constraintDisplayOrder><tableauxDisplayOrder>t1, t2</tableauxDisplayOrder><layouts><layout id="layout1"><item pos="1">grammar1</item><item pos="2"><textblock>Here is some descriptive text.</textblock></item><item pos="3">c1</item><item pos="4">c1:name</item><item pos="5">t1</item><item pos="6">t2</item></layout><layout id="layout2"><item pos="1">grammar2</item><item pos="2"><textblock>Here is some descriptive text.</textblock></item><item pos="3">c1</item><item pos="4">c1:name</item><item pos="5">t1</item><item pos="6">t2</item></layout></layouts></display><display id="display2">

<candidateDisplayOrder>t1c1, t1c2</candidateDisplayOrder>

<constraintDisplayOrder>c2, c1</constraintDisplayOrder>

<tableauxDisplayOrder>t1, t2</tableauxDisplayOrder>

</display></displays>

4.7.1 candidateDisplayOrder

The candidateDisplayOrder element contains a comma-delimited list of candidate ids. The order of the list corresponds to the order in which candidates should be displayed in tableaux. In the above example, candidate t1c1 would appear first, followed by candidate t1c2. Each candidateDisplayOrder element has an obligatory tableau attribute, which localizes the or dering to a given tableau.

<candidateDisplayOrder tableau="t1">t1c1, t1c2</candidateDisplayOrder>

4.7.2 constraintDisplayOrder

The constraintDisplayOrder element contains a comma-delimited list of constraint ids. The order of the list corresponds to the order in which constraints should be displayed in tableaux. In the above example, constraint c2 would appear first, with constraint c1 appearing to its right. Each constraintDisplayOrder element has an obligatory tableau attribute, which localizes the ordering to a given tableau.

<constraintDisplayOrder tableau="t1">c2, c1</constraintDisplayOrder>

4.7.3 tableauxDisplayOrder

The tableauxDisplayOrder element contains a comma-delimited list of tableau ids. The order of the list corresponds to the order in which tableaux should be displayed in the model. There may only be one tableauxDisplayOrder element per display block.

<tableauxDisplayOrder>t1, t2</tableauxDisplayOrder>

4.7.4 layouts

The layouts element contains any number of layout sub-elements, which simply record a linear ordering of items in the file for display purposes. For example, in one display, you may wish to show all tableaux, all constraints, and their definitions, but you may also wish to have a ‘terse’ display which simply shows ERCs and constraints without prose descriptions. Each layout element has a unique id and contains any number of item sub-elements. Each item element has a pos attribute, the value of which specifies the linear order in which the content of the element is to be displayed. It is possible to include text and images not specified in the model file by using the textblock and imgblock tags as illustrated below.

<layout id="layout1"> <item pos="1">grammar1</item><item pos="2"><textblock>Here is some descriptive text.</textblock></item><item pos="3">c1</item><item pos="4">c1:name</item><item pos="5">t1</item><item pos="6"><imgblock>file:///Users/jkirby/Desktop/table2.jpg</imgblock></item></layout>

4.8 Tags

The cPhon schema also defines a generic tag type called tag. Tags have two attributes, id and type. At this time, CLML has left the possible values of type open-ended, but a common usage might be to include comments:

<tag id="comment1" type="comment">Check this regexp</tag>

It is possible that in the future, we will remove tag and replace it with e.g. a comment tag, etc.

4.9 Conclusion

The cPhon file specification is a work in progress and will be updated along with Erculator. Please see the Erculator website for more information and a copy of the most up-to-date version of this manual. If you run into problems or have suggestions for further improvement of the cPhon file specification or aspects of the Erculator, please feel free to contact us.

5 Downloads

You don’t need to download anything to use Erculator (you can use the cli or gui right in your browser). These downloads are only necessary if you want to incorporate erculator-lib into your own python program, run erculator-cli locally, or serve erculator-web on your own site. Windows

• Executable installer, Version 1.0.0-dev: exe, msi

Source Distribution (all platforms)

• Development Snapshot (0.4.0-dev)
• Version 0.3.0

Subversion Repository Access

• Browsable and downloadable at http://clml.uchicago.edu/svn.
• Repository URL is svn://clml.uchicago.edu

6 Project Publications

• Erculator User’s Manual (work in progress): HTML, PDF, PS
• LSA 2007 Abstract: PDF