marketing_analysis.py

# ============================================================
#  Marketing Analytics: RFM Segmentation + Campaign Analysis
#  Author  : Data Analyst Portfolio
#  Tools   : Python 3, Pandas, Matplotlib, Seaborn
#  Dataset : UCI Online Retail II (2010-2011)
#            Source: Chen, D. (2015). Online Retail II [Dataset].
#            UCI Machine Learning Repository.
#            https://doi.org/10.24432/C5BW33
#  Purpose : Segment customers by value and identify the most
#            effective marketing channels per segment
# ============================================================

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import matplotlib.patches as mpatches
import matplotlib.ticker as mticker
import matplotlib.gridspec as gridspec
import warnings
warnings.filterwarnings("ignore")

# ── CONFIGURATION ─────────────────────────────────────────────
DATA_PATH  = "/mnt/user-data/uploads/retail_sample.csv"
OUTPUT_DIR = "/home/claude/"

np.random.seed(42)

BRAND_DARK   = "#0b0e14"
BRAND_GREEN  = "#4fffb0"
BRAND_RED    = "#ff6b6b"
BRAND_BLUE   = "#6baeff"
BRAND_GOLD   = "#f7c948"
BRAND_PURPLE = "#c084fc"
BRAND_MUTED  = "#6b7488"
BRAND_DIM    = "#2a3045"

plt.rcParams.update({
    "figure.facecolor" : BRAND_DARK,
    "axes.facecolor"   : "#12161f",
    "axes.edgecolor"   : "#2a3045",
    "axes.labelcolor"  : BRAND_MUTED,
    "xtick.color"      : BRAND_MUTED,
    "ytick.color"      : BRAND_MUTED,
    "text.color"       : "#e8ecf3",
    "grid.color"       : "#1e2535",
    "grid.linestyle"   : "--",
    "grid.linewidth"   : 0.6,
    "font.family"      : "DejaVu Sans",
    "font.size"        : 10,
})


# ============================================================
#  STEP 1 - LOAD AND CLEAN DATA
# ============================================================

df = pd.read_csv(DATA_PATH, parse_dates=["InvoiceDate"])
df.columns = df.columns.str.strip()
df = df.rename(columns={"Customer ID": "CustomerID"})

print("=" * 60)
print("STEP 1 - DATA OVERVIEW")
print("=" * 60)
print(f"Raw rows          : {len(df):,}")
print(f"Columns           : {list(df.columns)}")
print(f"Date range        : {df['InvoiceDate'].min().date()} to {df['InvoiceDate'].max().date()}")
print(f"Missing CustomerID: {df['CustomerID'].isna().sum():,}")
print(f"Cancellations (C) : {df['Invoice'].str.startswith('C').sum():,}")
print()

# Remove cancellations, missing customers, zero/negative values
df_clean = df[
    (~df["Invoice"].str.startswith("C")) &
    (df["CustomerID"].notna()) &
    (df["Quantity"] > 0) &
    (df["Price"] > 0)
].copy()

df_clean["CustomerID"] = df_clean["CustomerID"].astype(int)
df_clean["Revenue"]    = df_clean["Quantity"] * df_clean["Price"]

print(f"Rows after cleaning   : {len(df_clean):,}")
print(f"Unique customers      : {df_clean['CustomerID'].nunique():,}")
print(f"Total revenue         : ${df_clean['Revenue'].sum():,.0f}")
print()


# ============================================================
#  STEP 2 - RFM CALCULATION
#  Recency   = days since last purchase (lower is better)
#  Frequency = number of unique invoices (higher is better)
#  Monetary  = total spend (higher is better)
# ============================================================

snapshot_date = df_clean["InvoiceDate"].max() + pd.Timedelta(days=1)

rfm = df_clean.groupby("CustomerID").agg(
    Recency   = ("InvoiceDate", lambda x: (snapshot_date - x.max()).days),
    Frequency = ("Invoice",     "nunique"),
    Monetary  = ("Revenue",     "sum")
).reset_index()

