visualize.py

# -*- coding: utf-8 -*-
"""
visualize.py
------------
Exploratory data analysis & visualization for the serial-killer incident
dataset. Reads the cleaned dataset (data/Data_Analytics_clean.csv) and
produces every chart used in the presentation, saved to outputs/.

Run from the repo root:
    python src/visualize.py
"""

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import seaborn as sns
from pathlib import Path

ROOT = Path(__file__).resolve().parent.parent
DATA_PATH = ROOT / "data" / "Data_Analytics_clean.csv"
OUT_DIR = ROOT / "outputs"
OUT_DIR.mkdir(exist_ok=True)

# =============================================================================
# 1. Load data
# =============================================================================
df = pd.read_csv(DATA_PATH)

print("Dataset shape:", df.shape)
print("\nFirst 5 rows:")
print(df.head())

# Convert MentalIllness column to a list of disorders per row
df["Disorders"] = df["MentalIllness"].str.split(", ")

# Binary indicator column per disorder (for co-occurrence analysis)
all_disorders = sorted(set(d for sublist in df["Disorders"] for d in sublist))
for disorder in all_disorders:
    df[disorder] = df["Disorders"].apply(lambda d: 1 if disorder in d else 0)

# =============================================================================
# 2. Disorder frequency (per incident, exploded)
# =============================================================================
disorders_expanded = df.explode("Disorders")
disorder_counts = disorders_expanded["Disorders"].value_counts()

print("\nDisorder frequencies (per incident):")
print(disorder_counts)

plt.figure(figsize=(10, 5))
disorder_counts.plot(kind="bar", color="coral")
plt.title("Frequency of Mental Disorders Among Serial Killers (per incident)")
plt.xlabel("Disorder")
plt.ylabel("Count")
plt.xticks(rotation=45, ha="right")
plt.tight_layout()
plt.savefig(OUT_DIR / "01_frequency_of_disorders.png", dpi=150)
plt.close()

# =============================================================================
# 3. Focus on top disorders for detailed visualization
# =============================================================================
top_disorders = disorder_counts.head(6).index.tolist()
mask_top = df["Disorders"].apply(lambda d: any(dis in d for dis in top_disorders))
df_top = df[mask_top].copy()

# Primary disorder = first one listed (simplification, documented in README)
df_top["PrimaryDisorder"] = df_top["Disorders"].apply(lambda d: d[0] if d else "Unknown")

# =============================================================================
# 4. Victim age distribution by primary disorder
# =============================================================================
plt.figure(figsize=(12, 6))
sns.boxplot(data=df_top, x="PrimaryDisorder", y="VictimAge", hue="PrimaryDisorder",
            palette="Set2", legend=False)
plt.title("Victim Age Distribution by Killer's Primary Mental Disorder")
plt.xticks(rotation=45)
plt.ylabel("Victim Age")
plt.xlabel("Primary Disorder")
plt.tight_layout()
plt.savefig(OUT_DIR / "02_victim_age_by_disorder.png", dpi=150)
plt.close()

# =============================================================================
# 5. Victim gender by primary disorder
# =============================================================================
gender_ct = pd.crosstab(df_top["PrimaryDisorder"], df_top["VictimGender"])
gender_ct.plot(kind="bar", stacked=True, colormap="viridis", figsize=(12, 6))
plt.title("Victim Gender by Killer's Primary Mental Disorder")
plt.xlabel("Primary Disorder")
plt.ylabel("Count")
plt.legend(title="Victim Gender")
plt.xticks(rotation=45)
plt.tight_layout()
plt.savefig(OUT_DIR / "03_victim_gender_by_disorder.png", dpi=150)
plt.close()

# =============================================================================
# 6. Killing method by primary disorder (proportions)
# =============================================================================
method_by_disorder = pd.crosstab(df_top["PrimaryDisorder"], df_top["Method"])
method_by_disorder_norm = method_by_disorder.div(method_by_disorder.sum(axis=1), axis=0)

