dantesfai/Tigrinya_Multiclass_Text_Classification

# Tigrinya Multiclass Text Classification Experiment (Reproducible Research) This repository contains a **reproducible** pipeline for transformer-based text classification, complete with training, evaluation, plots, and optional SHAP/LIME explainability. It uses the Hugging Face ecosystem (`transformers`, `datasets`, `accelerate`) and standard ML tooling. ## Quick Start (Step-by-Step) ### 1) Clone and set up a virtual environment ```bash git clone .git cd text-classification-experiment # Create and activate a virtual environment (choose one) python -m venv .venv && source .venv/bin/activate # macOS/Linux # or python -m venv .venv && .venv\Scripts\activate # Windows PowerShell # Install dependencies pip install --upgrade pip pip install -r requirements.txt ``` > **GPU:** If you have an NVIDIA GPU, follow PyTorch's installation selector for a CUDA-enabled build before installing requirements: pytorch.org ### 2) Prepare your data Place your CSV in `data/` and make sure it has **three columns**: - `cleaned_text` (string) - `translit_text` (string) - `Category` (class label) Example: ``` data/ └── preprocessed_news.csv ``` ### 3) (Optional) Prepare stopwords If you have a stopwords file, place it at e.g. `data/stopwords.txt` (one token per line). ### 4) Prepare your models directory Place one or more Hugging Face **model folders** in `models/`. Each folder should be a standard HF directory (i.e., it contains `config.json`, `pytorch_model.bin` or `safetensors`, tokenizer files, etc.). Example: ``` models/ ├── distilbert-base-uncased/ └── bert-base-uncased/ ``` > You can also point to local folders containing `AutoTokenizer`/`AutoModel*` artifacts downloaded via `from_pretrained`. ### 5) Run an experiment Run via the CLI entrypoint: ```bash # minimal example tcexp --dataset_path data/preprocessed_news.csv --plm_dir models --output_dir results # with stopwords and custom tokenizer tcexp --dataset_path data/preproce …