{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n\n# The skore API\n\nThis example illustrates the consistent API shared by skore reports and displays.\nReports expose the same accessors (``data``, ``metrics``, ``inspection``), and\neach method that produces a visualization returns a **Display** object. All\ndisplays implement a common interface: ``plot()``, ``frame()``, ``set_style()``,\nand ``help()``.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Reports share the same accessor structure\n\n:class:`~skore.EstimatorReport`, :class:`~skore.CrossValidationReport`, and\n:class:`~skore.ComparisonReport` all expose the same accessors 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 only available on :class:`~skore.EstimatorReport` and\n:class:`~skore.CrossValidationReport` because when comparing models, the input data\ncan be different and thus one can access the underlying reports to inspect the data.\n\nCalling a method on these accessors returns a **Display** object. The same\npattern holds across report types, so once you know one, you know them all.\n\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Minimal setup: one report and one display\n\nWe build a simple :class:`~skore.EstimatorReport` and use it to show how\naccessors return displays and how those displays behave.\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 EstimatorReport, train_test_split\nfrom skrub import tabular_pipeline\n\nX, y = load_breast_cancer(return_X_y=True, as_frame=True)\nsplit_data = train_test_split(X=X, y=y, random_state=42, as_dict=True)\nestimator = tabular_pipeline(LogisticRegression())\n\nreport = EstimatorReport(estimator, **split_data)"
      ]
    },
    {
      "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": [
        "## Same API with :class:`~skore.CrossValidationReport`\n\nThe same accessors and display API apply to :class:`~skore.CrossValidationReport`.\nWe use the same dataset and model; only the report type changes.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from skore import CrossValidationReport\n\ncv_report = CrossValidationReport(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": [
        "The same accessors and display API apply to :class:`~skore.ComparisonReport`\n(metrics and inspection; no data accessor when comparing reports).\n\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Summary\n\n- **Reports** (Estimator, CrossValidation, Comparison) use the same accessor\n  layout: ``report.data``, ``report.metrics``, ``report.inspection`` (where\n  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.13.12"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}