diff --git a/README.md b/README.md index 508956d00..e171a0121 100644 --- a/README.md +++ b/README.md @@ -1,78 +1,96 @@ -# skore +# 👋 Welcome to skore ![ci](https://github.com/probabl-ai/skore/actions/workflows/ci.yml/badge.svg?event=push) ![python](https://img.shields.io/badge/python-3.11%20|%203.12-blue?style=flat&logo=python) -## Installation +`skore` allows data scientists to create tracking and visualization from their Python code: +1. Users can store objects of different types: python lists and dictionaries, `numpy` arrays, `scikit-learn` fitted models, `matplotlib`, `altair`, and `plotly` figures, etc. Storing some values over time allows one to perform **tracking** and also to **visualize** them: +2. They can visualize these stored objects on a dashboard. The dashboard is user-friendly: objects can easily be organized. +3. This dashboard can be exported into a HTML file. -For now, the only supported method to use skore is from source. -Follow the instructions in [CONTRIBUTING.md](https://github.com/probabl-ai/skore/blob/main/CONTRIBUTING.md#quick-start) to install dependencies and start the UI. +These are only the first features of `skore`'s roadmap. +`skore` is a work in progress and, on the long run, it aims to be an all-inclusive library for data scientists. +Stay tuned! -## Quick start +

+ +

