ml4t-diagnostic 0.1.0a1__py3-none-any.whl

ml4t/diagnostic/reporting/base.py

@@ -0,0 +1,130 @@
+"""Base report generation functionality."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from ml4t.diagnostic.results.base import BaseResult
+
+
+class ReportFormat(str, Enum):
+    """Supported report formats."""
+
+    HTML = "html"
+    JSON = "json"
+    MARKDOWN = "markdown"
+
+
+class ReportGenerator(ABC):
+    """Base class for report generators.
+
+    Provides abstract interface for rendering evaluation results
+    into different formats (HTML, JSON, Markdown).
+
+    Subclasses must implement render() method.
+
+    Examples:
+        >>> generator = HTMLReportGenerator()
+        >>> report = generator.render(result)
+        >>> generator.save(report, "output.html")
+    """
+
+    @abstractmethod
+    def render(self, result: BaseResult, **options: Any) -> str:
+        """Render result to string format.
+
+        Args:
+            result: Evaluation result to render
+            **options: Format-specific rendering options
+
+        Returns:
+            Rendered report as string
+        """
+        ...
+
+    def save(self, content: str, filepath: str | Path) -> None:
+        """Save rendered report to file.
+
+        Args:
+            content: Rendered report content
+            filepath: Output file path
+        """
+        path = Path(filepath)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+
+
+class ReportFactory:
+    """Factory for creating report generators.
+
+    Provides convenient access to all report generators via format enum.
+
+    Examples:
+        >>> generator = ReportFactory.create(ReportFormat.HTML)
+        >>> report = generator.render(result)
+
+        >>> # Or use convenience method
+        >>> report = ReportFactory.render(result, ReportFormat.MARKDOWN)
+    """
+
+    _generators: dict[ReportFormat, type[ReportGenerator]] = {}
+
+    @classmethod
+    def register(cls, format: ReportFormat, generator_class: type[ReportGenerator]) -> None:
+        """Register a report generator for a format.
+
+        Args:
+            format: Report format enum
+            generator_class: Generator class to register
+        """
+        cls._generators[format] = generator_class
+
+    @classmethod
+    def create(cls, format: ReportFormat) -> ReportGenerator:
+        """Create report generator for format.
+
+        Args:
+            format: Desired report format
+
+        Returns:
+            Report generator instance
+
+        Raises:
+            ValueError: If format not registered
+        """
+        if format not in cls._generators:
+            raise ValueError(
+                f"No generator registered for format: {format}. Available: {list(cls._generators.keys())}"
+            )
+        return cls._generators[format]()
+
+    @classmethod
+    def render(cls, result: BaseResult, format: ReportFormat, **options: Any) -> str:
+        """Convenience method to create generator and render in one call.
+
+        Args:
+            result: Evaluation result to render
+            format: Desired report format
+            **options: Format-specific rendering options
+
+        Returns:
+            Rendered report as string
+
+        Examples:
+            >>> report = ReportFactory.render(result, ReportFormat.HTML)
+            >>> report = ReportFactory.render(result, ReportFormat.JSON, indent=4)
+        """
+        generator = cls.create(format)
+        return generator.render(result, **options)
+
+    @classmethod
+    def available_formats(cls) -> list[ReportFormat]:
+        """List all registered report formats.
+
+        Returns:
+            List of available formats
+        """
+        return list(cls._generators.keys())

ml4t/diagnostic/reporting/html_renderer.py

@@ -0,0 +1,275 @@
+"""HTML report renderer with template support."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ml4t.diagnostic.reporting.base import ReportFormat, ReportGenerator
+from ml4t.diagnostic.results.base import BaseResult
+
+
+class HTMLReportGenerator(ReportGenerator):
+    """Generate HTML reports from evaluation results.
+
+    Supports custom templates and styling.
+
+    Examples:
+        >>> generator = HTMLReportGenerator()
+        >>> report = generator.render(result, template="default")
+        >>> generator.save(report, "report.html")
+
+        >>> # Custom template
+        >>> custom_template = '''
+        ... <html><body>
+        ... <h1>{analysis_type}</h1>
+        ... {content}
+        ... </body></html>
+        ... '''
+        >>> report = generator.render(result, custom_template=custom_template)
+    """
+
+    DEFAULT_TEMPLATE = """<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{title}</title>
+    <style>
+        body {{
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+            max-width: 1200px;
+            margin: 0 auto;
+            padding: 20px;
+            background-color: #f5f5f5;
+        }}
+        .container {{
+            background-color: white;
+            padding: 30px;
+            border-radius: 8px;
+            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+        }}
+        h1 {{
+            color: #2c3e50;
+            border-bottom: 2px solid #3498db;
+            padding-bottom: 10px;
+        }}
+        h2 {{
+            color: #34495e;
+            margin-top: 30px;
+        }}
+        .metadata {{
+            background-color: #ecf0f1;
+            padding: 15px;
+            border-radius: 4px;
+            margin-bottom: 20px;
+        }}
+        .metadata-item {{
+            margin: 5px 0;
+        }}
+        .summary {{
+            background-color: #fff9e6;
+            border-left: 4px solid #f39c12;
+            padding: 15px;
+            margin: 20px 0;
+        }}
+        table {{
+            width: 100%;
+            border-collapse: collapse;
+            margin: 20px 0;
+        }}
+        th {{
+            background-color: #3498db;
+            color: white;
+            padding: 12px;
+            text-align: left;
+        }}
+        td {{
+            padding: 10px;
+            border-bottom: 1px solid #ddd;
+        }}
+        tr:hover {{
+            background-color: #f5f5f5;
+        }}
+        .footer {{
+            margin-top: 40px;
+            padding-top: 20px;
+            border-top: 1px solid #ddd;
+            color: #7f8c8d;
+            font-size: 0.9em;
+        }}
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>{title}</h1>
+        {metadata}
+        {summary}
+        {dataframes}
+        <div class="footer">
+            Generated by ML4T Diagnostic {version}
+        </div>
+    </div>
+</body>
+</html>"""
+
+    def render(self, result: BaseResult, **options: Any) -> str:
+        """Render result to HTML format.
+
+        Args:
+            result: Evaluation result to render
+            **options: HTML rendering options
+                - template: Template name or "default" (default: "default")
+                - custom_template: Custom HTML template string
+                - include_metadata: Include metadata section (default: True)
+                - include_dataframes: Include DataFrame tables (default: True)
+                - max_rows: Max rows to show in DataFrame tables (default: 50)
+
+        Returns:
+            HTML string
+        """
+        template = options.get("custom_template") or self.DEFAULT_TEMPLATE
+        include_metadata = options.get("include_metadata", True)
+        include_dataframes = options.get("include_dataframes", True)
+        max_rows = options.get("max_rows", 50)
+
+        # Build template variables
+        analysis_type = result.analysis_type.replace("_", " ").title()
+        title = f"{analysis_type} Report"
+
+        # Metadata section
+        metadata_html = ""
+        if include_metadata:
+            metadata_html = f"""
+            <div class="metadata">
+                <h2>Metadata</h2>
+                <div class="metadata-item"><strong>Analysis Type:</strong> {result.analysis_type}</div>
+                <div class="metadata-item"><strong>Created:</strong> {result.created_at}</div>
+                <div class="metadata-item"><strong>ML4T Diagnostic Version:</strong> {result.version}</div>
+            </div>
+            """
+
+        # Summary section
+        summary_html = f"""
+        <div class="summary">
+            <h2>Summary</h2>
+            <pre>{self._escape_html(result.summary())}</pre>
+        </div>
+        """
+
+        # DataFrame sections
+        dataframes_html = ""
+        if include_dataframes:
+            try:
+                available_dfs = result.list_available_dataframes()
+                if available_dfs:
+                    df_sections = []
+                    for df_name in available_dfs:
+                        df = result.get_dataframe(df_name)
+
+                        # Limit rows if needed
+                        if len(df) > max_rows:
+                            display_df = df.head(max_rows)
+                            caption = f"Showing first {max_rows} of {len(df)} rows"
+                        else:
+                            display_df = df
+                            caption = ""
+
+                        table_html = self._dataframe_to_html(
+                            display_df, title=df_name.replace("_", " ").title(), caption=caption
+                        )
+                        df_sections.append(table_html)
+
+                    dataframes_html = "\n".join(df_sections)
+            except (NotImplementedError, ValueError):
+                # Some results may not have DataFrames
+                pass
+
+        # Fill template
+        html = template.format(
+            title=title,
+            analysis_type=analysis_type,
+            metadata=metadata_html,
+            summary=summary_html,
+            dataframes=dataframes_html,
+            version=result.version,
+        )
+
+        return html
+
+    def _dataframe_to_html(self, df, title: str = "", caption: str = "") -> str:
+        """Convert Polars DataFrame to HTML table.
+
+        Args:
+            df: Polars DataFrame
+            title: Table title
+            caption: Optional caption
+
+        Returns:
+            HTML table string
+        """
+        html_parts = []
+
+        if title:
+            html_parts.append(f"<h2>{title}</h2>")
+
+        if caption:
+            html_parts.append(f"<p><em>{caption}</em></p>")
+
+        # Table header
+        html_parts.append("<table>")
+        html_parts.append("<thead><tr>")
+        for col in df.columns:
+            html_parts.append(f"<th>{self._escape_html(col)}</th>")
+        html_parts.append("</tr></thead>")
+
+        # Table body
+        html_parts.append("<tbody>")
+        for row in df.iter_rows():
+            html_parts.append("<tr>")
+            for val in row:
+                formatted = self._format_cell(val)
+                html_parts.append(f"<td>{formatted}</td>")
+            html_parts.append("</tr>")
+        html_parts.append("</tbody>")
+        html_parts.append("</table>")
+
+        return "\n".join(html_parts)
+
+    def _format_cell(self, value: Any) -> str:
+        """Format cell value for HTML display.
+
+        Args:
+            value: Cell value
+
+        Returns:
+            Formatted HTML string
+        """
+        if value is None:
+            return "<em>null</em>"
+        elif isinstance(value, float):
+            return f"{value:.4f}"
+        else:
+            return self._escape_html(str(value))
+
+    def _escape_html(self, text: str) -> str:
+        """Escape HTML special characters.
+
+        Args:
+            text: Text to escape
+
+        Returns:
+            Escaped text
+        """
+        return (
+            text.replace("&", "&amp;")
+            .replace("<", "&lt;")
+            .replace(">", "&gt;")
+            .replace('"', "&quot;")
+            .replace("'", "&#39;")
+        )
+
+
+# Register with factory
+from ml4t.diagnostic.reporting.base import ReportFactory  # noqa: E402
+
+ReportFactory.register(ReportFormat.HTML, HTMLReportGenerator)

