fundedness 0.2.4__py3-none-any.whl

fundedness/viz/colors.py

@@ -0,0 +1,110 @@
+"""Color palette and styling constants for visualizations."""
+
+# Primary colors
+COLORS = {
+    # Blues for wealth/assets
+    "wealth_primary": "#3498db",
+    "wealth_secondary": "#2980b9",
+    "wealth_light": "#5dade2",
+    "wealth_dark": "#1a5276",
+
+    # Greens for spending/survival/positive outcomes
+    "success_primary": "#27ae60",
+    "success_secondary": "#2ecc71",
+    "success_light": "#58d68d",
+    "success_dark": "#1e8449",
+
+    # Reds for haircuts/negative outcomes
+    "danger_primary": "#e74c3c",
+    "danger_secondary": "#c0392b",
+    "danger_light": "#ec7063",
+    "danger_dark": "#922b21",
+
+    # Oranges for warnings/caution
+    "warning_primary": "#f39c12",
+    "warning_secondary": "#e67e22",
+    "warning_light": "#f5b041",
+    "warning_dark": "#b9770e",
+
+    # Purples for alternatives/special
+    "accent_primary": "#9b59b6",
+    "accent_secondary": "#8e44ad",
+    "accent_light": "#bb8fce",
+    "accent_dark": "#6c3483",
+
+    # Grays for neutral elements
+    "neutral_primary": "#7f8c8d",
+    "neutral_secondary": "#95a5a6",
+    "neutral_light": "#bdc3c7",
+    "neutral_dark": "#5d6d7e",
+
+    # Background colors
+    "background": "#ffffff",
+    "background_alt": "#f8f9fa",
+
+    # Text colors
+    "text_primary": "#2c3e50",
+    "text_secondary": "#7f8c8d",
+}
+
+# Fan chart percentile colors (gradient from optimistic to pessimistic)
+FAN_CHART_COLORS = {
+    "P90": "rgba(46, 204, 113, 0.3)",   # Light green (optimistic)
+    "P75": "rgba(46, 204, 113, 0.4)",
+    "P50": "rgba(52, 152, 219, 0.8)",   # Solid blue (median)
+    "P25": "rgba(231, 76, 60, 0.4)",
+    "P10": "rgba(231, 76, 60, 0.3)",    # Light red (pessimistic)
+}
+
+# Waterfall chart colors
+WATERFALL_COLORS = {
+    "increase": COLORS["success_primary"],
+    "decrease": COLORS["danger_primary"],
+    "total": COLORS["wealth_primary"],
+}
+
+# Strategy comparison colors (for withdrawal lab)
+STRATEGY_COLORS = [
+    COLORS["wealth_primary"],
+    COLORS["success_primary"],
+    COLORS["accent_primary"],
+    COLORS["warning_primary"],
+    COLORS["danger_primary"],
+]
+
+# Default Plotly template settings
+TEMPLATE_SETTINGS = {
+    "template": "plotly_white",
+    "font_family": "Inter, system-ui, -apple-system, sans-serif",
+    "title_font_size": 18,
+    "axis_font_size": 12,
+    "legend_font_size": 11,
+}
+
+
+def get_plotly_layout_defaults() -> dict:
+    """Get default layout settings for consistent styling."""
+    return {
+        "template": TEMPLATE_SETTINGS["template"],
+        "font": {
+            "family": TEMPLATE_SETTINGS["font_family"],
+            "size": TEMPLATE_SETTINGS["axis_font_size"],
+            "color": COLORS["text_primary"],
+        },
+        "title": {
+            "font": {
+                "size": TEMPLATE_SETTINGS["title_font_size"],
+                "color": COLORS["text_primary"],
+            },
+            "x": 0.5,
+            "xanchor": "center",
+        },
+        "paper_bgcolor": COLORS["background"],
+        "plot_bgcolor": COLORS["background"],
+        "margin": {"l": 60, "r": 40, "t": 60, "b": 60},
+        "hoverlabel": {
+            "bgcolor": COLORS["background"],
+            "font_size": 12,
+            "font_family": TEMPLATE_SETTINGS["font_family"],
+        },
+    }

fundedness/viz/comparison.py