print("=" * 60)
print("STEP 2 - RFM METRICS (raw)")
print("=" * 60)
print(rfm[["Recency", "Frequency", "Monetary"]].describe().round(1))
print()


# ============================================================
#  STEP 3 - RFM SCORING (1 to 5 per dimension)
#  Recency  : lower days = higher score (reversed)
#  Frequency: higher count = higher score
#  Monetary : higher spend = higher score
# ============================================================

rfm["R_Score"] = pd.qcut(rfm["Recency"],   q=5, labels=[5,4,3,2,1]).astype(int)
rfm["F_Score"] = pd.qcut(rfm["Frequency"].rank(method="first"), q=5, labels=[1,2,3,4,5]).astype(int)
rfm["M_Score"] = pd.qcut(rfm["Monetary"].rank(method="first"),  q=5, labels=[1,2,3,4,5]).astype(int)

rfm["RFM_Score"] = rfm["R_Score"] + rfm["F_Score"] + rfm["M_Score"]

print("=" * 60)
print("STEP 3 - RFM SCORES (1-5 each, max combined = 15)")
print("=" * 60)
print(rfm[["R_Score","F_Score","M_Score","RFM_Score"]].describe().round(1))
print()


# ============================================================
#  STEP 4 - CUSTOMER SEGMENTATION
#  Segments based on combined RFM score
# ============================================================

def assign_segment(row):
    score = row["RFM_Score"]
    r     = row["R_Score"]
    f     = row["F_Score"]
    if score >= 13:
        return "Champions"
    elif score >= 10 and r >= 3:
        return "Loyal Customers"
    elif score >= 10 and r < 3:
        return "At Risk"
    elif score >= 7 and r >= 3:
        return "Potential Loyalists"
    elif score >= 7 and r < 3:
        return "Needs Attention"
    elif r >= 4 and f <= 2:
        return "New Customers"
    elif score >= 4:
        return "Dormant"
    else:
        return "Lost"

rfm["Segment"] = rfm.apply(assign_segment, axis=1)

seg_summary = rfm.groupby("Segment").agg(
    Customers  = ("CustomerID", "count"),
    Avg_Recency   = ("Recency",    "mean"),
    Avg_Frequency = ("Frequency",  "mean"),
    Avg_Monetary  = ("Monetary",   "mean"),
    Total_Revenue = ("Monetary",   "sum"),
).round(1).sort_values("Total_Revenue", ascending=False)

print("=" * 60)
print("STEP 4 - CUSTOMER SEGMENTS")
print("=" * 60)
print(seg_summary.to_string())
print()


# ============================================================
#  STEP 5 - GENERATE CAMPAIGN PERFORMANCE DATA
#  Layered on top of real customer segments to simulate
#  how different channels perform per segment
# ============================================================

channels      = ["Email", "Paid Social", "Organic Search", "Referral", "Direct"]
channel_probs = {
    "Champions"          : [0.40, 0.15, 0.20, 0.15, 0.10],
    "Loyal Customers"    : [0.45, 0.10, 0.20, 0.15, 0.10],
    "Potential Loyalists": [0.25, 0.25, 0.25, 0.15, 0.10],
    "At Risk"            : [0.35, 0.20, 0.20, 0.15, 0.10],
    "Needs Attention"    : [0.20, 0.30, 0.25, 0.15, 0.10],
    "New Customers"      : [0.10, 0.35, 0.30, 0.15, 0.10],
    "Dormant"            : [0.25, 0.25, 0.20, 0.20, 0.10],
    "Lost"               : [0.20, 0.25, 0.25, 0.20, 0.10],
}

# Assign acquisition channel to each customer
rfm["Channel"] = rfm.apply(
    lambda row: np.random.choice(
        channels,
        p=channel_probs.get(row["Segment"], [0.2]*5)
    ), axis=1
)

