Tools for working with L1-L2 parallel UD treebanks.

Installation

clone this repository
move inside the corresponding folder and run
```
stack install
```

If you are trying to install L2-UD on Windows and the latter does not work, try following these instructions.

Usage

Querying parallel L1-L2 treebanks

To return the set of parallel L1-L2 sentences matching an error pattern, run

l2-ud match L1-TB L2-TB PATTERNS [OPTS]

where:

L1-TB is the CoNNL-U file containing correction hypotheses
L2-TB is the CoNNL-U file containing original learner sentences
PATTERNS is a list of space-separated L1-L2 patterns or the path to a file containing an L1-L2 pattern per line (see the saved queries folder for examples).

By default, the match command prints the list of sentence IDs of the sentences matching the pattern.

Available OPTS:

--help, -h: show usage instructions
--markdown, -m: rather than sentence IDs, output a markdown report showing the sentences with matches highlighted in bold, like this one
--conllu=DIR, -cDIR: on top of printing sentence IDs to the standard output, extract the pairs of subtrees matching the pattern and write them to an L1.conllu and an L2.conllu file in the given DIRectory (if no directory is specified, files are created in the current folder)

Extracting error patterns (CURRENTLY UNDER DEVELOPMENT)

Return the error patterns contained in an L1-L2 treebank.

l2-ud extract L1-TB L2-TB [OPTS]

Where:

L1-TB is the CoNNL-U file containing correction hypotheses
L2-TB is the CoNNL-U file containing original learner sentences

Available OPTS:

--help, -h: show usage instructions
--markdown, -m: rather than sentence IDs, output a markdown report showing the sentences with errors highlighted in bold next to the error patterns that were detected
--conllu=DIR, -cDIR: on top of printing the error patterns to the standard output, extract the pairs of subtrees where the errors were found and write them to an L1.conllu and an L2.conllu file in the given DIRectory (if no directory is specified, files are created in the current folder)

Retrieving similar examples

Given an L1-L2 sentence pair, return similar examples from an L1-L2 treebank, by:

annotating the sentences in UD using UDPipe2 (requires an internet connection)
extracting error patterns from them (analogous to l2-ud extract)
querying the treebank with such error patterns (analogous to l2-ud match)

l2-ud example L1-TB L2-TB L1-SENTENCE L2-SENTENCE LANG [OPTS]

Where:

L1-TB is the CoNNL-U file containing correction hypotheses
L2-TB is the CoNNL-U file containing original learner sentences
L1-SENTENCE is a correct sentence
L2-SENTENCE is a sentence containing 1+ grammatical errors
LANG is the name of the UDPipe 2 model to be used for annotating the sentences. The default model for each language is called the English name of the language, lowercased, e.g. swedish

Available OPTS:

--help, -h: show usage instructions
--verbose, -v: show intermediate results (UD-annotated example sentences and extracted patterns)
--markdown, -m: rather than sentence IDs, show similar examples found in the treebank a markdown report.

L1-L2 patterns

An L1-L2 error pattern is a "parallel" gf-ud pattern¹, i.e. essentially a pair of UD patterns. For conciseness, instead of writing full pairs of patterns, L1-L2 patterns are written as single UD patterns with discrepancies enclosed in curly braces. For instance, the pattern

AND [POS "DET", FEATS_ "Gender={Masc->Fem}"]

reads as "feminine determiners corrected with their masculine form", or "feminine determiners that should have been masculine" and is expanded to two gf-ud patterns:

AND [POS "DET", FEATS_ "Gender=Masc"], to be looked in the L1 corrections treebank
AND [POS "DET", FEATS_ "Gender=Fem"], to be looked for in the L2 treebanks of original learner sentences.

L2-only patterns

For some types of error, an L2 pattern is sufficient to concisely describe an error. When that is the case, it is possible to write a single UD pattern P, which is expanded to a pair