@@ -0,0 +1,294 @@
+"""Strategy comparison visualizations."""
+
+from typing import Any
+
+import numpy as np
+import plotly.graph_objects as go
+from plotly.subplots import make_subplots
+
+from fundedness.viz.colors import COLORS, STRATEGY_COLORS, get_plotly_layout_defaults
+
+
+def create_strategy_comparison_chart(
+    years: np.ndarray,
+    strategies: dict[str, dict[str, np.ndarray]],
+    metric: str = "wealth_median",
+    title: str = "Strategy Comparison",
+    y_label: str = "Portfolio Value ($)",
+    height: int = 500,
+    width: int | None = None,
+) -> go.Figure:
+    """Create a line chart comparing multiple strategies.
+
+    Args:
+        years: Array of year values
+        strategies: Dictionary mapping strategy name to metrics dict
+            Each metrics dict should contain arrays for the requested metric
+        metric: Which metric to plot (e.g., "wealth_median", "spending_median")
+        title: Chart title
+        y_label: Y-axis label
+        height: Chart height in pixels
+        width: Chart width in pixels
+
+    Returns:
+        Plotly Figure object
+    """
+    fig = go.Figure()
+
+    for i, (name, metrics) in enumerate(strategies.items()):
+        if metric not in metrics:
+            continue
+
+        color = STRATEGY_COLORS[i % len(STRATEGY_COLORS)]
+
+        fig.add_trace(
+            go.Scatter(
+                x=years,
+                y=metrics[metric],
+                mode="lines",
+                name=name,
+                line={"color": color, "width": 2},
+                hovertemplate=(
+                    f"<b>{name}</b><br>"
+                    "Year: %{x}<br>"
+                    "Value: $%{y:,.0f}<br>"
+                    "<extra></extra>"
+                ),
+            )
+        )
+
+    # Apply layout
+    layout = get_plotly_layout_defaults()
+    layout.update({
+        "title": {"text": title},
+        "height": height,
+        "xaxis": {
+            "title": "Year",
+            "gridcolor": COLORS["neutral_light"],
+            "dtick": 5,
+        },
+        "yaxis": {
+            "title": y_label,
+            "tickformat": "$,.0f",
+            "gridcolor": COLORS["neutral_light"],
+        },
+        "legend": {
+            "orientation": "h",
+            "yanchor": "bottom",
+            "y": 1.02,
+            "xanchor": "right",
+            "x": 1,
+        },
+        "hovermode": "x unified",
+    })
+
+    if width:
+        layout["width"] = width
+
+    fig.update_layout(**layout)
+
+    return fig
+
+
+def create_strategy_metrics_table(
+    strategies: dict[str, dict[str, Any]],
+    metrics_to_show: list[str] | None = None,
+    title: str = "Strategy Metrics Summary",
+    height: int = 300,
+    width: int | None = None,
+) -> go.Figure:
+    """Create a table comparing strategy metrics.
+
+    Args:
+        strategies: Dictionary mapping strategy name to metrics dict
+        metrics_to_show: List of metric names to display
+        title: Chart title
+        height: Chart height in pixels
+        width: Chart width in pixels
+
+    Returns:
+        Plotly Figure object
+    """
+    if metrics_to_show is None:
+        metrics_to_show = [
+            "success_rate",
+            "median_terminal_wealth",
+            "median_spending",
+            "spending_volatility",
+            "worst_drawdown",
+        ]
+
+    metric_labels = {
+        "success_rate": "Success Rate",
+        "median_terminal_wealth": "Median Terminal Wealth",
+        "median_spending": "Median Spending",
+        "spending_volatility": "Spending Volatility",
+        "worst_drawdown": "Worst Drawdown",
+        "time_to_ruin_p10": "Time to Ruin (P10)",
+        "floor_breach_rate": "Floor Breach Rate",
+    }
+
+    metric_formats = {
+        "success_rate": lambda x: f"{x:.1%}",
+        "median_terminal_wealth": lambda x: f"${x:,.0f}",
+        "median_spending": lambda x: f"${x:,.0f}",
+        "spending_volatility": lambda x: f"{x:.1%}",
+        "worst_drawdown": lambda x: f"{x:.1%}",
+        "time_to_ruin_p10": lambda x: f"{x:.1f} years",
+        "floor_breach_rate": lambda x: f"{x:.1%}",
+    }
+
+    # Build table data
+    strategy_names = list(strategies.keys())
+    header_values = ["Metric"] + strategy_names
+
+    rows = []
+    for metric in metrics_to_show:
+        row = [metric_labels.get(metric, metric)]
+        formatter = metric_formats.get(metric, lambda x: f"{x:.2f}")
+
+        for name in strategy_names:
+            value = strategies[name].get(metric, None)
+            if value is not None:
+                row.append(formatter(value))
+            else:
+                row.append("N/A")
+        rows.append(row)
+
+    # Transpose for plotly table format
+    cell_values = list(zip(*rows))
+
+    fig = go.Figure(
+        data=[
+            go.Table(
+                header={
+                    "values": header_values,
+                    "fill_color": COLORS["wealth_primary"],
+                    "font": {"color": "white", "size": 12},
+                    "align": "center",
+                    "height": 30,
+                },
+                cells={
+                    "values": cell_values,
+                    "fill_color": [COLORS["background_alt"]] + [COLORS["background"]] * len(strategy_names),
+                    "font": {"color": COLORS["text_primary"], "size": 11},
+                    "align": ["left"] + ["center"] * len(strategy_names),
+                    "height": 25,
+                },
+            )
+        ]
+    )
+
+    layout = get_plotly_layout_defaults()
+    layout.update({
+        "title": {"text": title},
+        "height": height,
+        "margin": {"l": 20, "r": 20, "t": 60, "b": 20},
+    })
+
+    if width:
+        layout["width"] = width
+
+    fig.update_layout(**layout)
+
+    return fig
+
+
+def create_multi_metric_comparison(
+    years: np.ndarray,
+    strategies: dict[str, dict[str, np.ndarray]],
+    title: str = "Multi-Metric Strategy Comparison",
+    height: int = 800,
+    width: int | None = None,
+) -> go.Figure:
+    """Create a multi-panel chart comparing strategies across metrics.
+
+    Args:
+        years: Array of year values
+        strategies: Dictionary mapping strategy name to metrics dict
+        title: Chart title
+        height: Chart height in pixels
+        width: Chart width in pixels
+
+    Returns:
+        Plotly Figure object with subplots
+    """
+    fig = make_subplots(
+        rows=2,
+        cols=2,
+        subplot_titles=(
+            "Median Wealth",
+            "Median Spending",
+            "Survival Probability",
+            "Spending as % of Initial",
+        ),
+        vertical_spacing=0.12,
+        horizontal_spacing=0.1,
+    )
+
+    metrics_config = [
+        ("wealth_median", 1, 1, "$,.0f"),
+        ("spending_median", 1, 2, "$,.0f"),
+        ("survival_prob", 2, 1, ".0%"),
+        ("spending_ratio", 2, 2, ".1%"),
+    ]
+
+    for i, (name, metrics) in enumerate(strategies.items()):
+        color = STRATEGY_COLORS[i % len(STRATEGY_COLORS)]
+
+        for metric, row, col, fmt in metrics_config:
+            if metric not in metrics:
+                continue
+
+            values = metrics[metric]
+            if metric == "survival_prob":
+                values = values * 100  # Convert to percentage
+
+            fig.add_trace(
+                go.Scatter(
+                    x=years,
+                    y=values,
+                    mode="lines",
+                    name=name,
+                    line={"color": color, "width": 2},
+                    showlegend=(row == 1 and col == 1),  # Only show legend once
+                    hovertemplate=(
+                        f"<b>{name}</b><br>"
+                        "Year: %{x}<br>"
+                        "Value: %{y}<br>"
+                        "<extra></extra>"
+                    ),
+                ),
+                row=row,
+                col=col,
+            )
+
+    # Apply layout
+    layout = get_plotly_layout_defaults()
+    layout.update({
+        "title": {"text": title},
+        "height": height,
+        "legend": {
+            "orientation": "h",
+            "yanchor": "bottom",
+            "y": 1.02,
+            "xanchor": "right",
+            "x": 1,
+        },
+    })
+
+    if width:
+        layout["width"] = width
+
+    fig.update_layout(**layout)
+
+    # Update axes
+    fig.update_xaxes(title_text="Year", gridcolor=COLORS["neutral_light"])
+    fig.update_yaxes(gridcolor=COLORS["neutral_light"])
+
+    fig.update_yaxes(tickformat="$,.0f", row=1, col=1)
+    fig.update_yaxes(tickformat="$,.0f", row=1, col=2)
+    fig.update_yaxes(ticksuffix="%", row=2, col=1)
+    fig.update_yaxes(ticksuffix="%", row=2, col=2)
+
+    return fig

