Update README.md

README.md

@@ -9,4 +9,131 @@ base_model:
 - HooshvareLab/bert-base-parsbert-uncased
 pipeline_tag: text-classification
 library_name: transformers
----
+---
+# Model Card for aref-j/emotion-classifier-bert-fa-v1
+<!-- Provide a quick summary of what the model is/does. -->
+This is a fine-tuned BERT model for classifying emotions in Persian text, specifically detecting 6 emotion categories: ANGRY, FEAR, HAPPY, HATE, SAD, SURPRISE. It was developed using a merged dataset of Persian emotion corpora and is designed for applications like sentiment analysis on Persian tweets.
+
+## Model Details
+### Model Description
+<!-- Provide a longer summary of what this model is. -->
+This model is a fine-tuned version of ParsBERT (HooshvareLab/bert-base-parsbert-uncased) for emotion classification in Persian text. It uses a BERT base architecture with a sequence classification head to predict one of six emotion labels from input text. The model addresses class imbalance through weighted cross-entropy loss and was trained on a combined dataset of Persian tweets and short texts.
+- **Developed by:** Aref Jafary
+- **Model type:** Text classification (fine-tuned BERT)
+- **Language(s) (NLP):** Persian (fa)
+- **License:** MIT
+- **Finetuned from model:** HooshvareLab/bert-base-parsbert-uncased
+### Model Sources [optional]
+<!-- Provide the basic links for the model. -->
+- **Repository:** https://github.com/ArefJafary/Persian-Emotion-Classification-BERT
+- **Paper [optional]:** Not available
+- **Demo [optional]:** Not available
+## Uses
+<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
+### Direct Use
+<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+The model can be used directly for inferring emotions from Persian text inputs, such as tweets or short messages, via the Hugging Face Transformers pipeline. It is suitable for applications in social media monitoring, customer feedback analysis, or psychological text analysis in Persian-speaking contexts.
+### Downstream Use [optional]
+<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
+The model can be further fine-tuned for specific downstream tasks like multi-label emotion detection or integrated into larger NLP systems for Persian language processing.
+### Out-of-Scope Use
+<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+The model is not intended for use in non-Persian languages, multi-label classification, or real-time high-stakes applications without further validation. It may not perform well on formal Persian text, dialects, or noisy data beyond tweets. Misuse could include biased emotional profiling or surveillance without ethical considerations.
+## Bias, Risks, and Limitations
+<!-- This section is meant to convey both technical and sociotechnical limitations. -->
+The model may inherit biases from the training datasets, which are primarily sourced from social media (tweets), potentially reflecting cultural, demographic, or topical biases in Persian online content. It handles 6 emotions but may struggle with nuanced or mixed emotions. Performance is evaluated on a held-out set, but real-world generalization could vary. Class imbalance in emotions like HATE or SURPRISE might affect minority class predictions.
+### Recommendations
+<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
+Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. Evaluate the model on your specific dataset before deployment. Consider debiasing techniques or additional data for underrepresented emotions. Use ethically and transparently, especially in sensitive applications.
+## How to Get Started with the Model
+Use the code below to get started with the model.
+```python
+from transformers import AutoTokenizer, AutoModelForSequenceClassification, pipeline
+
+model_name = "aref-j/emotion-classifier-bert-fa-v1"
+
+# Load tokenizer and model
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+model = AutoModelForSequenceClassification.from_pretrained(model_name)
+
+# Create the classification pipeline
+classifier = pipeline("text-classification", model=model, tokenizer=tokenizer)
+
+# Example usage
+result = classifier("چه هوای زیبایی امروز است")
+print(result)  # e.g. [{'label': 'HAPPY', 'score': 0.99}]
+```
+## Training Details
+### Training Data
+<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
+The model was trained on a merged dataset from three Persian emotion corpora:
+- **ArmanEmo**: Over 7,000 Persian sentences labeled for 7 emotions. [Paper](https://arxiv.org/abs/2207.11808), [GitHub](https://github.com/Arman-Rayan-Sharif/arman-text-emotion)
+- **EmoPars**: 30,000 Persian tweets labeled with 6 basic emotions (Anger, Fear, Happiness, Sadness, Hatred, Wonder). [Paper](https://aclanthology.org/2021.ranlp-srw.23/), [GitHub](https://github.com/nazaninsbr/Persian-Emotion-Detection)
+- **ShortPersianEmo**: 5,472 short Persian texts labeled for 5 emotions (angry, sad, fear, happy, neutral). [GitHub](https://github.com/vkiani/ShortPersianEmo), [Paper](https://jad.shahroodut.ac.ir/article_3030_8c27fa0d8cb5bfba01e6835a469d3072.pdf)
+
+Datasets were standardized, cleaned (normalization with Parsivar, removal of URLs, mentions, emojis, etc.), deduplicated, and split into 90% train / 10% validation, with ArmanEmo held out for testing.
+### Training Procedure
+<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
+#### Preprocessing [optional]
+Text was normalized using Parsivar, with character mapping, diacritic removal, and stripping of URLs, mentions, hashtags, emojis, punctuation, digits, and extra spaces. Multi-label instances in EmoPars were converted to single-label via dominant label.
+#### Training Hyperparameters
+- **Training regime:** fp32 (assumed, not specified)
+- Batch size: 32
+- Epochs: 6
+- Learning rate: 1e-5
+- Optimizer: Not specified (default Hugging Face Trainer)
+- Loss: Weighted cross-entropy to handle class imbalance
+- Early stopping: After 2 epochs without validation loss improvement
+#### Speeds, Sizes, Times [optional]
+Not specified.
+## Evaluation
+<!-- This section describes the evaluation protocols and provides the results. -->
+### Testing Data, Factors & Metrics
+#### Testing Data
+<!-- This should link to a Dataset Card if possible. -->
+Held-out ArmanEmo test set.
+#### Factors
+<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
+Evaluation disaggregated by emotion classes (ANGRY, FEAR, HAPPY, HATE, SAD, SURPRISE).
+#### Metrics
+<!-- These are the evaluation metrics being used, ideally with a description of why. -->
+Accuracy (overall correct predictions), Macro F1-score (average F1 across classes, treating all equally), Precision, Recall, and Confusion Matrix.
+### Results
+- Test Accuracy: 70.88%
+- Macro F1-Score: 66.35%
+
+Detailed per-class metrics and confusion matrix available in the repository.
+#### Summary
+The model shows robust performance on unseen Persian tweet data, with good generalization across emotions.
+
+
+## Technical Specifications [optional]
+### Model Architecture and Objective
+BERT base model with a sequence classification head for multi-class emotion prediction.
+#### Hardware
+T4.
+#### Software
+Hugging Face Transformers library, Python.
+
+
+**BibTeX:**
+```
+@misc{jafary2023persianemotion,
+  author = {Aref Jafary},
+  title = {Persian Emotion Classification with BERT},
+  year = {2023},
+  publisher = {GitHub},
+  journal = {GitHub repository},
+  howpublished = {\url{https://github.com/ArefJafary/Persian-Emotion-Classification-BERT}}
+}
+```
+
+**APA:**
+Jafary, A. (2023). Persian Emotion Classification with BERT [Repository]. GitHub. https://github.com/ArefJafary/Persian-Emotion-Classification-BERT
+## Glossary
+<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
+- **ParsBERT**: A BERT model pre-trained on Persian text.
+- **Weighted Cross-Entropy**: Loss function that assigns higher weights to underrepresented classes.
+
+## Model Card Contact
+Contact via GitHub: https://github.com/ArefJafary