Update README.md

README.md

@@ -15,12 +15,14 @@ tags:
 
 # BERT Sentiment Classifier
 
-This repository contains a fine-tuned BERT model for **English movie review sentiment classification**. The model classifies text into two sentiment categories:
+A fine-tuned **BERT Base Uncased** model for English movie review sentiment classification.
 
-- **POSITIVE** — The review expresses a positive opinion.
-- **NEGATIVE** — The review expresses a negative opinion.
+This model classifies movie reviews into two sentiment categories:
 
-The model is based on the pretrained `google-bert/bert-base-uncased` architecture and was fine-tuned using the IMDb movie reviews dataset.
+- **POSITIVE (1):** The review expresses a positive opinion.
+- **NEGATIVE (0):** The review expresses a negative opinion.
+
+The model was fine-tuned using the IMDb Movie Reviews dataset and evaluated on a separate test set containing 2,000 examples.
 
 ## Model Details
 
@@ -28,7 +30,7 @@ The model is based on the pretrained `google-bert/bert-base-uncased` architectur
 |---|---|
 | Model architecture | BERT Base Uncased |
 | Base model | `google-bert/bert-base-uncased` |
-| Task | Sentiment Classification |
+| Task | Binary Sentiment Classification |
 | Number of classes | 2 |
 | Positive label | 1 |
 | Negative label | 0 |
