DOC - Improving getting started example (#1627)

Co-authored-by: Guillaume Lemaitre <guillaume@probabl.ai>

Author: rcap107

doc/modules/data_ops/validation/hyperparameter_tuning.rst

@@ -200,6 +200,6 @@ We can see the generated parameter grid with :func:`DataOps.skb.describe_param_g
 "- choose_from({'number': …, 'text': …}): ['number', 'text']\n"
 
 A more advanced application of this technique is used in
-:ref:`this tutorial on forecasting timeseries <https://skrub-data.org/EuroSciPy2025/content/notebooks/single_horizon_prediction.html>_`,
+`this tutorial on forecasting timeseries <https://skrub-data.org/EuroSciPy2025/content/notebooks/single_horizon_prediction.html>`_,
 along with the feature engineering required to prepare the columns, and the
 analysis of the results.

doc/modules/tablereport/exploring_dataframes_interactively.rst

@@ -45,14 +45,6 @@ be copied in a script.
 The TableReport can be used in a notebook cell, or it can be opened in a browser
 window using ``TableReport(df).open()``.
 
-It is also possible to export the |TableReport| in HTML or JSON format: see
-:ref:`user_guide_table_report_sharing` for more detail.
-
-Customizing and sharing the |TableReport|
-=========================================
-
-.. |set_config| replace:: :func:`~skrub.set_config`
-
 .. _user_guide_table_report_customize:
 
 Altering the Appearance of the |TableReport|
@@ -73,8 +65,6 @@ Parameters can be made permanent in a script by altering the configuration with
 |set_config|, or by setting the respective environment variables. Refer to
 :ref:`user_guide_configuration_parameters` for more detail.
 
-.. |TableReport| replace:: :class:`~skrub.TableReport`
-
 .. _user_guide_table_report_sharing:
 
 Exporting and Sharing the |TableReport|

examples/00_getting_started.py

@@ -2,75 +2,52 @@
 Getting Started
 ===============
 
-This guide showcases some of the features of ``skrub``, an open-source package
-that aims at bridging the gap between tabular data stored in Pandas or Polars
-dataframes, and machine-learning models.
-
-Much of ``skrub`` revolves around simplifying many of the tasks that are involved
+This guide showcases some of the features of skrub.
+Much of skrub revolves around simplifying many of the tasks that are involved
 in pre-processing raw data into a format that shallow or classic machine-learning
 models can understand, that is, numerical data.
 
-``skrub`` does this by vectorizing, assembling, and encoding tabular data through
-a number of features that we present in this example and the following.
+Skrub achieves this by vectorizing, assembling, and encoding tabular data through
+the features we present in this example and the following ones.
+
+.. |TableReport| replace:: :class:`~skrub.TableReport`
+.. |Cleaner| replace:: :class:`~skrub.Cleaner`
+.. |set_config| replace:: :func:`~skrub.set_config`
+.. |tabular_pipeline| replace:: :func:`~skrub.tabular_pipeline`
+.. |TableVectorizer| replace:: :class:`~skrub.TableVectorizer`
+.. |Joiner| replace:: :class:`~skrub.Joiner`
+.. |SquashingScaler| replace:: :class:`~skrub.SquashingScaler`
+.. |DatetimeEncoder| replace:: :class:`~skrub.DatetimeEncoder`
+.. |ApplyToCols| replace:: :class:`~skrub.ApplyToCols`
+.. |StringEncoder| replace:: :class:`~skrub.StringEncoder`
+.. |TextEncoder| replace:: :class:`~skrub.TextEncoder`
 """
 
-# %%
-# Downloading example datasets
-# ----------------------------
-#
-# The :obj:`~skrub.datasets` module allows us to download tabular datasets and
-# demonstrate ``skrub``'s features.
-#
-# .. note::
-#
-#    You can control the directory where the datasets are stored by:
-#
-#    - setting in your environment the ``SKRUB_DATA_DIRECTORY`` variable to an
-#      absolute directory path,
-#    - using the parameter ``data_directory`` in fetch functions, which takes
-#      precedence over the envar.
-#
-#    By default, the datasets are stored in a folder named "skrub_data" in the
-#    user home folder.
-
 
 # %%
+# Preliminary exploration with the |TableReport|
+# ----------------------------------------------
 from skrub.datasets import fetch_employee_salaries
 
 dataset = fetch_employee_salaries()
 employees_df, salaries = dataset.X, dataset.y
 
 # %%
-# Explore all the available datasets in :ref:`datasets_ref`.
+# Typically, the first step with new data is exploration and parsing.
+# To quickly get an overview of a dataframe's contents, use the |TableReport|.
 
 # %%
-# Preliminary exploration and parsing of data
-# -------------------------------------------------
-# Typically, the first operations that are done on new data involve data exploration
-# and parsing.
-# To quickly get an overview of a dataframe's contents, use the
-# :class:`~skrub.TableReport`.
-# Here, we also use the :class:`~skrub.Cleaner`, a transformer that cleans the
-# dataframe by parsing nulls and dates, and by dropping "uninformative" columns
-# (e.g., that contain too many nulls, or that are constant).
-#
-
-# %%
-from skrub import Cleaner, TableReport
+from skrub import TableReport
 
 TableReport(employees_df)
 
 # %%
-# From the Report above, we can see that there are datetime columns, so we use the
-# :class:`~skrub.Cleaner` to parse them.
-
-employees_df = Cleaner().fit_transform(employees_df)
-TableReport(employees_df)
-
-# %%
-#
 # You can use the interactive display above to explore the dataset visually.
 #
+# It is also possible to tell skrub to replace the default pandas and polars
+# displays with |TableReport| by modifying the global config with
+# |set_config|.
+#
 # .. note::
 #
 #    You can see a few more `example reports`_ online. We also
@@ -80,31 +57,36 @@
 #
 #    .. _example reports: https://skrub-data.org/skrub-reports/examples/
 #    .. _demo: https://skrub-data.org/skrub-reports/
+#
+# From the report above, we see that there are columns with date and time stored
+# as `object` dtype (cf. "Stats" tab of the report).
+# Datatypes not being parsed correctly is a scenario that occurs commonly after
+# reading a table. We can use the |Cleaner| to address this.
+# In the next section, we show that this transformer does additional cleaning.
 
 # %%
-# It is also possible to tell ``skrub`` to replace the default pandas & polars
-# displays with ``TableReport`` by modifying the global config with
-# :func:`~skrub.set_config`.
-
-from skrub import set_config
+# Sanitizing data with the |Cleaner|
+# ----------------------------------
+# Here, we use the |Cleaner|, a transformer that sanitizing the
+# dataframe by parsing nulls and dates, and by dropping "uninformative" columns
+# (e.g., columns with too many nulls or that are constant).
+#
 
-set_config(use_table_report=True)
+from skrub import Cleaner
 
-employees_df
+employees_df = Cleaner().fit_transform(employees_df)
+TableReport(employees_df)
 
 # %%
-# This setting can easily be reverted:
-
-set_config(use_table_report=False)
-
-employees_df
+# We can see from the "Stats" tab that now the column `date_first_hired` has been
+# parsed correctly as a Datetime.
 
 # %%
 # Easily building a strong baseline for tabular machine learning
 # --------------------------------------------------------------
 #
-# The goal of ``skrub`` is to ease tabular data preparation for machine learning.
-# The :func:`~skrub.tabular_pipeline` function provides an easy way to build a simple
+# The goal of skrub is to ease tabular data preparation for machine learning.
+# The |tabular_pipeline| function provides an easy way to build a simple
 # but reliable machine learning model that works well on most tabular data.
 
 
@@ -114,87 +96,41 @@
 from skrub import tabular_pipeline
 
 model = tabular_pipeline("regressor")
+model
+# %%
 results = cross_validate(model, employees_df, salaries)
 results["test_score"]
 
 # %%
 # To handle rich tabular data and feed it to a machine learning model, the
-# pipeline returned by :func:`~skrub.tabular_pipeline` preprocesses and encodes
-# strings, categories and dates using the :class:`~skrub.TableVectorizer`.
+# pipeline returned by |tabular_pipeline| preprocesses and encodes
+# strings, categories and dates using the |TableVectorizer|.
 # See its documentation or :ref:`sphx_glr_auto_examples_01_encodings.py` for
 # more details. An overview of the chosen defaults is available in
 # :ref:`user_guide_tabular_pipeline`.
 
 
-# %%
-# Assembling data
-# ---------------
-#
-# ``skrub`` allows imperfect assembly of data, such as joining dataframes
-# on columns that contain typos. ``skrub``'s joiners have ``fit`` and
-# ``transform`` methods, storing information about the data across calls.
-#
-# The :class:`~skrub.Joiner` allows fuzzy-joining multiple tables, each row of
-# a main table will be augmented with values from the best match in the auxiliary table.
-# You can control how distant fuzzy-matches are allowed to be with the
-# ``max_dist`` parameter.
-
-# %%
-# In the following, we add information about countries to a table containing
-# airports and the cities they are in:
-
-# %%
-import pandas as pd
-
-from skrub import Joiner
-
-airports = pd.DataFrame(
-    {
-        "airport_id": [1, 2],
-        "airport_name": ["Charles de Gaulle", "Aeroporto Leonardo da Vinci"],
-        "city": ["Paris", "Roma"],
-    }
-)
-# Notice the "Rome" instead of "Roma"
-capitals = pd.DataFrame(
-    {"capital": ["Berlin", "Paris", "Rome"], "country": ["Germany", "France", "Italy"]}
-)
-joiner = Joiner(
-    capitals,
-    main_key="city",
-    aux_key="capital",
-    max_dist=0.8,
-    add_match_info=False,
-)
-joiner.fit_transform(airports)
-
-# %%
-# Information about countries have been added, even if the rows aren't exactly matching.
-#
-# ``skrub`` allows to aggregate multiple tables according to various strategies: you
-# can see other ways to join multiple tables in :ref:`userguide_joining_tables`.
-
 # %%
 # Encoding any data as numerical features
 # ---------------------------------------
 #
-# Tabular data can contain a variety of datatypes, ranging from numerical, to
-# datetimes, to categories, strings, and text. Encoding features in a meaningful
-# way requires a lot of effort and is a major part of the feature engineering
-# process that is required to properly train machine learning models.
+# Tabular data can contain a variety of datatypes, from numerical to
+# datetimes, categories, strings, and text. Encoding features in a meaningful
+# way requires significant effort and is a major part of the feature engineering
+# process required to properly train machine learning models.
 #
-# ``skrub`` helps with this by providing various transformers that automatically
+# Skrub helps with this by providing various transformers that automatically
 # encode different datatypes into ``float32`` features.
 #
-# For **numerical features**, the :class:`~skrub.SquashingScaler` applies a robust
+# For **numerical features**, the |SquashingScaler| applies a robust
 # scaling technique that is less sensitive to outliers. Check the
-# :ref:`relative example <sphx_glr_auto_examples_11_squashing_scaler.py>`
+# :ref:`relative example <sphx_glr_auto_examples_10_squashing_scaler.py>`
 # for more information on the feature.
 #
-# For **datetime columns**, ``skrub`` provides the :class:`~skrub.DatetimeEncoder`
+# For **datetime columns**, skrub provides the |DatetimeEncoder|
 # which can extract useful features such as year, month, day, as well as additional
 # features such as weekday or day of year. Periodic encoding with trigonometric
-# or spline features is also available. Refer to the :class:`~skrub.DatetimeEncoder`
+# or spline features is also available. Refer to the |DatetimeEncoder|
 # documentation for more detail.
 #
 
@@ -211,10 +147,10 @@
 data = Cleaner().fit_transform(data)
 TableReport(data)
 # %%
-# ``skrub`` transformers are applied column-by-column, but it is possible to use
-# the :class:`~skrub.ApplyToCols` meta-transformer to apply a transformer to
+# Skrub transformers are applied column-by-column, but it's possible to use
+# the |ApplyToCols| meta-transformer to apply a transformer to
 # multiple columns at once. Complex column selection is possible using
-# :ref:`skrub's column selectors <userguide_selectors>`.
+# :ref:`skrub's column selectors <user_guide_selectors>`.
 
 from skrub import ApplyToCols, DatetimeEncoder
 
@@ -224,10 +160,10 @@
 
 # %%
 # Finally, when a column contains **categorical or string data**, it can be
-# encoded using various encoders provided by ``skrub``. The default encoder is
-# the :class:`~skrub.StringEncoder`, which encodes categories using
+# encoded using various encoders provided by skrub. The default encoder is
+# the |StringEncoder|, which encodes categories using
 # `Latent Semantic Analysis (LSA) <https://scikit-learn.org/stable/modules/decomposition.html#about-truncated-svd-and-latent-semantic-analysis-(lsa)>`_.
-# It is a simple and efficient way to encode categories, and works well in
+# It is a simple and efficient way to encode categories and works well in
 # practice.
 
 data = pd.DataFrame(
@@ -243,22 +179,40 @@
 
 # %%
 # If your data includes a lot of text, you may want to use the
-# :class:`~skrub.TextEncoder`,
+# |TextEncoder|,
 # which uses pre-trained language models retrieved from the HuggingFace hub to
 # create meaningful text embeddings.
-# See :ref:`userguide_encoders` for more details on all the categorical encoders
-# provided by ``skrub``, and :ref:`sphx_glr_auto_examples_01_encodings.py` for a
+# See :ref:`user_guide_encoders_index` for more details on all the categorical encoders
+# provided by skrub, and :ref:`sphx_glr_auto_examples_01_encodings.py` for a
 # comparison between the different methods.
+#
+
+# %%
+# Assembling data
+# ---------------
+#
+# Skrub allows imperfect assembly of data, such as joining dataframes
+# on columns that contain typos. Skrub's joiners have ``fit`` and
+# ``transform`` methods, storing information about the data across calls.
+#
+# The |Joiner| allows fuzzy-joining multiple tables, where each row of
+# a main table will be augmented with values from the best match in the auxiliary table.
+# You can control how distant fuzzy-matches are allowed to be with the
+# ``max_dist`` parameter.
+#
+# Skrub also allows you to aggregate multiple tables according to various strategies.
+# You can see other ways to join multiple tables in
+# :ref:`user_guide_joining_dataframes`.
 
 # %%
 # Advanced use cases
 # ----------------------
 # If your use case involves more complex data preparation, hyperparameter tuning,
 # or model selection, if you want to build a multi-table pipeline that requires
-# assembling and preparing multiple tables, or if you want to make sure that the
-# data preparation can be reproduced exactly, you can use the ``skrub`` Data Ops,
-# a powerful framework which provides tools to build complex data processing pipelines.
-# See the relative :ref:`user guide <userguide_data_ops>` and the
+# assembling and preparing multiple tables, or if you want to ensure that the
+# data preparation can be reproduced exactly, you can use the skrub Data Ops,
+# a powerful framework that provides tools to build complex data processing pipelines.
+# See the related :ref:`user guide <user_guide_data_ops_index>` and the
 # :ref:`data_ops_examples_ref`
 # examples for more details.
 
@@ -267,11 +221,11 @@
 # ----------
 #
 # We have briefly covered pipeline creation, vectorizing, assembling, and encoding
-# data. We presented the main functionalities of ``skrub``, but there is much
-# more to it!
+# data. We presented the main functionalities of skrub, but there is much
+# more to explore!
 #
 # Please refer to our :ref:`user_guide` for a more in-depth presentation of
-# ``skrub``'s concepts, or visit our
+# skrub's concepts, or visit our
 # `examples <https://skrub-data.org/stable/auto_examples>`_ for more
 # illustrations of the tools that we provide!
 #