"""SQN (System Quality Number) analyzer visual — hero + colour-band gauge. Van Tharp's SQN measures the quality of a trading system by looking at the distribution of trade P&L. Higher values indicate more consistent profitability. """ from __future__ import annotations import math from typing import Any from bokeh.layouts import column, row from bokeh.models.css import InlineStyleSheet from bokeh.models.layouts import LayoutDOM from ..helper.analyzer_visual import ( format_value, hero_stats_div, section_title, text_div, zone_scale_plot, ) from ..helper.table import ColumnDataType, build_table from ..schemes.scheme import Scheme # SQN quality tiers (Van Tharp's classification) _SQN_ZONES: list[tuple[float, float, str]] = [ (-3.0, 1.0, "Below Avg"), (1.0, 2.0, "Average"), (2.0, 3.0, "Good"), (3.0, 5.0, "Excellent"), (5.0, 7.0, "Superb"), (7.0, 10.0, "Holy Grail"), ] def _sqn_quality(sqn: float) -> tuple[str, str]: """Classify SQN value into a quality tier.""" if not math.isfinite(sqn): return ("N/A", "Insufficient trade data for SQN") if sqn < 1.0: return ("Below Avg", "SQN < 1.0 — subpar system quality") if sqn < 2.0: return ("Average", "SQN 1.0–2.0 — average system performance") if sqn < 3.0: return ("Good", "SQN 2.0–3.0 — good system, tradable") if sqn < 5.0: return ("Excellent", "SQN 3.0–5.0 — excellent system") if sqn < 7.0: return ("Superb", "SQN 5.0–7.0 — superb, among the best") return ("Holy Grail", "SQN ≥ 7.0 — exceptional system quality") def _sqn_colour(sqn: float, scheme: Scheme) -> str: """Colour for SQN value.""" if not math.isfinite(sqn): return scheme.color_gray if sqn < 1.0: return scheme.color_red if sqn < 2.0: return scheme.color_orange if sqn < 3.0: return scheme.color_amber if sqn < 5.0: return scheme.color_green return scheme.color_green def analysis_plot(self: Any, scheme: Scheme, stylesheet: InlineStyleSheet) -> LayoutDOM | None: a: dict[str, Any] = self.get_analysis() sqn: float = float(a.get("sqn", float("nan"))) trades: int = int(a.get("trades", 0)) sqn_valid: bool = math.isfinite(sqn) label, _ = _sqn_quality(sqn if sqn_valid else float("nan")) color: str = _sqn_colour(sqn if sqn_valid else float("nan"), scheme) hero_div = hero_stats_div( value=format_value(sqn), color=color, subtitle=f"{label} • {trades} trades", subtitle_color=color, ) hero_div.stylesheets = [ *hero_div.stylesheets, InlineStyleSheet(css=":host { justify-self: center; }"), ] x_hi: float = max(10.0, (sqn if sqn_valid else 0.0) * 1.4 + 2.0) zones: list[tuple[float, float, str, str]] = [] zone_colours: list[str] = [ scheme.color_red, scheme.color_orange, scheme.color_amber, scheme.color_green, scheme.color_green, scheme.color_green, ] for (lo, hi, zlabel), zcolor in zip(_SQN_ZONES, zone_colours): zones.append((lo, min(hi, x_hi), zcolor, zlabel)) gauge = zone_scale_plot( zones=zones, scheme=scheme, x_lo=-3.0, x_hi=x_hi, marker=sqn if sqn_valid else None, marker_label=f"SQN {format_value(sqn)}" if sqn_valid else "", height=90, ) gauge.stylesheets = [*gauge.stylesheets, stylesheet] info_text: str = ( "Van Tharp's System Quality Number measures the consistency of trade returns. " "SQN = sqrt(N) × mean(P&L) / stddev(P&L). Higher values indicate more " "consistent profitability relative to trade risk." ) info_div = text_div(text=info_text, scheme=scheme, stylesheet=stylesheet) split_css: InlineStyleSheet = InlineStyleSheet( css=( ":host { display: grid; grid-template-columns: 1fr 3fr; " "column-gap: 12px; align-items: center; }" ), ) return column( children=[ section_title("System Quality Number", stylesheet), info_div, row( children=[hero_div, gauge], sizing_mode="stretch_width", stylesheets=[split_css], ), ], sizing_mode="stretch_width", ) def analysis_table(self: Any, scheme: Scheme, stylesheet: InlineStyleSheet) -> LayoutDOM | None: a: dict[str, Any] = self.get_analysis() sqn: float = float(a.get("sqn", float("nan"))) trades: int = int(a.get("trades", 0)) label, description = _sqn_quality(sqn) tab: list[list[Any]] = [ ["Metric", ColumnDataType.STRING], ["Value", ColumnDataType.STRING], ] tab[0].extend(["SQN", "Number of Trades", "Quality", "Description"]) tab[1].extend( [ format_value(sqn), str(trades) if trades > 0 else "-", label, description, ] ) return column( children=[ build_table(tab, scheme, stylesheet), ], sizing_mode="stretch_width", )