calamanCy: NLP pipelines for Tagalog

calamanCy is a Tagalog natural language preprocessing framework made with spaCy. Its goal is to provide pipelines and datasets for downstream NLP tasks. This repository contains material for using calamanCy, reproduction of results, and guides on usage.

calamanCy takes inspiration from other language-specific spaCy Universe frameworks such as DaCy, huSpaCy, and graCy. The name is based from calamansi, a citrus fruit native to the Philippines and used in traditional Filipino cuisine.

🔧 Installation

To get started with calamanCy, simply install it using pip by running the following line in your terminal:

pip install calamanCy

Development

If you are developing calamanCy, first clone the repository:

git clone git@github.com:ljvmiranda921/calamanCy.git

Then, create a virtual environment and install the dependencies:

python -m venv venv
venv/bin/pip install -e .  # requires pip>=23.0
venv/bin/pip install .[dev]

# Activate the virtual environment
source venv/bin/activate

or alternatively, use make dev.

Running the tests

We use pytest as our test runner:

python -m pytest --pyargs calamancy

👩‍💻 Usage

To use calamanCy you first have to download either the medium, large, or transformer model. To see a list of all available models, run:

import calamancy
from model in calamancy.models():
    print(model)

# ..
# tl_calamancy_md-0.1.0
# tl_calamancy_lg-0.1.0
# tl_calamancy_trf-0.1.0

To download and load a model, run:

nlp = calamancy.load("tl_calamancy_md-0.1.0")
doc = nlp("Ako si Juan de la Cruz")

The nlp object is an instance of spaCy's Language class and you can use it as any other spaCy pipeline. You can also access these models on Hugging Face 🤗.

📦 Models and Datasets

calamanCy provides Tagalog models and datasets that you can use in your spaCy pipelines. You can download them directly or use the calamancy Python library to access them. The training procedure for each pipeline can be found in the models/ directory. They are further subdivided into versions. Each folder is an instance of a spaCy project.

Here are the models for the latest release:

📓 API

The calamanCy library contains utility functions that help you load its models and infer on your text. You can think of these functions as "syntactic sugar" to the spaCy API. We highly recommend checking out the spaCy Doc object, as it provides the most flexibility.

Loaders

The loader functions provide an easier interface to download calamanCy models. These models are hosted on HuggingFace so you can try them out first before downloading.

function get_latest_version

Return the latest version of a calamanCy model.

function models

Get a list of valid calamanCy models.

function load

Load a calamanCy model as a spaCy language pipeline.

Inference

Below are lightweight utility classes for users who are not familiar with spaCy's primitives. They are only useful for inference and not for training. If you wish to train on top of these calamanCy models (e.g., text categorization, task-specific NER, etc.), we advise you to follow the standard spaCy training workflow.

General usage: first, you need to instantiate a class with the name of a model. Then, you can use the __call__ method to perform the prediction. The output is of the type Iterable[Tuple[str, Any]] where the first part of the tuple is the token and the second part is its label.

method EntityRecognizer.__call__

Perform named entity recognition (NER). By default, it uses the v0.1.0 of TLUnified-NER with the following entity labels: PER (Person), ORG (Organization), LOC (Location).

method Tagger.__call__

Perform parts-of-speech tagging. It uses the annotations from the TRG and Ugnayan treebanks with the following tags: ADJ, ADP, ADV, AUX, DET, INTJ, NOUN, PART, PRON, PROPN, PUNCT, SCONJ, VERB.

method Parser.__call__

Perform syntactic dependency parsing. It uses the annotations from the TRG and Ugnayan treebanks.

📝 Reporting Issues

If you have questions regarding the usage of calamanCy, bug reports, or just want to give us feedback after giving it a spin, please use the Issue tracker. Thank you!

📜 Citation

If you are citing the open-source software, please use:

@misc{miranda2023calamancy,
    title={{calamanCy: A Tagalog Natural Language Processing Toolkit}}, 
    author={Lester James V. Miranda},
    year={2023},
    eprint={2311.07171},
    archivePrefix={arXiv},
    primaryClass={cs.CL}
}

If you are citing the NER dataset, please use:

@misc{miranda2023developing,
    title={{Developing a Named Entity Recognition Dataset for Tagalog}}, 
    author={Lester James V. Miranda},
    year={2023},
    eprint={2311.07161},
    archivePrefix={arXiv},
    primaryClass={cs.CL}
}