fundedness/viz/fan_chart.py

@@ -0,0 +1,193 @@
+"""Fan chart visualization for Monte Carlo projections."""
+
+import numpy as np
+import plotly.graph_objects as go
+
+from fundedness.viz.colors import COLORS, get_plotly_layout_defaults
+
+
+def create_fan_chart(
+    years: np.ndarray,
+    percentiles: dict[str, np.ndarray],
+    title: str = "Wealth Projection",
+    y_label: str = "Portfolio Value ($)",
+    show_median_line: bool = True,
+    show_floor: float | None = None,
+    height: int = 500,
+    width: int | None = None,
+) -> go.Figure:
+    """Create a fan chart showing percentile bands over time.
+
+    Args:
+        years: Array of year values (x-axis)
+        percentiles: Dictionary mapping percentile names to value arrays
+            Expected keys: "P10", "P25", "P50", "P75", "P90"
+        title: Chart title
+        y_label: Y-axis label
+        show_median_line: Whether to show a distinct median line
+        show_floor: Optional floor value to show as horizontal line
+        height: Chart height in pixels
+        width: Chart width in pixels (None = responsive)
+
+    Returns:
+        Plotly Figure object
+    """
+    fig = go.Figure()
+
+    # P10-P90 band (outermost)
+    if "P10" in percentiles and "P90" in percentiles:
+        fig.add_trace(
+            go.Scatter(
+                x=np.concatenate([years, years[::-1]]),
+                y=np.concatenate([percentiles["P90"], percentiles["P10"][::-1]]),
+                fill="toself",
+                fillcolor="rgba(52, 152, 219, 0.15)",
+                line={"width": 0},
+                name="P10-P90 Range",
+                hoverinfo="skip",
+                showlegend=True,
+            )
+        )
+
+    # P25-P75 band (middle)
+    if "P25" in percentiles and "P75" in percentiles:
+        fig.add_trace(
+            go.Scatter(
+                x=np.concatenate([years, years[::-1]]),
+                y=np.concatenate([percentiles["P75"], percentiles["P25"][::-1]]),
+                fill="toself",
+                fillcolor="rgba(52, 152, 219, 0.3)",
+                line={"width": 0},
+                name="P25-P75 Range",
+                hoverinfo="skip",
+                showlegend=True,
+            )
+        )
+
+    # Percentile lines
+    percentile_styles = {
+        "P90": {"color": COLORS["success_secondary"], "dash": "dot", "width": 1},
+        "P75": {"color": COLORS["success_primary"], "dash": "dash", "width": 1},
+        "P50": {"color": COLORS["wealth_primary"], "dash": "solid", "width": 3},
+        "P25": {"color": COLORS["warning_primary"], "dash": "dash", "width": 1},
+        "P10": {"color": COLORS["danger_secondary"], "dash": "dot", "width": 1},
+    }
+
+    for pct_name, values in percentiles.items():
+        if pct_name in percentile_styles:
+            style = percentile_styles[pct_name]
+            is_median = pct_name == "P50"
+
+            fig.add_trace(
+                go.Scatter(
+                    x=years,
+                    y=values,
+                    mode="lines",
+                    name=pct_name,
+                    line={
+                        "color": style["color"],
+                        "dash": style["dash"],
+                        "width": style["width"] if not (is_median and show_median_line) else 3,
+                    },
+                    hovertemplate=(
+                        f"<b>{pct_name}</b><br>"
+                        "Year: %{x}<br>"
+                        "Value: $%{y:,.0f}<br>"
+                        "<extra></extra>"
+                    ),
+                    showlegend=not (pct_name in ["P90", "P75", "P25", "P10"]),
+                )
+            )
+
+    # Add floor line if specified
+    if show_floor is not None:
+        fig.add_hline(
+            y=show_floor,
+            line_dash="dash",
+            line_color=COLORS["danger_primary"],
+            line_width=2,
+            annotation_text=f"Floor: ${show_floor:,.0f}",
+            annotation_position="top right",
+            annotation_font_color=COLORS["danger_primary"],
+        )
+
+    # Apply layout
+    layout = get_plotly_layout_defaults()
+    layout.update({
+        "title": {"text": title},
+        "height": height,
+        "xaxis": {
+            "title": "Year",
+            "gridcolor": COLORS["neutral_light"],
+            "dtick": 5,
+        },
+        "yaxis": {
+            "title": y_label,
+            "tickformat": "$,.0f",
+            "gridcolor": COLORS["neutral_light"],
+            "rangemode": "tozero",
+        },
+        "legend": {
+            "orientation": "h",
+            "yanchor": "bottom",
+            "y": 1.02,
+            "xanchor": "right",
+            "x": 1,
+        },
+        "hovermode": "x unified",
+    })
+
+    if width:
+        layout["width"] = width
+
+    fig.update_layout(**layout)
+
+    return fig
+
+
+def create_spending_fan_chart(
+    years: np.ndarray,
+    percentiles: dict[str, np.ndarray],
+    floor_spending: float | None = None,
+    target_spending: float | None = None,
+    title: str = "Spending Projection",
+    height: int = 500,
+    width: int | None = None,
+) -> go.Figure:
+    """Create a fan chart specifically for spending projections.
+
+    Args:
+        years: Array of year values
+        percentiles: Dictionary mapping percentile names to spending arrays
+        floor_spending: Essential spending floor
+        target_spending: Target spending level
+        title: Chart title
+        height: Chart height in pixels
+        width: Chart width in pixels
+
+    Returns:
+        Plotly Figure object
+    """
+    fig = create_fan_chart(
+        years=years,
+        percentiles=percentiles,
+        title=title,
+        y_label="Annual Spending ($)",
+        show_floor=floor_spending,
+        height=height,
+        width=width,
+    )
+
+    # Add target spending line if specified
+    if target_spending is not None:
+        fig.add_hline(
+            y=target_spending,
+            line_dash="dot",
+            line_color=COLORS["success_primary"],
+            line_width=2,
+            annotation_text=f"Target: ${target_spending:,.0f}",
+            annotation_position="top left",
+            annotation_font_color=COLORS["success_primary"],
+        )
+
+    return fig