method_by_disorder_norm.plot(kind="bar", stacked=True, figsize=(14, 7), colormap="tab20")
plt.title("Proportion of Killing Methods by Primary Mental Disorder")
plt.xlabel("Primary Disorder")
plt.ylabel("Proportion")
plt.legend(title="Method", bbox_to_anchor=(1.05, 1))
plt.xticks(rotation=45)
plt.tight_layout()
plt.savefig(OUT_DIR / "04_method_proportions_by_disorder.png", dpi=150)
plt.close()

# =============================================================================
# 7. Relationship to victim (Stranger vs Acquaintance)
# =============================================================================
rel_ct = pd.crosstab(df_top["PrimaryDisorder"], df_top["Relationship"])
rel_ct.plot(kind="bar", stacked=True, figsize=(12, 6), colormap="coolwarm")
plt.title("Relationship to Victim by Primary Mental Disorder")
plt.xlabel("Primary Disorder")
plt.ylabel("Count")
plt.legend(title="Relationship")
plt.xticks(rotation=45)
plt.tight_layout()
plt.savefig(OUT_DIR / "05_relationship_by_disorder.png", dpi=150)
plt.close()

# =============================================================================
# 8. Killer age at crime by primary disorder
# =============================================================================
plt.figure(figsize=(12, 6))
sns.boxplot(data=df_top, x="PrimaryDisorder", y="KillerAge", hue="PrimaryDisorder",
            palette="Set3", legend=False)
plt.title("Killer Age at Crime by Primary Mental Disorder")
plt.xlabel("Primary Disorder")
plt.ylabel("Killer Age")
plt.xticks(rotation=45)
plt.tight_layout()
plt.savefig(OUT_DIR / "06_killer_age_by_disorder.png", dpi=150)
plt.close()

# =============================================================================
# 9. Geographic patterns - incident count by state and primary disorder
# =============================================================================
state_by_disorder = df_top.groupby("PrimaryDisorder")["State"].agg(
    lambda x: x.mode()[0] if not x.mode().empty else "Multiple"
)
print("\nMost common state per primary disorder:")
print(state_by_disorder)

plt.figure(figsize=(14, 6))
sns.countplot(data=df_top, y="State", hue="PrimaryDisorder",
              order=df_top["State"].value_counts().index)
plt.title("Incident Count by State and Primary Disorder")
plt.xlabel("Count")
plt.ylabel("State")
plt.legend(bbox_to_anchor=(1.05, 1))
plt.tight_layout()
plt.savefig(OUT_DIR / "07_incidents_by_state_and_disorder.png", dpi=150)
plt.close()

# =============================================================================
# 10. Disorder co-occurrence heatmap
# =============================================================================
co_occur = df[all_disorders].T.dot(df[all_disorders])
co_occur_arr = co_occur.to_numpy().copy()
np.fill_diagonal(co_occur_arr, 0)  # ignore self-pairs
co_occur = pd.DataFrame(co_occur_arr, index=co_occur.index, columns=co_occur.columns)

plt.figure(figsize=(12, 10))
sns.heatmap(co_occur, annot=True, fmt="d", cmap="Blues", square=True)
plt.title("Co-occurrence Counts of Mental Disorders (Number of Killers With Both)")
plt.tight_layout()
plt.savefig(OUT_DIR / "08_disorder_co_occurrence_heatmap.png", dpi=150)
plt.close()

# =============================================================================
# 11. Descriptive statistics summary (printed + saved to CSV for the README)
# =============================================================================
desc = df["VictimAge"].describe()
mode_age = df["VictimAge"].mode().iloc[0]
summary = pd.DataFrame({
    "VictimAge": [desc["mean"], desc["50%"], mode_age, desc["std"], desc["min"], desc["max"]],
}, index=["mean", "median", "mode", "std", "min", "max"])
summary.to_csv(OUT_DIR / "victim_age_summary_stats.csv")
print("\nVictim age summary statistics:")
print(summary)

print("\nAll charts saved to:", OUT_DIR)