README.md

---
title: AspectBERT
emoji: 🔋
colorFrom: blue
colorTo: green
sdk: streamlit
sdk_version: "1.28.0"
app_file: app.py
pinned: false
license: mit
tags:
  - aspect-based-sentiment-analysis
  - distilbert
  - text-classification
  - amazon-reviews
  - absa
---

# AspectBERT

AspectBERT is a fine-tuned **DistilBERT** model for **Aspect-Based Sentiment
Analysis (ABSA)** on Amazon product reviews. Given a single review, it
predicts the sentiment (**positive / neutral / negative**) for each of 8
product aspects independently.

## Aspects

```
battery, display, camera, price, performance, design, software, customer_service
```

## Model description

- **Base model:** [`distilbert-base-uncased`](https://huggingface.co/distilbert-base-uncased)
- **Input format:** `"{review_text} aspect: {aspect_name}"`
- **Architecture:** DistilBERT backbone (first 4 of 6 transformer layers
  frozen, last 2 fine-tuned) → `Linear(768, 256)` → `GELU` →
  `Dropout(0.2)` → `Linear(256, 3)`
- **Output:** 3-way softmax over `negative`, `neutral`, `positive`

## Training data

- **Source:** [`McAuley-Lab/Amazon-Reviews-2023`](https://huggingface.co/datasets/McAuley-Lab/Amazon-Reviews-2023)
  (`raw_review_Electronics` config), ~25,000 sampled reviews
- **Aspect labeling:** keyword matching — each review can produce multiple
  rows, one per detected aspect
- **Sentiment labeling:** derived from the review's star rating
  - 4–5 stars → `positive`
  - 3 stars → `neutral`
  - 1–2 stars → `negative`
- **Split:** 70% train / 15% validation / 15% test

## Training procedure

- **Optimizer:** AdamW (`lr=2e-5`, `weight_decay=0.01`)
- **Scheduler:** OneCycleLR, 10% warmup, cosine decay
- **Epochs:** 4
- **Batch size:** 16 (CPU) / 32 (GPU)
- **Loss:** Cross-entropy
- **Model selection:** best checkpoint by validation macro F1

Training history is logged to [`results/training_history.json`](results/training_history.json).

## Evaluation

Reported on the held-out test split (15%):

- Macro F1
- Accuracy
- Per-class F1 (negative / neutral / positive)
- Confusion matrix
- Comparison against a [VADER](https://github.com/cjhutto/vaderSentiment)
  rule-based sentiment baseline (review-level, not aspect-aware)

Results are written to `results/test_metrics.json` after training
(see `src/train.py`).

## How to use

### Python (HuggingFace Hub)

```python
import os
os.environ["HF_MODEL_NAME"] = "<your-username>/aspectbert"

from src.inference import load_model, predict_all_aspects

model, tokenizer, device = load_model()
results = predict_all_aspects(
    model, tokenizer, device,
    "The battery lasts forever but the camera is disappointing in low light."
)
print(results)
# {
#   "battery": {"label": "positive", "scores": {...}},
#   "camera":  {"label": "negative", "scores": {...}},
#   ...
# }
```

### Command line

```bash
python src/inference.py "Great screen but the battery dies way too fast." --aspect battery
```

### Streamlit app

```bash
export HF_MODEL_NAME="<your-username>/aspectbert"
streamlit run app.py
```

The app supports:
- Free-text review input + 4 example reviews
- Per-aspect sentiment with confidence bars
- A radar chart of positive-sentiment scores across aspects
- LIME word-importance explanations
- A toggle to compare against a VADER baseline

## Project structure

```
AspectBERT/
├── src/
│   ├── constants.py        # shared aspects, label maps, input formatting
│   ├── data_preparation.py # download, clean, aspect labeling, splits
│   ├── model.py             # DistilBERT + classification head
│   ├── train.py             # training loop, evaluation, checkpointing
│   └── inference.py         # predict single review, all aspects, LIME
├── notebooks/
│   └── training.ipynb       # Kaggle/Colab GPU training notebook
├── app.py                    # Streamlit UI
├── requirements.txt
├── deploy_to_hf.sh           # push app to a HuggingFace Space
└── README.md
```

## Limitations

- Aspect labels are derived from keyword matching, which is noisy and may
  miss implicit aspect mentions or mislabel sarcasm.
- Sentiment labels are derived from the overall review rating, not
  aspect-specific ratings, so an aspect's true sentiment may occasionally
  differ from the review's overall rating.
- Trained on Electronics category reviews; may not generalize well to other
  product categories.

## License

MIT