Naive Bayes Classifier Explained — How It Works, When to Use It, and Why It's Surprisingly Powerful

# bayes_theorem_walkthrough.py
# Let's verify Bayes' theorem manually before using any library.
# We'll use a medical test scenario: does a patient have a rare disease?

# ---- Setup: prior knowledge from medical literature ----
prob_has_disease = 0.01          # 1% of the population has this disease (prior)
prob_no_disease = 1 - prob_has_disease  # 99% do not

# The test is 95% accurate:
# If you HAVE the disease, it correctly says 'positive' 95% of the time
prob_positive_given_disease = 0.95

# If you DON'T have the disease, it incorrectly says 'positive' 5% of the time
prob_positive_given_no_disease = 0.05

# ---- Step 1: Calculate the total probability of testing positive ----
# This accounts for BOTH true positives and false positives
prob_positive = (
    prob_positive_given_disease * prob_has_disease
    + prob_positive_given_no_disease * prob_no_disease
)

# ---- Step 2: Apply Bayes' Theorem ----
# P(disease | positive test) = P(positive | disease) * P(disease) / P(positive)
prob_disease_given_positive = (
    prob_positive_given_disease * prob_has_disease
) / prob_positive

print(f"Probability of testing positive overall:       {prob_positive:.4f} ({prob_positive*100:.2f}%)")
print(f"Probability of ACTUALLY having the disease")
print(f"  AFTER a positive test result:               {prob_disease_given_positive:.4f} ({prob_disease_given_positive*100:.2f}%)")
print()
print("Key insight: Even with a 95%-accurate test,")
print(f"a positive result only means {prob_disease_given_positive*100:.1f}% chance of having the disease.")
print("The low prior (1% prevalence) dominates the math.")
print("This is why base rates matter enormously in Naive Bayes.")

# naive_bayes_from_scratch.py
# A fully hand-rolled Naive Bayes spam classifier.
# Every probability is computed manually — no sklearn magic here.

import math
from collections import defaultdict

# ---- Training data: (message, label) pairs ----
training_emails = [
    ("free money click here now",           "spam"),
    ("win a free iphone congratulations",   "spam"),
    ("cheap pills free offer limited time", "spam"),
    ("click here to claim your prize free", "spam"),
    ("you won congratulations claim now",   "spam"),
    ("meeting at 3pm in the boardroom",     "ham"),
    ("can you review my pull request",      "ham"),
    ("lunch tomorrow works for me",         "ham"),
    ("please send the quarterly report",    "ham"),
    ("the deployment is scheduled friday",  "ham"),
]

# ---- Step 1: Count word frequencies per class ----
word_counts = {"spam": defaultdict(int), "ham": defaultdict(int)}
class_doc_counts = {"spam": 0, "ham": 0}
vocabulary = set()

for message, label in training_emails:
    class_doc_counts[label] += 1
    for word in message.split():
        word_counts[label][word] += 1
        vocabulary.add(word)          # build the full vocabulary

total_docs = sum(class_doc_counts.values())
vocab_size = len(vocabulary)

print(f"Vocabulary size:  {vocab_size} unique words")
print(f"Spam messages:    {class_doc_counts['spam']}")
print(f"Ham messages:     {class_doc_counts['ham']}")
print()

# ---- Step 2: Calculate prior log-probabilities for each class ----
# log() turns multiplication into addition — avoids floating-point underflow
log_prior = {
    label: math.log(count / total_docs)
    for label, count in class_doc_counts.items()
}

# ---- Step 3: Define prediction function with Laplace smoothing ----
def classify_message(message: str) -> tuple[str, dict]:
    """
    Classify a message as 'spam' or 'ham'.
    Returns the predicted label and the log-probability scores for both classes.
    """
    words = message.lower().split()
    log_scores = {}

    for label in ["spam", "ham"]:
        # Start with the prior probability for this class
        score = log_prior[label]

        # Total words seen in this class (for denominator)
        total_words_in_class = sum(word_counts[label].values())

        for word in words:
            # Laplace smoothing: add 1 to numerator, vocab_size to denominator
            # This prevents any word from having zero probability
            word_count_in_class = word_counts[label].get(word, 0)
            smoothed_probability = (
                (word_count_in_class + 1)
                / (total_words_in_class + vocab_size)
            )
            # Add log-probability instead of multiplying raw probability
            score += math.log(smoothed_probability)

        log_scores[label] = score

    predicted_label = max(log_scores, key=log_scores.get)
    return predicted_label, log_scores

