fundedness 0.2.4__py3-none-any.whl

fundedness/viz/survival.py

@@ -0,0 +1,230 @@
+"""Survival curve visualization."""
+
+import numpy as np
+import plotly.graph_objects as go
+
+from fundedness.viz.colors import COLORS, get_plotly_layout_defaults
+
+
+def create_survival_curve(
+    years: np.ndarray,
+    survival_prob: np.ndarray,
+    floor_survival_prob: np.ndarray | None = None,
+    title: str = "Portfolio Survival Probability",
+    threshold_years: list[int] | None = None,
+    height: int = 450,
+    width: int | None = None,
+) -> go.Figure:
+    """Create a survival curve showing probability of not running out of money.
+
+    Args:
+        years: Array of year values
+        survival_prob: Probability of portfolio survival at each year (above ruin)
+        floor_survival_prob: Probability of being above spending floor at each year
+        title: Chart title
+        threshold_years: Years to highlight with vertical lines (e.g., [20, 30])
+        height: Chart height in pixels
+        width: Chart width in pixels
+
+    Returns:
+        Plotly Figure object
+    """
+    fig = go.Figure()
+
+    # Main survival curve (above ruin)
+    fig.add_trace(
+        go.Scatter(
+            x=years,
+            y=survival_prob * 100,
+            mode="lines",
+            name="Above Ruin",
+            line={
+                "color": COLORS["wealth_primary"],
+                "width": 3,
+            },
+            fill="tozeroy",
+            fillcolor="rgba(52, 152, 219, 0.2)",
+            hovertemplate=(
+                "<b>Year %{x}</b><br>"
+                "Survival Probability: %{y:.1f}%<br>"
+                "<extra></extra>"
+            ),
+        )
+    )
+
+    # Floor survival curve if provided
+    if floor_survival_prob is not None:
+        fig.add_trace(
+            go.Scatter(
+                x=years,
+                y=floor_survival_prob * 100,
+                mode="lines",
+                name="Above Floor",
+                line={
+                    "color": COLORS["success_primary"],
+                    "width": 2,
+                    "dash": "dash",
+                },
+                hovertemplate=(
+                    "<b>Year %{x}</b><br>"
+                    "Floor Probability: %{y:.1f}%<br>"
+                    "<extra></extra>"
+                ),
+            )
+        )
+
+    # Add threshold year markers
+    if threshold_years:
+        for year in threshold_years:
+            if year <= years[-1]:
+                idx = np.searchsorted(years, year)
+                if idx < len(survival_prob):
+                    prob = survival_prob[idx] * 100
+                    fig.add_vline(
+                        x=year,
+                        line_dash="dot",
+                        line_color=COLORS["neutral_primary"],
+                        annotation_text=f"Year {year}: {prob:.0f}%",
+                        annotation_position="top",
+                    )
+
+    # Add horizontal reference lines
+    for prob_level, label in [(90, "90%"), (75, "75%"), (50, "50%")]:
+        fig.add_hline(
+            y=prob_level,
+            line_dash="dot",
+            line_color=COLORS["neutral_light"],
+            line_width=1,
+        )
+
+    # Apply layout
+    layout = get_plotly_layout_defaults()
+    layout.update({
+        "title": {"text": title},
+        "height": height,
+        "xaxis": {
+            "title": "Years",
+            "gridcolor": COLORS["neutral_light"],
+            "dtick": 5,
+        },
+        "yaxis": {
+            "title": "Probability (%)",
+            "range": [0, 105],
+            "gridcolor": COLORS["neutral_light"],
+            "ticksuffix": "%",
+        },
+        "legend": {
+            "orientation": "h",
+            "yanchor": "bottom",
+            "y": 1.02,
+            "xanchor": "right",
+            "x": 1,
+        },
+    })
+
+    if width:
+        layout["width"] = width
+
+    fig.update_layout(**layout)
+
+    return fig
+
+
+def create_dual_survival_chart(
+    years: np.ndarray,
+    ruin_prob: np.ndarray,
+    floor_breach_prob: np.ndarray,
+    title: str = "Risk Timeline",
+    height: int = 450,
+    width: int | None = None,
+) -> go.Figure:
+    """Create a chart showing both ruin and floor breach probabilities over time.
+
+    Shows the cumulative probability of experiencing each event by each year.
+
+    Args:
+        years: Array of year values
+        ruin_prob: Cumulative probability of ruin by each year
+        floor_breach_prob: Cumulative probability of floor breach by each year
+        title: Chart title
+        height: Chart height in pixels
+        width: Chart width in pixels
+
+    Returns:
+        Plotly Figure object
+    """
+    fig = go.Figure()
+
+    # Floor breach probability (less severe, but more common)
+    fig.add_trace(
+        go.Scatter(
+            x=years,
+            y=floor_breach_prob * 100,
+            mode="lines",
+            name="Floor Breach Risk",
+            line={
+                "color": COLORS["warning_primary"],
+                "width": 2,
+            },
+            fill="tozeroy",
+            fillcolor="rgba(243, 156, 18, 0.15)",
+            hovertemplate=(
+                "<b>Year %{x}</b><br>"
+                "Floor Breach Risk: %{y:.1f}%<br>"
+                "<extra></extra>"
+            ),
+        )
+    )
+
+    # Ruin probability (more severe)
+    fig.add_trace(
+        go.Scatter(
+            x=years,
+            y=ruin_prob * 100,
+            mode="lines",
+            name="Ruin Risk",
+            line={
+                "color": COLORS["danger_primary"],
+                "width": 2,
+            },
+            fill="tozeroy",
+            fillcolor="rgba(231, 76, 60, 0.15)",
+            hovertemplate=(
+                "<b>Year %{x}</b><br>"
+                "Ruin Risk: %{y:.1f}%<br>"
+                "<extra></extra>"
+            ),
+        )
+    )
+
+    # Apply layout
+    layout = get_plotly_layout_defaults()
+    layout.update({
+        "title": {"text": title},
+        "height": height,
+        "xaxis": {
+            "title": "Years",
+            "gridcolor": COLORS["neutral_light"],
+            "dtick": 5,
+        },
+        "yaxis": {
+            "title": "Cumulative Probability (%)",
+            "range": [0, max(50, max(ruin_prob.max(), floor_breach_prob.max()) * 100 * 1.1)],
+            "gridcolor": COLORS["neutral_light"],
+            "ticksuffix": "%",
+        },
+        "legend": {
+            "orientation": "h",
+            "yanchor": "bottom",
+            "y": 1.02,
+            "xanchor": "right",
+            "x": 1,
+        },
+    })
+
+    if width:
+        layout["width"] = width
+
+    fig.update_layout(**layout)
+
+    return fig

