Marketing Analyst

#!/usr/bin/env python3
"""Channel Mix Optimizer - Optimize marketing budget allocation across channels.

Analyzes channel performance data (spend, leads, revenue) and recommends
optimal budget reallocation to maximize ROI.

Usage:
    python channel_mix_optimizer.py channels.json
    python channel_mix_optimizer.py channels.json --budget 100000 --json
    python channel_mix_optimizer.py --demo
"""

import argparse
import json
import sys


def analyze_channels(channels, total_budget=None):
    """Analyze channel performance and recommend budget allocation."""
    results = []
    total_spend = sum(ch.get("spend", 0) for ch in channels)
    total_leads = sum(ch.get("leads", 0) for ch in channels)
    total_revenue = sum(ch.get("revenue", 0) for ch in channels)

    if total_budget is None:
        total_budget = total_spend

    for ch in channels:
        name = ch.get("name", ch.get("channel", "Unknown"))
        spend = ch.get("spend", 0)
        leads = ch.get("leads", 0)
        revenue = ch.get("revenue", 0)
        customers = ch.get("customers", 0)
        impressions = ch.get("impressions", 0)
        clicks = ch.get("clicks", 0)

        # Calculate metrics
        cpl = spend / max(leads, 1)
        cac = spend / max(customers, 1) if customers else None
        roas = revenue / max(spend, 1)
        roi = ((revenue - spend) / max(spend, 1)) * 100
        ctr = (clicks / max(impressions, 1)) * 100 if impressions else None
        conversion_rate = (leads / max(clicks, 1)) * 100 if clicks else None
        spend_share = (spend / max(total_spend, 1)) * 100
        revenue_share = (revenue / max(total_revenue, 1)) * 100
        efficiency_index = revenue_share / max(spend_share, 0.1)

        results.append({
            "channel": name,
            "spend": spend,
            "leads": leads,
            "revenue": revenue,
            "customers": customers,
            "cpl": round(cpl, 2),
            "cac": round(cac, 2) if cac else None,
            "roas": round(roas, 2),
            "roi": round(roi, 1),
            "ctr": round(ctr, 2) if ctr else None,
            "conversion_rate": round(conversion_rate, 2) if conversion_rate else None,
            "spend_share": round(spend_share, 1),
            "revenue_share": round(revenue_share, 1),
            "efficiency_index": round(efficiency_index, 2),
        })

    # Rank by efficiency
    results.sort(key=lambda x: x["efficiency_index"], reverse=True)

    # Calculate optimal allocation
    # Weighted by efficiency index
    total_efficiency = sum(r["efficiency_index"] for r in results)
    recommendations = []

    for r in results:
        weight = r["efficiency_index"] / max(total_efficiency, 0.01)
        # Blend current allocation with efficiency-based allocation (70/30)
        current_share = r["spend_share"] / 100
        optimal_share = weight
        recommended_share = (current_share * 0.3 + optimal_share * 0.7)

        recommended_budget = int(total_budget * recommended_share)
        budget_change = recommended_budget - r["spend"]
        change_pct = ((recommended_budget - r["spend"]) / max(r["spend"], 1)) * 100

        # Project ROI at new budget (linear assumption with diminishing returns)
        diminishing_factor = 0.85 if budget_change > 0 else 1.1
        projected_revenue = r["revenue"] * (recommended_budget / max(r["spend"], 1)) * diminishing_factor
        projected_roas = projected_revenue / max(recommended_budget, 1)

        recommendations.append({
            "channel": r["channel"],
            "current_budget": r["spend"],
            "recommended_budget": recommended_budget,
            "budget_change": budget_change,
            "change_pct": round(change_pct, 1),
            "current_roas": r["roas"],
            "projected_roas": round(projected_roas, 2),
            "efficiency_rank": results.index(r) + 1,
            "action": "increase" if budget_change > 0 else ("decrease" if budget_change < 0 else "maintain"),
        })

    # Normalize recommendations to total budget
    total_recommended = sum(r["recommended_budget"] for r in recommendations)
    if total_recommended > 0:
        scale_factor = total_budget / total_recommended
        for r in recommendations:
            r["recommended_budget"] = int(r["recommended_budget"] * scale_factor)
            r["budget_change"] = r["recommended_budget"] - [ch for ch in results if ch["channel"] == r["channel"]][0]["spend"]

    # Summary
    current_total_roas = total_revenue / max(total_spend, 1)
    projected_total_revenue = sum(
        r["projected_roas"] * r["recommended_budget"] for r in recommendations
    )
    projected_total_roas = projected_total_revenue / max(total_budget, 1)

    return {
        "summary": {
            "total_budget": total_budget,
            "current_spend": total_spend,
            "total_leads": total_leads,
            "total_revenue": total_revenue,
            "current_roas": round(current_total_roas, 2),
            "projected_roas": round(projected_total_roas, 2),
            "projected_revenue": round(projected_total_revenue, 2),
            "revenue_improvement": round(
                ((projected_total_revenue - total_revenue) / max(total_revenue, 1)) * 100, 1
            ),
        },
        "channels": results,
        "recommendations": sorted(recommendations, key=lambda x: x["budget_change"], reverse=True),
    }


