.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/skore_project/plot_tracking_items.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_examples_skore_project_plot_tracking_items.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_skore_project_plot_tracking_items.py:


.. _example_tracking_items:

==============
Tracking items
==============

This example illustrates how skore can be used to track some items using their history,
for example tracking some ML metrics over time.

.. GENERATED FROM PYTHON SOURCE LINES 13-15

Creating and loading the skore project
======================================

.. GENERATED FROM PYTHON SOURCE LINES 17-18

We create and load the skore project in the current directory:

.. GENERATED FROM PYTHON SOURCE LINES 20-25

.. code-block:: Python

    import skore


    my_project = skore.Project("my_project")








.. GENERATED FROM PYTHON SOURCE LINES 35-37

Tracking an integer
===================

.. GENERATED FROM PYTHON SOURCE LINES 39-41

Let us store several integer values for a same item called ``my_int``, each storage
being separated by 0.1 second:

.. GENERATED FROM PYTHON SOURCE LINES 43-53

.. code-block:: Python

    import time

    my_project.put("my_int", 4)

    time.sleep(0.1)
    my_project.put("my_int", 9)

    time.sleep(0.1)
    my_project.put("my_int", 16)








.. GENERATED FROM PYTHON SOURCE LINES 54-55

We retrieve the history of the ``my_int`` item:

.. GENERATED FROM PYTHON SOURCE LINES 57-59

.. code-block:: Python

    history = my_project.get("my_int", version="all", metadata=True)








.. GENERATED FROM PYTHON SOURCE LINES 60-61

We can print the details of the first version of this item:

.. GENERATED FROM PYTHON SOURCE LINES 63-66

.. code-block:: Python


    print(history[0])





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    {'value': 4, 'date': '2025-02-21T10:38:09.807602+00:00', 'note': None}




.. GENERATED FROM PYTHON SOURCE LINES 67-68

Let us construct a dataframe with the values and last updated times:

.. GENERATED FROM PYTHON SOURCE LINES 70-87

.. code-block:: Python

    import numpy as np
    import pandas as pd

    list_value, list_created_at, list_updated_at = zip(
        *[(version["value"], history[0]["date"], version["date"]) for version in history]
    )

    df_track = pd.DataFrame(
        {
            "value": list_value,
            "created_at": list_created_at,
            "updated_at": list_updated_at,
        }
    )
    df_track.insert(0, "version_number", np.arange(len(df_track)))
    df_track






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>version_number</th>
          <th>value</th>
          <th>created_at</th>
          <th>updated_at</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>0</td>
          <td>4</td>
          <td>2025-02-21T10:38:09.807602+00:00</td>
          <td>2025-02-21T10:38:09.807602+00:00</td>
        </tr>
        <tr>
          <th>1</th>
          <td>1</td>
          <td>9</td>
          <td>2025-02-21T10:38:09.807602+00:00</td>
          <td>2025-02-21T10:38:09.917174+00:00</td>
        </tr>
        <tr>
          <th>2</th>
          <td>2</td>
          <td>16</td>
          <td>2025-02-21T10:38:09.807602+00:00</td>
          <td>2025-02-21T10:38:10.022275+00:00</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 88-95

.. role:: python(code)
  :language: python

Notice that the ``created_at`` dates are the same for all iterations because they
correspond to the date of the first version of the item, but the ``updated_at`` dates
are spaced by 0.1 second (approximately) as we used :python:`time.sleep(0.1)` between
each :func:`~skore.Project.put`.

.. GENERATED FROM PYTHON SOURCE LINES 97-98

We can now track the value of the item over time:

.. GENERATED FROM PYTHON SOURCE LINES 100-112

.. code-block:: Python

    import plotly.express as px

    fig = px.line(
        df_track,
        x="version_number",
        y="value",
        hover_data=df_track.columns,
        markers=True,
    )
    fig.update_layout(xaxis_type="category")
    fig








.. GENERATED FROM PYTHON SOURCE LINES 116-119

.. note::
  We can hover over the histories of the item to visualize the last update date for
  example.

.. GENERATED FROM PYTHON SOURCE LINES 121-130

Here, we focused on *how* to use skore's tracking of history of items.
But *why* track items?

* We could track some items such as machine learning scores over time to better
  understand which feature engineering works best.

* Avoid overwriting a useful metric by mistake. No results are can be lost.

* The last updated time can help us reproduce an iteration of a key metric.


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.466 seconds)


.. _sphx_glr_download_auto_examples_skore_project_plot_tracking_items.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

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

      :download:`Download Jupyter notebook: plot_tracking_items.ipynb <plot_tracking_items.ipynb>`

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

      :download:`Download Python source code: plot_tracking_items.py <plot_tracking_items.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_tracking_items.zip <plot_tracking_items.zip>`


.. only:: html

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

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