pyqicharts 2.0.0__py3-none-any.whl

pyqicharts/__init__.py

@@ -0,0 +1,51 @@
+"""pyqicharts: Quality Improvement and SPC charts for Python.
+
+The package root re-exports the supported public API. Internal helper functions
+remain inside their modules so future releases can evolve implementation
+details without forcing users to change imports.
+"""
+from .core import QicResult, qic
+from .advanced import autocorrelation_diagnostics, funnel_table, interactive_signal_review, overdispersion_test, rare_event_limits, risk_adjusted_summary, seasonality_diagnostics
+from .chart_selector import ChartSuggestion, suggest_chart
+from .datasets import days_between_falls_with_harm, days_between_serious_incidents, get_sample_data_path, infections_between_events, risk_adjusted_infection_rates, risk_adjusted_readmissions, sample_healthcare_qi_data, sample_subgroup_measurements
+from .education import chart_selection_tutorial, interpretation_mistakes, simulate_process, teaching_dataset
+from .export import create_report_bundle, export_excel, export_png, export_powerpoint
+from .interactive import qic_altair, qic_plotly, qic_widget
+from .localization import TERMINOLOGY, get_terminology, localize_interpretation
+from .nelson import nelson_rule_signals, shewhart_rule_signals
+from .xmr_rules import XmrRuleConfig, xmr_signals
+from .pareto import ParetoResult, pareto_chart, paretochart
+from .powerbi import (
+    intervention_metadata_table,
+    kpi_table,
+    improvement_output_table,
+    improvement_warning_table,
+    interpretation_table,
+    phase_metadata_table,
+    powerbi_table,
+    signal_table,
+    special_cause_summary_table,
+    spc_summary_table,
+    target_metadata_table,
+)
+from .presets import PRESETS, get_preset, list_presets
+from .reporting import create_qi_report_pack, create_report_pack_from_config, load_chart_config, run_chart_batch
+from .rules import AnhoejResult, anhoej_rules
+from .signals import SIGNAL_SCHEMA_VERSION, Signal, signals_to_frame
+from .tables import CHART_ALIASES, VALID_CHARTS, qic_table, pareto_table
+from .themes import Theme, get_theme, list_themes
+from .validation import compare_to_expected, read_validation_csv, validation_manifest, validation_summary
+
+__all__ = [
+    "AnhoejResult", "CHART_ALIASES", "ChartSuggestion", "XmrRuleConfig", "PRESETS", "ParetoResult", "QicResult", "TERMINOLOGY", "Theme", "VALID_CHARTS",
+    "anhoej_rules", "autocorrelation_diagnostics", "chart_selection_tutorial", "compare_to_expected", "create_report_bundle", "days_between_falls_with_harm",
+    "create_qi_report_pack", "create_report_pack_from_config",
+    "days_between_serious_incidents", "export_excel", "export_png",
+    "export_powerpoint", "funnel_table", "get_preset", "get_sample_data_path", "get_terminology", "get_theme", "interactive_signal_review", "interpretation_mistakes", "intervention_metadata_table", "kpi_table", "list_presets", "list_themes", "load_chart_config", "localize_interpretation", "nelson_rule_signals", "interpretation_table", "improvement_output_table", "improvement_warning_table", "overdispersion_test", "pareto_table",
+    "pareto_chart", "paretochart", "powerbi_table", "qic", "qic_table", "infections_between_events", "rare_event_limits", "risk_adjusted_summary", "run_chart_batch", "seasonality_diagnostics", "simulate_process", "teaching_dataset", "validation_manifest", "validation_summary", "xmr_signals",
+    "risk_adjusted_infection_rates", "risk_adjusted_readmissions",
+    "sample_healthcare_qi_data", "sample_subgroup_measurements", "shewhart_rule_signals",
+    "phase_metadata_table", "read_validation_csv", "signal_table", "signals_to_frame", "special_cause_summary_table", "spc_summary_table",
+    "qic_altair", "qic_plotly", "qic_widget", "suggest_chart", "target_metadata_table", "SIGNAL_SCHEMA_VERSION", "Signal",
+]
+__version__ = "2.0.0"