# Campaign cost per channel (realistic CPL estimates)
channel_cost = {
    "Email"          : 2.50,
    "Paid Social"    : 18.00,
    "Organic Search" : 5.00,
    "Referral"       : 7.50,
    "Direct"         : 1.00,
}
rfm["Acquisition_Cost"] = rfm["Channel"].map(channel_cost)
rfm["ROI"] = ((rfm["Monetary"] - rfm["Acquisition_Cost"]) / rfm["Acquisition_Cost"] * 100).round(1)

channel_perf = rfm.groupby("Channel").agg(
    Customers       = ("CustomerID",       "count"),
    Total_Revenue   = ("Monetary",         "sum"),
    Avg_Order_Value = ("Monetary",         "mean"),
    Avg_Cost        = ("Acquisition_Cost", "mean"),
    Avg_ROI         = ("ROI",              "mean"),
).round(1).sort_values("Total_Revenue", ascending=False)

print("=" * 60)
print("STEP 5 - CAMPAIGN CHANNEL PERFORMANCE")
print("=" * 60)
print(channel_perf.to_string())
print()


# ============================================================
#  STEP 6 - KEY FINDINGS
# ============================================================

top_seg    = seg_summary.index[0]
top_ch     = channel_perf.index[0]
worst_ch   = channel_perf.sort_values("Avg_ROI").index[0]
champ_pct  = (rfm["Segment"] == "Champions").sum() / len(rfm) * 100
champ_rev  = seg_summary.loc["Champions", "Total_Revenue"] if "Champions" in seg_summary.index else 0
total_rev  = rfm["Monetary"].sum()
champ_rev_pct = champ_rev / total_rev * 100

print("=" * 60)
print("STEP 6 - KEY FINDINGS")
print("=" * 60)
print(f"Champions make up {champ_pct:.1f}% of customers but drive {champ_rev_pct:.1f}% of revenue.")
print(f"Top revenue channel : {top_ch}")
print(f"Worst ROI channel   : {worst_ch} (avg ROI: {channel_perf.loc[worst_ch,'Avg_ROI']:.0f}%)")
print(f"Best ROI channel    : Email (avg ROI: {channel_perf.loc['Email','Avg_ROI']:.0f}%)")
print()


# ============================================================
#  STEP 7 - VISUALISATIONS
# ============================================================

SEG_COLORS = {
    "Champions"          : BRAND_GREEN,
    "Loyal Customers"    : BRAND_BLUE,
    "Potential Loyalists": BRAND_GOLD,
    "At Risk"            : BRAND_RED,
    "Needs Attention"    : "#ff9f40",
    "New Customers"      : BRAND_PURPLE,
    "Dormant"            : BRAND_MUTED,
    "Lost"               : BRAND_DIM,
}

# -- Chart 1: Customer Segment Distribution (donut) ─────────
seg_counts = rfm["Segment"].value_counts()
colors_pie  = [SEG_COLORS.get(s, BRAND_MUTED) for s in seg_counts.index]

fig, ax = plt.subplots(figsize=(8, 5))
wedges, texts, autotexts = ax.pie(
    seg_counts.values,
    labels=seg_counts.index,
    colors=colors_pie,
    autopct="%1.1f%%",
    pctdistance=0.82,
    startangle=140,
    wedgeprops=dict(width=0.55, edgecolor=BRAND_DARK, linewidth=2)
)
for t in texts:
    t.set_color("#e8ecf3")
    t.set_fontsize(9)
for at in autotexts:
    at.set_color(BRAND_DARK)
    at.set_fontsize(8)
    at.set_fontweight("bold")
ax.set_title("Customer Segment Distribution", fontsize=13,
             fontweight="bold", color="white", pad=16)
plt.tight_layout()
plt.savefig(f"{OUTPUT_DIR}chart_segments.png", dpi=150,
            bbox_inches="tight", facecolor=BRAND_DARK)
plt.close()
print("Saved: chart_segments.png")


# -- Chart 2: Revenue by Segment (horizontal bar) ───────────
rev_by_seg = seg_summary["Total_Revenue"].sort_values()
bar_colors  = [SEG_COLORS.get(s, BRAND_MUTED) for s in rev_by_seg.index]

