Treesearch

Pattern matching for dependency treebanks.

⚠️ Early Stage: This project is under active development. The API and query language will change as we refine the design.

Overview

Treesearch finds syntactic patterns in dependency-parsed corpora. It reads treebanks in CoNLL-U format and returns all sentences matching a specified structural pattern. Designed for corpus linguistics research on large treebanks with automatic parallel processing for multi-file operations.

Installation

From PyPI

Requires Python 3.12+.

pip install treesearch-ud

# Optional: Install with visualization support (displaCy)
pip install treesearch-ud[viz]

From Source

Requires Python 3.12+ and Rust toolchain.

# Clone repository
git clone https://github.com/rmalouf/treesearch
cd treesearch

# Install with uv (recommended)
uv pip install -e .

# Or with pip
pip install maturin
maturin develop

Quick Example

Find passive constructions in an English treebank:

import treesearch

# Parse a pattern for passive voice
pattern = treesearch.compile_query("""
    MATCH {
        V [upos="VERB"];
        Aux [lemma="be"];
        V -[aux:pass]-> Aux;
    }
""")

# Search a single file
for tree, match in treesearch.search("corpus.conllu", pattern):
    verb = tree.word(match["V"])
    print(f"{verb.form}: {tree.sentence_text}")

Search multiple files with automatic parallel processing:

# Glob pattern for multiple files
for tree, match in treesearch.search("data/*.conllu", pattern):
    verb = tree.word(match["V"])
    print(f"{verb.form}: {tree.sentence_text}")

# Or use the object-oriented API
treebank = treesearch.load("data/*.conllu")
for tree, match in treebank.search(pattern):
    verb = tree.word(match["V"])
    print(f"{verb.form}: {tree.sentence_text}")

Pattern Language

Patterns specify structural constraints on dependency trees:

MATCH {
    Verb [upos="VERB" & lemma="help"];
    Obj [upos="NOUN"];
    Verb -[obj]-> Obj;
}

Node constraints: upos, xpos, lemma, form, deprel, feats.* (morphological features), misc.* (miscellaneous features); values are "literals" or /regexes/, combined with &, |, !=, and parentheses

Edge constraints: -> (child), -[label]-> (labeled edge), -/regex/-> (regex edge), !-> (negative), !-[label]-> (negative labeled), !-/regex/-> (negative regex)

Precedence: < (immediately precedes), << (precedes)

EXCEPT blocks: Reject matches where a condition is true (negative existential)

OPTIONAL blocks: Extend matches with additional bindings if possible

Data Format

Reads treebanks in CoNLL-U format. Supports plain text (.conllu), gzip-compressed (.conllu.gz), and zstd-compressed files (.conllu.zst) with automatic decompression.

Documentation

• API.md - Complete Python API reference
• RELEASING.md - CI workflows and release process (maintainers)
• GitHub repository - Source code and issue tracker

License

MIT

Citation

If you use Treesearch in your research, please cite:

@software{treesearch,
  author = {Malouf, Robert},
  title = {Treesearch: Pattern matching for dependency treebanks},
  year = {2025},
  url = {https://github.com/rmalouf/treesearch}
}