ml4t-diagnostic 0.1.0a1__py3-none-any.whl

ml4t/diagnostic/evaluation/stats/sharpe_inference.py

@@ -0,0 +1,219 @@
+"""Sharpe ratio inference: variance estimation and multiple testing adjustment.
+
+This module implements the statistical inference framework for Sharpe ratios:
+
+- Variance of Sharpe ratio estimator (2025 formula with autocorrelation)
+- Expected maximum Sharpe under null (for multiple testing)
+- Variance rescaling factors for selection bias
+
+References
+----------
+López de Prado, M., Lipton, A., & Zoonekynd, V. (2025).
+"How to Use the Sharpe Ratio." ADIA Lab Research Paper Series, No. 19.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.stats import norm
+
+# Euler-Mascheroni constant for E[max{Z}] calculation
+EULER_GAMMA = 0.5772156649015329
+
+# Standard deviation rescaling factors for maximum of K standard normals
+# Source: López de Prado et al. (2025), Exhibit 3, page 13
+# These are √V[max{X_k}] values for DSR variance adjustment
+VARIANCE_RESCALING_FACTORS: dict[int, float] = {
+    1: 1.00000,
+    2: 0.82565,
+    3: 0.74798,
+    4: 0.70122,
+    5: 0.66898,
+    6: 0.64492,
+    7: 0.62603,
+    8: 0.61065,
+    9: 0.59779,
+    10: 0.58681,
+    20: 0.52131,
+    30: 0.49364,
+    40: 0.47599,
+    50: 0.46334,
+    60: 0.45361,
+    70: 0.44579,
+    80: 0.43929,
+    90: 0.43376,
+    100: 0.42942,
+}
+
+
+def get_variance_rescaling_factor(k: int) -> float:
+    """Get variance rescaling factor √V[max{X_k}] for K trials.
+
+    Source: López de Prado et al. (2025), Exhibit 3, page 13.
+
+    Parameters
+    ----------
+    k : int
+        Number of independent trials
+
+    Returns
+    -------
+    float
+        Rescaling factor (uses linear interpolation for unlisted values)
+    """
+    if k in VARIANCE_RESCALING_FACTORS:
+        return VARIANCE_RESCALING_FACTORS[k]
+
+    keys = sorted(VARIANCE_RESCALING_FACTORS.keys())
+    if k < keys[0]:
+        return VARIANCE_RESCALING_FACTORS[keys[0]]
+    if k > keys[-1]:
+        return VARIANCE_RESCALING_FACTORS[keys[-1]]
+
+    # Linear interpolation
+    for i in range(len(keys) - 1):
+        if keys[i] <= k <= keys[i + 1]:
+            k1, k2 = keys[i], keys[i + 1]
+            v1, v2 = VARIANCE_RESCALING_FACTORS[k1], VARIANCE_RESCALING_FACTORS[k2]
+            return v1 + (v2 - v1) * (k - k1) / (k2 - k1)
+
+    return VARIANCE_RESCALING_FACTORS[keys[-1]]
+
+
+def compute_sharpe_variance(
+    sharpe: float,
+    n_samples: int,
+    skewness: float,
+    kurtosis: float,
+    autocorrelation: float,
+    n_trials: int = 1,
+) -> float:
+    """Compute variance of Sharpe ratio estimator.
+
+    Implements the full 2025 formula with autocorrelation correction:
+
+    .. math::
+
+        \\sigma^2[\\widehat{SR}] = \\frac{1}{T} \\left[
+            \\frac{1+\\rho}{1-\\rho}
+            - \\left(1 + \\frac{\\rho}{1-\\rho} + \\frac{\\rho^2}{1-\\rho^2}\\right) \\gamma_3 SR
+            + \\frac{1+\\rho^2}{1-\\rho^2} \\frac{\\gamma_4 - 1}{4} SR^2
+        \\right] \\times V[\\max_k\\{X_k\\}]
+
+    When ρ=0 (i.i.d. assumption), this reduces to the 2014 formula:
+
+    .. math::
+
+        \\sigma^2[\\widehat{SR}] = \\frac{1}{T} \\left[
+            1 - \\gamma_3 SR + \\frac{\\gamma_4 - 1}{4} SR^2
+        \\right]
+
+    Parameters
+    ----------
+    sharpe : float
+        Sharpe ratio (at native frequency)
+    n_samples : int
+        Number of observations (T)
+    skewness : float
+        Return skewness (γ₃)
+    kurtosis : float
+        Return kurtosis (γ₄), Pearson convention (normal = 3)
+    autocorrelation : float
+        First-order autocorrelation (ρ), must be in (-1, 1)
+    n_trials : int, default 1
+        Number of strategies (K) for variance rescaling
+
+    Returns
+    -------
+    float
+        Variance of Sharpe ratio estimator
+
+    Raises
+    ------
+    ValueError
+        If autocorrelation is not in (-1, 1).
+
+    References
+    ----------
+    López de Prado et al. (2025), Equations 2-5, pages 5-7.
+    """
+    rho = autocorrelation
+
+    # Validate autocorrelation
+    if abs(rho) >= 1.0:
+        raise ValueError(f"Autocorrelation must be in (-1, 1), got {rho}")
+
+    # Compute coefficients (from reference implementation)
+    # When rho=0: coef_a=1, coef_b=0, coef_c=0, so a=1, b=1, c=1 (reduces to 2014 formula)
+    coef_a = 1.0
+    if rho != 0:
+        coef_b = rho / (1 - rho)
+        coef_c = rho**2 / (1 - rho**2)
+    else:
+        coef_b = 0.0
+        coef_c = 0.0
+
+    a = coef_a + 2 * coef_b  # = (1+ρ)/(1-ρ) - base term coefficient
+    b = coef_a + coef_b + coef_c  # = 1 + ρ/(1-ρ) + ρ²/(1-ρ²) - skewness coefficient
+    c = coef_a + 2 * coef_c  # = (1+ρ²)/(1-ρ²) - kurtosis coefficient
+
+    # Variance formula (Equation 5)
+    variance = (a - b * skewness * sharpe + c * (kurtosis - 1) / 4 * sharpe**2) / n_samples
+
+    # Apply variance rescaling for multiple testing (Equation 29)
+    if n_trials > 1:
+        rescaling_factor = get_variance_rescaling_factor(n_trials)
+        variance *= rescaling_factor**2
+
+    return max(variance, 0.0)  # Ensure non-negative
+
+
+def compute_expected_max_sharpe(n_trials: int, variance_trials: float) -> float:
+    """Compute expected maximum Sharpe ratio under null hypothesis.
+
+    .. math::
+
+        E[\\max_k\\{\\widehat{SR}_k\\}] \\approx \\sqrt{V[\\{\\widehat{SR}_k\\}]}
+        \\left((1-\\gamma) \\Phi^{-1}(1-1/K) + \\gamma \\Phi^{-1}(1-1/(Ke))\\right)
+
+    where γ is the Euler-Mascheroni constant ≈ 0.5772.
+
+    Parameters
+    ----------
+    n_trials : int
+        Number of strategies tested (K)
+    variance_trials : float
+        Cross-sectional variance of Sharpe ratios: Var[{SR_1, ..., SR_K}]
+
+    Returns
+    -------
+    float
+        Expected maximum Sharpe ratio E[max{SR}]
+
+    References
+    ----------
+    López de Prado et al. (2025), Equation 26, page 13.
+    Bailey & López de Prado (2014), Appendix A.1, Equation 6.
+    """
+    if n_trials <= 1:
+        return 0.0
+
+    if variance_trials <= 0:
+        return 0.0
+
+    # E[max{Z}] for K i.i.d. standard normals (Equation 26)
+    quantile_1 = norm.ppf(1 - 1 / n_trials)
+    quantile_2 = norm.ppf(1 - 1 / (n_trials * np.e))
+    e_max_z = (1 - EULER_GAMMA) * quantile_1 + EULER_GAMMA * quantile_2
+
+    # Scale by standard deviation of Sharpe ratios across trials
+    return float(np.sqrt(variance_trials) * e_max_z)
+
+
+__all__ = [
+    "EULER_GAMMA",
+    "VARIANCE_RESCALING_FACTORS",
+    "get_variance_rescaling_factor",
+    "compute_sharpe_variance",
+    "compute_expected_max_sharpe",
+]

ml4t/diagnostic/evaluation/themes.py

@@ -0,0 +1,330 @@
+"""Plotly themes and styling for ml4t-diagnostic visualizations.
+
+This module provides consistent theming across all ml4t-diagnostic visualizations,
+including color schemes, layout templates, and accessibility options.
+"""
+
+from typing import Any
+
+# Financial color schemes
+FINANCIAL_COLORS = {
+    # Returns and performance
+    "positive": "#00CC88",  # Green for gains
+    "negative": "#FF4444",  # Red for losses
+    "neutral": "#888888",  # Gray for neutral
+    # Data series
+    "primary": "#3366CC",  # Blue
+    "secondary": "#FF9900",  # Orange
+    "tertiary": "#109618",  # Dark green
+    "quaternary": "#990099",  # Purple
+    # UI elements
+    "background": "#F8F9FA",  # Light gray
+    "paper": "#FFFFFF",  # White
+    "grid": "#E0E0E0",  # Grid lines
+    "text": "#333333",  # Dark gray text
+    "subtitle": "#666666",  # Medium gray
+    # Quantiles (5-level)
+    "q1": "#D32F2F",  # Dark red (lowest)
+    "q2": "#F57C00",  # Orange
+    "q3": "#FBC02D",  # Yellow
+    "q4": "#689F38",  # Light green
+    "q5": "#388E3C",  # Dark green (highest)
+}
+
+# Colorblind-friendly palette
+COLORBLIND_SAFE = {
+    "blue": "#0173B2",
+    "orange": "#DE8F05",
+    "green": "#029E73",
+    "red": "#CC78BC",
+    "purple": "#5B4E96",
+    "brown": "#A65628",
+    "pink": "#F0E442",
+    "gray": "#999999",
+}
+
+# Layout templates
+DEFAULT_TEMPLATE = {
+    "layout": {
+        # Typography
+        "font": {
+            "family": "Arial, Helvetica, sans-serif",
+            "size": 12,
+            "color": FINANCIAL_COLORS["text"],
+        },
+        "title": {
+            "font": {"size": 16, "color": FINANCIAL_COLORS["text"]},
+            "x": 0.5,
+            "xanchor": "center",
+        },
+        # Colors
+        "plot_bgcolor": FINANCIAL_COLORS["background"],
+        "paper_bgcolor": FINANCIAL_COLORS["paper"],
+        # Margins
+        "margin": {"l": 60, "r": 30, "t": 60, "b": 60},
+        # Hover
+        "hovermode": "closest",
+        "hoverlabel": {"bgcolor": "white", "font_size": 12, "font_family": "Arial"},
+        # Grid and axes
+        "xaxis": {
+            "gridcolor": FINANCIAL_COLORS["grid"],
+            "zeroline": False,
+            "showgrid": True,
+            "showline": True,
+            "linecolor": FINANCIAL_COLORS["grid"],
+            "tickfont": {"size": 11},
+        },
+        "yaxis": {
+            "gridcolor": FINANCIAL_COLORS["grid"],
+            "zeroline": True,
+            "zerolinecolor": FINANCIAL_COLORS["grid"],
+            "showgrid": True,
+            "showline": True,
+            "linecolor": FINANCIAL_COLORS["grid"],
+            "tickfont": {"size": 11},
+        },
+        # Legend
+        "legend": {
+            "bgcolor": "rgba(255,255,255,0.9)",
+            "bordercolor": FINANCIAL_COLORS["grid"],
+            "borderwidth": 1,
+        },
+    },
+}
+
+# Dark theme for dashboards
+DARK_TEMPLATE = {
+    "layout": {
+        # Typography
+        "font": {"family": "Arial, Helvetica, sans-serif", "size": 12, "color": "#E0E0E0"},
+        "title": {"font": {"size": 16, "color": "#FFFFFF"}, "x": 0.5, "xanchor": "center"},
+        # Colors
+        "plot_bgcolor": "#1E1E1E",
+        "paper_bgcolor": "#121212",
+        # Grid and axes
+        "xaxis": {
+            "gridcolor": "#333333",
+            "zeroline": False,
+            "showgrid": True,
+            "showline": True,
+            "linecolor": "#444444",
+            "tickfont": {"color": "#B0B0B0"},
+        },
+        "yaxis": {
+            "gridcolor": "#333333",
+            "zeroline": True,
+            "zerolinecolor": "#444444",
+            "showgrid": True,
+            "showline": True,
+            "linecolor": "#444444",
+            "tickfont": {"color": "#B0B0B0"},
+        },
+        # Legend
+        "legend": {
+            "bgcolor": "rgba(30,30,30,0.9)",
+            "bordercolor": "#444444",
+            "borderwidth": 1,
+            "font": {"color": "#E0E0E0"},
+        },
+    },
+}
+
+# Print-friendly template
+PRINT_TEMPLATE = {
+    "layout": {
+        # Black and white only
+        "font": {"family": "Times New Roman, serif", "size": 10, "color": "black"},
+        "title": {"font": {"size": 14, "color": "black"}, "x": 0.5, "xanchor": "center"},
+        # White background
+        "plot_bgcolor": "white",
+        "paper_bgcolor": "white",
+        # Minimal margins for printing
+        "margin": {"l": 40, "r": 20, "t": 40, "b": 40},
+        # High contrast grid
+        "xaxis": {
+            "gridcolor": "#CCCCCC",
+            "zeroline": True,
+            "zerolinecolor": "black",
+            "showgrid": True,
+            "showline": True,
+            "linecolor": "black",
+            "linewidth": 1,
+        },
+        "yaxis": {
+            "gridcolor": "#CCCCCC",
+            "zeroline": True,
+            "zerolinecolor": "black",
+            "showgrid": True,
+            "showline": True,
+            "linecolor": "black",
+            "linewidth": 1,
+        },
+        # No shadows or effects
+        "legend": {"bgcolor": "white", "bordercolor": "black", "borderwidth": 1},
+    },
+}
+
+
+def get_color_scale(n_colors: int, scheme: str = "diverging") -> list[str]:
+    """Get a color scale for visualizations.
+
+    Parameters
+    ----------
+    n_colors : int
+        Number of colors needed
+    scheme : str, default "diverging"
+        Color scheme type: "diverging", "sequential", "quantile", "colorblind"
+
+    Returns:
+    -------
+    list[str]
+        List of hex color codes
+    """
+    if scheme == "diverging":
+        # Red to green through white
+        if n_colors == 2:
+            return [FINANCIAL_COLORS["negative"], FINANCIAL_COLORS["positive"]]
+        if n_colors == 3:
+            return [
+                FINANCIAL_COLORS["negative"],
+                FINANCIAL_COLORS["neutral"],
+                FINANCIAL_COLORS["positive"],
+            ]
+        # Use plotly's RdYlGn scale
+        import plotly.colors as pc
+
+        return pc.sample_colorscale("RdYlGn", n_colors)
+
+    if scheme == "sequential":
+        # Blue gradient
+        if n_colors <= 5:
+            return ["#E3F2FD", "#90CAF9", "#42A5F5", "#1E88E5", "#0D47A1"][:n_colors]
+        import plotly.colors as pc
+
+        return pc.sample_colorscale("Blues", n_colors)
+
+    if scheme == "quantile":
+        # Specific colors for quantiles
+        quantile_colors = [
+            FINANCIAL_COLORS["q1"],
+            FINANCIAL_COLORS["q2"],
+            FINANCIAL_COLORS["q3"],
+            FINANCIAL_COLORS["q4"],
+            FINANCIAL_COLORS["q5"],
+        ]
+        if n_colors <= 5:
+            return quantile_colors[:n_colors]
+        # Interpolate if more than 5
+        import plotly.colors as pc
+
+        return pc.sample_colorscale("RdYlGn", n_colors)
+
+    if scheme == "colorblind":
+        # Colorblind-safe palette
+        colors = list(COLORBLIND_SAFE.values())
+        if n_colors <= len(colors):
+            return colors[:n_colors]
+        # Cycle through if need more
+        return (colors * (n_colors // len(colors) + 1))[:n_colors]
+
+    # Default categorical
+    import plotly.express as px
+
+    return px.colors.qualitative.Set3[:n_colors]
+
+
+def apply_theme(fig: Any, theme: str = "default") -> Any:
+    """Apply a theme to a Plotly figure.
+
+    Parameters
+    ----------
+    fig : plotly.graph_objects.Figure
+        Figure to apply theme to
+    theme : str, default "default"
+        Theme name: "default", "dark", "print", "colorblind"
+
+    Returns:
+    -------
+    plotly.graph_objects.Figure
+        Figure with theme applied
+    """
+    if theme == "default":
+        template = DEFAULT_TEMPLATE
+    elif theme == "dark":
+        template = DARK_TEMPLATE
+    elif theme == "print":
+        template = PRINT_TEMPLATE
+    elif theme == "colorblind":
+        # Apply colorblind-safe colors to existing theme
+        template = DEFAULT_TEMPLATE.copy()
+        # Would need to update trace colors here
+    else:
+        raise ValueError(f"Unknown theme: {theme}")
+
+    # Apply template
+    fig.update_layout(template["layout"])
+
+    return fig
+
+
+def format_percentage(value: float, decimals: int = 1) -> str:
+    """Format a value as percentage for display.
+
+    Parameters
+    ----------
+    value : float
+        Value to format (0.05 = 5%)
+    decimals : int, default 1
+        Number of decimal places
+
+    Returns:
+    -------
+    str
+        Formatted percentage string
+    """
+    return f"{value * 100:.{decimals}f}%"
+
+
+def format_currency(value: float, currency: str = "$", decimals: int = 0) -> str:
+    """Format a value as currency for display.
+
+    Parameters
+    ----------
+    value : float
+        Value to format
+    currency : str, default "$"
+        Currency symbol
+    decimals : int, default 0
+        Number of decimal places
+
+    Returns:
+    -------
+    str
+        Formatted currency string
+    """
+    if decimals == 0:
+        return f"{currency}{value:,.0f}"
+    return f"{currency}{value:,.{decimals}f}"
+
+
+# Accessibility helpers
+def add_pattern_overlay(fig: Any, _trace_index: int, _pattern: str = "diagonal") -> Any:
+    """Add pattern overlay for better accessibility.
+
+    Parameters
+    ----------
+    fig : plotly.graph_objects.Figure
+        Figure to modify
+    trace_index : int
+        Index of trace to add pattern to
+    pattern : str, default "diagonal"
+        Pattern type: "diagonal", "vertical", "horizontal", "dot"
+
+    Returns:
+    -------
+    plotly.graph_objects.Figure
+        Modified figure
+    """
+    # This would add SVG patterns for accessibility
+    # Implementation depends on Plotly version and trace type
+    return fig