Reporting

.github/workflows/tests.yml

@@ -12,10 +12,10 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11"]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
     steps:
       - uses: actions/checkout@v2
-      - name: Set up Python 3.9
+      - name: Set up Python
         uses: actions/setup-python@v2
         with:
           python-version: ${{ matrix.python-version }}

.gitignore

@@ -12,6 +12,7 @@ test/examples/logs/*
 curifactory.egg-info/*
 **.stats
 **/.ipynb_checkpoints/*
+**/.virtual_documents/*
 
 data/*
 dist/*

curifactory/reporting.py

@@ -250,6 +250,42 @@ def html(self) -> str:
         return f"<img src='{self.path}/{self.qualified_name}.{self.kwargs['format']}'>"
 
 
+class ImageReporter(Reportable):
+    """Adds an image to the report from a specified path.
+
+    Args:
+        image_path (str): Path to an image to copy into report folder and display on report.
+    """
+
+    def __init__(self, image_path: str, name: str = None, group: str = None):
+        self.image_path = image_path
+        self.copied = False
+        self.cache_path = None
+        super().__init__(name=name, group=group)
+
+    def render(self):
+        _, extension = os.path.splitext(self.image_path)
+
+        # we have to copy the image into cache so that if the image gets deleted
+        # (or wasn't already being properly saved uniquely within the cache),
+        # rerunning the experiment will still replicate the image into the
+        # report correctly.
+        if not self.copied:
+            self.cache_path = self.record.get_path(self.qualified_name + extension)
+            shutil.copyfile(self.image_path, self.cache_path)
+            self.copied = True
+
+        new_path = f"{self.path}/{self.qualified_name}{extension}"
+        shutil.copyfile(self.cache_path, new_path)
+
+    def html(self) -> str:
+        # NOTE: duplicated because self.path is different for html() than
+        # render()
+        _, extension = os.path.splitext(self.image_path)
+        new_path = f"{self.path}/{self.qualified_name}{extension}"
+        return f"<img src='{new_path}'>"
+
+
 class LinePlotReporter(Reportable):
     """Takes set(s) of data, creates matplotlib line plots for it, and adds to the report.
 

examples/experiments/reload-reportables.py

@@ -1,18 +1,26 @@
 """Demonstrates reportables persisting in a report even if the stage it comes from short-circuits."""
 
+import matplotlib.pyplot as plt
+
 import curifactory as cf
 from curifactory.caching import JsonCacher
-from curifactory.reporting import LinePlotReporter
+from curifactory.reporting import ImageReporter, LinePlotReporter
 
 
 @cf.stage(None, ["outputs"], [JsonCacher])
 def do_things(record):
     record.report(LinePlotReporter([3, 2, 1]))
+
+    fig, ax = plt.subplots()
+    ax.plot([3, 2, 1])
+    fig.savefig("testing.png")
+    record.report(ImageReporter("testing.png"))
+
     return {"lucky_number": 13}
 
 
 def get_params():
-    return [cf.ExperimentArgs(name="test")]
+    return [cf.ExperimentParameters(name="test")]
 
 
 def run(argsets, manager):

test/examples/experiments/image_reporter.py

@@ -0,0 +1,25 @@
+import matplotlib.pyplot as plt
+
+import curifactory as cf
+from curifactory.caching import JsonCacher
+from curifactory.reporting import ImageReporter
+
+
+@cf.stage(None, ["outputs"], [JsonCacher])
+def save_manual_image(record):
+    fig, ax = plt.subplots()
+    ax.plot([3, 2, 1])
+    fig.savefig("testing.png")
+    record.report(ImageReporter("testing.png"))
+
+    return {"thing": 13}
+
+
+def get_params():
+    return [cf.ExperimentParameters(name="test")]
+
+
+def run(argsets, manager):
+    for argset in argsets:
+        r = cf.Record(manager, argset)
+        r = save_manual_image(r)

test/test_caching.py

@@ -1,5 +1,6 @@
 import json
 import os
+import sys
 from dataclasses import dataclass
 from test.examples.stages.cache_stages import (
     filerefcacher_stage,
@@ -770,6 +771,12 @@ def save_large_df(record):
 def test_pandas_cacher_for_all_io_formats(configured_test_manager, io_format):
     """The PandasCacher should work for save and load for all IO formats."""
 
+    if io_format == "hdf5" and (sys.version_info[0] == 3 and sys.version_info[1] < 10):
+        # NOTE: pytables is incompatible with python < 3.10, but the tables/h5
+        # functionality is also optional in CF, so don't have a hard requirement
+        # on this test passing.
+        return
+
     io_format_enum = _PandasIOType[io_format]
     data = {
         "col1": ["things, with commas", "more rows", "MOAR!"],

test/test_cli.py

@@ -10,7 +10,7 @@ def test_experiments_completer():
     """The experiments autocomplete function should return the correct set of
     experiment scripts."""
     output = completer_experiments()
-    assert output == ["basic", "simple_cache", "subexp.example"]
+    assert output == ["basic", "image_reporter", "simple_cache", "subexp.example"]
 
 
 def test_params_completer():
@@ -19,6 +19,7 @@ def test_params_completer():
     output = completer_params()
     assert output == [
         "empty",
+        "image_reporter",
         "nonarrayargs",
         "params1",
         "params2",
@@ -59,5 +60,5 @@ def test_experiment_ls_output(mocker, capfd):  # noqa: F811
     out, err = capfd.readouterr()
     assert (
         out
-        == "EXPERIMENTS:\n\tbasic\n\tsimple_cache\n\tsubexp.example\n\nPARAMS:\n\tempty\n\tnonarrayargs\n\tparams1\n\tparams2\n\tsimple_cache\n\tsubparams.thing\n"
+        == "EXPERIMENTS:\n\tbasic\n\timage_reporter\n\tsimple_cache\n\tsubexp.example\n\nPARAMS:\n\tempty\n\timage_reporter\n\tnonarrayargs\n\tparams1\n\tparams2\n\tsimple_cache\n\tsubparams.thing\n"
     )

test/test_reporting.py

@@ -191,3 +191,20 @@ def test_log_copied_to_report(configured_test_manager):
     assert os.path.exists(
         f"{configured_test_manager.get_run_output_path()}/report/log.txt"
     )
+
+
+def test_image_reporter_persists_after_original_deletion(configured_test_manager):
+    """The ImageReporter should still display the image in a report for a re-run
+    experiment, even if the original image was deleted."""
+
+    run_experiment("image_reporter", ["image_reporter"], mngr=configured_test_manager)
+    assert os.path.exists(
+        f"{configured_test_manager.reports_path}/{configured_test_manager.get_reference_name()}/reportables/test_save_manual_image_0.png"
+    )
+
+    os.remove("testing.png")
+
+    run_experiment("image_reporter", ["image_reporter"], mngr=configured_test_manager)
+    assert os.path.exists(
+        f"{configured_test_manager.reports_path}/{configured_test_manager.get_reference_name()}/reportables/test_save_manual_image_0.png"
+    )