Data for: Learning tonotactics with autosegmental representations

This dataset provides BUFIA-AR, an implementation of the Bottom-Up Factor Inference Algorithm over Autosegmental Representations (ARs) for learning phonotactic grammars from positive examples. Given a set of words represented as orthographic forms, BUFIA-AR constructs their corresponding autosegmental representations and infers a constraint-based grammar consisting of the minimal forbidden substructures that characterize the language. The repository also includes the AR class used to represent autosegmental structures, the datasets used in the experiments reported in the paper, and additional demonstration datasets for illustrating the use of the implementation. # Learning tonotactics with autosegmental representations ## Introduction This repository contains the data and code accompanying the paper *Learning Tonotactics with Autosegmental Representations* (Li & Heinz), accepted for publication in *Phonology*.  The files are described below. ### `BUFIA-AR` **BUFIA-AR (Bottom-Up Factor Inference Algorithm over Autosegmental Representations)** is a tool for learning phonological grammars from syllabified wordlists. The functions of BUFIA-AR include: * Convert syllabified or **orthographic** wordlists into **Autorep** graph objects * Print out the corresponding **autosegmental representations** of words * Infer phonological grammars (inviolable constraints over ARs) with user-defined complexity limits * Export learned constraints as `svg`, `png`, or `pdf` — ready to include directly in papers Please see below for instructions on how to run BUFIA-AR from the command line. **`autorep.py`** A supporting module that defines the classes and data structures used to represent and manipulate autosegmental representations. **`Interactive.ipynb`** An interactive notebook for running BUFIA-AR, exploring autosegmental representations, and learning constraints without using the command line. **`_environment.yml`** A configuration file that specifies the Conda environment and dependencies required to run BUFIA-AR. **`hausa.txt`** A text file containing the Hausa wordlist used in the paper. --- ## Instruction: Using BUFIA-AR for Tonotactic Learning ### 0. Download Download all files in this repository and place them in a single folder. Alternatively, you can clone the repository using Git: ```bash git clone github.com cd BUFIA_AR ``` ### 1*. Required Data file The current folder contains a Hausa data file. To use BUFIA-AR with another language, prepare a syllabified wordlist with annotated tone markers and save it as a `.txt` file (e.g., `hausa.txt`). Each line should contain one word form. ``` gáa.ɓàa kòo.góo rú.wáa kúm.fáa táf.kìi ``` Note the contour tone is marked on the nucleaus vowel: ``` mâi mù.tûm kûn.née ``` If the wordlist is not already syllabified, a syllabifier can be used. One option is to use Jordan Kodner's [Syllabify](github.com). ### 2. Create the environment An `environment.yml` file is provided with all required dependencies.\ Create the environment with: ```bash conda env create -f environment.yml ``` Then activate it: ```bash conda activate bufia-ar ``` #### 3. Verify installation (optional) ```bash python -c "import graphviz, numpy; print(graphviz.__version__, numpy.__version__)" dot -V # checks Graphviz binary ``` #### 4. Run the command line ```bash python BUFIA_AR.py --input INPUT [--output OUTPUT] [--format FORMAT] [--t T] [--s S] [--m M] (-convert | -learn) ``` **Required arguments are:** * `--input INPUT` : path to syllabified or orthographic wordlist - `-convert`: Convert a word list of orthographic forms into ARs - `-learn`: Learn a phonotactic grammar directly from a word list of orthographic forms. **Optional arguments** * `--output OUTPUT` : output directory (default: `output`) * `--format FORMAT` : graph output format (`svg`, `png`, `pdf`; default: `svg`) * `--t T` : tone number limit (default: `2`) * `--s S` : syllable number limit (default: `2`) * `--m M` : mora number limit (default: `2`) --- ## Demo: Learning Hausa Tonotactics The accompanying Hausa dataset is included in the `data` folder. ### **1. Get a list of ARs** To convert the provided wordlist into an autosegmental reppresentation, use this ```bash python BUFIA_AR.py --input data/hausa.txt -convert ``` This command line will generate a list (saved in output by default called "hausa_ar_list). As shown below, each line provides: * A word example (only one representative word is shown; other words with the same form are omitted). * The tone extracted from the transcription (obey OCP). * The autosegmental representation in the form of tuples `(tone, mora, syllable)` encodes associations across three tiers. ``` ƙá.sáa, H, [(1, 1, 1), (1, 2, 2), (1, 3, 2)] ƙùu.ráa, LH, [(1, 1, 1), (1, 2, 1), (2, 3, 2), (2, 4, 2)] tà.ɓóo, LH, [(1, 1, 1), (2, 2, 2), (2, 3, 2)] tú.dùu, HL, [(1, 1, 1), (2, 2, 2), (2, 3, 2)] ``` Given a list of tuple associations such as: `[(1, 1, 1), (1, 2, 2), (1, 3, 2)]` : * `(1, 1, 1)` → tone 1 connects to mora 1 and syllable 1 * `(1, 2, 2)` → tone 1 connects to mora 2 and syllable 2 * `(1, 3, 2)` → tone 1 connects to mora 3 and syllable 2 ### **2. Learn grammar with default settings** The default configuration learns grammars within **2 tones, 2 moras, and 2 syllables**.\ The output will be saved as `.svg` files in the `output/` directory. ```bash python BUFIA_AR.py --input data/hausa.txt -learn ``` ### **3. Learn grammar with custom settings** You can increase the complexity limits and change the output format.\ For example, to allow up to **3 tones, 3 moras, and 3 syllables**, save results in `results/`, and export plots as PNG: ```bash python BUFIA_AR.py --input data/hausa.txt --output results --format png --t 3 --s 3 --m 3 -learn ``` --- #### Related Papers * Chandlee, J., Eyraud, R., Heinz, J., Jardine, A., & Rawski, J. (2019, July). Learning with Partially Ordered Representations. In *Proceedings of the 16th Meeting on the Mathematics of Language* (pp. 91-101). * Li, H. (2025). *Learning Tonotactic Patterns over Autosegmental Representations.* In *Proceedings of the Annual Meetings on Phonology* (Vol. 1, No. 1). University of Massachusetts Amherst Libraries.