Upload README.md

README.md

@@ -0,0 +1,148 @@
+---
+library_name: adapter-transformers
+tags:
+  - adapters
+  - mad-x
+  - emotion-detection
+  - multi-label-classification
+  - multilingual
+  - low-resource
+  - xlm-roberta
+base_model:
+  - FacebookAI/xlm-roberta-large
+  - UBC-NLP/serengeti-E250
+datasets:
+  - brighter-dataset/BRIGHTER-emotion-categories
+language:
+  - en
+  - hi
+  - ru
+  - ha
+  - rw
+  - su
+  - yo
+  - vmw
+  - pcm
+---
+
+# All Emotion Adapters: MAD-X adapters for multilingual emotion detection
+
+Trained MAD-X adapters from my MSc dissertation, **"Multilingual Models Have Feelings Too?"**
+(MSc Applied Artificial Intelligence, University of Huddersfield, 2026).
+
+They detect six emotions in text as a **multi-label** task (a text can have several emotions, or none):
+
+`anger, disgust, fear, joy, sadness, surprise`
+
+They cover 9 languages across three resource levels, from the BRIGHTER dataset (SemEval-2025 Task 11):
+
+| Tier | Languages (code) |
+|---|---|
+| High resource | English (`eng`), Hindi (`hin`), Russian (`rus`) |
+| Mid resource | Hausa (`hau`), Kinyarwanda (`kin`), Sundanese (`sun`) |
+| Low resource | Yoruba (`yor`), Emakhuwa (`vmw`), Nigerian Pidgin (`pcm`) |
+
+- **Dissertation code and results:** https://github.com/Momina0398/EmotionDetection
+- **API that serves these adapters (FastAPI, Docker, CI):** https://github.com/Momina0398/emotion-api
+
+## What is in this repo
+
+```
+adapters_xlmr_weighted/     47 runs on xlm-roberta-large (all 9 languages)
+adapters_serengeti/         26 runs on UBC-NLP/serengeti-E250 (5 African languages)
+lang_sun_lapt/              Sundanese language adapter, extra pre-training (LAPT)
+lang_vmw_lapt/              Emakhuwa language adapter, LAPT, xlm-roberta-large
+lang_vmw_lapt_serengeti/    Emakhuwa language adapter, LAPT, SERENGETI
+```
+
+Each run folder is named `<lang>_track_<a|c>_<C1|C2|C3>` and contains three parts:
+
+```
+lang/   language adapter (invertible MAD-X language adapter)
+task/   emotion task adapter ("emotion_task")
+head/   6-label multi-label classification head
+```
+
+**Track**
+- `track_a`: target-language training data was available (supervised)
+- `track_c`: no target-language training data (cross-lingual transfer only)
+
+**Source configuration** (which languages the task adapter was trained on)
+- `C1`: all other BRIGHTER languages
+- `C2`: languages in the same top-level family as the target
+- `C3`: languages in the same sub-family as the target
+
+Some combinations are missing on purpose. When a family or sub-family pool was too small to form a valid training set, that run was not created rather than filled with an invented pool.
+
+## How to use
+
+```python
+# pip install adapters==1.3.0 transformers torch huggingface_hub
+import torch
+from huggingface_hub import snapshot_download
+from transformers import AutoTokenizer
+from adapters import AutoAdapterModel
+import adapters.composition as ac
+
+REPO = "MominaMahmood/All-Emotion-Adapters"
+RUN = "adapters_xlmr_weighted/rus_track_a_C1"
+BASE = "xlm-roberta-large"            # use "UBC-NLP/serengeti-E250" for adapters_serengeti runs
+LABELS = ["anger", "disgust", "fear", "joy", "sadness", "surprise"]
+
+path = snapshot_download(REPO, allow_patterns=[f"{RUN}/*"])
+run = f"{path}/{RUN}"
+
+tok = AutoTokenizer.from_pretrained(BASE)
+model = AutoAdapterModel.from_pretrained(BASE)
+model.load_adapter(f"{run}/lang", load_as="lang")
+model.load_adapter(f"{run}/task", load_as="emotion_task")
+model.load_head(f"{run}/head")
+model.set_active_adapters(ac.Stack("lang", "emotion_task"))
+model.eval()
+
+texts = ["Я так рада тебя видеть!"]
+enc = tok(texts, padding=True, truncation=True, max_length=256, return_tensors="pt")
+with torch.no_grad():
+    probs = torch.sigmoid(model(**enc).logits)[0].tolist()
+print({e: round(p, 3) for e, p in zip(LABELS, probs)})
+print("labels:", [e for e, p in zip(LABELS, probs) if p >= 0.5])
+```
+
+Use a threshold of **0.5** per label, as in training and evaluation.
+
+## Training details
+
+| Setting | Value |
+|---|---|
+| Architecture | MAD-X: language adapter + task adapter stacked on a frozen backbone |
+| Backbones | `xlm-roberta-large`, `UBC-NLP/serengeti-E250` |
+| Adapter configs | `SeqBnInvConfig` (language), `SeqBnConfig` (task), reduction factor 16 |
+| Loss | Binary cross-entropy with per-label positive class weights ("weighted") |
+| Learning rate | 5e-5 |
+| Batch size | 8 |
+| Max epochs | 10, early stopping with patience 3 on the dev split |
+| Max sequence length | 256 |
+| Library | `adapters` 1.3.0 |
+| LAPT | Extra masked-language-model training of the language adapter for Emakhuwa (Emakhuwa text) and Sundanese (Javanese and Indonesian text) |
+
+Model selection used the validation split only. Full results, significance tests and per-language analysis are in the dissertation repo linked above.
+
+## Limitations
+
+- **English has no disgust labels** in the BRIGHTER training data, so English runs cannot learn that emotion. Treat English disgust scores as meaningless.
+- **Single random seed.** Results do not capture variation between training runs.
+- **Emotion labels are dataset annotations**, not ground truth about how a writer feels.
+- Performance on the low-resource languages (especially Emakhuwa and Nigerian Pidgin) is well below the high-resource languages.
+- A main finding of the dissertation is that **sub-family transfer (C3) did not beat broader source pools**. For most languages, pick C1 or C2 first.
+- **Not for high-stakes decisions about individuals** (for example health, hiring or policing) without expert human review.
+
+## Citation
+
+If you use these adapters, please cite the dissertation:
+
+```
+Siddiq, M. M. (2026). Multilingual Models Have Feelings Too? Culturally Aware
+Sub-Family Transfer for Emotion Detection. MSc dissertation, University of Huddersfield.
+```
+
+Please also cite the BRIGHTER dataset and SemEval-2025 Task 11 papers.