def get_demo_data():
    return [
        {"name": "Paid Search", "spend": 45000, "leads": 520, "revenue": 180000, "customers": 52, "impressions": 250000, "clicks": 12500},
        {"name": "LinkedIn Ads", "spend": 30000, "leads": 310, "revenue": 145000, "customers": 35, "impressions": 180000, "clicks": 5400},
        {"name": "Email Marketing", "spend": 5000, "leads": 380, "revenue": 120000, "customers": 40, "impressions": 0, "clicks": 0},
        {"name": "Content/SEO", "spend": 12000, "leads": 250, "revenue": 95000, "customers": 28, "impressions": 0, "clicks": 0},
        {"name": "Display Ads", "spend": 15000, "leads": 90, "revenue": 22000, "customers": 8, "impressions": 500000, "clicks": 3500},
        {"name": "Social Organic", "spend": 3000, "leads": 120, "revenue": 38000, "customers": 15, "impressions": 100000, "clicks": 8000},
    ]


def format_report(analysis):
    """Format human-readable report."""
    lines = []
    lines.append("=" * 75)
    lines.append("CHANNEL MIX OPTIMIZATION REPORT")
    lines.append("=" * 75)

    s = analysis["summary"]
    lines.append(f"Total Budget:        ${s['total_budget']:,.0f}")
    lines.append(f"Current ROAS:        {s['current_roas']:.1f}x")
    lines.append(f"Projected ROAS:      {s['projected_roas']:.1f}x")
    lines.append(f"Revenue Improvement: {s['revenue_improvement']:+.1f}%")
    lines.append("")

    # Channel performance
    lines.append("--- CHANNEL PERFORMANCE (ranked by efficiency) ---")
    lines.append(f"{'Channel':<20} {'Spend':>10} {'Revenue':>10} {'ROAS':>6} {'CPL':>8} {'Efficiency':>10}")
    lines.append("-" * 70)
    for ch in analysis["channels"]:
        lines.append(
            f"{ch['channel']:<20} ${ch['spend']:>9,} ${ch['revenue']:>9,} "
            f"{ch['roas']:>5.1f}x ${ch['cpl']:>7,.0f} {ch['efficiency_index']:>10.2f}"
        )
    lines.append("")

    # Recommendations
    lines.append("--- BUDGET RECOMMENDATIONS ---")
    lines.append(f"{'Channel':<20} {'Current':>10} {'Recommended':>12} {'Change':>10} {'Action':>10}")
    lines.append("-" * 65)
    for r in analysis["recommendations"]:
        lines.append(
            f"{r['channel']:<20} ${r['current_budget']:>9,} ${r['recommended_budget']:>11,} "
            f"{r['change_pct']:>+9.0f}% {r['action']:>10}"
        )

    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(description="Optimize marketing budget allocation across channels")
    parser.add_argument("input", nargs="?", help="JSON file with channel performance data")
    parser.add_argument("--budget", type=float, help="Total budget to allocate")
    parser.add_argument("--json", action="store_true", dest="json_output", help="Output JSON")
    parser.add_argument("--demo", action="store_true", help="Run with demo data")
    args = parser.parse_args()

    if args.demo:
        channels = get_demo_data()
    elif args.input:
        try:
            with open(args.input, "r", encoding="utf-8") as f:
                data = json.load(f)
            channels = data if isinstance(data, list) else data.get("channels", [])
        except FileNotFoundError:
            print(f"Error: File not found: {args.input}", file=sys.stderr)
            sys.exit(1)
    else:
        parser.print_help()
        sys.exit(1)

    analysis = analyze_channels(channels, args.budget)

    if args.json_output:
        print(json.dumps(analysis, indent=2))
    else:
        print(format_report(analysis))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Cohort Analyzer - Analyze user retention and behavior by cohort.