fundedness/viz/tornado.py

@@ -0,0 +1,236 @@
+"""Tornado chart for sensitivity analysis."""
+
+import plotly.graph_objects as go
+
+from fundedness.viz.colors import COLORS, get_plotly_layout_defaults
+
+
+def create_tornado_chart(
+    parameters: list[str],
+    low_values: list[float],
+    high_values: list[float],
+    base_value: float,
+    parameter_labels: list[str] | None = None,
+    title: str = "Sensitivity Analysis",
+    value_label: str = "CEFR",
+    height: int = 500,
+    width: int | None = None,
+) -> go.Figure:
+    """Create a tornado chart for sensitivity analysis.
+
+    Args:
+        parameters: List of parameter names
+        low_values: Outcome values when parameter is at low end
+        high_values: Outcome values when parameter is at high end
+        base_value: Baseline outcome value
+        parameter_labels: Display labels for parameters (uses parameters if None)
+        title: Chart title
+        value_label: Label for the outcome metric
+        height: Chart height in pixels
+        width: Chart width in pixels
+
+    Returns:
+        Plotly Figure object
+    """
+    if parameter_labels is None:
+        parameter_labels = parameters
+
+    # Calculate ranges and sort by total impact
+    impacts = []
+    for i, (low, high) in enumerate(zip(low_values, high_values)):
+        low_impact = base_value - low
+        high_impact = high - base_value
+        total_impact = abs(high - low)
+        impacts.append({
+            "param": parameter_labels[i],
+            "low": low,
+            "high": high,
+            "low_impact": low_impact,
+            "high_impact": high_impact,
+            "total_impact": total_impact,
+        })
+
+    # Sort by total impact (largest first)
+    impacts.sort(key=lambda x: x["total_impact"], reverse=True)
+
+    fig = go.Figure()
+
+    # Low impact bars (extending left from base)
+    fig.add_trace(
+        go.Bar(
+            y=[i["param"] for i in impacts],
+            x=[-(base_value - i["low"]) for i in impacts],
+            orientation="h",
+            name="Low Scenario",
+            marker_color=COLORS["danger_primary"],
+            text=[f"{i['low']:.2f}" for i in impacts],
+            textposition="outside",
+            hovertemplate=(
+                "<b>%{y}</b><br>"
+                f"Low {value_label}: " + "%{customdata:.2f}<br>"
+                "<extra></extra>"
+            ),
+            customdata=[i["low"] for i in impacts],
+        )
+    )
+
+    # High impact bars (extending right from base)
+    fig.add_trace(
+        go.Bar(
+            y=[i["param"] for i in impacts],
+            x=[i["high"] - base_value for i in impacts],
+            orientation="h",
+            name="High Scenario",
+            marker_color=COLORS["success_primary"],
+            text=[f"{i['high']:.2f}" for i in impacts],
+            textposition="outside",
+            hovertemplate=(
+                "<b>%{y}</b><br>"
+                f"High {value_label}: " + "%{customdata:.2f}<br>"
+                "<extra></extra>"
+            ),
+            customdata=[i["high"] for i in impacts],
+        )
+    )
+
+    # Add base value line
+    fig.add_vline(
+        x=0,
+        line_color=COLORS["text_primary"],
+        line_width=2,
+    )
+
+    # Apply layout
+    layout = get_plotly_layout_defaults()
+
+    # Calculate x-axis range
+    max_deviation = max(
+        max(abs(base_value - i["low"]) for i in impacts),
+        max(abs(i["high"] - base_value) for i in impacts),
+    )
+    x_range = [-max_deviation * 1.3, max_deviation * 1.3]
+
+    layout.update({
+        "title": {"text": title},
+        "height": height,
+        "xaxis": {
+            "title": f"Change in {value_label} from Base ({base_value:.2f})",
+            "gridcolor": COLORS["neutral_light"],
+            "range": x_range,
+            "zeroline": True,
+            "zerolinecolor": COLORS["text_primary"],
+            "zerolinewidth": 2,
+        },
+        "yaxis": {
+            "title": "",
+            "autorange": "reversed",  # Largest impact at top
+        },
+        "barmode": "overlay",
+        "legend": {
+            "orientation": "h",
+            "yanchor": "bottom",
+            "y": 1.02,
+            "xanchor": "right",
+            "x": 1,
+        },
+    })
+
+    if width:
+        layout["width"] = width
+
+    fig.update_layout(**layout)
+
+    # Add base value annotation
+    fig.add_annotation(
+        x=0,
+        y=1.1,
+        xref="x",
+        yref="paper",
+        text=f"Base: {base_value:.2f}",
+        showarrow=False,
+        font={"size": 12, "color": COLORS["text_primary"]},
+    )
+
+    return fig
+
+
+def create_scenario_comparison_chart(
+    scenarios: list[str],
+    values: list[float],
+    base_scenario: str | None = None,
+    title: str = "Scenario Comparison",
+    value_label: str = "CEFR",
+    height: int = 400,
+    width: int | None = None,
+) -> go.Figure:
+    """Create a bar chart comparing different scenarios.
+
+    Args:
+        scenarios: List of scenario names
+        values: Outcome values for each scenario
+        base_scenario: Name of the base scenario (highlighted differently)
+        title: Chart title
+        value_label: Label for the outcome metric
+        height: Chart height in pixels
+        width: Chart width in pixels
+
+    Returns:
+        Plotly Figure object
+    """
+    colors = []
+    for scenario in scenarios:
+        if scenario == base_scenario:
+            colors.append(COLORS["wealth_primary"])
+        elif values[scenarios.index(scenario)] >= 1.0:
+            colors.append(COLORS["success_primary"])
+        else:
+            colors.append(COLORS["warning_primary"])
+
+    fig = go.Figure()
+
+    fig.add_trace(
+        go.Bar(
+            x=scenarios,
+            y=values,
+            marker_color=colors,
+            text=[f"{v:.2f}" for v in values],
+            textposition="outside",
+            hovertemplate=(
+                "<b>%{x}</b><br>"
+                f"{value_label}: " + "%{y:.2f}<br>"
+                "<extra></extra>"
+            ),
+        )
+    )
+
+    # Add threshold line at 1.0 for CEFR
+    if value_label == "CEFR":
+        fig.add_hline(
+            y=1.0,
+            line_dash="dash",
+            line_color=COLORS["neutral_primary"],
+            annotation_text="Fully Funded (1.0)",
+            annotation_position="top right",
+        )
+
+    # Apply layout
+    layout = get_plotly_layout_defaults()
+    layout.update({
+        "title": {"text": title},
+        "height": height,
+        "xaxis": {
+            "title": "Scenario",
+        },
+        "yaxis": {
+            "title": value_label,
+            "gridcolor": COLORS["neutral_light"],
+        },
+        "showlegend": False,
+    })
+
+    if width:
+        layout["width"] = width
+
+    fig.update_layout(**layout)
+
+    return fig