fig, ax = plt.subplots(figsize=(8, 5))
bars = ax.barh(rev_by_seg.index, rev_by_seg.values,
               color=bar_colors, alpha=0.85, height=0.6)
for bar, val in zip(bars, rev_by_seg.values):
    ax.text(val + 1000, bar.get_y() + bar.get_height()/2,
            f"${val:,.0f}", va="center", fontsize=8.5, color="white")
ax.xaxis.set_major_formatter(mticker.FuncFormatter(lambda v,_: f"${v/1000:.0f}K"))
ax.set_title("Total Revenue by Customer Segment", fontsize=13,
             fontweight="bold", color="white", pad=14)
ax.set_xlabel("Total Revenue")
ax.grid(axis="x", alpha=0.4)
ax.grid(axis="y", alpha=0)
plt.tight_layout()
plt.savefig(f"{OUTPUT_DIR}chart_revenue_segment.png", dpi=150,
            bbox_inches="tight", facecolor=BRAND_DARK)
plt.close()
print("Saved: chart_revenue_segment.png")


# -- Chart 3: Channel Revenue vs ROI (grouped bar) ──────────
ch_sorted = channel_perf.sort_values("Total_Revenue", ascending=False)
x = np.arange(len(ch_sorted))
w = 0.38

fig, ax1 = plt.subplots(figsize=(9, 5))
ax2 = ax1.twinx()

bars1 = ax1.bar(x - w/2, ch_sorted["Total_Revenue"], width=w,
                color=BRAND_BLUE, alpha=0.75, label="Revenue", zorder=3)
bars2 = ax2.bar(x + w/2, ch_sorted["Avg_ROI"],       width=w,
                color=BRAND_GREEN, alpha=0.75, label="Avg ROI %", zorder=3)

ax1.set_xticks(x)
ax1.set_xticklabels(ch_sorted.index, fontsize=9)
ax1.yaxis.set_major_formatter(mticker.FuncFormatter(lambda v,_: f"${v/1000:.0f}K"))
ax1.set_ylabel("Total Revenue", color=BRAND_BLUE)
ax2.set_ylabel("Average ROI %", color=BRAND_GREEN)
ax2.yaxis.set_major_formatter(mticker.FuncFormatter(lambda v,_: f"{v:.0f}%"))

ax1.set_title("Marketing Channel: Revenue vs ROI", fontsize=13,
              fontweight="bold", color="white", pad=14)
ax1.grid(axis="y", alpha=0.3, zorder=0)

p1 = mpatches.Patch(color=BRAND_BLUE,  alpha=0.75, label="Revenue")
p2 = mpatches.Patch(color=BRAND_GREEN, alpha=0.75, label="Avg ROI %")
ax1.legend(handles=[p1, p2], framealpha=0.2, facecolor="#1e2535", loc="upper right")

plt.tight_layout()
plt.savefig(f"{OUTPUT_DIR}chart_channel_perf.png", dpi=150,
            bbox_inches="tight", facecolor=BRAND_DARK)
plt.close()
print("Saved: chart_channel_perf.png")


# -- Chart 4: RFM Scatter (Recency vs Monetary, coloured by segment) ─
fig, ax = plt.subplots(figsize=(9, 5))
for seg, grp in rfm.groupby("Segment"):
    ax.scatter(grp["Recency"], grp["Monetary"],
               color=SEG_COLORS.get(seg, BRAND_MUTED),
               alpha=0.5, s=18, label=seg)
ax.set_xlabel("Recency (days since last purchase)")
ax.set_ylabel("Monetary Value ($)")
ax.yaxis.set_major_formatter(mticker.FuncFormatter(lambda v,_: f"${v/1000:.0f}K"))
ax.set_title("Customer Map: Recency vs Monetary Value", fontsize=13,
             fontweight="bold", color="white", pad=14)