-For a complete introductory example, see our [basic usage notebook](https://github.com/probabl-ai/skore/blob/main/examples/basic_usage.ipynb). The resulting skore report has been exported to [this HTML file](https://gist.github.com/augustebaum/6b21dbd7f7d5a584fbf2c1956692574e): download it and open it in your browser to visualize it. +## ⚙️ Installation + +You can install `skore` by using `pip`: +```bash +pip install -U skore +``` + +## 🚀 Quick start +======= In your shell, run the following to create a project file `project.skore` (the default) in your current working directory: -```sh -python -m skore create +```bash +python -m skore create 'project.skore' ``` -Run the following in your Python code to load the project: +Run the following in your Python code (in the same working directory) to load the project, store some objects, delete them, etc: ```python from skore import load +# load the project project = load("project.skore") -``` -You can save items you need to track in your project: -```python +# save an item you need to track in your project project.put("my int", 3) -``` -You can also get them back: -```python +# get an item's value project.get("my int") -``` -By default, strings are assumed to be Markdown: -```python +# by default, strings are assumed to be Markdown: project.put("my string", "Hello world!") -``` -Note that `put` overwrites previous data -```python +# `put` overwrites previous data project.put("my string", "Hello again!") -``` -You can list all the keys in a project with: -```python -project.list_keys() -``` +# list all the keys in a project +print(project.list_item_keys()) -You can delete items with: -```python +# delete an item project.delete_item("my int") ``` -Then, in the directory containing your project, run the following command to start the UI locally: -```sh +Then, in the directory containing your project, run the following command in your shell to start the UI locally: +```bash python -m skore launch project.skore ``` - This will automatically open a browser at the UI's location. +In the `Elements` tab on the left, you can visualize the stored items. +Create a new `View`, then you can then add items into this view. + +💡 Note that after launching the dashboard, you can keep modifying current items or store new ones, and the dashboard will automatically be refreshed. + +👨‍🏫 For a complete introductory example, see our [basic usage notebook](https://github.com/probabl-ai/skore/blob/main/examples/basic_usage.ipynb). +It shows you how to store all types of items: python lists and dictionaries, `numpy` arrays, `scikit-learn` fitted models, `matplotlib`, `altair`, and `plotly` figures, etc. +The resulting `skore` report has been exported to [this HTML file](https://sylvaincom.github.io/files/probabl/skore/basic_usage.html). + +## 🔨 Contributing + +Thank you for your interest! +See [CONTRIBUTING.md](https://github.com/probabl-ai/skore/blob/main/CONTRIBUTING.md). +## 💬 Where to ask questions -## Roadmap +| Type | Platforms | +|-------------------------------------|----------------------------------| +| 🐛 Bug reports | [GitHub Issue Tracker] | +| ✨ Feature requests and ideas | [GitHub Issue Tracker] & [Discord] | +| 💬 Usage questions, discussions, contributions, etc | [Discord] | -With Skore, you can: -- Store data -- Visualize data +[GitHub Issue Tracker]: https://github.com/probabl-ai/skore/issues +[Discord]: https://discord.gg/scBZerAGwW -In the future, you will be able to: -- Share visualizations of your data -- Extract insights from your data -- Get tips on how to improve your data science code +--- -## Contributing +Brought to you by: -See [CONTRIBUTING.md](https://github.com/probabl-ai/skore/blob/main/CONTRIBUTING.md) for more information and to contribute to the evolution of this library. + + Probabl logo + diff --git a/examples/basic_usage.ipynb b/examples/basic_usage.ipynb index 09a713fad..5e0c9153d 100644 --- a/examples/basic_usage.ipynb +++ b/examples/basic_usage.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "31f5797e", + "id": "0", "metadata": {}, "source": [ "# Getting started with `skore`" @@ -10,19 +10,24 @@ }, { "cell_type": "markdown", - "id": "5eaf0f80", + "id": "1", "metadata": {}, "source": [ "# Introduction\n", "\n", - "The purpose of this guide is to illustrate some of the main features that `skore` provides. Please refer to our instructions for installing `skore`.\n", + "The purpose of this guide is to illustrate some of the main features that `skore` currently provides.\n", "\n", - "Given to you by [:probabl.](https://probabl.ai/), `skore` is a powerful tool that allows data scientists to create tracking and clear reports from their Python code, typically a notebook. For example, see [this HTML file](https://gist.github.com/augustebaum/6b21dbd7f7d5a584fbf2c1956692574e): download it and open it in your browser to visualize it." + "`skore` allows data scientists to create tracking and visualizations from their Python code:\n", + "1. Users can store objects of different types (python lists and dictionaries, `numpy` arrays, `scikit-learn` fitted models, `matplotlib`, `altair`, and `plotly` figures, etc). Storing some values over time allows one to perform **tracking** and also to **visualize** them:\n", + "2. They can visualize these stored objects on a dashboard. The dashboard is user-friendly: objects can easily be organized.\n", + "3. This dashboard can be exported into a HTML file.\n", + "\n", + "This notebook will store some items that have been used to generated a skore report available at [this link](https://sylvaincom.github.io/files/probabl/skore/basic_usage.html): download this HTML file and open it in your browser to visualize it." ] }, { "cell_type": "markdown", - "id": "817609d9", + "id": "2", "metadata": {}, "source": [ "## Imports" @@ -31,17 +36,16 @@ { "cell_type": "code", "execution_count": null, - "id": "d6f56c15", + "id": "3", "metadata": {}, "outputs": [], "source": [ - "# ruff: noqa\n", - "\n", "import altair as alt\n", "import io\n", "import matplotlib.pyplot as plt\n", "import numpy as np\n", "import pandas as pd\n", + "import plotly.express as px\n", "import PIL\n", "\n", "from sklearn.datasets import load_diabetes\n", @@ -55,48 +59,27 @@ }, { "cell_type": "markdown", - "id": "b68aa7de", + "id": "4", "metadata": {}, "source": [ "# Initialize and use a Project\n", "\n", - "To initialize a Project, we need to give it a name, or equivalently a file path:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "23f035b6", - "metadata": {}, - "outputs": [], - "source": [ - "# Create a project at path './project.skore'\n", - "!python -m skore create 'project.skore'" - ] - }, - { - "cell_type": "markdown", - "id": "1fbcfbbf", - "metadata": {}, - "source": [ - "This will create a Skore project directory named \"project.skore\" in the current directory." - ] - }, - { - "cell_type": "markdown", - "id": "964267f0", - "metadata": {}, - "source": [ - "Now that you have created the `project.skore` folder (even though nothing has yet been stored), you can run the UI (in your project root i.e. where `project.skore` is):\n", + "To initialize a Project, we need to give it a name, or equivalently a file path. In your shell, run:\n", + "```bash\n", + "$ python -m skore create 'project.skore'\n", + "```\n", + "This will create a Skore project directory named \"project.skore\" in the current directory.\n", + "\n", + "Now that you have created the `project.skore` folder (even though nothing has yet been stored), you can run the UI (in your project root i.e. where `project.skore` is) from your shell:\n", "```python3\n", "$ python -m skore launch project.skore\n", "```\n", "\n", - ">*Note*: If you already had some data in your `project.skore` directory from a previous run -- you can check for that in your shell by using:\n", + ">*Note*: If you already had a `project.skore` directory from a previous run -- you can check for that in your shell by using:\n", ">```python3\n", ">$ ls\n", ">```\n", - ">and if you no longer need its objects, we recommend deleting this folder by running `rm` in your shell:\n", + ">and if you no longer need it, we recommend deleting this folder by running `rm` in your shell:\n", ">```python3\n", ">$ rm -r project.skore\n", ">```\n", @@ -105,16 +88,16 @@ }, { "cell_type": "markdown", - "id": "1d7a45e5", + "id": "5", "metadata": {}, "source": [ - "Now that the project file exists, we can load it in our script so that we can read from and write to it:" + "Now that the project file exists, we can load it in our notebook so that we can read from and write to it:" ] }, { "cell_type": "code", "execution_count": null, - "id": "6e4d51c7", + "id": "6", "metadata": {}, "outputs": [], "source": [ @@ -123,7 +106,7 @@ }, { "cell_type": "markdown", - "id": "0419195c", + "id": "7", "metadata": {}, "source": [ "## Storing an integer" @@ -131,7 +114,7 @@ }, { "cell_type": "markdown", - "id": "05f7f17f", + "id": "8", "metadata": {}, "source": [ "Now, let us store our first object, for example an integer:" @@ -140,7 +123,7 @@ { "cell_type": "code", "execution_count": null, - "id": "31fc4cc8", + "id": "9", "metadata": {}, "outputs": [], "source": [ @@ -149,7 +132,7 @@ }, { "cell_type": "markdown", - "id": "dc643253", + "id": "10", "metadata": {}, "source": [ "Here, the name of my object is `my_int` and the integer value is 3.\n", @@ -160,7 +143,7 @@ { "cell_type": "code", "execution_count": null, - "id": "19053a47", + "id": "11", "metadata": {}, "outputs": [], "source": [ @@ -169,7 +152,7 @@ }, { "cell_type": "markdown", - "id": "8af44c95", + "id": "12", "metadata": {}, "source": [ "Careful; like in a traditional Python dictionary, the `put` method will *overwrite* past data if you use a key which already exists!" @@ -178,7 +161,7 @@ { "cell_type": "code", "execution_count": null, - "id": "5f3ffd54", + "id": "13", "metadata": {}, "outputs": [], "source": [ @@ -187,7 +170,7 @@ }, { "cell_type": "markdown", - "id": "72a29907", + "id": "14", "metadata": {}, "source": [ "Let us check the updated value:" @@ -196,7 +179,7 @@ { "cell_type": "code", "execution_count": null, - "id": "00f983cc", + "id": "15", "metadata": {}, "outputs": [], "source": [ @@ -205,7 +188,7 @@ }, { "cell_type": "markdown", - "id": "11e83006", + "id": "16", "metadata": {}, "source": [ "By using the `delete_item` method, you can also delete an object so that your `skore` UI does not become cluttered:" @@ -214,7 +197,7 @@ { "cell_type": "code", "execution_count": null, - "id": "97d162d2", + "id": "17", "metadata": {}, "outputs": [], "source": [ @@ -224,7 +207,7 @@ { "cell_type": "code", "execution_count": null, - "id": "94f7001a", + "id": "18", "metadata": {}, "outputs": [], "source": [ @@ -233,7 +216,7 @@ }, { "cell_type": "markdown", - "id": "17b5f6a0", + "id": "19", "metadata": {}, "source": [ "You can use `project.list_item_keys` to display all the keys in your project:" @@ -242,7 +225,7 @@ { "cell_type": "code", "execution_count": null, - "id": "e7f30789", + "id": "20", "metadata": {}, "outputs": [], "source": [ @@ -251,7 +234,7 @@ }, { "cell_type": "markdown", - "id": "12b5a0c0", + "id": "21", "metadata": {}, "source": [ "## Storing a string" @@ -259,7 +242,7 @@ }, { "cell_type": "markdown", - "id": "d38fcff8", + "id": "22", "metadata": {}, "source": [ "We just stored a integer, now let us store some text using strings!" @@ -268,7 +251,7 @@ { "cell_type": "code", "execution_count": null, - "id": "90bbe0ec", + "id": "23", "metadata": {}, "outputs": [], "source": [ @@ -278,7 +261,7 @@ { "cell_type": "code", "execution_count": null, - "id": "4b805bd5", + "id": "24", "metadata": {}, "outputs": [], "source": [ @@ -287,7 +270,7 @@ }, { "cell_type": "markdown", - "id": "6348a8dc", + "id": "25", "metadata": {}, "source": [ "`project.get` infers the type of the inserted object by default. For example, strings are assumed to be in Markdown format. Hence, you can customize the display of your text:" @@ -296,7 +279,7 @@ { "cell_type": "code", "execution_count": null, - "id": "b67679af", + "id": "26", "metadata": {}, "outputs": [], "source": [ @@ -316,7 +299,7 @@ }, { "cell_type": "markdown", - "id": "8f8bc0e3", + "id": "27", "metadata": {}, "source": [ "Moreover, you can also explicitly tell `skore` the media type of an object, for example in HTML:" @@ -325,7 +308,7 @@ { "cell_type": "code", "execution_count": null, - "id": "2e93653f", + "id": "28", "metadata": {}, "outputs": [], "source": [ @@ -340,7 +323,7 @@ }, { "cell_type": "markdown", - "id": "aeac33be", + "id": "29", "metadata": {}, "source": [ "Note that the media type is only used for the UI, and not in this notebook at hand:" @@ -349,7 +332,7 @@ { "cell_type": "code", "execution_count": null, - "id": "37a9c8ae", + "id": "30", "metadata": {}, "outputs": [], "source": [ @@ -358,7 +341,7 @@ }, { "cell_type": "markdown", - "id": "3c52a9dd", + "id": "31", "metadata": {}, "source": [ "You can also conveniently use Python f-strings:" @@ -367,7 +350,7 @@ { "cell_type": "code", "execution_count": null, - "id": "427533bb", + "id": "32", "metadata": {}, "outputs": [], "source": [ @@ -378,7 +361,7 @@ }, { "cell_type": "markdown", - "id": "f128b0c2", + "id": "33", "metadata": {}, "source": [ "## Storing many kinds of data" @@ -386,7 +369,7 @@ }, { "cell_type": "markdown", - "id": "8059cd6b", + "id": "34", "metadata": {}, "source": [ "Python list:" @@ -395,7 +378,7 @@ { "cell_type": "code", "execution_count": null, - "id": "271d5e8b", + "id": "35", "metadata": {}, "outputs": [], "source": [ @@ -405,7 +388,7 @@ }, { "cell_type": "markdown", - "id": "9ec88d84", + "id": "36", "metadata": {}, "source": [ "Python dictionary:" @@ -414,7 +397,7 @@ { "cell_type": "code", "execution_count": null, - "id": "8d6cb2b3", + "id": "37", "metadata": {}, "outputs": [], "source": [ @@ -427,7 +410,7 @@ }, { "cell_type": "markdown", - "id": "893e2231", + "id": "38", "metadata": {}, "source": [ "NumPy array:" @@ -436,7 +419,7 @@ { "cell_type": "code", "execution_count": null, - "id": "cba91e88", + "id": "39", "metadata": {}, "outputs": [], "source": [ @@ -446,7 +429,7 @@ }, { "cell_type": "markdown", - "id": "7fedf721", + "id": "40", "metadata": {}, "source": [ "Pandas data frame:" @@ -455,7 +438,7 @@ { "cell_type": "code", "execution_count": null, - "id": "76e90ff7", + "id": "41", "metadata": {}, "outputs": [], "source": [ @@ -465,24 +448,26 @@ }, { "cell_type": "markdown", - "id": "efe93568", + "id": "42", "metadata": {}, "source": [ - "## Data visualization" + "## Data visualization\n", + "\n", + "Note that, in the dashboard, the interactivity of plots is supported, for example for `altair` and `plotly`." ] }, { "cell_type": "markdown", - "id": "46cc9344", + "id": "43", "metadata": {}, "source": [ - "Matplotlib Figures:" + "Matplotlib figures:" ] }, { "cell_type": "code", "execution_count": null, - "id": "e5ed6a5e", + "id": "44", "metadata": {}, "outputs": [], "source": [ @@ -503,16 +488,16 @@ }, { "cell_type": "markdown", - "id": "727b319c", + "id": "45", "metadata": {}, "source": [ - "Altair Charts:" + "Altair charts:" ] }, { "cell_type": "code", "execution_count": null, - "id": "b47150af", + "id": "46", "metadata": {}, "outputs": [], "source": [ @@ -521,20 +506,41 @@ " {\"x\": np.random.randn(num_points), \"y\": np.random.randn(num_points)}\n", ")\n", "\n", - "my_chart = (\n", + "my_altair_chart = (\n", " alt.Chart(df_plot)\n", " .mark_circle()\n", " .encode(x=\"x\", y=\"y\", tooltip=[\"x\", \"y\"])\n", " .interactive()\n", " .properties(title=\"My title\")\n", ")\n", + "my_altair_chart.show()\n", "\n", - "project.put(\"my_chart\", my_chart)" + "project.put(\"my_altair_chart\", my_altair_chart)" + ] + }, + { + "cell_type": "markdown", + "id": "47", + "metadata": {}, + "source": [ + "Plotly figures:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "48", + "metadata": {}, + "outputs": [], + "source": [ + "my_plotly_fig = px.bar(x=[\"a\", \"b\", \"c\"], y=[1, 3, 2])\n", + "my_plotly_fig.show()\n", + "project.put(\"my_plotly_fig\", my_plotly_fig)" ] }, { "cell_type": "markdown", - "id": "9aed47d9", + "id": "49", "metadata": {}, "source": [ "PIL images:" @@ -543,7 +549,7 @@ { "cell_type": "code", "execution_count": null, - "id": "183c2e51", + "id": "50", "metadata": {}, "outputs": [], "source": [ @@ -556,7 +562,7 @@ }, { "cell_type": "markdown", - "id": "ac2d4024", + "id": "51", "metadata": {}, "source": [ "## Scikit-learn models and pipelines\n", @@ -569,7 +575,7 @@ { "cell_type": "code", "execution_count": null, - "id": "b1e071f7", + "id": "52", "metadata": {}, "outputs": [], "source": [ @@ -579,7 +585,7 @@ }, { "cell_type": "markdown", - "id": "124c4690", + "id": "53", "metadata": {}, "source": [ "You can also store scikit-learn pipelines:" @@ -588,7 +594,7 @@ { "cell_type": "code", "execution_count": null, - "id": "238a8fe5", + "id": "54", "metadata": {}, "outputs": [], "source": [ @@ -600,7 +606,7 @@ }, { "cell_type": "markdown", - "id": "7235e282", + "id": "55", "metadata": {}, "source": [ "Moreover, you can store fitted scikit-learn pipelines:" @@ -609,7 +615,7 @@ { "cell_type": "code", "execution_count": null, - "id": "deb9d103", + "id": "56", "metadata": {}, "outputs": [], "source": [ @@ -623,7 +629,7 @@ }, { "cell_type": "markdown", - "id": "e6b090d3", + "id": "57", "metadata": {}, "source": [ "_Stay tuned for some new features!_" @@ -631,7 +637,7 @@ }, { "cell_type": "markdown", - "id": "555665f0", + "id": "58", "metadata": {}, "source": [ "---\n", @@ -643,125 +649,87 @@ { "cell_type": "code", "execution_count": null, - "id": "30f6f3bf", + "id": "59", "metadata": {}, "outputs": [], "source": [ - "project.put_item(\n", + "project.put(\n", " \"my_comment_1\",\n", - " MediaItem.factory(\n", - " \"

Welcome to skore!

Given to you by :probabl., skore is a powerful tool that allows data scientists to create tracking and clear reports from their Python code, typically a notebook. This HTML document is actually a skore report generated using the `basic_usage.ipynb` notebook that has been exported (into HTML)!

\",\n", - " media_type=\"text/html\",\n", - " ),\n", + " \"

Welcome to skore!

skore allows data scientists to create tracking and reports from their Python code. This HTML document is actually a skore report generated using the basic_usage.ipynb notebook and that has been exported (into HTML)!

\",\n", ")" ] }, { "cell_type": "code", "execution_count": null, - "id": "7e5ed756", + "id": "60", "metadata": {}, "outputs": [], "source": [ - "project.put_item(\n", + "project.put(\n", " \"my_comment_2\",\n", - " MediaItem.factory(\"

Integers

\", media_type=\"text/html\"),\n", + " \"

Integers

\",\n", ")" ] }, { "cell_type": "code", "execution_count": null, - "id": "2108a347", + "id": "61", "metadata": {}, "outputs": [], "source": [ - "project.put_item(\n", - " \"my_comment_3\", MediaItem.factory(\"

Strings

\", media_type=\"text/html\")\n", + "project.put(\n", + " \"my_comment_3\", \"

Strings

\"\n", ")" ] }, { "cell_type": "code", "execution_count": null, - "id": "067e4fdd", + "id": "62", "metadata": {}, "outputs": [], "source": [ - "project.put_item(\n", + "project.put(\n", " \"my_comment_4\",\n", - " MediaItem.factory(\"

Many kinds of data

\", media_type=\"text/html\"),\n", + " \"

Many kinds of data

\",\n", ")" ] }, { "cell_type": "code", "execution_count": null, - "id": "da81ae66", + "id": "63", "metadata": {}, "outputs": [], "source": [ - "project.put_item(\n", + "project.put(\n", " \"my_comment_5\",\n", - " MediaItem.factory(\"

Altair plots

\", media_type=\"text/html\"),\n", + " \"

Plots

\",\n", ")" ] }, { "cell_type": "code", "execution_count": null, - "id": "c65be8c4", + "id": "64", "metadata": {}, "outputs": [], "source": [ - "project.put_item(\n", + "project.put(\n", " \"my_comment_6\",\n", - " MediaItem.factory(\n", - " \"

Scikit-learn models and pipelines

\", media_type=\"text/html\"\n", - " ),\n", + " \"

Scikit-learn models and pipelines

\"\n", ")" ] }, { "cell_type": "code", "execution_count": null, - "id": "e1365efe", + "id": "65", "metadata": {}, "outputs": [], - "source": [ - "project.put_item(\n", - " \"my_comment_7\",\n", - " MediaItem.factory(\n", - " \"

Manipulating the skore report

\", media_type=\"text/html\"\n", - " ),\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "e908bcc2", - "metadata": {}, - "outputs": [], - "source": [ - "project.put_item(\n", - " \"my_comment_8\",\n", - " MediaItem.factory(\n", - " \"

Once you have created cells in your Skore report, you can place them where you want: move them up or down, delete them, for example put one to the left of a graph to comment on it.

\",\n", - " media_type=\"text/html\",\n", - " ),\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "b35e24c8", - "metadata": {}, - "outputs": [], - "source": [ - "project.put(\"my_chart_2\", my_chart)" - ] + "source": [] } ], "metadata": { @@ -772,6 +740,18 @@ "display_name": ".venv", "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.12.7" } }, "nbformat": 4, diff --git a/examples/basic_usage.py b/examples/basic_usage.py index 064735890..964997fc9 100644 --- a/examples/basic_usage.py +++ b/examples/basic_usage.py @@ -6,7 +6,7 @@ # extension: .py # format_name: percent # format_version: '1.3' -# jupytext_version: 1.16.1 +# jupytext_version: 1.16.4 # kernelspec: # display_name: .venv # language: python @@ -19,21 +19,25 @@ # %% [markdown] # # Introduction # -# The purpose of this guide is to illustrate some of the main features that `skore` provides. Please refer to our instructions for installing `skore`. +# The purpose of this guide is to illustrate some of the main features that `skore` currently provides. # -# Given to you by [:probabl.](https://probabl.ai/), `skore` is a powerful tool that allows data scientists to create tracking and clear reports from their Python code, typically a notebook. For example, see [this HTML file](https://gist.github.com/augustebaum/6b21dbd7f7d5a584fbf2c1956692574e): download it and open it in your browser to visualize it. +# `skore` allows data scientists to create tracking and visualizations from their Python code: +# 1. Users can store objects of different types (python lists and dictionaries, `numpy` arrays, `scikit-learn` fitted models, `matplotlib`, `altair`, and `plotly` figures, etc). Storing some values over time allows one to perform **tracking** and also to **visualize** them: +# 2. They can visualize these stored objects on a dashboard. The dashboard is user-friendly: objects can easily be organized. +# 3. This dashboard can be exported into a HTML file. +# +# This notebook will store some items that have been used to generated a skore report available at [this link](https://sylvaincom.github.io/files/probabl/skore/basic_usage.html): download this HTML file and open it in your browser to visualize it. # %% [markdown] # ## Imports # %% -# ruff: noqa - import altair as alt import io import matplotlib.pyplot as plt import numpy as np import pandas as pd +import plotly.express as px import PIL from sklearn.datasets import load_diabetes @@ -47,33 +51,29 @@ # %% [markdown] # # Initialize and use a Project # -# To initialize a Project, we need to give it a name, or equivalently a file path: - -# %% -# Create a project at path './project.skore' -# !python -m skore create 'project.skore' - -# %% [markdown] +# To initialize a Project, we need to give it a name, or equivalently a file path. In your shell, run: +# ```bash +# $ python -m skore create 'project.skore' +# ``` # This will create a Skore project directory named "project.skore" in the current directory. - -# %% [markdown] -# Now that you have created the `project.skore` folder (even though nothing has yet been stored), you can run the UI (in your project root i.e. where `project.skore` is): +# +# Now that you have created the `project.skore` folder (even though nothing has yet been stored), you can run the UI (in your project root i.e. where `project.skore` is) from your shell: # ```python3 # $ python -m skore launch project.skore # ``` # -# >*Note*: If you already had some data in your `project.skore` directory from a previous run -- you can check for that in your shell by using: +# >*Note*: If you already had a `project.skore` directory from a previous run -- you can check for that in your shell by using: # >```python3 # >$ ls # >``` -# >and if you no longer need its objects, we recommend deleting this folder by running `rm` in your shell: +# >and if you no longer need it, we recommend deleting this folder by running `rm` in your shell: # >```python3 # >$ rm -r project.skore # >``` # >This deletion needs to be done before the cells above: before initializing the store and before launching the UI! # %% [markdown] -# Now that the project file exists, we can load it in our script so that we can read from and write to it: +# Now that the project file exists, we can load it in our notebook so that we can read from and write to it: # %% project = load("project.skore") @@ -213,9 +213,11 @@ def my_func(x): # %% [markdown] # ## Data visualization +# +# Note that, in the dashboard, the interactivity of plots is supported, for example for `altair` and `plotly`. # %% [markdown] -# Matplotlib Figures: +# Matplotlib figures: # %% x = np.linspace(0, 2, 100) @@ -233,7 +235,7 @@ def my_func(x): project.put("my_figure", fig) # %% [markdown] -# Altair Charts: +# Altair charts: # %% num_points = 100 @@ -241,15 +243,24 @@ def my_func(x): {"x": np.random.randn(num_points), "y": np.random.randn(num_points)} ) -my_chart = ( +my_altair_chart = ( alt.Chart(df_plot) .mark_circle() .encode(x="x", y="y", tooltip=["x", "y"]) .interactive() .properties(title="My title") ) +my_altair_chart.show() -project.put("my_chart", my_chart) +project.put("my_altair_chart", my_altair_chart) + +# %% [markdown] +# Plotly figures: + +# %% +my_plotly_fig = px.bar(x=["a", "b", "c"], y=[1, 3, 2]) +my_plotly_fig.show() +project.put("my_plotly_fig", my_plotly_fig) # %% [markdown] # PIL images: @@ -302,61 +313,38 @@ def my_func(x): # The following is just some `skore` strings that we generate in order to provide more context on the obtained report. # %% -project.put_item( +project.put( "my_comment_1", - MediaItem.factory( - "

