controlchartspy 0.1.0__py3-none-any.whl

controlchartspy/__init__.py

@@ -0,0 +1,13 @@
+"""Calculate and visualise statistical process control charts and funnel plots."""
+
+from ._api import funnel, funnel_default_settings, spc, spc_default_settings
+from ._result import ControlChart, StaticPlot
+
+__all__ = [
+    "ControlChart",
+    "StaticPlot",
+    "funnel",
+    "funnel_default_settings",
+    "spc",
+    "spc_default_settings",
+]

controlchartspy/_api.py

@@ -0,0 +1,237 @@
+"""Public chart constructors mirroring the R package."""
+
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+from ._data import (
+    TOOLTIPS,
+    Column,
+    Columns,
+    Data,
+    Settings,
+    apply_padding,
+    prepare_aggregations,
+    prepare_data,
+    prepare_settings,
+    prepare_title,
+)
+from ._engine import engine, render
+from ._limits import funnel_limits, funnel_lines, spc_limits
+from ._result import ControlChart, StaticPlot, dimension
+
+Title = str | Mapping[str, object] | None
+ReturnObjs = str | Iterable[str]
+
+
+def _defaults(chart_type: str, group: str | None) -> dict[str, Any]:
+    settings = engine().defaults(chart_type)
+    settings["tooltips"] = TOOLTIPS.copy()
+    if group is None:
+        return settings
+    if group not in settings:
+        raise ValueError(f"'{group}' is not a valid settings group.")
+    group_settings: dict[str, Any] = settings[group]
+    return group_settings
+
+
+def spc_default_settings(group: str | None = None) -> dict[str, Any]:
+    """Return the default settings for SPC charts, optionally for one group."""
+    return _defaults("spc", group)
+
+
+def funnel_default_settings(group: str | None = None) -> dict[str, Any]:
+    """Return the default settings for funnel plots, optionally for one group."""
+    return _defaults("funnel", group)
+
+
+def _create(
+    chart_type: str,
+    data: Data,
+    keys: Column,
+    numerators: Column,
+    optional: Mapping[str, Column | None],
+    indicators: Columns | None,
+    tooltips: Columns | None,
+    aggregations: Mapping[str, str] | None,
+    title: Title,
+    settings: Mapping[str, Settings | None],
+    tooltip_settings: Settings | None,
+    width: float | None,
+    height: float | None,
+    return_objs: ReturnObjs,
+) -> ControlChart:
+    if isinstance(return_objs, str):
+        return_objs = (return_objs,)
+    outputs = set(return_objs)
+    valid = {"static_plot", "limits"}
+    if chart_type == "funnel":
+        valid.add("limit_lines")
+    if outputs - valid:
+        raise ValueError(f"Invalid return_objs: {', '.join(sorted(outputs - valid))}.")
+    width = dimension(width, 640)
+    height = dimension(height, 400)
+    if tooltip_settings is not None:
+        if not isinstance(tooltip_settings, Mapping):
+            raise TypeError("tooltip_settings must be a mapping.")
+        if set(tooltip_settings) - TOOLTIPS.keys():
+            raise ValueError("Invalid tooltip setting.")
+    raw_data, order = prepare_data(
+        data, keys, numerators, optional, indicators, tooltips, chart_type == "spc"
+    )
+    if "static_plot" in outputs and raw_data.get("indicators"):
+        groups = set(zip(*raw_data["indicators"].values()))
+        if len(groups) > 1:
+            raise ValueError(
+                "Grouped SPC charts support limits only; use return_objs='limits'."
+            )
+    defaults = _defaults(chart_type, None)
+    input_settings, conditional = prepare_settings(settings, defaults, order)
+    title_settings = prepare_title(title)
+    updates = engine().call(
+        "makeUpdateValues",
+        raw_data,
+        input_settings,
+        prepare_aggregations(aggregations),
+        conditional,
+        list(dict.fromkeys(raw_data["categories"])),
+    )
+    views = updates["dataViews"]
+    apply_padding(chart_type, views, defaults, title_settings)
+    result = ControlChart()
+    if not outputs:
+        return result
+    raw = render(
+        chart_type,
+        views,
+        title_settings,
+        width,
+        height,
+        "static_plot" in outputs,
+        bool(outputs & {"limits", "limit_lines"}),
+    )
+    if "static_plot" in outputs:
+        result.static_plot = StaticPlot(
+            chart_type, raw["svg"], width, height, views, title_settings
+        )
+    if chart_type == "funnel" and outputs & {"limits", "limit_lines"}:
+        lines = funnel_lines(raw, settings.get("lines") or {})
+        if "limit_lines" in outputs:
+            result.limit_lines = lines
+        if "limits" in outputs:
+            result.limits = funnel_limits(raw, lines, settings.get("outliers") or {})
+    elif chart_type == "spc" and "limits" in outputs:
+        result.limits = spc_limits(raw, settings.get("outliers") or {})
+        result.indicator_names = raw["indicatorVarNames"]
+    return result
+
+
+def spc(
+    data: Data,
+    keys: Column,
+    numerators: Column,
+    denominators: Column | None = None,
+    groupings: Column | None = None,
+    indicators: Columns | None = None,
+    xbar_sds: Column | None = None,
+    tooltips: Columns | None = None,
+    labels: Column | None = None,
+    aggregations: Mapping[str, str] | None = None,
+    title: Title = None,
+    canvas_settings: Settings | None = None,
+    spc_settings: Settings | None = None,
+    outlier_settings: Settings | None = None,
+    nhs_icon_settings: Settings | None = None,
+    scatter_settings: Settings | None = None,
+    line_settings: Settings | None = None,
+    x_axis_settings: Settings | None = None,
+    y_axis_settings: Settings | None = None,
+    date_settings: Settings | None = None,
+    label_settings: Settings | None = None,
+    tooltip_settings: Settings | None = None,
+    width: float | None = None,
+    height: float | None = None,
+    return_objs: ReturnObjs = ("static_plot", "limits"),
+) -> ControlChart:
+    """Generate a statistical process control (SPC) chart and calculate control limits."""
+    return _create(
+        "spc",
+        data,
+        keys,
+        numerators,
+        {
+            "denominators": denominators,
+            "groupings": groupings,
+            "xbar_sds": xbar_sds,
+            "labels": labels,
+        },
+        indicators,
+        tooltips,
+        aggregations,
+        title,
+        {
+            "canvas": canvas_settings,
+            "spc": spc_settings,
+            "outliers": outlier_settings,
+            "nhs_icons": nhs_icon_settings,
+            "scatter": scatter_settings,
+            "lines": line_settings,
+            "x_axis": x_axis_settings,
+            "y_axis": y_axis_settings,
+            "dates": date_settings,
+            "labels": label_settings,
+        },
+        tooltip_settings,
+        width,
+        height,
+        return_objs,
+    )
+
+
+def funnel(
+    data: Data,
+    keys: Column,
+    numerators: Column,
+    denominators: Column,
+    tooltips: Columns | None = None,
+    labels: Column | None = None,
+    aggregations: Mapping[str, str] | None = None,
+    title: Title = None,
+    canvas_settings: Settings | None = None,
+    funnel_settings: Settings | None = None,
+    outlier_settings: Settings | None = None,
+    scatter_settings: Settings | None = None,
+    line_settings: Settings | None = None,
+    x_axis_settings: Settings | None = None,
+    y_axis_settings: Settings | None = None,
+    label_settings: Settings | None = None,
+    tooltip_settings: Settings | None = None,
+    width: float | None = None,
+    height: float | None = None,
+    return_objs: ReturnObjs = ("static_plot", "limits"),
+) -> ControlChart:
+    """Generate a funnel plot and calculate control limits."""
+    return _create(
+        "funnel",
+        data,
+        keys,
+        numerators,
+        {"denominators": denominators, "labels": labels},
+        None,
+        tooltips,
+        aggregations,
+        title,
+        {
+            "canvas": canvas_settings,
+            "funnel": funnel_settings,
+            "outliers": outlier_settings,
+            "scatter": scatter_settings,
+            "lines": line_settings,
+            "x_axis": x_axis_settings,
+            "y_axis": y_axis_settings,
+            "labels": label_settings,
+        },
+        tooltip_settings,
+        width,
+        height,
+        return_objs,
+    )