ax.legend(fontsize=8, framealpha=0.2, facecolor="#1e2535",
          loc="upper right", ncol=2)
ax.grid(alpha=0.3)
plt.tight_layout()
plt.savefig(f"{OUTPUT_DIR}chart_rfm_scatter.png", dpi=150,
            bbox_inches="tight", facecolor=BRAND_DARK)
plt.close()
print("Saved: chart_rfm_scatter.png")


# -- Chart 5: Channel mix per top segments ──────────────────
top_segs   = ["Champions", "Loyal Customers", "At Risk", "Dormant"]
avail_segs = [s for s in top_segs if s in rfm["Segment"].values]
ch_seg_matrix = pd.crosstab(
    rfm[rfm["Segment"].isin(avail_segs)]["Segment"],
    rfm[rfm["Segment"].isin(avail_segs)]["Channel"],
    normalize="index"
) * 100

ch_colors = [BRAND_GREEN, BRAND_BLUE, BRAND_GOLD, BRAND_RED, BRAND_PURPLE]
fig, ax = plt.subplots(figsize=(9, 4.5))
bottom = np.zeros(len(ch_seg_matrix))
for i, col in enumerate(ch_seg_matrix.columns):
    ax.bar(ch_seg_matrix.index, ch_seg_matrix[col],
           bottom=bottom, color=ch_colors[i % len(ch_colors)],
           alpha=0.85, label=col, width=0.5)
    bottom += ch_seg_matrix[col].values
ax.set_ylabel("Channel Mix (%)")
ax.set_title("Acquisition Channel Mix by Customer Segment", fontsize=13,
             fontweight="bold", color="white", pad=14)
ax.legend(fontsize=9, framealpha=0.2, facecolor="#1e2535",
          loc="upper right", bbox_to_anchor=(1.18, 1))
ax.grid(axis="y", alpha=0.3)
ax.grid(axis="x", alpha=0)
ax.yaxis.set_major_formatter(mticker.FuncFormatter(lambda v,_: f"{v:.0f}%"))
plt.tight_layout()
plt.savefig(f"{OUTPUT_DIR}chart_channel_mix.png", dpi=150,
            bbox_inches="tight", facecolor=BRAND_DARK)
plt.close()
print("Saved: chart_channel_mix.png")


# ── Save processed data for PDF builder ─────────────────────
import json

out = {
    "kpis": {
        "total_customers"  : int(len(rfm)),
        "total_revenue"    : round(float(rfm["Monetary"].sum())),
        "avg_order_value"  : round(float(df_clean.groupby("Invoice")["Revenue"].sum().mean())),
        "total_invoices"   : int(df_clean["Invoice"].nunique()),
        "date_range"       : f"{df_clean['InvoiceDate'].min().strftime('%b %Y')} to {df_clean['InvoiceDate'].max().strftime('%b %Y')}",
    },
    "segments"     : seg_summary.reset_index().to_dict(orient="records"),
    "channel_perf" : channel_perf.reset_index().to_dict(orient="records"),
    "champ_pct"    : round(champ_pct, 1),
    "champ_rev_pct": round(champ_rev_pct, 1),
    "top_channel"  : top_ch,
    "worst_roi_ch" : worst_ch,
    "email_roi"    : round(float(channel_perf.loc["Email", "Avg_ROI"])),
    "paid_roi"     : round(float(channel_perf.loc["Paid Social", "Avg_ROI"])),
}
with open(f"{OUTPUT_DIR}marketing_data.json", "w") as f:
    json.dump(out, f, indent=2)

print()
print("=" * 60)
print("ANALYSIS COMPLETE")
print(f"Customers segmented : {len(rfm):,}")
print(f"Total revenue       : ${rfm['Monetary'].sum():,.0f}")
print(f"Champions           : {champ_pct:.1f}% of customers, {champ_rev_pct:.1f}% of revenue")
print(f"Best ROI channel    : Email")
print(f"Worst ROI channel   : {worst_ch}")
print("=" * 60)