structboost 0.1.0__py3-none-any.whl

structboost/_persistence.py

@@ -0,0 +1,326 @@
+"""Checkpoint serialization for a fitted :class:`~structboost._model.BAE`.
+
+The payload written here contains **only** tensors and Python primitives. That
+is a deliberate constraint, not an accident of implementation: it is what lets
+``BAE.load`` call ``torch.load(..., weights_only=True)``, so reading a
+structboost checkpoint can never execute arbitrary code from the file. PyTorch's
+restricted unpickler (``torch/_weights_only_unpickler.py``) admits tensors,
+``torch.device``, ``torch.Size``, ``OrderedDict``, ``set``, ``bytes`` and the
+builtin scalar/container types — but *not* NumPy arrays or NumPy scalars, which
+is why everything crossing this boundary is converted explicitly.
+
+Two things a fitted model carries are intentionally not written:
+
+``ObsCovariateEncoding.encoded``
+    The training-set covariate design matrix, shape ``(n_cells, n_columns)``. It
+    is read only inside ``BAE.fit``, which re-encodes from the incoming
+    ``AnnData`` before using it, so nothing needs it after a load. Dropping it
+    keeps cell-level training data out of a shipped model file and keeps the
+    file size independent of the training set.
+optimizer state
+    A loaded model is deployable, not resumable mid-run. ``fit`` rebuilds the
+    decoder and its optimizer unconditionally anyway.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+if TYPE_CHECKING:  # pragma: no cover
+    from ._model import BAE
+    from ._utils import ObsCovariateEncoding
+
+#: Identifies the file as a structboost checkpoint. A ``.pt`` file is otherwise
+#: indistinguishable from any other torch payload, and a confusing
+#: ``KeyError`` deep inside the restore is a worse diagnostic than a refusal.
+MAGIC = "structboost.bae"
+
+#: Bumped whenever the payload layout changes incompatibly. ``load`` refuses a
+#: file written by a newer format than it understands rather than guessing.
+#:
+#: 2 — added ``layer``. The bump is for *forward* compatibility: an older install
+#: would ignore the key and silently read ``adata.X`` instead of the layer the
+#: model was fitted on, which is a wrong answer rather than a missing one.
+#:
+#: 3 — the two covariate encodings became one, alongside the ``batch_key`` /
+#: ``batch_integration_mode`` API. Formats 1 and 2 predate the first public
+#: release, so no migration is written and the loader refuses them by name
+#: rather than failing on a missing key.
+#:
+#: 4 — ``BAEConfig.boosting_mode`` was dropped with ``allboost``'s refine mode.
+#: ``restore_payload`` splats the stored config into ``BAEConfig``, so a format-3
+#: file would otherwise die on an unexpected keyword argument. Every format below
+#: this one predates the first public release.
+CHECKPOINT_FORMAT = 4
+#: Oldest format this install can read.
+MIN_CHECKPOINT_FORMAT = 4
+
+#: Category element types that survive the round trip with their comparison
+#: semantics intact. ``bool`` precedes ``int`` because ``bool`` is a subclass of
+#: ``int`` and would otherwise be recorded as one.
+_CATEGORY_KINDS: tuple[tuple[str, type], ...] = (
+    ("bool", bool),
+    ("int", int),
+    ("float", float),
+    ("str", str),
+)
+
+
+def _to_primitive(obj: Any, *, coerce_unknown: bool = False) -> Any:
+    """Convert `obj` into tensors-free primitives that ``weights_only`` accepts.
+
+    NumPy scalars become Python scalars and NumPy arrays become nested lists;
+    tuples become lists, since pickle would otherwise be the only thing keeping
+    them apart and the distinction does not survive anyway.
+
+    Parameters
+    ----------
+    obj
+        Value to convert.
+    coerce_unknown
+        If True, anything not otherwise convertible is stringified. This is used
+        only for provenance dictionaries, matching the best-effort
+        ``json.dumps(..., default=str)`` policy in :mod:`structboost._io`. For
+        values that take part in computation it stays False, so an unexpected
+        type raises instead of silently becoming its ``repr``.
+    """
+    if obj is None or isinstance(obj, (str, bool, int, float)):
+        return obj
+    if isinstance(obj, np.generic):
+        return obj.item()
+    if isinstance(obj, np.ndarray):
+        return obj.tolist()
+    if isinstance(obj, dict):
+        return {str(k): _to_primitive(v, coerce_unknown=coerce_unknown) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple, set)):
+        return [_to_primitive(v, coerce_unknown=coerce_unknown) for v in obj]
+    if coerce_unknown:
+        return str(obj)
+    raise TypeError(f"cannot serialize object of type {type(obj).__name__!r} into a checkpoint")
+
+
+def _tensor(array: Any) -> Any:
+    """Convert an array-like to a CPU tensor, preserving dtype."""
+    import torch
+
+    return torch.as_tensor(np.asarray(array)).cpu()
+
+
+def _array(tensor: Any) -> np.ndarray:
+    """Convert a checkpoint tensor back to a NumPy array."""
+    return tensor.cpu().numpy()
+
+
+def _encode_categories(column: str, categories: list) -> dict[str, Any]:
+    """Record a categorical column's levels with their type.
+
+    The levels come from ``list(series.cat.categories)`` or
+    ``list(pd.unique(series))``, so they can be NumPy scalars. Their *type*
+    matters downstream: ``transform_obs_covariates`` both tests
+    ``value not in categories`` and builds ``pd.Categorical(series,
+    categories=...)``, and a level list whose dtype no longer matches the incoming
+    column maps every cell to NaN, yielding an all-zero dummy block — a wrong
+    reconstruction with no error raised. NumPy scalars are therefore unwrapped to
+    true Python scalars, which compare equal to their NumPy counterparts, and
+    anything outside the supported set is refused here rather than corrupting a
+    reconstruction later.
+    """
+    values = [v.item() if isinstance(v, np.generic) else v for v in categories]
+    for kind, py_type in _CATEGORY_KINDS:
+        if all(isinstance(v, py_type) for v in values):
+            return {"kind": kind, "values": values}
+    offending = next(
+        (type(v).__name__ for v in values if not isinstance(v, (bool, int, float, str))),
+        type(values[0]).__name__ if values else "unknown",
+    )
+    raise ValueError(
+        f"obs column {column!r} has categories of type {offending!r}, which cannot be "
+        "persisted in a BAE checkpoint. Convert the column to string, integer or "
+        "boolean before fitting."
+    )
+
+
+def _decode_categories(payload: dict[str, Any]) -> list:
+    """Rebuild a category list with the element type it was saved with."""
+    kind = payload["kind"]
+    caster = {"bool": bool, "int": int, "float": float, "str": str}[kind]
+    return [caster(v) for v in payload["values"]]
+
+
+def _encode_encoding(encoding: ObsCovariateEncoding | None) -> dict[str, Any] | None:
+    """Serialize an :class:`~structboost._utils.ObsCovariateEncoding`.
+
+    ``encoded`` is dropped; see the module docstring.
+    """
+    if encoding is None:
+        return None
+    column_info: dict[str, Any] = {}
+    for column, info in encoding.column_info.items():
+        entry = {
+            "type": info["type"],
+            "n_dummies": int(info["n_dummies"]),
+            "encoded_columns": [str(c) for c in info["encoded_columns"]],
+        }
+        if info["type"] == "categorical":
+            entry["categories"] = _encode_categories(column, list(info["categories"]))
+        column_info[column] = entry
+    return {
+        "column_info": column_info,
+        "mean": _tensor(encoding.mean),
+        "std": _tensor(encoding.std),
+        "obs_columns": [str(c) for c in encoding.obs_columns],
+        "n_columns": int(encoding.n_columns),
+        "encoded_columns": [str(c) for c in encoding.encoded_columns],
+    }
+
+
+def _decode_encoding(payload: dict[str, Any] | None) -> ObsCovariateEncoding | None:
+    """Rebuild an encoding, with a zero-row ``encoded`` placeholder."""
+    if payload is None:
+        return None
+    from ._utils import ObsCovariateEncoding
+
+    column_info: dict[str, dict] = {}
+    for column, info in payload["column_info"].items():
+        entry: dict[str, Any] = {
+            "type": info["type"],
+            "n_dummies": info["n_dummies"],
+            "encoded_columns": list(info["encoded_columns"]),
+        }
+        if info["type"] == "categorical":
+            entry["categories"] = _decode_categories(info["categories"])
+        column_info[column] = entry
+    n_columns = int(payload["n_columns"])
+    return ObsCovariateEncoding(
+        # Not the training design matrix: it is not persisted, and a zero-row
+        # array makes any accidental use fail on shape instead of quietly
+        # contributing wrong numbers.
+        encoded=np.empty((0, n_columns), dtype=np.float64),
+        column_info=column_info,
+        mean=_array(payload["mean"]),
+        std=_array(payload["std"]),
+        obs_columns=list(payload["obs_columns"]),
+        n_columns=n_columns,
+        encoded_columns=list(payload["encoded_columns"]),
+    )
+
+
+def build_payload(model: BAE) -> dict[str, Any]:
+    """Assemble the checkpoint dictionary for a fitted model."""
+    from dataclasses import asdict
+
+    config = asdict(model.config)
+    config["device"] = str(model.config.device)
+    config["decoder_hidden_dims"] = [int(d) for d in model.config.decoder_hidden_dims]
+
+    report = model._training_report
+    prior = model._prior_weights
+    scaling = model._latent_scaling
+
+    return {
+        "magic": MAGIC,
+        "format_version": CHECKPOINT_FORMAT,
+        "structboost_version": _package_version(),
+        "n_genes": int(model.n_genes),
+        "config": _to_primitive(config),
+        "encoder_state": model.encoder.state_dict(),
+        "decoder_state": model.decoder.state_dict(),
+        # Read off the decoder itself rather than re-derived from the encoding,
+        # so the rebuilt geometry cannot drift from what the weights expect.
+        "decoder_n_covariates": int(model.decoder.n_covariates),
+        "is_fitted": bool(model._is_fitted),
+        "layer": model._layer,
+        "var_names": None if model._var_names is None else [str(v) for v in model._var_names],
+        "training_history": {
+            str(k): [float(x) for x in v] for k, v in model._training_history.items()
+        },
+        "training_report": (
+            None if report is None else {k: _tensor(v) for k, v in report.to_dict().items()}
+        ),
+        "latent_init": _to_primitive(model._latent_init),
+        "batch_encoding": _encode_encoding(model._batch_encoding),
+        "batch_integration_mode": str(model._batch_integration_mode),
+        "batch_weights": (None if model._batch_weights is None else _tensor(model._batch_weights)),
+        "balance_obs": model._balance_obs,
+        "mandatory_genes": _to_primitive(model._mandatory_genes),
+        "prior_weights": None if prior is None else _tensor(prior),
+        "prior_info": _to_primitive(model._prior_info, coerce_unknown=True),
+        "latent_scaling": (
+            None
+            if scaling is None
+            else {"mean": _tensor(scaling["mean"]), "scale": _tensor(scaling["scale"])}
+        ),
+    }
+
+
+def restore_payload(cls: type[BAE], payload: dict[str, Any], device: Any) -> BAE:
+    """Rebuild a model from a checkpoint payload on `device`."""
+    from ._decoder import BAEDecoder
+    from ._types import BAEConfig, TrainingReport
+
+    config_kwargs = dict(payload["config"])
+    # Must be a tuple again: BAEConfig equality and `dataclasses.replace`
+    # round-trips both depend on it, and a list would quietly propagate.
+    config_kwargs["decoder_hidden_dims"] = tuple(config_kwargs["decoder_hidden_dims"])
+    config_kwargs["device"] = device
+    config = BAEConfig(**config_kwargs)
+
+    model = cls(int(payload["n_genes"]), config)
+
+    # Rebuild the decoder at the geometry the saved weights were trained with;
+    # `__init__` builds an unconditioned one. Mirrors BAE.fit.
+    decoder_input = 2 * config.latent_dim if config.split_softmax else config.latent_dim
+    model.decoder = BAEDecoder(
+        model.n_genes,
+        config,
+        input_dim_override=decoder_input,
+        n_covariates=int(payload["decoder_n_covariates"]),
+    ).to(config.device)
+
+    model.encoder.load_state_dict(payload["encoder_state"])
+    model.decoder.load_state_dict(payload["decoder_state"])
+    model.to(config.device)
+
+    model._is_fitted = bool(payload["is_fitted"])
+    # `.get`: format-1 checkpoints predate layer support and were fitted on `.X`.
+    model._layer = payload.get("layer")
+    var_names = payload["var_names"]
+    model._var_names = None if var_names is None else np.asarray(var_names, dtype=object)
+    model._training_history = {k: list(v) for k, v in payload["training_history"].items()}
+    report = payload["training_report"]
+    model._training_report = (
+        None
+        if report is None
+        else TrainingReport.from_dict({k: _array(v) for k, v in report.items()})
+    )
+    model._latent_init = dict(payload["latent_init"])
+
+    model._batch_encoding = _decode_encoding(payload["batch_encoding"])
+    model._batch_integration_mode = payload["batch_integration_mode"]
+    batch_weights = payload["batch_weights"]
+    model._batch_weights = None if batch_weights is None else _array(batch_weights)
+    model._balance_obs = payload["balance_obs"]
+    model._mandatory_genes = payload["mandatory_genes"]
+
+    prior = payload["prior_weights"]
+    model._prior_weights = None if prior is None else _array(prior)
+    model._prior_info = dict(payload["prior_info"])
+    scaling = payload["latent_scaling"]
+    model._latent_scaling = (
+        None
+        if scaling is None
+        else {"mean": _array(scaling["mean"]), "scale": _array(scaling["scale"])}
+    )
+    return model
+
+
+def _package_version() -> str:
+    """Best-effort package version for provenance; never fatal."""
+    try:
+        from . import __version__
+
+        return str(__version__)
+    except Exception:  # pragma: no cover - provenance only
+        return "unknown"

structboost/_plotting.py

@@ -0,0 +1,301 @@
+"""Plotting helpers for structboost.
+
+These utilities are intentionally lightweight and optional: they only depend on
+matplotlib and numpy.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import numpy as np
+
+
+def plot_top_boosting_coefficients(
+    betamat: np.ndarray,
+    gene_names: Sequence[str],
+    cluster_labels: Sequence[str],
+    *,
+    top_m: int = 10,
+    neg_color: str = "#1f77b4",
+    pos_color: str = "#d62728",
+):
+    """Plot per-target dot/lollipop charts of top boosting coefficients.
+
+    Parameters
+    ----------
+    betamat
+        Array of shape (n_targets, n_features) with boosting coefficients.
+    gene_names
+        Feature names of length n_features (e.g., gene symbols).
+    cluster_labels
+        Target labels of length n_targets (e.g., cluster IDs).
+    top_m
+        Number of features to display per target (ranked by ``|beta|``).
+    neg_color, pos_color
+        Colors used for negative and positive coefficients, respectively.
+
+    Returns
+    -------
+    figs
+        List of matplotlib Figure objects, one per target.
+    axes
+        List of matplotlib Axes objects, one per target.
+    """
+    import matplotlib.pyplot as plt
+
+    betamat = np.asarray(betamat, dtype=float)
+    n_targets, n_features = betamat.shape
+
+    if len(gene_names) != n_features:
+        raise ValueError(f"gene_names must have length {n_features}, got {len(gene_names)}")
+    if len(cluster_labels) != n_targets:
+        raise ValueError(f"cluster_labels must have length {n_targets}, got {len(cluster_labels)}")
+    if top_m < 1:
+        raise ValueError("top_m must be >= 1")
+
+    top_m_eff = min(top_m, n_features)
+    figs = []
+    axes = []
+
+    for t, cluster in enumerate(cluster_labels):
+        beta_all = betamat[t, :]
+
+        nonzero = np.flatnonzero(beta_all)
+        if nonzero.size > 0:
+            idx_rank = nonzero[np.argsort(np.abs(beta_all[nonzero]))[::-1]]
+        else:
+            idx_rank = np.argsort(np.abs(beta_all))[::-1]
+
+        feat_idx = idx_rank[:top_m_eff]
+        beta_hat = beta_all[feat_idx]
+        genes = [gene_names[j] for j in feat_idx]
+
+        order = np.argsort(np.abs(beta_hat))[::-1]
+        beta_hat = beta_hat[order]
+        genes = [genes[o] for o in order]
+        y_pos = np.arange(len(genes))
+
+        colors = np.where(beta_hat >= 0, pos_color, neg_color)
+
+        fig, ax = plt.subplots(figsize=(9.5, 0.55 * len(genes) + 1.6))
+        ax.hlines(y_pos, 0, beta_hat, color=colors, linewidth=4, alpha=0.25, zorder=1)
+        ax.scatter(beta_hat, y_pos, s=90, c=colors, edgecolors="white", linewidths=0.9, zorder=2)
+        ax.axvline(0, color="#9aa0a6", linestyle=(0, (3, 3)), linewidth=1.5, zorder=0)
+
+        ax.set_yticks(y_pos)
+        ax.set_yticklabels(genes, fontsize=10)
+        ax.set_xlabel("Boosting coefficient", fontsize=11)
+        ax.set_title(
+            f"Top {len(genes)} boosting coefficients (Cluster {cluster})", fontsize=12, pad=10
+        )
+
+        max_abs = float(np.max(np.abs(beta_hat))) if beta_hat.size else 1.0
+        pad = 0.15 * max_abs + 1e-9
+        ax.set_xlim(-(max_abs + pad), (max_abs + pad))
+
+        ax.grid(axis="y", visible=False)
+        for spine in ("top", "right"):
+            ax.spines[spine].set_visible(False)
+
+        for x, y, c in zip(beta_hat, y_pos, colors, strict=True):
+            ha = "left" if x >= 0 else "right"
+            ax.text(
+                x + (0.02 * (max_abs + pad) if x >= 0 else -0.02 * (max_abs + pad)),
+                y,
+                f"{x:.3f}",
+                va="center",
+                ha=ha,
+                fontsize=9,
+                color=c,
+                alpha=0.85,
+            )
+
+        ax.invert_yaxis()
+        fig.tight_layout()
+
+        figs.append(fig)
+        axes.append(ax)
+
+    return figs, axes
+
+
+def plot_boosting_coefficient_paths(
+    beta_path: np.ndarray,
+    gene_names: Sequence[str],
+    cluster_labels: Sequence[str],
+    *,
+    top_m: int = 10,
+    linewidth: float = 1.6,
+    alpha: float = 0.9,
+):
+    """Plot coefficient trajectories across boosting steps (per target).
+
+    This visualizes how coefficients evolve over iterations. For each target, we
+    select the top-``|beta|`` features at the **final** step and plot their paths.
+
+    Parameters
+    ----------
+    beta_path
+        Array of shape (n_targets, n_steps, n_features), typically
+        `history.beta_path` from `allboost(..., return_history=True)`.
+    gene_names
+        Feature names of length n_features.
+    cluster_labels
+        Target labels of length n_targets.
+    top_m
+        Number of features to display per target (ranked by ``|beta|`` at final step).
+    linewidth
+        Line width for each feature trajectory.
+    alpha
+        Line alpha for each feature trajectory.
+    Returns
+    -------
+    figs, axes
+        Lists of matplotlib Figure/Axes objects, one per target.
+    """
+    import matplotlib.pyplot as plt
+
+    beta_path = np.asarray(beta_path, dtype=float)
+    n_targets, n_steps, n_features = beta_path.shape
+
+    if len(gene_names) != n_features:
+        raise ValueError(f"gene_names must have length {n_features}, got {len(gene_names)}")
+    if len(cluster_labels) != n_targets:
+        raise ValueError(f"cluster_labels must have length {n_targets}, got {len(cluster_labels)}")
+    if top_m < 1:
+        raise ValueError("top_m must be >= 1")
+
+    steps = np.arange(1, n_steps + 1)
+    top_m_eff = min(top_m, n_features)
+
+    figs = []
+    axes = []
+
+    for t, cluster in enumerate(cluster_labels):
+        beta_final = beta_path[t, -1, :]
+        top_idx = np.argsort(np.abs(beta_final))[::-1][:top_m_eff]
+
+        fig, ax = plt.subplots(figsize=(10, 4))
+        for j in top_idx:
+            ax.plot(
+                steps, beta_path[t, :, j], label=gene_names[j], linewidth=linewidth, alpha=alpha
+            )
+
+        ax.axhline(0, color="black", linewidth=0.9, alpha=0.4)
+        ax.set_title(f"Coefficient paths (Cluster {cluster})")
+        ax.set_xlabel("Boosting step")
+        ax.set_ylabel("Coefficient")
+        ax.legend(ncols=2, fontsize=8, frameon=False)
+        fig.tight_layout()
+
+        figs.append(fig)
+        axes.append(ax)
+
+    return figs, axes
+
+
+def plot_training_diagnostics(
+    report,
+    *,
+    figsize: tuple[float, float] = (13.0, 9.0),
+    log_scale: bool = True,
+):
+    """Plot a :class:`~structboost.TrainingReport` as a six-panel diagnostic figure.
+
+    Parameters
+    ----------
+    report
+        A :class:`~structboost.TrainingReport`, a fitted ``BAE`` (its
+        ``training_report`` is used), or an ``AnnData`` carrying
+        ``uns["bae"]["training_report"]``.
+    figsize
+        Figure size in inches.
+    log_scale
+        Use a log y-axis for the convergence and gradient panels, whose values
+        span orders of magnitude.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        The figure. Panels are: reconstruction loss, per-iteration contribution
+        of the encoder and decoder halves, encoder convergence, selected genes,
+        gradient norms, and boosting fit quality.
+
+    Raises
+    ------
+    ValueError
+        If no training report is available (``diagnostics=True`` was not set).
+    """
+    import matplotlib.pyplot as plt
+
+    from ._types import TrainingReport
+
+    if not isinstance(report, TrainingReport):
+        candidate = getattr(report, "training_report", None)
+        if candidate is None:
+            uns = getattr(report, "uns", None)
+            stored = uns.get("bae", {}).get("training_report") if uns is not None else None
+            if stored is None:
+                raise ValueError(
+                    "no training report available; fit with diagnostics=True to collect one"
+                )
+            candidate = TrainingReport.from_dict(stored)
+        report = candidate
+
+    it = report.iteration
+    fig, axes = plt.subplots(2, 3, figsize=figsize)
+    fig.suptitle("BAE training diagnostics", fontsize=13)
+
+    ax = axes[0, 0]
+    ax.plot(it, report.loss_post_decoder, lw=1.8, color="#1f77b4", label="full-data")
+    ax.plot(it, report.train_loss, lw=1.0, color="#aaaaaa", alpha=0.9, label="minibatch running")
+    ax.set_title("Reconstruction loss")
+    ax.set_xlabel("iteration")
+    ax.set_ylabel("MSE")
+    ax.legend(fontsize=8)
+
+    # The two halves of the alternating optimizer, as loss change per iteration.
+    ax = axes[0, 1]
+    ax.axhline(0.0, color="#666666", lw=0.8)
+    ax.plot(it, report.encoder_delta, lw=1.4, color="#d62728", label="encoder (boosting)")
+    ax.plot(it, report.decoder_delta, lw=1.4, color="#2ca02c", label="decoder (SGD)")
+    ax.set_title("Loss change per update\n(negative = improved)")
+    ax.set_xlabel("iteration")
+    ax.set_ylabel("Δ MSE")
+    ax.legend(fontsize=8)
+
+    ax = axes[0, 2]
+    ax.plot(it, report.weight_change_rel, lw=1.6, color="#9467bd", label="rel. weight change")
+    ax.plot(it, 1.0 - report.support_jaccard, lw=1.2, color="#ff7f0e", label="1 − support Jaccard")
+    if log_scale:
+        ax.set_yscale("log")
+    ax.set_title("Encoder convergence")
+    ax.set_xlabel("iteration")
+    ax.legend(fontsize=8)
+
+    ax = axes[1, 0]
+    ax.plot(it, report.n_selected, lw=1.6, color="#8c564b")
+    ax.set_title("Selected genes")
+    ax.set_xlabel("iteration")
+    ax.set_ylabel("n genes with nonzero weight")
+
+    ax = axes[1, 1]
+    ax.plot(it, report.target_grad_norm, lw=1.6, color="#e377c2", label="‖∂L/∂z‖ (targets)")
+    ax.plot(it, report.decoder_grad_norm, lw=1.2, color="#7f7f7f", label="‖∇ decoder‖")
+    if log_scale:
+        ax.set_yscale("log")
+    ax.set_title("Gradient norms")
+    ax.set_xlabel("iteration")
+    ax.legend(fontsize=8)
+
+    ax = axes[1, 2]
+    ax.plot(it, report.boosting_r2, lw=1.6, color="#17becf")
+    ax.set_title("Boosting fit to targets")
+    ax.set_xlabel("iteration")
+    ax.set_ylabel("R²")
+
+    for ax in axes.ravel():
+        ax.grid(alpha=0.25, lw=0.6)
+    fig.tight_layout()
+    return fig