fundedness/viz/waterfall.py

@@ -0,0 +1,203 @@
+"""CEFR waterfall chart visualization."""
+
+import plotly.graph_objects as go
+
+from fundedness.cefr import CEFRResult
+from fundedness.viz.colors import COLORS, WATERFALL_COLORS, get_plotly_layout_defaults
+
+
+def create_cefr_waterfall(
+    cefr_result: CEFRResult,
+    show_liability: bool = True,
+    title: str = "CEFR Calculation Breakdown",
+    height: int = 500,
+    width: int | None = None,
+) -> go.Figure:
+    """Create a waterfall chart showing CEFR calculation breakdown.
+
+    Shows: Gross Assets → Tax Haircut → Liquidity Haircut → Reliability Haircut → Net Assets
+    Optionally shows liability comparison.
+
+    Args:
+        cefr_result: CEFR calculation result
+        show_liability: Whether to show liability PV for comparison
+        title: Chart title
+        height: Chart height in pixels
+        width: Chart width in pixels (None = responsive)
+
+    Returns:
+        Plotly Figure object
+    """
+    # Prepare data
+    labels = [
+        "Gross Assets",
+        "Tax Haircut",
+        "Liquidity Haircut",
+        "Reliability Haircut",
+        "Net Assets",
+    ]
+    values = [
+        cefr_result.gross_assets,
+        -cefr_result.total_tax_haircut,
+        -cefr_result.total_liquidity_haircut,
+        -cefr_result.total_reliability_haircut,
+        cefr_result.net_assets,
+    ]
+    measures = ["absolute", "relative", "relative", "relative", "total"]
+
+    if show_liability and cefr_result.liability_pv > 0:
+        labels.append("Liability PV")
+        values.append(cefr_result.liability_pv)
+        measures.append("absolute")
+
+    # Create waterfall
+    fig = go.Figure(
+        go.Waterfall(
+            name="CEFR",
+            orientation="v",
+            measure=measures,
+            x=labels,
+            textposition="outside",
+            text=[f"${abs(v):,.0f}" for v in values],
+            y=values,
+            connector={"line": {"color": COLORS["neutral_light"]}},
+            increasing={"marker": {"color": WATERFALL_COLORS["increase"]}},
+            decreasing={"marker": {"color": WATERFALL_COLORS["decrease"]}},
+            totals={"marker": {"color": WATERFALL_COLORS["total"]}},
+            hovertemplate=(
+                "<b>%{x}</b><br>"
+                "Value: $%{y:,.0f}<br>"
+                "<extra></extra>"
+            ),
+        )
+    )
+
+    # Add liability reference line if shown
+    if show_liability and cefr_result.liability_pv > 0:
+        fig.add_hline(
+            y=cefr_result.liability_pv,
+            line_dash="dash",
+            line_color=COLORS["danger_secondary"],
+            annotation_text=f"Liability PV: ${cefr_result.liability_pv:,.0f}",
+            annotation_position="top right",
+        )
+
+    # Apply layout
+    layout = get_plotly_layout_defaults()
+    layout.update({
+        "title": {"text": title},
+        "height": height,
+        "yaxis": {
+            "title": "Value ($)",
+            "tickformat": "$,.0f",
+            "gridcolor": COLORS["neutral_light"],
+        },
+        "xaxis": {
+            "title": "",
+        },
+        "showlegend": False,
+    })
+
+    if width:
+        layout["width"] = width
+
+    fig.update_layout(**layout)
+
+    # Add CEFR annotation
+    cefr_text = f"CEFR: {cefr_result.cefr:.2f}"
+    if cefr_result.is_funded:
+        cefr_color = COLORS["success_primary"]
+    else:
+        cefr_color = COLORS["danger_primary"]
+
+    fig.add_annotation(
+        x=0.02,
+        y=0.98,
+        xref="paper",
+        yref="paper",
+        text=f"<b>{cefr_text}</b>",
+        showarrow=False,
+        font={"size": 16, "color": cefr_color},
+        bgcolor=COLORS["background"],
+        bordercolor=cefr_color,
+        borderwidth=2,
+        borderpad=8,
+    )
+
+    return fig
+
+
+def create_haircut_breakdown_bar(
+    cefr_result: CEFRResult,
+    title: str = "Haircut Breakdown by Category",
+    height: int = 400,
+    width: int | None = None,
+) -> go.Figure:
+    """Create a horizontal bar chart showing haircut breakdown.
+
+    Args:
+        cefr_result: CEFR calculation result
+        title: Chart title
+        height: Chart height in pixels
+        width: Chart width in pixels (None = responsive)
+
+    Returns:
+        Plotly Figure object
+    """
+    categories = ["Tax", "Liquidity", "Reliability"]
+    values = [
+        cefr_result.total_tax_haircut,
+        cefr_result.total_liquidity_haircut,
+        cefr_result.total_reliability_haircut,
+    ]
+    percentages = [
+        v / cefr_result.gross_assets * 100 if cefr_result.gross_assets > 0 else 0
+        for v in values
+    ]
+
+    colors = [
+        COLORS["warning_primary"],
+        COLORS["accent_primary"],
+        COLORS["danger_primary"],
+    ]
+
+    fig = go.Figure()
+
+    fig.add_trace(
+        go.Bar(
+            y=categories,
+            x=values,
+            orientation="h",
+            marker_color=colors,
+            text=[f"${v:,.0f} ({p:.1f}%)" for v, p in zip(values, percentages)],
+            textposition="auto",
+            hovertemplate=(
+                "<b>%{y} Haircut</b><br>"
+                "Amount: $%{x:,.0f}<br>"
+                "<extra></extra>"
+            ),
+        )
+    )
+
+    # Apply layout
+    layout = get_plotly_layout_defaults()
+    layout.update({
+        "title": {"text": title},
+        "height": height,
+        "xaxis": {
+            "title": "Haircut Amount ($)",
+            "tickformat": "$,.0f",
+            "gridcolor": COLORS["neutral_light"],
+        },
+        "yaxis": {
+            "title": "",
+        },
+        "showlegend": False,
+    })
+
+    if width:
+        layout["width"] = width
+
+    fig.update_layout(**layout)
+
+    return fig

fundedness/withdrawals/__init__.py

@@ -0,0 +1,27 @@
+"""Withdrawal strategy implementations."""
+
+from fundedness.withdrawals.base import WithdrawalContext, WithdrawalDecision, WithdrawalPolicy
+from fundedness.withdrawals.comparison import compare_strategies
+from fundedness.withdrawals.fixed_swr import FixedRealSWRPolicy
+from fundedness.withdrawals.guardrails import GuardrailsPolicy
+from fundedness.withdrawals.merton_optimal import (
+    FloorAdjustedMertonPolicy,
+    MertonOptimalSpendingPolicy,
+    SmoothedMertonPolicy,
+)
+from fundedness.withdrawals.rmd_style import RMDStylePolicy
+from fundedness.withdrawals.vpw import VPWPolicy
+
+__all__ = [
+    "compare_strategies",
+    "FixedRealSWRPolicy",
+    "FloorAdjustedMertonPolicy",
+    "GuardrailsPolicy",
+    "MertonOptimalSpendingPolicy",
+    "RMDStylePolicy",
+    "SmoothedMertonPolicy",
+    "VPWPolicy",
+    "WithdrawalContext",
+    "WithdrawalDecision",
+    "WithdrawalPolicy",
+]