Deep Learning › Sequences and Text › Day 224

Hands-on lab — 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

  1. Verify BiLSTMAttentionSentiment.forward outputs logits of shape (batch_size, num_classes).
  2. Confirm attn_weights sum to 1.0 along the sequence dimension.
  3. Ensure explain_tokens produces saliency vectors matching input token length.
  4. 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

  1. Implement temperature scaling to calibrate confidence probabilities.
  2. Build an Integrated Gradients path integral calculation across $m=50$ interpolation steps.

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

  1. 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.