controlchartspy/_data.py

@@ -0,0 +1,284 @@
+"""Normalize Python columns and R-compatible chart settings."""
+
+import math
+from collections.abc import Iterable, Mapping, Sequence
+from datetime import date, datetime
+from html import escape
+from numbers import Integral, Real
+from typing import Any, TypeGuard
+
+Scalar = str | bool | int | float | None
+Column = str | Iterable[object]
+Columns = Column | Mapping[str, Column]
+Data = Mapping[str, Column] | Sequence[Mapping[str, object]]
+Settings = Mapping[str, Any]
+Record = dict[str, Any]
+
+AGGREGATIONS = {
+    "numerators": "sum",
+    "denominators": "sum",
+    "groupings": "first",
+    "xbar_sds": "first",
+    "tooltips": "first",
+    "labels": "first",
+}
+TOOLTIPS = {
+    "ttip_font_size": 12,
+    "ttip_font": "Arial, sans-serif",
+    "ttip_font_color": "#000000",
+    "ttip_background_color": "#E0E0E0",
+    "ttip_opacity": 1,
+    "ttip_border_radius": 5,
+    "ttip_border_color": "#000000",
+    "ttip_border_width": 1,
+}
+TITLE: dict[str, Any] = {
+    "text": None,
+    "font_size": "16px",
+    "font_weight": "bold",
+    "font_family": "'Arial', sans-serif",
+    "x": "50%",
+    "y": 5,
+    "text_anchor": "middle",
+    "dominant_baseline": "hanging",
+    "subtitle": None,
+    "subtitle_font_size": "12px",
+    "subtitle_font_weight": "normal",
+}
+
+
+def missing(value: object) -> bool:
+    return value is None or (isinstance(value, Real) and math.isnan(value))
+
+
+def is_sequence(value: object) -> TypeGuard[Iterable[object]]:
+    return isinstance(value, Iterable) and not isinstance(value, (str, bytes, Mapping))
+
+
+def scalar(value: object) -> Scalar:
+    if missing(value):
+        return None
+    if isinstance(value, (str, bool)):
+        return value
+    if isinstance(value, Integral):
+        return int(value)
+    if isinstance(value, Real):
+        if not math.isfinite(value):
+            raise ValueError("Infinite values are not supported.")
+        return float(value)
+    if isinstance(value, (date, datetime)):
+        return label(value)
+    raise TypeError(f"Unsupported value type: {type(value).__name__}")
+
+
+def label(value: object) -> str | None:
+    if missing(value):
+        return None
+    if isinstance(value, bool):
+        return str(value).upper()
+    if isinstance(value, datetime):
+        return value.isoformat(sep=" ")
+    if isinstance(value, date):
+        return value.isoformat()
+    if isinstance(value, Real):
+        return format(value, ".15g")
+    return str(value)
+
+
+def column(
+    data: Data, value: Column, name: str, length: int | None = None
+) -> list[Any]:
+    if isinstance(value, str):
+        if isinstance(data, Sequence):
+            value = [row[value] for row in data]
+        else:
+            value = data[value]
+    if not is_sequence(value):
+        raise TypeError(f"{name} must be a column name or a sequence.")
+    result = list(value)
+    if length is not None and len(result) != length:
+        raise ValueError(f"{name} must have one value per observation ({length}).")
+    return result
+
+
+def named_columns(
+    data: Data, value: Columns | None, name: str, length: int
+) -> dict[str, list[str | None]]:
+    if value is None:
+        return {}
+    columns: Mapping[str, Column]
+    if isinstance(value, Mapping):
+        columns = value
+    elif isinstance(value, str):
+        columns = {value: value}
+    else:
+        columns = {name: value}
+    if not columns:
+        raise ValueError(f"{name} must contain at least one column.")
+    return {
+        str(key): [label(item) for item in column(data, values, name, length)]
+        for key, values in columns.items()
+    }
+
+
+def prepare_data(
+    data: Data,
+    keys: Column,
+    numerators: Column,
+    optional: Mapping[str, Column | None],
+    indicators: Columns | None,
+    tooltips: Columns | None,
+    date_keys: bool,
+) -> tuple[Record, list[int]]:
+    keys = column(data, keys, "keys")
+    n = len(keys)
+    if n == 0:
+        raise ValueError("No data present")
+    if date_keys:
+        for key in keys:
+            if not (missing(key) or isinstance(key, (str, date))):
+                raise TypeError("SPC keys must be dates or strings.")
+    groups = named_columns(data, indicators, "indicators", n)
+    tips = named_columns(data, tooltips, "tooltips", n)
+
+    def sort_key(index: int) -> tuple[tuple[bool, Any], ...]:
+        values: list[Any] = [values[index] for values in groups.values()]
+        key = keys[index]
+        if date_keys:
+            key = label(key)
+        values.append(key)
+        return tuple((missing(value), value) for value in values)
+
+    order = sorted(range(n), key=sort_key)
+    raw: Record = {
+        "crosstalk_identities": [str(i + 1) for i in order],
+        "categories": [label(keys[i]) for i in order],
+    }
+    fields = {"numerators": numerators, **optional}
+    for name, value in fields.items():
+        if value is None:
+            continue
+        values = column(data, value, name, n)
+        if name in ("groupings", "labels"):
+            values = [label(item) for item in values]
+            if name == "labels":
+                values = [
+                    escape(item, quote=False) if item is not None else None
+                    for item in values
+                ]
+        else:
+            values = [scalar(item) for item in values]
+            if any(
+                item is not None and not isinstance(item, (int, float))
+                for item in values
+            ):
+                raise TypeError(f"{name} must contain numeric values.")
+        raw[name] = [values[i] for i in order]
+    if groups:
+        raw["indicators"] = {
+            name: [values[i] for i in order] for name, values in groups.items()
+        }
+    if tips:
+        raw["tooltips"] = {
+            name: [values[i] for i in order] for name, values in tips.items()
+        }
+    return raw, order
+
+
+def prepare_settings(
+    settings: Mapping[str, Settings | None],
+    defaults: Mapping[str, Settings],
+    order: Sequence[int],
+) -> tuple[dict[str, dict[str, Any]], bool]:
+    result: dict[str, dict[str, Any]] = {}
+    conditional = False
+    n = len(order)
+    for group, entries in settings.items():
+        if entries is None:
+            continue
+        if not isinstance(entries, Mapping):
+            raise TypeError(f"{group} settings must be a mapping.")
+        result[group] = {}
+        for name, value in entries.items():
+            if name not in defaults[group]:
+                raise ValueError(f"Invalid setting '{name}' in group '{group}'.")
+            if is_sequence(value):
+                value = list(value)
+                if len(value) == 1:
+                    value = value[0]
+                elif len(value) == n:
+                    conditional = True
+                    result[group][name] = {
+                        str(i + 1): setting_value(name, value[i]) for i in order
+                    }
+                    continue
+                else:
+                    raise ValueError(f"Setting '{name}' must have one or {n} values.")
+            result[group][name] = setting_value(name, value)
+    return result, conditional
+
+
+def setting_value(name: str, value: object) -> Scalar:
+    value = scalar(value)
+    if name.endswith("_label") and value is not None:
+        return escape(str(value), quote=False)
+    return value
+
+
+def prepare_aggregations(aggregations: Mapping[str, str] | None) -> dict[str, str]:
+    result = AGGREGATIONS.copy()
+    if aggregations is None:
+        return result
+    if not isinstance(aggregations, Mapping):
+        raise TypeError("aggregations must be a mapping.")
+    valid = {"first", "last", "sum", "mean", "min", "max", "median", "count"}
+    for name, value in aggregations.items():
+        if name not in result:
+            raise ValueError(f"'{name}' is not a valid variable to aggregate.")
+        if value not in valid:
+            raise ValueError(f"'{value}' is not a valid aggregation.")
+        result[name] = value
+    return result
+
+
+def prepare_title(title: str | Mapping[str, object] | None) -> dict[str, Any]:
+    result = TITLE.copy()
+    if isinstance(title, str):
+        result["text"] = title
+    elif title is not None:
+        if not isinstance(title, Mapping):
+            raise TypeError("title must be a string or a mapping.")
+        for name, value in title.items():
+            if name not in result:
+                raise ValueError(f"Invalid title setting '{name}'.")
+            if value is not None:
+                result[name] = scalar(value)
+    for name in ("text", "subtitle"):
+        if result[name] is not None:
+            result[name] = escape(str(result[name]), quote=False)
+    return result
+
+
+def apply_padding(
+    chart_type: str,
+    views: list[Any],
+    defaults: Mapping[str, Settings],
+    title: Mapping[str, Any],
+) -> None:
+    title_padding = 0.0
+    if title["text"] is not None:
+        title_padding = float(str(title["font_size"]).removesuffix("px")) + title["y"]
+        if title["subtitle"] is not None:
+            title_padding += float(str(title["subtitle_font_size"]).removesuffix("px"))
+    for settings in views[0]["categorical"]["categories"][0]["objects"]:
+        canvas = {**defaults["canvas"], **settings.get("canvas", {})}
+        axis = {**defaults["x_axis"], **settings.get("x_axis", {})}
+        canvas["upper_padding"] += title_padding
+        canvas["left_padding"] += 50
+        pad = 10 + axis["xlimit_tick_size"]
+        if axis["xlimit_tick_rotation"] != 0:
+            pad += 15
+        if chart_type == "spc" and axis["xlimit_label"]:
+            pad += 20
+        canvas["lower_padding"] += pad
+        settings["canvas"] = canvas

