Visualisation

displayer

High-level display and visualisation manager module.

BaseDisplayer

Shared visualisation engine providing config resolution, subgroup heatmap plotting, and artifact persistence, independent of outcome type.

Config-resolution and heatmap plotting are outcome-type-agnostic: plot parameter precedence (defaults -> overrides -> outcome overrides -> runtime kwargs) and strata delta heatmaps operate purely on plot-type names, metric names, and evaluation dictionaries produced identically by both the classifier and regressor evaluators. Outcome-type-specific metric computation and high-level plotting methods (e.g. ROC/PR curves for classification, coverage/sharpness for regression) are provided by subclasses, which also override _PLOT_TYPE_ALIASES and _FALLBACK_DISPLAY_DEFAULTS for their own plot types.

Parameters:

Name	Type	Description	Default
`orchestrator`	`MedpipeOrchestrator`	Active pipeline orchestrator instance containing execution context and run directory.	required
`theme`	`MedpipeTheme`	Aesthetic theme configuration. If None, defaults to `MedpipeTheme()`.	`None`

Attributes:

Name	Type	Description
`orchestrator`	`MedpipeOrchestrator`	Associated pipeline orchestrator instance.
`run_dir`	`Path`	Path to the output directory for storing generated figures.
`theme`	`MedpipeTheme`	Active visual theme specification.
`logger`	`Logger`	Console logger instance for displayer operations.

Methods:

Name	Description
`plot_data_distribution`
`label=None, xlabel=None, save=None, show=None, **style_kwargs)`	Render a data distribution histogram and save output.
`plot_strata_heatmap`
`save=None, show=None, **style_kwargs)`	Validate subgroup inputs, compute delta matrix, render strata heatmap, and save output.
`plot_all_heatmaps`	Generate subgroup delta heatmaps across outcomes for each evaluated metric.

Source code in medpipe/visualisation/displayer.py

class BaseDisplayer:
    """Shared visualisation engine providing config resolution, subgroup
    heatmap plotting, and artifact persistence, independent of outcome type.

    Config-resolution and heatmap plotting are outcome-type-agnostic: plot
    parameter precedence (defaults -> overrides -> outcome overrides ->
    runtime kwargs) and strata delta heatmaps operate purely on plot-type
    names, metric names, and evaluation dictionaries produced identically by
    both the classifier and regressor evaluators. Outcome-type-specific
    metric computation and high-level plotting methods (e.g. ROC/PR curves
    for classification, coverage/sharpness for regression) are provided by
    subclasses, which also override `_PLOT_TYPE_ALIASES` and
    `_FALLBACK_DISPLAY_DEFAULTS` for their own plot types.

    Parameters
    ----------
    orchestrator : MedpipeOrchestrator
        Active pipeline orchestrator instance containing execution context and
        run directory.
    theme : MedpipeTheme, optional
        Aesthetic theme configuration. If None, defaults to `MedpipeTheme()`.

    Attributes
    ----------
    orchestrator : MedpipeOrchestrator
        Associated pipeline orchestrator instance.
    run_dir : Path
        Path to the output directory for storing generated figures.
    theme : MedpipeTheme
        Active visual theme specification.
    logger : logging.Logger
        Console logger instance for displayer operations.

    Methods
    -------
    plot_data_distribution(data, outcome="default", n_bins=None, yscale=None,
    label=None, xlabel=None, save=None, show=None, **style_kwargs)
        Render a data distribution histogram and save output.
    plot_strata_heatmap(outcomes, metric, strata, scores, strata_scores,
    save=None, show=None, **style_kwargs)
        Validate subgroup inputs, compute delta matrix, render strata heatmap,
        and save output.
    plot_all_heatmaps(evaluations, metrics=None, save=None, show=None, **style_kwargs)
        Generate subgroup delta heatmaps across outcomes for each evaluated metric.

    """

    _PLOT_TYPE_ALIASES: ClassVar[dict[str, str]] = {
        "heatmap": "strata_heatmap",
    }
    # Metrics expressed in the units of the target, for which the heatmap colour
    # scale is set from the data instead of a fixed value.
    _SCALE_DEPENDENT_METRICS: ClassVar[frozenset[str]] = frozenset(
        {"rmse", "mae", "crps"}
    )
    _FALLBACK_DISPLAY_DEFAULTS: ClassVar[dict[str, Any]] = {
        "n_bootstraps": 1000,
        "save": True,
        "show": False,
        "n_jobs": 1,
    }

    def __init__(
        self,
        orchestrator: MedpipeOrchestrator,
        theme: MedpipeTheme | None = None,
    ) -> None:
        self.orchestrator = orchestrator
        self.run_dir = orchestrator.run_dir
        self.theme = theme or self._theme_from_config(orchestrator)
        self.logger = get_console_logger("medpipe.displayer")

    @staticmethod
    def _theme_from_config(orchestrator: MedpipeOrchestrator) -> MedpipeTheme:
        """Build the theme from the `display.theme` configuration.

        Parameters
        ----------
        orchestrator : MedpipeOrchestrator
            Pipeline orchestrator holding the validated configuration.

        Returns
        -------
        MedpipeTheme
            Theme built from the configured parameters, or the default theme
            if none are configured. Unrecognised keys are ignored.

        """
        display_cfg = getattr(orchestrator.config, "display", None)
        theme_cfg = getattr(display_cfg, "theme", None)
        if isinstance(theme_cfg, dict) and theme_cfg:
            return MedpipeTheme.from_dict(theme_cfg)
        return MedpipeTheme()

    # --- Config Resolution ---

    @classmethod
    def _normalize_plot_type(cls, plot_type: str) -> str:
        """Normalize plot aliases to canonical names.

        Parameters
        ----------
        plot_type : str
            Raw identifier or alias for a specific plot type
            (e.g., 'calibration', 'pr_curve').

        Returns
        -------
        str
            Canonical plot type identifier used for consistent configuration lookup.

        """
        return cls._PLOT_TYPE_ALIASES.get(plot_type.lower(), plot_type.lower())

    def _resolve_plot_config(
        self,
        plot_type: str,
        outcome: str | None = None,
        **runtime_kwargs: Any,
    ) -> dict[str, Any]:
        """Resolve plot parameters hierarchically across configuration levels.

        Applies parameter precedence in the following order (lowest to highest):
        1. Default global display settings (`display_cfg.defaults`)
        2. Plot-type overrides (`display_cfg.overrides`)
        3. Outcome-specific plot overrides (`display_cfg.outcome_overrides`)
        4. Explicit non-None runtime arguments (`runtime_kwargs`)

        Parameters
        ----------
        plot_type : str
            Plot identifier or alias (e.g., 'calibration', 'roc', 'distribution').
        outcome : str, optional
            Outcome key used to retrieve outcome-specific plot overrides.
        **runtime_kwargs : Any
            Runtime keyword arguments passed directly to the calling plot method.

        Returns
        -------
        dict of {str : Any}
            Fully resolved dictionary of parameters for the specified plot.

        """
        display_cfg = getattr(self.orchestrator.config, "display", None)

        if display_cfg is None:
            config_params: dict[str, Any] = dict(self._FALLBACK_DISPLAY_DEFAULTS)
            overrides: dict[str, Any] = {}
            outcome_overrides: dict[str, Any] = {}
        else:
            config_params = display_cfg.defaults.model_dump()
            overrides = display_cfg.overrides
            outcome_overrides = display_cfg.outcome_overrides

        canonical_type = self._normalize_plot_type(plot_type)

        # 1. Apply global plot-type overrides (matching on any alias that
        # normalizes to the same canonical plot type as `plot_type`)
        for key, value in overrides.items():
            if self._normalize_plot_type(key) == canonical_type:
                config_params.update(value)

        # 2. Apply outcome-specific plot overrides
        if outcome and outcome in outcome_overrides:
            out_cfg = outcome_overrides[outcome]
            for key, value in out_cfg.items():
                if self._normalize_plot_type(key) == canonical_type:
                    config_params.update(value)

        # 3. Apply explicit non-None runtime kwargs overrides
        for k, v in runtime_kwargs.items():
            if v is not None:
                config_params[k] = v

        return config_params

    # --- Internal Helpers ---
    @staticmethod
    def _format_stratum_label(cat_key: Any) -> str:
        """Format raw stratum variable names and category keys into clean
        display labels.

        Parses stringified numerical bounds (e.g., '[18, 50]' or '[51, 120]') into
        readable ranges (e.g., '18-50' or open-ended '≥ 51'). Non-interval keys
        (e.g., 'F', 'M') are returned with standard variable prefixing.

        Parameters
        ----------
        cat_key : Any
            Category identifier or raw bin string (e.g., '[18, 50]', 'F').

        Returns
        -------
        str
            Formatted stratum label suitable for heatmap visual displays.

        Examples
        --------
        >>> BaseDisplayer._format_stratum_label("[18, 50]")
        '18-50'
        >>> BaseDisplayer._format_stratum_label("[51, 120]")
        '≥ 51'
        >>> BaseDisplayer._format_stratum_label("F")
        'Female'

        """
        cat_str = str(cat_key).strip()

        if cat_str.startswith("[") and cat_str.endswith("]"):
            try:
                parsed = ast.literal_eval(cat_str)
                if isinstance(parsed, (list, tuple)) and len(parsed) == 2:
                    low, high = parsed[0], parsed[1]

                    if isinstance(high, (int, float)) and high >= 100:
                        return f"≥ {low}"

                    return f"{low}-{high}"
            except (ValueError, SyntaxError):
                pass

        if cat_str == "F":
            return "Female"

        elif cat_str == "M":
            return "Male"

        return f"{cat_str}"

    def _save_figure(
        self, fig: Figure | SubFigure, filename: str, outcome: str | None = None
    ) -> Path:
        """Persist figure artifact to disk in the run directory structure.

        Parameters
        ----------
        fig : Figure | SubFigure
            Matplotlib figure object to be saved.
        filename : str
            Base filename for the saved image file (without extension).
        outcome : str, optional
            Subdirectory name corresponding to a specific clinical outcome.

        Returns
        -------
        Path
            Absolute path to the created plot file.
        """
        plot_dir = self.run_dir / "plots"
        if outcome:
            plot_dir = plot_dir / outcome
        plot_dir.mkdir(parents=True, exist_ok=True)

        save_path = plot_dir / f"{filename}.png"
        fig.get_figure(root=True).savefig(
            save_path, dpi=self.theme.dpi, bbox_inches="tight"
        )
        self.logger.info(f"Saved plot artifact to {save_path}")
        return save_path

    # --- Data Distribution Plotting ---

    def plot_data_distribution(
        self,
        data: np.ndarray,
        outcome: str = "default",
        n_bins: int | None = None,
        yscale: str | None = None,
        label: str | None = None,
        xlabel: str | None = None,
        save: bool | None = None,
        show: bool | None = None,
        **style_kwargs: Any,
    ) -> tuple[Figure | SubFigure, Axes]:
        """Render a data distribution histogram and save figure artifact.

        Outcome-type-agnostic: works for classifier predicted probabilities
        or regressor continuous target values alike.

        Parameters
        ----------
        data : np.ndarray
            Data values of shape (n_samples, 2) or (n_samples,) (e.g.
            predicted probabilities or continuous target values).
        outcome : str, default="default"
            Outcome identifier used for figure titles and directory structuring.
        n_bins : int, optional
            Number of equal-width bins spanning the data's own range.
        yscale : str, optional
            Scale to use for the y-axis (e.g. linear, log, etc.)
        label : str, optional
            Legend label. Defaults to "Data".
        xlabel : str, optional
            Label for the x-axis. Defaults to "Value".
        save : bool, optional
            Automatically save the generated plot to the run directory.
        show : bool, optional
            Whether to display the plot interactively before closing.
        **style_kwargs : Any
            Additional style parameters forwarded to `draw_data_distribution`.

        Returns
        -------
        fig : Figure | SubFigure
            Rendered Matplotlib figure object.
        ax : Axes
            Matplotlib axes containing the plotted histogram.

        """
        cfg = self._resolve_plot_config(
            plot_type="distribution",
            outcome=outcome,
            dist_n_bins=n_bins,
            dist_yscale=yscale,
            save=save,
            show=show,
            **style_kwargs,
        )

        n_bins_val = cfg.get("dist_n_bins", 10)
        save_val = cfg["save"]
        show_val = cfg["show"]
        dist_yscale_val = cfg.get("dist_yscale", "linear")

        self.logger.info(f"[{outcome}] Starting data distribution plotting.")
        self.logger.debug(
            f"[{outcome}] Plotting data distribution with "
            f"data: {data.shape} and {n_bins_val} bins."
        )
        display_label = label or "Data"

        with (
            plt.rc_context(self.theme.to_rc_params()),
        ):
            fig, ax = draw_data_distribution(
                data=data,
                n_bins=n_bins_val,
                label=display_label,
                xlabel=xlabel or "Value",
                yscale=dist_yscale_val,
                color=style_kwargs.pop("color", self.theme.primary_color),
                show_spines=style_kwargs.pop("show_spines", self.theme.show_spines),
                **style_kwargs,
            )

        if save_val:
            self._save_figure(
                fig=fig,
                filename=f"{outcome}_data_distribution",
                outcome=outcome,
            )

        if show_val:
            plt.show()
        elif save_val:
            plt.close(fig.get_figure(root=True))

        return fig, ax

    # --- Subgroup Heatmap Plotting ---

    def plot_strata_heatmap(
        self,
        outcomes: list[str],
        metric: str,
        strata: list[str],
        scores: np.ndarray,
        strata_scores: np.ndarray,
        save: bool | None = None,
        show: bool | None = None,
        **style_kwargs: Any,
    ) -> tuple[Figure | SubFigure, Axes]:
        """Validate strata data, compute delta matrix, and render heatmap.

        Parameters
        ----------
        outcomes : list of str
            List of outcome names.
        metric : str
            Metric identifier being evaluated (e.g., 'auc', 'ici').
        strata : list of str
            List of subgroup strata names.
        scores : np.ndarray
            Baseline metric scores for unstratified models of shape (n_outcomes,).
        strata_scores : np.ndarray
            Metric scores per stratum and outcome of shape (n_strata, n_outcomes).
        save : bool, optional
            Automatically save the generated plot to the run directory.
        show : bool, optional
            Whether to display the plot interactively before closing.
        **style_kwargs : Any
            Additional style parameters forwarded to `draw_strata_heatmap`.

        Returns
        -------
        fig : Figure | SubFigure
            Rendered Matplotlib figure object.
        ax : Axes
            Matplotlib axes containing the heatmap plot.

        Raises
        ------
        ValueError
            If matrix dimensions do not match the provided strata, outcomes, or scores.

        """
        cfg = self._resolve_plot_config(
            plot_type="strata_heatmap",
            save=save,
            show=show,
            **style_kwargs,
        )
        save_val = cfg["save"]
        show_val = cfg["show"]

        scores_arr = np.asarray(scores)
        strata_scores_arr = np.asarray(strata_scores)

        # 1. Validation Logic
        if strata_scores_arr.ndim != 2:
            raise ValueError(
                f"strata_scores must be a 2D array, got shape {strata_scores_arr.shape}"
            )
        if len(strata) != strata_scores_arr.shape[0]:
            raise ValueError(
                f"Inputs strata and strata_scores must have matching row count, "
                f"got {len(strata)} and {strata_scores_arr.shape[0]}"
            )
        if len(outcomes) != strata_scores_arr.shape[1]:
            raise ValueError(
                f"Inputs outcomes and strata_scores must have matching column count, "
                f"got {len(outcomes)} and {strata_scores_arr.shape[1]}"
            )
        if len(scores_arr) != strata_scores_arr.shape[1]:
            raise ValueError(
                f"Inputs scores and strata_scores must have matching column count, "
                f"got {len(scores_arr)} and {strata_scores_arr.shape[1]}"
            )

        # 2. Data Preparation
        strata_matrix = np.vstack((scores_arr, strata_scores_arr))
        plot_data = np.abs(strata_matrix - scores_arr)
        text_data = strata_matrix.copy()

        try:
            spec = MetricRegistry.get(metric)
            display_name = (
                getattr(spec, "display_name", None) or metric.replace("_", " ").upper()
            )
        except Exception:
            display_name = metric.replace("_", " ").upper()

        is_ici = metric.lower() == "ici"
        vmax = 0.5 if is_ici else 0.1
        if metric.lower() in self._SCALE_DEPENDENT_METRICS:
            # Errors in the units of the target: no fixed scale applies
            vmax = float(np.max(plot_data)) or 1.0
        percent = r" $\times$ 100" if is_ici else ""

        if is_ici:
            plot_data *= 100
            text_data *= 100

        colorbar_label = rf"|$\Delta$ {display_name}|" + percent
        title = style_kwargs.pop("title", f"Strata delta - {display_name}{percent}")
        row_labels = ["All strata", *list(strata)]

        # 3. Stateless Drawing Delegate
        with (
            plt.rc_context(self.theme.to_rc_params()),
        ):
            fig, ax = draw_strata_heatmap(
                plot_data=plot_data,
                text_data=text_data,
                row_labels=row_labels,
                col_labels=outcomes,
                colorbar_label=colorbar_label,
                vmax=vmax,
                title=title,
                **style_kwargs,
            )

        if save_val:
            self._save_figure(fig=fig, filename=f"{metric}_strata_heatmap")

        if show_val:
            plt.show()
        elif save_val:
            plt.close(fig.get_figure(root=True))

        return fig, ax

    def plot_all_heatmaps(
        self,
        evaluations: dict[str, Any],
        metrics: list[str] | None = None,
        save: bool | None = None,
        show: bool | None = None,
        **style_kwargs: Any,
    ) -> dict[str, tuple[Figure | SubFigure, Axes]]:
        """Generate subgroup delta heatmaps across outcomes for each evaluated metric.

        Parameters
        ----------
        evaluations : dict of str to Any
            Nested evaluations dictionary mapping outcome keys to their overall and
            subgroup performance evaluation results.
        metrics : list of str, optional
            List of metric names to render heatmaps for (e.g., ['auc', 'ici']).
            If None, inferred from the first outcome's overall metrics.
        save : bool, optional
            Automatically save all generated heatmap figures to disk.
        show : bool, optional
            Whether to display figures interactively before closing.
        **style_kwargs : Any
            Additional style parameters forwarded to `plot_strata_heatmap`.

        Returns
        -------
        heatmap_plots : dict of str to (Figure, Axes)
            Dictionary mapping metric names to their rendered (Figure, Axes) tuples.

        """
        outcomes = list(evaluations.keys())
        if not outcomes:
            return {}

        first_eval = evaluations[outcomes[0]]
        overall_dict = first_eval.get("overall", {})
        strata_dict = first_eval.get("strata", {})

        target_metrics = metrics or list(overall_dict.keys())

        # Flatten nested strata dict structure: stratum_variable -> category -> metric
        # Example row labels: "SEX: F", "SEX: M", "AGE: [18, 50]"
        strata_tuples: list[tuple[str, str]] = []
        strata_row_labels: list[str] = []

        for stratum_var, cat_dict in strata_dict.items():
            for cat_key in cat_dict:
                strata_tuples.append((stratum_var, cat_key))
                # Use helper to transform raw cat_key into clean label
                strata_row_labels.append(self._format_stratum_label(cat_key))

        if not strata_tuples:
            self.logger.warning(
                "No subgroup strata found in evaluation dict; skipping heatmaps."
            )
            return {}

        heatmap_plots: dict[str, tuple[Figure | SubFigure, Axes]] = {}

        for metric in target_metrics:
            # Look up MetricSpec display_name
            try:
                spec = MetricRegistry.get(metric)
                disp_name = (
                    getattr(spec, "display_name", None)
                    or metric.replace("_", " ").upper()
                )
            except Exception:
                disp_name = metric.replace("_", " ").upper()

            self.logger.info(
                f"--- Starting heatmap plotting for metric: {disp_name} ---"
            )
            # Extract unstratified baseline point estimates across outcomes
            scores_list = []
            for out in outcomes:
                entry = evaluations[out].get("overall", {}).get(metric, {})
                val = (
                    entry.get("point_estimate", np.nan)
                    if isinstance(entry, dict)
                    else entry
                )
                scores_list.append(val)
            scores = np.array(scores_list)

            # Extract stratum point estimates matrix (shape: n_strata_rows, n_outcomes)
            strata_scores_list: list[list[float]] = []
            for stratum_var, cat_key in strata_tuples:
                row = []
                for out in outcomes:
                    entry = (
                        evaluations[out]
                        .get("strata", {})
                        .get(stratum_var, {})
                        .get(cat_key, {})
                        .get(metric, {})
                    )
                    val = (
                        entry.get("point_estimate", np.nan)
                        if isinstance(entry, dict)
                        else entry
                    )
                    row.append(val)
                strata_scores_list.append(row)

            strata_scores = np.array(strata_scores_list)

            # Render heatmap for current metric
            heatmap_plots[metric] = self.plot_strata_heatmap(
                outcomes=outcomes,
                metric=metric,
                strata=strata_row_labels,
                scores=scores,
                strata_scores=strata_scores,
                save=save,
                show=show,
                **style_kwargs.copy(),
            )

            self.logger.info(
                f"--- Finished heatmap plotting for metric: {disp_name} ---"
            )
        return heatmap_plots

plot_data_distribution