Welcome to skore!

Given to you by :probabl., skore is a powerful tool that allows data scientists to create tracking and clear reports from their Python code, typically a notebook. This HTML document is actually a skore report generated using the `basic_usage.ipynb` notebook that has been exported (into HTML)!

", - media_type="text/html", - ), + "

Welcome to skore!

skore allows data scientists to create tracking and reports from their Python code. This HTML document is actually a skore report generated using the basic_usage.ipynb notebook and that has been exported (into HTML)!

", ) # %% -project.put_item( +project.put( "my_comment_2", - MediaItem.factory("

Integers

", media_type="text/html"), + "

Integers

", ) # %% -project.put_item( - "my_comment_3", MediaItem.factory("

Strings

", media_type="text/html") +project.put( + "my_comment_3", "

Strings

" ) # %% -project.put_item( +project.put( "my_comment_4", - MediaItem.factory("

Many kinds of data

", media_type="text/html"), + "

Many kinds of data

", ) # %% -project.put_item( +project.put( "my_comment_5", - MediaItem.factory("

Altair plots

", media_type="text/html"), + "

Plots

", ) # %% -project.put_item( +project.put( "my_comment_6", - MediaItem.factory( - "

Scikit-learn models and pipelines

", media_type="text/html" - ), -) - -# %% -project.put_item( - "my_comment_7", - MediaItem.factory( - "

Manipulating the skore report

", media_type="text/html" - ), -) - -# %% -project.put_item( - "my_comment_8", - MediaItem.factory( - "

Once you have created cells in your Skore report, you can place them where you want: move them up or down, delete them, for example put one to the left of a graph to comment on it.

", - media_type="text/html", - ), + "

Scikit-learn models and pipelines

" ) # %% -project.put("my_chart_2", my_chart)