processbehavior 0.2.0__py3-none-any.whl

processbehavior/plotting/report.py

@@ -0,0 +1,211 @@
+"""HTML report generation.
+
+Extracted from plotter.py to isolate report building from chart rendering.
+"""
+
+from __future__ import annotations
+
+import html
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .themes import ChartTheme, get_theme
+
+if TYPE_CHECKING:
+    from ..analysis_result import AnalysisResult
+
+logger = logging.getLogger(__name__)
+
+
+def generate_report(
+    result: AnalysisResult,
+    filepath: str,
+    include_charts: bool = True,
+    include_residuals: bool = True,
+    include_effects: bool = True,
+    include_summary: bool = True,
+    theme: str | ChartTheme = 'processbehavior',
+    width: int = 1200,
+    title: str | None = None,
+) -> None:
+    """Generate a comprehensive HTML report with all visualizations.
+
+    Creates a single-page HTML file with analysis summary, control charts,
+    residual diagnostics, and effects analysis.
+
+    Parameters
+    ----------
+    result : AnalysisResult
+        The analysis result to report on.
+    filepath : str
+        Output HTML file path.
+    include_charts : bool, default True
+        Include control charts.
+    include_residuals : bool, default True
+        Include residual diagnostic plots (if available).
+    include_effects : bool, default True
+        Include effects bar charts (if available).
+    include_summary : bool, default True
+        Include analysis summary section.
+    theme : str or ChartTheme, default 'processbehavior'
+        Visual theme for all charts.
+    width : int, default 1200
+        Width of charts in pixels.
+    title : str, optional
+        Report title (defaults to "Process Behavior Analysis Report").
+    """
+    # Import here to avoid circular import at module level
+    from .plotter import Plotter
+
+    plotter = Plotter(result)
+
+    sections: list[str] = []
+    report_title = title or 'Process Behavior Analysis Report'
+    esc = html.escape
+
+    # Resolve theme for plotter calls
+    resolved_theme = get_theme(theme) if isinstance(theme, str) else theme
+
+    # Summary section
+    if include_summary:
+        sections.append(_build_summary_section(result, esc))
+
+    # Control charts section
+    if include_charts:
+        fig = plotter.plot(theme=resolved_theme, width=width, height=500)
+        chart_html = fig.figure.to_html(full_html=False, include_plotlyjs=False)
+        sections.append(f"""
+        <div class="section">
+            <h2>Control Charts</h2>
+            {chart_html}
+        </div>
+        """)
+
+    # Residuals section
+    if include_residuals and result.has_residuals:
+        from .residuals import plot_residuals
+
+        fig = plot_residuals(result, theme=resolved_theme, width=width, height=350)
+        residual_html = fig.figure.to_html(full_html=False, include_plotlyjs=False)
+        sections.append(f"""
+        <div class="section">
+            <h2>Residual Diagnostics</h2>
+            <p>R1 residuals showing process variation over time.</p>
+            {residual_html}
+        </div>
+        """)
+
+    # Effects section
+    if include_effects and result.has_effects:
+        try:
+            fig = plotter.plot_effects(
+                effect_type='all',
+                theme=resolved_theme,
+                width=width,
+                height=400,
+            )
+            effects_html = fig.figure.to_html(full_html=False, include_plotlyjs=False)
+            sections.append(f"""
+            <div class="section">
+                <h2>Main Effects Analysis</h2>
+                <p>Factor and time effects showing contribution to process variation.</p>
+                {effects_html}
+            </div>
+            """)
+        except (ValueError, Exception):
+            pass  # No effects to plot
+
+    # Build full HTML
+    html_content = _build_html_page(report_title, sections, esc)
+    Path(filepath).write_text(html_content)
+    logger.info(f'Report generated: {filepath}')
+
+
+def _build_summary_section(result, esc):
+    """Build the HTML summary table."""
+    summary = result.summary
+    has_res = 'Yes' if summary['has_residuals'] else 'No'
+    has_eff = 'Yes' if summary['has_effects'] else 'No'
+    return f"""
+    <div class="section">
+        <h2>Analysis Summary</h2>
+        <table class="summary-table">
+            <tr><td><strong>ADS</strong></td><td>{esc(str(summary['analytical_sds']))} - {
+        esc(str(summary['analytical_sds_description']))
+    }</td></tr>
+            <tr><td><strong>Response Variable</strong></td><td>{esc(str(summary['response_var']))}</td></tr>
+            <tr><td><strong>Observations</strong></td><td>{esc(str(summary['n_observations']))}</td></tr>
+            <tr><td><strong>Charts</strong></td><td>{esc(', '.join(str(c) for c in summary['chart_types']))}</td></tr>
+            <tr><td><strong>Signals Detected</strong></td><td>{esc(str(summary['n_signals_total']))}</td></tr>
+            <tr><td><strong>Has Residuals</strong></td><td>{has_res}</td></tr>
+            <tr><td><strong>Has Effects</strong></td><td>{has_eff}</td></tr>
+        </table>
+    </div>
+    """
+
+
+def _build_html_page(report_title, sections, esc):
+    """Build the full HTML page."""
+    return f"""
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <title>{esc(report_title)}</title>
+    <script src="https://cdn.plot.ly/plotly-latest.min.js"></script>
+    <style>
+        body {{
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            max-width: 1400px;
+            margin: 0 auto;
+            padding: 20px;
+            background-color: #f5f5f5;
+        }}
+        h1 {{
+            color: #333;
+            border-bottom: 2px solid #4a90a4;
+            padding-bottom: 10px;
+        }}
+        h2 {{
+            color: #4a90a4;
+            margin-top: 30px;
+        }}
+        .section {{
+            background: white;
+            padding: 20px;
+            margin: 20px 0;
+            border-radius: 8px;
+            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+        }}
+        .summary-table {{
+            border-collapse: collapse;
+            width: 100%;
+            max-width: 600px;
+        }}
+        .summary-table td {{
+            padding: 8px 12px;
+            border-bottom: 1px solid #eee;
+        }}
+        .summary-table tr:last-child td {{
+            border-bottom: none;
+        }}
+        .footer {{
+            text-align: center;
+            color: #888;
+            font-size: 12px;
+            margin-top: 40px;
+            padding-top: 20px;
+            border-top: 1px solid #ddd;
+        }}
+    </style>
+</head>
+<body>
+    <h1>{esc(report_title)}</h1>
+    {''.join(sections)}
+    <div class="footer">
+        Generated with ProcessBehavior - Statistical Process Control for Python
+    </div>
+</body>
+</html>
+    """

