{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n\n# The skore API\n\nSkore has three types of reports: :class:`~skore.EstimatorReport`\n(single train-test evaluation), :class:`~skore.CrossValidationReport`\n(cross-validation), and :class:`~skore.ComparisonReport` (comparing several\nestimators). All three are created via :func:`~skore.evaluate` by passing an\nestimator (or a list of estimators for comparison), the data ``X`` and ``y``,\nand a ``splitter`` that controls the evaluation strategy.\n\nThis example showcases the **unified API** shared by these reports: they expose\nthe same accessors (``data``, ``metrics``, ``inspection``). Methods that\nproduce a visualization return a **Display** object with ``plot()``, ``frame()``,\n``set_style()``, and ``help()``.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Three report types, one API\n\n:func:`~skore.evaluate` returns one of three report types depending on its\n``splitter`` argument: an :class:`~skore.EstimatorReport` when ``splitter`` is a\nfloat or ``\"prefit\"``, a :class:`~skore.CrossValidationReport` when ``splitter`` is\nan integer or a scikit-learn cross-validator (e.g. ``KFold``, ``StratifiedKFold``),\nor a :class:`~skore.ComparisonReport` when passing a list of estimators.\nAll three respect the same accessor layout where applicable:\n\n- **data**: dataset analysis\n- **metrics**: performance metrics and related displays (e.g. ROC, confusion matrix)\n- **inspection**: model inspection (e.g. coefficients, feature importance)\n\nThe ``data`` accessor is not available on ComparisonReport because compared\nmodels may use different input data; you can still inspect each underlying report.\nMethods on these accessors return **Display** objects with a common interface.\n\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## First report: single train-test split\n\nWe call :func:`~skore.evaluate` with the default ``splitter=0.2`` to get an\n:class:`~skore.EstimatorReport`. The accessors and display API shown below\nare the same for the other report types.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from sklearn.datasets import load_breast_cancer\nfrom sklearn.linear_model import LogisticRegression\nfrom skore import evaluate\nfrom skrub import tabular_pipeline\n\nX, y = load_breast_cancer(return_X_y=True, as_frame=True)\nestimator = tabular_pipeline(LogisticRegression())\n\nreport = evaluate(estimator, X, y, splitter=0.2)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### Data accessor: ``report.data.analyze()`` returns a display\n\nThe **data** accessor provides dataset summaries. Its ``analyze()`` method\nreturns a :class:`~skore._sklearn._plot.data.table_report.TableReportDisplay`.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "data_display = report.data.analyze()\ndata_display.help()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Every display implements the same API. You can:\n\n- **Plot** it (with optional backend and style):\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "data_display.plot(kind=\"dist\", x=\"mean radius\", y=\"mean texture\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "You can set the style of the plot via ``set_style()`` and then call ``plot()``:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "data_display.set_style(scatterplot_kwargs={\"color\": \"orange\", \"alpha\": 1.0})\ndata_display.plot(kind=\"dist\", x=\"mean radius\", y=\"mean texture\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "- **Export** the underlying data as a DataFrame:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "data_display.frame()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Metrics accessor: same idea, same display API\n\nThe **metrics** accessor exposes methods such as ``confusion_matrix()``,\n``roc_curve()``, ``precision_recall()``, and ``prediction_error()``. Each\nreturns a display (e.g. :class:`~skore.ConfusionMatrixDisplay`) with the\nsame interface: ``plot()``, ``frame()``, ``set_style()``, ``help()``.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "metrics_display = report.metrics.confusion_matrix()\nmetrics_display.help()"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "metrics_display.frame()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Draw the confusion matrix by calling ``plot()``:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "metrics_display.plot()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Inspection accessor\n\nThe **inspection** accessor exposes model-specific displays (e.g.\n``coefficients()`` for linear models, ``impurity_decrease()`` for trees).\nThese also return Display objects with the same ``plot()``, ``frame()``,\n``set_style()``, and ``help()`` methods.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "inspection_display = report.inspection.coefficients()\ninspection_display.plot(select_k=15, sorting_order=\"descending\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Second report type: cross-validation\n\nUsing the same :func:`~skore.evaluate` with an integer ``splitter`` returns a\n:class:`~skore.CrossValidationReport`. The same accessors and display API\napply; only the way the report was built changes.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "cv_report = evaluate(estimator, X, y, splitter=3)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Again: ``data``, ``metrics``, and ``inspection`` return displays with\n``plot()``, ``frame()``, and ``set_style()``.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "cv_report.data.analyze().plot(kind=\"dist\", x=\"mean radius\", y=\"mean texture\")"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "cv_report.metrics.confusion_matrix().plot()"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "cv_report.inspection.coefficients().plot(select_k=10, sorting_order=\"descending\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Third report type: comparison\n\nPassing a **list of estimators** to :func:`~skore.evaluate` returns a\n:class:`~skore.ComparisonReport`. It exposes the same ``metrics`` and\n``inspection`` accessors (no ``data`` accessor, since compared models can\nuse different datasets). The display API is unchanged.\n\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Summary\n\n- **Three report types** (:class:`~skore.EstimatorReport`,\n  :class:`~skore.CrossValidationReport`, :class:`~skore.ComparisonReport`) are\n  all created with :func:`~skore.evaluate` and share the same accessor layout:\n  ``report.data``, ``report.metrics``, ``report.inspection`` (where applicable).\n- **Accessor methods** that produce figures or tables return **Display**\n  objects.\n- **Displays** share a single, predictable API:\n\n  - ``plot(**kwargs)`` \u2014 render the visualization\n  - ``frame(**kwargs)`` \u2014 return the data as a :class:`pandas.DataFrame`\n  - ``set_style(policy=..., **kwargs)`` \u2014 customize appearance\n  - ``help()`` \u2014 show available options\n\nThis consistency makes it easy to switch between report types and to reuse\nthe same workflow across data, metrics, and inspection.\n\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.14.4"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}