pyqicharts/advanced.py

@@ -0,0 +1,150 @@
+"""Advanced exploratory helpers for SPC review workflows.
+
+These functions are deliberately table-first. They help analysts inspect
+autocorrelation, seasonality, overdispersion, risk adjustment and funnel-style
+variation without changing the core ``qic()`` chart API.
+"""
+from __future__ import annotations
+
+import math
+
+import numpy as np
+import pandas as pd
+
+
+def autocorrelation_diagnostics(values, lag: int = 1) -> pd.DataFrame:
+    """Return a simple lag autocorrelation diagnostic table."""
+
+    series = pd.Series(values, dtype="float64").dropna().reset_index(drop=True)
+    if lag < 1:
+        raise ValueError("lag must be at least 1.")
+    if len(series) <= lag:
+        raise ValueError("At least lag + 1 numeric observations are required for autocorrelation diagnostics.")
+    autocorrelation = float(series.autocorr(lag=lag))
+    return pd.DataFrame({"lag": [lag], "observations": [len(series)], "autocorrelation": [autocorrelation]})
+
+
+def seasonality_diagnostics(data: pd.DataFrame, x: str, y: str, period: int) -> pd.DataFrame:
+    """Estimate average seasonal indices for a repeated period."""
+
+    if period < 2:
+        raise ValueError("period must be 2 or greater.")
+    if x not in data.columns or y not in data.columns:
+        raise ValueError("seasonality_diagnostics requires existing x and y columns.")
+    frame = data[[x, y]].copy()
+    frame[y] = pd.to_numeric(frame[y], errors="coerce")
+    frame = frame.dropna(subset=[y]).reset_index(drop=True)
+    if frame.empty:
+        raise ValueError("No numeric values are available for seasonality diagnostics.")
+    overall = frame[y].mean()
+    frame["season_position"] = frame.index % period
+    out = frame.groupby("season_position", as_index=False)[y].mean()
+    out["seasonal_index"] = out[y] / overall if overall else np.nan
+    return out.rename(columns={y: "seasonal_mean"})
+
+
+def overdispersion_test(data: pd.DataFrame, y: str, denominator: str | None = None) -> pd.DataFrame:
+    """Return a lightweight dispersion diagnostic for count or rate data."""
+
+    if y not in data.columns:
+        raise ValueError(f"Column {y!r} was not found for overdispersion testing.")
+    values = pd.to_numeric(data[y], errors="coerce")
+    if denominator:
+        if denominator not in data.columns:
+            raise ValueError(f"Denominator column {denominator!r} was not found.")
+        denom = pd.to_numeric(data[denominator], errors="coerce")
+        values = values / denom.replace(0, np.nan)
+    values = values.dropna()
+    if len(values) < 2:
+        raise ValueError("At least two numeric observations are required for overdispersion testing.")
+    mean = float(values.mean())
+    variance = float(values.var(ddof=1))
+    ratio = variance / mean if mean else np.nan
+    return pd.DataFrame({"observations": [len(values)], "mean": [mean], "variance": [variance], "dispersion_ratio": [ratio]})
+
+
+def funnel_table(data: pd.DataFrame, numerator: str, denominator: str, group: str | None = None, z: float = 3.0) -> pd.DataFrame:
+    """Create a reference-style funnel table for proportions."""
+
+    for column in [numerator, denominator] + ([group] if group else []):
+        if column not in data.columns:
+            raise ValueError(f"Column {column!r} was not found for funnel table generation.")
+    frame = data.copy()
+    frame[numerator] = pd.to_numeric(frame[numerator], errors="coerce")
+    frame[denominator] = pd.to_numeric(frame[denominator], errors="coerce")
+    frame = frame.dropna(subset=[numerator, denominator])
+    frame = frame[frame[denominator] > 0]
+    if frame.empty:
+        raise ValueError("No rows remain after requiring numeric numerator values and positive denominators.")
+    if group:
+        frame = frame.groupby(group, as_index=False)[[numerator, denominator]].sum()
+    centre = frame[numerator].sum() / frame[denominator].sum()
+    se = np.sqrt(centre * (1 - centre) / frame[denominator])
+    out = frame.copy()
+    out["rate"] = out[numerator] / out[denominator]
+    out["centre"] = centre
+    out["lcl"] = (centre - z * se).clip(lower=0)
+    out["ucl"] = (centre + z * se).clip(upper=1)
+    out["outside_limits"] = (out["rate"] < out["lcl"]) | (out["rate"] > out["ucl"])
+    return out.reset_index(drop=True)
+
+
+def rare_event_limits(values, method: str = "geometric") -> pd.DataFrame:
+    """Return rare-event centre and approximate limits for G/T style intervals."""
+
+    series = pd.Series(values, dtype="float64").dropna()
+    if (series < 0).any():
+        raise ValueError("Rare-event intervals must be non-negative.")
+    if series.empty:
+        raise ValueError("At least one interval is required for rare-event limits.")
+    centre = float(series.mean())
+    if method not in {"geometric", "exponential"}:
+        raise ValueError("method must be 'geometric' or 'exponential'.")
+    lcl = 0.0
+    ucl = centre * 3.0 if method == "geometric" else centre * math.log(1 / 0.00135)
+    return pd.DataFrame({"method": [method], "centre": [centre], "lcl": [lcl], "ucl": [ucl]})
+
+
+def risk_adjusted_summary(data: pd.DataFrame, observed: str, expected: str, denominator: str | None = None) -> pd.DataFrame:
+    """Summarise observed, expected and observed/expected values."""
+
+    for column in [observed, expected] + ([denominator] if denominator else []):
+        if column not in data.columns:
+            raise ValueError(f"Column {column!r} was not found for risk-adjusted summary.")
+    frame = data.copy()
+    frame[observed] = pd.to_numeric(frame[observed], errors="coerce")
+    frame[expected] = pd.to_numeric(frame[expected], errors="coerce")
+    frame = frame.dropna(subset=[observed, expected])
+    if frame.empty:
+        raise ValueError("No rows have usable observed and expected values.")
+    safe_expected = frame[expected].replace(0, np.nan)
+    result = {
+        "observed_total": float(frame[observed].sum()),
+        "expected_total": float(frame[expected].sum()),
+        "observed_expected_ratio": float(frame[observed].sum() / safe_expected.sum()) if safe_expected.sum() else np.nan,
+        "zero_expected_rows": int((frame[expected] == 0).sum()),
+    }
+    if denominator:
+        frame[denominator] = pd.to_numeric(frame[denominator], errors="coerce")
+        result["denominator_total"] = float(frame[denominator].sum())
+    return pd.DataFrame([result])
+
+
+def interactive_signal_review(chart) -> pd.DataFrame:
+    """Return a compact table for reviewing detected signals interactively."""
+
+    table = chart.table.copy()
+    if "signal" not in table:
+        return pd.DataFrame(columns=[chart.x, "plot_value", "signal_rule", "suggested_review"])
+    signals = table[table["signal"]].copy()
+    if signals.empty:
+        return pd.DataFrame(columns=[chart.x, "plot_value", "signal_rule", "suggested_review"])
+    signals["suggested_review"] = signals.get("special_cause_type", "signal").astype(str).map(
+        {
+            "improvement": "Check whether the change is real, understood and sustainable.",
+            "concern": "Review context, data quality and potential causes promptly.",
+            "neutral": "Treat as a signal for learning before judging direction.",
+        }
+    ).fillna("Review the point and surrounding process context.")
+    columns = [chart.x, "plot_value", "signal_rule", "suggested_review"]
+    return signals[[column for column in columns if column in signals.columns]].reset_index(drop=True)

