:orphan:

.. _auto_examples:

Examples
========

Below is a gallery of narrated notebook examples on how and why to use skore.

.. note::
    If you would like to run the examples, please install their dependencies using

    .. code-block:: bash

        pip install -U skore[sphinx]


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>

Getting started
---------------

We recommend starting with these examples that provide an overall and gentle
introduction to skore.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This guide illustrates how to use skore through a complete machine learning workflow for binary classification:">

.. only:: html

  .. image:: /auto_examples/getting_started/images/thumb/sphx_glr_plot_getting_started_thumb.png
    :alt:

  :doc:`/auto_examples/getting_started/plot_getting_started`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Skore: getting started</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

End-to-end data science use cases
---------------------------------

These examples showcase skore in action on real use cases.
We aimed at showing skore's ability to:

- be compatible with scikit-learn
- reduce boilerplate code for some standard *de facto* data science analysis
- speed-up exploration by optimizing some internal computation


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we tackle the California housing dataset where the goal is to perform a regression task: predicting house prices based on features such as the number of bedrooms, the geolocation, etc. For that, we try out several families of models. We evaluate these methods using evaluate and the report&#x27;s metrics.">

.. only:: html

  .. image:: /auto_examples/use_cases/images/thumb/sphx_glr_plot_feature_importance_thumb.png
    :alt:

  :doc:`/auto_examples/use_cases/plot_feature_importance`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">EstimatorReport: Inspecting your models with the feature importance</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to leverage skore for structuring useful experiment information allowing to get insights from machine learning experiments.">

.. only:: html

  .. image:: /auto_examples/use_cases/images/thumb/sphx_glr_plot_employee_salaries_thumb.png
    :alt:

  :doc:`/auto_examples/use_cases/plot_employee_salaries`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Simplified and structured experiment reporting</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="To track all operations and be able to apply the fitted estimator to unseen data, we need to include all the data wrangling in the estimator used for our skore report. In very simple cases this can be done with a scikit-learn Pipeline. When we have transformations not supported by the Pipeline (such as transformations that change the number of rows, or that involve multiple tables such as joins), skore allows us to use a skrub DataOp instead.">

.. only:: html

  .. image:: /auto_examples/use_cases/images/thumb/sphx_glr_plot_tracking_all_the_data_processing_thumb.png
    :alt:

  :doc:`/auto_examples/use_cases/plot_tracking_all_the_data_processing`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Tracking all the data processing</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Model evaluation
----------------

These examples illustrate how skore can help data scientists to improve their
machine learning modelling thanks to methodological guidance and diagnostics.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="By default, summarize reports a curated set of metrics for your ML task. In practice you often need domain-specific scores: a business cost function, a custom fairness measure, an F-beta with a particular beta, etc.">

.. only:: html

  .. image:: /auto_examples/model_evaluation/images/thumb/sphx_glr_plot_custom_metrics_thumb.png
    :alt:

  :doc:`/auto_examples/model_evaluation/plot_custom_metrics`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Adapt skore to your use-case by adding your own metrics</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how the skore.EstimatorReport class can be used to quickly get insights from any scikit-learn estimator.">

.. only:: html

  .. image:: /auto_examples/model_evaluation/images/thumb/sphx_glr_plot_estimator_report_thumb.png
    :alt:

  :doc:`/auto_examples/model_evaluation/plot_estimator_report`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">EstimatorReport: Get insights from any scikit-learn estimator</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Checking for modeling pitfalls and remediation
----------------------------------------------

Examples for each automated check. Each script reproduces a check, and walks
through fixes described in :ref:`automated_checks`.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="skd002-underfitting and skd001-overfitting describe opposite ends of the same problem: model expressiveness.">

.. only:: html

  .. image:: /auto_examples/pitfalls_and_solutions/images/thumb/sphx_glr_plot_skd001_skd002_overfitting_underfitting_thumb.png
    :alt:

  :doc:`/auto_examples/pitfalls_and_solutions/plot_skd001_skd002_overfitting_underfitting`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">SKD001 & SKD002 - Overfitting and underfitting</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="skd004-high-class-imbalance flags a binary classification task when the majority class exceeds 80 % of rows. Accuracy can look high while the minority class is ignored as a default. This notebook is mostly about how to work with that imbalance once the check fires: we do not try to make SKD004 disappear, because natural prevalence is often the right thing to keep.">

