|
|
--- |
|
|
license: mit |
|
|
tags: |
|
|
- rwanda |
|
|
- gender-prediction |
|
|
- name-classification |
|
|
- scikit-learn |
|
|
- logistic-regression |
|
|
- low-resource |
|
|
- african-names |
|
|
- nlp |
|
|
model-index: |
|
|
- name: RwandaNameGenderModel |
|
|
results: [] |
|
|
--- |
|
|
|
|
|
# RwandaNameGenderModel |
|
|
|
|
|
**RwandaNameGenderModel** is a machine learning model that predicts gender based on Rwandan names — whether a **first name**, **surname**, or **both in any order**. It uses a character-level n-gram approach with a logistic regression classifier to provide fast, interpretable, and highly accurate predictions — achieving **96%+ accuracy** on both validation and test sets. |
|
|
|
|
|
--- |
|
|
|
|
|
## 🧠 Model Overview |
|
|
|
|
|
- **Type:** Classic ML (Logistic Regression) |
|
|
- **Input:** Rwandan name (flexible: single or full name) |
|
|
- **Vectorization:** Character-level n-grams (2–3 chars) |
|
|
- **Framework:** scikit-learn |
|
|
- **Training Set:** 66,735 names (out of 83,419) |
|
|
- **Validation/Test Accuracy:** ~96.6% |
|
|
|
|
|
--- |
|
|
|
|
|
## 📁 Project Structure |
|
|
|
|
|
``` |
|
|
RwandaNameGenderModel/ |
|
|
├── dataset/ |
|
|
│ └── rwandan_names.csv |
|
|
├── model/ |
|
|
│ ├── logistic_model.joblib |
|
|
│ └── vectorizer.joblib |
|
|
├── logs/ |
|
|
│ └── metrics_log.txt |
|
|
├── train.py |
|
|
├── inference.py |
|
|
├── README.md |
|
|
└── requirements.txt |
|
|
``` |
|
|
|
|
|
--- |
|
|
|
|
|
## 🚀 Quickstart |
|
|
|
|
|
### 1. Install requirements |
|
|
```bash |
|
|
pip install -r requirements.txt |
|
|
``` |
|
|
|
|
|
### 2. Train the model |
|
|
```bash |
|
|
python train.py |
|
|
``` |
|
|
|
|
|
### 3. Predict gender from a name using script |
|
|
Run interactive inference with: |
|
|
```bash |
|
|
python inference.py |
|
|
``` |
|
|
|
|
|
### 4. Predict gender from a name using Python code |
|
|
```python |
|
|
from joblib import load |
|
|
|
|
|
model = load("model/logistic_model.joblib") |
|
|
vectorizer = load("model/vectorizer.joblib") |
|
|
|
|
|
def predict_gender(name): |
|
|
X = vectorizer.transform([name]) |
|
|
return model.predict(X)[0] |
|
|
|
|
|
# Flexible input: first name, surname, or both (any order) |
|
|
predict_gender("Gabriel") # Output: "male" |
|
|
predict_gender("Baziramwabo") # Output: "male" |
|
|
predict_gender("Baziramwabo Gabriel") # Output: "male" |
|
|
predict_gender("Gabriel Baziramwabo") # Output: "male" |
|
|
``` |
|
|
|
|
|
--- |
|
|
|
|
|
## 📈 Performance |
|
|
|
|
|
| Dataset | Accuracy | Precision | Recall | F1-Score | |
|
|
|------------|----------|-----------|--------|----------| |
|
|
| Validation | 96.72% | 96.90% | 96.53% | 96.72% | |
|
|
| Test | 96.64% | 96.94% | 96.34% | 96.64% | |
|
|
|
|
|
Metrics are logged in both `logs/metrics_log.txt` and TensorBoard format. |
|
|
|
|
|
--- |
|
|
|
|
|
## 🌍 Use Cases |
|
|
|
|
|
- Demographic analysis |
|
|
- Smart form processing |
|
|
- Voice assistant personalization |
|
|
- NLP preprocessing for Rwandan corpora |
|
|
|
|
|
--- |
|
|
|
|
|
## 🛡️ Ethical Note |
|
|
|
|
|
This model predicts binary gender based on patterns in names and may not reflect self-identified gender. It should not be used in sensitive contexts without consent. |
|
|
|
|
|
--- |
|
|
|
|
|
## 📄 License |
|
|
|
|
|
This project is maintained by [Gabriel Baziramwabo](https://benax.rw) and is open for research and educational use. For commercial use, please contact the author. |
|
|
|
|
|
--- |
|
|
|
|
|
## 🤝 Contributing |
|
|
|
|
|
We welcome improvements and multilingual extensions. Fork this repo, improve, and submit a PR! |
|
|
|
|
|
--- |
|
|
|
|
|
## 🔗 Links |
|
|
|
|
|
- [Benax Technologies](https://benax.rw) |
|
|
|
