API Reference

def compare_models(
    scores: Mapping[str, float],
    *,
    ax: Axes | None = None,
    metric_name: str = "Score",
    title: str = "Model Comparison",
) -> Axes:
    """Compare evaluation scores from already-completed model experiments.

    Args:
        scores: A mapping from model names to their evaluation scores.
        ax: The Matplotlib Axes to plot on. If None, a new Axes is created.
        metric_name: The name of the evaluation metric.
        title: The title of the plot.

    Returns:
        The Matplotlib Axes containing the plot.

    WHY: A consistent visual basis helps analysts compare models evaluated with
    the same metric and experimental conditions.

    NOTE: This function assumes the caller has already established that the
    supplied scores are meaningfully comparable.
    """
    if not scores:
        msg = "scores must contain at least one model result."
        raise ValueError(msg)

    if ax is None:
        _, ax = plt.subplots()

    names = list(scores)
    values = [scores[name] for name in names]

    ax.bar(names, values)
    ax.set_ylabel(metric_name)
    ax.set_title(title)
    ax.tick_params(axis="x", rotation=30)
    return ax

def compare_splits(
    splits: Sequence[SplitView],
) -> tuple[Axes, ...]:
    """Create one train/test visualization per completed split.

    Args:
        splits: A sequence of SplitView instances representing the completed splits.

    Returns:
        A tuple of Matplotlib Axes, each containing the visualization for one split.

    WHY: Comparing several partitions makes sampling variability visible.

    This function does not create splits or train models. Each visualization is
    created in its own figure, and all Axes are returned to the caller.
    """
    axes: list[Axes] = []

    for split in splits:
        _, ax = plt.subplots()

        title = split.label
        if split.score is not None:
            title = f"{title} | score={split.score:.3f}"

        show_train_test_split(
            split.X_train,
            split.X_test,
            ax=ax,
            title=title,
        )
        axes.append(ax)

    return tuple(axes)

def save_chart(
    ax: Axes,
    path: str | Path,
    *,
    bbox_inches: str | None = "tight",
) -> None:
    """Save chart.

    Args:
        ax (Axes): The matplotlib Axes object containing the chart to save.
        path (str | Path): The file path where the chart should be saved.
        bbox_inches (str | None, optional): The bounding box in inches. Defaults to "tight".

    Raises:
        ValueError: If the Axes is not attached to a Figure.

    """
    output_path = Path(path)
    output_path.parent.mkdir(parents=True, exist_ok=True)

    figure = ax.get_figure(root=True)
    if figure is None:
        raise ValueError("Axes must be attached to a Figure before saving.")

    figure.savefig(output_path, bbox_inches=bbox_inches)

def show_actual_vs_predicted(
    y_true: Numeric1D,
    y_pred: Numeric1D,
    *,
    ax: Axes | None = None,
    title: str = "Actual vs. Predicted",
) -> Axes:
    """Show actual versus predicted regression values.

    WHY: Good predictions should generally fall near the identity line.

    The implementation delegates to scikit-learn's PredictionErrorDisplay.
    """
    plot_ax = _new_axes(ax)

    PredictionErrorDisplay.from_predictions(
        y_true,
        y_pred,
        kind="actual_vs_predicted",
        ax=plot_ax,
    )
    plot_ax.set_title(title)
    return plot_ax

def show_class_distribution(
    y: Numeric1D,
    *,
    ax: Axes | None = None,
    title: str = "Class Distribution",
    x_label: str = "Class",
) -> Axes:
    """Show the number of observations in each target class.

    Args:
        y: The target labels.
        ax: The Matplotlib Axes to plot on. If None, a new Axes is created.
        title: The title of the plot.
        x_label: The label for the x-axis.

    Returns:
        The Matplotlib Axes containing the plot.

    WHY: Class imbalance can affect training, evaluation, and interpretation.
    """
    counts = pd.Series(y).value_counts(dropna=False).sort_index()
    plot_ax = _new_axes(ax)

    plot_ax.bar(counts.index.astype(str), counts.to_numpy())
    plot_ax.set_xlabel(x_label)
    plot_ax.set_ylabel("Count")
    plot_ax.set_title(title)
    return plot_ax