.. only:: html

  .. image:: /auto_examples/pitfalls_and_solutions/images/thumb/sphx_glr_plot_skd004_high_class_imbalance_thumb.png
    :alt:

  :doc:`/auto_examples/pitfalls_and_solutions/plot_skd004_high_class_imbalance`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">SKD004 - High class imbalance</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the limitations that skd007-mdi-cardinality-bias warns against on tree models. Mean decrease in impurity (MDI) tends to rank high-cardinality categorical or continuous columns as more important than features with as much signal but lower cardinality. This is due to the tree building process picking high cardinality features more often as they offer more split points to choose from.">

.. only:: html

  .. image:: /auto_examples/pitfalls_and_solutions/images/thumb/sphx_glr_plot_skd007_mdi_cardinality_bias_thumb.png
    :alt:

  :doc:`/auto_examples/pitfalls_and_solutions/plot_skd007_mdi_cardinality_bias`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">SKD007 - MDI feature importance is biased for high-cardinality features</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example walks through mitigations when check skd008-correlated-features fires because numeric columns are nearly redundant. The check computes pairwise Spearman correlation on training inputs and flags pairs with |ρ| &gt; 0.9.">

.. only:: html

  .. image:: /auto_examples/pitfalls_and_solutions/images/thumb/sphx_glr_plot_skd008_correlated_features_thumb.png
    :alt:

  :doc:`/auto_examples/pitfalls_and_solutions/plot_skd008_correlated_features`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">SKD008 - Highly correlated input features</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates mitigations when check skd013-train-test-time-overlap fires on temporal data. The check compares datetime columns in train and test folds and flags overlap when the latest training timestamp is not strictly before the earliest test timestamp.">

.. only:: html

  .. image:: /auto_examples/pitfalls_and_solutions/images/thumb/sphx_glr_plot_skd013_train_test_time_overlap_thumb.png
    :alt:

  :doc:`/auto_examples/pitfalls_and_solutions/plot_skd013_train_test_time_overlap`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">SKD013 - Train-test overlap in time series</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example walks through mitigations when checks skd014-hyperparams-at-search-edge and skd015-hyperparameters-worth-tuning fire on a fitted search object. SKD014 is an issue: numeric best_params_ sit on the minimum or maximum value tried, so the true optimum may lie outside the searched range. SKD015 is a tip: a hyperparameter is missing from the search space, which is incomplete rather than necessarily wrong.">

.. only:: html

  .. image:: /auto_examples/pitfalls_and_solutions/images/thumb/sphx_glr_plot_skd014_skd015_hyperparameter_search_thumb.png
    :alt:

  :doc:`/auto_examples/pitfalls_and_solutions/plot_skd014_skd015_hyperparameter_search`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">SKD014 & SKD015: Hyperparameter search pitfalls</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example walks through mitigations when check skd016-estimator-not-tuned tips on a plain estimator left at scikit-learn defaults. The check compares initialization parameters against a curated table of high-impact hyperparameters and suggests axes worth tuning.">

.. only:: html

  .. image:: /auto_examples/pitfalls_and_solutions/images/thumb/sphx_glr_plot_skd016_estimator_not_tuned_thumb.png
    :alt:

  :doc:`/auto_examples/pitfalls_and_solutions/plot_skd016_estimator_not_tuned`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">SKD016 - Estimator not tuned</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Integrations
------------

These examples show how `skore` integrates with other libraries of the Python data
science ecosystem.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The primilarly goal of skore is to create data science artifacts in the form of structured reports. Those reports can easily be used programmatically via the Python API. A subsequent aim is to store those reports that you create during your experiment cycle in a way that it is easy to retrieve them later on.">

.. only:: html

  .. image:: /auto_examples/integrations/images/thumb/sphx_glr_plot_skore_mlflow_project_thumb.png
    :alt:

  :doc:`/auto_examples/integrations/plot_skore_mlflow_project`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Store and retrieve Skore reports in MLflow</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to use Project in hub mode: store reports remotely and inspect them. A key point is that summarize returns a Summary object that holds the metadata and metrics of every report. In Jupyter it renders as an interactive table with different views where you can filter and pick rows to build a query string; outside of Jupyter you can work with the underlying pandas.DataFrame via its frame method.">