controlchartspy/_engine.py

@@ -0,0 +1,97 @@
+"""Thread-local access to the shared chart engine."""
+
+import json
+import threading
+import warnings
+from collections.abc import Mapping
+from importlib.resources import files
+from typing import Any
+
+import quickjs
+
+_STATE = threading.local()
+_SCRIPTS = (
+    "minidom.js",
+    "ccD3.js",
+    "PBISPC.js",
+    "PBIFUN.js",
+    "MISC.js",
+    "commonUtils.js",
+    "headlessUtils.js",
+)
+
+
+def _warn(message: str) -> None:
+    warnings.warn(message, RuntimeWarning, stacklevel=3)
+
+
+class Engine:
+    def __init__(self) -> None:
+        self.context = quickjs.Context()
+        self.context.add_callable("pythonWarning", _warn)
+        self.context.eval("""
+            globalThis.console = {
+                log: (...args) => pythonWarning(args.join(" ")),
+                error: (error) => pythonWarning(String(error))
+            };
+            function pythonReplacer(key, value) {
+                if (value === undefined) {
+                    return null;
+                }
+                return value;
+            }
+            function pythonCall(name, payload) {
+                return JSON.stringify(globalThis[name](...JSON.parse(payload)), pythonReplacer);
+            }
+            function pythonDefaults(type) {
+                return JSON.stringify(globalThis[type].defaultSettings, pythonReplacer);
+            }
+        """)
+        assets = files("controlchartspy").joinpath("_vendor")
+        for name in _SCRIPTS:
+            self.context.eval(assets.joinpath(name).read_text(encoding="utf-8"))
+        self.context.eval("initialiseHeadless()")
+        self._call = self.context.get("pythonCall")
+        self._defaults = self.context.get("pythonDefaults")
+
+    def call(self, name: str, *args: object) -> Any:
+        try:
+            return json.loads(self._call(name, json.dumps(args, allow_nan=False)))
+        except quickjs.JSException as error:
+            raise ValueError(str(error)) from error
+
+    def defaults(self, chart_type: str) -> dict[str, Any]:
+        defaults: dict[str, Any] = json.loads(self._defaults(chart_type))
+        return defaults
+
+
+def engine() -> Engine:
+    instance: Engine | None = getattr(_STATE, "engine", None)
+    if instance is None:
+        instance = Engine()
+        _STATE.engine = instance
+    return instance
+
+
+def render(
+    chart_type: str,
+    data_views: list[Any],
+    title: Mapping[str, Any],
+    width: float,
+    height: float,
+    static: bool,
+    limits: bool,
+) -> dict[str, Any]:
+    result: dict[str, Any] = engine().call(
+        "updateHeadlessVisual",
+        chart_type,
+        data_views,
+        title,
+        width,
+        height,
+        static,
+        limits,
+    )
+    if "error" in result:
+        raise ValueError(result["error"])
+    return result