Add Residual and Effects Plotting + Improve Chart Design

[cnicholas]

Overview

The ProcessBehavior library calculates comprehensive VAS (Variance Analysis System) residuals (R1-R5) and main effects, but these powerful analytical outputs are not currently visualized. Additionally, the existing control charts could be enhanced with better annotations, labels, and summary statistics.

Current State

What Works:

• ✅ R1-R5 residuals are calculated correctly
• ✅ Main effects and interactions are computed
• ✅ Data is available in result.residuals and result.effects
• ✅ Can be exported to Excel for manual plotting

What's Missing:

• ❌ No built-in methods to plot residuals
• ❌ No built-in methods to plot effects
• ❌ No built-in methods to plot interactions
• ❌ Charts lack process capability annotations
• ❌ Charts lack summary statistics panels
• ❌ Subgroup size indicators not shown

Proposed Solution

Part 1: Add Residual/Effects Visualization Methods

Add three new plotting methods to AnalysisResult:

1. result.plot_residuals(residual_types=['R1', 'R2', 'R3', 'R4', 'R5'])

# Histogram or scatter plot showing distribution of residuals
result.plot_residuals(residual_types=['R1', 'R5'])
# Shows variance decomposition visually

2. result.plot_effects(effect_type='main')

# Bar chart showing main effects per factor
result.plot_effects(effect_type='main')
# Shows which factors have largest impact

3. result.plot_interactions()

# Heatmap showing factor × time interactions
result.plot_interactions()
# Shows interaction patterns

Part 2: Enhance Chart Design

Improve all control charts with:

Annotations:

• Process capability indices (Cp, Cpk) when applicable
• Percentage of points within/beyond limits
• Detection rule annotations (which rules triggered)

Labels:

• Enhanced axis labels with units (if provided)
• Better title formatting with analysis metadata
• Clearer limit labels (UCL/LCL values shown)

Summary Statistics:

• Panel showing key stats (n, mean, σ, range)
• Sample size indicator per subgroup (n=5, n=varies, etc.)
• SDS indicator ("SDS 1: Full Factorial with Replication")

Visual Improvements:

• Better legend positioning (non-overlapping)
• Grid styling improvements
• Color-coded zones (A, B, C for Western Electric rules)
• Improved marker styling for signals

Implementation Details

Files to Modify:

• processbehavior/plotting/plotter.py - Add new plotting methods
• processbehavior/analysis_result.py - Expose new plot methods
• processbehavior/plotting/themes.py - Add annotation themes

Estimated Effort: 3-5 days

Benefits

• Residual plots: Make VAS framework actually usable for practitioners
• Effects plots: Quick visual identification of significant factors
• Better annotations: Reduce need to calculate stats manually
• Summary panels: All key information visible at a glance
• Professional output: Publication-ready charts

References

From comprehensive codebase review:

• Current residual calculation: processbehavior/residual_calculator.py
• Current effects calculation: processbehavior/effects_calculator.py
• Current plotting infrastructure: processbehavior/plotting/plotter.py

Acceptance Criteria

• plot_residuals() method implemented and tested
• plot_effects() method implemented and tested
• plot_interactions() method implemented and tested
• All charts show process capability annotations
• All charts show summary statistics panel
• All charts show subgroup size indicators
• Documentation updated with examples
• Tests added for new functionality