plot_data_distribution(
    data: ndarray,
    outcome: str = "default",
    n_bins: int | None = None,
    yscale: str | None = None,
    label: str | None = None,
    xlabel: str | None = None,
    save: bool | None = None,
    show: bool | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Render a data distribution histogram and save figure artifact.

Outcome-type-agnostic: works for classifier predicted probabilities or regressor continuous target values alike.

Parameters:

Name	Type	Description	Default
`data`	`ndarray`	Data values of shape (n_samples, 2) or (n_samples,) (e.g. predicted probabilities or continuous target values).	required
`outcome`	`str`	Outcome identifier used for figure titles and directory structuring.	`"default"`
`n_bins`	`int`	Number of equal-width bins spanning the data's own range.	`None`
`yscale`	`str`	Scale to use for the y-axis (e.g. linear, log, etc.)	`None`
`label`	`str`	Legend label. Defaults to "Data".	`None`
`xlabel`	`str`	Label for the x-axis. Defaults to "Value".	`None`
`save`	`bool`	Automatically save the generated plot to the run directory.	`None`
`show`	`bool`	Whether to display the plot interactively before closing.	`None`
`**style_kwargs`	`Any`	Additional style parameters forwarded to `draw_data_distribution`.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure \| SubFigure`	Rendered Matplotlib figure object.
`ax`	`Axes`	Matplotlib axes containing the plotted histogram.

Source code in medpipe/visualisation/displayer.py

def plot_data_distribution(
    self,
    data: np.ndarray,
    outcome: str = "default",
    n_bins: int | None = None,
    yscale: str | None = None,
    label: str | None = None,
    xlabel: str | None = None,
    save: bool | None = None,
    show: bool | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Render a data distribution histogram and save figure artifact.

    Outcome-type-agnostic: works for classifier predicted probabilities
    or regressor continuous target values alike.

    Parameters
    ----------
    data : np.ndarray
        Data values of shape (n_samples, 2) or (n_samples,) (e.g.
        predicted probabilities or continuous target values).
    outcome : str, default="default"
        Outcome identifier used for figure titles and directory structuring.
    n_bins : int, optional
        Number of equal-width bins spanning the data's own range.
    yscale : str, optional
        Scale to use for the y-axis (e.g. linear, log, etc.)
    label : str, optional
        Legend label. Defaults to "Data".
    xlabel : str, optional
        Label for the x-axis. Defaults to "Value".
    save : bool, optional
        Automatically save the generated plot to the run directory.
    show : bool, optional
        Whether to display the plot interactively before closing.
    **style_kwargs : Any
        Additional style parameters forwarded to `draw_data_distribution`.

    Returns
    -------
    fig : Figure | SubFigure
        Rendered Matplotlib figure object.
    ax : Axes
        Matplotlib axes containing the plotted histogram.

    """
    cfg = self._resolve_plot_config(
        plot_type="distribution",
        outcome=outcome,
        dist_n_bins=n_bins,
        dist_yscale=yscale,
        save=save,
        show=show,
        **style_kwargs,
    )

    n_bins_val = cfg.get("dist_n_bins", 10)
    save_val = cfg["save"]
    show_val = cfg["show"]
    dist_yscale_val = cfg.get("dist_yscale", "linear")

    self.logger.info(f"[{outcome}] Starting data distribution plotting.")
    self.logger.debug(
        f"[{outcome}] Plotting data distribution with "
        f"data: {data.shape} and {n_bins_val} bins."
    )
    display_label = label or "Data"

    with (
        plt.rc_context(self.theme.to_rc_params()),
    ):
        fig, ax = draw_data_distribution(
            data=data,
            n_bins=n_bins_val,
            label=display_label,
            xlabel=xlabel or "Value",
            yscale=dist_yscale_val,
            color=style_kwargs.pop("color", self.theme.primary_color),
            show_spines=style_kwargs.pop("show_spines", self.theme.show_spines),
            **style_kwargs,
        )

    if save_val:
        self._save_figure(
            fig=fig,
            filename=f"{outcome}_data_distribution",
            outcome=outcome,
        )

    if show_val:
        plt.show()
    elif save_val:
        plt.close(fig.get_figure(root=True))

    return fig, ax

plot_strata_heatmap

plot_strata_heatmap(
    outcomes: list[str],
    metric: str,
    strata: list[str],
    scores: ndarray,
    strata_scores: ndarray,
    save: bool | None = None,
    show: bool | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Validate strata data, compute delta matrix, and render heatmap.

Parameters:

Name	Type	Description	Default
`outcomes`	`list of str`	List of outcome names.	required
`metric`	`str`	Metric identifier being evaluated (e.g., 'auc', 'ici').	required
`strata`	`list of str`	List of subgroup strata names.	required
`scores`	`ndarray`	Baseline metric scores for unstratified models of shape (n_outcomes,).	required
`strata_scores`	`ndarray`	Metric scores per stratum and outcome of shape (n_strata, n_outcomes).	required
`save`	`bool`	Automatically save the generated plot to the run directory.	`None`
`show`	`bool`	Whether to display the plot interactively before closing.	`None`
`**style_kwargs`	`Any`	Additional style parameters forwarded to `draw_strata_heatmap`.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure \| SubFigure`	Rendered Matplotlib figure object.
`ax`	`Axes`	Matplotlib axes containing the heatmap plot.

Raises:

Type	Description
`ValueError`	If matrix dimensions do not match the provided strata, outcomes, or scores.

Source code in medpipe/visualisation/displayer.py

def plot_strata_heatmap(
    self,
    outcomes: list[str],
    metric: str,
    strata: list[str],
    scores: np.ndarray,
    strata_scores: np.ndarray,
    save: bool | None = None,
    show: bool | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Validate strata data, compute delta matrix, and render heatmap.

    Parameters
    ----------
    outcomes : list of str
        List of outcome names.
    metric : str
        Metric identifier being evaluated (e.g., 'auc', 'ici').
    strata : list of str
        List of subgroup strata names.
    scores : np.ndarray
        Baseline metric scores for unstratified models of shape (n_outcomes,).
    strata_scores : np.ndarray
        Metric scores per stratum and outcome of shape (n_strata, n_outcomes).
    save : bool, optional
        Automatically save the generated plot to the run directory.
    show : bool, optional
        Whether to display the plot interactively before closing.
    **style_kwargs : Any
        Additional style parameters forwarded to `draw_strata_heatmap`.

    Returns
    -------
    fig : Figure | SubFigure
        Rendered Matplotlib figure object.
    ax : Axes
        Matplotlib axes containing the heatmap plot.

    Raises
    ------
    ValueError
        If matrix dimensions do not match the provided strata, outcomes, or scores.

    """
    cfg = self._resolve_plot_config(
        plot_type="strata_heatmap",
        save=save,
        show=show,
        **style_kwargs,
    )
    save_val = cfg["save"]
    show_val = cfg["show"]

    scores_arr = np.asarray(scores)
    strata_scores_arr = np.asarray(strata_scores)

    # 1. Validation Logic
    if strata_scores_arr.ndim != 2:
        raise ValueError(
            f"strata_scores must be a 2D array, got shape {strata_scores_arr.shape}"
        )
    if len(strata) != strata_scores_arr.shape[0]:
        raise ValueError(
            f"Inputs strata and strata_scores must have matching row count, "
            f"got {len(strata)} and {strata_scores_arr.shape[0]}"
        )
    if len(outcomes) != strata_scores_arr.shape[1]:
        raise ValueError(
            f"Inputs outcomes and strata_scores must have matching column count, "
            f"got {len(outcomes)} and {strata_scores_arr.shape[1]}"
        )
    if len(scores_arr) != strata_scores_arr.shape[1]:
        raise ValueError(
            f"Inputs scores and strata_scores must have matching column count, "
            f"got {len(scores_arr)} and {strata_scores_arr.shape[1]}"
        )

    # 2. Data Preparation
    strata_matrix = np.vstack((scores_arr, strata_scores_arr))
    plot_data = np.abs(strata_matrix - scores_arr)
    text_data = strata_matrix.copy()

    try:
        spec = MetricRegistry.get(metric)
        display_name = (
            getattr(spec, "display_name", None) or metric.replace("_", " ").upper()
        )
    except Exception:
        display_name = metric.replace("_", " ").upper()

    is_ici = metric.lower() == "ici"
    vmax = 0.5 if is_ici else 0.1
    if metric.lower() in self._SCALE_DEPENDENT_METRICS:
        # Errors in the units of the target: no fixed scale applies
        vmax = float(np.max(plot_data)) or 1.0
    percent = r" $\times$ 100" if is_ici else ""

    if is_ici:
        plot_data *= 100
        text_data *= 100

    colorbar_label = rf"|$\Delta$ {display_name}|" + percent
    title = style_kwargs.pop("title", f"Strata delta - {display_name}{percent}")
    row_labels = ["All strata", *list(strata)]

    # 3. Stateless Drawing Delegate
    with (
        plt.rc_context(self.theme.to_rc_params()),
    ):
        fig, ax = draw_strata_heatmap(
            plot_data=plot_data,
            text_data=text_data,
            row_labels=row_labels,
            col_labels=outcomes,
            colorbar_label=colorbar_label,
            vmax=vmax,
            title=title,
            **style_kwargs,
        )

    if save_val:
        self._save_figure(fig=fig, filename=f"{metric}_strata_heatmap")

    if show_val:
        plt.show()
    elif save_val:
        plt.close(fig.get_figure(root=True))

    return fig, ax

plot_all_heatmaps

plot_all_heatmaps(
    evaluations: dict[str, Any],
    metrics: list[str] | None = None,
    save: bool | None = None,
    show: bool | None = None,
    **style_kwargs: Any,
) -> dict[str, tuple[Figure | SubFigure, Axes]]

Generate subgroup delta heatmaps across outcomes for each evaluated metric.

Parameters:

Name	Type	Description	Default
`evaluations`	`dict of str to Any`	Nested evaluations dictionary mapping outcome keys to their overall and subgroup performance evaluation results.	required
`metrics`	`list of str`	List of metric names to render heatmaps for (e.g., ['auc', 'ici']). If None, inferred from the first outcome's overall metrics.	`None`
`save`	`bool`	Automatically save all generated heatmap figures to disk.	`None`
`show`	`bool`	Whether to display figures interactively before closing.	`None`
`**style_kwargs`	`Any`	Additional style parameters forwarded to `plot_strata_heatmap`.	`{}`

Returns:

Name	Type	Description
`heatmap_plots`	`dict of str to (Figure, Axes)`	Dictionary mapping metric names to their rendered (Figure, Axes) tuples.

Source code in medpipe/visualisation/displayer.py

def plot_all_heatmaps(
    self,
    evaluations: dict[str, Any],
    metrics: list[str] | None = None,
    save: bool | None = None,
    show: bool | None = None,
    **style_kwargs: Any,
) -> dict[str, tuple[Figure | SubFigure, Axes]]:
    """Generate subgroup delta heatmaps across outcomes for each evaluated metric.

    Parameters
    ----------
    evaluations : dict of str to Any
        Nested evaluations dictionary mapping outcome keys to their overall and
        subgroup performance evaluation results.
    metrics : list of str, optional
        List of metric names to render heatmaps for (e.g., ['auc', 'ici']).
        If None, inferred from the first outcome's overall metrics.
    save : bool, optional
        Automatically save all generated heatmap figures to disk.
    show : bool, optional
        Whether to display figures interactively before closing.
    **style_kwargs : Any
        Additional style parameters forwarded to `plot_strata_heatmap`.

    Returns
    -------
    heatmap_plots : dict of str to (Figure, Axes)
        Dictionary mapping metric names to their rendered (Figure, Axes) tuples.

    """
    outcomes = list(evaluations.keys())
    if not outcomes:
        return {}

    first_eval = evaluations[outcomes[0]]
    overall_dict = first_eval.get("overall", {})
    strata_dict = first_eval.get("strata", {})

    target_metrics = metrics or list(overall_dict.keys())

    # Flatten nested strata dict structure: stratum_variable -> category -> metric
    # Example row labels: "SEX: F", "SEX: M", "AGE: [18, 50]"
    strata_tuples: list[tuple[str, str]] = []
    strata_row_labels: list[str] = []

    for stratum_var, cat_dict in strata_dict.items():
        for cat_key in cat_dict:
            strata_tuples.append((stratum_var, cat_key))
            # Use helper to transform raw cat_key into clean label
            strata_row_labels.append(self._format_stratum_label(cat_key))

    if not strata_tuples:
        self.logger.warning(
            "No subgroup strata found in evaluation dict; skipping heatmaps."
        )
        return {}

    heatmap_plots: dict[str, tuple[Figure | SubFigure, Axes]] = {}

    for metric in target_metrics:
        # Look up MetricSpec display_name
        try:
            spec = MetricRegistry.get(metric)
            disp_name = (
                getattr(spec, "display_name", None)
                or metric.replace("_", " ").upper()
            )
        except Exception:
            disp_name = metric.replace("_", " ").upper()

        self.logger.info(
            f"--- Starting heatmap plotting for metric: {disp_name} ---"
        )
        # Extract unstratified baseline point estimates across outcomes
        scores_list = []
        for out in outcomes:
            entry = evaluations[out].get("overall", {}).get(metric, {})
            val = (
                entry.get("point_estimate", np.nan)
                if isinstance(entry, dict)
                else entry
            )
            scores_list.append(val)
        scores = np.array(scores_list)

        # Extract stratum point estimates matrix (shape: n_strata_rows, n_outcomes)
        strata_scores_list: list[list[float]] = []
        for stratum_var, cat_key in strata_tuples:
            row = []
            for out in outcomes:
                entry = (
                    evaluations[out]
                    .get("strata", {})
                    .get(stratum_var, {})
                    .get(cat_key, {})
                    .get(metric, {})
                )
                val = (
                    entry.get("point_estimate", np.nan)
                    if isinstance(entry, dict)
                    else entry
                )
                row.append(val)
            strata_scores_list.append(row)

        strata_scores = np.array(strata_scores_list)

        # Render heatmap for current metric
        heatmap_plots[metric] = self.plot_strata_heatmap(
            outcomes=outcomes,
            metric=metric,
            strata=strata_row_labels,
            scores=scores,
            strata_scores=strata_scores,
            save=save,
            show=show,
            **style_kwargs.copy(),
        )

        self.logger.info(
            f"--- Finished heatmap plotting for metric: {disp_name} ---"
        )
    return heatmap_plots

MedpipeClassifierDisplayer

Bases: BaseDisplayer

High-level visualisation and display manager for MedpipeClassifier pipeline runs.

This class handles statistical calculations (such as bootstrap confidence intervals and calibration metrics), applies theme aesthetics, delegates rendering to stateless drawing functions, and manages artifact persistence.

Parameters:

Name	Type	Description	Default
`orchestrator`	`MedpipeOrchestrator`	Active pipeline orchestrator instance containing execution context and run directory.	required
`theme`	`MedpipeTheme`	Aesthetic theme configuration. If None, defaults to `MedpipeTheme()`.	`None`

Attributes:

Name	Type	Description
`orchestrator`	`MedpipeOrchestrator`	Associated pipeline orchestrator instance.
`run_dir`	`Path`	Path to the output directory for storing generated figures.
`theme`	`MedpipeTheme`	Active visual theme specification.
`logger`	`Logger`	Console logger instance for displayer operations.

Methods:

Name	Description
`plot_roc_curve`
`n_bootstraps=None, save=None, show=None, **style_kwargs)`	Compute ROC statistics, render curve with optional bootstrap CIs, and save output.
`plot_precision_recall_curve`
`label=None, n_bootstraps=None, save=None, show=None, **style_kwargs)`	Compute PR statistics, render curve with optional bootstrap CIs, and save output.
`plot_data_distribution`
`label=None, xlabel=None, save=None, show=None, **style_kwargs)`	Render predicted probability distribution histogram and save output.
`plot_reliability_diagram`
`strategy=None, label=None, n_bootstraps=None, save=None,`
`show=False, **style_kwargs)`	Compute calibration metrics (binned or spline), render reliability diagram with optional CIs, and save output.
`plot_strata_heatmap`
`save=None, show=None, **style_kwargs)`	Validate subgroup inputs, compute delta matrix, render strata heatmap, and save output.
`plot_dca_curve`
`label=None, save=None, show=None, **style_kwargs)`	Compute Net Benefit across decision thresholds, render DCA plot, and save output.
`plot_all_heatmaps`	Generate subgroup delta heatmaps across outcomes for each evaluated metric.
`plot_all`
`show=None, **style_kwargs)`	Execute all core model evaluation visualization routines (ROC, PR, distribution, reliability, DCA) for a given outcome.

Source code in medpipe/visualisation/displayer.py

class MedpipeClassifierDisplayer(BaseDisplayer):
    """High-level visualisation and display manager for MedpipeClassifier pipeline runs.

    This class handles statistical calculations (such as bootstrap confidence intervals
    and calibration metrics), applies theme aesthetics, delegates rendering to stateless
    drawing functions, and manages artifact persistence.

    Parameters
    ----------
    orchestrator : MedpipeOrchestrator
        Active pipeline orchestrator instance containing execution context and
        run directory.
    theme : MedpipeTheme, optional
        Aesthetic theme configuration. If None, defaults to `MedpipeTheme()`.

    Attributes
    ----------
    orchestrator : MedpipeOrchestrator
        Associated pipeline orchestrator instance.
    run_dir : Path
        Path to the output directory for storing generated figures.
    theme : MedpipeTheme
        Active visual theme specification.
    logger : logging.Logger
        Console logger instance for displayer operations.

    Methods
    -------
    plot_roc_curve(y_true, probas, outcome="default", label=None,
    n_bootstraps=None, save=None, show=None, **style_kwargs)
        Compute ROC statistics, render curve with optional bootstrap CIs,
        and save output.
    plot_precision_recall_curve(y_true, probas, outcome="default",
    label=None, n_bootstraps=None, save=None, show=None, **style_kwargs)
        Compute PR statistics, render curve with optional bootstrap CIs,
        and save output.
    plot_data_distribution(data, outcome="default", n_bins=None, yscale=None,
    label=None, xlabel=None, save=None, show=None, **style_kwargs)
        Render predicted probability distribution histogram and save output.
    plot_reliability_diagram(y_true, probas, outcome="default", n_bins=None,
    strategy=None, label=None, n_bootstraps=None, save=None,
    show=False, **style_kwargs)
        Compute calibration metrics (binned or spline), render reliability
        diagram with optional CIs, and save output.
    plot_strata_heatmap(outcomes, metric, strata, scores, strata_scores,
    save=None, show=None, **style_kwargs)
        Validate subgroup inputs, compute delta matrix, render strata heatmap,
        and save output.
    plot_dca_curve(y_true, probas, outcome="default", thresholds=None,
    label=None, save=None, show=None, **style_kwargs)
        Compute Net Benefit across decision thresholds, render DCA plot,
        and save output.
    plot_all_heatmaps(evaluations, metrics=None, save=None, show=None, **style_kwargs)
        Generate subgroup delta heatmaps across outcomes for each evaluated metric.
    plot_all(y_true, probas, outcome="default", n_bootstraps=None, save=None,
    show=None, **style_kwargs)
        Execute all core model evaluation visualization routines
        (ROC, PR, distribution, reliability, DCA) for a given outcome.
    """

    _PLOT_TYPE_ALIASES: ClassVar[dict[str, str]] = {
        **BaseDisplayer._PLOT_TYPE_ALIASES,
        "calibration": "reliability",
        "reliability_diagram": "reliability",
        "pr": "precision_recall",
        "pr_curve": "precision_recall",
        "roc_curve": "roc",
        "distribution": "data_distribution",
        "dist": "data_distribution",
        "dca_curve": "dca",
    }
    _FALLBACK_DISPLAY_DEFAULTS: ClassVar[dict[str, Any]] = {
        **BaseDisplayer._FALLBACK_DISPLAY_DEFAULTS,
        "n_bins": 10,
        "dist_n_bins": 10,
        "dist_yscale": "linear",
        "strategy": "uniform",
        "cv_splines": 3,
    }

    def _compute_roc_data(
        self,
        y_true: np.ndarray,
        probas: np.ndarray,
        n_bootstraps: int = 1000,
        random_state: int | None = 42,
        n_jobs: int | None = 1,
    ) -> tuple[np.ndarray, np.ndarray, float, np.ndarray | None, np.ndarray | None]:
        """Compute Receiver Operating Characteristic metrics and bootstrap CIs.

        Parameters
        ----------
        y_true : np.ndarray
            Ground truth binary target labels of shape (n_samples,).
        probas : np.ndarray
            Predicted probabilities of shape (n_samples, 2) or (n_samples,).
        n_bootstraps : int, default=1000
            Number of bootstrap iterations for 95% confidence interval estimation.
        random_state : int, optional, default=42
            Random seed for bootstrap resampling reproducibility.

        Returns
        -------
        fpr : np.ndarray
            False positive rates across decision thresholds.
        tpr : np.ndarray
            True positive rates across decision thresholds.
        roc_auc : float
            Area Under the ROC Curve.
        lower_ci : np.ndarray or None
            Lower 2.5% percentile bound of TPR across bootstraps, if n_bootstraps > 0.
        upper_ci : np.ndarray or None
            Upper 97.5% percentile bound of TPR across bootstraps, if n_bootstraps > 0.

        """
        if probas.ndim == 2:
            probas = probas[:, 1]

        y_true = np.asarray(y_true).squeeze()

        fpr, tpr, _ = roc_curve(y_true, probas)
        roc_auc = float(auc(fpr, tpr))

        if n_bootstraps <= 0:
            return fpr, tpr, roc_auc, None, None

        rng = np.random.default_rng(random_state)
        bootstrap_indices = draw_bootstrap_indices(rng, len(y_true), n_bootstraps)

        # Threads: each resample is a millisecond-scale numpy sort that
        # releases the GIL, so worker processes only add start-up and
        # pickling cost (resamples lacking a class are dropped).
        boots = run_bootstraps(
            _roc_bootstrap_iteration,
            bootstrap_indices,
            y_true,
            probas,
            fpr,
            n_jobs=n_jobs,
            backend="threading",
        )

        if not boots:
            return fpr, tpr, roc_auc, None, None

        lower_ci = np.percentile(boots, 2.5, axis=0)
        upper_ci = np.percentile(boots, 97.5, axis=0)

        return fpr, tpr, roc_auc, lower_ci, upper_ci

    def _compute_precision_recall_data(
        self,
        y_true: np.ndarray,
        probas: np.ndarray,
        n_bootstraps: int = 1000,
        random_state: int | None = 42,
        n_jobs: int | None = 1,
    ) -> tuple[
        np.ndarray,
        np.ndarray,
        float,
        float,
        np.ndarray | None,
        np.ndarray | None,
    ]:
        """Compute Precision-Recall metrics, Average Precision, and bootstrap CIs.

        Parameters
        ----------
        y_true : np.ndarray
            Ground truth binary target labels of shape (n_samples,).
        probas : np.ndarray
            Predicted probabilities of shape (n_samples, 2) or (n_samples,).
        n_bootstraps : int, default=1000
            Number of bootstrap iterations for 95% confidence interval estimation.
        random_state : int, optional, default=42
            Random seed for bootstrap resampling reproducibility.

        Returns
        -------
        precision : np.ndarray
            Precision values across decision thresholds.
        recall : np.ndarray
            Recall values across decision thresholds.
        ap_score : float
            Average Precision (AP) score.
        baseline : float
            Prevalence / fraction of positive ground truth samples.
        lower_ci : np.ndarray or None
            Lower 2.5% percentile bound of precision across bootstraps, if
            n_bootstraps > 0.
        upper_ci : np.ndarray or None
            Upper 97.5% percentile bound of precision across bootstraps, if
            n_bootstraps > 0.

        """
        if probas.ndim == 2:
            probas = probas[:, 1]

        y_true = np.asarray(y_true).squeeze()

        precision, recall, _ = precision_recall_curve(y_true, probas)
        ap_score = float(average_precision_score(y_true, probas))
        baseline = float(np.mean(y_true))

        if n_bootstraps <= 0:
            return precision, recall, ap_score, baseline, None, None

        rng = np.random.default_rng(random_state)
        bootstrap_indices = draw_bootstrap_indices(rng, len(y_true), n_bootstraps)

        # Scikit-learn precision_recall_curve outputs recall in descending order
        rev_recall = recall[::-1]

        # Threads, for the same reason as in `_compute_roc_data`.
        boots = run_bootstraps(
            _pr_bootstrap_iteration,
            bootstrap_indices,
            y_true,
            probas,
            rev_recall,
            n_jobs=n_jobs,
            backend="threading",
        )

        if not boots:
            return precision, recall, ap_score, baseline, None, None

        lower_ci = np.percentile(boots, 2.5, axis=0)
        upper_ci = np.percentile(boots, 97.5, axis=0)

        return precision, recall, ap_score, baseline, lower_ci, upper_ci

    def _compute_reliability_data(
        self,
        y_true: np.ndarray,
        probas: np.ndarray,
        n_bins: int = 10,
        strategy: str = "uniform",
        n_bootstraps: int = 1000,
        random_state: int | None = 42,
        n_jobs: int | None = 1,
        cv_splines: int = 3,
    ) -> tuple[
        np.ndarray,
        np.ndarray,
        np.ndarray | None,
        np.ndarray | None,
    ]:
        """Compute calibration curve data (reliability diagram) and bootstrap CIs.

        Parameters
        ----------
        y_true : np.ndarray
            Ground truth binary target labels of shape (n_samples,).
        probas : np.ndarray
            Predicted probabilities of shape (n_samples, 2) or (n_samples,).
        n_bins : int, default=10
            Number of bins used for 'uniform' or 'quantile' binning strategies.
        strategy : {'uniform', 'quantile', 'spline'}, default='uniform'
            Calibration curve estimation strategy.
        n_bootstraps : int, default=1000
            Number of bootstrap iterations for 95% confidence interval estimation.
        random_state : int, optional, default=42
            Random seed for bootstrap resampling reproducibility.
        n_jobs : int or None, default=1
            Number of parallel jobs used to compute bootstrap resamples,
            each of which independently fits its own calibration curve
            (e.g. a fresh `SplineCalib` under `strategy='spline'`).
        cv_splines : int, default=3
            Number of internal cross-validation folds `SplineCalib` uses to
            select its regularization strength (only used when
            `strategy='spline'`); `SplineCalib`'s own default is 5.

        Returns
        -------
        prob_true : np.ndarray
            Fraction of positives or spline-calibrated probabilities.
        prob_pred : np.ndarray
            Mean predicted probabilities or evaluation grid points.
        lower_ci : np.ndarray or None
            Lower 2.5% percentile bound of calibration curve across bootstraps.
        upper_ci : np.ndarray or None
            Upper 97.5% percentile bound of calibration curve across bootstraps.

        """
        if probas.ndim == 2:
            probas = probas[:, 1]

        y_true = np.asarray(y_true).squeeze()

        if strategy == "spline":
            from pysplinecalib import SplineCalib

            sc = SplineCalib(cv_spline=cv_splines)
            sc.fit(probas, y_true)
            prob_pred = np.linspace(0.0, 1.0, 100)
            prob_true = sc.calibrate(prob_pred)

            assert prob_true is not None
            if prob_true.ndim == 2:
                prob_true = prob_true[:, 1]
        else:
            prob_true, prob_pred = calibration_curve(
                y_true, probas, n_bins=n_bins, strategy=strategy
            )

        if n_bootstraps <= 0 or len(prob_pred) == 0:
            return prob_true, prob_pred, None, None

        rng = np.random.default_rng(random_state)
        bootstrap_indices = draw_bootstrap_indices(rng, len(y_true), n_bootstraps)

        # Processes for the spline strategy: each resample's fit (a
        # SplineCalib fit via scipy's L-BFGS-B) spends its time in a
        # Python-level optimizer loop that holds the GIL, so threads add
        # contention instead of speedup. The binned strategies are cheap
        # numpy work, where threads avoid the process overhead.
        boots = run_bootstraps(
            _reliability_bootstrap_iteration,
            bootstrap_indices,
            y_true,
            probas,
            prob_pred,
            strategy,
            n_bins,
            cv_splines,
            n_jobs=n_jobs,
            backend="loky" if strategy == "spline" else "threading",
        )

        if not boots:
            return prob_true, prob_pred, None, None

        lower_ci = np.percentile(boots, 2.5, axis=0)
        upper_ci = np.percentile(boots, 97.5, axis=0)

        return prob_true, prob_pred, lower_ci, upper_ci

    def _compute_dca_data(
        self,
        y_true: np.ndarray,
        probas: np.ndarray,
        thresholds: np.ndarray | None = None,
    ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
        """Compute Net Benefit for Model, Treat All, and Treat None.

        Parameters
        ----------
        y_true : np.ndarray
            Ground truth binary target labels of shape (n_samples,).
        probas : np.ndarray
            Predicted probabilities of shape (n_samples, 2) or (n_samples,).
        thresholds : np.ndarray, optional
            Array of threshold probabilities. Defaults to `np.linspace(0.01, 0.99, 99)`.

        Returns
        -------
        thresholds : np.ndarray
            Evaluated threshold probabilities.
        net_benefit_model : np.ndarray
            Model Net Benefit across thresholds.
        net_benefit_all : np.ndarray
            Treat All Net Benefit across thresholds.
        """
        if probas.ndim == 2:
            probas = probas[:, 1]

        y_true = np.asarray(y_true).squeeze()
        n_samples = len(y_true)

        if thresholds is None:
            thresholds = np.linspace(0.01, 0.99, 99)

        positives = np.sum(y_true == 1)
        negatives = n_samples - positives

        # Calculate Treat All Net Benefit
        net_benefit_all = (positives / n_samples) - (negatives / n_samples) * (
            thresholds / (1.0 - thresholds)
        )

        # Calculate Model Net Benefit. Sorting each class's probabilities
        # once lets `searchsorted` count the predictions at or above every
        # threshold, without a pass over the samples per threshold.
        pos_probas = np.sort(probas[y_true == 1])
        neg_probas = np.sort(probas[y_true == 0])
        tp = len(pos_probas) - np.searchsorted(pos_probas, thresholds, side="left")
        fp = len(neg_probas) - np.searchsorted(neg_probas, thresholds, side="left")
        net_benefit_model = (tp / n_samples) - (fp / n_samples) * (
            thresholds / (1.0 - thresholds)
        )

        return thresholds, net_benefit_model, net_benefit_all

    # --- High-Level Plotting Methods ---

    def plot_roc_curve(
        self,
        y_true: np.ndarray,
        probas: np.ndarray,
        outcome: str = "default",
        label: str | None = None,
        n_bootstraps: int | None = None,
        save: bool | None = None,
        show: bool | None = None,
        n_jobs: int | None = None,
        **style_kwargs: Any,
    ) -> tuple[Figure | SubFigure, Axes]:
        """Compute ROC metrics, render curve with confidence intervals, and save figure.

        Parameters
        ----------
        y_true : np.ndarray
            Ground truth binary target labels of shape (n_samples,).
        probas : np.ndarray
            Predicted probabilities of shape (n_samples, 2) or (n_samples,).
        outcome : str, default="default"
            Outcome identifier used for figure titles and folder structuring.
        label : str, optional
            Legend label for the model. If None, defaults to 'Model (AUC = X.XX)'.
        n_bootstraps : int, optional
            Number of bootstrap iterations for confidence intervals. Set to 0
            to disable.
        save : bool, optional
            Automatically save the generated plot to the run directory.
        show : bool, optional
            Whether to display the plot interactively before closing.
        n_jobs : int, optional
            Number of parallel jobs used for the bootstrap resamples. Overrides
            the display configuration's `n_jobs` when given.
        **style_kwargs : Any
            Additional style parameters forwarded to `draw_roc_curve`.

        Returns
        -------
        fig : Figure | SubFigure
            Rendered Matplotlib figure object.
        ax : Axes
            Matplotlib axes containing the plotted elements.

        """
        cfg = self._resolve_plot_config(
            plot_type="roc",
            outcome=outcome,
            n_bootstraps=n_bootstraps,
            n_jobs=n_jobs,
            save=save,
            show=show,
            **style_kwargs,
        )

        n_bootstraps_val = cfg["n_bootstraps"]
        n_jobs_val = cfg["n_jobs"]
        save_val = cfg["save"]
        show_val = cfg["show"]

        self.logger.info(f"[{outcome}] Starting ROC curve plotting.")
        self.logger.debug(
            f"[{outcome}] Plotting ROC curve with "
            f"y: {y_true.shape} and {n_bootstraps_val} bootstrap iterations."
        )
        fpr, tpr, roc_auc, lower_ci, upper_ci = self._compute_roc_data(
            y_true=y_true,
            probas=probas,
            n_bootstraps=n_bootstraps_val,
            n_jobs=n_jobs_val,
        )

        display_label = label or f"Model (AUC = {roc_auc:.3f})"

        # Apply global theme context
        with (
            plt.rc_context(self.theme.to_rc_params()),
        ):
            fig, ax = draw_roc_curve(
                fpr=fpr,
                tpr=tpr,
                lower_ci=lower_ci,
                upper_ci=upper_ci,
                label=display_label,
                color=style_kwargs.pop("color", self.theme.primary_color),
                ci_alpha=style_kwargs.pop("ci_alpha", self.theme.ci_alpha),
                linewidth=style_kwargs.pop("linewidth", self.theme.linewidth),
                show_spines=style_kwargs.pop("show_spines", self.theme.show_spines),
                title=f"ROC Curve - {outcome.capitalize()}",
                **style_kwargs,
            )

        if save_val:
            self._save_figure(fig=fig, filename=f"{outcome}_roc_curve", outcome=outcome)

        if show_val:
            plt.show()
        elif save_val:
            plt.close(fig.get_figure(root=True))

        return fig, ax

    def plot_precision_recall_curve(
        self,
        y_true: np.ndarray,
        probas: np.ndarray,
        outcome: str = "default",
        label: str | None = None,
        n_bootstraps: int | None = None,
        save: bool | None = None,
        show: bool | None = None,
        n_jobs: int | None = None,
        **style_kwargs: Any,
    ) -> tuple[Figure | SubFigure, Axes]:
        """Compute PR metrics, render curve with confidence intervals, and save figure.

        Parameters
        ----------
        y_true : np.ndarray
            Ground truth binary target labels of shape (n_samples,).
        probas : np.ndarray
            Predicted probabilities of shape (n_samples, 2) or (n_samples,).
        outcome : str, default="default"
            Outcome identifier used for figure titles and folder structuring.
        label : str, optional
            Legend label for the model. If None, defaults to 'Model (AP = X.XX)'.
        n_bootstraps : int, optional
            Number of bootstrap iterations for confidence intervals. Set to 0
            to disable.
        save : bool, optional
            Automatically save the generated plot to the run directory.
        show : bool, optional
            Whether to display the plot interactively before closing.
        n_jobs : int, optional
            Number of parallel jobs used for the bootstrap resamples. Overrides
            the display configuration's `n_jobs` when given.
        **style_kwargs : Any
            Additional style parameters forwarded to `draw_precision_recall_curve`.

        Returns
        -------
        fig : Figure | SubFigure
            Rendered Matplotlib figure object.
        ax : Axes
            Matplotlib axes containing the plotted elements.

        """
        cfg = self._resolve_plot_config(
            plot_type="precision_recall",
            outcome=outcome,
            n_bootstraps=n_bootstraps,
            n_jobs=n_jobs,
            save=save,
            show=show,
            **style_kwargs,
        )

        n_bootstraps_val = cfg["n_bootstraps"]
        n_jobs_val = cfg["n_jobs"]
        save_val = cfg["save"]
        show_val = cfg["show"]

        self.logger.info(f"[{outcome}] Starting PR curve plotting.")
        self.logger.debug(
            f"[{outcome}] Plotting PR curve with "
            f"y: {y_true.shape} and {n_bootstraps_val} bootstrap iterations."
        )
        (
            precision,
            recall,
            ap_score,
            baseline,
            lower_ci,
            upper_ci,
        ) = self._compute_precision_recall_data(
            y_true=y_true,
            probas=probas,
            n_bootstraps=n_bootstraps_val,
            n_jobs=n_jobs_val,
        )

        display_label = label or f"Model (AP = {ap_score:.3f})"

        with (
            plt.rc_context(self.theme.to_rc_params()),
        ):
            fig, ax = draw_precision_recall_curve(
                precision=precision,
                recall=recall,
                lower_ci=lower_ci,
                upper_ci=upper_ci,
                baseline=baseline,
                label=display_label,
                color=style_kwargs.pop("color", self.theme.primary_color),
                ci_alpha=style_kwargs.pop("ci_alpha", self.theme.ci_alpha),
                linewidth=style_kwargs.pop("linewidth", self.theme.linewidth),
                show_spines=style_kwargs.pop("show_spines", self.theme.show_spines),
                title=f"Precision-Recall Curve - {outcome.capitalize()}",
                **style_kwargs,
            )

        if save_val:
            self._save_figure(fig=fig, filename=f"{outcome}_pr_curve", outcome=outcome)

        if show_val:
            plt.show()
        elif save_val:
            plt.close(fig.get_figure(root=True))

        return fig, ax

    def plot_reliability_diagram(
        self,
        y_true: np.ndarray,
        probas: np.ndarray,
        outcome: str = "default",
        n_bins: int | None = None,
        dist_n_bins: int | None = None,
        dist_yscale: str | None = None,
        strategy: str | None = None,
        label: str | None = None,
        n_bootstraps: int | None = None,
        save: bool | None = None,
        show: bool | None = None,
        n_jobs: int | None = None,
        **style_kwargs: Any,
    ) -> tuple[Figure | SubFigure, Axes]:
        """Compute calibration data, render a reliability diagram with a
        probability distribution subplot, and save figure.

        Parameters
        ----------
        y_true : numpy.ndarray
            Ground truth binary target labels of shape (n_samples,).
        probas : numpy.ndarray
            Predicted probabilities of shape (n_samples, 2) or (n_samples,).
        outcome : str, default="default"
            Outcome identifier used for figure titles and directory structuring.
        n_bins : int, optional
            Number of calibration bins (ignored if strategy='spline').
        dist_n_bins : int, optional
            Number of bins for the distribution.
        dist_yscale : str, optional
            Scale to use for the y-axis (e.g. linear, log, etc.)
        strategy : {'uniform', 'quantile', 'spline'}, optional
            Binning or smoothing strategy for calibration calculation.
        label : str, optional
            Legend label for the model curve. Defaults to 'Model'.
        n_bootstraps : int, optional
            Number of bootstrap iterations for confidence intervals. Set to 0
            to disable.
        save : bool, optional
            Automatically save the generated plot to the run directory.
        show : bool, optional
            Whether to display the plot interactively before closing.
        n_jobs : int, optional
            Number of parallel jobs used for the bootstrap resamples. Overrides
            the display configuration's `n_jobs` when given.
        **style_kwargs : Any
            Additional style parameters forwarded to `draw_reliability_diagram`.

        Returns
        -------
        fig : matplotlib.figure.Figure or matplotlib.figure.SubFigure
            Rendered Matplotlib figure object.
        ax : matplotlib.axes.Axes
            Matplotlib axes containing the main reliability diagram.

        """
        cfg = self._resolve_plot_config(
            plot_type="reliability",
            outcome=outcome,
            n_bins=n_bins,
            dist_n_bins=dist_n_bins,
            dist_yscale=dist_yscale,
            strategy=strategy,
            n_bootstraps=n_bootstraps,
            n_jobs=n_jobs,
            save=save,
            show=show,
            **style_kwargs,
        )

        n_bins_val = cfg["n_bins"]
        strategy_val = cfg["strategy"]
        n_bootstraps_val = cfg["n_bootstraps"]
        n_jobs_val = cfg["n_jobs"]
        cv_splines_val = cfg["cv_splines"]
        dist_yscale_val = cfg["dist_yscale"]
        dist_n_bins_val = cfg["dist_n_bins"]
        save_val = cfg["save"]
        show_val = cfg["show"]

        self.logger.info(f"[{outcome}] Starting reliability diagram plotting.")
        self.logger.debug(
            f"[{outcome}] Plotting reliability diagram with "
            f"y: {y_true.shape}, {n_bootstraps_val} bootstrap iterations, "
            f"{n_bins_val} bins, {strategy_val} strategy, "
            f"{n_jobs_val} parallel job(s), and {cv_splines_val} spline CV folds."
        )
        prob_true, prob_pred, lower_ci, upper_ci = self._compute_reliability_data(
            y_true=y_true,
            probas=probas,
            n_bins=n_bins_val,
            strategy=strategy_val,
            n_bootstraps=n_bootstraps_val,
            n_jobs=n_jobs_val,
            cv_splines=cv_splines_val,
        )

        display_label = label or "Model"

        # Suppress scatter points for smooth continuous spline curves
        if strategy_val == "spline":
            style_kwargs.setdefault("marker", None)

        with (
            plt.rc_context(self.theme.to_rc_params()),
        ):
            fig, ax = draw_reliability_diagram(
                prob_true=prob_true,
                prob_pred=prob_pred,
                probas=probas,  # Pass raw probabilities for bottom histogram
                dist_yscale=dist_yscale_val,
                dist_n_bins=dist_n_bins_val,
                lower_ci=lower_ci,
                upper_ci=upper_ci,
                label=display_label,
                color=style_kwargs.pop("color", self.theme.primary_color),
                ci_alpha=style_kwargs.pop("ci_alpha", self.theme.ci_alpha),
                linewidth=style_kwargs.pop("linewidth", self.theme.linewidth),
                show_spines=style_kwargs.pop("show_spines", self.theme.show_spines),
                title=f"Reliability Diagram - {outcome.capitalize()}",
                **style_kwargs,
            )

        if save_val:
            self._save_figure(
                fig=fig, filename=f"{outcome}_reliability_diagram", outcome=outcome
            )

        if show_val:
            plt.show()
        elif save_val:
            plt.close(fig.get_figure(root=True))

        return fig, ax

    def plot_dca_curve(
        self,
        y_true: np.ndarray,
        probas: np.ndarray,
        outcome: str = "default",
        thresholds: np.ndarray | None = None,
        label: str | None = None,
        save: bool | None = None,
        show: bool | None = None,
        **style_kwargs: Any,
    ) -> tuple[Figure | SubFigure, Axes]:
        """Compute Decision Curve Analysis metrics, render plot, and save
        figure artifact.

        Parameters
        ----------
        y_true : np.ndarray
            Ground truth binary target labels of shape (n_samples,).
        probas : np.ndarray
            Predicted probabilities of shape (n_samples, 2) or (n_samples,).
        outcome : str, default="default"
            Outcome identifier used for figure titles and directory structuring.
        thresholds : np.ndarray, optional
            Array of threshold probabilities.
        label : str, optional
            Legend label for the model curve. Defaults to 'Model'.
        save : bool, optional
            Automatically save the generated plot to the run directory.
        show : bool, optional
            Whether to display the plot interactively before closing.
        **style_kwargs : Any
            Additional style parameters forwarded to `draw_dca_curve`.

        Returns
        -------
        fig : Figure | SubFigure
            Rendered Matplotlib figure object.
        ax : Axes
            Matplotlib axes containing the DCA plot.

        """
        cfg = self._resolve_plot_config(
            plot_type="dca",
            save=save,
            show=show,
            **style_kwargs,
        )
        save_val = cfg["save"]
        show_val = cfg["show"]

        self.logger.info(f"[{outcome}] Starting DCA graph plotting.")
        self.logger.debug(f"[{outcome}] Plotting DCA graph with y: {y_true.shape}.")
        thresh, nb_model, nb_all = self._compute_dca_data(
            y_true=y_true,
            probas=probas,
            thresholds=thresholds,
        )

        display_label = label or "Model"

        with (
            plt.rc_context(self.theme.to_rc_params()),
        ):
            fig, ax = draw_dca_curve(
                thresholds=thresh,
                net_benefit_model=nb_model,
                net_benefit_all=nb_all,
                label=display_label,
                color=style_kwargs.pop("color", self.theme.primary_color),
                linewidth=style_kwargs.pop("linewidth", self.theme.linewidth),
                show_spines=style_kwargs.pop("show_spines", self.theme.show_spines),
                title=f"Decision Curve Analysis - {outcome.capitalize()}",
                **style_kwargs,
            )

        if save_val:
            self._save_figure(fig=fig, filename=f"{outcome}_dca_curve", outcome=outcome)

        if show_val:
            plt.show()
        elif save_val:
            plt.close(fig.get_figure(root=True))

        return fig, ax

    def plot_all(
        self,
        y_true: np.ndarray,
        probas: np.ndarray,
        outcome: str = "default",
        n_bootstraps: int | None = None,
        save: bool | None = None,
        show: bool | None = None,
        n_jobs: int | None = None,
        **style_kwargs: Any,
    ) -> dict[str, tuple[Figure | SubFigure, Axes]]:
        """Execute all core evaluation visualization routines for a given outcome.

        Generates and optionally persists the ROC curve, Precision-Recall curve,
        Probability Distribution histogram, Reliability Diagram, and Decision
        Curve Analysis (DCA).

        Parameters
        ----------
        y_true : np.ndarray
            Ground truth binary target labels of shape (n_samples,).
        probas : np.ndarray
            Predicted probabilities of shape (n_samples, 2) or (n_samples,).
        outcome : str, default="default"
            Outcome identifier used for figure titles and output folder structuring.
        n_bootstraps : int, optional
            Number of bootstrap iterations for ROC, PR, and reliability curves.
        save : bool, optional
            Automatically save all generated plot artifacts to the run directory.
        show : bool, optional
            Whether to display figures interactively before closing.
        n_jobs : int, optional
            Number of parallel jobs used for the bootstrap resamples. Overrides
            the display configuration's `n_jobs` when given.
        **style_kwargs : Any
            Additional style parameters forwarded to underlying drawing functions.

        Returns
        -------
        Dict[str, Tuple[Figure | SubFigure, Axes]]
            Dictionary mapping plot identifiers ('roc', 'pr', 'distribution',
            'reliability', 'dca') to their rendered (Figure, Axes) tuples.

        """
        plots: dict[str, tuple[Figure | SubFigure, Axes]] = {}

        self.logger.info(f"--- Starting graphical display for outcome: {outcome} ---")

        # Pass copies of style_kwargs to prevent parameter mutation across calls
        plots["roc"] = self.plot_roc_curve(
            y_true=y_true,
            probas=probas,
            outcome=outcome,
            n_bootstraps=n_bootstraps,
            n_jobs=n_jobs,
            save=save,
            show=show,
            **style_kwargs.copy(),
        )

        plots["pr"] = self.plot_precision_recall_curve(
            y_true=y_true,
            probas=probas,
            outcome=outcome,
            n_bootstraps=n_bootstraps,
            n_jobs=n_jobs,
            save=save,
            show=show,
            **style_kwargs.copy(),
        )

        plots["distribution"] = self.plot_data_distribution(
            data=probas,
            outcome=outcome,
            save=save,
            show=show,
            **style_kwargs.copy(),
        )

        plots["reliability"] = self.plot_reliability_diagram(
            y_true=y_true,
            probas=probas,
            outcome=outcome,
            n_bootstraps=n_bootstraps,
            n_jobs=n_jobs,
            save=save,
            show=show,
            **style_kwargs.copy(),
        )

        plots["dca"] = self.plot_dca_curve(
            y_true=y_true,
            probas=probas,
            outcome=outcome,
            save=save,
            show=show,
            **style_kwargs.copy(),
        )

        self.logger.info(f"--- Finished graphical display for outcome: {outcome} ---")
        return plots

plot_roc_curve

plot_roc_curve(
    y_true: ndarray,
    probas: ndarray,
    outcome: str = "default",
    label: str | None = None,
    n_bootstraps: int | None = None,
    save: bool | None = None,
    show: bool | None = None,
    n_jobs: int | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Compute ROC metrics, render curve with confidence intervals, and save figure.

Parameters:

Name	Type	Description	Default
`y_true`	`ndarray`	Ground truth binary target labels of shape (n_samples,).	required
`probas`	`ndarray`	Predicted probabilities of shape (n_samples, 2) or (n_samples,).	required
`outcome`	`str`	Outcome identifier used for figure titles and folder structuring.	`"default"`
`label`	`str`	Legend label for the model. If None, defaults to 'Model (AUC = X.XX)'.	`None`
`n_bootstraps`	`int`	Number of bootstrap iterations for confidence intervals. Set to 0 to disable.	`None`
`save`	`bool`	Automatically save the generated plot to the run directory.	`None`
`show`	`bool`	Whether to display the plot interactively before closing.	`None`
`n_jobs`	`int`	Number of parallel jobs used for the bootstrap resamples. Overrides the display configuration's `n_jobs` when given.	`None`
`**style_kwargs`	`Any`	Additional style parameters forwarded to `draw_roc_curve`.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure \| SubFigure`	Rendered Matplotlib figure object.
`ax`	`Axes`	Matplotlib axes containing the plotted elements.

Source code in medpipe/visualisation/displayer.py

def plot_roc_curve(
    self,
    y_true: np.ndarray,
    probas: np.ndarray,
    outcome: str = "default",
    label: str | None = None,
    n_bootstraps: int | None = None,
    save: bool | None = None,
    show: bool | None = None,
    n_jobs: int | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Compute ROC metrics, render curve with confidence intervals, and save figure.

    Parameters
    ----------
    y_true : np.ndarray
        Ground truth binary target labels of shape (n_samples,).
    probas : np.ndarray
        Predicted probabilities of shape (n_samples, 2) or (n_samples,).
    outcome : str, default="default"
        Outcome identifier used for figure titles and folder structuring.
    label : str, optional
        Legend label for the model. If None, defaults to 'Model (AUC = X.XX)'.
    n_bootstraps : int, optional
        Number of bootstrap iterations for confidence intervals. Set to 0
        to disable.
    save : bool, optional
        Automatically save the generated plot to the run directory.
    show : bool, optional
        Whether to display the plot interactively before closing.
    n_jobs : int, optional
        Number of parallel jobs used for the bootstrap resamples. Overrides
        the display configuration's `n_jobs` when given.
    **style_kwargs : Any
        Additional style parameters forwarded to `draw_roc_curve`.

    Returns
    -------
    fig : Figure | SubFigure
        Rendered Matplotlib figure object.
    ax : Axes
        Matplotlib axes containing the plotted elements.

    """
    cfg = self._resolve_plot_config(
        plot_type="roc",
        outcome=outcome,
        n_bootstraps=n_bootstraps,
        n_jobs=n_jobs,
        save=save,
        show=show,
        **style_kwargs,
    )

    n_bootstraps_val = cfg["n_bootstraps"]
    n_jobs_val = cfg["n_jobs"]
    save_val = cfg["save"]
    show_val = cfg["show"]

    self.logger.info(f"[{outcome}] Starting ROC curve plotting.")
    self.logger.debug(
        f"[{outcome}] Plotting ROC curve with "
        f"y: {y_true.shape} and {n_bootstraps_val} bootstrap iterations."
    )
    fpr, tpr, roc_auc, lower_ci, upper_ci = self._compute_roc_data(
        y_true=y_true,
        probas=probas,
        n_bootstraps=n_bootstraps_val,
        n_jobs=n_jobs_val,
    )

    display_label = label or f"Model (AUC = {roc_auc:.3f})"

    # Apply global theme context
    with (
        plt.rc_context(self.theme.to_rc_params()),
    ):
        fig, ax = draw_roc_curve(
            fpr=fpr,
            tpr=tpr,
            lower_ci=lower_ci,
            upper_ci=upper_ci,
            label=display_label,
            color=style_kwargs.pop("color", self.theme.primary_color),
            ci_alpha=style_kwargs.pop("ci_alpha", self.theme.ci_alpha),
            linewidth=style_kwargs.pop("linewidth", self.theme.linewidth),
            show_spines=style_kwargs.pop("show_spines", self.theme.show_spines),
            title=f"ROC Curve - {outcome.capitalize()}",
            **style_kwargs,
        )

    if save_val:
        self._save_figure(fig=fig, filename=f"{outcome}_roc_curve", outcome=outcome)

    if show_val:
        plt.show()
    elif save_val:
        plt.close(fig.get_figure(root=True))

    return fig, ax

plot_precision_recall_curve

plot_precision_recall_curve(
    y_true: ndarray,
    probas: ndarray,
    outcome: str = "default",
    label: str | None = None,
    n_bootstraps: int | None = None,
    save: bool | None = None,
    show: bool | None = None,
    n_jobs: int | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Compute PR metrics, render curve with confidence intervals, and save figure.

Parameters:

Name	Type	Description	Default
`y_true`	`ndarray`	Ground truth binary target labels of shape (n_samples,).	required
`probas`	`ndarray`	Predicted probabilities of shape (n_samples, 2) or (n_samples,).	required
`outcome`	`str`	Outcome identifier used for figure titles and folder structuring.	`"default"`
`label`	`str`	Legend label for the model. If None, defaults to 'Model (AP = X.XX)'.	`None`
`n_bootstraps`	`int`	Number of bootstrap iterations for confidence intervals. Set to 0 to disable.	`None`
`save`	`bool`	Automatically save the generated plot to the run directory.	`None`
`show`	`bool`	Whether to display the plot interactively before closing.	`None`
`n_jobs`	`int`	Number of parallel jobs used for the bootstrap resamples. Overrides the display configuration's `n_jobs` when given.	`None`
`**style_kwargs`	`Any`	Additional style parameters forwarded to `draw_precision_recall_curve`.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure \| SubFigure`	Rendered Matplotlib figure object.
`ax`	`Axes`	Matplotlib axes containing the plotted elements.

Source code in medpipe/visualisation/displayer.py

def plot_precision_recall_curve(
    self,
    y_true: np.ndarray,
    probas: np.ndarray,
    outcome: str = "default",
    label: str | None = None,
    n_bootstraps: int | None = None,
    save: bool | None = None,
    show: bool | None = None,
    n_jobs: int | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Compute PR metrics, render curve with confidence intervals, and save figure.

    Parameters
    ----------
    y_true : np.ndarray
        Ground truth binary target labels of shape (n_samples,).
    probas : np.ndarray
        Predicted probabilities of shape (n_samples, 2) or (n_samples,).
    outcome : str, default="default"
        Outcome identifier used for figure titles and folder structuring.
    label : str, optional
        Legend label for the model. If None, defaults to 'Model (AP = X.XX)'.
    n_bootstraps : int, optional
        Number of bootstrap iterations for confidence intervals. Set to 0
        to disable.
    save : bool, optional
        Automatically save the generated plot to the run directory.
    show : bool, optional
        Whether to display the plot interactively before closing.
    n_jobs : int, optional
        Number of parallel jobs used for the bootstrap resamples. Overrides
        the display configuration's `n_jobs` when given.
    **style_kwargs : Any
        Additional style parameters forwarded to `draw_precision_recall_curve`.

    Returns
    -------
    fig : Figure | SubFigure
        Rendered Matplotlib figure object.
    ax : Axes
        Matplotlib axes containing the plotted elements.

    """
    cfg = self._resolve_plot_config(
        plot_type="precision_recall",
        outcome=outcome,
        n_bootstraps=n_bootstraps,
        n_jobs=n_jobs,
        save=save,
        show=show,
        **style_kwargs,
    )

    n_bootstraps_val = cfg["n_bootstraps"]
    n_jobs_val = cfg["n_jobs"]
    save_val = cfg["save"]
    show_val = cfg["show"]

    self.logger.info(f"[{outcome}] Starting PR curve plotting.")
    self.logger.debug(
        f"[{outcome}] Plotting PR curve with "
        f"y: {y_true.shape} and {n_bootstraps_val} bootstrap iterations."
    )
    (
        precision,
        recall,
        ap_score,
        baseline,
        lower_ci,
        upper_ci,
    ) = self._compute_precision_recall_data(
        y_true=y_true,
        probas=probas,
        n_bootstraps=n_bootstraps_val,
        n_jobs=n_jobs_val,
    )

    display_label = label or f"Model (AP = {ap_score:.3f})"

    with (
        plt.rc_context(self.theme.to_rc_params()),
    ):
        fig, ax = draw_precision_recall_curve(
            precision=precision,
            recall=recall,
            lower_ci=lower_ci,
            upper_ci=upper_ci,
            baseline=baseline,
            label=display_label,
            color=style_kwargs.pop("color", self.theme.primary_color),
            ci_alpha=style_kwargs.pop("ci_alpha", self.theme.ci_alpha),
            linewidth=style_kwargs.pop("linewidth", self.theme.linewidth),
            show_spines=style_kwargs.pop("show_spines", self.theme.show_spines),
            title=f"Precision-Recall Curve - {outcome.capitalize()}",
            **style_kwargs,
        )

    if save_val:
        self._save_figure(fig=fig, filename=f"{outcome}_pr_curve", outcome=outcome)

    if show_val:
        plt.show()
    elif save_val:
        plt.close(fig.get_figure(root=True))

    return fig, ax

plot_reliability_diagram

plot_reliability_diagram(
    y_true: ndarray,
    probas: ndarray,
    outcome: str = "default",
    n_bins: int | None = None,
    dist_n_bins: int | None = None,
    dist_yscale: str | None = None,
    strategy: str | None = None,
    label: str | None = None,
    n_bootstraps: int | None = None,
    save: bool | None = None,
    show: bool | None = None,
    n_jobs: int | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Compute calibration data, render a reliability diagram with a probability distribution subplot, and save figure.

Parameters:

Name	Type	Description	Default
`y_true`	`ndarray`	Ground truth binary target labels of shape (n_samples,).	required
`probas`	`ndarray`	Predicted probabilities of shape (n_samples, 2) or (n_samples,).	required
`outcome`	`str`	Outcome identifier used for figure titles and directory structuring.	`"default"`
`n_bins`	`int`	Number of calibration bins (ignored if strategy='spline').	`None`
`dist_n_bins`	`int`	Number of bins for the distribution.	`None`
`dist_yscale`	`str`	Scale to use for the y-axis (e.g. linear, log, etc.)	`None`
`strategy`	`(uniform, quantile, spline)`	Binning or smoothing strategy for calibration calculation.	`'uniform'`
`label`	`str`	Legend label for the model curve. Defaults to 'Model'.	`None`
`n_bootstraps`	`int`	Number of bootstrap iterations for confidence intervals. Set to 0 to disable.	`None`
`save`	`bool`	Automatically save the generated plot to the run directory.	`None`
`show`	`bool`	Whether to display the plot interactively before closing.	`None`
`n_jobs`	`int`	Number of parallel jobs used for the bootstrap resamples. Overrides the display configuration's `n_jobs` when given.	`None`
`**style_kwargs`	`Any`	Additional style parameters forwarded to `draw_reliability_diagram`.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure or SubFigure`	Rendered Matplotlib figure object.
`ax`	`Axes`	Matplotlib axes containing the main reliability diagram.

Source code in medpipe/visualisation/displayer.py

def plot_reliability_diagram(
    self,
    y_true: np.ndarray,
    probas: np.ndarray,
    outcome: str = "default",
    n_bins: int | None = None,
    dist_n_bins: int | None = None,
    dist_yscale: str | None = None,
    strategy: str | None = None,
    label: str | None = None,
    n_bootstraps: int | None = None,
    save: bool | None = None,
    show: bool | None = None,
    n_jobs: int | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Compute calibration data, render a reliability diagram with a
    probability distribution subplot, and save figure.

    Parameters
    ----------
    y_true : numpy.ndarray
        Ground truth binary target labels of shape (n_samples,).
    probas : numpy.ndarray
        Predicted probabilities of shape (n_samples, 2) or (n_samples,).
    outcome : str, default="default"
        Outcome identifier used for figure titles and directory structuring.
    n_bins : int, optional
        Number of calibration bins (ignored if strategy='spline').
    dist_n_bins : int, optional
        Number of bins for the distribution.
    dist_yscale : str, optional
        Scale to use for the y-axis (e.g. linear, log, etc.)
    strategy : {'uniform', 'quantile', 'spline'}, optional
        Binning or smoothing strategy for calibration calculation.
    label : str, optional
        Legend label for the model curve. Defaults to 'Model'.
    n_bootstraps : int, optional
        Number of bootstrap iterations for confidence intervals. Set to 0
        to disable.
    save : bool, optional
        Automatically save the generated plot to the run directory.
    show : bool, optional
        Whether to display the plot interactively before closing.
    n_jobs : int, optional
        Number of parallel jobs used for the bootstrap resamples. Overrides
        the display configuration's `n_jobs` when given.
    **style_kwargs : Any
        Additional style parameters forwarded to `draw_reliability_diagram`.

    Returns
    -------
    fig : matplotlib.figure.Figure or matplotlib.figure.SubFigure
        Rendered Matplotlib figure object.
    ax : matplotlib.axes.Axes
        Matplotlib axes containing the main reliability diagram.

    """
    cfg = self._resolve_plot_config(
        plot_type="reliability",
        outcome=outcome,
        n_bins=n_bins,
        dist_n_bins=dist_n_bins,
        dist_yscale=dist_yscale,
        strategy=strategy,
        n_bootstraps=n_bootstraps,
        n_jobs=n_jobs,
        save=save,
        show=show,
        **style_kwargs,
    )

    n_bins_val = cfg["n_bins"]
    strategy_val = cfg["strategy"]
    n_bootstraps_val = cfg["n_bootstraps"]
    n_jobs_val = cfg["n_jobs"]
    cv_splines_val = cfg["cv_splines"]
    dist_yscale_val = cfg["dist_yscale"]
    dist_n_bins_val = cfg["dist_n_bins"]
    save_val = cfg["save"]
    show_val = cfg["show"]

    self.logger.info(f"[{outcome}] Starting reliability diagram plotting.")
    self.logger.debug(
        f"[{outcome}] Plotting reliability diagram with "
        f"y: {y_true.shape}, {n_bootstraps_val} bootstrap iterations, "
        f"{n_bins_val} bins, {strategy_val} strategy, "
        f"{n_jobs_val} parallel job(s), and {cv_splines_val} spline CV folds."
    )
    prob_true, prob_pred, lower_ci, upper_ci = self._compute_reliability_data(
        y_true=y_true,
        probas=probas,
        n_bins=n_bins_val,
        strategy=strategy_val,
        n_bootstraps=n_bootstraps_val,
        n_jobs=n_jobs_val,
        cv_splines=cv_splines_val,
    )

    display_label = label or "Model"

    # Suppress scatter points for smooth continuous spline curves
    if strategy_val == "spline":
        style_kwargs.setdefault("marker", None)

    with (
        plt.rc_context(self.theme.to_rc_params()),
    ):
        fig, ax = draw_reliability_diagram(
            prob_true=prob_true,
            prob_pred=prob_pred,
            probas=probas,  # Pass raw probabilities for bottom histogram
            dist_yscale=dist_yscale_val,
            dist_n_bins=dist_n_bins_val,
            lower_ci=lower_ci,
            upper_ci=upper_ci,
            label=display_label,
            color=style_kwargs.pop("color", self.theme.primary_color),
            ci_alpha=style_kwargs.pop("ci_alpha", self.theme.ci_alpha),
            linewidth=style_kwargs.pop("linewidth", self.theme.linewidth),
            show_spines=style_kwargs.pop("show_spines", self.theme.show_spines),
            title=f"Reliability Diagram - {outcome.capitalize()}",
            **style_kwargs,
        )

    if save_val:
        self._save_figure(
            fig=fig, filename=f"{outcome}_reliability_diagram", outcome=outcome
        )

    if show_val:
        plt.show()
    elif save_val:
        plt.close(fig.get_figure(root=True))

    return fig, ax

plot_dca_curve

plot_dca_curve(
    y_true: ndarray,
    probas: ndarray,
    outcome: str = "default",
    thresholds: ndarray | None = None,
    label: str | None = None,
    save: bool | None = None,
    show: bool | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Compute Decision Curve Analysis metrics, render plot, and save figure artifact.

Parameters:

Name	Type	Description	Default
`y_true`	`ndarray`	Ground truth binary target labels of shape (n_samples,).	required
`probas`	`ndarray`	Predicted probabilities of shape (n_samples, 2) or (n_samples,).	required
`outcome`	`str`	Outcome identifier used for figure titles and directory structuring.	`"default"`
`thresholds`	`ndarray`	Array of threshold probabilities.	`None`
`label`	`str`	Legend label for the model curve. Defaults to 'Model'.	`None`
`save`	`bool`	Automatically save the generated plot to the run directory.	`None`
`show`	`bool`	Whether to display the plot interactively before closing.	`None`
`**style_kwargs`	`Any`	Additional style parameters forwarded to `draw_dca_curve`.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure \| SubFigure`	Rendered Matplotlib figure object.
`ax`	`Axes`	Matplotlib axes containing the DCA plot.

Source code in medpipe/visualisation/displayer.py

def plot_dca_curve(
    self,
    y_true: np.ndarray,
    probas: np.ndarray,
    outcome: str = "default",
    thresholds: np.ndarray | None = None,
    label: str | None = None,
    save: bool | None = None,
    show: bool | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Compute Decision Curve Analysis metrics, render plot, and save
    figure artifact.

    Parameters
    ----------
    y_true : np.ndarray
        Ground truth binary target labels of shape (n_samples,).
    probas : np.ndarray
        Predicted probabilities of shape (n_samples, 2) or (n_samples,).
    outcome : str, default="default"
        Outcome identifier used for figure titles and directory structuring.
    thresholds : np.ndarray, optional
        Array of threshold probabilities.
    label : str, optional
        Legend label for the model curve. Defaults to 'Model'.
    save : bool, optional
        Automatically save the generated plot to the run directory.
    show : bool, optional
        Whether to display the plot interactively before closing.
    **style_kwargs : Any
        Additional style parameters forwarded to `draw_dca_curve`.

    Returns
    -------
    fig : Figure | SubFigure
        Rendered Matplotlib figure object.
    ax : Axes
        Matplotlib axes containing the DCA plot.

    """
    cfg = self._resolve_plot_config(
        plot_type="dca",
        save=save,
        show=show,
        **style_kwargs,
    )
    save_val = cfg["save"]
    show_val = cfg["show"]

    self.logger.info(f"[{outcome}] Starting DCA graph plotting.")
    self.logger.debug(f"[{outcome}] Plotting DCA graph with y: {y_true.shape}.")
    thresh, nb_model, nb_all = self._compute_dca_data(
        y_true=y_true,
        probas=probas,
        thresholds=thresholds,
    )

    display_label = label or "Model"

    with (
        plt.rc_context(self.theme.to_rc_params()),
    ):
        fig, ax = draw_dca_curve(
            thresholds=thresh,
            net_benefit_model=nb_model,
            net_benefit_all=nb_all,
            label=display_label,
            color=style_kwargs.pop("color", self.theme.primary_color),
            linewidth=style_kwargs.pop("linewidth", self.theme.linewidth),
            show_spines=style_kwargs.pop("show_spines", self.theme.show_spines),
            title=f"Decision Curve Analysis - {outcome.capitalize()}",
            **style_kwargs,
        )

    if save_val:
        self._save_figure(fig=fig, filename=f"{outcome}_dca_curve", outcome=outcome)

    if show_val:
        plt.show()
    elif save_val:
        plt.close(fig.get_figure(root=True))

    return fig, ax

plot_all

plot_all(
    y_true: ndarray,
    probas: ndarray,
    outcome: str = "default",
    n_bootstraps: int | None = None,
    save: bool | None = None,
    show: bool | None = None,
    n_jobs: int | None = None,
    **style_kwargs: Any,
) -> dict[str, tuple[Figure | SubFigure, Axes]]

Execute all core evaluation visualization routines for a given outcome.

Generates and optionally persists the ROC curve, Precision-Recall curve, Probability Distribution histogram, Reliability Diagram, and Decision Curve Analysis (DCA).

Parameters:

Name	Type	Description	Default
`y_true`	`ndarray`	Ground truth binary target labels of shape (n_samples,).	required
`probas`	`ndarray`	Predicted probabilities of shape (n_samples, 2) or (n_samples,).	required
`outcome`	`str`	Outcome identifier used for figure titles and output folder structuring.	`"default"`
`n_bootstraps`	`int`	Number of bootstrap iterations for ROC, PR, and reliability curves.	`None`
`save`	`bool`	Automatically save all generated plot artifacts to the run directory.	`None`
`show`	`bool`	Whether to display figures interactively before closing.	`None`
`n_jobs`	`int`	Number of parallel jobs used for the bootstrap resamples. Overrides the display configuration's `n_jobs` when given.	`None`
`**style_kwargs`	`Any`	Additional style parameters forwarded to underlying drawing functions.	`{}`

Returns:

Type	Description
`Dict[str, Tuple[Figure \| SubFigure, Axes]]`	Dictionary mapping plot identifiers ('roc', 'pr', 'distribution', 'reliability', 'dca') to their rendered (Figure, Axes) tuples.

Source code in medpipe/visualisation/displayer.py

def plot_all(
    self,
    y_true: np.ndarray,
    probas: np.ndarray,
    outcome: str = "default",
    n_bootstraps: int | None = None,
    save: bool | None = None,
    show: bool | None = None,
    n_jobs: int | None = None,
    **style_kwargs: Any,
) -> dict[str, tuple[Figure | SubFigure, Axes]]:
    """Execute all core evaluation visualization routines for a given outcome.

    Generates and optionally persists the ROC curve, Precision-Recall curve,
    Probability Distribution histogram, Reliability Diagram, and Decision
    Curve Analysis (DCA).

    Parameters
    ----------
    y_true : np.ndarray
        Ground truth binary target labels of shape (n_samples,).
    probas : np.ndarray
        Predicted probabilities of shape (n_samples, 2) or (n_samples,).
    outcome : str, default="default"
        Outcome identifier used for figure titles and output folder structuring.
    n_bootstraps : int, optional
        Number of bootstrap iterations for ROC, PR, and reliability curves.
    save : bool, optional
        Automatically save all generated plot artifacts to the run directory.
    show : bool, optional
        Whether to display figures interactively before closing.
    n_jobs : int, optional
        Number of parallel jobs used for the bootstrap resamples. Overrides
        the display configuration's `n_jobs` when given.
    **style_kwargs : Any
        Additional style parameters forwarded to underlying drawing functions.

    Returns
    -------
    Dict[str, Tuple[Figure | SubFigure, Axes]]
        Dictionary mapping plot identifiers ('roc', 'pr', 'distribution',
        'reliability', 'dca') to their rendered (Figure, Axes) tuples.

    """
    plots: dict[str, tuple[Figure | SubFigure, Axes]] = {}

    self.logger.info(f"--- Starting graphical display for outcome: {outcome} ---")

    # Pass copies of style_kwargs to prevent parameter mutation across calls
    plots["roc"] = self.plot_roc_curve(
        y_true=y_true,
        probas=probas,
        outcome=outcome,
        n_bootstraps=n_bootstraps,
        n_jobs=n_jobs,
        save=save,
        show=show,
        **style_kwargs.copy(),
    )

    plots["pr"] = self.plot_precision_recall_curve(
        y_true=y_true,
        probas=probas,
        outcome=outcome,
        n_bootstraps=n_bootstraps,
        n_jobs=n_jobs,
        save=save,
        show=show,
        **style_kwargs.copy(),
    )

    plots["distribution"] = self.plot_data_distribution(
        data=probas,
        outcome=outcome,
        save=save,
        show=show,
        **style_kwargs.copy(),
    )

    plots["reliability"] = self.plot_reliability_diagram(
        y_true=y_true,
        probas=probas,
        outcome=outcome,
        n_bootstraps=n_bootstraps,
        n_jobs=n_jobs,
        save=save,
        show=show,
        **style_kwargs.copy(),
    )

    plots["dca"] = self.plot_dca_curve(
        y_true=y_true,
        probas=probas,
        outcome=outcome,
        save=save,
        show=show,
        **style_kwargs.copy(),
    )

    self.logger.info(f"--- Finished graphical display for outcome: {outcome} ---")
    return plots

MedpipeRegressorDisplayer

Bases: BaseDisplayer

High-level visualisation and display manager for MedpipeRegressor pipeline runs.

Renders distributional diagnostic figures (coverage reliability, sharpness, Winkler score, marginal calibration, and PIT histograms), as well as a target-value data distribution histogram, for regression models that produce a predictive CDF via predict_dist. Coverage, sharpness, and Winkler score are bootstrapped for confidence intervals, mirroring MedpipeClassifierDisplayer's ROC/PR/reliability curves.

Currently only OrdBoost's ContinuousPredictiveDistribution is supported (a mapper is required for PIT histograms, e.g. the fitted OrdBoostRegressor's mapper_ attribute); NGBoost-wrapped distributions are not yet supported and will raise a clear error if passed to plot_pit_histogram.

Parameters:

Name	Type	Description	Default
`orchestrator`	`MedpipeOrchestrator`	Active pipeline orchestrator instance containing execution context and run directory.	required
`theme`	`MedpipeTheme`	Aesthetic theme configuration. If None, defaults to `MedpipeTheme()`.	`None`

Attributes:

Name	Type	Description
`orchestrator`	`MedpipeOrchestrator`	Associated pipeline orchestrator instance.
`run_dir`	`Path`	Path to the output directory for storing generated figures.
`theme`	`MedpipeTheme`	Active visual theme specification.
`logger`	`Logger`	Console logger instance for displayer operations.

Methods:

Name	Description
`plot_coverage`
`n_bootstraps=None, label=None, save=None, show=None, **style_kwargs)`	Compute empirical coverage across nominal coverage levels with bootstrap CIs, render curve, and save output.
`plot_sharpness`
`n_bootstraps=None, label=None, save=None, show=None, **style_kwargs)`	Compute mean interval width across nominal coverage levels with bootstrap CIs, render curve, and save output.
`plot_winkler`
`n_bootstraps=None, label=None, save=None, show=None, **style_kwargs)`	Compute Winkler score across nominal coverage levels with bootstrap CIs, render curve, and save output.
`plot_marginal_calibration`
`save=None, show=None, **style_kwargs)`	Compute marginal calibration curve, render plot, and save output.
`plot_pit_histogram`
`label=None, save=None, show=None, **style_kwargs)`	Compute PIT diagnostics, render histogram, and save output.
`plot_data_distribution`
`label=None, xlabel=None, save=None, show=None, **style_kwargs)`	Render a data distribution histogram and save output.
`plot_strata_heatmap`
`save=None, show=None, **style_kwargs)`	Validate subgroup inputs, compute delta matrix, render strata heatmap, and save output.
`plot_all_heatmaps`	Generate subgroup delta heatmaps across outcomes for each evaluated metric.
`plot_all`
`n_bootstraps=None, save=None, show=None, **style_kwargs)`	Execute all core distributional diagnostic visualization routines for a given outcome.

Source code in medpipe/visualisation/displayer.py

class MedpipeRegressorDisplayer(BaseDisplayer):
    """High-level visualisation and display manager for MedpipeRegressor pipeline runs.

    Renders distributional diagnostic figures (coverage reliability, sharpness,
    Winkler score, marginal calibration, and PIT histograms), as well as a
    target-value data distribution histogram, for regression models that
    produce a predictive CDF via `predict_dist`. Coverage, sharpness, and
    Winkler score are bootstrapped for confidence intervals, mirroring
    `MedpipeClassifierDisplayer`'s ROC/PR/reliability curves.

    Currently only OrdBoost's `ContinuousPredictiveDistribution` is
    supported (a `mapper` is required for PIT histograms, e.g. the fitted
    `OrdBoostRegressor`'s `mapper_` attribute); NGBoost-wrapped
    distributions are not yet supported and will raise a clear error if
    passed to `plot_pit_histogram`.

    Parameters
    ----------
    orchestrator : MedpipeOrchestrator
        Active pipeline orchestrator instance containing execution context and
        run directory.
    theme : MedpipeTheme, optional
        Aesthetic theme configuration. If None, defaults to `MedpipeTheme()`.

    Attributes
    ----------
    orchestrator : MedpipeOrchestrator
        Associated pipeline orchestrator instance.
    run_dir : Path
        Path to the output directory for storing generated figures.
    theme : MedpipeTheme
        Active visual theme specification.
    logger : logging.Logger
        Console logger instance for displayer operations.

    Methods
    -------
    plot_coverage(y_true, dist, outcome="default", coverage_levels=None,
    n_bootstraps=None, label=None, save=None, show=None, **style_kwargs)
        Compute empirical coverage across nominal coverage levels with
        bootstrap CIs, render curve, and save output.
    plot_sharpness(y_true, dist, outcome="default", coverage_levels=None,
    n_bootstraps=None, label=None, save=None, show=None, **style_kwargs)
        Compute mean interval width across nominal coverage levels with
        bootstrap CIs, render curve, and save output.
    plot_winkler(y_true, dist, outcome="default", coverage_levels=None,
    n_bootstraps=None, label=None, save=None, show=None, **style_kwargs)
        Compute Winkler score across nominal coverage levels with bootstrap
        CIs, render curve, and save output.
    plot_marginal_calibration(y_true, dist, outcome="default", label=None,
    save=None, show=None, **style_kwargs)
        Compute marginal calibration curve, render plot, and save output.
    plot_pit_histogram(y_true, dist, mapper, outcome="default", n_bins=None,
    label=None, save=None, show=None, **style_kwargs)
        Compute PIT diagnostics, render histogram, and save output.
    plot_data_distribution(data, outcome="default", n_bins=None, yscale=None,
    label=None, xlabel=None, save=None, show=None, **style_kwargs)
        Render a data distribution histogram and save output.
    plot_strata_heatmap(outcomes, metric, strata, scores, strata_scores,
    save=None, show=None, **style_kwargs)
        Validate subgroup inputs, compute delta matrix, render strata heatmap,
        and save output.
    plot_all_heatmaps(evaluations, metrics=None, save=None, show=None, **style_kwargs)
        Generate subgroup delta heatmaps across outcomes for each evaluated metric.
    plot_all(y_true, dist, mapper, outcome="default", coverage_levels=None,
    n_bootstraps=None, save=None, show=None, **style_kwargs)
        Execute all core distributional diagnostic visualization routines
        for a given outcome.

    """

    _PLOT_TYPE_ALIASES: ClassVar[dict[str, str]] = {
        **BaseDisplayer._PLOT_TYPE_ALIASES,
        "coverage_curve": "coverage",
        "sharpness_curve": "sharpness",
        "winkler_curve": "winkler",
        "winkler_score": "winkler",
        "marginal_calib": "marginal_calibration",
        "pit": "pit_histogram",
        "distribution": "data_distribution",
        "dist": "data_distribution",
    }
    _FALLBACK_DISPLAY_DEFAULTS: ClassVar[dict[str, Any]] = {
        **BaseDisplayer._FALLBACK_DISPLAY_DEFAULTS,
        "dist_n_bins": 20,
        "dist_yscale": "linear",
        "coverage_levels": list(range(5, 100, 10)),
        "pit_n_bins": 20,
    }

    def _compute_coverage_sharpness_winkler_data(
        self,
        y_true: np.ndarray,
        dist: ContinuousPredictiveDistribution,
        coverage_levels: np.ndarray,
        metric: Literal["coverage", "sharpness", "winkler"],
        n_bootstraps: int = 1000,
        random_state: int | None = 42,
        decimals: int | None = None,
        n_jobs: int | None = 1,
    ) -> dict[str, Any]:
        """Compute one of empirical coverage, sharpness, or Winkler score
        across nominal coverage levels, with bootstrap CIs.

        Parameters
        ----------
        y_true : np.ndarray
            Ground truth continuous target values of shape (n_samples,).
        dist : ContinuousPredictiveDistribution
            Predictive distribution for the same samples.
        coverage_levels : np.ndarray
            Nominal central-interval coverage levels in percent (e.g. 90 for
            a 90% interval).
        metric : {"coverage", "sharpness", "winkler"}
            Which single metric to compute.
        n_bootstraps : int, default=1000
            Number of bootstrap iterations for 95% confidence interval estimation.
        random_state : int, optional, default=42
            Random seed for bootstrap resampling reproducibility.
        decimals : int, optional
            Number of decimals the predictive interval bounds are rounded to
            before computing the metric. If None, no rounding is applied.
        n_jobs : int or None, default=1
            Number of parallel jobs used for the bootstrap resamples.

        Returns
        -------
        dict of str to Any
            `"coverage_levels"` (np.ndarray), and `"output"`, a dict with
            `"point"`, `"lower_ci"`, `"upper_ci"` (the latter two None when
            `n_bootstraps <= 0`) for the requested `metric`.

        """

        y_true_arr = np.asarray(y_true, dtype=float)
        coverage_levels_arr = np.asarray(coverage_levels, dtype=float)
        alphas = 1.0 - coverage_levels_arr / 100.0

        point = np.array(
            [
                _interval_metric_value(metric, y_true_arr, dist, alpha, decimals)
                for alpha in alphas
            ]
        )

        result: dict[str, Any] = {
            "coverage_levels": coverage_levels_arr,
            "output": {"point": point, "lower_ci": None, "upper_ci": None},
        }

        if n_bootstraps <= 0:
            return result

        rng = np.random.default_rng(random_state)
        bootstrap_indices = draw_bootstrap_indices(rng, len(y_true_arr), n_bootstraps)

        # Processes: each resample evaluates the predictive distribution's
        # intervals at every level, which is dominated by Python-level
        # overhead, so threads give no speedup. Row-indexing the
        # distribution inside the worker keeps the (memory-mapped) full CDF
        # matrix from being re-serialised per resample.
        boot = np.array(
            run_bootstraps(
                _interval_bootstrap_iteration,
                bootstrap_indices,
                y_true_arr,
                dist,
                alphas,
                metric,
                decimals,
                n_jobs=n_jobs,
                backend="loky",
            )
        )

        result["output"]["lower_ci"] = np.percentile(boot, 2.5, axis=0)
        result["output"]["upper_ci"] = np.percentile(boot, 97.5, axis=0)

        return result

    def _compute_marginal_calibration_data(
        self,
        y_true: np.ndarray,
        dist: ContinuousPredictiveDistribution,
        mapper: BaseBinMapper,
    ) -> tuple[np.ndarray, np.ndarray]:
        """Compute the marginal calibration curve for a predictive distribution.

        Parameters
        ----------
        y_true : np.ndarray
            Ground truth continuous target values of shape (n_samples,).
        dist : ContinuousPredictiveDistribution
            Predictive distribution for the same samples.
        mapper : BaseBinMapper
            Mapper used by the OrdBoostRegressor.

        Returns
        -------
        grid_y : np.ndarray
            Target-value grid points.
        diff : np.ndarray
            Empirical CDF minus mean predicted CDF at each grid point.

        """
        y_true_arr = np.asarray(y_true, dtype=float)
        grid_y, diff = marginal_calibration_curve(y_true_arr, dist, mapper)
        return grid_y, diff

    def _compute_pit_histogram_data(
        self,
        y_true: np.ndarray,
        dist: ContinuousPredictiveDistribution,
        mapper: BaseBinMapper | None,
        n_bins: int = 20,
    ) -> tuple[np.ndarray, np.ndarray, float]:
        """Compute PIT (Probability Integral Transform) histogram diagnostics.

        Parameters
        ----------
        y_true : np.ndarray
            Ground truth continuous target values of shape (n_samples,).
        dist : ContinuousPredictiveDistribution
            Predictive distribution for the same samples.
        mapper : BaseBinMapper or None
            The fitted OrdBoost model's bin mapper (e.g. its `mapper_`
            attribute), required to compute exact PIT diagnostics.
        n_bins : int, default=20
            Number of PIT histogram bins.

        Returns
        -------
        bin_centres : np.ndarray
            Bin centre positions in [0, 1].
        hist_values : np.ndarray
            Density values for each bin.
        alpha_score : float
            PIT alpha (uniformity) score.

        Raises
        ------
        ValueError
            If `mapper` is None, since NGBoost-wrapped distributions (which
            have no OrdBoost bin mapper) are not yet supported.

        """
        if mapper is None:
            raise ValueError(
                "A `mapper` (e.g. the fitted OrdBoostRegressor's `mapper_` "
                "attribute) is required to compute a PIT histogram. "
                "Distributions without an OrdBoost bin mapper (e.g. "
                "NGBoost-wrapped distributions) are not yet supported."
            )

        y_true_arr = np.asarray(y_true, dtype=float)
        pit = pit_diagnostics(y_true_arr, dist, mapper)
        alpha_score = float(np.asarray(pit.alpha_score()))
        hist = pit.hist_values(n_bins)
        bin_centres = np.asarray(hist["bin_centre"].values)
        hist_values = np.asarray(hist.values)

        return bin_centres, hist_values, alpha_score

    # --- High-Level Plotting Methods ---

    def plot_coverage(
        self,
        y_true: np.ndarray,
        dist: ContinuousPredictiveDistribution,
        outcome: str = "default",
        coverage_levels: np.ndarray | None = None,
        n_bootstraps: int | None = None,
        label: str | None = None,
        save: bool | None = None,
        show: bool | None = None,
        decimals: int | None = None,
        n_jobs: int | None = None,
        **style_kwargs: Any,
    ) -> tuple[Figure | SubFigure, Axes]:
        """Compute coverage reliability, render curve with confidence
        intervals, and save figure.

        Parameters
        ----------
        y_true : np.ndarray
            Ground truth continuous target values of shape (n_samples,).
        dist : ContinuousPredictiveDistribution
            Predictive distribution for the same samples.
        outcome : str, default="default"
            Outcome identifier used for figure titles and folder structuring.
        coverage_levels : np.ndarray, optional
            Nominal central-interval coverage levels in percent. Defaults to
            `np.arange(5, 100, 10)`.
        n_bootstraps : int, optional
            Number of bootstrap iterations for confidence intervals. Set to 0
            to disable.
        label : str, optional
            Legend label for the model. Defaults to 'Model'.
        save : bool, optional
            Automatically save the generated plot to the run directory.
        show : bool, optional
            Whether to display the plot interactively before closing.
        decimals : int, optional
            Number of decimals the predictive interval bounds are rounded to.
            If None, no rounding is applied.
        n_jobs : int, optional
            Number of parallel jobs used for the bootstrap resamples. Overrides
            the display configuration's `n_jobs` when given.
        **style_kwargs : Any
            Additional style parameters forwarded to `draw_coverage_curve`.

        Returns
        -------
        fig : Figure | SubFigure
            Rendered Matplotlib figure object.
        ax : Axes
            Matplotlib axes containing the plotted elements.

        """
        cfg = self._resolve_plot_config(
            plot_type="coverage",
            outcome=outcome,
            coverage_levels=coverage_levels,
            n_bootstraps=n_bootstraps,
            n_jobs=n_jobs,
            save=save,
            show=show,
            **style_kwargs,
        )
        n_bootstraps_val = cfg["n_bootstraps"]
        n_jobs_val = cfg["n_jobs"]
        save_val = cfg["save"]
        show_val = cfg["show"]
        levels = np.asarray(cfg["coverage_levels"])

        self.logger.info(f"[{outcome}] Starting coverage curve plotting.")
        data = self._compute_coverage_sharpness_winkler_data(
            y_true=y_true,
            dist=dist,
            coverage_levels=levels,
            metric="coverage",
            n_bootstraps=n_bootstraps_val,
            decimals=decimals,
            n_jobs=n_jobs_val,
        )

        display_label = label or "Model"

        with (
            plt.rc_context(self.theme.to_rc_params()),
        ):
            fig, ax = draw_coverage_curve(
                coverage_levels=data["coverage_levels"],
                empirical_coverage=data["output"]["point"],
                lower_ci=data["output"]["lower_ci"],
                upper_ci=data["output"]["upper_ci"],
                label=display_label,
                color=style_kwargs.pop("color", self.theme.primary_color),
                ci_alpha=style_kwargs.pop("ci_alpha", self.theme.ci_alpha),
                linewidth=style_kwargs.pop("linewidth", self.theme.linewidth),
                show_spines=style_kwargs.pop("show_spines", self.theme.show_spines),
                title=f"Coverage Reliability - {outcome.capitalize()}",
                **style_kwargs,
            )

        if save_val:
            self._save_figure(fig=fig, filename=f"{outcome}_coverage", outcome=outcome)

        if show_val:
            plt.show()
        elif save_val:
            plt.close(fig.get_figure(root=True))

        return fig, ax

    def plot_sharpness(
        self,
        y_true: np.ndarray,
        dist: ContinuousPredictiveDistribution,
        outcome: str = "default",
        coverage_levels: np.ndarray | None = None,
        n_bootstraps: int | None = None,
        label: str | None = None,
        save: bool | None = None,
        show: bool | None = None,
        decimals: int | None = None,
        n_jobs: int | None = None,
        **style_kwargs: Any,
    ) -> tuple[Figure | SubFigure, Axes]:
        """Compute sharpness, render curve with confidence intervals, and
        save figure.

        Parameters
        ----------
        y_true : np.ndarray
            Ground truth continuous target values of shape (n_samples,).
        dist : ContinuousPredictiveDistribution
            Predictive distribution for the same samples.
        outcome : str, default="default"
            Outcome identifier used for figure titles and folder structuring.
        coverage_levels : np.ndarray, optional
            Nominal central-interval coverage levels in percent. Defaults to
            `np.arange(5, 100, 10)`.
        n_bootstraps : int, optional
            Number of bootstrap iterations for confidence intervals. Set to 0
            to disable.
        label : str, optional
            Legend label for the model. Defaults to 'Model'.
        save : bool, optional
            Automatically save the generated plot to the run directory.
        show : bool, optional
            Whether to display the plot interactively before closing.
        decimals : int, optional
            Number of decimals the predictive interval bounds are rounded to.
            If None, no rounding is applied.
        n_jobs : int, optional
            Number of parallel jobs used for the bootstrap resamples. Overrides
            the display configuration's `n_jobs` when given.
        **style_kwargs : Any
            Additional style parameters forwarded to `draw_sharpness_curve`.

        Returns
        -------
        fig : Figure | SubFigure
            Rendered Matplotlib figure object.
        ax : Axes
            Matplotlib axes containing the plotted elements.

        """
        cfg = self._resolve_plot_config(
            plot_type="sharpness",
            outcome=outcome,
            coverage_levels=coverage_levels,
            n_bootstraps=n_bootstraps,
            n_jobs=n_jobs,
            save=save,
            show=show,
            **style_kwargs,
        )
        n_bootstraps_val = cfg["n_bootstraps"]
        n_jobs_val = cfg["n_jobs"]
        save_val = cfg["save"]
        show_val = cfg["show"]
        levels = np.asarray(cfg["coverage_levels"])

        self.logger.info(f"[{outcome}] Starting sharpness curve plotting.")
        data = self._compute_coverage_sharpness_winkler_data(
            y_true=y_true,
            dist=dist,
            coverage_levels=levels,
            metric="sharpness",
            n_bootstraps=n_bootstraps_val,
            decimals=decimals,
            n_jobs=n_jobs_val,
        )

        display_label = label or "Model"

        with (
            plt.rc_context(self.theme.to_rc_params()),
        ):
            fig, ax = draw_sharpness_curve(
                coverage_levels=data["coverage_levels"],
                sharpness_values=data["output"]["point"],
                lower_ci=data["output"]["lower_ci"],
                upper_ci=data["output"]["upper_ci"],
                label=display_label,
                color=style_kwargs.pop("color", self.theme.primary_color),
                ci_alpha=style_kwargs.pop("ci_alpha", self.theme.ci_alpha),
                linewidth=style_kwargs.pop("linewidth", self.theme.linewidth),
                show_spines=style_kwargs.pop("show_spines", self.theme.show_spines),
                title=f"Sharpness - {outcome.capitalize()}",
                **style_kwargs,
            )

        if save_val:
            self._save_figure(fig=fig, filename=f"{outcome}_sharpness", outcome=outcome)

        if show_val:
            plt.show()
        elif save_val:
            plt.close(fig.get_figure(root=True))

        return fig, ax

    def plot_winkler(
        self,
        y_true: np.ndarray,
        dist: ContinuousPredictiveDistribution,
        outcome: str = "default",
        coverage_levels: np.ndarray | None = None,
        n_bootstraps: int | None = None,
        label: str | None = None,
        save: bool | None = None,
        show: bool | None = None,
        decimals: int | None = None,
        n_jobs: int | None = None,
        **style_kwargs: Any,
    ) -> tuple[Figure | SubFigure, Axes]:
        """Compute Winkler score, render curve with confidence intervals,
        and save figure.

        Parameters
        ----------
        y_true : np.ndarray
            Ground truth continuous target values of shape (n_samples,).
        dist : ContinuousPredictiveDistribution
            Predictive distribution for the same samples.
        outcome : str, default="default"
            Outcome identifier used for figure titles and folder structuring.
        coverage_levels : np.ndarray, optional
            Nominal central-interval coverage levels in percent. Defaults to
            `np.arange(5, 100, 10)`.
        n_bootstraps : int, optional
            Number of bootstrap iterations for confidence intervals. Set to 0
            to disable.
        label : str, optional
            Legend label for the model. Defaults to 'Model'.
        save : bool, optional
            Automatically save the generated plot to the run directory.
        show : bool, optional
            Whether to display the plot interactively before closing.
        decimals : int, optional
            Number of decimals the predictive interval bounds are rounded to.
            If None, no rounding is applied.
        n_jobs : int, optional
            Number of parallel jobs used for the bootstrap resamples. Overrides
            the display configuration's `n_jobs` when given.
        **style_kwargs : Any
            Additional style parameters forwarded to `draw_winkler_curve`.

        Returns
        -------
        fig : Figure | SubFigure
            Rendered Matplotlib figure object.
        ax : Axes
            Matplotlib axes containing the plotted elements.

        """
        cfg = self._resolve_plot_config(
            plot_type="winkler",
            outcome=outcome,
            coverage_levels=coverage_levels,
            n_bootstraps=n_bootstraps,
            n_jobs=n_jobs,
            save=save,
            show=show,
            **style_kwargs,
        )
        n_bootstraps_val = cfg["n_bootstraps"]
        n_jobs_val = cfg["n_jobs"]
        save_val = cfg["save"]
        show_val = cfg["show"]
        levels = np.asarray(cfg["coverage_levels"])

        self.logger.info(f"[{outcome}] Starting Winkler score curve plotting.")
        data = self._compute_coverage_sharpness_winkler_data(
            y_true=y_true,
            dist=dist,
            coverage_levels=levels,
            metric="winkler",
            n_bootstraps=n_bootstraps_val,
            decimals=decimals,
            n_jobs=n_jobs_val,
        )

        display_label = label or "Model"

        with (
            plt.rc_context(self.theme.to_rc_params()),
        ):
            fig, ax = draw_winkler_curve(
                coverage_levels=data["coverage_levels"],
                winkler_values=data["output"]["point"],
                lower_ci=data["output"]["lower_ci"],
                upper_ci=data["output"]["upper_ci"],
                label=display_label,
                color=style_kwargs.pop("color", self.theme.primary_color),
                ci_alpha=style_kwargs.pop("ci_alpha", self.theme.ci_alpha),
                linewidth=style_kwargs.pop("linewidth", self.theme.linewidth),
                show_spines=style_kwargs.pop("show_spines", self.theme.show_spines),
                title=f"Winkler Score - {outcome.capitalize()}",
                **style_kwargs,
            )

        if save_val:
            self._save_figure(fig=fig, filename=f"{outcome}_winkler", outcome=outcome)

        if show_val:
            plt.show()
        elif save_val:
            plt.close(fig.get_figure(root=True))

        return fig, ax

    def plot_marginal_calibration(
        self,
        y_true: np.ndarray,
        dist: ContinuousPredictiveDistribution,
        mapper: BaseBinMapper,
        outcome: str = "default",
        label: str | None = None,
        save: bool | None = None,
        show: bool | None = None,
        **style_kwargs: Any,
    ) -> tuple[Figure | SubFigure, Axes]:
        """Compute the marginal calibration curve, render plot, and save figure.

        Parameters
        ----------
        y_true : np.ndarray
            Ground truth continuous target values of shape (n_samples,).
        dist : ContinuousPredictiveDistribution
            Predictive distribution for the same samples.
        mapper : BaseBinMapper
            Mapper used by the OrdBoostRegressor.
        outcome : str, default="default"
            Outcome identifier used for figure titles and folder structuring.
        label : str, optional
            Legend label for the model. Defaults to 'Model'.
        save : bool, optional
            Automatically save the generated plot to the run directory.
        show : bool, optional
            Whether to display the plot interactively before closing.
        **style_kwargs : Any
            Additional style parameters forwarded to `draw_marginal_calibration`.

        Returns
        -------
        fig : Figure | SubFigure
            Rendered Matplotlib figure object.
        ax : Axes
            Matplotlib axes containing the plotted elements.

        """
        cfg = self._resolve_plot_config(
            plot_type="marginal_calibration",
            outcome=outcome,
            save=save,
            show=show,
            **style_kwargs,
        )
        save_val = cfg["save"]
        show_val = cfg["show"]

        self.logger.info(f"[{outcome}] Starting marginal calibration plotting.")
        grid_y, diff = self._compute_marginal_calibration_data(
            y_true=y_true, dist=dist, mapper=mapper
        )

        display_label = label or "Model"

        with (
            plt.rc_context(self.theme.to_rc_params()),
        ):
            fig, ax = draw_marginal_calibration(
                grid_y=grid_y,
                diff=diff,
                label=display_label,
                color=style_kwargs.pop("color", self.theme.primary_color),
                linewidth=style_kwargs.pop("linewidth", self.theme.linewidth),
                show_spines=style_kwargs.pop("show_spines", self.theme.show_spines),
                title=f"Marginal Calibration - {outcome.capitalize()}",
                **style_kwargs,
            )

        if save_val:
            self._save_figure(
                fig=fig, filename=f"{outcome}_marginal_calibration", outcome=outcome
            )

        if show_val:
            plt.show()
        elif save_val:
            plt.close(fig.get_figure(root=True))

        return fig, ax

    def plot_pit_histogram(
        self,
        y_true: np.ndarray,
        dist: ContinuousPredictiveDistribution,
        mapper: BaseBinMapper | None = None,
        outcome: str = "default",
        n_bins: int | None = None,
        label: str | None = None,
        save: bool | None = None,
        show: bool | None = None,
        **style_kwargs: Any,
    ) -> tuple[Figure | SubFigure, Axes]:
        """Compute PIT diagnostics, render histogram, and save figure.

        Parameters
        ----------
        y_true : np.ndarray
            Ground truth continuous target values of shape (n_samples,).
        dist : ContinuousPredictiveDistribution
            Predictive distribution for the same samples.
        mapper : BaseBinMapper, optional
            The fitted OrdBoost model's bin mapper (e.g. its `mapper_`
            attribute). Required; NGBoost-wrapped distributions are not yet
            supported and will raise a clear error.
        outcome : str, default="default"
            Outcome identifier used for figure titles and folder structuring.
        n_bins : int, optional
            Number of PIT histogram bins. Defaults to 20.
        label : str, optional
            Legend label prefix for the histogram. Defaults to 'Model'.
        save : bool, optional
            Automatically save the generated plot to the run directory.
        show : bool, optional
            Whether to display the plot interactively before closing.
        **style_kwargs : Any
            Additional style parameters forwarded to `draw_pit_histogram`.

        Returns
        -------
        fig : Figure | SubFigure
            Rendered Matplotlib figure object.
        ax : Axes
            Matplotlib axes containing the plotted elements.

        Raises
        ------
        ValueError
            If `mapper` is None.

        """
        cfg = self._resolve_plot_config(
            plot_type="pit_histogram",
            outcome=outcome,
            pit_n_bins=n_bins,
            save=save,
            show=show,
            **style_kwargs,
        )
        n_bins_val = cfg["pit_n_bins"]
        save_val = cfg["save"]
        show_val = cfg["show"]

        self.logger.info(f"[{outcome}] Starting PIT histogram plotting.")
        bin_centres, hist_values, alpha_score = self._compute_pit_histogram_data(
            y_true=y_true, dist=dist, mapper=mapper, n_bins=n_bins_val
        )

        display_label = label or "Model"

        with (
            plt.rc_context(self.theme.to_rc_params()),
        ):
            fig, ax = draw_pit_histogram(
                bin_centres=bin_centres,
                hist_values=hist_values,
                alpha_score=alpha_score,
                n_bins=n_bins_val,
                label=display_label,
                color=style_kwargs.pop("color", self.theme.primary_color),
                show_spines=style_kwargs.pop("show_spines", self.theme.show_spines),
                title=f"PIT Histogram - {outcome.capitalize()}",
                **style_kwargs,
            )

        if save_val:
            self._save_figure(
                fig=fig, filename=f"{outcome}_pit_histogram", outcome=outcome
            )

        if show_val:
            plt.show()
        elif save_val:
            plt.close(fig.get_figure(root=True))

        return fig, ax

    def plot_all(
        self,
        y_true: np.ndarray,
        dist: ContinuousPredictiveDistribution,
        mapper: BaseBinMapper | None = None,
        outcome: str = "default",
        coverage_levels: np.ndarray | None = None,
        n_bootstraps: int | None = None,
        save: bool | None = None,
        show: bool | None = None,
        decimals: int | None = None,
        n_jobs: int | None = None,
        **style_kwargs: Any,
    ) -> dict[str, tuple[Figure | SubFigure, Axes]]:
        """Execute all core distributional diagnostic visualization routines
        for a given outcome.

        Generates and optionally persists the coverage reliability curve,
        sharpness curve, Winkler score curve, marginal calibration curve,
        PIT histogram, and target-value data distribution histogram.

        Parameters
        ----------
        y_true : np.ndarray
            Ground truth continuous target values of shape (n_samples,).
        dist : ContinuousPredictiveDistribution
            Predictive distribution for the same samples.
        mapper : BaseBinMapper, optional
            The fitted OrdBoost model's bin mapper, required for the PIT
            histogram (e.g. its `mapper_` attribute).
        outcome : str, default="default"
            Outcome identifier used for figure titles and output folder structuring.
        coverage_levels : np.ndarray, optional
            Nominal central-interval coverage levels in percent, used for the
            coverage, sharpness, and Winkler score curves.
        n_bootstraps : int, optional
            Number of bootstrap iterations for coverage, sharpness, and
            Winkler score curves.
        save : bool, optional
            Automatically save all generated plot artifacts to the run directory.
        show : bool, optional
            Whether to display figures interactively before closing.
        decimals : int, optional
            Number of decimals the predictive interval bounds are rounded to
            for the coverage, sharpness, and Winkler score curves. If None,
            no rounding is applied.
        n_jobs : int, optional
            Number of parallel jobs used for the bootstrap resamples. Overrides
            the display configuration's `n_jobs` when given.
        **style_kwargs : Any
            Additional style parameters forwarded to underlying drawing functions.

        Returns
        -------
        Dict[str, Tuple[Figure | SubFigure, Axes]]
            Dictionary mapping plot identifiers ('coverage', 'sharpness',
            'winkler', 'marginal_calibration', 'pit_histogram',
            'data_distribution') to their rendered (Figure, Axes) tuples.

        """
        plots: dict[str, tuple[Figure | SubFigure, Axes]] = {}

        self.logger.info(f"--- Starting graphical display for outcome: {outcome} ---")

        plots["coverage"] = self.plot_coverage(
            y_true=y_true,
            dist=dist,
            outcome=outcome,
            coverage_levels=coverage_levels,
            n_bootstraps=n_bootstraps,
            n_jobs=n_jobs,
            save=save,
            show=show,
            decimals=decimals,
            **style_kwargs.copy(),
        )

        plots["sharpness"] = self.plot_sharpness(
            y_true=y_true,
            dist=dist,
            outcome=outcome,
            coverage_levels=coverage_levels,
            n_bootstraps=n_bootstraps,
            n_jobs=n_jobs,
            save=save,
            show=show,
            decimals=decimals,
            **style_kwargs.copy(),
        )

        plots["winkler"] = self.plot_winkler(
            y_true=y_true,
            dist=dist,
            outcome=outcome,
            coverage_levels=coverage_levels,
            n_bootstraps=n_bootstraps,
            n_jobs=n_jobs,
            save=save,
            show=show,
            decimals=decimals,
            **style_kwargs.copy(),
        )

        plots["marginal_calibration"] = self.plot_marginal_calibration(
            y_true=y_true,
            dist=dist,
            mapper=mapper,
            outcome=outcome,
            save=save,
            show=show,
            **style_kwargs.copy(),
        )

        plots["pit_histogram"] = self.plot_pit_histogram(
            y_true=y_true,
            dist=dist,
            mapper=mapper,
            outcome=outcome,
            save=save,
            show=show,
            **style_kwargs.copy(),
        )

        plots["data_distribution"] = self.plot_data_distribution(
            data=y_true,
            outcome=outcome,
            save=save,
            show=show,
            **style_kwargs.copy(),
        )

        self.logger.info(f"--- Finished graphical display for outcome: {outcome} ---")
        return plots

plot_coverage

plot_coverage(
    y_true: ndarray,
    dist: ContinuousPredictiveDistribution,
    outcome: str = "default",
    coverage_levels: ndarray | None = None,
    n_bootstraps: int | None = None,
    label: str | None = None,
    save: bool | None = None,
    show: bool | None = None,
    decimals: int | None = None,
    n_jobs: int | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Compute coverage reliability, render curve with confidence intervals, and save figure.

Parameters:

Name	Type	Description	Default
`y_true`	`ndarray`	Ground truth continuous target values of shape (n_samples,).	required
`dist`	`ContinuousPredictiveDistribution`	Predictive distribution for the same samples.	required
`outcome`	`str`	Outcome identifier used for figure titles and folder structuring.	`"default"`
`coverage_levels`	`ndarray`	Nominal central-interval coverage levels in percent. Defaults to `np.arange(5, 100, 10)`.	`None`
`n_bootstraps`	`int`	Number of bootstrap iterations for confidence intervals. Set to 0 to disable.	`None`
`label`	`str`	Legend label for the model. Defaults to 'Model'.	`None`
`save`	`bool`	Automatically save the generated plot to the run directory.	`None`
`show`	`bool`	Whether to display the plot interactively before closing.	`None`
`decimals`	`int`	Number of decimals the predictive interval bounds are rounded to. If None, no rounding is applied.	`None`
`n_jobs`	`int`	Number of parallel jobs used for the bootstrap resamples. Overrides the display configuration's `n_jobs` when given.	`None`
`**style_kwargs`	`Any`	Additional style parameters forwarded to `draw_coverage_curve`.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure \| SubFigure`	Rendered Matplotlib figure object.
`ax`	`Axes`	Matplotlib axes containing the plotted elements.

Source code in medpipe/visualisation/displayer.py

def plot_coverage(
    self,
    y_true: np.ndarray,
    dist: ContinuousPredictiveDistribution,
    outcome: str = "default",
    coverage_levels: np.ndarray | None = None,
    n_bootstraps: int | None = None,
    label: str | None = None,
    save: bool | None = None,
    show: bool | None = None,
    decimals: int | None = None,
    n_jobs: int | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Compute coverage reliability, render curve with confidence
    intervals, and save figure.

    Parameters
    ----------
    y_true : np.ndarray
        Ground truth continuous target values of shape (n_samples,).
    dist : ContinuousPredictiveDistribution
        Predictive distribution for the same samples.
    outcome : str, default="default"
        Outcome identifier used for figure titles and folder structuring.
    coverage_levels : np.ndarray, optional
        Nominal central-interval coverage levels in percent. Defaults to
        `np.arange(5, 100, 10)`.
    n_bootstraps : int, optional
        Number of bootstrap iterations for confidence intervals. Set to 0
        to disable.
    label : str, optional
        Legend label for the model. Defaults to 'Model'.
    save : bool, optional
        Automatically save the generated plot to the run directory.
    show : bool, optional
        Whether to display the plot interactively before closing.
    decimals : int, optional
        Number of decimals the predictive interval bounds are rounded to.
        If None, no rounding is applied.
    n_jobs : int, optional
        Number of parallel jobs used for the bootstrap resamples. Overrides
        the display configuration's `n_jobs` when given.
    **style_kwargs : Any
        Additional style parameters forwarded to `draw_coverage_curve`.

    Returns
    -------
    fig : Figure | SubFigure
        Rendered Matplotlib figure object.
    ax : Axes
        Matplotlib axes containing the plotted elements.

    """
    cfg = self._resolve_plot_config(
        plot_type="coverage",
        outcome=outcome,
        coverage_levels=coverage_levels,
        n_bootstraps=n_bootstraps,
        n_jobs=n_jobs,
        save=save,
        show=show,
        **style_kwargs,
    )
    n_bootstraps_val = cfg["n_bootstraps"]
    n_jobs_val = cfg["n_jobs"]
    save_val = cfg["save"]
    show_val = cfg["show"]
    levels = np.asarray(cfg["coverage_levels"])

    self.logger.info(f"[{outcome}] Starting coverage curve plotting.")
    data = self._compute_coverage_sharpness_winkler_data(
        y_true=y_true,
        dist=dist,
        coverage_levels=levels,
        metric="coverage",
        n_bootstraps=n_bootstraps_val,
        decimals=decimals,
        n_jobs=n_jobs_val,
    )

    display_label = label or "Model"

    with (
        plt.rc_context(self.theme.to_rc_params()),
    ):
        fig, ax = draw_coverage_curve(
            coverage_levels=data["coverage_levels"],
            empirical_coverage=data["output"]["point"],
            lower_ci=data["output"]["lower_ci"],
            upper_ci=data["output"]["upper_ci"],
            label=display_label,
            color=style_kwargs.pop("color", self.theme.primary_color),
            ci_alpha=style_kwargs.pop("ci_alpha", self.theme.ci_alpha),
            linewidth=style_kwargs.pop("linewidth", self.theme.linewidth),
            show_spines=style_kwargs.pop("show_spines", self.theme.show_spines),
            title=f"Coverage Reliability - {outcome.capitalize()}",
            **style_kwargs,
        )

    if save_val:
        self._save_figure(fig=fig, filename=f"{outcome}_coverage", outcome=outcome)

    if show_val:
        plt.show()
    elif save_val:
        plt.close(fig.get_figure(root=True))

    return fig, ax

plot_sharpness

plot_sharpness(
    y_true: ndarray,
    dist: ContinuousPredictiveDistribution,
    outcome: str = "default",
    coverage_levels: ndarray | None = None,
    n_bootstraps: int | None = None,
    label: str | None = None,
    save: bool | None = None,
    show: bool | None = None,
    decimals: int | None = None,
    n_jobs: int | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Compute sharpness, render curve with confidence intervals, and save figure.

Parameters:

Name	Type	Description	Default
`y_true`	`ndarray`	Ground truth continuous target values of shape (n_samples,).	required
`dist`	`ContinuousPredictiveDistribution`	Predictive distribution for the same samples.	required
`outcome`	`str`	Outcome identifier used for figure titles and folder structuring.	`"default"`
`coverage_levels`	`ndarray`	Nominal central-interval coverage levels in percent. Defaults to `np.arange(5, 100, 10)`.	`None`
`n_bootstraps`	`int`	Number of bootstrap iterations for confidence intervals. Set to 0 to disable.	`None`
`label`	`str`	Legend label for the model. Defaults to 'Model'.	`None`
`save`	`bool`	Automatically save the generated plot to the run directory.	`None`
`show`	`bool`	Whether to display the plot interactively before closing.	`None`
`decimals`	`int`	Number of decimals the predictive interval bounds are rounded to. If None, no rounding is applied.	`None`
`n_jobs`	`int`	Number of parallel jobs used for the bootstrap resamples. Overrides the display configuration's `n_jobs` when given.	`None`
`**style_kwargs`	`Any`	Additional style parameters forwarded to `draw_sharpness_curve`.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure \| SubFigure`	Rendered Matplotlib figure object.
`ax`	`Axes`	Matplotlib axes containing the plotted elements.

Source code in medpipe/visualisation/displayer.py

def plot_sharpness(
    self,
    y_true: np.ndarray,
    dist: ContinuousPredictiveDistribution,
    outcome: str = "default",
    coverage_levels: np.ndarray | None = None,
    n_bootstraps: int | None = None,
    label: str | None = None,
    save: bool | None = None,
    show: bool | None = None,
    decimals: int | None = None,
    n_jobs: int | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Compute sharpness, render curve with confidence intervals, and
    save figure.

    Parameters
    ----------
    y_true : np.ndarray
        Ground truth continuous target values of shape (n_samples,).
    dist : ContinuousPredictiveDistribution
        Predictive distribution for the same samples.
    outcome : str, default="default"
        Outcome identifier used for figure titles and folder structuring.
    coverage_levels : np.ndarray, optional
        Nominal central-interval coverage levels in percent. Defaults to
        `np.arange(5, 100, 10)`.
    n_bootstraps : int, optional
        Number of bootstrap iterations for confidence intervals. Set to 0
        to disable.
    label : str, optional
        Legend label for the model. Defaults to 'Model'.
    save : bool, optional
        Automatically save the generated plot to the run directory.
    show : bool, optional
        Whether to display the plot interactively before closing.
    decimals : int, optional
        Number of decimals the predictive interval bounds are rounded to.
        If None, no rounding is applied.
    n_jobs : int, optional
        Number of parallel jobs used for the bootstrap resamples. Overrides
        the display configuration's `n_jobs` when given.
    **style_kwargs : Any
        Additional style parameters forwarded to `draw_sharpness_curve`.

    Returns
    -------
    fig : Figure | SubFigure
        Rendered Matplotlib figure object.
    ax : Axes
        Matplotlib axes containing the plotted elements.

    """
    cfg = self._resolve_plot_config(
        plot_type="sharpness",
        outcome=outcome,
        coverage_levels=coverage_levels,
        n_bootstraps=n_bootstraps,
        n_jobs=n_jobs,
        save=save,
        show=show,
        **style_kwargs,
    )
    n_bootstraps_val = cfg["n_bootstraps"]
    n_jobs_val = cfg["n_jobs"]
    save_val = cfg["save"]
    show_val = cfg["show"]
    levels = np.asarray(cfg["coverage_levels"])

    self.logger.info(f"[{outcome}] Starting sharpness curve plotting.")
    data = self._compute_coverage_sharpness_winkler_data(
        y_true=y_true,
        dist=dist,
        coverage_levels=levels,
        metric="sharpness",
        n_bootstraps=n_bootstraps_val,
        decimals=decimals,
        n_jobs=n_jobs_val,
    )

    display_label = label or "Model"

    with (
        plt.rc_context(self.theme.to_rc_params()),
    ):
        fig, ax = draw_sharpness_curve(
            coverage_levels=data["coverage_levels"],
            sharpness_values=data["output"]["point"],
            lower_ci=data["output"]["lower_ci"],
            upper_ci=data["output"]["upper_ci"],
            label=display_label,
            color=style_kwargs.pop("color", self.theme.primary_color),
            ci_alpha=style_kwargs.pop("ci_alpha", self.theme.ci_alpha),
            linewidth=style_kwargs.pop("linewidth", self.theme.linewidth),
            show_spines=style_kwargs.pop("show_spines", self.theme.show_spines),
            title=f"Sharpness - {outcome.capitalize()}",
            **style_kwargs,
        )

    if save_val:
        self._save_figure(fig=fig, filename=f"{outcome}_sharpness", outcome=outcome)

    if show_val:
        plt.show()
    elif save_val:
        plt.close(fig.get_figure(root=True))

    return fig, ax

plot_winkler

plot_winkler(
    y_true: ndarray,
    dist: ContinuousPredictiveDistribution,
    outcome: str = "default",
    coverage_levels: ndarray | None = None,
    n_bootstraps: int | None = None,
    label: str | None = None,
    save: bool | None = None,
    show: bool | None = None,
    decimals: int | None = None,
    n_jobs: int | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Compute Winkler score, render curve with confidence intervals, and save figure.

Parameters:

Name	Type	Description	Default
`y_true`	`ndarray`	Ground truth continuous target values of shape (n_samples,).	required
`dist`	`ContinuousPredictiveDistribution`	Predictive distribution for the same samples.	required
`outcome`	`str`	Outcome identifier used for figure titles and folder structuring.	`"default"`
`coverage_levels`	`ndarray`	Nominal central-interval coverage levels in percent. Defaults to `np.arange(5, 100, 10)`.	`None`
`n_bootstraps`	`int`	Number of bootstrap iterations for confidence intervals. Set to 0 to disable.	`None`
`label`	`str`	Legend label for the model. Defaults to 'Model'.	`None`
`save`	`bool`	Automatically save the generated plot to the run directory.	`None`
`show`	`bool`	Whether to display the plot interactively before closing.	`None`
`decimals`	`int`	Number of decimals the predictive interval bounds are rounded to. If None, no rounding is applied.	`None`
`n_jobs`	`int`	Number of parallel jobs used for the bootstrap resamples. Overrides the display configuration's `n_jobs` when given.	`None`
`**style_kwargs`	`Any`	Additional style parameters forwarded to `draw_winkler_curve`.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure \| SubFigure`	Rendered Matplotlib figure object.
`ax`	`Axes`	Matplotlib axes containing the plotted elements.

Source code in medpipe/visualisation/displayer.py

def plot_winkler(
    self,
    y_true: np.ndarray,
    dist: ContinuousPredictiveDistribution,
    outcome: str = "default",
    coverage_levels: np.ndarray | None = None,
    n_bootstraps: int | None = None,
    label: str | None = None,
    save: bool | None = None,
    show: bool | None = None,
    decimals: int | None = None,
    n_jobs: int | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Compute Winkler score, render curve with confidence intervals,
    and save figure.

    Parameters
    ----------
    y_true : np.ndarray
        Ground truth continuous target values of shape (n_samples,).
    dist : ContinuousPredictiveDistribution
        Predictive distribution for the same samples.
    outcome : str, default="default"
        Outcome identifier used for figure titles and folder structuring.
    coverage_levels : np.ndarray, optional
        Nominal central-interval coverage levels in percent. Defaults to
        `np.arange(5, 100, 10)`.
    n_bootstraps : int, optional
        Number of bootstrap iterations for confidence intervals. Set to 0
        to disable.
    label : str, optional
        Legend label for the model. Defaults to 'Model'.
    save : bool, optional
        Automatically save the generated plot to the run directory.
    show : bool, optional
        Whether to display the plot interactively before closing.
    decimals : int, optional
        Number of decimals the predictive interval bounds are rounded to.
        If None, no rounding is applied.
    n_jobs : int, optional
        Number of parallel jobs used for the bootstrap resamples. Overrides
        the display configuration's `n_jobs` when given.
    **style_kwargs : Any
        Additional style parameters forwarded to `draw_winkler_curve`.

    Returns
    -------
    fig : Figure | SubFigure
        Rendered Matplotlib figure object.
    ax : Axes
        Matplotlib axes containing the plotted elements.

    """
    cfg = self._resolve_plot_config(
        plot_type="winkler",
        outcome=outcome,
        coverage_levels=coverage_levels,
        n_bootstraps=n_bootstraps,
        n_jobs=n_jobs,
        save=save,
        show=show,
        **style_kwargs,
    )
    n_bootstraps_val = cfg["n_bootstraps"]
    n_jobs_val = cfg["n_jobs"]
    save_val = cfg["save"]
    show_val = cfg["show"]
    levels = np.asarray(cfg["coverage_levels"])

    self.logger.info(f"[{outcome}] Starting Winkler score curve plotting.")
    data = self._compute_coverage_sharpness_winkler_data(
        y_true=y_true,
        dist=dist,
        coverage_levels=levels,
        metric="winkler",
        n_bootstraps=n_bootstraps_val,
        decimals=decimals,
        n_jobs=n_jobs_val,
    )

    display_label = label or "Model"

    with (
        plt.rc_context(self.theme.to_rc_params()),
    ):
        fig, ax = draw_winkler_curve(
            coverage_levels=data["coverage_levels"],
            winkler_values=data["output"]["point"],
            lower_ci=data["output"]["lower_ci"],
            upper_ci=data["output"]["upper_ci"],
            label=display_label,
            color=style_kwargs.pop("color", self.theme.primary_color),
            ci_alpha=style_kwargs.pop("ci_alpha", self.theme.ci_alpha),
            linewidth=style_kwargs.pop("linewidth", self.theme.linewidth),
            show_spines=style_kwargs.pop("show_spines", self.theme.show_spines),
            title=f"Winkler Score - {outcome.capitalize()}",
            **style_kwargs,
        )

    if save_val:
        self._save_figure(fig=fig, filename=f"{outcome}_winkler", outcome=outcome)

    if show_val:
        plt.show()
    elif save_val:
        plt.close(fig.get_figure(root=True))

    return fig, ax

plot_marginal_calibration

plot_marginal_calibration(
    y_true: ndarray,
    dist: ContinuousPredictiveDistribution,
    mapper: BaseBinMapper,
    outcome: str = "default",
    label: str | None = None,
    save: bool | None = None,
    show: bool | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Compute the marginal calibration curve, render plot, and save figure.

Parameters:

Name	Type	Description	Default
`y_true`	`ndarray`	Ground truth continuous target values of shape (n_samples,).	required
`dist`	`ContinuousPredictiveDistribution`	Predictive distribution for the same samples.	required
`mapper`	`BaseBinMapper`	Mapper used by the OrdBoostRegressor.	required
`outcome`	`str`	Outcome identifier used for figure titles and folder structuring.	`"default"`
`label`	`str`	Legend label for the model. Defaults to 'Model'.	`None`
`save`	`bool`	Automatically save the generated plot to the run directory.	`None`
`show`	`bool`	Whether to display the plot interactively before closing.	`None`
`**style_kwargs`	`Any`	Additional style parameters forwarded to `draw_marginal_calibration`.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure \| SubFigure`	Rendered Matplotlib figure object.
`ax`	`Axes`	Matplotlib axes containing the plotted elements.

Source code in medpipe/visualisation/displayer.py

def plot_marginal_calibration(
    self,
    y_true: np.ndarray,
    dist: ContinuousPredictiveDistribution,
    mapper: BaseBinMapper,
    outcome: str = "default",
    label: str | None = None,
    save: bool | None = None,
    show: bool | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Compute the marginal calibration curve, render plot, and save figure.

    Parameters
    ----------
    y_true : np.ndarray
        Ground truth continuous target values of shape (n_samples,).
    dist : ContinuousPredictiveDistribution
        Predictive distribution for the same samples.
    mapper : BaseBinMapper
        Mapper used by the OrdBoostRegressor.
    outcome : str, default="default"
        Outcome identifier used for figure titles and folder structuring.
    label : str, optional
        Legend label for the model. Defaults to 'Model'.
    save : bool, optional
        Automatically save the generated plot to the run directory.
    show : bool, optional
        Whether to display the plot interactively before closing.
    **style_kwargs : Any
        Additional style parameters forwarded to `draw_marginal_calibration`.

    Returns
    -------
    fig : Figure | SubFigure
        Rendered Matplotlib figure object.
    ax : Axes
        Matplotlib axes containing the plotted elements.

    """
    cfg = self._resolve_plot_config(
        plot_type="marginal_calibration",
        outcome=outcome,
        save=save,
        show=show,
        **style_kwargs,
    )
    save_val = cfg["save"]
    show_val = cfg["show"]

    self.logger.info(f"[{outcome}] Starting marginal calibration plotting.")
    grid_y, diff = self._compute_marginal_calibration_data(
        y_true=y_true, dist=dist, mapper=mapper
    )

    display_label = label or "Model"

    with (
        plt.rc_context(self.theme.to_rc_params()),
    ):
        fig, ax = draw_marginal_calibration(
            grid_y=grid_y,
            diff=diff,
            label=display_label,
            color=style_kwargs.pop("color", self.theme.primary_color),
            linewidth=style_kwargs.pop("linewidth", self.theme.linewidth),
            show_spines=style_kwargs.pop("show_spines", self.theme.show_spines),
            title=f"Marginal Calibration - {outcome.capitalize()}",
            **style_kwargs,
        )

    if save_val:
        self._save_figure(
            fig=fig, filename=f"{outcome}_marginal_calibration", outcome=outcome
        )

    if show_val:
        plt.show()
    elif save_val:
        plt.close(fig.get_figure(root=True))

    return fig, ax

plot_pit_histogram

plot_pit_histogram(
    y_true: ndarray,
    dist: ContinuousPredictiveDistribution,
    mapper: BaseBinMapper | None = None,
    outcome: str = "default",
    n_bins: int | None = None,
    label: str | None = None,
    save: bool | None = None,
    show: bool | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Compute PIT diagnostics, render histogram, and save figure.

Parameters:

Name	Type	Description	Default
`y_true`	`ndarray`	Ground truth continuous target values of shape (n_samples,).	required
`dist`	`ContinuousPredictiveDistribution`	Predictive distribution for the same samples.	required
`mapper`	`BaseBinMapper`	The fitted OrdBoost model's bin mapper (e.g. its `mapper_` attribute). Required; NGBoost-wrapped distributions are not yet supported and will raise a clear error.	`None`
`outcome`	`str`	Outcome identifier used for figure titles and folder structuring.	`"default"`
`n_bins`	`int`	Number of PIT histogram bins. Defaults to 20.	`None`
`label`	`str`	Legend label prefix for the histogram. Defaults to 'Model'.	`None`
`save`	`bool`	Automatically save the generated plot to the run directory.	`None`
`show`	`bool`	Whether to display the plot interactively before closing.	`None`
`**style_kwargs`	`Any`	Additional style parameters forwarded to `draw_pit_histogram`.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure \| SubFigure`	Rendered Matplotlib figure object.
`ax`	`Axes`	Matplotlib axes containing the plotted elements.

Raises:

Type	Description
`ValueError`	If `mapper` is None.

Source code in medpipe/visualisation/displayer.py

def plot_pit_histogram(
    self,
    y_true: np.ndarray,
    dist: ContinuousPredictiveDistribution,
    mapper: BaseBinMapper | None = None,
    outcome: str = "default",
    n_bins: int | None = None,
    label: str | None = None,
    save: bool | None = None,
    show: bool | None = None,
    **style_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Compute PIT diagnostics, render histogram, and save figure.

    Parameters
    ----------
    y_true : np.ndarray
        Ground truth continuous target values of shape (n_samples,).
    dist : ContinuousPredictiveDistribution
        Predictive distribution for the same samples.
    mapper : BaseBinMapper, optional
        The fitted OrdBoost model's bin mapper (e.g. its `mapper_`
        attribute). Required; NGBoost-wrapped distributions are not yet
        supported and will raise a clear error.
    outcome : str, default="default"
        Outcome identifier used for figure titles and folder structuring.
    n_bins : int, optional
        Number of PIT histogram bins. Defaults to 20.
    label : str, optional
        Legend label prefix for the histogram. Defaults to 'Model'.
    save : bool, optional
        Automatically save the generated plot to the run directory.
    show : bool, optional
        Whether to display the plot interactively before closing.
    **style_kwargs : Any
        Additional style parameters forwarded to `draw_pit_histogram`.

    Returns
    -------
    fig : Figure | SubFigure
        Rendered Matplotlib figure object.
    ax : Axes
        Matplotlib axes containing the plotted elements.

    Raises
    ------
    ValueError
        If `mapper` is None.

    """
    cfg = self._resolve_plot_config(
        plot_type="pit_histogram",
        outcome=outcome,
        pit_n_bins=n_bins,
        save=save,
        show=show,
        **style_kwargs,
    )
    n_bins_val = cfg["pit_n_bins"]
    save_val = cfg["save"]
    show_val = cfg["show"]

    self.logger.info(f"[{outcome}] Starting PIT histogram plotting.")
    bin_centres, hist_values, alpha_score = self._compute_pit_histogram_data(
        y_true=y_true, dist=dist, mapper=mapper, n_bins=n_bins_val
    )

    display_label = label or "Model"

    with (
        plt.rc_context(self.theme.to_rc_params()),
    ):
        fig, ax = draw_pit_histogram(
            bin_centres=bin_centres,
            hist_values=hist_values,
            alpha_score=alpha_score,
            n_bins=n_bins_val,
            label=display_label,
            color=style_kwargs.pop("color", self.theme.primary_color),
            show_spines=style_kwargs.pop("show_spines", self.theme.show_spines),
            title=f"PIT Histogram - {outcome.capitalize()}",
            **style_kwargs,
        )

    if save_val:
        self._save_figure(
            fig=fig, filename=f"{outcome}_pit_histogram", outcome=outcome
        )

    if show_val:
        plt.show()
    elif save_val:
        plt.close(fig.get_figure(root=True))

    return fig, ax

plot_all

plot_all(
    y_true: ndarray,
    dist: ContinuousPredictiveDistribution,
    mapper: BaseBinMapper | None = None,
    outcome: str = "default",
    coverage_levels: ndarray | None = None,
    n_bootstraps: int | None = None,
    save: bool | None = None,
    show: bool | None = None,
    decimals: int | None = None,
    n_jobs: int | None = None,
    **style_kwargs: Any,
) -> dict[str, tuple[Figure | SubFigure, Axes]]

Execute all core distributional diagnostic visualization routines for a given outcome.

Generates and optionally persists the coverage reliability curve, sharpness curve, Winkler score curve, marginal calibration curve, PIT histogram, and target-value data distribution histogram.

Parameters:

Name	Type	Description	Default
`y_true`	`ndarray`	Ground truth continuous target values of shape (n_samples,).	required
`dist`	`ContinuousPredictiveDistribution`	Predictive distribution for the same samples.	required
`mapper`	`BaseBinMapper`	The fitted OrdBoost model's bin mapper, required for the PIT histogram (e.g. its `mapper_` attribute).	`None`
`outcome`	`str`	Outcome identifier used for figure titles and output folder structuring.	`"default"`
`coverage_levels`	`ndarray`	Nominal central-interval coverage levels in percent, used for the coverage, sharpness, and Winkler score curves.	`None`
`n_bootstraps`	`int`	Number of bootstrap iterations for coverage, sharpness, and Winkler score curves.	`None`
`save`	`bool`	Automatically save all generated plot artifacts to the run directory.	`None`
`show`	`bool`	Whether to display figures interactively before closing.	`None`
`decimals`	`int`	Number of decimals the predictive interval bounds are rounded to for the coverage, sharpness, and Winkler score curves. If None, no rounding is applied.	`None`
`n_jobs`	`int`	Number of parallel jobs used for the bootstrap resamples. Overrides the display configuration's `n_jobs` when given.	`None`
`**style_kwargs`	`Any`	Additional style parameters forwarded to underlying drawing functions.	`{}`

Returns:

Type	Description
`Dict[str, Tuple[Figure \| SubFigure, Axes]]`	Dictionary mapping plot identifiers ('coverage', 'sharpness', 'winkler', 'marginal_calibration', 'pit_histogram', 'data_distribution') to their rendered (Figure, Axes) tuples.

Source code in medpipe/visualisation/displayer.py

def plot_all(
    self,
    y_true: np.ndarray,
    dist: ContinuousPredictiveDistribution,
    mapper: BaseBinMapper | None = None,
    outcome: str = "default",
    coverage_levels: np.ndarray | None = None,
    n_bootstraps: int | None = None,
    save: bool | None = None,
    show: bool | None = None,
    decimals: int | None = None,
    n_jobs: int | None = None,
    **style_kwargs: Any,
) -> dict[str, tuple[Figure | SubFigure, Axes]]:
    """Execute all core distributional diagnostic visualization routines
    for a given outcome.

    Generates and optionally persists the coverage reliability curve,
    sharpness curve, Winkler score curve, marginal calibration curve,
    PIT histogram, and target-value data distribution histogram.

    Parameters
    ----------
    y_true : np.ndarray
        Ground truth continuous target values of shape (n_samples,).
    dist : ContinuousPredictiveDistribution
        Predictive distribution for the same samples.
    mapper : BaseBinMapper, optional
        The fitted OrdBoost model's bin mapper, required for the PIT
        histogram (e.g. its `mapper_` attribute).
    outcome : str, default="default"
        Outcome identifier used for figure titles and output folder structuring.
    coverage_levels : np.ndarray, optional
        Nominal central-interval coverage levels in percent, used for the
        coverage, sharpness, and Winkler score curves.
    n_bootstraps : int, optional
        Number of bootstrap iterations for coverage, sharpness, and
        Winkler score curves.
    save : bool, optional
        Automatically save all generated plot artifacts to the run directory.
    show : bool, optional
        Whether to display figures interactively before closing.
    decimals : int, optional
        Number of decimals the predictive interval bounds are rounded to
        for the coverage, sharpness, and Winkler score curves. If None,
        no rounding is applied.
    n_jobs : int, optional
        Number of parallel jobs used for the bootstrap resamples. Overrides
        the display configuration's `n_jobs` when given.
    **style_kwargs : Any
        Additional style parameters forwarded to underlying drawing functions.

    Returns
    -------
    Dict[str, Tuple[Figure | SubFigure, Axes]]
        Dictionary mapping plot identifiers ('coverage', 'sharpness',
        'winkler', 'marginal_calibration', 'pit_histogram',
        'data_distribution') to their rendered (Figure, Axes) tuples.

    """
    plots: dict[str, tuple[Figure | SubFigure, Axes]] = {}

    self.logger.info(f"--- Starting graphical display for outcome: {outcome} ---")

    plots["coverage"] = self.plot_coverage(
        y_true=y_true,
        dist=dist,
        outcome=outcome,
        coverage_levels=coverage_levels,
        n_bootstraps=n_bootstraps,
        n_jobs=n_jobs,
        save=save,
        show=show,
        decimals=decimals,
        **style_kwargs.copy(),
    )

    plots["sharpness"] = self.plot_sharpness(
        y_true=y_true,
        dist=dist,
        outcome=outcome,
        coverage_levels=coverage_levels,
        n_bootstraps=n_bootstraps,
        n_jobs=n_jobs,
        save=save,
        show=show,
        decimals=decimals,
        **style_kwargs.copy(),
    )

    plots["winkler"] = self.plot_winkler(
        y_true=y_true,
        dist=dist,
        outcome=outcome,
        coverage_levels=coverage_levels,
        n_bootstraps=n_bootstraps,
        n_jobs=n_jobs,
        save=save,
        show=show,
        decimals=decimals,
        **style_kwargs.copy(),
    )

    plots["marginal_calibration"] = self.plot_marginal_calibration(
        y_true=y_true,
        dist=dist,
        mapper=mapper,
        outcome=outcome,
        save=save,
        show=show,
        **style_kwargs.copy(),
    )

    plots["pit_histogram"] = self.plot_pit_histogram(
        y_true=y_true,
        dist=dist,
        mapper=mapper,
        outcome=outcome,
        save=save,
        show=show,
        **style_kwargs.copy(),
    )

    plots["data_distribution"] = self.plot_data_distribution(
        data=y_true,
        outcome=outcome,
        save=save,
        show=show,
        **style_kwargs.copy(),
    )

    self.logger.info(f"--- Finished graphical display for outcome: {outcome} ---")
    return plots

plots

Stateless drawing primitives for MedpipeClassifier visualizations.

draw_data_distribution

draw_data_distribution(
    data: ndarray,
    n_bins: int = 10,
    label: str = "Data",
    ax: Axes | None = None,
    yscale: str = "linear",
    color: str = primary_color,
    edgecolor: str = "black",
    xlabel: str = "Value",
    title: str | None = None,
    show_spines: bool = show_spines,
    **hist_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Render a data distribution histogram.

Parameters:

Name	Type	Description	Default
`data`	`ndarray`	Data values of shape (n_samples, 2) or (n_samples,) (e.g. predicted probabilities or continuous target values). If 2D, the second column is used.	required
`n_bins`	`int`	Number of equal-width bins spanning the data's own range.	`10`
`label`	`str`	Legend label for the histogram series.	`"Data"`
`ax`	`Axes`	Pre-existing Matplotlib axes instance. If None, a new figure and axes are created.	`None`
`yscale`	`str`	Scale to use for the y-axis (e.g. linear, log, etc.)	`"linear"`
`color`	`str`	Fill color for histogram bars.	`_DEFAULT_THEME.primary_color`
`edgecolor`	`str`	Border color for histogram bars.	`"black"`
`xlabel`	`str`	Label for the x-axis.	`"Value"`
`title`	`str`	Axes title text.	`None`
`show_spines`	`bool`	Whether to keep the top and right border spines visible.	`_DEFAULT_THEME.show_spines`
`**hist_kwargs`	`Any`	Additional Matplotlib keyword arguments forwarded to `ax.hist`.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure or SubFigure`	Parent Matplotlib figure containing the axes.
`ax`	`Axes`	Matplotlib axes containing the rendered histogram.

Raises:

Type	Description
`ValueError`	If ax is provided but not attached to a Figure.

Source code in medpipe/visualisation/plots.py

def draw_data_distribution(
    data: np.ndarray,
    n_bins: int = 10,
    label: str = "Data",
    ax: Axes | None = None,
    yscale: str = "linear",
    color: str = _DEFAULT_THEME.primary_color,
    edgecolor: str = "black",
    xlabel: str = "Value",
    title: str | None = None,
    show_spines: bool = _DEFAULT_THEME.show_spines,
    **hist_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Render a data distribution histogram.

    Parameters
    ----------
    data : np.ndarray
        Data values of shape (n_samples, 2) or (n_samples,) (e.g. predicted
        probabilities or continuous target values). If 2D, the second column
        is used.
    n_bins : int, default=10
        Number of equal-width bins spanning the data's own range.
    label : str, default="Data"
        Legend label for the histogram series.
    ax : matplotlib.axes.Axes, optional
        Pre-existing Matplotlib axes instance. If None, a new figure and axes
        are created.
    yscale : str, default="linear"
        Scale to use for the y-axis (e.g. linear, log, etc.)
    color : str, default=_DEFAULT_THEME.primary_color
        Fill color for histogram bars.
    edgecolor : str, default="black"
        Border color for histogram bars.
    xlabel : str, default="Value"
        Label for the x-axis.
    title : str, optional
        Axes title text.
    show_spines : bool, default=_DEFAULT_THEME.show_spines
        Whether to keep the top and right border spines visible.
    **hist_kwargs : Any
        Additional Matplotlib keyword arguments forwarded to `ax.hist`.

    Returns
    -------
    fig : matplotlib.figure.Figure or matplotlib.figure.SubFigure
        Parent Matplotlib figure containing the axes.
    ax : matplotlib.axes.Axes
        Matplotlib axes containing the rendered histogram.

    Raises
    ------
    ValueError
        If ax is provided but not attached to a Figure.

    """
    fig: Figure | SubFigure | None
    if ax is None:
        fig, ax = plt.subplots(figsize=(6, 6))
    else:
        fig = ax.get_figure()
        if fig is None:
            raise ValueError("The provided Axes instance is not attached to a Figure")

    if data.ndim == 2:
        data = data[:, 1]

    data_min = float(np.min(data))
    data_max = float(np.max(data))
    if data_min == data_max:
        data_min -= 0.5
        data_max += 0.5
    margin = 0.05 * (data_max - data_min)
    bins = np.linspace(data_min, data_max, n_bins + 1).tolist()

    # Clean hist_kwargs to prevent parameter collisions
    for key in ("color", "edgecolor", "bins", "label"):
        hist_kwargs.pop(key, None)

    ax.hist(
        data,
        bins=bins,
        color=color,
        edgecolor=edgecolor,
        label=label,
        **hist_kwargs,
    )

    ax.set_xlabel(xlabel, fontweight="bold")
    ax.set_ylabel("Count", fontweight="bold")
    ax.set_yscale(yscale)
    ax.set_xlim(xmin=data_min - margin, xmax=data_max + margin)

    if title:
        ax.set_title(title, fontweight="bold")

    if not show_spines:
        ax.spines["top"].set_visible(False)
        ax.spines["right"].set_visible(False)

    return fig, ax

draw_roc_curve

draw_roc_curve(
    fpr: ndarray,
    tpr: ndarray,
    lower_ci: ndarray | None = None,
    upper_ci: ndarray | None = None,
    label: str = "Model",
    ax: Axes | None = None,
    color: str = primary_color,
    ci_color: str | None = None,
    ci_alpha: float = ci_alpha,
    linestyle: str = "-",
    linewidth: float = linewidth,
    chance_linestyle: str = "--",
    chance_color: str = "black",
    title: str | None = None,
    show_spines: bool = show_spines,
    **line_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Render a Receiver Operating Characteristic (ROC) curve and optional CI bounds.

Parameters:

Name	Type	Description	Default
`fpr`	`ndarray`	False positive rates across decision thresholds.	required
`tpr`	`ndarray`	True positive rates across decision thresholds.	required
`lower_ci`	`ndarray`	Lower bound array of TPR values for 95% confidence interval shading.	`None`
`upper_ci`	`ndarray`	Upper bound array of TPR values for 95% confidence interval shading.	`None`
`label`	`str`	Legend label for the plotted ROC curve.	`"Model"`
`ax`	`Axes`	Pre-existing Matplotlib axes instance. If None, a new figure and axes are created.	`None`
`color`	`str`	Color specifier for the main ROC curve and default confidence interval fill.	`_DEFAULT_THEME.primary_color`
`ci_color`	`str`	Custom color specifier for confidence interval shading. Defaults to `color`.	`None`
`ci_alpha`	`float`	Opacity level for confidence interval shaded region [0.0, 1.0].	`_DEFAULT_THEME.ci_alpha`
`linestyle`	`str`	Line style specification for the ROC curve.	`"-"`
`linewidth`	`float`	Width in points for the ROC curve line.	`_DEFAULT_THEME.linewidth`
`chance_linestyle`	`str`	Line style specification for the diagonal chance reference line.	`"--"`
`chance_color`	`str`	Color specifier for the diagonal chance reference line.	`"black"`
`title`	`str`	Axes title text.	`None`
`show_spines`	`bool`	Whether to keep the top and right border spines visible.	`_DEFAULT_THEME.show_spines`
`**line_kwargs`	`Any`	Additional Matplotlib keyword arguments forwarded to `ax.plot` for the ROC curve.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure \| SubFigure`	Parent Matplotlib figure containing the axes.
`ax`	`Axes`	Matplotlib axes containing all rendered ROC elements.

Raises:

Type	Description
`ValueError`	If ax is not attached to a Figure.

Source code in medpipe/visualisation/plots.py

def draw_roc_curve(
    fpr: np.ndarray,
    tpr: np.ndarray,
    lower_ci: np.ndarray | None = None,
    upper_ci: np.ndarray | None = None,
    label: str = "Model",
    ax: Axes | None = None,
    color: str = _DEFAULT_THEME.primary_color,
    ci_color: str | None = None,
    ci_alpha: float = _DEFAULT_THEME.ci_alpha,
    linestyle: str = "-",
    linewidth: float = _DEFAULT_THEME.linewidth,
    chance_linestyle: str = "--",
    chance_color: str = "black",
    title: str | None = None,
    show_spines: bool = _DEFAULT_THEME.show_spines,
    **line_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Render a Receiver Operating Characteristic (ROC) curve and optional CI bounds.

    Parameters
    ----------
    fpr : np.ndarray
        False positive rates across decision thresholds.
    tpr : np.ndarray
        True positive rates across decision thresholds.
    lower_ci : np.ndarray, optional
        Lower bound array of TPR values for 95% confidence interval shading.
    upper_ci : np.ndarray, optional
        Upper bound array of TPR values for 95% confidence interval shading.
    label : str, default="Model"
        Legend label for the plotted ROC curve.
    ax : matplotlib.axes.Axes, optional
        Pre-existing Matplotlib axes instance. If None, a new figure and axes
        are created.
    color : str, default=_DEFAULT_THEME.primary_color
        Color specifier for the main ROC curve and default confidence interval fill.
    ci_color : str, optional
        Custom color specifier for confidence interval shading. Defaults to `color`.
    ci_alpha : float, default=_DEFAULT_THEME.ci_alpha
        Opacity level for confidence interval shaded region [0.0, 1.0].
    linestyle : str, default="-"
        Line style specification for the ROC curve.
    linewidth : float, default=_DEFAULT_THEME.linewidth
        Width in points for the ROC curve line.
    chance_linestyle : str, default="--"
        Line style specification for the diagonal chance reference line.
    chance_color : str, default="black"
        Color specifier for the diagonal chance reference line.
    title : str, optional
        Axes title text.
    show_spines : bool, default=_DEFAULT_THEME.show_spines
        Whether to keep the top and right border spines visible.
    **line_kwargs : Any
        Additional Matplotlib keyword arguments forwarded to `ax.plot` for the
        ROC curve.

    Returns
    -------
    fig : Figure | SubFigure
        Parent Matplotlib figure containing the axes.
    ax : Axes
        Matplotlib axes containing all rendered ROC elements.

    Raises
    ------
    ValueError
        If ax is not attached to a Figure.

    """
    fig: Figure | SubFigure | None
    if ax is None:
        fig, ax = plt.subplots(figsize=(6, 6))
    else:
        fig = ax.get_figure()
        if fig is None:
            raise ValueError("The provided Axes instance is not attached to a Figure")

    # Draw diagonal reference line (chance level)
    ax.plot(
        [0, 1],
        [0, 1],
        linestyle=chance_linestyle,
        color=chance_color,
        label="Chance level",
    )

    # Clean line_kwargs to prevent parameter collision
    for key in ("color", "linestyle", "linewidth", "label"):
        line_kwargs.pop(key, None)

    # Draw main ROC curve line
    ax.plot(
        fpr,
        tpr,
        color=color,
        linestyle=linestyle,
        linewidth=linewidth,
        label=label,
        **line_kwargs,
    )

    # Draw confidence interval shading if bounds are supplied
    if lower_ci is not None and upper_ci is not None:
        ax.fill_between(
            fpr,
            lower_ci,
            upper_ci,
            color=ci_color or color,
            alpha=ci_alpha,
            label=f"{label} 95% CI",
        )

    # Format axis bounds and labels
    ax.set_xlabel("FPR (1 - Specificity)", fontweight="bold")
    ax.set_ylabel("TPR (Sensitivity)", fontweight="bold")
    ax.set_xlim(xmin=-0.02, xmax=1.02)
    ax.set_ylim(ymin=-0.02, ymax=1.02)

    if title:
        ax.set_title(title, fontweight="bold")

    if not show_spines:
        ax.spines["top"].set_visible(False)
        ax.spines["right"].set_visible(False)

    ax.legend(loc="lower right", frameon=False)

    return fig, ax

draw_precision_recall_curve

draw_precision_recall_curve(
    precision: ndarray,
    recall: ndarray,
    lower_ci: ndarray | None = None,
    upper_ci: ndarray | None = None,
    baseline: float | None = None,
    label: str = "Model",
    ax: Axes | None = None,
    color: str = primary_color,
    ci_color: str | None = None,
    ci_alpha: float = ci_alpha,
    linestyle: str = "-",
    linewidth: float = linewidth,
    baseline_linestyle: str = "--",
    baseline_color: str = "black",
    title: str | None = None,
    show_spines: bool = show_spines,
    **line_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Render a Precision-Recall (PR) curve with optional CI bounds and baseline.

Parameters:

Name	Type	Description	Default
`precision`	`ndarray`	Precision values across thresholds.	required
`recall`	`ndarray`	Recall values across thresholds.	required
`lower_ci`	`ndarray`	Lower bound array of precision values for 95% confidence interval shading.	`None`
`upper_ci`	`ndarray`	Upper bound array of precision values for 95% confidence interval shading.	`None`
`baseline`	`float`	Horizontal baseline value representing chance performance (positive class ratio).	`None`
`label`	`str`	Legend label for the plotted PR curve.	`"Model"`
`ax`	`Axes`	Pre-existing Matplotlib axes instance. If None, a new figure and axes are created.	`None`
`color`	`str`	Color specifier for the main PR curve and default confidence interval fill.	`_DEFAULT_THEME.primary_color`
`ci_color`	`str`	Custom color specifier for confidence interval shading. Defaults to `color`.	`None`
`ci_alpha`	`float`	Opacity level for confidence interval shaded region [0.0, 1.0].	`_DEFAULT_THEME.ci_alpha`
`linestyle`	`str`	Line style specification for the PR curve.	`"-"`
`linewidth`	`float`	Width in points for the PR curve line.	`_DEFAULT_THEME.linewidth`
`baseline_linestyle`	`str`	Line style specification for the baseline reference line.	`"--"`
`baseline_color`	`str`	Color specifier for the baseline reference line.	`"black"`
`title`	`str`	Axes title text.	`None`
`show_spines`	`bool`	Whether to keep the top and right border spines visible.	`_DEFAULT_THEME.show_spines`
`**line_kwargs`	`Any`	Additional Matplotlib keyword arguments forwarded to `ax.plot` for the PR curve.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure or SubFigure`	Parent Matplotlib figure containing the axes.
`ax`	`Axes`	Matplotlib axes containing all rendered PR elements.

Raises:

Type	Description
`ValueError`	If ax is provided but not attached to a Figure.

Source code in medpipe/visualisation/plots.py

def draw_precision_recall_curve(
    precision: np.ndarray,
    recall: np.ndarray,
    lower_ci: np.ndarray | None = None,
    upper_ci: np.ndarray | None = None,
    baseline: float | None = None,
    label: str = "Model",
    ax: Axes | None = None,
    color: str = _DEFAULT_THEME.primary_color,
    ci_color: str | None = None,
    ci_alpha: float = _DEFAULT_THEME.ci_alpha,
    linestyle: str = "-",
    linewidth: float = _DEFAULT_THEME.linewidth,
    baseline_linestyle: str = "--",
    baseline_color: str = "black",
    title: str | None = None,
    show_spines: bool = _DEFAULT_THEME.show_spines,
    **line_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Render a Precision-Recall (PR) curve with optional CI bounds and baseline.

    Parameters
    ----------
    precision : np.ndarray
        Precision values across thresholds.
    recall : np.ndarray
        Recall values across thresholds.
    lower_ci : np.ndarray, optional
        Lower bound array of precision values for 95% confidence interval shading.
    upper_ci : np.ndarray, optional
        Upper bound array of precision values for 95% confidence interval shading.
    baseline : float, optional
        Horizontal baseline value representing chance performance (positive
        class ratio).
    label : str, default="Model"
        Legend label for the plotted PR curve.
    ax : matplotlib.axes.Axes, optional
        Pre-existing Matplotlib axes instance. If None, a new figure and axes
        are created.
    color : str, default=_DEFAULT_THEME.primary_color
        Color specifier for the main PR curve and default confidence interval fill.
    ci_color : str, optional
        Custom color specifier for confidence interval shading. Defaults to `color`.
    ci_alpha : float, default=_DEFAULT_THEME.ci_alpha
        Opacity level for confidence interval shaded region [0.0, 1.0].
    linestyle : str, default="-"
        Line style specification for the PR curve.
    linewidth : float, default=_DEFAULT_THEME.linewidth
        Width in points for the PR curve line.
    baseline_linestyle : str, default="--"
        Line style specification for the baseline reference line.
    baseline_color : str, default="black"
        Color specifier for the baseline reference line.
    title : str, optional
        Axes title text.
    show_spines : bool, default=_DEFAULT_THEME.show_spines
        Whether to keep the top and right border spines visible.
    **line_kwargs : Any
        Additional Matplotlib keyword arguments forwarded to `ax.plot` for the PR curve.

    Returns
    -------
    fig : Figure or SubFigure
        Parent Matplotlib figure containing the axes.
    ax : Axes
        Matplotlib axes containing all rendered PR elements.

    Raises
    ------
    ValueError
        If ax is provided but not attached to a Figure.

    """
    fig: Figure | SubFigure | None
    if ax is None:
        fig, ax = plt.subplots(figsize=(6, 6))
    else:
        fig = ax.get_figure()
        if fig is None:
            raise ValueError("The provided Axes instance is not attached to a Figure")

    # Draw horizontal baseline (prevalence / chance level) if provided
    if baseline is not None:
        ax.axhline(
            y=baseline,
            linestyle=baseline_linestyle,
            color=baseline_color,
            label=f"Baseline ({baseline:.2f})",
        )

    # Clean line_kwargs to prevent parameter collisions
    for key in ("color", "linestyle", "linewidth", "label"):
        line_kwargs.pop(key, None)

    # Draw main PR curve line (Recall on X-axis, Precision on Y-axis)
    ax.plot(
        recall,
        precision,
        color=color,
        linestyle=linestyle,
        linewidth=linewidth,
        label=label,
        **line_kwargs,
    )

    # Draw confidence interval shading if bounds are supplied
    if lower_ci is not None and upper_ci is not None:
        ax.fill_between(
            recall,
            lower_ci,
            upper_ci,
            color=ci_color or color,
            alpha=ci_alpha,
            label=f"{label} 95% CI",
        )

    # Format axis bounds and labels
    ax.set_xlabel("Recall (Sensitivity)", fontweight="bold")
    ax.set_ylabel("Precision (PPV)", fontweight="bold")
    ax.set_xlim(xmin=-0.02, xmax=1.02)
    ax.set_ylim(ymin=-0.02, ymax=1.02)

    if title:
        ax.set_title(title, fontweight="bold")

    if not show_spines:
        ax.spines["top"].set_visible(False)
        ax.spines["right"].set_visible(False)

    ax.legend(loc="lower left", frameon=False)

    return fig, ax

draw_reliability_diagram

draw_reliability_diagram(
    prob_true: ndarray,
    prob_pred: ndarray,
    probas: ndarray | None = None,
    lower_ci: ndarray | None = None,
    upper_ci: ndarray | None = None,
    label: str = "Model",
    dist_n_bins: int = 20,
    dist_yscale: str = "linear",
    auto_inset: bool = True,
    ax: Axes | None = None,
    color: str = primary_color,
    ci_color: str | None = None,
    ci_alpha: float = ci_alpha,
    linestyle: str = "-",
    linewidth: float = linewidth,
    marker: str | None = "o",
    ref_linestyle: str = "--",
    ref_color: str = "black",
    title: str | None = None,
    show_spines: bool = show_spines,
    **line_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Render a reliability diagram with optional prediction distribution.

Parameters:

Name	Type	Description	Default
`prob_true`	`ndarray`	Fraction of positives or spline-calibrated probabilities.	required
`prob_pred`	`ndarray`	Mean predicted probabilities or evaluation grid points.	required
`probas`	`ndarray`	Raw predicted probabilities of shape (n_samples, 2) or (n_samples,). If provided, renders a histogram of predicted probabilities underneath the graph.	`None`
`lower_ci`	`ndarray`	Lower bound array for 95% confidence interval shading.	`None`
`upper_ci`	`ndarray`	Upper bound array for 95% confidence interval shading.	`None`
`label`	`str`	Legend label for the plotted curve.	`"Model"`
`dist_n_bins`	`int`	Number of bins for the underlying probability distribution histogram.	`20`
`dist_yscale`	`str`	Scale to use for the y-axis (e.g. linear, log, etc.)	`"linear"`
`auto_inset`	`bool`	Whether to automatically render a zoomed inset box when maximum predicted probability < 0.4.	`True`
`ax`	`Axes`	Pre-existing Matplotlib axes instance. If None, a new figure and axes are created.	`None`
`color`	`str`	Color specifier for main calibration elements and distribution bars.	`_DEFAULT_THEME.primary_color`
`ci_color`	`str`	Custom color specifier for confidence interval shading. Defaults to `color`.	`None`
`ci_alpha`	`float`	Opacity level for confidence interval shaded region [0.0, 1.0].	`_DEFAULT_THEME.ci_alpha`
`linestyle`	`str`	Line style for the calibration curve.	`"-"`
`linewidth`	`float`	Width in points for the calibration line.	`_DEFAULT_THEME.linewidth`
`marker`	`str or None`	Marker symbol for calibration points.	`"o"`
`ref_linestyle`	`str`	Line style for the perfect calibration reference line.	`"--"`
`ref_color`	`str`	Color specifier for the reference line.	`"black"`
`title`	`str`	Axes title text.	`None`
`show_spines`	`bool`	Whether to keep top and right border spines visible.	`_DEFAULT_THEME.show_spines`
`**line_kwargs`	`Any`	Additional Matplotlib keyword arguments forwarded to `ax.plot`.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure or SubFigure`	Parent Matplotlib figure containing the axes.
`ax`	`Axes`	Matplotlib axes containing the main calibration diagram.

Source code in medpipe/visualisation/plots.py

def draw_reliability_diagram(
    prob_true: np.ndarray,
    prob_pred: np.ndarray,
    probas: np.ndarray | None = None,
    lower_ci: np.ndarray | None = None,
    upper_ci: np.ndarray | None = None,
    label: str = "Model",
    dist_n_bins: int = 20,
    dist_yscale: str = "linear",
    auto_inset: bool = True,
    ax: Axes | None = None,
    color: str = _DEFAULT_THEME.primary_color,
    ci_color: str | None = None,
    ci_alpha: float = _DEFAULT_THEME.ci_alpha,
    linestyle: str = "-",
    linewidth: float = _DEFAULT_THEME.linewidth,
    marker: str | None = "o",
    ref_linestyle: str = "--",
    ref_color: str = "black",
    title: str | None = None,
    show_spines: bool = _DEFAULT_THEME.show_spines,
    **line_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Render a reliability diagram with optional prediction distribution.

    Parameters
    ----------
    prob_true : np.ndarray
        Fraction of positives or spline-calibrated probabilities.
    prob_pred : np.ndarray
        Mean predicted probabilities or evaluation grid points.
    probas : np.ndarray, optional
        Raw predicted probabilities of shape (n_samples, 2) or (n_samples,).
        If provided, renders a histogram of predicted probabilities underneath
        the graph.
    lower_ci : np.ndarray, optional
        Lower bound array for 95% confidence interval shading.
    upper_ci : np.ndarray, optional
        Upper bound array for 95% confidence interval shading.
    label : str, default="Model"
        Legend label for the plotted curve.
    dist_n_bins : int, default=20
        Number of bins for the underlying probability distribution histogram.
    dist_yscale : str, default="linear"
        Scale to use for the y-axis (e.g. linear, log, etc.)
    auto_inset : bool, default=True
        Whether to automatically render a zoomed inset box when maximum
        predicted probability < 0.4.
    ax : matplotlib.axes.Axes, optional
        Pre-existing Matplotlib axes instance. If None, a new figure and axes
        are created.
    color : str, default=_DEFAULT_THEME.primary_color
        Color specifier for main calibration elements and distribution bars.
    ci_color : str, optional
        Custom color specifier for confidence interval shading. Defaults to `color`.
    ci_alpha : float, default=_DEFAULT_THEME.ci_alpha
        Opacity level for confidence interval shaded region [0.0, 1.0].
    linestyle : str, default="-"
        Line style for the calibration curve.
    linewidth : float, default=_DEFAULT_THEME.linewidth
        Width in points for the calibration line.
    marker : str or None, default="o"
        Marker symbol for calibration points.
    ref_linestyle : str, default="--"
        Line style for the perfect calibration reference line.
    ref_color : str, default="black"
        Color specifier for the reference line.
    title : str, optional
        Axes title text.
    show_spines : bool, default=_DEFAULT_THEME.show_spines
        Whether to keep top and right border spines visible.
    **line_kwargs : Any
        Additional Matplotlib keyword arguments forwarded to `ax.plot`.

    Returns
    -------
    fig : matplotlib.figure.Figure or matplotlib.figure.SubFigure
        Parent Matplotlib figure containing the axes.
    ax : matplotlib.axes.Axes
        Matplotlib axes containing the main calibration diagram.

    """
    fig: Figure | SubFigure | None
    if ax is None:
        fig, ax = plt.subplots(figsize=(6, 6))
    else:
        fig = ax.get_figure()
        if fig is None:
            raise ValueError("The provided Axes instance is not attached to a Figure")

    # Clean line_kwargs to prevent parameter collisions
    for key in ("color", "linestyle", "linewidth", "marker", "label"):
        line_kwargs.pop(key, None)

    # 1. Reference Line
    ax.plot(
        [0, 1],
        [0, 1],
        linestyle=ref_linestyle,
        color=ref_color,
        label="Perfectly calibrated",
    )

    # 2. Calibration Line & CI Fills
    plot_kwargs: dict[str, Any] = {
        "color": color,
        "linestyle": linestyle,
        "linewidth": linewidth,
        "label": label,
        **line_kwargs,
    }
    if marker:
        plot_kwargs["marker"] = marker

    ax.plot(prob_pred, prob_true, **plot_kwargs)

    if lower_ci is not None and upper_ci is not None:
        ax.fill_between(
            prob_pred,
            lower_ci,
            upper_ci,
            color=ci_color or color,
            alpha=ci_alpha,
            label=f"{label} 95% CI",
        )

    # 3. Axis Formatting
    ax.set_ylabel("Fraction of positives", fontweight="bold")
    ax.set_xlim(xmin=-0.02, xmax=1.02)
    ax.set_ylim(ymin=-0.02, ymax=1.02)

    if title:
        ax.set_title(title, fontweight="bold")

    if not show_spines:
        ax.spines["top"].set_visible(False)
        ax.spines["right"].set_visible(False)

    # 4. Bottom Distribution Subplot
    if probas is not None:
        if probas.ndim == 2:
            probas = probas[:, 1]

        ax.tick_params(labelbottom=False)
        ax.set_xlabel("")

        divider = make_axes_locatable(ax)
        ax_dist = divider.append_axes("bottom", size="25%", pad=0.15, sharex=ax)

        bins = np.linspace(0.0, 1.0, dist_n_bins + 1)
        ax_dist.hist(
            probas,
            bins=bins,
            color=color,
            edgecolor="black",
        )
        ax_dist.set_xlabel("Mean predicted probability", fontweight="bold")
        ax_dist.set_ylabel("Count", fontweight="bold")
        ax_dist.set_yscale(dist_yscale)
        ax_dist.set_ylim(bottom=1, top=30e5)

        if not show_spines:
            ax_dist.spines["top"].set_visible(False)
            ax_dist.spines["right"].set_visible(False)
    else:
        ax.set_xlabel("Mean predicted probability", fontweight="bold")

    ax.legend(loc="lower right", frameon=False)

    return fig, ax

draw_strata_heatmap

draw_strata_heatmap(
    plot_data: ndarray,
    text_data: ndarray,
    row_labels: list[str],
    col_labels: list[str],
    colorbar_label: str = "|$\\mathbf{\\Delta}$ Score|",
    vmax: float = 0.1,
    ax: Axes | None = None,
    cmap: str = "cividis",
    title: str | None = None,
    **heatmap_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Render a pre-computed strata heatmap matrix onto an Axes.

Parameters:

Name	Type	Description	Default
`plot_data`	`ndarray`	2D matrix of delta values driving heatmap cell colors.	required
`text_data`	`ndarray`	2D matrix of absolute score values displayed as cell text.	required
`row_labels`	`list of str`	Y-axis tick labels (e.g., ['All strata', 'Male', 'Female']).	required
`col_labels`	`list of str`	X-axis tick labels (e.g., ['Mortality', 'Readmission']).	required
`colorbar_label`	`str`	Label text for the colorbar legend.	`r"\|$\Delta$ Score\|"`
`vmax`	`float`	Maximum color scale limit for imshow.	`0.1`
`ax`	`Axes`	Pre-existing Matplotlib axes instance. If None, a new figure and axes are created.	`None`
`cmap`	`str`	Matplotlib colormap identifier.	`"cividis"`
`title`	`str`	Axes title text.	`None`
`**heatmap_kwargs`	`Any`	Additional keyword arguments forwarded to `ax.imshow`.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure or SubFigure`	Parent Matplotlib figure containing the axes.
`ax`	`Axes`	Matplotlib axes containing the rendered heatmap.

Source code in medpipe/visualisation/plots.py

def draw_strata_heatmap(
    plot_data: np.ndarray,
    text_data: np.ndarray,
    row_labels: list[str],
    col_labels: list[str],
    colorbar_label: str = r"|$\mathbf{\Delta}$ Score|",
    vmax: float = 0.1,
    ax: Axes | None = None,
    cmap: str = "cividis",
    title: str | None = None,
    **heatmap_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Render a pre-computed strata heatmap matrix onto an Axes.

    Parameters
    ----------
    plot_data : np.ndarray
        2D matrix of delta values driving heatmap cell colors.
    text_data : np.ndarray
        2D matrix of absolute score values displayed as cell text.
    row_labels : list of str
        Y-axis tick labels (e.g., ['All strata', 'Male', 'Female']).
    col_labels : list of str
        X-axis tick labels (e.g., ['Mortality', 'Readmission']).
    colorbar_label : str, default=r"|$\\Delta$ Score|"
        Label text for the colorbar legend.
    vmax : float, default=0.1
        Maximum color scale limit for imshow.
    ax : matplotlib.axes.Axes, optional
        Pre-existing Matplotlib axes instance. If None, a new figure and axes
        are created.
    cmap : str, default="cividis"
        Matplotlib colormap identifier.
    title : str, optional
        Axes title text.
    **heatmap_kwargs : Any
        Additional keyword arguments forwarded to `ax.imshow`.

    Returns
    -------
    fig : matplotlib.figure.Figure or matplotlib.figure.SubFigure
        Parent Matplotlib figure containing the axes.
    ax : matplotlib.axes.Axes
        Matplotlib axes containing the rendered heatmap.

    """
    fig: Figure | SubFigure | None
    if ax is None:
        fig, ax = plt.subplots(figsize=(10, 6))
    else:
        fig = ax.get_figure()
        if fig is None:
            raise ValueError("The provided Axes instance is not attached to a Figure")

    n_rows, n_cols = plot_data.shape

    # Clean kwargs
    for key in ("cmap", "aspect", "vmax"):
        heatmap_kwargs.pop(key, None)

    im = ax.imshow(plot_data, cmap=cmap, aspect="equal", vmax=vmax, **heatmap_kwargs)

    fig.colorbar(im, ax=ax, shrink=0.8, extend="max", label=colorbar_label)

    ax.set_yticks(np.arange(n_rows), labels=row_labels)
    ax.set_xticks(
        np.arange(n_cols),
        labels=col_labels,
        rotation=-30,
        rotation_mode="anchor",
        ha="left",
    )
    ax.set_ylabel("Strata", fontweight="bold")
    ax.set_xlabel("Outcomes", fontweight="bold")

    # Render cell text annotations
    for i in range(n_cols):
        for j in range(n_rows):
            colour = "k" if np.abs(plot_data[j, i]) >= 0.8 * vmax else "w"
            ax.text(
                i,
                j,
                f"{text_data[j, i]:.2f}",
                ha="center",
                va="center",
                color=colour,
                fontsize=6,
                fontweight="bold",
            )

    ax.spines[:].set_visible(False)

    # Grid divider lines between cells
    ax.set_yticks(np.arange(n_rows + 1) - 0.5, minor=True)
    ax.set_xticks(np.arange(n_cols + 1) - 0.5, minor=True)
    ax.grid(which="minor", color="w", linestyle="-", linewidth=1)
    ax.tick_params(which="minor", bottom=False, left=False)

    if title:
        ax.set_title(title, fontweight="bold")

    return fig, ax

draw_coverage_curve

draw_coverage_curve(
    coverage_levels: ndarray,
    empirical_coverage: ndarray,
    lower_ci: ndarray | None = None,
    upper_ci: ndarray | None = None,
    label: str = "Model",
    ax: Axes | None = None,
    color: str = primary_color,
    ci_color: str | None = None,
    ci_alpha: float = ci_alpha,
    linestyle: str = "-",
    linewidth: float = linewidth,
    marker: str | None = "o",
    ideal: bool = True,
    ideal_linestyle: str = "--",
    ideal_color: str = "black",
    title: str | None = None,
    show_spines: bool = show_spines,
    **line_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Render a coverage reliability curve (nominal vs. empirical coverage).

Parameters:

Name	Type	Description	Default
`coverage_levels`	`ndarray`	Nominal central-interval coverage levels in percent (e.g. 90 for a 90% interval).	required
`empirical_coverage`	`ndarray`	Empirical coverage in percent at each nominal coverage level.	required
`lower_ci`	`ndarray`	Lower bound array for 95% confidence interval error bars.	`None`
`upper_ci`	`ndarray`	Upper bound array for 95% confidence interval error bars.	`None`
`label`	`str`	Legend label for the plotted curve.	`"Model"`
`ax`	`Axes`	Pre-existing Matplotlib axes instance. If None, a new figure and axes are created.	`None`
`color`	`str`	Color specifier for the main curve and default error bar color.	`_DEFAULT_THEME.primary_color`
`ci_color`	`str`	Custom color specifier for confidence interval error bars. Defaults to `color`.	`None`
`ci_alpha`	`float`	Opacity level for confidence interval error bars [0.0, 1.0].	`_DEFAULT_THEME.ci_alpha`
`linestyle`	`str`	Line style for the coverage curve.	`"-"`
`linewidth`	`float`	Width in points for the coverage curve line.	`_DEFAULT_THEME.linewidth`
`marker`	`str or None`	Marker symbol for coverage points.	`"o"`
`ideal_linestyle`	`str`	Line style for the perfect-coverage diagonal reference line.	`"--"`
`ideal_color`	`str`	Color specifier for the reference line.	`"black"`
`title`	`str`	Axes title text.	`None`
`show_spines`	`bool`	Whether to keep the top and right border spines visible.	`_DEFAULT_THEME.show_spines`
`**line_kwargs`	`Any`	Additional Matplotlib keyword arguments forwarded to `ax.plot`.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure or SubFigure`	Parent Matplotlib figure containing the axes.
`ax`	`Axes`	Matplotlib axes containing the rendered coverage curve.

Source code in medpipe/visualisation/plots.py

def draw_coverage_curve(
    coverage_levels: np.ndarray,
    empirical_coverage: np.ndarray,
    lower_ci: np.ndarray | None = None,
    upper_ci: np.ndarray | None = None,
    label: str = "Model",
    ax: Axes | None = None,
    color: str = _DEFAULT_THEME.primary_color,
    ci_color: str | None = None,
    ci_alpha: float = _DEFAULT_THEME.ci_alpha,
    linestyle: str = "-",
    linewidth: float = _DEFAULT_THEME.linewidth,
    marker: str | None = "o",
    ideal: bool = True,
    ideal_linestyle: str = "--",
    ideal_color: str = "black",
    title: str | None = None,
    show_spines: bool = _DEFAULT_THEME.show_spines,
    **line_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Render a coverage reliability curve (nominal vs. empirical coverage).

    Parameters
    ----------
    coverage_levels : np.ndarray
        Nominal central-interval coverage levels in percent (e.g. 90 for a
        90% interval).
    empirical_coverage : np.ndarray
        Empirical coverage in percent at each nominal coverage level.
    lower_ci : np.ndarray, optional
        Lower bound array for 95% confidence interval error bars.
    upper_ci : np.ndarray, optional
        Upper bound array for 95% confidence interval error bars.
    label : str, default="Model"
        Legend label for the plotted curve.
    ax : matplotlib.axes.Axes, optional
        Pre-existing Matplotlib axes instance. If None, a new figure and axes
        are created.
    color : str, default=_DEFAULT_THEME.primary_color
        Color specifier for the main curve and default error bar color.
    ci_color : str, optional
        Custom color specifier for confidence interval error bars. Defaults to `color`.
    ci_alpha : float, default=_DEFAULT_THEME.ci_alpha
        Opacity level for confidence interval error bars [0.0, 1.0].
    linestyle : str, default="-"
        Line style for the coverage curve.
    linewidth : float, default=_DEFAULT_THEME.linewidth
        Width in points for the coverage curve line.
    marker : str or None, default="o"
        Marker symbol for coverage points.
    ideal_linestyle : str, default="--"
        Line style for the perfect-coverage diagonal reference line.
    ideal_color : str, default="black"
        Color specifier for the reference line.
    title : str, optional
        Axes title text.
    show_spines : bool, default=_DEFAULT_THEME.show_spines
        Whether to keep the top and right border spines visible.
    **line_kwargs : Any
        Additional Matplotlib keyword arguments forwarded to `ax.plot`.

    Returns
    -------
    fig : matplotlib.figure.Figure or matplotlib.figure.SubFigure
        Parent Matplotlib figure containing the axes.
    ax : matplotlib.axes.Axes
        Matplotlib axes containing the rendered coverage curve.

    """
    fig: Figure | SubFigure | None
    if ax is None:
        fig, ax = plt.subplots(figsize=(6, 6))
    else:
        fig = ax.get_figure()
        if fig is None:
            raise ValueError("The provided Axes instance is not attached to a Figure")

    if ideal:
        ax.plot(
            [0, 100],
            [0, 100],
            linestyle=ideal_linestyle,
            color=ideal_color,
            label="Ideal",
        )

    for key in ("color", "linestyle", "linewidth", "marker", "label"):
        line_kwargs.pop(key, None)

    plot_kwargs: dict[str, Any] = {
        "color": color,
        "linestyle": linestyle,
        "linewidth": linewidth,
        "label": label,
        **line_kwargs,
    }
    if marker:
        plot_kwargs["marker"] = marker

    if lower_ci is not None and upper_ci is not None:
        ax.errorbar(
            coverage_levels,
            empirical_coverage,
            yerr=[
                np.clip(empirical_coverage - lower_ci, 0, None),
                np.clip(upper_ci - empirical_coverage, 0, None),
            ],
            ecolor=ci_color or color,
            elinewidth=linewidth,
            capsize=4,
            alpha=ci_alpha,
            **plot_kwargs,
        )

    else:
        ax.plot(coverage_levels, empirical_coverage, **plot_kwargs)

    ax.set_xlabel("Nominal coverage (%)", fontweight="bold")
    ax.set_ylabel("Empirical coverage (%)", fontweight="bold")
    ax.set_xlim(0, 100)
    ax.set_ylim(0, 100)

    if title:
        ax.set_title(title, fontweight="bold")

    if not show_spines:
        ax.spines["top"].set_visible(False)
        ax.spines["right"].set_visible(False)

    ax.legend(loc="lower right", frameon=False)

    return fig, ax

draw_sharpness_curve

draw_sharpness_curve(
    coverage_levels: ndarray,
    sharpness_values: ndarray,
    lower_ci: ndarray | None = None,
    upper_ci: ndarray | None = None,
    label: str = "Model",
    ax: Axes | None = None,
    color: str = primary_color,
    ci_color: str | None = None,
    ci_alpha: float = ci_alpha,
    linestyle: str = "-",
    linewidth: float = linewidth,
    marker: str | None = "o",
    title: str | None = None,
    show_spines: bool = show_spines,
    **line_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Render a sharpness curve (mean prediction interval width vs. nominal coverage).

Parameters:

Name	Type	Description	Default
`coverage_levels`	`ndarray`	Nominal central-interval coverage levels in percent.	required
`sharpness_values`	`ndarray`	Mean prediction interval width at each nominal coverage level.	required
`lower_ci`	`ndarray`	Lower bound array for 95% confidence interval error bars.	`None`
`upper_ci`	`ndarray`	Upper bound array for 95% confidence interval error bars.	`None`
`label`	`str`	Legend label for the plotted curve.	`"Model"`
`ax`	`Axes`	Pre-existing Matplotlib axes instance. If None, a new figure and axes are created.	`None`
`color`	`str`	Color specifier for the main curve and default error bar color.	`_DEFAULT_THEME.primary_color`
`ci_color`	`str`	Custom color specifier for confidence interval error bars. Defaults to `color`.	`None`
`ci_alpha`	`float`	Opacity level for confidence interval error bars [0.0, 1.0].	`_DEFAULT_THEME.ci_alpha`
`linestyle`	`str`	Line style for the sharpness curve.	`"-"`
`linewidth`	`float`	Width in points for the sharpness curve line.	`_DEFAULT_THEME.linewidth`
`marker`	`str or None`	Marker symbol for sharpness points.	`"o"`
`title`	`str`	Axes title text.	`None`
`show_spines`	`bool`	Whether to keep the top and right border spines visible.	`_DEFAULT_THEME.show_spines`
`**line_kwargs`	`Any`	Additional Matplotlib keyword arguments forwarded to `ax.plot`.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure or SubFigure`	Parent Matplotlib figure containing the axes.
`ax`	`Axes`	Matplotlib axes containing the rendered sharpness curve.

Source code in medpipe/visualisation/plots.py

def draw_sharpness_curve(
    coverage_levels: np.ndarray,
    sharpness_values: np.ndarray,
    lower_ci: np.ndarray | None = None,
    upper_ci: np.ndarray | None = None,
    label: str = "Model",
    ax: Axes | None = None,
    color: str = _DEFAULT_THEME.primary_color,
    ci_color: str | None = None,
    ci_alpha: float = _DEFAULT_THEME.ci_alpha,
    linestyle: str = "-",
    linewidth: float = _DEFAULT_THEME.linewidth,
    marker: str | None = "o",
    title: str | None = None,
    show_spines: bool = _DEFAULT_THEME.show_spines,
    **line_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Render a sharpness curve (mean prediction interval width vs. nominal
    coverage).

    Parameters
    ----------
    coverage_levels : np.ndarray
        Nominal central-interval coverage levels in percent.
    sharpness_values : np.ndarray
        Mean prediction interval width at each nominal coverage level.
    lower_ci : np.ndarray, optional
        Lower bound array for 95% confidence interval error bars.
    upper_ci : np.ndarray, optional
        Upper bound array for 95% confidence interval error bars.
    label : str, default="Model"
        Legend label for the plotted curve.
    ax : matplotlib.axes.Axes, optional
        Pre-existing Matplotlib axes instance. If None, a new figure and axes
        are created.
    color : str, default=_DEFAULT_THEME.primary_color
        Color specifier for the main curve and default error bar color.
    ci_color : str, optional
        Custom color specifier for confidence interval error bars. Defaults to `color`.
    ci_alpha : float, default=_DEFAULT_THEME.ci_alpha
        Opacity level for confidence interval error bars [0.0, 1.0].
    linestyle : str, default="-"
        Line style for the sharpness curve.
    linewidth : float, default=_DEFAULT_THEME.linewidth
        Width in points for the sharpness curve line.
    marker : str or None, default="o"
        Marker symbol for sharpness points.
    title : str, optional
        Axes title text.
    show_spines : bool, default=_DEFAULT_THEME.show_spines
        Whether to keep the top and right border spines visible.
    **line_kwargs : Any
        Additional Matplotlib keyword arguments forwarded to `ax.plot`.

    Returns
    -------
    fig : matplotlib.figure.Figure or matplotlib.figure.SubFigure
        Parent Matplotlib figure containing the axes.
    ax : matplotlib.axes.Axes
        Matplotlib axes containing the rendered sharpness curve.

    """
    fig: Figure | SubFigure | None
    if ax is None:
        fig, ax = plt.subplots(figsize=(6, 6))
    else:
        fig = ax.get_figure()
        if fig is None:
            raise ValueError("The provided Axes instance is not attached to a Figure")

    for key in ("color", "linestyle", "linewidth", "marker", "label"):
        line_kwargs.pop(key, None)

    plot_kwargs: dict[str, Any] = {
        "color": color,
        "linestyle": linestyle,
        "linewidth": linewidth,
        "label": label,
        **line_kwargs,
    }
    if marker:
        plot_kwargs["marker"] = marker

    if lower_ci is not None and upper_ci is not None:
        ax.errorbar(
            coverage_levels,
            sharpness_values,
            yerr=[
                np.clip(sharpness_values - lower_ci, 0, None),
                np.clip(upper_ci - sharpness_values, 0, None),
            ],
            ecolor=ci_color or color,
            elinewidth=linewidth,
            capsize=4,
            alpha=ci_alpha,
            **plot_kwargs,
        )
    else:
        ax.plot(coverage_levels, sharpness_values, **plot_kwargs)

    ax.set_xlabel("Nominal coverage (%)", fontweight="bold")
    ax.set_ylabel("Mean interval width", fontweight="bold")
    ax.set_xlim(0, 100)

    if title:
        ax.set_title(title, fontweight="bold")

    if not show_spines:
        ax.spines["top"].set_visible(False)
        ax.spines["right"].set_visible(False)

    ax.legend(loc="upper left", frameon=False)

    return fig, ax

draw_winkler_curve

draw_winkler_curve(
    coverage_levels: ndarray,
    winkler_values: ndarray,
    lower_ci: ndarray | None = None,
    upper_ci: ndarray | None = None,
    label: str = "Model",
    ax: Axes | None = None,
    color: str = primary_color,
    ci_color: str | None = None,
    ci_alpha: float = ci_alpha,
    linestyle: str = "-",
    linewidth: float = linewidth,
    marker: str | None = "o",
    title: str | None = None,
    show_spines: bool = show_spines,
    **line_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Render a Winkler (interval) score curve across nominal coverage levels.

Parameters:

Name	Type	Description	Default
`coverage_levels`	`ndarray`	Nominal central-interval coverage levels in percent.	required
`winkler_values`	`ndarray`	Mean Winkler score at each nominal coverage level (lower is better).	required
`lower_ci`	`ndarray`	Lower bound array for 95% confidence interval error bars.	`None`
`upper_ci`	`ndarray`	Upper bound array for 95% confidence interval error bars.	`None`
`label`	`str`	Legend label for the plotted curve.	`"Model"`
`ax`	`Axes`	Pre-existing Matplotlib axes instance. If None, a new figure and axes are created.	`None`
`color`	`str`	Color specifier for the main curve and default error bar color.	`_DEFAULT_THEME.primary_color`
`ci_color`	`str`	Custom color specifier for confidence interval shading. Defaults to `color`.	`None`
`ci_alpha`	`float`	Opacity level for confidence interval error bars [0.0, 1.0].	`_DEFAULT_THEME.ci_alpha`
`linestyle`	`str`	Line style for the Winkler score curve.	`"-"`
`linewidth`	`float`	Width in points for the Winkler score curve line.	`_DEFAULT_THEME.linewidth`
`marker`	`str or None`	Marker symbol for Winkler score points.	`"o"`
`title`	`str`	Axes title text.	`None`
`show_spines`	`bool`	Whether to keep the top and right border spines visible.	`_DEFAULT_THEME.show_spines`
`**line_kwargs`	`Any`	Additional Matplotlib keyword arguments forwarded to `ax.errorbar` (or `ax.plot` when no confidence interval is given).	`{}`

Returns:

Name	Type	Description
`fig`	`Figure or SubFigure`	Parent Matplotlib figure containing the axes.
`ax`	`Axes`	Matplotlib axes containing the rendered Winkler score curve.

Source code in medpipe/visualisation/plots.py

def draw_winkler_curve(
    coverage_levels: np.ndarray,
    winkler_values: np.ndarray,
    lower_ci: np.ndarray | None = None,
    upper_ci: np.ndarray | None = None,
    label: str = "Model",
    ax: Axes | None = None,
    color: str = _DEFAULT_THEME.primary_color,
    ci_color: str | None = None,
    ci_alpha: float = _DEFAULT_THEME.ci_alpha,
    linestyle: str = "-",
    linewidth: float = _DEFAULT_THEME.linewidth,
    marker: str | None = "o",
    title: str | None = None,
    show_spines: bool = _DEFAULT_THEME.show_spines,
    **line_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Render a Winkler (interval) score curve across nominal coverage levels.

    Parameters
    ----------
    coverage_levels : np.ndarray
        Nominal central-interval coverage levels in percent.
    winkler_values : np.ndarray
        Mean Winkler score at each nominal coverage level (lower is better).
    lower_ci : np.ndarray, optional
        Lower bound array for 95% confidence interval error bars.
    upper_ci : np.ndarray, optional
        Upper bound array for 95% confidence interval error bars.
    label : str, default="Model"
        Legend label for the plotted curve.
    ax : matplotlib.axes.Axes, optional
        Pre-existing Matplotlib axes instance. If None, a new figure and axes
        are created.
    color : str, default=_DEFAULT_THEME.primary_color
        Color specifier for the main curve and default error bar color.
    ci_color : str, optional
        Custom color specifier for confidence interval shading. Defaults to `color`.
    ci_alpha : float, default=_DEFAULT_THEME.ci_alpha
        Opacity level for confidence interval error bars [0.0, 1.0].
    linestyle : str, default="-"
        Line style for the Winkler score curve.
    linewidth : float, default=_DEFAULT_THEME.linewidth
        Width in points for the Winkler score curve line.
    marker : str or None, default="o"
        Marker symbol for Winkler score points.
    title : str, optional
        Axes title text.
    show_spines : bool, default=_DEFAULT_THEME.show_spines
        Whether to keep the top and right border spines visible.
    **line_kwargs : Any
        Additional Matplotlib keyword arguments forwarded to `ax.errorbar`
        (or `ax.plot` when no confidence interval is given).

    Returns
    -------
    fig : matplotlib.figure.Figure or matplotlib.figure.SubFigure
        Parent Matplotlib figure containing the axes.
    ax : matplotlib.axes.Axes
        Matplotlib axes containing the rendered Winkler score curve.

    """
    fig: Figure | SubFigure | None
    if ax is None:
        fig, ax = plt.subplots(figsize=(6, 6))
    else:
        fig = ax.get_figure()
        if fig is None:
            raise ValueError("The provided Axes instance is not attached to a Figure")

    for key in ("color", "linestyle", "linewidth", "marker", "label"):
        line_kwargs.pop(key, None)

    plot_kwargs: dict[str, Any] = {
        "color": color,
        "linestyle": linestyle,
        "linewidth": linewidth,
        "label": label,
        **line_kwargs,
    }
    if marker:
        plot_kwargs["marker"] = marker

    if lower_ci is not None and upper_ci is not None:
        ax.errorbar(
            coverage_levels,
            winkler_values,
            yerr=[
                np.clip(winkler_values - lower_ci, 0, None),
                np.clip(upper_ci - winkler_values, 0, None),
            ],
            ecolor=ci_color or color,
            elinewidth=linewidth,
            capsize=4,
            alpha=ci_alpha,
            **plot_kwargs,
        )
    else:
        ax.plot(coverage_levels, winkler_values, **plot_kwargs)

    ax.set_xlabel("Nominal coverage (%)", fontweight="bold")
    ax.set_ylabel("Winkler score", fontweight="bold")
    ax.set_xlim(0, 100)

    if title:
        ax.set_title(title, fontweight="bold")

    if not show_spines:
        ax.spines["top"].set_visible(False)
        ax.spines["right"].set_visible(False)

    ax.legend(loc="upper left", frameon=False)

    return fig, ax

draw_marginal_calibration

draw_marginal_calibration(
    grid_y: ndarray,
    diff: ndarray,
    label: str = "Model",
    ax: Axes | None = None,
    color: str = primary_color,
    linestyle: str = "-",
    linewidth: float = linewidth,
    zero_linestyle: str = "--",
    zero_color: str = "black",
    title: str | None = None,
    show_spines: bool = show_spines,
    **line_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Render a marginal calibration curve (empirical minus mean-predicted CDF).

Parameters:

Name	Type	Description	Default
`grid_y`	`ndarray`	Target-value grid points along the X-axis.	required
`diff`	`ndarray`	Difference between the empirical CDF and the mean predicted CDF at each grid point (empirical - mean predicted).	required
`label`	`str`	Legend label for the plotted curve.	`"Model"`
`ax`	`Axes`	Pre-existing Matplotlib axes instance. If None, a new figure and axes are created.	`None`
`color`	`str`	Color specifier for the curve.	`_DEFAULT_THEME.primary_color`
`linestyle`	`str`	Line style for the curve.	`"-"`
`linewidth`	`float`	Width in points for the curve line.	`_DEFAULT_THEME.linewidth`
`zero_linestyle`	`str`	Line style for the zero (perfect calibration) reference line.	`"--"`
`zero_color`	`str`	Color specifier for the zero reference line.	`"black"`
`title`	`str`	Axes title text.	`None`
`show_spines`	`bool`	Whether to keep the top and right border spines visible.	`_DEFAULT_THEME.show_spines`
`**line_kwargs`	`Any`	Additional Matplotlib keyword arguments forwarded to `ax.plot`.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure or SubFigure`	Parent Matplotlib figure containing the axes.
`ax`	`Axes`	Matplotlib axes containing the rendered marginal calibration curve.

Source code in medpipe/visualisation/plots.py

def draw_marginal_calibration(
    grid_y: np.ndarray,
    diff: np.ndarray,
    label: str = "Model",
    ax: Axes | None = None,
    color: str = _DEFAULT_THEME.primary_color,
    linestyle: str = "-",
    linewidth: float = _DEFAULT_THEME.linewidth,
    zero_linestyle: str = "--",
    zero_color: str = "black",
    title: str | None = None,
    show_spines: bool = _DEFAULT_THEME.show_spines,
    **line_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Render a marginal calibration curve (empirical minus mean-predicted CDF).

    Parameters
    ----------
    grid_y : np.ndarray
        Target-value grid points along the X-axis.
    diff : np.ndarray
        Difference between the empirical CDF and the mean predicted CDF at
        each grid point (empirical - mean predicted).
    label : str, default="Model"
        Legend label for the plotted curve.
    ax : matplotlib.axes.Axes, optional
        Pre-existing Matplotlib axes instance. If None, a new figure and axes
        are created.
    color : str, default=_DEFAULT_THEME.primary_color
        Color specifier for the curve.
    linestyle : str, default="-"
        Line style for the curve.
    linewidth : float, default=_DEFAULT_THEME.linewidth
        Width in points for the curve line.
    zero_linestyle : str, default="--"
        Line style for the zero (perfect calibration) reference line.
    zero_color : str, default="black"
        Color specifier for the zero reference line.
    title : str, optional
        Axes title text.
    show_spines : bool, default=_DEFAULT_THEME.show_spines
        Whether to keep the top and right border spines visible.
    **line_kwargs : Any
        Additional Matplotlib keyword arguments forwarded to `ax.plot`.

    Returns
    -------
    fig : matplotlib.figure.Figure or matplotlib.figure.SubFigure
        Parent Matplotlib figure containing the axes.
    ax : matplotlib.axes.Axes
        Matplotlib axes containing the rendered marginal calibration curve.

    """
    fig: Figure | SubFigure | None
    if ax is None:
        fig, ax = plt.subplots(figsize=(7, 5))
    else:
        fig = ax.get_figure()
        if fig is None:
            raise ValueError("The provided Axes instance is not attached to a Figure")

    for key in ("color", "linestyle", "linewidth", "label"):
        line_kwargs.pop(key, None)

    ax.plot(
        grid_y,
        diff,
        color=color,
        linestyle=linestyle,
        linewidth=linewidth,
        label=label,
        **line_kwargs,
    )
    ax.axhline(0.0, color=zero_color, linestyle=zero_linestyle, linewidth=1.5)

    ax.set_xlabel("Target value", fontweight="bold")
    ax.set_ylabel(r"eCDF - $\mathbf{\overline{CDF}}$", fontweight="bold")

    if title:
        ax.set_title(title, fontweight="bold")

    if not show_spines:
        ax.spines["top"].set_visible(False)
        ax.spines["right"].set_visible(False)

    return fig, ax

draw_pit_histogram

draw_pit_histogram(
    bin_centres: ndarray,
    hist_values: ndarray,
    alpha_score: float,
    n_bins: int = 20,
    label: str = "Model",
    ax: Axes | None = None,
    color: str = primary_color,
    edgecolor: str = "black",
    uniform_linestyle: str = "--",
    uniform_color: str = "black",
    title: str | None = None,
    show_spines: bool = show_spines,
    **bar_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Render a randomized Probability Integral Transform (PIT) histogram.

Parameters:

Name	Type	Description	Default
`bin_centres`	`ndarray`	Bin centre positions in [0, 1] for each PIT histogram bar.	required
`hist_values`	`ndarray`	Density values for each PIT histogram bin.	required
`alpha_score`	`float`	PIT alpha (uniformity) score, displayed in the legend label.	required
`n_bins`	`int`	Number of bins used to compute the histogram (drives bar width and the uniform reference line height).	`20`
`label`	`str`	Legend label prefix for the histogram series.	`"Model"`
`ax`	`Axes`	Pre-existing Matplotlib axes instance. If None, a new figure and axes are created.	`None`
`color`	`str`	Fill color for histogram bars.	`_DEFAULT_THEME.primary_color`
`edgecolor`	`str`	Border color for histogram bars.	`"black"`
`uniform_linestyle`	`str`	Line style for the uniform-density reference line.	`"--"`
`uniform_color`	`str`	Color specifier for the uniform-density reference line.	`"black"`
`title`	`str`	Axes title text.	`None`
`show_spines`	`bool`	Whether to keep the top and right border spines visible.	`_DEFAULT_THEME.show_spines`
`**bar_kwargs`	`Any`	Additional Matplotlib keyword arguments forwarded to `ax.bar`.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure or SubFigure`	Parent Matplotlib figure containing the axes.
`ax`	`Axes`	Matplotlib axes containing the rendered PIT histogram.

Source code in medpipe/visualisation/plots.py

def draw_pit_histogram(
    bin_centres: np.ndarray,
    hist_values: np.ndarray,
    alpha_score: float,
    n_bins: int = 20,
    label: str = "Model",
    ax: Axes | None = None,
    color: str = _DEFAULT_THEME.primary_color,
    edgecolor: str = "black",
    uniform_linestyle: str = "--",
    uniform_color: str = "black",
    title: str | None = None,
    show_spines: bool = _DEFAULT_THEME.show_spines,
    **bar_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Render a randomized Probability Integral Transform (PIT) histogram.

    Parameters
    ----------
    bin_centres : np.ndarray
        Bin centre positions in [0, 1] for each PIT histogram bar.
    hist_values : np.ndarray
        Density values for each PIT histogram bin.
    alpha_score : float
        PIT alpha (uniformity) score, displayed in the legend label.
    n_bins : int, default=20
        Number of bins used to compute the histogram (drives bar width and
        the uniform reference line height).
    label : str, default="Model"
        Legend label prefix for the histogram series.
    ax : matplotlib.axes.Axes, optional
        Pre-existing Matplotlib axes instance. If None, a new figure and axes
        are created.
    color : str, default=_DEFAULT_THEME.primary_color
        Fill color for histogram bars.
    edgecolor : str, default="black"
        Border color for histogram bars.
    uniform_linestyle : str, default="--"
        Line style for the uniform-density reference line.
    uniform_color : str, default="black"
        Color specifier for the uniform-density reference line.
    title : str, optional
        Axes title text.
    show_spines : bool, default=_DEFAULT_THEME.show_spines
        Whether to keep the top and right border spines visible.
    **bar_kwargs : Any
        Additional Matplotlib keyword arguments forwarded to `ax.bar`.

    Returns
    -------
    fig : matplotlib.figure.Figure or matplotlib.figure.SubFigure
        Parent Matplotlib figure containing the axes.
    ax : matplotlib.axes.Axes
        Matplotlib axes containing the rendered PIT histogram.

    """
    fig: Figure | SubFigure | None
    if ax is None:
        fig, ax = plt.subplots(figsize=(7, 5))
    else:
        fig = ax.get_figure()
        if fig is None:
            raise ValueError("The provided Axes instance is not attached to a Figure")

    for key in ("color", "edgecolor", "width", "label"):
        bar_kwargs.pop(key, None)

    bin_width = 1.0 / n_bins
    ax.bar(
        bin_centres,
        hist_values,
        width=bin_width * 0.9,
        color=color,
        edgecolor=edgecolor,
        label=rf"{label} ($\alpha$ score: {alpha_score:.3f})",
        **bar_kwargs,
    )
    ax.axhline(
        1.0 / n_bins,
        color=uniform_color,
        linestyle=uniform_linestyle,
        linewidth=1.5,
        label="Uniform",
    )

    ax.set_xlabel("PIT value", fontweight="bold")
    ax.set_ylabel("Density", fontweight="bold")
    ax.set_xlim(0, 1)

    if title:
        ax.set_title(title, fontweight="bold")

    if not show_spines:
        ax.spines["top"].set_visible(False)
        ax.spines["right"].set_visible(False)

    ax.legend(frameon=False)

    return fig, ax

draw_dca_curve

draw_dca_curve(
    thresholds: ndarray,
    net_benefit_model: ndarray,
    net_benefit_all: ndarray,
    label: str = "Model",
    ax: Axes | None = None,
    color: str = primary_color,
    linestyle: str = "-",
    linewidth: float = linewidth,
    all_linestyle: str = ":",
    all_color: str = "gray",
    none_linestyle: str = "--",
    none_color: str = "black",
    title: str | None = None,
    show_spines: bool = show_spines,
    **line_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]

Render a Decision Curve Analysis (DCA) plot comparing net benefit across thresholds.

Parameters:

Name	Type	Description	Default
`thresholds`	`ndarray`	Array of threshold probabilities along the X-axis.	required
`net_benefit_model`	`ndarray`	Computed Net Benefit values for the evaluated model.	required
`net_benefit_all`	`ndarray`	Computed Net Benefit values for the 'Treat All' strategy.	required
`label`	`str`	Legend label for the model net benefit curve.	`"Model"`
`ax`	`Axes`	Pre-existing Matplotlib axes instance. If None, a new figure and axes are created.	`None`
`color`	`str`	Color specifier for the model net benefit line.	`_DEFAULT_THEME.primary_color`
`linestyle`	`str`	Line style for the model curve.	`"-"`
`linewidth`	`float`	Width in points for the model curve line.	`_DEFAULT_THEME.linewidth`
`all_linestyle`	`str`	Line style for the 'Treat All' reference curve.	`":"`
`all_color`	`str`	Color specifier for the 'Treat All' reference curve.	`"gray"`
`none_linestyle`	`str`	Line style for the 'Treat None' reference baseline.	`"--"`
`none_color`	`str`	Color specifier for the 'Treat None' reference baseline.	`"black"`
`title`	`str`	Axes title text.	`None`
`show_spines`	`bool`	Whether to keep top and right border spines visible.	`_DEFAULT_THEME.show_spines`
`**line_kwargs`	`Any`	Additional Matplotlib keyword arguments forwarded to `ax.plot` for the model curve.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure or SubFigure`	Parent Matplotlib figure containing the axes.
`ax`	`Axes`	Matplotlib axes containing the rendered decision curves.

Raises:

Type	Description
`ValueError`	If ax is provided but not attached to a Figure.

Source code in medpipe/visualisation/plots.py

def draw_dca_curve(
    thresholds: np.ndarray,
    net_benefit_model: np.ndarray,
    net_benefit_all: np.ndarray,
    label: str = "Model",
    ax: Axes | None = None,
    color: str = _DEFAULT_THEME.primary_color,
    linestyle: str = "-",
    linewidth: float = _DEFAULT_THEME.linewidth,
    all_linestyle: str = ":",
    all_color: str = "gray",
    none_linestyle: str = "--",
    none_color: str = "black",
    title: str | None = None,
    show_spines: bool = _DEFAULT_THEME.show_spines,
    **line_kwargs: Any,
) -> tuple[Figure | SubFigure, Axes]:
    """Render a Decision Curve Analysis (DCA) plot comparing net benefit
    across thresholds.

    Parameters
    ----------
    thresholds : np.ndarray
        Array of threshold probabilities along the X-axis.
    net_benefit_model : np.ndarray
        Computed Net Benefit values for the evaluated model.
    net_benefit_all : np.ndarray
        Computed Net Benefit values for the 'Treat All' strategy.
    label : str, default="Model"
        Legend label for the model net benefit curve.
    ax : matplotlib.axes.Axes, optional
        Pre-existing Matplotlib axes instance. If None, a new figure and axes
        are created.
    color : str, default=_DEFAULT_THEME.primary_color
        Color specifier for the model net benefit line.
    linestyle : str, default="-"
        Line style for the model curve.
    linewidth : float, default=_DEFAULT_THEME.linewidth
        Width in points for the model curve line.
    all_linestyle : str, default=":"
        Line style for the 'Treat All' reference curve.
    all_color : str, default="gray"
        Color specifier for the 'Treat All' reference curve.
    none_linestyle : str, default="--"
        Line style for the 'Treat None' reference baseline.
    none_color : str, default="black"
        Color specifier for the 'Treat None' reference baseline.
    title : str, optional
        Axes title text.
    show_spines : bool, default=_DEFAULT_THEME.show_spines
        Whether to keep top and right border spines visible.
    **line_kwargs : Any
        Additional Matplotlib keyword arguments forwarded to `ax.plot` for the
        model curve.

    Returns
    -------
    fig : matplotlib.figure.Figure or matplotlib.figure.SubFigure
        Parent Matplotlib figure containing the axes.
    ax : matplotlib.axes.Axes
        Matplotlib axes containing the rendered decision curves.

    Raises
    ------
    ValueError
        If ax is provided but not attached to a Figure.

    """
    fig: Figure | SubFigure | None
    if ax is None:
        fig, ax = plt.subplots(figsize=(6, 6))
    else:
        fig = ax.get_figure()
        if fig is None:
            raise ValueError("The provided Axes instance is not attached to a Figure")

    # Draw reference strategy curves
    ax.plot(
        thresholds,
        np.zeros_like(thresholds),
        linestyle=none_linestyle,
        color=none_color,
        label="Treat None",
    )
    ax.plot(
        thresholds,
        net_benefit_all,
        linestyle=all_linestyle,
        color=all_color,
        label="Treat All",
    )

    # Clean line_kwargs to prevent parameter collisions
    for key in ("color", "linestyle", "linewidth", "label"):
        line_kwargs.pop(key, None)

    # Draw main model Net Benefit curve
    ax.plot(
        thresholds,
        net_benefit_model,
        color=color,
        linestyle=linestyle,
        linewidth=linewidth,
        label=label,
        **line_kwargs,
    )

    # Format axis bounds and labels
    ax.set_xlabel("Threshold probability", fontweight="bold")
    ax.set_ylabel("Net benefit", fontweight="bold")
    ax.set_xlim(xmin=-0.02, xmax=1.02)

    # Dynamically set y limits based on data range
    y_min = max(-0.05, min(np.min(net_benefit_model), np.min(net_benefit_all)) - 0.02)
    y_max = max(np.max(net_benefit_model), np.max(net_benefit_all)) + 0.05
    ax.set_ylim(ymin=y_min, ymax=y_max)

    if title:
        ax.set_title(title, fontweight="bold")

    if not show_spines:
        ax.spines["top"].set_visible(False)
        ax.spines["right"].set_visible(False)

    ax.legend(loc="upper right", frameon=False)

    return fig, ax

themes

Themes for displaying graphs.

MedpipeTheme `dataclass`

Central aesthetic configuration for MedPipe pipeline visualizations.

This class manages color palettes, line weights, font sizes, axes spines, and Matplotlib runtime parameter updates across all graphics generated within the pipeline.

Attributes:

Name	Type	Description
`primary_color`	`str, default="#2D90D8"`	Hex string or Matplotlib color identifier for primary plot elements.
`palette`	`list of str`	Ordered list of color hex codes used for multi-class or multi-outcome figures.
`ci_alpha`	`float, default=0.3`	Opacity level for confidence interval shaded fills, bounded in [0.0, 1.0].
`linewidth`	`float, default=2.0`	Line width in points for main plotted curves.
`dpi`	`int, default=300`	Dots per inch (resolution) for saved rasterized images.
`font_family`	`str, default="sans-serif"`	Font family specification for titles, labels, and tick annotations.
`title_fontsize`	`int, default=12`	Font size in points for axes and figure titles.
`label_fontsize`	`int, default=10`	Font size in points for x and y axis labels.
`show_spines`	`bool, default=False`	Whether to draw top and right axes border lines.

Methods:

Name	Description
`to_rc_params`	Convert theme options into a dictionary compatible with Matplotlib rcParams.
`get_color`	Retrieve a color from the palette by index, wrapping cyclically if exceeded.
`from_dict`	Construct a MedpipeTheme instance from a dictionary configuration.

Source code in medpipe/visualisation/themes.py

@dataclass
class MedpipeTheme:
    """Central aesthetic configuration for MedPipe pipeline visualizations.

    This class manages color palettes, line weights, font sizes, axes spines, and
    Matplotlib runtime parameter updates across all graphics generated within the
    pipeline.

    Attributes
    ----------
    primary_color : str, default="#2D90D8"
        Hex string or Matplotlib color identifier for primary plot elements.
    palette : list of str
        Ordered list of color hex codes used for multi-class or multi-outcome figures.
    ci_alpha : float, default=0.3
        Opacity level for confidence interval shaded fills, bounded in [0.0, 1.0].
    linewidth : float, default=2.0
        Line width in points for main plotted curves.
    dpi : int, default=300
        Dots per inch (resolution) for saved rasterized images.
    font_family : str, default="sans-serif"
        Font family specification for titles, labels, and tick annotations.
    title_fontsize : int, default=12
        Font size in points for axes and figure titles.
    label_fontsize : int, default=10
        Font size in points for x and y axis labels.
    show_spines : bool, default=False
        Whether to draw top and right axes border lines.

    Methods
    -------
    to_rc_params()
        Convert theme options into a dictionary compatible with Matplotlib rcParams.
    get_color(index)
        Retrieve a color from the palette by index, wrapping cyclically if exceeded.
    from_dict(data)
        Construct a MedpipeTheme instance from a dictionary configuration.
    """

    primary_color: str = "#2D90D8"
    palette: list[str] = field(
        default_factory=lambda: [
            "#2D90D8",
            "#33367A",
            "#96690E",
            "#CDB4DB",
            "#F2CC8F",
        ]
    )
    ci_alpha: float = 0.3
    linewidth: float = 2.0
    dpi: int = 300
    font_family: str = "sans-serif"
    title_fontsize: int = 12
    label_fontsize: int = 10
    show_spines: bool = False
    show_grid: bool = False

    def to_rc_params(self) -> dict[RcKeyType, Any]:
        """Convert theme attributes into Matplotlib runtime configurations.

        Returns
        -------
        Dict[RcKeytype, Any]
            Dictionary mapping standard Matplotlib `rcParams` keys to theme values.

        """
        return {
            "font.family": self.font_family,
            "axes.titlesize": self.title_fontsize,
            "axes.labelsize": self.label_fontsize,
            "axes.titleweight": "bold",
            "axes.labelweight": "bold",
            "figure.dpi": self.dpi,
            "savefig.dpi": self.dpi,
            "axes.spines.top": self.show_spines,
            "axes.spines.right": self.show_spines,
            "axes.grid": self.show_grid,
        }

    def get_color(self, index: int) -> str:
        """Retrieve a color from the palette by index.

        If the specified index exceeds the number of colors in the palette, the
        selection wraps around cyclically.

        Parameters
        ----------
        index : int
            The zero-based index of the requested color.

        Returns
        -------
        str
            Hex color code from the palette corresponding to the index.

        """
        if not self.palette:
            return self.primary_color
        return self.palette[index % len(self.palette)]

    @classmethod
    def from_dict(cls, data: dict[str, Any]) -> "MedpipeTheme":
        """Instantiate a MedpipeTheme configuration from a dictionary.

        Filters out unrecognized keys to prevent initialization errors when reading
        from TOML or external configuration dictionaries.

        Parameters
        ----------
        data : dict of {str : Any}
            Dictionary containing theme attribute key-value pairs.

        Returns
        -------
        MedpipeTheme
            A newly constructed theme instance populated with provided settings.

        """
        valid_fields = {f.name for f in cls.__dataclass_fields__.values()}
        filtered_data = {k: v for k, v in data.items() if k in valid_fields}
        return cls(**filtered_data)

to_rc_params

to_rc_params() -> dict[RcKeyType, Any]

Convert theme attributes into Matplotlib runtime configurations.

Returns:

Type	Description
`Dict[RcKeytype, Any]`	Dictionary mapping standard Matplotlib `rcParams` keys to theme values.

Source code in medpipe/visualisation/themes.py

def to_rc_params(self) -> dict[RcKeyType, Any]:
    """Convert theme attributes into Matplotlib runtime configurations.

    Returns
    -------
    Dict[RcKeytype, Any]
        Dictionary mapping standard Matplotlib `rcParams` keys to theme values.

    """
    return {
        "font.family": self.font_family,
        "axes.titlesize": self.title_fontsize,
        "axes.labelsize": self.label_fontsize,
        "axes.titleweight": "bold",
        "axes.labelweight": "bold",
        "figure.dpi": self.dpi,
        "savefig.dpi": self.dpi,
        "axes.spines.top": self.show_spines,
        "axes.spines.right": self.show_spines,
        "axes.grid": self.show_grid,
    }

get_color

get_color(index: int) -> str

Retrieve a color from the palette by index.

If the specified index exceeds the number of colors in the palette, the selection wraps around cyclically.

Parameters:

Name	Type	Description	Default
`index`	`int`	The zero-based index of the requested color.	required

Returns:

Type	Description
`str`	Hex color code from the palette corresponding to the index.

Source code in medpipe/visualisation/themes.py

def get_color(self, index: int) -> str:
    """Retrieve a color from the palette by index.

    If the specified index exceeds the number of colors in the palette, the
    selection wraps around cyclically.

    Parameters
    ----------
    index : int
        The zero-based index of the requested color.

    Returns
    -------
    str
        Hex color code from the palette corresponding to the index.

    """
    if not self.palette:
        return self.primary_color
    return self.palette[index % len(self.palette)]

from_dict `classmethod`

from_dict(data: dict[str, Any]) -> MedpipeTheme

Instantiate a MedpipeTheme configuration from a dictionary.

Filters out unrecognized keys to prevent initialization errors when reading from TOML or external configuration dictionaries.

Parameters:

Name	Type	Description	Default
`data`	`dict of {str : Any}`	Dictionary containing theme attribute key-value pairs.	required

Returns:

Type	Description
`MedpipeTheme`	A newly constructed theme instance populated with provided settings.

Source code in medpipe/visualisation/themes.py

@classmethod
def from_dict(cls, data: dict[str, Any]) -> "MedpipeTheme":
    """Instantiate a MedpipeTheme configuration from a dictionary.

    Filters out unrecognized keys to prevent initialization errors when reading
    from TOML or external configuration dictionaries.

    Parameters
    ----------
    data : dict of {str : Any}
        Dictionary containing theme attribute key-value pairs.

    Returns
    -------
    MedpipeTheme
        A newly constructed theme instance populated with provided settings.

    """
    valid_fields = {f.name for f in cls.__dataclass_fields__.values()}
    filtered_data = {k: v for k, v in data.items() if k in valid_fields}
    return cls(**filtered_data)

Visualisation

displayer

BaseDisplayer

plot_data_distribution

plot_strata_heatmap

plot_all_heatmaps

MedpipeClassifierDisplayer

plot_roc_curve

plot_precision_recall_curve

plot_reliability_diagram

plot_dca_curve

plot_all

MedpipeRegressorDisplayer

plot_coverage

plot_sharpness

plot_winkler

plot_marginal_calibration

plot_pit_histogram

plot_all

plots

draw_data_distribution

draw_roc_curve

draw_precision_recall_curve

draw_reliability_diagram

draw_strata_heatmap

draw_coverage_curve

draw_sharpness_curve

draw_winkler_curve

draw_marginal_calibration

draw_pit_histogram

draw_dca_curve

themes

MedpipeTheme dataclass

to_rc_params

get_color

from_dict classmethod

MedpipeTheme `dataclass`

from_dict `classmethod`