def show_confusion_matrix(
    y_true: Numeric1D,
    y_pred: Numeric1D,
    *,
    labels: Sequence[Any] | None = None,
    normalize: str | None = None,
    ax: Axes | None = None,
    title: str = "Confusion Matrix",
) -> Axes:
    """Show a confusion matrix from completed classification predictions.

    Args:
        y_true: The true labels.
        y_pred: The predicted labels.
        labels: Optional sequence of labels to include in the matrix.
        normalize: Normalization method for the confusion matrix.
        ax: The Matplotlib Axes to plot on. If None, a new Axes is created.
        title: The title of the plot.

    Returns:
        The Matplotlib Axes containing the plot.

    WHY: Overall accuracy can hide which classes are being confused.

    This function delegates the matrix visualization to scikit-learn and
    returns the Matplotlib Axes.
    """
    plot_ax = _new_axes(ax)

    ConfusionMatrixDisplay.from_predictions(
        y_true,
        y_pred,
        labels=labels,
        normalize=normalize,
        ax=plot_ax,
    )
    plot_ax.set_title(title)
    return plot_ax

def show_decision_boundary(
    model: Any,
    X: pd.DataFrame,
    y: Sequence[Any] | None = None,
    *,
    ax: Axes | None = None,
    response_method: str = "auto",
    plot_method: str = "contourf",
    title: str = "Decision Boundary",
    alpha: float = 0.25,
) -> Axes:
    """Show the decision boundary for an already-trained classifier.

    Args:
        model: The trained classifier to visualize.
        X: A DataFrame containing exactly two numeric features.
        y: Optional sequence of true labels corresponding to X.
        ax: The Matplotlib Axes to plot on. If None, a new Axes is created.
        response_method: The response method to use for the decision boundary.
        plot_method: The plotting method for the decision boundary.
        title: The title of the plot.
        alpha: The transparency level for the decision boundary.

    Returns:
        The Matplotlib Axes containing the plot.

    WHY: A decision boundary makes the classifier's learned separation of
    feature space visible.

    REQ: X must contain exactly two numeric features.
    REQ: model must already be fitted.

    The implementation delegates boundary construction to scikit-learn's
    DecisionBoundaryDisplay and returns the Matplotlib Axes to the caller.
    """
    if X.shape[1] != 2:
        msg = "Decision-boundary plots require exactly two features."
        raise ValueError(msg)

    plot_ax = _new_axes(ax)

    DecisionBoundaryDisplay.from_estimator(
        model,
        X,
        response_method=response_method,
        plot_method=plot_method,
        alpha=alpha,
        ax=plot_ax,
    )

    # Overlay observed samples when labels are supplied. The boundary itself is
    # produced by scikit-learn; this layer makes the result easier to inspect.
    if y is not None:
        values = np.asarray(y)
        classes, codes = np.unique(values, return_inverse=True)
        plot_ax.scatter(
            X.iloc[:, 0],
            X.iloc[:, 1],
            c=codes,
            edgecolors="black",
            alpha=0.85,
        )

        # A compact legend makes class identity available without dictating
        # styling beyond the default Matplotlib color cycle.
        handles = []
        for code, label in enumerate(classes):
            handles.append(
                plt.Line2D(
                    [],
                    [],
                    marker="o",
                    linestyle="",
                    label=str(label),
                    markerfacecolor=f"C{code % 10}",
                    markeredgecolor="black",
                )
            )
        plot_ax.legend(handles=handles, title="Class")

    plot_ax.set_title(title)
    return plot_ax

def show_feature_importance(
    model: Any,
    feature_names: Sequence[str],
    *,
    ax: Axes | None = None,
    title: str = "Feature Importance",
) -> Axes:
    """Show model-provided feature importance values.

    Args:
        model: The already-trained model exposing ``feature_importances_``.
        feature_names: The names of the features corresponding to the importance values.
        ax: The Matplotlib Axes to plot on. If None, a new Axes is created.
        title: The title of the plot.

    Returns:
        The Matplotlib Axes containing the plot.

    WHY: Importance values can help analysts investigate which features most
    influenced a fitted model.

    REQ: The model must already expose ``feature_importances_``.
    """
    if not hasattr(model, "feature_importances_"):
        msg = f"{type(model).__name__} does not expose feature_importances_."
        raise ValueError(msg)

    importance = np.asarray(model.feature_importances_, dtype=float)

    if len(importance) != len(feature_names):
        msg = "feature_names must match the model's feature count."
        raise ValueError(msg)

    order = np.argsort(importance)
    ordered_names = np.asarray(feature_names, dtype=str)[order]
    ordered_values = importance[order]

    if ax is None:
        _, ax = plt.subplots()

    ax.barh(ordered_names, ordered_values)
    ax.set_xlabel("Importance")
    ax.set_title(title)
    return ax