@@ -40,7 +42,7 @@ The model is based on the pretrained `google-bert/bert-base-uncased` architectur
 
 The model was fine-tuned using the [IMDb Movie Reviews Dataset](https://huggingface.co/datasets/stanfordnlp/imdb).
 
-The notebook uses the following data split:
+The notebook uses the following dataset split:
 
 | Dataset | Number of samples |
 |---|---:|
@@ -49,20 +51,20 @@ The notebook uses the following data split:
 | Testing | 2,000 |
 | **Total** | **11,000** |
 
-The IMDb dataset contains movie reviews with binary sentiment labels:
+The dataset contains English movie reviews with binary sentiment labels:
 
 - `0`: Negative
 - `1`: Positive
 
-The training data is used to fine-tune the model, validation data is used to evaluate training progress and select the best checkpoint, and the separate test set is used for final evaluation.
+The training set is used to fine-tune the model, the validation set is used to monitor training and evaluate checkpoints, and the test set is used for final performance evaluation.
 
 ## Training Configuration
 
-The model was fine-tuned using the following configuration:
+The model was fine-tuned for three epochs using the following configuration:
 
 | Parameter | Value |
 |---|---|
-| Base learning model | BERT Base Uncased |
+| Base model | BERT Base Uncased |
 | Epochs | 3 |
 | Batch size | 16 |
 | Learning rate | 2e-5 |
@@ -71,32 +73,101 @@ The model was fine-tuned using the following configuration:
 | Maximum sequence length | 192 |
 | Random seed | 42 |
 | Best checkpoint metric | Validation accuracy |
+| Training framework | PyTorch |
+
+A two-class classification head was added to the pretrained BERT encoder and fine-tuned for sentiment prediction.
+
+## Training Results
+
+The following table shows the training progress across all three epochs.
+
+| Epoch | Training Loss | Validation Loss | Accuracy | Precision | Recall | F1-score |
+|---|---:|---:|---:|---:|---:|---:|
+| 1 | 0.376433 | 0.259453 | 0.896000 | 0.919321 | 0.867735 | 0.892784 |
+| 2 | 0.166479 | 0.358983 | 0.884000 | 0.894845 | 0.869739 | 0.882114 |
+| 3 | 0.134408 | 0.445110 | 0.894000 | 0.887574 | 0.901804 | 0.894632 |
+
+Training loss decreased throughout training. However, validation loss increased after the first epoch. This may indicate overfitting, even though the validation accuracy remained relatively stable.
+
+## Final Validation Results
 
-The pretrained BERT encoder provides contextual language representations. A two-class classification head is added and fine-tuned for sentiment prediction.
+The final validation evaluation produced the following results:
+
+| Metric | Result |
+|---|---:|
+| Validation Loss | 0.259079 |
+| Accuracy | **89.70%** |
+| Precision | 91.95% |
+| Recall | 86.97% |
+| F1-score | **89.39%** |
+
+## Final Test Results
+
+The final evaluation was performed on a separate test set containing **2,000 movie reviews**, with 1,000 Negative and 1,000 Positive examples.
+
+| Metric | Result |
+|---|---:|
+| Test Loss | 0.259910 |
+| Accuracy | **88.80%** |
+| Precision | 91.54% |
+| Recall | 85.50% |
+| F1-score | **88.42%** |
 
-## Evaluation
+The model correctly classified 1,776 out of 2,000 test examples.
 
-The notebook evaluates the model using:
+### Classification Report
 
-- **Accuracy:** Measures the percentage of correctly classified reviews.
-- **Precision:** Measures how many predicted positive examples are actually positive.
-- **Recall:** Measures how many actual positive examples the model identifies.
-- **F1-score:** Combines precision and recall.
-- **Confusion Matrix:** Shows correct and incorrect predictions for both classes.
+| Class | Precision | Recall | F1-score | Support |
+|---|---:|---:|---:|---:|
+| Negative | 0.8640 | 0.9210 | 0.8916 | 1,000 |
+| Positive | 0.9154 | 0.8550 | 0.8842 | 1,000 |
+| **Macro Average** | **0.8897** | **0.8880** | **0.8879** | **2,000** |
+| **Weighted Average** | **0.8897** | **0.8880** | **0.8879** | **2,000** |
 
-Final test metrics are produced by running the evaluation cells in the notebook. No numerical performance results are stated here because they depend on the actual training run.
+### Confusion Matrix
+
+The confusion matrix shows the actual and predicted sentiment labels.
+
+| Actual / Predicted | Predicted Negative | Predicted Positive |
+|---|---:|---:|
+| Actual Negative | 921 | 79 |
+| Actual Positive | 145 | 855 |
+
+**Interpretation:**
+
+- 921 Negative reviews were correctly classified.
+- 855 Positive reviews were correctly classified.
+- 79 Negative reviews were incorrectly classified as Positive.
+- 145 Positive reviews were incorrectly classified as Negative.
+
+The model achieved higher recall for Negative reviews (92.10%) than Positive reviews (85.50%).
+
+## Model Architecture
+
+This project uses an **encoder-only transformer architecture**.
+
+BERT reads the input text and creates contextual representations of its tokens. The classification head uses these representations to predict the sentiment of the complete review.
+
+The model follows this general workflow:
+
+1. Receive an English movie review.
+2. Tokenize the input text.
+3. Pass the tokens through the pretrained BERT encoder.
+4. Generate classification logits.
+5. Apply softmax to obtain class probabilities.
+6. Return the predicted sentiment and confidence score.
 
 ## Usage
 
 You can load this model directly using Hugging Face Transformers.
 
-### Install dependencies
+### Install Dependencies
 
 ```bash
 pip install transformers torch
 ```
 
-### Load the model
+### Load the Model
 
 ```python
 import torch
@@ -111,7 +182,7 @@ model = AutoModelForSequenceClassification.from_pretrained(MODEL_NAME)
 model.eval()
 ```
 
-### Make a prediction
+### Make a Prediction
 
 ```python
 def predict_sentiment(text):
@@ -151,16 +222,16 @@ result = predict_sentiment(
 print(result)
 ```
 
-### Example predictions
+### Example Predictions
 
-| Input review | Expected sentiment |
+| Input Review | Expected Sentiment |
 |---|---|
 | This movie was absolutely wonderful! | POSITIVE |
 | This movie was terrible and boring. | NEGATIVE |
 | I loved every moment of this film. | POSITIVE |
 | I hated this movie. It was a waste of time. | NEGATIVE |
 
-These are illustrative examples, not guaranteed outputs for every sentence.
+These examples are illustrative and are not guaranteed predictions.
 
 ## Applications
 
@@ -180,6 +251,7 @@ This model can be integrated into:
 - It may not perform equally well on other domains, such as product reviews, news, or social media.
 - Sarcasm, irony, ambiguous language, and mixed sentiment can be difficult to classify.
 - Confidence scores are model probabilities, not guarantees of correctness.
+- Validation loss increased after the first epoch, suggesting possible overfitting.
 
 ## Technologies Used
 
@@ -188,7 +260,7 @@ This model can be integrated into:
 - Hugging Face Transformers
 - Hugging Face Datasets
 - Scikit-learn
-- IMDb Dataset
+- IMDb Movie Reviews Dataset
 - Google BERT Base Uncased
 
 ## Training Notebook
@@ -205,10 +277,16 @@ The training notebook includes:
 8. Custom sentiment prediction.
 9. Saving and uploading the model to Hugging Face.
 
-## Model Repository
+## Project Integration
+
+This model is also used as the sentiment classification component in my NLP Analysis Studio application, alongside a separate decoder-only Qwen model for Named Entity Recognition.
 
-**Hugging Face:** https://huggingface.co/ullahhafeez321/bert-sentiment-classifier
+- **Live Application:** https://sentimentclassifynamedentitymodels.streamlit.app/
+- **GitHub Repository:** https://github.com/ullahhafeez321/SentimentClassify_NamedEntityModels
+- **BERT Model:** https://huggingface.co/ullahhafeez321/bert-sentiment-classifier
+- **Qwen NER Model:** https://huggingface.co/ullahhafeez321/Qwen-NER-Decoder
 
 ## License
 
-MIT License.
+This project is released under the MIT License.
+