processbehavior/plotting/residuals.py

@@ -0,0 +1,282 @@
+"""Residual diagnostic plots.
+
+Extracted from plotter.py to isolate residual visualization from
+control chart rendering.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+import plotly.graph_objects as go
+from plotly.subplots import make_subplots
+
+from ..exceptions import ValidationError
+from ._math import normal_pdf, normal_ppf
+from .control_chart import ControlChartFigure
+from .themes import ChartTheme, apply_theme, get_theme
+
+if TYPE_CHECKING:
+    from ..analysis_result import AnalysisResult
+
+
+def plot_residuals(
+    result: AnalysisResult,
+    residual_type: str = 'R1',
+    plot_type: str = 'all',
+    theme: str | ChartTheme = 'processbehavior',
+    width: int = 1200,
+    height: int = 400,
+) -> ControlChartFigure:
+    """Create residual diagnostic plots.
+
+    Visualizes VAS residuals to assess process behavior and identify
+    patterns that may indicate non-random variation.
+
+    Parameters
+    ----------
+    result : AnalysisResult
+        The analysis result containing residuals.
+    residual_type : str, default 'R1'
+        Which residual to plot ('R1', 'R2', 'R3', 'R4', 'R5').
+    plot_type : str, default 'all'
+        Type of diagnostic plot:
+        - 'histogram': Distribution of residuals
+        - 'qq': Quantile-quantile plot for normality
+        - 'sequence': Residuals vs. observation order
+        - 'all': All three plots in subplots
+    theme : str or ChartTheme, default 'processbehavior'
+        Visual theme.
+    width : int, default 1200
+        Figure width in pixels.
+    height : int, default 400
+        Figure height in pixels (per row for 'all').
+
+    Returns
+    -------
+    ControlChartFigure
+        Interactive figure with residual diagnostics.
+
+    Raises
+    ------
+    ValidationError
+        If residuals not available or invalid residual type.
+    """
+    if not result.has_residuals:
+        raise ValidationError(
+            'Residuals not available for this analysis.\nResiduals require SDS >= 1 (replicated observations).'
+        )
+
+    # One lookup, shared with get_residual: it finds stored residuals on the study-level
+    # snapshot and request residuals (R6/RCR6) on this result's dataset. Reading
+    # result.residuals directly here is what made this raise "not found" about a column
+    # the result was holding.
+    r_data = result.get_residual(residual_type).dropna()
+
+    theme = get_theme(theme) if isinstance(theme, str) else theme
+
+    if plot_type == 'all':
+        fig = _plot_all_diagnostics(r_data, residual_type, theme, width, height)
+    elif plot_type == 'histogram':
+        fig = _plot_histogram(r_data, residual_type, theme, width, height)
+    elif plot_type == 'qq':
+        fig = _plot_qq(r_data, residual_type, theme, width, height)
+    elif plot_type == 'sequence':
+        fig = _plot_sequence(r_data, residual_type, theme, width, height)
+    else:
+        raise ValidationError(f"Invalid plot_type: '{plot_type}'.\nOptions: 'all', 'histogram', 'qq', 'sequence'")
+
+    fig = apply_theme(fig, theme)
+    return ControlChartFigure(fig, result)
+
+
+# ---------------------------------------------------------------------------
+#  Internal plot builders
+# ---------------------------------------------------------------------------
+
+
+def _plot_all_diagnostics(r_data, residual_type, theme, width, height):
+    """3-panel diagnostic: histogram + Q-Q + sequence."""
+    fig = make_subplots(
+        rows=1,
+        cols=3,
+        subplot_titles=['Histogram', 'Q-Q Plot', 'Sequence Plot'],
+        horizontal_spacing=0.08,
+    )
+
+    # 1. Histogram
+    fig.add_trace(
+        go.Histogram(
+            x=r_data,
+            name='Residuals',
+            marker_color=theme.data_color,
+            opacity=0.7,
+            showlegend=False,
+        ),
+        row=1,
+        col=1,
+    )
+
+    # Normal curve overlay
+    x_range = np.linspace(r_data.min(), r_data.max(), 100)
+    mu, sigma = r_data.mean(), r_data.std()
+    y_normal = np.array([normal_pdf(x, mu, sigma) for x in x_range])
+    y_normal = y_normal * len(r_data) * (r_data.max() - r_data.min()) / 20
+
+    fig.add_trace(
+        go.Scatter(
+            x=x_range,
+            y=y_normal,
+            mode='lines',
+            name='Normal',
+            line=dict(color=theme.center_color, width=2, dash='dash'),
+            showlegend=False,
+        ),
+        row=1,
+        col=1,
+    )
+
+    # 2. Q-Q Plot
+    probs = np.linspace(0.01, 0.99, len(r_data))
+    theoretical_q = np.array([normal_ppf(p) for p in probs])
+    sample_q = np.sort(r_data.values)
+
+    fig.add_trace(
+        go.Scatter(
+            x=theoretical_q,
+            y=sample_q,
+            mode='markers',
+            name='Q-Q',
+            marker=dict(color=theme.data_color, size=5),
+            showlegend=False,
+        ),
+        row=1,
+        col=2,
+    )
+
+    # Reference line
+    qq_min = min(theoretical_q.min(), sample_q.min())
+    qq_max = max(theoretical_q.max(), sample_q.max())
+    fig.add_trace(
+        go.Scatter(
+            x=[qq_min, qq_max],
+            y=[qq_min * r_data.std() + r_data.mean(), qq_max * r_data.std() + r_data.mean()],
+            mode='lines',
+            name='Reference',
+            line=dict(color=theme.ucl_color, dash='dash'),
+            showlegend=False,
+        ),
+        row=1,
+        col=2,
+    )
+
+    # 3. Sequence plot
+    fig.add_trace(
+        go.Scatter(
+            x=list(range(len(r_data))),
+            y=r_data.values,
+            mode='lines+markers',
+            name='Residuals',
+            marker=dict(size=4, color=theme.data_color),
+            line=dict(color=theme.data_color, width=1),
+            showlegend=False,
+        ),
+        row=1,
+        col=3,
+    )
+    fig.add_hline(y=0, line_dash='dash', line_color=theme.center_color, row=1, col=3)
+
+    fig.update_layout(
+        title=f'{residual_type} Residual Diagnostics',
+        width=width,
+        height=height,
+        showlegend=False,
+    )
+    fig.update_xaxes(title_text='Residual Value', row=1, col=1)
+    fig.update_yaxes(title_text='Frequency', row=1, col=1)
+    fig.update_xaxes(title_text='Theoretical Quantiles', row=1, col=2)
+    fig.update_yaxes(title_text='Sample Quantiles', row=1, col=2)
+    fig.update_xaxes(title_text='Observation', row=1, col=3)
+    fig.update_yaxes(title_text='Residual', row=1, col=3)
+
+    return fig
+
+
+def _plot_histogram(r_data, residual_type, theme, width, height):
+    fig = go.Figure()
+    fig.add_trace(
+        go.Histogram(
+            x=r_data,
+            name='Residuals',
+            marker_color=theme.data_color,
+            opacity=0.7,
+        )
+    )
+    fig.update_layout(
+        title=f'{residual_type} Residual Distribution',
+        xaxis_title='Residual Value',
+        yaxis_title='Frequency',
+        width=width,
+        height=height,
+    )
+    return fig
+
+
+def _plot_qq(r_data, residual_type, theme, width, height):
+    probs = np.linspace(0.01, 0.99, len(r_data))
+    theoretical_q = np.array([normal_ppf(p) for p in probs])
+    sample_q = np.sort(r_data.values)
+
+    fig = go.Figure()
+    fig.add_trace(
+        go.Scatter(
+            x=theoretical_q,
+            y=sample_q,
+            mode='markers',
+            name='Data',
+            marker=dict(color=theme.data_color, size=6),
+        )
+    )
+    qq_min = min(theoretical_q.min(), sample_q.min())
+    qq_max = max(theoretical_q.max(), sample_q.max())
+    fig.add_trace(
+        go.Scatter(
+            x=[qq_min, qq_max],
+            y=[qq_min * r_data.std() + r_data.mean(), qq_max * r_data.std() + r_data.mean()],
+            mode='lines',
+            name='Normal Reference',
+            line=dict(color=theme.ucl_color, dash='dash'),
+        )
+    )
+    fig.update_layout(
+        title=f'{residual_type} Q-Q Plot',
+        xaxis_title='Theoretical Quantiles',
+        yaxis_title='Sample Quantiles',
+        width=width,
+        height=height,
+    )
+    return fig
+
+
+def _plot_sequence(r_data, residual_type, theme, width, height):
+    fig = go.Figure()
+    fig.add_trace(
+        go.Scatter(
+            x=list(range(len(r_data))),
+            y=r_data.values,
+            mode='lines+markers',
+            name='Residuals',
+            marker=dict(size=5, color=theme.data_color),
+            line=dict(color=theme.data_color, width=1),
+        )
+    )
+    fig.add_hline(y=0, line_dash='dash', line_color=theme.center_color)
+    fig.update_layout(
+        title=f'{residual_type} Residual Sequence Plot',
+        xaxis_title='Observation',
+        yaxis_title='Residual Value',
+        width=width,
+        height=height,
+    )
+    return fig

processbehavior/plotting/run_rules_viz.py

@@ -0,0 +1,150 @@
+"""Run rules visualization for control charts."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+import pandas as pd
+import plotly.graph_objects as go
+
+from processbehavior.exceptions import ProcessBehaviorError
+
+if TYPE_CHECKING:
+    from processbehavior.analysis_result import AnalysisResult
+
+    from .themes import ChartTheme
+
+logger = logging.getLogger(__name__)
+
+_RULE_SHORT_NAMES = {
+    'rule_2': '2 of 3 in Zone A',
+    'rule_3': '4 of 5 in Zone B+',
+    'rule_4': '8+ same side',
+    'rule_5': 'Trend',
+    'rule_6': 'Oscillation',
+    'rule_7': 'In Zone C',
+    'rule_8': 'Avoiding center',
+}
+
+
+def add_run_rules_visualization(
+    fig: go.Figure,
+    data: pd.DataFrame,
+    stats: dict,
+    chart_name: str,
+    value_col: str,
+    x_col: str,
+    theme: ChartTheme,
+    result: AnalysisResult,
+    row: int | None = None,
+    col: int | None = None,
+) -> go.Figure:
+    """
+    Add visualization for Western Electric run rules (Rules 2-8).
+
+    Detects rule violations and adds annotations and markers to highlight
+    the specific rules that were violated at each observation.
+
+    Parameters
+    ----------
+    fig : go.Figure
+        Plotly figure to add visualizations to
+    data : DataFrame
+        Chart data
+    stats : dict
+        Chart statistics
+    chart_name : str
+        Name of the chart being plotted
+    value_col : str
+        Name of the value column
+    x_col : str
+        Name of the x-axis column
+    theme : ChartTheme
+        Theme with rule colors and styling
+    result : AnalysisResult
+        Analysis result for signal detection
+    row : int, optional
+        Row number for faceted plots (1-indexed)
+    col : int, optional
+        Column number for faceted plots (1-indexed)
+    """
+    try:
+        signal_result = result.detect_signals(chart=chart_name)
+
+        if not signal_result.has_signals:
+            return fig
+
+        violations = signal_result.violations
+
+        # Skip Rule 1 (already handled by highlight_signals)
+        violations = violations[violations['rule_name'] != 'rule_1']
+
+        if violations.empty:
+            return fig
+
+        grouped = violations.groupby('obs_id', observed=True)
+
+        annotated_points = []
+
+        for obs_id, obs_violations in grouped:
+            if obs_id in data.index:
+                obs_data = data.loc[obs_id]
+                if isinstance(obs_data, pd.DataFrame):
+                    logger.debug('Skipping obs_id=%s: MultiIndex expanded to DataFrame', obs_id)
+                    continue
+            else:
+                continue
+
+            x_val = obs_data[x_col] if x_col in data.columns else obs_id
+            y_val = obs_data[value_col]
+
+            rules = obs_violations['rule_name'].unique().tolist()
+            rule_nums = [r.split('_')[1] if '_' in r else r for r in rules]
+
+            annotated_points.append(
+                {
+                    'x': x_val,
+                    'y': y_val,
+                    'rules': rules,
+                    'rule_nums': rule_nums,
+                    'hover': '<br>'.join([_RULE_SHORT_NAMES.get(r, r) for r in rules]),
+                }
+            )
+
+        if not annotated_points:
+            return fig
+
+        x_vals = [p['x'] for p in annotated_points]
+        y_vals = [p['y'] for p in annotated_points]
+        hover_texts = [f'Rule violations:<br>{p["hover"]}<br>Value: {p["y"]:.3f}' for p in annotated_points]
+
+        scatter_kwargs = dict(
+            x=x_vals,
+            y=y_vals,
+            mode='markers',
+            name='Pattern Signals',
+            marker=dict(
+                size=theme.data_marker_size,
+                color=theme.pattern_signal_color,
+                symbol='circle',
+                line=dict(width=1, color='darkorange'),
+            ),
+            hovertext=hover_texts,
+            hoverinfo='text',
+            showlegend=False,
+        )
+
+        if row is not None and col is not None:
+            scatter_kwargs['showlegend'] = False
+            fig.add_trace(go.Scatter(**scatter_kwargs), row=row, col=col)
+        else:
+            fig.add_trace(go.Scatter(**scatter_kwargs))
+
+        return fig
+    except (AttributeError, KeyError, ValueError, ProcessBehaviorError) as e:
+        logger.info('Skipping run-rule annotations: %s', e)
+        return fig
+    except Exception:
+        logger.exception('Run-rule annotation failed unexpectedly')
+        raise