Generates cohort retention tables, identifies trends, and calculates
key retention metrics (D1/D7/D30, average lifetime, LTV).

Usage:
    python cohort_analyzer.py cohort_data.json
    python cohort_analyzer.py cohort_data.json --json
    python cohort_analyzer.py --demo
"""

import argparse
import json
import sys


def analyze_cohorts(cohort_data):
    """Analyze cohort retention data."""
    cohorts = cohort_data if isinstance(cohort_data, list) else cohort_data.get("cohorts", [])

    results = []
    all_retention_by_period = {}

    for cohort in cohorts:
        name = cohort.get("name", cohort.get("cohort", "Unknown"))
        initial_users = cohort.get("initial_users", cohort.get("users", 0))
        retention = cohort.get("retention", cohort.get("active_users", []))

        # Calculate retention rates
        retention_rates = []
        for i, active in enumerate(retention):
            rate = (active / max(initial_users, 1)) * 100
            retention_rates.append({
                "period": i,
                "active_users": active,
                "retention_rate": round(rate, 1),
                "churned": initial_users - active if i == 0 else retention[i - 1] - active,
            })

            if i not in all_retention_by_period:
                all_retention_by_period[i] = []
            all_retention_by_period[i].append(rate)

        # Key retention milestones
        d1 = retention_rates[1]["retention_rate"] if len(retention_rates) > 1 else None
        d7 = retention_rates[7]["retention_rate"] if len(retention_rates) > 7 else None
        d30 = retention_rates[30]["retention_rate"] if len(retention_rates) > 30 else None
        w1 = retention_rates[1]["retention_rate"] if len(retention_rates) > 1 else None

        # Calculate average lifetime (simplified)
        total_active_periods = sum(r["active_users"] for r in retention_rates)
        avg_lifetime = total_active_periods / max(initial_users, 1)

        results.append({
            "cohort": name,
            "initial_users": initial_users,
            "retention_rates": retention_rates,
            "milestones": {
                "period_1": round(d1, 1) if d1 else None,
                "period_7": round(d7, 1) if d7 else None,
                "period_30": round(d30, 1) if d30 else None,
            },
            "avg_lifetime_periods": round(avg_lifetime, 1),
            "final_retention": retention_rates[-1]["retention_rate"] if retention_rates else 0,
        })

    # Cross-cohort trend analysis
    trends = {}
    for period, rates in all_retention_by_period.items():
        if len(rates) >= 2:
            trends[period] = {
                "avg_retention": round(sum(rates) / len(rates), 1),
                "min_retention": round(min(rates), 1),
                "max_retention": round(max(rates), 1),
                "improving": rates[-1] > rates[0] if len(rates) >= 2 else None,
            }

    # Identify best and worst cohorts
    if results:
        final_retentions = [(r["cohort"], r["final_retention"]) for r in results]
        best_cohort = max(final_retentions, key=lambda x: x[1])
        worst_cohort = min(final_retentions, key=lambda x: x[1])
    else:
        best_cohort = worst_cohort = None

    return {
        "cohorts": results,
        "trends": trends,
        "summary": {
            "total_cohorts": len(results),
            "best_cohort": {"name": best_cohort[0], "final_retention": best_cohort[1]} if best_cohort else None,
            "worst_cohort": {"name": worst_cohort[0], "final_retention": worst_cohort[1]} if worst_cohort else None,
            "avg_final_retention": round(
                sum(r["final_retention"] for r in results) / max(len(results), 1), 1
            ),
        },
    }


def get_demo_data():
    return {
        "cohorts": [
            {"name": "Jan W1", "initial_users": 1000, "retention": [1000, 450, 350, 280, 250]},
            {"name": "Jan W2", "initial_users": 1100, "retention": [1100, 528, 418, 352, 308]},
            {"name": "Jan W3", "initial_users": 950, "retention": [950, 494, 399, 333, 295]},
            {"name": "Jan W4", "initial_users": 1050, "retention": [1050, 578, 473, 399, 357]},
            {"name": "Feb W1", "initial_users": 1200, "retention": [1200, 684, 564, 480, 432]},
        ],
    }


def format_report(analysis):
    """Format human-readable cohort report."""
    lines = []
    lines.append("=" * 70)
    lines.append("COHORT RETENTION ANALYSIS")
    lines.append("=" * 70)

    s = analysis["summary"]
    lines.append(f"Cohorts Analyzed:       {s['total_cohorts']}")
    lines.append(f"Avg Final Retention:    {s['avg_final_retention']:.1f}%")
    if s["best_cohort"]:
        lines.append(f"Best Cohort:            {s['best_cohort']['name']} ({s['best_cohort']['final_retention']:.1f}%)")
    if s["worst_cohort"]:
        lines.append(f"Worst Cohort:           {s['worst_cohort']['name']} ({s['worst_cohort']['final_retention']:.1f}%)")
    lines.append("")

    # Retention table
    if analysis["cohorts"]:
        max_periods = max(len(c["retention_rates"]) for c in analysis["cohorts"])
        period_headers = [f"P{i}" for i in range(min(max_periods, 8))]

        lines.append("--- RETENTION TABLE (%) ---")
        header = f"{'Cohort':<12} {'Users':>6} " + " ".join(f"{h:>6}" for h in period_headers)
        lines.append(header)
        lines.append("-" * len(header))

        for cohort in analysis["cohorts"]:
            rates = [f"{r['retention_rate']:>5.1f}%" for r in cohort["retention_rates"][:8]]
            line = f"{cohort['cohort']:<12} {cohort['initial_users']:>6} " + " ".join(rates)
            lines.append(line)
        lines.append("")

    # Trends
    if analysis["trends"]:
        lines.append("--- PERIOD TRENDS ---")
        for period, trend in sorted(analysis["trends"].items()):
            if period < 8:
                improving = "improving" if trend.get("improving") else "declining" if trend.get("improving") is False else "stable"
                lines.append(
                    f"  Period {period}: avg {trend['avg_retention']:.1f}% "
                    f"(range: {trend['min_retention']:.1f}%-{trend['max_retention']:.1f}%) [{improving}]"
                )

    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(description="Analyze user retention by cohort")
    parser.add_argument("input", nargs="?", help="JSON file with cohort data")
    parser.add_argument("--json", action="store_true", dest="json_output", help="Output JSON")
    parser.add_argument("--demo", action="store_true", help="Run with demo data")
    args = parser.parse_args()

    if args.demo:
        data = get_demo_data()
    elif args.input:
        try:
            with open(args.input, "r", encoding="utf-8") as f:
                data = json.load(f)
        except FileNotFoundError:
            print(f"Error: File not found: {args.input}", file=sys.stderr)
            sys.exit(1)
    else:
        parser.print_help()
        sys.exit(1)

    analysis = analyze_cohorts(data)

    if args.json_output:
        print(json.dumps(analysis, indent=2))
    else:
        print(format_report(analysis))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Marketing Forecast Generator - Generate marketing performance forecasts.

Uses historical data to project leads, revenue, and pipeline using
linear regression, moving averages, and growth rate extrapolation.

Usage:
    python marketing_forecast_generator.py historical.json --periods 6
    python marketing_forecast_generator.py historical.json --periods 6 --json
    python marketing_forecast_generator.py --demo
"""

