Feat: Add title to report (#1654)

Co-authored-by: Riccardo Cappuzzo <7548232+rcap107@users.noreply.github.com>
Co-authored-by: Riccardo Cappuzzo <riccardo.cappuzzo@gmail.com>

Author: MarieSacksick

CHANGES.rst

@@ -26,6 +26,9 @@ New features
   environments produced by a CV splitter -- similar to
   :meth:`DataOp.skb.train_test_split` but for multiple cross-validation splits.
   :pr:`1653` by :user:`Jérôme Dockès <jeromedockes>`.
+- :meth:`DataOp.skb.full_report` now accepts a new parameter, title, that is displayed
+  in the html report.
+  :pr:`1654` by :user:`Marie Sacksick <MarieSacksick>`.
 
 Changes
 -------

doc/modules/data_ops/ml_pipeline/evaluating_debugging_data_ops.rst

@@ -6,8 +6,10 @@ Evaluating and debugging the DataOps plan with :meth:`.skb.full_report() <DataOp
 
 All operations on DataOps are recorded in a computational graph, which can be
 inspected with :meth:`.skb.full_report() <DataOp.skb.full_report>`. This method
-generates a html report that shows the full plan, including all nodes,
-their names, descriptions, and the transformations applied to the data.
+generates a html report that shows the full plan, including all nodes, their names,
+descriptions, and the transformations applied to the data. It is possible to give a
+title to the evaluation report this way:
+``my_data_op.skb.full_report(title="my title")``.
 
 An example of the report can be found
 `here <../../../_static/credit_fraud_report/index.html>`_.

skrub/_data_ops/_inspection.py

@@ -119,6 +119,7 @@ def full_report(
     open=True,
     output_dir=None,
     overwrite=False,
+    title=None,
 ):
     if clear:
         clear_results(data_op, mode)
@@ -130,6 +131,7 @@ def full_report(
             open=open,
             output_dir=output_dir,
             overwrite=overwrite,
+            title=title,
         )
     finally:
         if clear:
@@ -143,6 +145,7 @@ def _make_full_report(
     open=True,
     output_dir=None,
     overwrite=False,
+    title=None,
 ):
     _check_graphviz()
     output_dir = _get_output_dir(output_dir, overwrite)
@@ -168,7 +171,7 @@ def make_url(node):
     svg = draw_data_op_graph(data_op, url=make_url).svg.decode("utf-8")
     jinja_env = _get_jinja_env()
     index = jinja_env.get_template("index.html").render(
-        {"svg": svg, "node_status": node_status}
+        {"svg": svg, "node_status": node_status, "title": title}
     )
     index_file = output_dir / "index.html"
     index_file.write_text(index, "utf-8")

skrub/_data_ops/_skrub_namespace.py

@@ -1466,6 +1466,7 @@ def full_report(
         open=True,
         output_dir=None,
         overwrite=False,
+        title=None,
     ):
         """Generate a full report of the DataOp's evaluation.
 
@@ -1492,6 +1493,10 @@ def full_report(
             What to do if the output directory already exists. If
             ``overwrite``, replace it, otherwise raise an exception.
 
+        title: str (default=None)
+            Title to display at the top of the report. If ``None``, no title will be
+            displayed.
+
         Returns
         -------
         dict
@@ -1568,6 +1573,7 @@ def full_report(
             open=open,
             output_dir=output_dir,
             overwrite=overwrite,
+            title=title,
         )
 
     def make_learner(self, *, fitted=False, keep_subsampling=False):

skrub/_data_ops/tests/test_inspection.py

@@ -60,6 +60,17 @@ def test_full_report():
     assert "This step did not run" in (out / "node_4.html").read_text("utf-8")
 
 
+@pytest.mark.skipif(not _inspection._has_graphviz(), reason="report requires graphviz")
+def test_full_report_title():
+    # TODO we should have a private function that returns the JSON data so we
+    #      can check the content before rendering with jinja
+    # however that requires first settling on the content of the report etc.
+    data_op = skrub.var("a", 1)
+    title = "small data ops"
+    report = data_op.skb.full_report(open=False, title=title)
+    assert title in report["report_path"].read_text("utf-8")
+
+
 @pytest.mark.skipif(not _inspection._has_graphviz(), reason="report requires graphviz")
 def test_preview_subsample():
     X = datasets.fetch_employee_salaries().X

skrub/_reporting/_data/templates/data_ops/index.html

@@ -11,6 +11,9 @@
 </head>
 
 <body>
+    {% if title %}
+        <h1>{{ title }}</h1>
+    {% endif %}
     <p>
         Click on a node to display more information.
     </p>