# ---- Step 4: Test on new, unseen messages ----
test_messages = [
    "free offer click here win prize",
    "can we reschedule the meeting to friday",
    "congratulations you won a free phone",
    "the report is ready for your review",
]

print("=" * 55)
print(f"{'Message':<38} {'Prediction':>10}")
print("=" * 55)

for msg in test_messages:
    prediction, scores = classify_message(msg)
    print(f"{msg[:37]:<38} {prediction:>10}")
    print(f"  spam score: {scores['spam']:.3f}  |  ham score: {scores['ham']:.3f}")
    print()

# spam_classifier_sklearn.py
# Production-grade spam classifier using sklearn.
# Includes pipeline, evaluation metrics, and probability calibration.

from sklearn.naive_bayes import MultinomialNB
from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.pipeline import Pipeline
from sklearn.model_selection import train_test_split, cross_val_score
from sklearn.metrics import classification_report, confusion_matrix
from sklearn.calibration import CalibratedClassifierCV
import numpy as np

# ---- Dataset: realistic spam/ham examples ----
email_messages = [
    # SPAM
    "WINNER! You have been selected. Claim your FREE prize now!",
    "Cheap Viagra! Buy online, no prescription needed.",
    "Make money fast from home — $5000/week guaranteed!",
    "Your account has been suspended click here immediately",
    "Congratulations! You won our lottery drawing. Reply now.",
    "FREE iPhone 15 Pro — limited time offer, click to claim",
    "URGENT: Your bank account needs verification now",
    "Hot singles in your area — click to meet them tonight",
    "Earn passive income with this one weird trick",
    "You have been pre-approved for a $50,000 loan no credit check",
    # HAM
    "Can you send me the updated project timeline?",
    "The sprint retrospective is moved to Thursday 2pm.",
    "I reviewed your PR — a few comments on the auth module.",
    "Quarterly revenue figures are attached. Let me know your thoughts.",
    "Are you joining the team lunch on Friday?",
    "The deployment went smoothly. All services are green.",
    "Could you review the new API documentation draft?",
    "Reminder: performance reviews are due by end of month.",
    "Thanks for the feedback on the design mockups.",
    "The client approved the proposal. Kickoff is next Monday.",
]

labels = (
    ["spam"] * 10  # first 10 are spam
    + ["ham"] * 10  # last 10 are ham
)

# ---- Split data ----
messages_train, messages_test, labels_train, labels_test = train_test_split(
    email_messages, labels,
    test_size=0.25,
    random_state=42,
    stratify=labels   # keeps class ratio balanced across train/test
)

# ---- Build a Pipeline: TF-IDF vectorisation + Naive Bayes ----
# TF-IDF is better than raw counts — it downweights common words like 'the'
spam_pipeline = Pipeline([
    (
        "tfidf_vectorizer",
        TfidfVectorizer(
            ngram_range=(1, 2),    # use single words AND two-word phrases
            min_df=1,              # include words appearing at least once
            stop_words="english",  # ignore 'the', 'is', 'and', etc.
            sublinear_tf=True,     # apply log scaling to term frequency
        )
    ),
    (
        "naive_bayes_classifier",
        MultinomialNB(alpha=1.0)   # alpha=1.0 is standard Laplace smoothing
    ),
])

# ---- Cross-validation score on training data ----
cv_scores = cross_val_score(
    spam_pipeline, messages_train, labels_train,
    cv=3, scoring="f1_macro"
)
print(f"Cross-validation F1 scores:  {cv_scores.round(3)}")
print(f"Mean CV F1:                  {cv_scores.mean():.3f}")
print()

# ---- Train and evaluate on test set ----
spam_pipeline.fit(messages_train, labels_train)
predictions = spam_pipeline.predict(messages_test)

print("Classification Report:")
print(classification_report(labels_test, predictions, target_names=["ham", "spam"]))

print("Confusion Matrix (rows=actual, cols=predicted):")
print(f"              Predicted Ham  Predicted Spam")
cm = confusion_matrix(labels_test, predictions, labels=["ham", "spam"])
print(f"Actual Ham          {cm[0][0]}              {cm[0][1]}")
print(f"Actual Spam         {cm[1][0]}              {cm[1][1]}")
print()