pyqicharts/chart_selector.py

@@ -0,0 +1,55 @@
+"""Guided chart selection helpers.
+
+The selector is intentionally rule-of-thumb based. It is meant to help users
+choose a sensible starting chart, not to replace analyst judgement.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ChartSuggestion:
+    """A chart recommendation with a plain-English explanation."""
+
+    chart: str
+    reason: str
+    example: str
+
+
+def suggest_chart(
+    kind: str | None = None,
+    *,
+    numerator: str | None = None,
+    denominator: str | None = None,
+    subgroup: bool = False,
+    rare_event: bool = False,
+    time_between: bool = False,
+    expected: str | None = None,
+) -> ChartSuggestion:
+    """Suggest a chart type from common QI/SPC data shapes.
+
+    Parameters are deliberately lightweight so the helper works in scripts,
+    notebooks, Excel Companion workflows and documentation examples.
+    """
+
+    key = (kind or "").strip().lower().replace("-", "_").replace(" ", "_")
+    if expected and denominator:
+        return ChartSuggestion("p_prime", "Observed and expected values with a denominator usually indicate a risk-adjusted proportion.", "qic(data, x='week', y='observed', expected='expected', denominator='n', chart='p_prime')")
+    if expected:
+        return ChartSuggestion("u_prime", "Observed and expected values without a clear proportion denominator can be reviewed as an observed/expected rate.", "qic(data, x='week', y='observed', expected='expected', chart='u_prime')")
+    if rare_event:
+        return ChartSuggestion("g", "Counts between rare events are suited to a G chart.", "qic(data, x='event_number', y='cases_between_events', chart='g')")
+    if time_between:
+        return ChartSuggestion("t", "Time between events is suited to a T chart.", "qic(data, x='event_number', y='days_between_events', chart='t')")
+    if subgroup or key in {"subgroup", "xbar", "x_bar"}:
+        return ChartSuggestion("xbar", "Repeated measurements in subgroups are usually reviewed with Xbar/S charts.", "qic(data, x='subgroup', y='value', chart='xbar')")
+    if key in {"proportion", "percentage", "percent", "binary"} or (numerator and denominator and key not in {"rate", "count_per_unit"}):
+        return ChartSuggestion("p", "Events out of opportunities are usually a P chart when the result is a proportion.", "qic(data, x='week', y='events', denominator='opportunities', chart='p')")
+    if key in {"rate", "count_per_unit", "events_per_unit"}:
+        return ChartSuggestion("u", "Events per unit of opportunity are usually a U chart.", "qic(data, x='week', y='events', denominator='bed_days', chart='u')")
+    if key in {"count", "counts", "defects"}:
+        return ChartSuggestion("c", "Counts with a broadly constant area of opportunity are usually a C chart.", "qic(data, x='week', y='count', chart='c')")
+    if key in {"run", "median"}:
+        return ChartSuggestion("run", "Use a run chart for a simple time series when you do not need control limits.", "qic(data, x='week', y='value', chart='run')")
+    return ChartSuggestion("i", "A continuous measure over time is usually a good starting point for an Individuals chart.", "qic(data, x='week', y='value', chart='i')")

pyqicharts/cli.py

@@ -0,0 +1,106 @@
+"""Command-line interface for simple automated chart/report creation."""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import pandas as pd
+
+from .core import qic
+from .export import export_excel, export_png, export_powerpoint
+from .reporting import create_report_pack_from_config, load_chart_config
+from .tables import qic_table
+
+
+def _add_chart_arguments(parser: argparse.ArgumentParser) -> None:
+    """Attach the common one-chart arguments used by the ``chart`` command."""
+
+    parser.add_argument("data", help="Input CSV file.")
+    parser.add_argument("--x", required=True, help="X-axis/date/week column.")
+    parser.add_argument("--y", required=True, help="Measure column.")
+    parser.add_argument("--chart", default="i", help="Chart type, for example i, p, u, c, run.")
+    parser.add_argument("--denominator", help="Denominator column for P/U charts.")
+    parser.add_argument("--expected", help="Expected column for P-prime/U-prime charts.")
+    parser.add_argument("--output", required=True, help="Output file path: .xlsx, .pptx or .png.")
+    parser.add_argument("--title", help="Optional chart/report title.")
+
+
+def _run_chart(args: argparse.Namespace) -> int:
+    """Create a single chart and write the requested output file."""
+
+    data = pd.read_csv(args.data)
+    chart = qic(data, args.x, args.y, chart=args.chart, denominator=args.denominator, expected=args.expected, title=args.title)
+    output = Path(args.output)
+    suffix = output.suffix.lower()
+    if suffix == ".xlsx":
+        export_excel(chart, output)
+    elif suffix == ".pptx":
+        export_powerpoint(chart, output, title=args.title)
+    elif suffix == ".png":
+        export_png(chart, output)
+    else:
+        raise ValueError("Output must end with .xlsx, .pptx or .png. Choose one of those file extensions.")
+    return 0
+
+
+def _run_report(args: argparse.Namespace) -> int:
+    """Create a configured multi-chart report folder."""
+
+    metadata = create_report_pack_from_config(args.config, args.output)
+    if metadata.get("successful_charts", 0) != metadata.get("chart_count", 0):
+        raise ValueError(f"Report completed with errors. See {metadata['batch_summary']} for details.")
+    return 0
+
+
+def _run_validate(args: argparse.Namespace) -> int:
+    """Validate that a CSV and chart configuration can produce a table."""
+
+    data = pd.read_csv(args.data)
+    config = load_chart_config(args.config)
+    specs = config.get("charts", [config])
+    spec = specs[0] if isinstance(specs, list) and specs else config
+    table = qic_table(
+        data,
+        x=spec.get("x"),
+        y=spec.get("y"),
+        chart=spec.get("chart", "i"),
+        denominator=spec.get("denominator"),
+        expected=spec.get("expected"),
+    )
+    if table.empty:
+        raise ValueError("Validation produced an empty calculation table. Check the CSV rows and selected columns.")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="pyqicharts", description="Create QI/SPC charts from CSV data.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    chart_parser = subparsers.add_parser("chart", help="Create one chart from one CSV file.")
+    _add_chart_arguments(chart_parser)
+
+    report_parser = subparsers.add_parser("report", help="Create a report folder from a chart config file.")
+    report_parser.add_argument("config", help="JSON or simple YAML chart configuration file.")
+    report_parser.add_argument("--output", required=True, help="Output report folder.")
+
+    validate_parser = subparsers.add_parser("validate", help="Check that a CSV and chart config can be calculated.")
+    validate_parser.add_argument("data", help="Input CSV file.")
+    validate_parser.add_argument("--config", required=True, help="JSON or simple YAML chart configuration file.")
+
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "chart":
+            return _run_chart(args)
+        if args.command == "report":
+            return _run_report(args)
+        if args.command == "validate":
+            return _run_validate(args)
+    except Exception as exc:  # noqa: BLE001 - CLI should present concise user-facing errors.
+        print(f"pyqicharts error: {exc}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

pyqicharts/core.py

@@ -0,0 +1,204 @@
+"""Matplotlib chart construction for pyqicharts.
+
+`qic()` is intentionally a thin plotting wrapper around `qic_table()`. The
+calculation table is always retained on the returned `QicResult`, so users can
+move between scripts, notebooks, Excel exports and Power BI without rerunning
+separate calculation logic.
+"""
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Optional
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+from .rules import AnhoejResult, anhoej_rules
+from .signals import table_signals
+from .tables import qic_table
+from .themes import get_theme
+
+@dataclass
+class QicResult:
+    """Container returned by `qic()` with data, calculations and figure objects."""
+    data: pd.DataFrame
+    chart: str
+    x: str
+    y: str
+    centre: float
+    centre_label: str
+    lcl: Optional[float]
+    ucl: Optional[float]
+    anhoej: Optional[AnhoejResult]
+    signals: pd.Series
+    table: pd.DataFrame
+    figure: object
+    axes: object
+    def save_png(self, path: str, dpi: int = 150):
+        """Save the chart figure as a PNG file."""
+        from .export import export_png
+        return export_png(self, path, dpi=dpi)
+    def summary(self) -> dict:
+        """Return a compact dictionary summary for reports and dashboards."""
+        out = {"chart": self.chart, "centre_label": self.centre_label, "centre": self.centre, "lcl": self.lcl, "ucl": self.ucl, "signals": int(self.signals.sum())}
+        if self.anhoej is not None: out["anhoej"] = self.anhoej
+        return out
+    def signal_table(self) -> pd.DataFrame:
+        """Return detected signals using the stable v1.1 signal schema."""
+        return table_signals(self.table, self.chart, self.x)
+    def show(self):
+        plt.show()
+
+def _normalise_chart_name(chart: str) -> str:
+    """Normalise public chart aliases to the internal chart key."""
+    key = chart.lower().replace("-", "_").replace(" ", "_")
+    return {"individuals":"i", "movingrange":"mr", "moving_range":"mr", "count":"c", "proportion":"p", "rate":"u", "rare_event":"g", "time_between":"t", "p'":"p_prime", "pprime":"p_prime", "u'":"u_prime", "uprime":"u_prime", "x_bar":"xbar", "x-bar":"xbar"}.get(key, key)
+
+def _scalar_or_none(series: pd.Series) -> float | None:
+    """Return the first non-missing scalar from a repeated table column."""
+    non_null = series.dropna()
+    return None if len(non_null) == 0 else float(non_null.iloc[0])
+
+
+def _signal_annotation_label(row: pd.Series) -> str:
+    """Choose the most specific human-readable label for a plotted signal."""
+
+    for column in ["special_cause_label", "special_cause_rule", "signal_rule"]:
+        value = row.get(column, "")
+        if pd.notna(value) and str(value).strip():
+            label = str(value).strip()
+            return label if len(label) <= 48 else label[:45] + "..."
+    return "Signal"
+
+
+def qic(
+    data: pd.DataFrame,
+    x: str,
+    y: str,
+    chart: str = "run",
+    denominator: str | None = None,
+    expected: str | None = None,
+    title: str | None = None,
+    figsize: tuple[int,int] = (10,5),
+    theme: str = "default",
+    improvement: str | None = None,
+    shift_points: int = 6,
+    trend_points: int = 6,
+    baseline_points: int | None = None,
+    recalculation_points: list | None = None,
+    target: float | int | None = None,
+    interventions: list[dict] | None = None,
+    step_changes: list[dict] | None = None,
+    freeze_points: list | None = None,
+    break_points: list | None = None,
+    exclude_points: list | None = None,
+    phases: list[dict] | None = None,
+    rules: str | None = None,
+    method: str = "anhoej",
+    baseline_start=None,
+    baseline_end=None,
+    freeze: list | None = None,
+    breaks: list | None = None,
+    exclude: list | None = None,
+    recalculate_after: list | None = None,
+    targets=None,
+    annotate_signals: bool = True,
+    exclude_mr_outliers: bool = False,
+) -> QicResult:
+    """Create a QI/SPC chart.
+
+    Version 1.2.0 supports run, I, MR, C, P, U, Xbar, S, G, T, P-prime and U-prime charts. P and U charts
+    require a denominator column. Individuals charts include healthcare QI-style
+    special cause colouring and interpretation, plus baseline, recalculation,
+    target, intervention and step-change metadata.
+    """
+    chart_key = _normalise_chart_name(chart); style = get_theme(theme)
+    table = qic_table(
+        data=data,
+        x=x,
+        y=y,
+        chart=chart_key,
+        denominator=denominator,
+        expected=expected,
+        improvement=improvement,
+        shift_points=shift_points,
+        trend_points=trend_points,
+        baseline_points=baseline_points,
+        recalculation_points=recalculation_points,
+        target=target,
+        interventions=interventions,
+        step_changes=step_changes,
+        freeze_points=freeze_points,
+        break_points=break_points,
+        exclude_points=exclude_points,
+        phases=phases,
+        rules=rules,
+        method=method,
+        baseline_start=baseline_start,
+        baseline_end=baseline_end,
+        freeze=freeze,
+        breaks=breaks,
+        exclude=exclude,
+        recalculate_after=recalculate_after,
+        targets=targets,
+        exclude_mr_outliers=exclude_mr_outliers,
+    )
+    fig, ax = plt.subplots(figsize=figsize)
+    ylabel = y
+    if chart_key == "mr": ylabel = f"Moving range of {y}"
+    elif chart_key == "p": ylabel = f"Proportion of {y}"
+    elif chart_key == "u": ylabel = f"Rate of {y}"
+    elif chart_key == "g": ylabel = f"Cases between events: {y}"
+    elif chart_key == "t": ylabel = f"Time between events: {y}"
+    elif chart_key in {"p_prime", "u_prime"}: ylabel = f"Observed / expected: {y}"
+    elif chart_key == "xbar": ylabel = f"Subgroup mean of {y}"
+    elif chart_key == "s": ylabel = f"Subgroup standard deviation of {y}"
+    ax.plot(table[x], table["plot_value"], marker="o", linewidth=1.8, color=style.line, markerfacecolor=style.marker, markeredgecolor=style.marker)
+    signal_rows = table[table["signal"]]
+    if not signal_rows.empty:
+        if "special_cause_type" in signal_rows:
+            plotted_labels = set()
+            for signal_type, rows in signal_rows.groupby("special_cause_type", dropna=False):
+                label = str(signal_type).title() if signal_type else "Signal"
+                color = str(rows["special_cause_colour"].iloc[0]) or style.signal
+                ax.scatter(rows[x], rows["plot_value"], s=90, color=color, marker="o", zorder=5, label=None if label in plotted_labels else label)
+                plotted_labels.add(label)
+        else:
+            ax.scatter(signal_rows[x], signal_rows["plot_value"], s=90, color=style.signal, marker="o", zorder=5, label="Signal")
+        if annotate_signals:
+            # Annotation text is deliberately derived from the calculated table
+            # fields so saved PNGs, notebooks and downstream exports tell the
+            # same story as `qic_table(...)`.
+            for _, row in signal_rows.iterrows():
+                ax.annotate(
+                    _signal_annotation_label(row),
+                    xy=(row[x], row["plot_value"]),
+                    xytext=(6, 10),
+                    textcoords="offset points",
+                    fontsize=8,
+                    color="#231F20",
+                    arrowprops={"arrowstyle": "->", "color": "#425563", "lw": 0.8},
+                )
+    centre = _scalar_or_none(table["centre"]); lcl = _scalar_or_none(table["lcl"]); ucl = _scalar_or_none(table["ucl"]); centre_label = str(table["centre_label"].iloc[0]) if len(table) else "Centre"
+    # Segment-aware horizontal lines let baseline/recalculation periods share
+    # one plot without pretending a single limit applies to every segment.
+    for segment_id, rows in table.groupby("segment_id" if "segment_id" in table else table.index, sort=True):
+        first_x = rows[x].iloc[0]; last_x = rows[x].iloc[-1]
+        seg_centre = _scalar_or_none(rows["centre"]); seg_lcl = _scalar_or_none(rows["lcl"]); seg_ucl = _scalar_or_none(rows["ucl"])
+        label_suffix = "" if segment_id == 1 else f" S{segment_id}"
+        if seg_centre is not None and not np.isnan(seg_centre): ax.hlines(seg_centre, first_x, last_x, linestyle="--", linewidth=1.4, color=style.centre, label=centre_label + label_suffix)
+        if seg_lcl is not None and not np.isnan(seg_lcl): ax.hlines(seg_lcl, first_x, last_x, linestyle=":", linewidth=1.2, color=style.limits, label="LCL" + label_suffix)
+        if seg_ucl is not None and not np.isnan(seg_ucl): ax.hlines(seg_ucl, first_x, last_x, linestyle=":", linewidth=1.2, color=style.limits, label="UCL" + label_suffix)
+    if target is not None:
+        ax.axhline(target, linestyle="-.", linewidth=1.2, color="#330072", label="Target")
+    if "intervention" in table:
+        for _, row in table[table["intervention"]].iterrows():
+            ax.axvline(row[x], linestyle="-", linewidth=1.0, color="#425563", alpha=0.65)
+            if row["intervention_label"]:
+                ax.text(row[x], row["plot_value"], str(row["intervention_label"]), rotation=90, va="bottom", ha="right", fontsize=8)
+    if "step_change" in table:
+        for _, row in table[table["step_change"]].iterrows():
+            ax.axvline(row[x], linestyle="--", linewidth=1.0, color="#007F3B", alpha=0.75)
+            if row["step_change_label"]:
+                ax.text(row[x], row["plot_value"], str(row["step_change_label"]), rotation=90, va="bottom", ha="left", fontsize=8)
+    ax.set_xlabel(x); ax.set_ylabel(ylabel); ax.set_title(title or f"{chart_key.upper()} chart of {y}"); ax.grid(True, alpha=style.grid_alpha); ax.legend(loc="best"); fig.tight_layout()
+    anhoej = anhoej_rules(table[y]) if chart_key == "run" else None
+    return QicResult(data.copy(), chart_key, x, y, centre if centre is not None else float("nan"), centre_label, lcl, ucl, anhoej, table["signal"], table, fig, ax)

pyqicharts/datasets.py

@@ -0,0 +1,96 @@
+"""Small example and sample datasets for pyqicharts.
+
+The bundled datasets are synthetic. They are designed for examples, tests and
+new-user exploration, not for clinical benchmarking.
+"""
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+import pandas as pd
+
+
+def get_sample_data_path(filename: str) -> Path:
+    """Return the installed path for a bundled sample-data CSV.
+
+    The sample CSVs live inside the importable ``pyqicharts`` package so they
+    are available after installation from a wheel or source distribution.
+    ``importlib.resources`` asks Python where the installed package resources
+    are, avoiding brittle assumptions about the user's ``site-packages`` path.
+    """
+
+    sample_root = resources.files("pyqicharts").joinpath("sample_data")
+    path = sample_root.joinpath(filename)
+    if not path.is_file():
+        raise FileNotFoundError(f"Sample dataset not found: {filename}")
+    return Path(path)
+
+
+def infections_between_events() -> pd.DataFrame:
+    """Return synthetic cases-between-infection event data for a G chart."""
+
+    return pd.DataFrame(
+        {
+            "case_number": range(1, 13),
+            "cases_between_events": [22, 18, 25, 21, 19, 24, 85, 20, 23, 17, 2, 21],
+        }
+    )
+
+
+def sample_healthcare_qi_data() -> pd.DataFrame:
+    """Return the bundled healthcare QI sample dataset as a DataFrame."""
+
+    return pd.read_csv(get_sample_data_path("sample_healthcare_qi_data.csv"))
+
+
+def sample_subgroup_measurements() -> pd.DataFrame:
+    """Return the bundled subgroup-measurement sample dataset as a DataFrame."""
+
+    return pd.read_csv(get_sample_data_path("sample_subgroup_measurements.csv"))
+
+
+def days_between_serious_incidents() -> pd.DataFrame:
+    """Return synthetic days-between-serious-incidents data for a T chart."""
+
+    return pd.DataFrame(
+        {
+            "event_number": range(1, 13),
+            "days_between_events": [31, 27, 35, 29, 33, 30, 120, 28, 32, 26, 1, 34],
+        }
+    )
+
+
+def days_between_falls_with_harm() -> pd.DataFrame:
+    """Return synthetic days-between-falls-with-harm data for a T chart."""
+
+    return pd.DataFrame(
+        {
+            "event_number": range(1, 13),
+            "days_between_events": [14, 17, 12, 16, 15, 13, 19, 18, 55, 11, 15, 2],
+        }
+    )
+
+
+def risk_adjusted_readmissions() -> pd.DataFrame:
+    """Return synthetic observed/expected readmissions data for a P-prime chart."""
+
+    return pd.DataFrame(
+        {
+            "month": range(1, 13),
+            "observed": [18, 21, 19, 22, 20, 24, 23, 42, 21, 20, 18, 19],
+            "expected": [20.0, 20.5, 19.8, 21.0, 20.2, 21.5, 22.0, 22.1, 21.0, 20.6, 19.7, 20.1],
+        }
+    )
+
+
+def risk_adjusted_infection_rates() -> pd.DataFrame:
+    """Return synthetic observed/expected infection data for a U-prime chart."""
+
+    return pd.DataFrame(
+        {
+            "month": range(1, 13),
+            "observed": [4, 5, 3, 4, 6, 5, 4, 12, 5, 4, 3, 5],
+            "expected": [4.5, 4.8, 4.2, 4.4, 4.9, 5.1, 4.7, 5.0, 4.6, 4.5, 4.3, 4.8],
+        }
+    )