def show_prediction_errors(
    X: pd.DataFrame,
    y_true: Numeric1D,
    y_pred: Numeric1D,
    *,
    ax: Axes | None = None,
    title: str = "Classification Prediction Errors",
) -> Axes:
    """Show correct and incorrect classifications in two-feature space.

    Args:
        X: A DataFrame containing exactly two numeric features.
        y_true: The true labels.
        y_pred: The predicted labels.
        ax: The Matplotlib Axes to plot on. If None, a new Axes is created.
        title: The title of the plot.

    Returns:
        The Matplotlib Axes containing the plot.

    WHY: Looking directly at mistakes can reveal overlap, unusual observations,
    and regions where a classifier struggles.

    REQ: X must contain exactly two numeric features.
    """
    if X.shape[1] != 2:
        msg = "Prediction-error plots require exactly two features."
        raise ValueError(msg)

    actual = np.asarray(y_true)
    predicted = np.asarray(y_pred)

    if len(X) != len(actual) or len(actual) != len(predicted):
        msg = "X, y_true, and y_pred must contain the same number of observations."
        raise ValueError(msg)

    correct = actual == predicted
    plot_ax = _new_axes(ax)

    plot_ax.scatter(
        X.iloc[correct, 0],
        X.iloc[correct, 1],
        marker="o",
        label="Correct",
        alpha=0.65,
    )
    plot_ax.scatter(
        X.iloc[~correct, 0],
        X.iloc[~correct, 1],
        marker="x",
        label="Incorrect",
        alpha=0.95,
    )

    plot_ax.set_xlabel(str(X.columns[0]))
    plot_ax.set_ylabel(str(X.columns[1]))
    plot_ax.set_title(title)
    plot_ax.legend()
    return plot_ax

def show_residuals(
    y_true: Numeric1D,
    y_pred: Numeric1D,
    *,
    ax: Axes | None = None,
    title: str = "Residuals vs. Predicted",
) -> Axes:
    """Show regression residuals against predicted values.

    WHY: Residual plots can reveal systematic error patterns, changing
    variance, and unusual observations.

    The implementation delegates to scikit-learn's PredictionErrorDisplay.
    """
    plot_ax = _new_axes(ax)

    PredictionErrorDisplay.from_predictions(
        y_true,
        y_pred,
        kind="residual_vs_predicted",
        ax=plot_ax,
    )
    plot_ax.set_title(title)
    return plot_ax

def show_train_test_split(
    X_train: pd.DataFrame,
    X_test: pd.DataFrame,
    *,
    ax: Axes | None = None,
    title: str = "Train/Test Split",
) -> Axes:
    """Show which observations were assigned to training and testing.

    Args:
        X_train: The training feature DataFrame containing exactly two numeric features.
        X_test: The testing feature DataFrame containing exactly two numeric features.
        ax: The Matplotlib Axes to plot on. If None, a new Axes is created.
        title: The title of the plot.

    Returns:
        The Matplotlib Axes containing the plot.

    WHY: Seeing the actual partition makes random splitting concrete instead
    of treating the random seed as unexplained boilerplate.

    REQ: Both frames must contain the same two numeric features.
    """
    if X_train.shape[1] != 2 or X_test.shape[1] != 2:
        msg = "Train/test split plots require exactly two features."
        raise ValueError(msg)

    if list(X_train.columns) != list(X_test.columns):
        msg = "Training and test data must contain the same features in the same order."
        raise ValueError(msg)

    if ax is None:
        _, ax = plt.subplots()

    feature_x, feature_y = X_train.columns

    ax.scatter(
        X_train[feature_x],
        X_train[feature_y],
        marker="o",
        label="Train",
        alpha=0.65,
    )
    ax.scatter(
        X_test[feature_x],
        X_test[feature_y],
        marker="x",
        label="Test",
        alpha=0.95,
    )

    ax.set_xlabel(str(feature_x))
    ax.set_ylabel(str(feature_y))
    ax.set_title(title)
    ax.legend()
    return ax