# ---- Show confidence scores for new messages ----
new_emails = [
    "You have won a free holiday package. Call now!",
    "Please review the attached contract before signing.",
]

probabilities = spam_pipeline.predict_proba(new_emails)
class_labels = spam_pipeline.classes_

print("Probability Breakdown for New Emails:")
print("-" * 55)
for email, prob_row in zip(new_emails, probabilities):
    ham_prob = prob_row[list(class_labels).index("ham")]
    spam_prob = prob_row[list(class_labels).index("spam")]
    verdict = "SPAM" if spam_prob > ham_prob else "HAM"
    print(f"Email: '{email[:45]}...'")
    print(f"  Ham probability:  {ham_prob:.3f}")
    print(f"  Spam probability: {spam_prob:.3f}  →  Verdict: {verdict}")
    print()

# naive_bayes_incremental_learning.py
# Demonstrates partial_fit() — training Naive Bayes incrementally.
# Perfect for scenarios where data arrives in batches (streaming, live systems).

from sklearn.naive_bayes import MultinomialNB
from sklearn.feature_extraction.text import HashingVectorizer
from sklearn.metrics import accuracy_score

# HashingVectorizer doesn't need to 'see' all data upfront — perfect for streaming
# It hashes words to a fixed-size feature vector without storing a vocabulary
vectorizer = HashingVectorizer(
    n_features=2**14,      # 16,384 feature buckets — enough for most text tasks
    alternate_sign=False,  # MultinomialNB requires non-negative values
    norm=None,             # raw counts, not normalised (MultinomialNB prefers this)
    stop_words="english",
)

# MultinomialNB with partial_fit — must declare all classes upfront
online_classifier = MultinomialNB(alpha=1.0)
all_classes = ["spam", "ham"]

# ---- Simulate three batches of incoming emails ----
batch_1 = [
    ("free money win cash prize now",        "spam"),
    ("meeting scheduled for 10am tomorrow",  "ham"),
    ("click here claim your free reward",    "spam"),
    ("please approve the budget proposal",   "ham"),
]

batch_2 = [
    ("urgent bank account suspended verify", "spam"),
    ("team offsite is confirmed for June",   "ham"),
    ("you won congratulations call now",     "spam"),
    ("deployment pipeline updated",          "ham"),
]

batch_3 = [
    ("cheap pills no prescription needed",   "spam"),
    ("client feedback received review docs", "ham"),
    ("earn money from home guaranteed",      "spam"),
    ("sprint planning at 9am Monday",        "ham"),
]

def train_on_batch(batch, batch_number):
    """Vectorise one batch and update the classifier using partial_fit."""
    texts, batch_labels = zip(*batch)  # unzip into separate lists

    # Transform text into feature vectors
    feature_matrix = vectorizer.transform(texts)

    # partial_fit updates the model WITHOUT forgetting what it learned before
    online_classifier.partial_fit(
        feature_matrix, batch_labels,
        classes=all_classes  # required on the FIRST call; harmless on subsequent calls
    )
    print(f"Batch {batch_number} processed — {len(batch)} messages ingested.")


def evaluate_on_held_out():
    """Test on a fixed set to see how accuracy improves with each batch."""
    test_messages = [
        "win a free iPhone click here",    # spam
        "can you review the pull request", # ham
        "guaranteed passive income online", # spam
        "the invoice is attached for Q2",  # ham
    ]
    true_labels = ["spam", "ham", "spam", "ham"]

    test_features = vectorizer.transform(test_messages)
    predictions = online_classifier.predict(test_features)
    accuracy = accuracy_score(true_labels, predictions)

    for msg, true, pred in zip(test_messages, true_labels, predictions):
        status = "✓" if true == pred else "✗"
        print(f"  {status} [{true:>4}] predicted [{pred:>4}]: '{msg[:40]}'")
    print(f"  Accuracy after this batch: {accuracy:.0%}")
    print()


# ---- Train incrementally, evaluate after each batch ----
for batch_num, batch_data in enumerate([batch_1, batch_2, batch_3], start=1):
    train_on_batch(batch_data, batch_num)
    print(f"Model state after Batch {batch_num}:")
    evaluate_on_held_out()