import argparse
import json
import sys
import math


def linear_regression(x_vals, y_vals):
    """Simple linear regression returning slope and intercept."""
    n = len(x_vals)
    if n < 2:
        return 0, y_vals[0] if y_vals else 0

    sum_x = sum(x_vals)
    sum_y = sum(y_vals)
    sum_xy = sum(x * y for x, y in zip(x_vals, y_vals))
    sum_x2 = sum(x * x for x in x_vals)

    denom = n * sum_x2 - sum_x * sum_x
    if denom == 0:
        return 0, sum_y / n

    slope = (n * sum_xy - sum_x * sum_y) / denom
    intercept = (sum_y - slope * sum_x) / n

    return slope, intercept


def moving_average(values, window=3):
    """Calculate moving average forecast."""
    if len(values) < window:
        return sum(values) / max(len(values), 1)
    return sum(values[-window:]) / window


def growth_rate_forecast(values, periods):
    """Forecast using compound growth rate."""
    if len(values) < 2:
        return [values[-1] if values else 0] * periods

    # Calculate average period-over-period growth
    growth_rates = []
    for i in range(1, len(values)):
        if values[i - 1] > 0:
            rate = (values[i] - values[i - 1]) / values[i - 1]
            growth_rates.append(rate)

    if not growth_rates:
        return [values[-1]] * periods

    avg_growth = sum(growth_rates) / len(growth_rates)
    # Dampen growth rate for longer forecasts
    forecasts = []
    last_val = values[-1]
    for i in range(periods):
        dampened_growth = avg_growth * (0.95 ** i)  # 5% dampening per period
        next_val = last_val * (1 + dampened_growth)
        forecasts.append(round(next_val, 2))
        last_val = next_val

    return forecasts


