processbehavior 0.2.0__py3-none-any.whl

processbehavior/analysis_result.py

@@ -0,0 +1,1276 @@
+"""
+AnalysisResult - Unified container for all analysis outputs.
+
+This module provides a comprehensive result object that makes all analysis data
+easily accessible in one place:
+- Chart data (Xbar, S, X, mR) with chart type as primary key
+- Stratified chart support with strata property and focus() for drill-down
+- Residuals (R1-R5)
+- Effects (main effects, interactions)
+- Summary metadata (design-state lineage, statistics, capabilities)
+
+Chart Structure
+---------------
+Charts are always keyed by chart type (e.g., 'Xbar', 'S', 'X', 'mR').
+X and mR charts are bundled together, similar to Xbar and S.
+
+For stratified X/mR charts, the structure includes:
+- Combined DataFrame with all strata (rsg column identifies them)
+- Statistics nested by stratum: {'Machine1': {...}, 'Machine2': {...}}
+- 'strata' list for discovering available subgroups
+
+Usage
+-----
+Basic access::
+
+    result = study.execute()
+    xbar_data = result.get_chart('Xbar')
+    stats = result.get_statistics('Xbar')
+
+Stratified chart drill-down::
+
+    result.strata           # ['Machine1_F2_1', 'Machine2_F2_2', ...]
+    result.is_stratified    # True
+
+    focused = result.focus('Machine1_F2_1')
+    focused.plot()
+    focused.to_excel('machine1.xlsx')
+
+Access residuals and effects::
+
+    residuals = result.residuals      # DataFrame with R1-R5
+    main_effects = result.effects
+    interactions = result.interactions
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Literal
+
+import pandas as pd
+
+from .exceptions import ChartNotAvailableError, ValidationError
+from .sds_detector import SDSRegistry
+from .spc_constants import ALL_RESIDUALS, REQUEST_RESIDUALS, STORED_RESIDUALS, normalize_chart_name
+from .types import Charts
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from .analysis_dataset import AnalysisDataSet
+    from .plotting.control_chart import ControlChartFigure
+    from .signals.result import SignalResult
+
+logger = logging.getLogger(__name__)
+
+# Built-in theme names (Literal for IDE autocomplete on .plot(theme=...)).
+# Custom themes registered via ``register_theme`` work too — the bare
+# ``str`` union on the parameter type allows them through.
+ThemeName = Literal['processbehavior', 'ggplot', 'minimal', 'dark', 'publication']
+
+# Standard SPC chart type names
+STANDARD_CHART_NAMES = {'Xbar', 'S', 'X', 'mR'}
+
+
+class AnalysisResult:
+    """
+    Comprehensive analysis result container.
+
+    This class unifies all analysis outputs into a single, easily accessible object.
+    It provides:
+    - Chart data and statistics (Xbar, S, X, mR)
+    - VAS residuals (R1-R5)
+    - Main effects and interactions
+    - Design-state lineage information (PDS / ODS / ADS)
+    - Summary metadata
+    - Stratified chart support with focus() for drill-down
+
+    Chart Structure
+    ---------------
+    Charts are keyed by chart type (e.g., 'Xbar', 'S', 'X', 'mR'):
+
+    - For standard charts:
+      ``{'Xbar': {'data': DataFrame, 'statistics': dict, 'metadata': dict}}``
+
+    - For stratified X/mR charts (multiple subgroups):
+      ``{'X': {'data': DataFrame, 'statistics': {stratum: dict}, 'strata': list}}``
+
+    X and mR charts are always bundled together, similar to Xbar and S.
+
+    Attributes
+    ----------
+    charts : dict
+        Dictionary of chart data keyed by chart type.
+    dataset : pd.DataFrame
+        Full analysis dataset with all calculations.
+    residuals : pd.DataFrame or None
+        VAS residuals (R1-R5) if calculated.
+    effects : dict or None
+        Main effects if calculated.
+    interactions : dict or None
+        Interaction effects if calculated.
+    summary : dict
+        Comprehensive metadata about the analysis.
+    sds : int
+        Sampling Design State (0-6).
+    sds_info : dict
+        Detailed SDS characteristics.
+    strata : list[str]
+        List of subgroup names for stratified charts (empty if not stratified).
+    is_stratified : bool
+        True if result contains stratified charts with multiple subgroups.
+
+    Examples
+    --------
+    Basic usage:
+
+    >>> result = study.execute()
+    >>> xbar = result.get_chart('Xbar')
+    >>> print(result.summary)
+
+    Stratified chart access:
+
+    >>> result.strata  # ['Machine1_F2_1', 'Machine2_F2_2', ...]
+    >>> focused = result.focus('Machine1_F2_1')
+    >>> focused.plot()
+    >>> focused.to_excel('machine1.xlsx')
+    """
+
+    def __init__(
+        self,
+        charts: Charts,
+        analysis_dataset_obj: AnalysisDataSet,
+        analysis_type: str | None = None,
+        request_dataset: pd.DataFrame | None = None,
+    ):
+        """
+        Initialize AnalysisResult from chart data and AnalysisDataSet.
+
+        Parameters
+        ----------
+        charts : Charts (dict[str, ChartPayload])
+            Chart-name → :class:`ChartPayload` map. Each payload carries
+            ``data`` (DataFrame), ``statistics`` (flat or by-stratum),
+            ``metadata``, and optional ``strata``.
+        analysis_dataset_obj : AnalysisDataSet
+            The underlying AnalysisDataSet with all calculations
+        analysis_type : str, optional
+            The executed chart type ('Xbar', 'S', 'X', 'mR').
+            Passed from Analysis at execute() time so result.summary
+            reports the executed chart, not the recommended one.
+        request_dataset : pd.DataFrame, optional
+            This request's own frame, carrying its request residual (R6/RCR6).
+            Only a request-residual execute() passes one; every other result
+            reads the shared study-level frame.
+        """
+        # Store chart data
+        self.charts: Charts = charts
+
+        # Backing frame: the shared study-level frame, or — for a request
+        # residual (R6/RCR6) — this request's own augmented copy. Public access
+        # goes through the `dataset` property, which hands out a copy — see there.
+        self._ads = analysis_dataset_obj
+        self._dataset = request_dataset if request_dataset is not None else analysis_dataset_obj.analysis_dataset
+
+        # Store the executed analysis type (passed from Analysis)
+        self._analysis_type = analysis_type
+
+        # Design state information
+        self.observed_sds: int = analysis_dataset_obj.observed_design_state
+        self.analytical_sds: int = analysis_dataset_obj.analytical_design_state.sds
+        self.observed_sds_info: dict = analysis_dataset_obj.raw_sds_characteristics
+        self.analytical_sds_info: dict = SDSRegistry().get_sds_characteristics(self.analytical_sds)
+
+        # Extract residuals if calculated
+        self._residuals = None
+        if analysis_dataset_obj.has_vas_residuals:
+            # Stored residuals only — request residuals (R6) are by=-dependent and
+            # belong to a single execute() result, not to this study-level snapshot.
+            residual_cols = list(STORED_RESIDUALS)
+            available_cols = [c for c in residual_cols if c in self._dataset.columns]
+            if available_cols:
+                self._residuals = self._dataset[available_cols].copy()
+
+        # Extract effects and interactions
+        self._effects = analysis_dataset_obj.effects if analysis_dataset_obj.effects else None
+        self._interactions = analysis_dataset_obj.interactions if analysis_dataset_obj.interactions else None
+
+        # Build comprehensive summary
+        self._summary = self._build_summary()
+
+    @property
+    def dataset(self) -> pd.DataFrame:
+        """
+        Full analysis dataset with means and residuals.
+
+        Returns a fresh copy on every access, matching ``Study.dataset``.
+        The frame behind a plain result is shared by the study and every other
+        plain result, so handing out the live frame would let one caller mutate
+        another's data. A request-residual result (R6/RCR6) is backed by its
+        own frame carrying that request's residual columns.
+
+        Returns
+        -------
+        pd.DataFrame
+            Copy of the analysis dataset.
+        """
+        return self._dataset.copy()
+
+    def _build_summary(self) -> dict:
+        """
+        Build comprehensive summary of analysis.
+
+        Returns
+        -------
+        dict
+            Summary with SDS info, capabilities, and statistics
+        """
+        # Count total signals across all charts
+        n_signals = 0
+
+        # Handle case where charts might not be a dict
+        if not isinstance(self.charts, dict):
+            logger.warning(f"Charts is not a dict, it's a {type(self.charts)}")
+            chart_values = []
+        else:
+            chart_values = self.charts.values()
+
+        for chart_info in chart_values:
+            if 'data' in chart_info and 'beyond_limits' in chart_info['data'].columns:
+                n_signals += (chart_info['data']['beyond_limits'] != 0).sum()
+
+        summary = {
+            # SDS information
+            'observed_sds': self.observed_sds,
+            'analytical_sds': self.analytical_sds,
+            'analytical_sds_description': self.analytical_sds_info.get('description', 'Unknown'),
+            'analytical_sds_capabilities': self.analytical_sds_info.get('capabilities', []),
+            'replication_type': self.analytical_sds_info.get('replication_type', 'unknown'),
+            # Analysis configuration
+            'analysis_type': self._analysis_type,
+            'response_var': self._ads.spec.response_var,
+            'grouping_vars': self._ads.spec.rsg_vars,
+            'time_var': self._ads.spec.time_var,
+            # Data dimensions
+            'n_observations': len(self._dataset),
+            'n_charts': len(self.charts),
+            'chart_types': list(self.charts.keys()),
+            # Capabilities
+            'has_residuals': self.has_residuals,
+            'has_effects': self.has_effects,
+            'has_interactions': self.has_interactions,
+            'variance_decomposition': self.analytical_sds_info.get('variance_decomposition', False),
+            'interaction_analysis': self.analytical_sds_info.get('interaction_analysis', False),
+            # Signals
+            'n_signals_total': int(n_signals),
+            # Stratification
+            'is_stratified': self._is_stratified(),
+        }
+
+        return summary
+
+    def _is_stratified(self) -> bool:
+        """
+        Check if this is a stratified analysis (separate charts per group).
+
+        Returns
+        -------
+        bool
+            True if any chart has a non-empty 'strata' key
+        """
+        # Handle case where charts might not be a dict
+        if not isinstance(self.charts, dict):
+            return False
+
+        for chart_info in self.charts.values():
+            if isinstance(chart_info, dict) and 'strata' in chart_info and chart_info['strata']:
+                return True
+        return False
+
+    # =========================================================================
+    # Properties for easy access
+    # =========================================================================
+
+    @property
+    def residuals(self) -> pd.DataFrame:
+        """
+        Get the **stored** VAS residuals (R1-R5) if calculated.
+
+        Deliberately excludes the **request** residuals (R6, RCR6): those are a function
+        of the ``execute()`` request's ``by=``, so there is no single study-level series
+        to put in this frame. Reach them with :meth:`get_residual` on a result that asked
+        for them.
+
+        Returns
+        -------
+        DataFrame
+            DataFrame with columns [R1, R2, R3, R4, R5] if residuals were
+            calculated, empty DataFrame with same schema otherwise
+        """
+        if self._residuals is None:
+            return pd.DataFrame(columns=['R1', 'R2', 'R3', 'R4', 'R5'])
+        return self._residuals.copy()
+
+    @property
+    def effects(self) -> dict:
+        """
+        Get main effects if calculated.
+
+        Returns a dict keyed by effect type rather than a single DataFrame.
+        This is intentional: each effect type has different semantics and
+        structure, and users typically work with one effect type at a time.
+
+        Keys are named after your own factor columns, so they vary by study.
+        For ``factors=['machine', 'shift']`` the dict holds:
+
+        - ``'machine'``, ``'shift'`` — per-factor main effects, one row per
+          level, in a ``Main_Effect`` column.
+        - ``'main_effect'`` — main effects of the composite rational subgroup,
+          one row per ``rsg`` value.
+        - ``'time'`` — time main effects, one row per time point, in a
+          ``PT_ME`` column.
+        - ``'machine_MEs'``, ``'shift_MEs'`` — observation-level main-effect
+          scores (one row per observation, not per level).
+        - ``'factor_interaction_effects'`` — observation-level interaction
+          effects; present only when two or more factors were declared.
+
+        Because the keys carry your column names, a factor literally named
+        ``time`` or ``main_effect`` collides with the library's own keys.
+
+        Returns
+        -------
+        dict[str, DataFrame]
+            Main effects keyed as described above. Empty dict if not
+            calculated (no factors, or a design state without effects).
+
+        Examples
+        --------
+        >>> effects = result.effects            # doctest: +SKIP
+        >>> sorted(effects)                     # doctest: +SKIP
+        ['factor_interaction_effects', 'machine', 'machine_MEs', 'main_effect',
+         'shift', 'shift_MEs', 'time']
+        >>> effects['machine']                  # doctest: +SKIP
+        >>> effects['time']                     # doctest: +SKIP
+        """
+        return self._effects.copy() if self._effects else {}
+
+    @property
+    def interactions(self) -> dict:
+        """
+        Get interaction effects if calculated.
+
+        Returns a dict keyed by interaction type rather than a single DataFrame.
+        This is intentional: interaction structures vary by SDS, and the dict
+        keys provide meaningful organization for different interaction terms.
+
+        Returns
+        -------
+        dict[str, DataFrame | Series]
+            Dictionary with interaction terms (structure varies by SDS).
+            Empty dict if not calculated.
+
+        Examples
+        --------
+        >>> interactions = result.interactions
+        >>> for name, data in interactions.items():
+        ...     print(f"{name}: {data.shape}")
+        """
+        return self._interactions.copy() if self._interactions else {}
+
+    @property
+    def summary(self) -> dict:
+        """
+        Get comprehensive summary of analysis.
+
+        Returns
+        -------
+        dict
+            Summary with SDS info, capabilities, dimensions, and statistics
+        """
+        return self._summary.copy()
+
+    @property
+    def has_residuals(self) -> bool:
+        """Check if VAS residuals were calculated."""
+        return self._residuals is not None
+
+    @property
+    def has_effects(self) -> bool:
+        """Check if main effects were calculated."""
+        return self._effects is not None and len(self._effects) > 0
+
+    @property
+    def has_interactions(self) -> bool:
+        """Check if interaction effects were calculated."""
+        return self._interactions is not None and len(self._interactions) > 0
+
+    @property
+    def all_charts(self) -> list[str]:
+        """Get list of all available chart names."""
+        return list(self.charts.keys())
+
+    @property
+    def strata(self) -> list[str]:
+        """
+        Get list of available subgroups focusable across every chart.
+
+        For stratified analysis, returns the order-preserving intersection
+        of every chart's strata list. A stratum present in one chart but
+        missing data in another (e.g. an X+mR pair where mR dropped a
+        single-observation cell) is excluded so that the returned values
+        are valid inputs to ``focus()`` for the full result.
+
+        Returns
+        -------
+        list[str]
+            List of stratum names focusable across all charts. Empty list
+            if no chart is stratified.
+
+        Examples
+        --------
+        >>> result = study.execute(chart='X', by=['factor 1'])
+        >>> result.strata
+        ['level_1', 'level_2', ...]
+
+        >>> if result.strata:
+        ...     for stratum in result.strata:
+        ...         focused = result.focus(stratum)
+        ...         focused.plot()
+        """
+        strata_lists = [
+            list(chart_info['strata'])
+            for chart_info in self.charts.values()
+            if 'strata' in chart_info and chart_info['strata']
+        ]
+        if not strata_lists:
+            return []
+        if len(strata_lists) == 1:
+            return strata_lists[0]
+        common = set(strata_lists[0])
+        for sl in strata_lists[1:]:
+            common &= set(sl)
+        return [s for s in strata_lists[0] if s in common]
+
+    @property
+    def is_stratified(self) -> bool:
+        """
+        Check if this result contains stratified charts.
+
+        Returns
+        -------
+        bool
+            True if charts have multiple strata, False otherwise.
+        """
+        return len(self.strata) > 0
+
+    def focus(self, stratum: str) -> AnalysisResult:
+        """
+        Return new AnalysisResult focused on a single stratum.
+
+        For stratified X/mR analysis, this allows drilling down to
+        a specific subgroup. The returned result is immutable - the
+        original result is unchanged.
+
+        Parameters
+        ----------
+        stratum : str
+            Name of the stratum to focus on (from result.strata)
+
+        Returns
+        -------
+        AnalysisResult
+            New AnalysisResult containing only data for the specified stratum
+
+        Raises
+        ------
+        ValidationError
+            If stratum is not in result.strata or focus produces empty data.
+        ProcessBehaviorError
+            If required stratification metadata/columns are inconsistent.
+
+        Examples
+        --------
+        >>> result = study.execute(chart='X', by=['factor 1'])
+        >>> result.strata
+        ['level_1', 'level_2', ...]
+        >>> focused = result.focus('level_1')
+        >>> focused.plot()
+
+        >>> # Chaining works
+        >>> result.focus('level_1').plot()
+        """
+        from .focused_result import focus_on
+
+        return focus_on(self, stratum)
+
+    # =========================================================================
+    # Convenience methods for accessing data
+    # =========================================================================
+
+    def _resolve_chart_name(self, name: str) -> str:
+        """Resolve chart name with case-insensitive fallback for base charts."""
+        if name in self.charts:
+            return name
+        normalized = normalize_chart_name(name)
+        if normalized in self.charts:
+            return normalized
+        return name  # Return as-is; caller raises the appropriate error
+
+    def get_chart(self, name: str) -> pd.DataFrame:
+        """
+        Get chart data by name.
+
+        Parameters
+        ----------
+        name : str
+            Chart name (e.g., 'Xbar', 'S', 'GroupA', 'all')
+
+        Returns
+        -------
+        DataFrame
+            Chart data
+
+        Raises
+        ------
+        ChartNotAvailableError
+            If chart name not found in this result.
+
+        Examples
+        --------
+        >>> xbar = result.get_chart('Xbar')
+        >>> alice = result.get_chart('Alice')  # For stratified X
+        """
+        name = self._resolve_chart_name(name)
+        if name not in self.charts:
+            raise ChartNotAvailableError(
+                f"Chart '{name}' not found. Available charts: {self.all_charts}", chart=name, available=self.all_charts
+            )
+        return self.charts[name]['data'].copy()
+
+    def get_statistics(self, name: str) -> dict:
+        """
+        Get chart statistics by name.
+
+        Parameters
+        ----------
+        name : str
+            Chart name (e.g., 'Xbar', 'S', 'GroupA')
+
+        Returns
+        -------
+        dict
+            Statistics dictionary. Every chart guarantees the same four
+            unified keys: ``{'N', 'center', 'lpl', 'upl'}``.
+
+            ``N`` is the subgroup size behind one plotted point. On Xbar/S
+            that is the cell size; on an X chart it is ``1`` (one
+            observation per point); on an mR chart it is ``2`` (the moving
+            window the range is taken over).
+
+            When the control limits or subgroup size vary across
+            subgroups (e.g. Xbar/S with ``n_mode='actual'`` on unbalanced
+            data, phased charts, or any chart whose limits aren't a
+            single scalar), ``N``, ``lpl``, and ``upl`` are ``None`` and
+            an optional ``'limits_vary': True`` flag is added so callers
+            can detect variable limits without a type check.
+
+            The Histogram chart also includes ``{'mean', 'std', 'n'}``
+            as additional fields (``mean`` is an alias for ``center``;
+            ``std`` is the sample standard deviation; ``n`` is an alias
+            for ``N``); its ``'lpl'`` and ``'upl'`` are ``None`` because
+            a histogram has no control limits.
+
+        Raises
+        ------
+        ChartNotAvailableError
+            If chart name not found in this result.
+
+        Examples
+        --------
+        >>> stats = result.get_statistics('Xbar')
+        >>> print(f"Center: {stats['center']}, UPL: {stats['upl']}")
+        """
+        name = self._resolve_chart_name(name)
+        if name not in self.charts:
+            raise ChartNotAvailableError(
+                f"Chart '{name}' not found. Available charts: {self.all_charts}", chart=name, available=self.all_charts
+            )
+        return self.charts[name]['statistics'].copy()
+
+    def statistics(self, chart: str, stratum: str | None = None) -> dict:
+        """Chart statistics with a shape that does not depend on the data.
+
+        :meth:`get_statistics` returns ``{'N', 'center', 'lpl', 'upl'}`` for an unstratified
+        result but ``{stratum: {...}}`` for a stratified one — so ``stats['center']`` works
+        on one dataset and raises ``KeyError`` on the next, depending on whether the chart
+        happened to stratify. This method always returns the four-key dict, and asks for a
+        stratum when the answer would otherwise be ambiguous.
+
+        Parameters
+        ----------
+        chart : str
+            Chart name, e.g. ``'Xbar'``.
+        stratum : str, optional
+            Required when the result is stratified; rejected when it is not, so a call that
+            names a stratum can never silently return whole-result numbers.
+
+        Returns
+        -------
+        dict
+            Always ``{'N', 'center', 'lpl', 'upl'}`` (plus any chart-specific extras). See
+            :meth:`get_statistics` for what ``None`` values mean when limits vary.
+
+        Raises
+        ------
+        ValidationError
+            If a stratum is needed and not given, given and not needed, or unknown.
+
+        Examples
+        --------
+        >>> result.statistics('Xbar')['center']
+        >>> result.statistics('X', stratum='Machine1')['upl']
+        """
+        stats = self.get_statistics(chart)
+
+        if not self.is_stratified:
+            if stratum is not None:
+                raise ValidationError(
+                    f"This result is not stratified, so stratum={stratum!r} does not apply.\n"
+                    f'Use result.statistics({chart!r}) with no stratum.'
+                )
+            return stats
+
+        available = self.strata
+        if stratum is None:
+            raise ValidationError(
+                f'This result is stratified, so a stratum is required to return one set of '
+                f'statistics.\n'
+                f'Available strata: {available}\n'
+                f"Use result.statistics({chart!r}, stratum={available[0]!r}) "
+                f'— or result.get_statistics({chart!r}) for every stratum at once.'
+            )
+        if stratum not in stats:
+            raise ValidationError(
+                f"Stratum {stratum!r} not found in chart {chart!r}.\nAvailable strata: {available}"
+            )
+        return dict(stats[stratum])
+
+    def get_residual(self, residual_type: str) -> pd.Series:
+        """
+        Get a specific residual series.
+
+        Finds **stored** residuals (R1-R5, RCR1-RCR5) on the study-level snapshot and
+        **request** residuals (R6, RCR6) on this result's dataset — see
+        :meth:`_locate_residual` for why they live in different places.
+
+        Parameters
+        ----------
+        residual_type : str
+            Residual code, e.g. 'R2', 'R6', or a recentered form such as 'RCR5'.
+
+        Returns
+        -------
+        Series
+            The residual values.
+
+        Raises
+        ------
+        ValidationError
+            If this result carries no residuals, or the code is not present here.
+            Previously this returned an empty Series, which let callers compute on
+            nothing; the message now says which case applies and what to do.
+
+        Examples
+        --------
+        >>> r2 = result.get_residual('R2')
+        >>> r6 = study.execute(chart='Xbar', value='R6', by=['machine']).get_residual('R6')
+        """
+        return self._locate_residual(residual_type)
+
+    def _locate_residual(self, residual_type: str) -> pd.Series:
+        """Return a residual series from wherever it legitimately lives, or raise.
+
+        The VAS residuals come in two kinds, and they are not stored in the same place:
+
+        - **stored** (R1-R5, RCR1-RCR5) — computed during ``formulate()`` and held on the
+          study-level snapshot. Independent of the request: R5 is the same series whatever
+          ``by=`` was passed.
+        - **request** (R6, RCR6) — computed during ``execute()`` onto that request's own
+          frame, from that request's ``by=``. There is no canonical study-level R6, which
+          is why ``result.residuals`` deliberately excludes it.
+
+        Looking in only one of those two places is what made ``get_residual('R6')`` report
+        "not found" about 4,000 values the same object was holding. This is the single
+        lookup; ``get_residual`` and ``plot_residuals`` both go through it so they cannot
+        diverge again.
+        """
+        if not self.has_residuals:
+            raise ValidationError(
+                f"No residuals available for this result, so '{residual_type}' cannot be "
+                f'returned.\nResiduals require a factorial design (ADS 1-3) with factors '
+                f'and time in the formulation.'
+            )
+
+        base = residual_type.upper()
+        base = base[2:] if base.startswith('RCR') else base
+
+        # Stored residuals: the study-level snapshot (R1-R5).
+        if self._residuals is not None and residual_type in self._residuals.columns:
+            return self._residuals[residual_type].copy()
+
+        # Request residuals: only from a result that actually asked for them. The shared
+        # study-level frame never carries R6/RCR6 — a result's own frame carries them iff
+        # that request computed them — so column presence here is the correct test.
+        if base in REQUEST_RESIDUALS:
+            if residual_type in self._dataset.columns:
+                return self._dataset[residual_type].copy()
+            raise ValidationError(
+                f"'{residual_type}' is computed per request and depends on by=, so it "
+                f'exists only on a result that asked for it.\n'
+                f'This result was not executed with it.\n'
+                f"Use study.execute(chart=..., value='{base}', by=[factor])."
+            )
+
+        # Stored recentered forms (RCR1-RCR5) live on the dataset, not the snapshot.
+        if residual_type in self._dataset.columns:
+            return self._dataset[residual_type].copy()
+
+        if base in ALL_RESIDUALS:
+            available = list(self._residuals.columns) if self._residuals is not None else []
+            raise ValidationError(
+                f"Residual '{residual_type}' is not present in this result.\n"
+                f'Available here: {available or "none"}'
+            )
+
+        raise ValidationError(
+            f"'{residual_type}' is not a recognized residual.\n"
+            f'Valid codes: {", ".join(ALL_RESIDUALS)} '
+            f"(prefix with 'RC' for the recentered form, e.g. 'RCR5')."
+        )
+
+    def list_strata(self) -> list[str]:
+        """
+        List all strata in stratified analysis.
+
+        Equivalent to accessing the ``strata`` property. Values returned
+        here are valid inputs to ``focus()``.
+
+        Returns
+        -------
+        list
+            List of stratum identifiers
+
+        Examples
+        --------
+        >>> strata = result.list_strata()
+        >>> for s in strata:
+        ...     focused = result.focus(s)
+        """
+        return self.strata
+
+    def iter_charts(self):
+        """
+        Iterate over all charts.
+
+        Yields
+        ------
+        tuple of (name, data, statistics)
+
+        Examples
+        --------
+        >>> for name, data, stats in result.iter_charts():
+        ...     print(f"{name}: {len(data)} points, mean={stats.get('mean')}")
+        """
+        for name, chart_info in self.charts.items():
+            yield name, chart_info['data'], chart_info['statistics']
+
+    def chart_table(
+        self, chart: str | None = None, include_signal_col: bool = True, signal_symbols: bool = True
+    ) -> pd.DataFrame:
+        """
+        Get a summary table of chart data with subgroup sizes.
+
+        Returns a clean DataFrame suitable for display in notebooks,
+        including the subgroup size (n) which affects control limit
+        calculations when n varies across subgroups.
+
+        Parameters
+        ----------
+        chart : str, optional
+            Chart name (e.g., 'Xbar', 'S'). If None, uses first chart.
+        include_signal_col : bool, default True
+            Whether to include a signal indicator column
+        signal_symbols : bool, default True
+            If True, use symbols (↑/↓) for signals; if False, use -1/0/1
+
+        Returns
+        -------
+        pd.DataFrame
+            Summary table with columns:
+            - subgroup: Subgroup identifier (RSG) — when chart_data has rsg
+            - n: Number of observations in subgroup
+            - value: The statistic value (xbar, s, etc.)
+            - center: Center line value
+            - lpl: Lower process limit
+            - upl: Upper process limit
+            - signal: Signal indicator (if include_signal_col=True)
+
+        Examples
+        --------
+        Display subgroup summary in notebook:
+
+        >>> result = study.execute()
+        >>> result.chart_table('S')
+          subgroup   n  value  center    lpl    upl signal
+        0      1_1  99  1.241   1.289  1.012  1.565
+        1      1_2  98  0.977   1.289  1.011  1.567      ↓
+        2      2_1 100  0.902   1.289  1.014  1.564      ↓
+        ...
+
+        Get table for Xbar chart:
+
+        >>> result.chart_table('Xbar')
+
+        Use numeric signal values:
+
+        >>> result.chart_table('S', signal_symbols=False)
+        """
+        from .result_tabular import build_chart_table
+
+        return build_chart_table(
+            self,
+            chart=chart,
+            include_signal_col=include_signal_col,
+            signal_symbols=signal_symbols,
+        )
+
+    def get_signals(self, chart_name: str | None = None) -> pd.DataFrame:
+        """
+        Get points beyond control limits.
+
+        Parameters
+        ----------
+        chart_name : str, optional
+            Chart name to check. If None, checks all charts.
+
+        Returns
+        -------
+        DataFrame
+            Rows where beyond_limits != 0
+
+        Examples
+        --------
+        >>> signals = result.get_signals('Xbar')
+        >>> all_signals = result.get_signals()  # All charts
+        """
+        from .result_tabular import build_signals_table
+
+        return build_signals_table(self, chart=chart_name)
+
+    # =========================================================================
+    # String representation
+    # =========================================================================
+
+    def __repr__(self) -> str:
+        """String representation."""
+        charts_str = ', '.join(self.all_charts)
+        return (
+            f'AnalysisResult(\n'
+            f'  analytical_sds={self.analytical_sds} ({self.analytical_sds_info["description"]}),\n'
+            f'  charts=[{charts_str}],\n'
+            f'  n_obs={len(self._dataset)},\n'
+            f'  has_residuals={self.has_residuals},\n'
+            f'  has_effects={self.has_effects},\n'
+            f'  n_signals={self.summary["n_signals_total"]}\n'
+            f')'
+        )
+
+    def __str__(self) -> str:
+        """User-friendly string representation."""
+        lines = [
+            '=' * 70,
+            'ANALYSIS RESULT SUMMARY',
+            '=' * 70,
+            f'\nAnalytical Design State (ADS): {self.analytical_sds}',
+            f'Description: {self.analytical_sds_info["description"]}',
+            f'\nAnalysis Type: {self.summary["analysis_type"]}',
+            f'Response Variable: {self.summary["response_var"]}',
+        ]
+
+        if self.summary['grouping_vars']:
+            lines.append(f'Grouping: {", ".join(self.summary["grouping_vars"])}')
+
+        if self.summary['time_var']:
+            lines.append(f'Time Variable: {self.summary["time_var"]}')
+
+        lines.extend(
+            [
+                f'\nObservations: {self.summary["n_observations"]}',
+                f'Charts: {", ".join(self.all_charts)}',
+            ]
+        )
+
+        if self.summary['is_stratified']:
+            lines.append(f'Stratified: Yes ({len(self.charts)} groups)')
+
+        lines.append('\nCapabilities:')
+        lines.append(f'  Residuals: {"✓" if self.has_residuals else "✗"}')
+        lines.append(f'  Effects: {"✓" if self.has_effects else "✗"}')
+        lines.append(f'  Interactions: {"✓" if self.has_interactions else "✗"}')
+
+        if self.summary['n_signals_total'] > 0:
+            lines.append(f'\n⚠️  Signals: {self.summary["n_signals_total"]} points beyond limits')
+
+        lines.append('=' * 70)
+
+        return '\n'.join(lines)
+
+    # =========================================================================
+    # Excel Export
+    # =========================================================================
+
+    def to_excel(self, filepath: str, **kwargs) -> list[Path]:
+        """
+        Export analysis results to Excel with each component on a separate tab.
+
+        Creates a multi-sheet Excel workbook with organized analysis results.
+        See ExcelExporter for full documentation and options.
+
+        Parameters
+        ----------
+        filepath : str
+            Output Excel file path (e.g., 'analysis.xlsx')
+        **kwargs
+            Additional options passed to ExcelExporter.export():
+            - include_summary : bool, default=True
+            - include_charts : bool, default=True
+            - include_residuals : bool, default=True
+            - include_effects : bool, default=True
+            - include_interactions : bool, default=True
+            - include_full_dataset : bool, default=False
+            - format_cells : bool, default=True
+            - include_chart_images : bool, default=True
+            - export_html : bool, default=False
+
+        Returns
+        -------
+        list[Path]
+            Every file written. With ``export_html=True`` that includes the
+            companion HTML documents, so nothing lands on disk unannounced.
+
+        Examples
+        --------
+        >>> result.to_excel('analysis.xlsx')
+        [PosixPath('analysis.xlsx')]
+        >>> result.to_excel('full.xlsx', include_full_dataset=True)  # doctest: +SKIP
+        """
+        from .exporters import ExcelExporter
+
+        return ExcelExporter(self).export(filepath, **kwargs)
+
+    def detect_signals(
+        self, chart: str | None = None, rules: str | list[str] | None = None, config: Any | None = None, **kwargs
+    ) -> SignalResult | dict[str, SignalResult]:
+        """
+        Detect Western Electric rule violations in control charts.
+
+        This method applies configurable pattern detection rules to identify
+        non-random patterns in control chart data.
+
+        Parameters
+        ----------
+        chart : str, optional
+            Specific chart to analyze. If None, analyzes all charts.
+        rules : str, list, or RuleSet, optional
+            Rules to apply:
+            - 'standard': Rules 1-4 (default)
+            - 'extended': Rules 1-8
+            - 'all': All available rules
+            - List of rule names: ['rule_1', 'rule_2', ...]
+            - RuleSet: Fluent API configuration
+        config : SignalConfig, optional
+            Advanced configuration object
+        **kwargs
+            Additional parameters passed to SignalConfig
+
+        Returns
+        -------
+        SignalResult or dict of SignalResult
+            If chart specified: single SignalResult
+            If no chart: dict mapping chart names to SignalResults
+
+        Examples
+        --------
+        Simple usage (standard rules):
+
+        >>> signals = result.detect_signals()
+        >>> print(signals.summary)
+
+        Specific chart and rules:
+
+        >>> signals = result.detect_signals(
+        ...     chart='Xbar',
+        ...     rules=['rule_1', 'rule_2', 'rule_5']
+        ... )
+
+        Using fluent API:
+
+        >>> from processbehavior.signals import RuleSet
+        >>> signals = result.detect_signals(
+        ...     rules=RuleSet()
+        ...         .beyond_limits()
+        ...         .zone_a(consecutive=2, window=3)
+        ...         .trend(length=6)
+        ... )
+
+        Full configuration:
+
+        >>> from processbehavior.signals import SignalConfig
+        >>> config = SignalConfig(
+        ...     enabled_rules=['rule_1', 'rule_2'],
+        ...     min_observations=30,
+        ...     ignore_first_n=5
+        ... )
+        >>> signals = result.detect_signals(config=config)
+
+        Access violations:
+
+        >>> signals.by_rule['rule_2']  # Rule 2 violations
+        >>> signals.flagged_observations  # Set of obs_ids
+        >>> signals.to_excel('violations.xlsx')
+        """
+        from .result_signals import detect_signals_for_result
+
+        return detect_signals_for_result(
+            self, chart=chart, rules=rules, config=config, **kwargs
+        )
+
+    def _extract_chart_type(self, chart_name: str) -> str:
+        """Base chart type from a chart name. Delegate for backward compat."""
+        from .result_signals import extract_chart_type
+
+        return extract_chart_type(chart_name)
+
+    def plot(
+        self,
+        chart: str | None = None,
+        facet: bool = False,
+        ncols: int = 2,
+        highlight_signals: bool = True,
+        show_limits: bool = True,
+        show_limit_values: bool = True,
+        show_zones: bool = False,
+        show_rules: bool = False,
+        show_stats: bool = False,
+        theme: ThemeName | str = 'processbehavior',
+        width: int = 1000,
+        height: int | None = None,
+        aspect_ratio: float | None = None,
+        title: str | None = None,
+        xaxis_title: str | None = None,
+        yaxis_title: str | None = None,
+        shared_yaxis: bool = True,
+        yaxis_padding: float = 0.05,
+        vertical_spacing: float = 0.15,
+    ) -> ControlChartFigure:
+        """Create interactive control chart visualisation.
+
+        Parameters
+        ----------
+        chart : str, optional
+            Specific chart to plot ('Xbar', 'S', 'X', etc.).
+            Also accepts 'Effects', 'MainEffects', 'TimeEffects',
+            'TimeInteraction', 'FactorInteraction'.
+            If None, plots all available charts.
+        facet : bool, default False
+            Whether to create faceted plot for stratified data.
+        ncols : int, default 2
+            Number of columns in faceted layout.
+        highlight_signals : bool, default True
+            Highlight points beyond control limits.
+        show_limits : bool, default True
+            Show control limit lines.
+        show_limit_values : bool, default True
+            Show numeric values in limit labels.
+        show_zones : bool, default False
+            Show zone shading (A/B/C zones at 1-2-3 sigma).
+        show_rules : bool, default False
+            Show additional run rules (WECO Rules 2-8).
+        show_stats : bool, default False
+            Show statistics box with CL, UPL, LPL values.
+        theme : str, default 'processbehavior'
+            Visual theme ('processbehavior', 'minimal', 'dark', 'ggplot',
+            'publication') or a ChartTheme instance.
+        width : int, default 1000
+            Figure width in pixels.
+        height : int, optional
+            Figure height in pixels (auto-calculated if None).
+        aspect_ratio : float, optional
+            Width-to-height ratio (overrides height if specified).
+        title : str, optional
+            Custom title for the figure.
+        xaxis_title, yaxis_title : str, optional
+            Custom axis labels.
+        shared_yaxis : bool, default True
+            Whether faceted charts share y-axis range.
+        yaxis_padding : float, default 0.05
+            Padding fraction for y-axis range.
+        vertical_spacing : float, default 0.15
+            Vertical spacing between rows in faceted layouts.
+
+        Returns
+        -------
+        ControlChartFigure
+            Interactive figure object with .show(), .save_html(), .save_image()
+
+        Examples
+        --------
+        >>> fig = result.plot()
+        >>> fig = result.plot(chart='Xbar', show_zones=True, show_stats=True)
+        >>> fig = result.plot(facet=True, ncols=3)
+        """
+        from .plotting import Plotter
+
+        if chart:
+            chart = self._resolve_chart_name(chart)
+
+        plotter = Plotter(self)
+        return plotter.plot(
+            chart=chart,
+            facet=facet,
+            ncols=ncols,
+            highlight_signals=highlight_signals,
+            show_limits=show_limits,
+            show_limit_values=show_limit_values,
+            show_zones=show_zones,
+            show_rules=show_rules,
+            show_stats=show_stats,
+            theme=theme,
+            width=width,
+            height=height,
+            aspect_ratio=aspect_ratio,
+            title=title,
+            xaxis_title=xaxis_title,
+            yaxis_title=yaxis_title,
+            shared_yaxis=shared_yaxis,
+            yaxis_padding=yaxis_padding,
+            vertical_spacing=vertical_spacing,
+        )
+
+    def plot_residuals(
+        self,
+        residual_type: str = 'R1',
+        plot_type: str = 'all',
+        theme: ThemeName | str = 'processbehavior',
+        width: int = 1200,
+        height: int = 400,
+    ) -> ControlChartFigure:
+        """Create residual diagnostic plots.
+
+        Parameters
+        ----------
+        residual_type : str, default 'R1'
+            Which residual. Stored codes ('R1'-'R5') or a request code ('R6') on a
+            result that was executed with it.
+        plot_type : str, default 'all'
+            'histogram', 'qq', 'sequence', or 'all'.
+        theme : str, default 'processbehavior'
+            Visual theme.
+        width, height : int
+            Figure dimensions.
+
+        Returns
+        -------
+        ControlChartFigure
+        """
+        from .plotting.residuals import plot_residuals as _plot_residuals
+
+        return _plot_residuals(
+            self,
+            residual_type=residual_type,
+            plot_type=plot_type,
+            theme=theme,
+            width=width,
+            height=height,
+        )
+
+    def plot_effects(
+        self,
+        effect_type: str = 'factor',
+        theme: ThemeName | str = 'processbehavior',
+        width: int = 800,
+        height: int = 500,
+    ) -> ControlChartFigure:
+        """Create bar chart of main effects.
+
+        Parameters
+        ----------
+        effect_type : str, default 'factor'
+            'factor', 'time', or 'all'.
+        theme : str, default 'processbehavior'
+            Visual theme.
+        width, height : int
+            Figure dimensions.
+
+        Returns
+        -------
+        ControlChartFigure
+        """
+        from .plotting import Plotter
+
+        plotter = Plotter(self)
+        return plotter.plot_effects(
+            effect_type=effect_type,
+            theme=theme,
+            width=width,
+            height=height,
+        )
+
+    def report(
+        self,
+        filepath: str,
+        include_charts: bool = True,
+        include_residuals: bool = True,
+        include_effects: bool = True,
+        include_summary: bool = True,
+        theme: ThemeName | str = 'processbehavior',
+        width: int = 1200,
+        title: str | None = None,
+    ) -> None:
+        """Generate comprehensive HTML report.
+
+        Parameters
+        ----------
+        filepath : str
+            Output HTML file path.
+        include_charts, include_residuals, include_effects, include_summary : bool
+            Sections to include.
+        theme : str, default 'processbehavior'
+            Visual theme.
+        width : int, default 1200
+            Chart width in pixels.
+        title : str, optional
+            Report title.
+        """
+        from .plotting.report import generate_report
+
+        generate_report(
+            self,
+            filepath=filepath,
+            include_charts=include_charts,
+            include_residuals=include_residuals,
+            include_effects=include_effects,
+            include_summary=include_summary,
+            theme=theme,
+            width=width,
+            title=title,
+        )
+
+
+
+# Re-export FocusedAnalysisResult for backward compat - the class lives
+# in focused_result.py now, but old imports of the form
+# `from processbehavior.analysis_result import FocusedAnalysisResult` and
+# any pickled instances continue to resolve through this module path.
+from .focused_result import FocusedAnalysisResult  # noqa: E402, F401