Deep Learning › Sequences and Text › Day 224
Hands-on lab — Day 224: A Sentiment Analysis Project
- ← Back to the Day 224 lesson
- Open the hands-on files on GitHub — clone or download them from the public labs repository
- Local path in your clone:
labs/sections/deep-learning/day-224-a-sentiment-analysis-project/
Commands
Setup
pip install -r requirements/requirements.txt Run
python3 examples/a_sentiment_analysis_project_lib.py Test
./tests/run_tests.sh File tree
conftest.py examples/a_sentiment_analysis_project_lib.py examples/test_a_sentiment_analysis_project_lib.py expected-output/examples-run.txt expected-output/FIELDS.md expected-output/measured-values.txt expected-output/starter-run.txt expected-output/test-run.txt metadata.yml README.md requirements/requirements.txt security.md starter/a_sentiment_analysis_project_lib.py starter/test_a_sentiment_analysis_project_lib.py tests/run_tests.sh tests/test_a_sentiment_analysis_project_lib.py troubleshooting.md
Lab README
Lab: Day 224 -- A Sentiment Analysis Project
Lesson
Day number: 224 of 365. Course: Course05-SS02 (Deep Learning - Sequence Models and Transformers). Topic: End-to-End Sentiment Analysis with Attention and Explainability.
Purpose
Build and test an end-to-end sentiment classification pipeline in PyTorch. Implement the BiLSTMAttentionSentiment architecture, compute attention-pooled document vectors, and extract gradient-based token attribution saliency scores for individual review explanations.
Learning objectives
- Implement bidirectional LSTM sequence encoding with learned attention pooling.
- Compute normalized attention weights and handle padding masks.
- Compute gradient saliency scores for token-level prediction explainability.
- Verify classification output dimensions and probability distributions.
Prerequisites
- Day 223 (Text Classification with Embeddings).
- Python 3.11+ with PyTorch and NumPy.
Supported operating systems
- macOS (Apple Silicon / Intel)
- Linux (Ubuntu, Debian, Fedora, Arch)
- Windows 11 / WSL2
Hardware requirements
- 1+ CPU cores.
- 1 GB RAM.
- 100 MB disk space.
Required software
- Python 3.11 or newer.
- pip package manager.
- virtualenv or venv module.
Free and open-source options
PyTorch is open-source software maintained by the Linux Foundation under a modified BSD license.
Installation
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements/requirements.txt
File structure
starter/a_sentiment_analysis_project_lib.py: Student scaffold file.examples/a_sentiment_analysis_project_lib.py: Complete reference implementation.tests/test_a_sentiment_analysis_project_lib.py: Pytest automated validation suite.expected-output/: Verified output logs and baseline values.
How to run
Execute the reference demonstration script:
python3 examples/a_sentiment_analysis_project_lib.py
What the commands do
- Evaluates BiLSTM attention forward passes over review batches.
- Calculates gradient saliency token attribution scores.
- Runs unit test assertions.
Expected output
Sentiment Demo: Logits Shape = torch.Size([2, 2]), Saliency Shape = torch.Size([5])
Validation steps
- Verify
BiLSTMAttentionSentiment.forwardoutputs logits of shape(batch_size, num_classes). - Confirm
attn_weightssum to 1.0 along the sequence dimension. - Ensure
explain_tokensproduces saliency vectors matching input token length. - Ensure all unit test assertions pass.
Tests
Run the test runner script:
./tests/run_tests.sh
Cleanup
find . -type d -name "__pycache__" -exec rm -rf {} +
find . -type d -name ".pytest_cache" -exec rm -rf {} +
Troubleshooting
- Gradients not tracked in explain_tokens: Ensure embedding weights are detached and marked with
.requires_grad_(True)before forward computation.
Security notes
All sentiment processing and gradient calculations run locally in memory.
Extension exercises
- Implement temperature scaling to calibrate confidence probabilities.
- Build an Integrated Gradients path integral calculation across $m=50$ interpolation steps.
Navigation
- Lesson title: A Sentiment Analysis Project
- Day number: 224 of 365
- Lesson article: https://ai-roadmap-365.github.io/day-224-a-sentiment-analysis-project
- Lab files: everything you need is in this directory — follow “How to run” below.
- Browse the course locally: from the repository root, this lab also appears in the course website at
/labs/day-224-a-sentiment-analysis-projectwhen the site is running.
Expected output
FIELDS.md
# Expected Output Fields: Day 224
- `Logits Shape`: Tensor shape of the model sentiment prediction logits.
- `Saliency Shape`: Tensor shape of the calculated token saliency scores.
examples-run.txt
Sentiment Demo: Logits Shape = torch.Size([2, 2]), Saliency Shape = torch.Size([5])
measured-values.txt
Logits Shape: torch.Size([2, 2])
Saliency Shape: torch.Size([5])
starter-run.txt
Starter scaffold executed. Ready for student implementation.
test-run.txt
============================= test session starts ==============================
collected 2 items
tests/test_a_sentiment_analysis_project_lib.py::test_bilstm_attention_sentiment_forward PASSED [ 50%]
tests/test_a_sentiment_analysis_project_lib.py::test_token_attribution_explainability PASSED [100%]
============================== 2 passed in 0.42s ===============================
Source files
conftest.py (585 bytes)
"""Make this lab importable when the suite runs.
pytest puts the test file's own directory on sys.path, not the lab root, so a
test that does `from examples.<module> import ...` -- or imports a module that
lives in examples/ directly -- fails without this. Putting it here rather than
in run_tests.sh means a bare `pytest` from the lab root works too.
"""
import os
import sys
LAB = os.path.dirname(os.path.abspath(__file__))
for candidate in (LAB, os.path.join(LAB, "examples")):
if os.path.isdir(candidate) and candidate not in sys.path:
sys.path.insert(0, candidate)
examples/a_sentiment_analysis_project_lib.py (2348 bytes)
import torch
import torch.nn as nn
import torch.nn.functional as F
from typing import Tuple
class BiLSTMAttentionSentiment(nn.Module):
def __init__(self, vocab_size: int, embed_dim: int, hidden_dim: int, num_classes: int = 2):
super().__init__()
self.embedding = nn.Embedding(vocab_size, embed_dim, padding_idx=0)
self.lstm = nn.LSTM(embed_dim, hidden_dim, batch_first=True, bidirectional=True)
self.attn_proj = nn.Linear(hidden_dim * 2, hidden_dim)
self.attn_vec = nn.Linear(hidden_dim, 1, bias=False)
self.classifier = nn.Sequential(
nn.Dropout(0.5),
nn.Linear(hidden_dim * 2, num_classes)
)
def forward(self, x: torch.Tensor, mask: torch.Tensor = None) -> Tuple[torch.Tensor, torch.Tensor]:
embeds = self.embedding(x)
h_seq, _ = self.lstm(embeds)
u = torch.tanh(self.attn_proj(h_seq))
scores = self.attn_vec(u).squeeze(2)
if mask is not None:
scores = scores.masked_fill(mask == 0, -1e9)
attn_weights = F.softmax(scores, dim=1)
doc_vec = torch.bmm(attn_weights.unsqueeze(1), h_seq).squeeze(1)
logits = self.classifier(doc_vec)
return logits, attn_weights
def explain_tokens(self, x: torch.Tensor, target_class: int = 1) -> Tuple[torch.Tensor, torch.Tensor]:
self.eval()
embeds = self.embedding(x).detach().requires_grad_(True)
h_seq, _ = self.lstm(embeds)
u = torch.tanh(self.attn_proj(h_seq))
scores = self.attn_vec(u).squeeze(2)
attn_weights = F.softmax(scores, dim=1)
doc_vec = torch.bmm(attn_weights.unsqueeze(1), h_seq).squeeze(1)
logits = self.classifier(doc_vec)
score = logits[0, target_class]
score.backward()
saliency = (embeds.grad[0] * embeds[0]).sum(dim=1).detach()
return saliency, attn_weights[0]
def run_sentiment_demo():
torch.manual_seed(42)
model = BiLSTMAttentionSentiment(vocab_size=50, embed_dim=8, hidden_dim=4, num_classes=2)
x = torch.randint(1, 50, (2, 5))
logits, weights = model(x)
saliency, _ = model.explain_tokens(x[:1], target_class=1)
print(f"Sentiment Demo: Logits Shape = {logits.shape}, Saliency Shape = {saliency.shape}")
return logits, saliency
if __name__ == "__main__":
run_sentiment_demo()
examples/test_a_sentiment_analysis_project_lib.py (848 bytes)
import pytest
import torch
from examples.a_sentiment_analysis_project_lib import BiLSTMAttentionSentiment
def test_bilstm_attention_sentiment_forward():
torch.manual_seed(42)
model = BiLSTMAttentionSentiment(vocab_size=100, embed_dim=16, hidden_dim=8, num_classes=2)
x = torch.randint(0, 100, (4, 10))
logits, weights = model(x)
assert logits.shape == (4, 2)
assert weights.shape == (4, 10)
for s in weights.sum(dim=1):
assert pytest.approx(s.item(), 1e-5) == 1.0
def test_token_attribution_explainability():
torch.manual_seed(42)
model = BiLSTMAttentionSentiment(vocab_size=100, embed_dim=16, hidden_dim=8, num_classes=2)
x = torch.randint(0, 100, (1, 6))
saliency, weights = model.explain_tokens(x, target_class=1)
assert saliency.shape == (6,)
assert weights.shape == (6,)
metadata.yml (441 bytes)
lesson_id: D224
day: 224
kind: lab
languages:
- python
setup_commands:
- 'pip install -r requirements/requirements.txt'
run_commands:
- 'python3 examples/a_sentiment_analysis_project_lib.py'
test_commands:
- './tests/run_tests.sh'
cleanup_commands:
- 'find . -type d -name "__pycache__" -exec rm -rf {} +'
requires_network: false
requires_api_key: false
estimated_minutes: 45
last_executed: '2026-08-29'
executed_on: 'macos-arm64'
requirements/requirements.txt (41 bytes)
torch>=2.2.0
numpy>=1.26.0
pytest>=8.0.0
starter/a_sentiment_analysis_project_lib.py (767 bytes)
import torch
import torch.nn as nn
import torch.nn.functional as F
from typing import Tuple
class BiLSTMAttentionSentiment(nn.Module):
def __init__(self, vocab_size: int, embed_dim: int, hidden_dim: int, num_classes: int = 2):
super().__init__()
# TODO: Initialize embedding, LSTM, attention projections, and classifier
pass
def forward(self, x: torch.Tensor, mask: torch.Tensor = None) -> Tuple[torch.Tensor, torch.Tensor]:
# TODO: Compute BiLSTM states, attention weights, pooled document vector, and logits
pass
def explain_tokens(self, x: torch.Tensor, target_class: int = 1) -> Tuple[torch.Tensor, torch.Tensor]:
# TODO: Compute token attribution saliency via input embedding gradients
pass
starter/test_a_sentiment_analysis_project_lib.py (848 bytes)
import pytest
import torch
from examples.a_sentiment_analysis_project_lib import BiLSTMAttentionSentiment
def test_bilstm_attention_sentiment_forward():
torch.manual_seed(42)
model = BiLSTMAttentionSentiment(vocab_size=100, embed_dim=16, hidden_dim=8, num_classes=2)
x = torch.randint(0, 100, (4, 10))
logits, weights = model(x)
assert logits.shape == (4, 2)
assert weights.shape == (4, 10)
for s in weights.sum(dim=1):
assert pytest.approx(s.item(), 1e-5) == 1.0
def test_token_attribution_explainability():
torch.manual_seed(42)
model = BiLSTMAttentionSentiment(vocab_size=100, embed_dim=16, hidden_dim=8, num_classes=2)
x = torch.randint(0, 100, (1, 6))
saliency, weights = model.explain_tokens(x, target_class=1)
assert saliency.shape == (6,)
assert weights.shape == (6,)
tests/run_tests.sh (227 bytes)
#!/usr/bin/env bash
set -euo pipefail
echo "========================================"
echo "Running Day 224 Lab Test Suite"
echo "========================================"
pytest tests/ -v
echo "All tests passed successfully."
tests/test_a_sentiment_analysis_project_lib.py (848 bytes)
import pytest
import torch
from examples.a_sentiment_analysis_project_lib import BiLSTMAttentionSentiment
def test_bilstm_attention_sentiment_forward():
torch.manual_seed(42)
model = BiLSTMAttentionSentiment(vocab_size=100, embed_dim=16, hidden_dim=8, num_classes=2)
x = torch.randint(0, 100, (4, 10))
logits, weights = model(x)
assert logits.shape == (4, 2)
assert weights.shape == (4, 10)
for s in weights.sum(dim=1):
assert pytest.approx(s.item(), 1e-5) == 1.0
def test_token_attribution_explainability():
torch.manual_seed(42)
model = BiLSTMAttentionSentiment(vocab_size=100, embed_dim=16, hidden_dim=8, num_classes=2)
x = torch.randint(0, 100, (1, 6))
saliency, weights = model.explain_tokens(x, target_class=1)
assert saliency.shape == (6,)
assert weights.shape == (6,)
Troubleshooting
Troubleshooting: Day 224 - A Sentiment Analysis Project
Common Issues
- Backward pass error in explain_tokens:
- Cause: Target class score was detached before calling backward.
- Fix: Keep computation graph intact when computing
logits[0, target_class].backward().
Security notes
Security & Privacy: Day 224 - A Sentiment Analysis Project
Security Guidance
- All sentiment analysis and token saliency operations execute locally.