def generate_forecast(historical_data, forecast_periods=6):
    """Generate multi-method forecast from historical data."""
    metrics = {}

    # Handle different input formats
    if isinstance(historical_data, list):
        # List of period objects
        for period in historical_data:
            for key, value in period.items():
                if key in ("period", "month", "date", "label"):
                    continue
                if isinstance(value, (int, float)):
                    if key not in metrics:
                        metrics[key] = []
                    metrics[key].append(value)
    elif isinstance(historical_data, dict):
        for key, values in historical_data.items():
            if isinstance(values, list) and all(isinstance(v, (int, float)) for v in values):
                metrics[key] = values

    results = {}
    for metric_name, values in metrics.items():
        x_vals = list(range(len(values)))
        n = len(values)

        # Method 1: Linear regression
        slope, intercept = linear_regression(x_vals, values)
        linear_forecast = [round(slope * (n + i) + intercept, 2) for i in range(forecast_periods)]

        # Method 2: Moving average
        ma_value = moving_average(values)
        ma_forecast = [round(ma_value, 2)] * forecast_periods

        # Method 3: Growth rate
        growth_forecast_vals = growth_rate_forecast(values, forecast_periods)

        # Ensemble: weighted average of methods
        ensemble = []
        for i in range(forecast_periods):
            avg = (linear_forecast[i] * 0.4 + growth_forecast_vals[i] * 0.4 + ma_forecast[i] * 0.2)
            ensemble.append(round(max(0, avg), 2))

        # Confidence intervals (simple approach: +/- based on historical variance)
        if len(values) > 2:
            mean = sum(values) / len(values)
            variance = sum((v - mean) ** 2 for v in values) / len(values)
            std_dev = math.sqrt(variance)
            ci_low = [round(max(0, e - 1.96 * std_dev * (1 + i * 0.1)), 2) for i, e in enumerate(ensemble)]
            ci_high = [round(e + 1.96 * std_dev * (1 + i * 0.1), 2) for i, e in enumerate(ensemble)]
        else:
            ci_low = [round(e * 0.8, 2) for e in ensemble]
            ci_high = [round(e * 1.2, 2) for e in ensemble]

        # Historical stats
        avg_val = sum(values) / max(len(values), 1)
        total_growth = ((values[-1] - values[0]) / max(values[0], 1) * 100) if len(values) > 1 else 0

        results[metric_name] = {
            "historical": values,
            "historical_stats": {
                "count": len(values),
                "mean": round(avg_val, 2),
                "min": min(values),
                "max": max(values),
                "total_growth_pct": round(total_growth, 1),
                "avg_period_growth": round(total_growth / max(len(values) - 1, 1), 1),
            },
            "forecast": {
                "ensemble": ensemble,
                "linear": linear_forecast,
                "growth_rate": growth_forecast_vals,
                "moving_average": ma_forecast,
                "confidence_low": ci_low,
                "confidence_high": ci_high,
            },
            "forecast_periods": forecast_periods,
        }

    return results