ml4t/diagnostic/reporting/json_renderer.py

@@ -0,0 +1,51 @@
+"""JSON report renderer."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ml4t.diagnostic.reporting.base import ReportFormat, ReportGenerator
+from ml4t.diagnostic.results.base import BaseResult
+
+
+class JSONReportGenerator(ReportGenerator):
+    """Generate JSON reports from evaluation results.
+
+    Leverages BaseResult's built-in JSON serialization.
+
+    Examples:
+        >>> generator = JSONReportGenerator()
+        >>> report = generator.render(result, indent=2)
+        >>> generator.save(report, "report.json")
+    """
+
+    def render(self, result: BaseResult, **options: Any) -> str:
+        """Render result to JSON format.
+
+        Args:
+            result: Evaluation result to render
+            **options: JSON rendering options
+                - indent: Indentation level (default: 2)
+                - exclude_none: Exclude None values (default: False)
+
+        Returns:
+            JSON string
+        """
+        indent = options.get("indent", 2)
+        exclude_none = options.get("exclude_none", False)
+
+        # Use BaseResult's built-in JSON export
+        if exclude_none:
+            # Get dict first, then convert to JSON
+            data = result.to_dict(exclude_none=True)
+            import json
+
+            return json.dumps(data, indent=indent)
+        else:
+            return result.to_json_string(indent=indent)
+
+
+# Register with factory
+from ml4t.diagnostic.reporting.base import ReportFactory  # noqa: E402
+
+ReportFactory.register(ReportFormat.JSON, JSONReportGenerator)

ml4t/diagnostic/reporting/markdown_renderer.py

@@ -0,0 +1,117 @@
+"""Markdown report renderer."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ml4t.diagnostic.reporting.base import ReportFormat, ReportGenerator
+from ml4t.diagnostic.results.base import BaseResult
+
+
+class MarkdownReportGenerator(ReportGenerator):
+    """Generate Markdown reports from evaluation results.
+
+    Creates human-readable Markdown documentation from results.
+
+    Examples:
+        >>> generator = MarkdownReportGenerator()
+        >>> report = generator.render(result, include_metadata=True)
+        >>> generator.save(report, "report.md")
+    """
+
+    def render(self, result: BaseResult, **options: Any) -> str:
+        """Render result to Markdown format.
+
+        Args:
+            result: Evaluation result to render
+            **options: Markdown rendering options
+                - include_metadata: Include metadata section (default: True)
+                - include_dataframes: Include DataFrame tables (default: True)
+                - max_rows: Max rows to show in DataFrame tables (default: 10)
+
+        Returns:
+            Markdown string
+        """
+        include_metadata = options.get("include_metadata", True)
+        include_dataframes = options.get("include_dataframes", True)
+        max_rows = options.get("max_rows", 10)
+
+        sections = []
+
+        # Title
+        analysis_type = result.analysis_type.replace("_", " ").title()
+        sections.append(f"# {analysis_type} Report\n")
+
+        # Metadata section
+        if include_metadata:
+            sections.append("## Metadata\n")
+            sections.append(f"- **Analysis Type**: {result.analysis_type}")
+            sections.append(f"- **Created**: {result.created_at}")
+            sections.append(f"- **ML4T Diagnostic Version**: {result.version}\n")
+
+        # Summary section (all results have summary())
+        sections.append("## Summary\n")
+        sections.append(f"```\n{result.summary()}\n```\n")
+
+        # DataFrame sections (if available)
+        if include_dataframes:
+            try:
+                available_dfs = result.list_available_dataframes()
+                if available_dfs:
+                    sections.append("## Data Tables\n")
+                    for df_name in available_dfs:
+                        df = result.get_dataframe(df_name)
+                        sections.append(f"### {df_name.replace('_', ' ').title()}\n")
+
+                        # Limit rows if needed
+                        if len(df) > max_rows:
+                            display_df = df.head(max_rows)
+                            sections.append(f"*Showing first {max_rows} of {len(df)} rows*\n")
+                        else:
+                            display_df = df
+
+                        # Convert to markdown table (basic implementation)
+                        sections.append(self._dataframe_to_markdown(display_df))
+                        sections.append("")
+            except (NotImplementedError, ValueError):
+                # Some results may not have DataFrames
+                pass
+
+        return "\n".join(sections)
+
+    def _dataframe_to_markdown(self, df) -> str:
+        """Convert Polars DataFrame to Markdown table.
+
+        Args:
+            df: Polars DataFrame
+
+        Returns:
+            Markdown table string
+        """
+
+        # Get column names
+        cols = df.columns
+
+        # Header
+        header = "| " + " | ".join(cols) + " |"
+        separator = "| " + " | ".join(["---"] * len(cols)) + " |"
+
+        # Rows
+        rows = []
+        for row in df.iter_rows():
+            formatted = []
+            for val in row:
+                # Format values
+                if isinstance(val, float):
+                    formatted.append(f"{val:.4f}")
+                else:
+                    formatted.append(str(val))
+            rows.append("| " + " | ".join(formatted) + " |")
+
+        return "\n".join([header, separator] + rows)
+
+
+# Register with factory
+from ml4t.diagnostic.reporting.base import ReportFactory  # noqa: E402
+
+ReportFactory.register(ReportFormat.MARKDOWN, MarkdownReportGenerator)

