diff --git a/doc/api.rst b/doc/api.rst index c79485fde..f76e8c85e 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -3,16 +3,14 @@ API .. currentmodule:: skore -*The API is currently work in progress and will be released soon, thank you for -your patience!* - This page lists all the public functions and classes of the ``skore`` package. -The User Interface ------------------- -These classes are meant for ``skore``'s UI. +The ``skore`` UI +---------------- + +These classes are meant for ``skore``'s user interface. .. autosummary:: :toctree: generated/ @@ -21,12 +19,21 @@ These classes are meant for ``skore``'s UI. Project -``scikit-learn`` enhancement ----------------------------- +.. autosummary:: + :toctree: generated/ + :template: function.rst + :nosignatures: -These classes enhance ``scikit-learn``'s ones. + load + +The ``skore`` machine learning programming assistant +---------------------------------------------------- + +These functions and classes enhance ``scikit-learn``'s ones. .. autosummary:: :toctree: generated/ - :template: class.rst + :template: function.rst :nosignatures: + + cross_validate diff --git a/doc/generated/skore.cross_validate.rst b/doc/generated/skore.cross_validate.rst new file mode 100644 index 000000000..3e20db320 --- /dev/null +++ b/doc/generated/skore.cross_validate.rst @@ -0,0 +1,10 @@ +:mod:`skore`.cross_validate +======================================== + +.. currentmodule:: skore + +.. autofunction:: cross_validate + +.. raw:: html + +
diff --git a/doc/generated/skore.load.rst b/doc/generated/skore.load.rst new file mode 100644 index 000000000..c7f823087 --- /dev/null +++ b/doc/generated/skore.load.rst @@ -0,0 +1,10 @@ +:mod:`skore`.load +============================== + +.. currentmodule:: skore + +.. autofunction:: load + +.. raw:: html + + diff --git a/doc/sg_execution_times.rst b/doc/sg_execution_times.rst index fc2bf8ef8..2c959ce19 100644 --- a/doc/sg_execution_times.rst +++ b/doc/sg_execution_times.rst @@ -6,7 +6,7 @@ Computation times ================= -**00:00.769** total execution time for 2 files **from all galleries**: +**00:02.306** total execution time for 2 files **from all galleries**: .. container:: @@ -32,9 +32,9 @@ Computation times * - Example - Time - Mem (MB) - * - :ref:`sphx_glr_auto_examples_plot_02_basic_usage.py` (``../examples/plot_02_basic_usage.py``) - - 00:00.632 - - 0.0 * - :ref:`sphx_glr_auto_examples_plot_01_getting_started.py` (``../examples/plot_01_getting_started.py``) - - 00:00.136 + - 00:02.306 + - 0.0 + * - :ref:`sphx_glr_auto_examples_plot_02_basic_usage.py` (``../examples/plot_02_basic_usage.py``) + - 00:00.000 - 0.0 diff --git a/doc/user_guide.rst b/doc/user_guide.rst index 02f8c3b6f..392169b05 100644 --- a/doc/user_guide.rst +++ b/doc/user_guide.rst @@ -7,3 +7,5 @@ User guide *The User Guide is currently work in progress and will be released soon, thank you for your patience!* + +For now, please look into the ``Getting Started`` and ``Examples`` tab. diff --git a/doc/user_guide/getting_started.rst b/doc/user_guide/getting_started.rst new file mode 100644 index 000000000..90d824ef1 --- /dev/null +++ b/doc/user_guide/getting_started.rst @@ -0,0 +1,107 @@ +.. _getting_started: + +Getting started with ``skore`` +============================== + +This example builds on top of the :ref:`getting_started` guide. + +``skore`` UI +------------ + +This section provides a quick start to the ``skore`` UI, an open-source package that aims to enable data scientists to: + +#. Store objects of different types from their Python code: python lists, ``scikit-learn`` fitted pipelines, ``plotly`` figures, and more. +#. Track and visualize these stored objects on a user-friendly dashboard. +#. Export the dashboard to a HTML file. + +Initialize a Project and launch the UI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +From your shell, initialize a skore project, here named ``project``, that will be +in your current working directory: + +.. code:: console + + python -m skore create "project" + +This will create a ``skore`` project directory named ``project`` in the current +directory. + +From your shell (in the same directory), start the UI locally: + +.. code:: console + + python -m skore launch "project" + +This will automatically open a browser at the UI's location. + +Now that the project file exists, we can load it in our notebook so that we can +read from and write to it: + +.. code-block:: python + + from skore import load + + project = load("project.skore") + +Storing some items +------------------ + +Storing an integer: + +.. code-block:: python + + project.put("my_int", 3) + +Here, the name of my stored item is ``my_int`` and the integer value is 3. + +For a ``pandas`` data frame: + +.. code-block:: python + + import numpy as np + import pandas as pd + + my_df = pd.DataFrame(np.random.randn(3, 3)) + + project.put("my_df", my_df) + + +For a ``matplotlib`` figure: + +.. code-block:: python + + import matplotlib.pyplot as plt + + x = [0, 1, 2, 3, 4, 5] + fig, ax = plt.subplots(figsize=(5, 3), layout="constrained") + _ = ax.plot(x) + + project.put("my_figure", fig) + +For a ``scikit-learn`` fitted pipeline: + +.. code-block:: python + + from sklearn.datasets import load_diabetes + from sklearn.linear_model import Lasso + from sklearn.pipeline import Pipeline + from sklearn.preprocessing import StandardScaler + + diabetes = load_diabetes() + X = diabetes.data[:150] + y = diabetes.target[:150] + my_pipeline = Pipeline( + [("standard_scaler", StandardScaler()), ("lasso", Lasso(alpha=2))] + ) + my_pipeline.fit(X, y) + + project.put("my_fitted_pipeline", my_pipeline) + +Back to the dashboard +^^^^^^^^^^^^^^^^^^^^^ +#. On the top left, create a new ``View``. +#. From the ``Elements`` section on the bottom left, you can add stored items to this view, either by double-cliking on them or by doing drag-and-drop. + +.. image:: https://raw.githubusercontent.com/sylvaincom/sylvaincom.github.io/master/files/probabl/skore/2024_10_14_skore_demo.gif + :alt: Getting started with ``skore`` demo diff --git a/examples/plot_01_getting_started.py b/examples/plot_01_getting_started.py index a2cdb89c3..bc9819910 100644 --- a/examples/plot_01_getting_started.py +++ b/examples/plot_01_getting_started.py @@ -3,7 +3,7 @@ Getting started with ``skore`` ============================== -This example builds on top of the :ref:`getting_started` guide. +This example runs the `Getting started` guide. ``skore`` UI ------------ @@ -17,47 +17,54 @@ Initialize a Project and launch the UI ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -From your shell, initialize a skore project, here named ``project``, that will be -in your current working directory: - -.. code:: console - - python -m skore create "project" - -This will create a ``skore`` project directory named ``project`` in the current -directory. - -From your shell (in the same directory), start the UI locally: - -.. code:: console +From your shell, initialize a skore project, here named ``my_project_gs``, that +will be in your current working directory: +""" - python -m skore launch "project" +# %% +import subprocess -This will automatically open a browser at the UI's location. +# remove the project if it already exists +subprocess.run("rm -rf my_project_gs.skore".split()) -Now that the project file exists, we can load it in our notebook so that we can -read from and write to it: -""" +# create the project +subprocess.run("python3 -m skore create my_project_gs".split()) # %% -# .. code-block:: python +# This will create a ``skore`` project directory named ``my_project_gs`` in the +# current directory. +# +# From your shell (in the same directory), start the UI locally: # -# from skore import load +# .. code:: console # -# project = load("project.skore") +# python -m skore launch "my_project_gs" +# +# This will automatically open a browser at the UI's location. +# +# Now that the project file exists, we can load it in our notebook so that we can +# read from and write to it: + +# %% +from skore import load + +my_project_gs = load("my_project_gs.skore") # %% # Storing some items -# ------------------ +# ^^^^^^^^^^^^^^^^^^ # # Storing an integer: -# -# .. code-block:: python -# -# project.put("my_int", 3) -# + +# %% +my_project_gs.put("my_int", 3) + +# %% # Here, the name of my stored item is ``my_int`` and the integer value is 3. +# %% +my_project_gs.get("my_int") + # %% # For a ``pandas`` data frame: @@ -66,12 +73,11 @@ import pandas as pd my_df = pd.DataFrame(np.random.randn(3, 3)) -my_df.head() + +my_project_gs.put("my_df", my_df) # %% -# .. code-block:: python -# -# project.put("my_df", my_df) +my_project_gs.get("my_df") # %% # For a ``matplotlib`` figure: @@ -83,10 +89,7 @@ fig, ax = plt.subplots(figsize=(5, 3), layout="constrained") _ = ax.plot(x) -# %% -# .. code-block:: python -# -# project.put("my_figure", fig) +my_project_gs.put("my_figure", fig) # %% # For a ``scikit-learn`` fitted pipeline: @@ -105,11 +108,12 @@ ) my_pipeline.fit(X, y) +my_project_gs.put("my_fitted_pipeline", my_pipeline) + +# %% +my_project_gs.get("my_fitted_pipeline") + # %% -# .. code-block:: python -# -# project.put("my_fitted_pipeline", my_pipeline) -# # Back to the dashboard # ^^^^^^^^^^^^^^^^^^^^^ # @@ -118,4 +122,3 @@ # # .. image:: https://raw.githubusercontent.com/sylvaincom/sylvaincom.github.io/master/files/probabl/skore/2024_10_14_skore_demo.gif # :alt: Getting started with ``skore`` demo -# diff --git a/examples/plot_02_basic_usage.py b/examples/plot_02_basic_usage.py index 71bc55336..63385df9e 100644 --- a/examples/plot_02_basic_usage.py +++ b/examples/plot_02_basic_usage.py @@ -31,3 +31,25 @@ sklearn.__version__ plt.plot([0, 1, 2, 3], [0, 1, 2, 3]) plt.show() + +# %% +import subprocess + +subprocess.run("rm -rf my_project_doc.skore".split()) +subprocess.run("python3 -m skore create my_project_doc".split()) + +# %% +from skore import load +from sklearn import datasets, linear_model +from skore.cross_validate import cross_validate + +my_project_doc = load("my_project_doc") + +diabetes = datasets.load_diabetes() +X = diabetes.data[:150] +y = diabetes.target[:150] +lasso = linear_model.Lasso() + +cv_results = cross_validate(lasso, X, y, cv=3, project=my_project_doc) + +my_project_doc.get_item("cross_validation").plot