AmirhosseinHonardoust/Sentiment-Analysis-BERT
AmirhosseinHonardoust/Sentiment-Analysis-BERT has 37 GitHub stars and 0 forks. GitHot measured 0 stars in 24 hours, 0 in 7 days, and 0 in 15 days. Last checked 2026-11-21 19:14 UTC. Last push 2026-09-09.
What you can do
- Shared preprocessing pipeline producing consistent train.csv / val.csv / test.csv splits
- BERT fine-tuning via Hugging Face Transformers (bert-base-uncased)
- BiLSTM baseline for a fast, pretrained-weight-free comparison
- Unified evaluation, evaluate.py auto-detects BERT vs. LSTM checkpoints
측정된 스타 증가
- in 24h
- 0
- in 7 days
- 0
- in 15 days
- 0
- in 1 month
- 기록 수집 중
서로 겹치는 기간의 순증가량이며 일별 합계가 아닙니다. 측정값이 없으면 비워 둡니다. 스타는 관심도를 나타내며 품질을 보장하지 않습니다.
소개
End-to-end sentiment analysis of tweets using BERT. Includes preprocessing, training, and evaluation with classification reports, confusion matrices, ROC curves, and word clouds. Demonstrates fine-tuning of transformer models for text classification with modular, reproducible code.
머신러닝README.md
OriginalA deep learning project for sentiment classification of tweets, built around fine-tuning BERT (bert-base-uncased) with a lightweight BiLSTM baseline for comparison, plus reproducible preprocessing, evaluation reporting, and single-text inference.
Note on data:
data/tweets_sample.csvis a ~15-row illustrative sample, not a real training set. It is enough to exercise the full pipeline end-to-end, but the metrics and plots checked intooutputs/are demo artifacts, not a benchmark of real model quality. Swap in a real labeled dataset (sametext,labelschema) for meaningful results.
Table of Contents
- Project Overview
- What This Project Does
- Key Features
- System Workflow
- Project Structure
- Installation
- Preprocess Data
- Train BERT
- Train LSTM
- Evaluate
- Predict
- Results
- Development and Testing
- Requirements
- Known Limitations
- Next Steps
- Author
- License
Project Overview
Sentiment classification is often demonstrated as a single accuracy number on a clean dataset, which hides most of the engineering that makes a model usable in practice: consistent preprocessing, a reproducible train/val/test split, an evaluation report that generalizes across model types, and a way to sanity-check predictions on raw text.
This project fine-tunes a transformer model on tweet sentiment (negative, neutral, positive) and pairs it with a lightweight BiLSTM baseline trained from scratch, so the two can be compared on identical data through the same evaluation entry point. It includes preprocessing, training for both model types, classification reports, confusion matrices, ROC curves, word clouds, and a CI-tested, offline-friendly test suite.
The goal is to show a modular, reproducible NLP pipeline rather than a single leaderboard score.
What This Project Does
This project can:
- Clean, tokenize, and split raw tweets into train/val/test sets
- Fine-tune
bert-base-uncasedon sentiment labels - Train a BiLSTM baseline as a lightweight, no-pretrained-weights alternative
- Evaluate either model through the same
evaluate.pyentry point, with checkpoint type auto-detected - Generate classification reports, confusion matrices, and ROC curves
- Generate word clouds for positive and negative predictions
- Track and visualize training and validation loss
- Classify one or more raw text strings directly, without a labeled CSV
- Run a full offline test suite in CI, including the BERT code path, without a live model download
Key Features
- Shared preprocessing pipeline producing consistent
train.csv/val.csv/test.csvsplits - BERT fine-tuning via Hugging Face Transformers (
bert-base-uncased) - BiLSTM baseline for a fast, pretrained-weight-free comparison
- Unified evaluation,
evaluate.pyauto-detects BERT vs. LSTM checkpoints - Classification reports, confusion matrices, and ROC curves for either model
- Word cloud generation for positive and negative predictions
- Single- or multi-text inference with
predict.py, same checkpoint auto-detection - Offline CI test suite, including a tiny randomly-initialized local BERT checkpoint fixture (
tests/conftest.py) so no network access or real download is required - Lint/format/type-check gate, Ruff, Black, and mypy, enforced in CI alongside pytest
- Dependabot-managed dependencies with a required full CI pass on every bump
System Workflow
Raw tweets (text, label)
↓
Preprocessing (clean, tokenize, split)
↓
train.csv / val.csv / test.csv
↓
BERT fine-tuning or BiLSTM baseline
↓
Evaluation (classification report, confusion matrix, ROC curve)
↓
Word clouds and training curves
↓
Single-text prediction (predict.py)
Project Structure
sentiment-analysis-bert/
│
├── .github/
│ ├── workflows/
│ │ └── ci.yml
│ └── dependabot.yml
│
├── data/
│ ├── tweets_sample.csv
│ ├── train.csv
│ ├── val.csv
│ └── test.csv
│
├── outputs/
│ ├── best_model_bert.pt
│ ├── best_model_lstm.pt
│ ├── confusion_matrix.png
│ ├── training_curves.png
│ ├── classification_report.txt
│ ├── wordcloud_negative.png
│ └── roc_curve.png
│
├── src/
│ ├── preprocess.py
│ ├── train_lstm.py
│ ├── train_bert.py
│ ├── bert_dataset.py
│ ├── evaluate.py
│ ├── predict.py
│ └── utils.py
│
├── tests/
│ └── conftest.py
│
├── README.md
├── CONTRIBUTING.md
├── LICENSE
├── pyproject.toml
├── requirements.txt
└── requirements-dev.txt
Installation
1. Clone the Repository
git clone https://github.com/AmirhosseinHonardoust/Sentiment-Analysis-BERT.git
cd Sentiment-Analysis-BERT
2. Create a Virtual Environment
On Windows CMD:
python -m venv .venv
.venv\Scripts\activate
On macOS/Linux:
python -m venv .venv
source .venv/bin/activate
3. Install Requirements
pip install -r requirements.txt
For development tools (Ruff, Black, mypy, pytest):
pip install -r requirements-dev.txt
Preprocess Data
Cleans and tokenizes the raw tweets, then splits them into train/val/test CSVs with the same text,label schema throughout.
python src/preprocess.py --input data/tweets_sample.csv --outdir data --val-size 0.15 --test-size 0.15
Train BERT
Fine-tunes bert-base-uncased on the training split, validating against val.csv.
python src/train_bert.py --train data/train.csv --val data/val.csv --outdir outputs/bert --epochs 3 --batch-size 16 --lr 2e-5 --model bert-base-uncased --max-len 128
Train LSTM
A lightweight BiLSTM baseline that needs no pretrained weights, useful for fast iteration or as a comparison point against BERT.
python src/train_lstm.py --train data/train.csv --val data/val.csv --outdir outputs/lstm --epochs 8 --batch-size 64 --lr 1e-3
Evaluate
Works for either model, evaluate.py auto-detects the checkpoint type from --checkpoint.
# BERT: point at the HF-format output directory (contains config.json)
python src/evaluate.py --test data/test.csv --checkpoint outputs/bert --outdir outputs/bert --wordclouds
# LSTM: point at the checkpoint file, or its containing directory
python src/evaluate.py --test data/test.csv --checkpoint outputs/lstm --outdir outputs/lstm --wordclouds
Generated outputs include:
outputs/classification_report.txt
outputs/confusion_matrix.png
outputs/roc_curve.png
outputs/training_curves.png
outputs/wordcloud_negative.png
Predict
Classify one or more texts directly, without a labeled CSV. Uses the same checkpoint auto-detection as evaluate.py.
python src/predict.py --checkpoint outputs/lstm --text "I love this!" --text "Broke after a week."
Results
- Classification Report:
outputs/classification_report.txt
| Confusion Matrix | ROC Curve |
|---|---|
![]() |
![]() |
| Analysis: Shows correct vs. incorrect predictions across the three sentiment classes on the held-out test set. | Analysis: Shows class separation across decision thresholds, read alongside the small sample size noted below. |
| Training Curves | Negative Wordcloud |
|---|---|
![]() |
![]() |
| Analysis: Training and validation loss over epochs, useful for spotting over/underfitting. | Analysis: Most frequent terms in negative predictions, generated with --wordclouds. |
The checked-in metrics and plots were generated from the ~15-row
tweets_sample.csvdemo data. They confirm the pipeline runs end-to-end, not that the model performs well, see Known Limitations.Image paths above are relative to the repo root (
outputs/...) and render on GitHub; they won't resolve if this file is viewed outside the repository.
Development and Testing
These four commands are exactly what CI runs on every push and pull request:
ruff check --select E,F,I,B,SIM,UP --line-length 100 src/ tests/
black --check --line-length 100 src/ tests/
mypy --ignore-missing-imports src/
pytest
The pytest suite covers preprocessing, the LSTM training/eval pipeline, utility functions, and the full BERT train/evaluate/predict pipeline, all without network access, since the BERT tests run against a tiny, randomly-initialized local checkpoint (tests/conftest.py's tiny_bert_dir fixture) rather than a real download. See CONTRIBUTING.md for details.
A real fine-tuning run against
bert-base-uncasedstill needs a live Hugging Face Hub download and is exercised manually rather than in CI.
CI is defined in:
.github/workflows/ci.yml
Requirements
- Python 3.11+
- PyTorch
- Transformers (Hugging Face)
- scikit-learn, pandas, matplotlib, seaborn
- WordCloud
- pytest, Ruff, Black, mypy
- GitHub Actions
Known Limitations
This project has important limitations:
data/tweets_sample.csvis a 15-row illustrative sample, don't read anything into the demo metrics/plots inoutputs/beyond "the pipeline runs end-to-end"- BERT's code path (training loop, evaluation, inference) is tested in CI against a tiny local checkpoint, but a real fine-tuning run against
bert-base-uncasedrequires a live Hugging Face Hub download and is only exercised manually - Pinned dependencies are refreshed periodically via Dependabot (
.github/dependabot.yml); each bump PR should pass the full gate, including the BERT tests, before merging
The project is strongest as a portfolio demonstration of a modular, reproducible transformer fine-tuning workflow, not as a benchmark of real-world sentiment accuracy.
Next Steps
Potential next improvements:
- Expand the dataset for more robust evaluation
- Try advanced transformer models (RoBERTa, DistilBERT)
- Apply hyperparameter tuning and cross-validation
- Deploy the model with FastAPI or Streamlit for an interactive demo
Author
Amir Honardoust
GitHub: @AmirhosseinHonardoust
License
This project is licensed under the MIT License. See LICENSE for details.
관련 프로젝트 살펴보기
불러오는 중…