ml4t/diagnostic/results/AGENT.md

@@ -0,0 +1,24 @@
+# results/ - Result Dataclasses
+
+Immutable results with `.to_dict()`, `.summary()`, `.get_dataframe()`.
+
+## Modules
+
+| File | Purpose |
+|------|---------|
+| base.py | `BaseResult` abstract |
+| feature_results.py | Feature diagnostics |
+| sharpe_results.py | DSR, PSR results |
+| event_results.py | Event study results |
+| portfolio_results.py | Portfolio analysis |
+
+## Subdirectories
+
+| Directory | Purpose |
+|-----------|---------|
+| signal_results/ | Signal analysis results (7 modules) |
+| barrier_results/ | Barrier analysis results (6 modules) |
+
+## Key Classes
+
+`SignalResult`, `BarrierTearSheet`, `DSRResult`, `FeatureDiagnosticsResult`, `EventStudyResult`

ml4t/diagnostic/results/__init__.py

@@ -0,0 +1,105 @@
+"""Type-safe Pydantic result schemas for all evaluation outputs.
+
+This module provides structured result schemas for:
+- Feature diagnostics (Module A)
+- Cross-feature analysis (Module B)
+- Feature-outcome relationships (Module C)
+- Portfolio evaluation (Module D)
+- Sharpe framework analysis
+
+All results support:
+- JSON serialization
+- DataFrame conversion
+- Human-readable summaries
+- Type-safe access via Pydantic validation
+"""
+
+from ml4t.diagnostic.results.barrier_results import (
+    BarrierTearSheet,
+    HitRateResult,
+    PrecisionRecallResult,
+    ProfitFactorResult,
+    TimeToTargetResult,
+)
+from ml4t.diagnostic.results.base import BaseResult
+from ml4t.diagnostic.results.event_results import (
+    AbnormalReturnResult,
+    EventStudyResult,
+)
+from ml4t.diagnostic.results.feature_results import (
+    ACFResult,
+    CrossFeatureResult,
+    FeatureDiagnosticsResult,
+    FeatureOutcomeResult,
+    ICAnalysisResult,
+    StationarityTestResult,
+    ThresholdAnalysisResult,
+)
+from ml4t.diagnostic.results.multi_signal_results import (
+    ComparisonResult,
+    MultiSignalSummary,
+)
+from ml4t.diagnostic.results.portfolio_results import (
+    BayesianComparisonResult,
+    PortfolioEvaluationResult,
+    PortfolioMetrics,
+)
+from ml4t.diagnostic.results.sharpe_results import (
+    DSRResult,
+    FDRResult,
+    MinTRLResult,
+    PSRResult,
+    SharpeFrameworkResult,
+)
+from ml4t.diagnostic.results.signal_results import (
+    IRtcResult,
+    QuantileAnalysisResult,
+    RASICResult,
+    SignalICResult,
+    SignalTearSheet,
+    TurnoverAnalysisResult,
+)
+
+__all__ = [
+    # Base
+    "BaseResult",
+    # Feature diagnostics (Module A)
+    "StationarityTestResult",
+    "ACFResult",
+    "FeatureDiagnosticsResult",
+    # Cross-feature (Module B)
+    "CrossFeatureResult",
+    # Feature-outcome (Module C)
+    "ICAnalysisResult",
+    "ThresholdAnalysisResult",
+    "FeatureOutcomeResult",
+    # Portfolio (Module D)
+    "PortfolioMetrics",
+    "BayesianComparisonResult",
+    "PortfolioEvaluationResult",
+    # Sharpe framework
+    "PSRResult",
+    "MinTRLResult",
+    "DSRResult",
+    "FDRResult",
+    "SharpeFrameworkResult",
+    # Signal analysis
+    "SignalICResult",
+    "RASICResult",
+    "QuantileAnalysisResult",
+    "TurnoverAnalysisResult",
+    "IRtcResult",
+    "SignalTearSheet",
+    # Event study
+    "AbnormalReturnResult",
+    "EventStudyResult",
+    # Multi-signal analysis
+    "MultiSignalSummary",
+    "ComparisonResult",
+    # Barrier analysis
+    "HitRateResult",
+    "ProfitFactorResult",
+    "PrecisionRecallResult",
+    "TimeToTargetResult",
+    "BarrierTearSheet",
+]