def get_demo_data():
    return [
        {"month": "Sep", "leads": 850, "revenue": 125000, "pipeline": 380000},
        {"month": "Oct", "leads": 920, "revenue": 138000, "pipeline": 415000},
        {"month": "Nov", "leads": 1050, "revenue": 152000, "pipeline": 460000},
        {"month": "Dec", "leads": 980, "revenue": 145000, "pipeline": 435000},
        {"month": "Jan", "leads": 1120, "revenue": 168000, "pipeline": 505000},
        {"month": "Feb", "leads": 1250, "revenue": 185000, "pipeline": 555000},
    ]


def format_report(results):
    """Format human-readable forecast."""
    lines = []
    lines.append("=" * 70)
    lines.append("MARKETING FORECAST REPORT")
    lines.append("=" * 70)

    for metric_name, data in results.items():
        label = metric_name.replace("_", " ").title()
        lines.append(f"\n--- {label} ---")
        stats = data["historical_stats"]
        lines.append(f"  Historical: {stats['count']} periods, mean={stats['mean']:,.0f}, growth={stats['total_growth_pct']:+.1f}%")

        lines.append(f"  {'Period':>8} {'Forecast':>12} {'Low':>12} {'High':>12}")
        lines.append("  " + "-" * 50)

        for i in range(data["forecast_periods"]):
            f_val = data["forecast"]["ensemble"][i]
            low = data["forecast"]["confidence_low"][i]
            high = data["forecast"]["confidence_high"][i]
            lines.append(f"  {f'P+{i+1}':>8} {f_val:>12,.0f} {low:>12,.0f} {high:>12,.0f}")

    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(description="Generate marketing performance forecasts")
    parser.add_argument("input", nargs="?", help="JSON file with historical data")
    parser.add_argument("--periods", type=int, default=6, help="Forecast periods")
    parser.add_argument("--json", action="store_true", dest="json_output", help="Output JSON")
    parser.add_argument("--demo", action="store_true", help="Run with demo data")
    args = parser.parse_args()

    if args.demo:
        data = get_demo_data()
    elif args.input:
        try:
            with open(args.input, "r", encoding="utf-8") as f:
                data = json.load(f)
        except FileNotFoundError:
            print(f"Error: File not found: {args.input}", file=sys.stderr)
            sys.exit(1)
    else:
        parser.print_help()
        sys.exit(1)

    results = generate_forecast(data, args.periods)

    if args.json_output:
        print(json.dumps(results, indent=2))
    else:
        print(format_report(results))


if __name__ == "__main__":
    main()