fundedness 0.1.0__py3-none-any.whl

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

fundedness/viz/histogram.py

@@ -0,0 +1,225 @@
+"""Histogram visualizations for time-to-event distributions."""
+
+import numpy as np
+import plotly.graph_objects as go
+
+from fundedness.viz.colors import COLORS, get_plotly_layout_defaults
+
+
+def create_time_distribution_histogram(
+    time_to_event: np.ndarray,
+    event_name: str = "Ruin",
+    planning_horizon: int | None = None,
+    percentiles_to_show: list[int] | None = None,
+    title: str | None = None,
+    height: int = 400,
+    width: int | None = None,
+) -> go.Figure:
+    """Create a histogram of time-to-event distribution.
+
+    Args:
+        time_to_event: Array of time values (years until event, inf for no event)
+        event_name: Name of the event (e.g., "Ruin", "Floor Breach")
+        planning_horizon: Maximum planning horizon (for x-axis)
+        percentiles_to_show: Percentiles to mark (e.g., [10, 50, 90])
+        title: Chart title (auto-generated if None)
+        height: Chart height in pixels
+        width: Chart width in pixels
+
+    Returns:
+        Plotly Figure object
+    """
+    # Filter out infinite values (no event occurred)
+    finite_times = time_to_event[np.isfinite(time_to_event)]
+    never_occurred_count = np.sum(~np.isfinite(time_to_event))
+    total_count = len(time_to_event)
+
+    if title is None:
+        title = f"Time to {event_name} Distribution"
+
+    fig = go.Figure()
+
+    if len(finite_times) > 0:
+        # Determine bins
+        max_time = planning_horizon or int(np.ceil(finite_times.max()))
+        bins = np.arange(0, max_time + 2, 1)
+
+        # Create histogram
+        fig.add_trace(
+            go.Histogram(
+                x=finite_times,
+                xbins={"start": 0, "end": max_time + 1, "size": 1},
+                marker_color=COLORS["danger_primary"],
+                opacity=0.7,
+                name=f"Years to {event_name}",
+                hovertemplate=(
+                    "<b>Year %{x}</b><br>"
+                    "Count: %{y}<br>"
+                    "<extra></extra>"
+                ),
+            )
+        )
+
+        # Add percentile lines
+        if percentiles_to_show:
+            percentile_colors = {
+                10: COLORS["danger_secondary"],
+                25: COLORS["warning_secondary"],
+                50: COLORS["wealth_primary"],
+                75: COLORS["success_secondary"],
+                90: COLORS["success_primary"],
+            }
+
+            for pct in percentiles_to_show:
+                value = np.percentile(finite_times, pct)
+                color = percentile_colors.get(pct, COLORS["neutral_primary"])
+                fig.add_vline(
+                    x=value,
+                    line_dash="dash",
+                    line_color=color,
+                    line_width=2,
+                    annotation_text=f"P{pct}: {value:.1f}y",
+                    annotation_position="top",
+                    annotation_font_color=color,
+                )
+
+    # Add annotation for "never occurred" count
+    if never_occurred_count > 0:
+        never_pct = never_occurred_count / total_count * 100
+        fig.add_annotation(
+            x=0.98,
+            y=0.98,
+            xref="paper",
+            yref="paper",
+            text=f"Never {event_name.lower()}ed: {never_pct:.1f}%<br>({never_occurred_count:,} paths)",
+            showarrow=False,
+            font={"size": 12, "color": COLORS["success_primary"]},
+            bgcolor=COLORS["background"],
+            bordercolor=COLORS["success_primary"],
+            borderwidth=1,
+            borderpad=6,
+            align="right",
+        )
+
+    # Apply layout
+    layout = get_plotly_layout_defaults()
+    layout.update({
+        "title": {"text": title},
+        "height": height,
+        "xaxis": {
+            "title": f"Years to {event_name}",
+            "gridcolor": COLORS["neutral_light"],
+            "dtick": 5,
+        },
+        "yaxis": {
+            "title": "Number of Paths",
+            "gridcolor": COLORS["neutral_light"],
+        },
+        "showlegend": False,
+        "bargap": 0.1,
+    })
+
+    if width:
+        layout["width"] = width
+
+    fig.update_layout(**layout)
+
+    return fig
+
+
+def create_outcome_distribution_histogram(
+    terminal_values: np.ndarray,
+    initial_value: float | None = None,
+    target_value: float | None = None,
+    title: str = "Terminal Wealth Distribution",
+    height: int = 400,
+    width: int | None = None,
+) -> go.Figure:
+    """Create a histogram of terminal portfolio values.
+
+    Args:
+        terminal_values: Array of terminal portfolio values
+        initial_value: Starting portfolio value (for reference)
+        target_value: Target terminal value (for reference)
+        title: Chart title
+        height: Chart height in pixels
+        width: Chart width in pixels
+
+    Returns:
+        Plotly Figure object
+    """
+    fig = go.Figure()
+
+    # Create histogram with log-scale bins for wealth distribution
+    fig.add_trace(
+        go.Histogram(
+            x=terminal_values,
+            nbinsx=50,
+            marker_color=COLORS["wealth_primary"],
+            opacity=0.7,
+            name="Terminal Value",
+            hovertemplate=(
+                "<b>Value Range</b><br>"
+                "$%{x:,.0f}<br>"
+                "Count: %{y}<br>"
+                "<extra></extra>"
+            ),
+        )
+    )
+
+    # Add reference lines
+    if initial_value is not None:
+        fig.add_vline(
+            x=initial_value,
+            line_dash="dash",
+            line_color=COLORS["neutral_primary"],
+            line_width=2,
+            annotation_text=f"Initial: ${initial_value:,.0f}",
+            annotation_position="top",
+        )
+
+    if target_value is not None:
+        fig.add_vline(
+            x=target_value,
+            line_dash="dot",
+            line_color=COLORS["success_primary"],
+            line_width=2,
+            annotation_text=f"Target: ${target_value:,.0f}",
+            annotation_position="top",
+        )
+
+    # Add median line
+    median_value = np.median(terminal_values)
+    fig.add_vline(
+        x=median_value,
+        line_dash="solid",
+        line_color=COLORS["wealth_secondary"],
+        line_width=2,
+        annotation_text=f"Median: ${median_value:,.0f}",
+        annotation_position="bottom",
+    )
+
+    # Apply layout
+    layout = get_plotly_layout_defaults()
+    layout.update({
+        "title": {"text": title},
+        "height": height,
+        "xaxis": {
+            "title": "Portfolio Value ($)",
+            "tickformat": "$,.0f",
+            "gridcolor": COLORS["neutral_light"],
+        },
+        "yaxis": {
+            "title": "Number of Paths",
+            "gridcolor": COLORS["neutral_light"],
+        },
+        "showlegend": False,
+        "bargap": 0.05,
+    })
+
+    if width:
+        layout["width"] = width
+
+    fig.update_layout(**layout)
+
+    return fig