.. only:: html

  .. image:: /auto_examples/integrations/images/thumb/sphx_glr_plot_skore_hub_project_thumb.png
    :alt:

  :doc:`/auto_examples/integrations/plot_skore_hub_project`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Store and retrieve reports on Skore Hub</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to use skore with scikit-learn compatible estimators.">

.. only:: html

  .. image:: /auto_examples/integrations/images/thumb/sphx_glr_plot_sklearn_api_thumb.png
    :alt:

  :doc:`/auto_examples/integrations/plot_sklearn_api`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Using skore with scikit-learn compatible estimators</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Technical details
-----------------

These examples show some technical details at the core of skore to better understand
some of the mechanics under the hood.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="skore lets you extend the built-in automated checks with your own. This example shows how to write a custom check function and register it with a report via add.">

.. only:: html

  .. image:: /auto_examples/technical_details/images/thumb/sphx_glr_plot_custom_checks_thumb.png
    :alt:

  :doc:`/auto_examples/technical_details/plot_custom_checks`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Adding custom checks</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="skore can automatically detect common modeling pitfalls such as overfitting and underfitting. This example walks through the checks accessor: how to run checks, how to read the detected issues, and how to mute specific checks.">

.. only:: html

  .. image:: /auto_examples/technical_details/images/thumb/sphx_glr_plot_checks_api_thumb.png
    :alt:

  :doc:`/auto_examples/technical_details/plot_checks_api`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Automatic detection of modelling issues</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how EstimatorReport and CrossValidationReport use caching to speed up computations.">

.. only:: html

  .. image:: /auto_examples/technical_details/images/thumb/sphx_glr_plot_cache_mechanism_thumb.png
    :alt:

  :doc:`/auto_examples/technical_details/plot_cache_mechanism`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Cache mechanism</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to use Project in local mode: store reports on your machine and inspect them. A key point is that summarize returns a Summary object that holds the metadata and metrics of every report. In Jupyter it renders as an interactive table with three views (Table, parallel-coordinates Plot, and Trend) where you can filter and pick reports to build a query string; the underlying pandas.DataFrame is accessible through its frame method.">

.. only:: html

  .. image:: /auto_examples/technical_details/images/thumb/sphx_glr_plot_skore_local_project_thumb.png
    :alt:

  :doc:`/auto_examples/technical_details/plot_skore_local_project`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Local skore Project</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Skore has three types of reports: EstimatorReport (single train-test evaluation), CrossValidationReport (cross-validation), and ComparisonReport (comparing several estimators). All three are created via evaluate by passing an estimator (or a list or dict of named estimators for comparison), the data X and y, and a splitter that controls the evaluation strategy.">

.. only:: html

  .. image:: /auto_examples/technical_details/images/thumb/sphx_glr_plot_skore_api_thumb.png
    :alt:

  :doc:`/auto_examples/technical_details/plot_skore_api`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">The skore API</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="When a skrub DataOp defines a cross-validation splitter on mark_as_X, evaluate can reuse that configuration — including split_kwargs such as groups — instead of skore&#x27;s default 80/20 holdout.">

.. only:: html

  .. image:: /auto_examples/technical_details/images/thumb/sphx_glr_plot_skrub_data_op_cv_thumb.png
    :alt:

  :doc:`/auto_examples/technical_details/plot_skrub_data_op_cv`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Using skrub DataOp cross-validation</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /auto_examples/getting_started/index.rst
   /auto_examples/use_cases/index.rst
   /auto_examples/model_evaluation/index.rst
   /auto_examples/pitfalls_and_solutions/index.rst
   /auto_examples/integrations/index.rst
   /auto_examples/technical_details/index.rst


.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-gallery

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download all examples in Python source code: auto_examples_python.zip </auto_examples/auto_examples_python.zip>`

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download all examples in Jupyter notebooks: auto_examples_jupyter.zip </auto_examples/auto_examples_jupyter.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_