sierra-research 1.3.11__py3-none-any.whl → 1.5.0__py3-none-any.whl

sierra/core/graphs/heatmap.py

@@ -2,6 +2,9 @@
 #
 #  SPDX-License-Identifier: MIT
 #
+"""
+Heatmap graph generation classes for stage{4,5}.
+"""
 
 # Core packages
 import textwrap
@@ -12,149 +15,175 @@ import pathlib
 # 3rd party packages
 import numpy as np
 import matplotlib.pyplot as plt
-import mpl_toolkits.axes_grid1
-import pandas as pd
+import holoviews as hv
+import bokeh
 
 # Project packages
 from sierra.core import utils, config, storage, types
+from . import pathset as _pathset
+
+_logger = logging.getLogger(__name__)
+
+
+def _ofile_ext(backend: str) -> tp.Optional[str]:
+    if backend == "matplotlib":
+        return config.kStaticImageType
+    elif backend == "bokeh":
+        return config.kInteractiveImageType
+
+    return None
+
+
+def generate(
+    pathset: _pathset.PathSet,
+    input_stem: str,
+    output_stem: str,
+    medium: str,
+    title: str,
+    backend: str,
+    colnames: tp.Tuple[str, str, str] = ("x", "y", "z"),
+    xlabel: tp.Optional[str] = "",
+    ylabel: tp.Optional[str] = "",
+    zlabel: tp.Optional[str] = "",
+    large_text: bool = False,
+    xticklabels: tp.Optional[tp.List[str]] = None,
+    yticklabels: tp.Optional[tp.List[str]] = None,
+    transpose: bool = False,
+    ext=config.kStats["mean"].exts["mean"],
+) -> bool:
+    """
+    Generate a X vs. Y vs. Z heatmap plot of a ``.mean`` file.
 
+    If the necessary ``.mean`` file does not exist, the graph is not generated.
+    Dataframe must be constructed with {x,y,z} columns; e.g.::
 
-class Heatmap:
-    """
-    Generates a X vs. Y vs. Z heatmap plot of a ``.mean`` file.
+       x,y,z
+       0,0,4
+       0,1,5
+       0,2,6
+       0,3,4
+       1,0,4
+       0,1,4
+       ...
 
-    If the necessary .mean file does not exist, the graph is not generated.
+    The ``x``, ``y`` columns are the indices, and the ``z`` column is the value
+    in that cell. The names of these columns are configurable.
 
     """
-    @staticmethod
-    def set_graph_size(df: pd.DataFrame, fig) -> None:
-        """
-        Set graph X,Y size based on dataframe dimensions.
-        """
-        if len(df.index) > len(df.columns):
-            xsize = config.kGraphBaseSize
-            ysize = xsize * float(len(df.index)) / float(len(df.columns))
-        else:
-            ysize = config.kGraphBaseSize
-            xsize = ysize * float(len(df.columns)) / float(len(df.index))
-
-        fig.set_size_inches(xsize, ysize)
-
-    def __init__(self,
-                 input_fpath: pathlib.Path,
-                 output_fpath: pathlib.Path,
-                 title: str,
-                 xlabel: str,
-                 ylabel: str,
-                 zlabel: tp.Optional[str] = None,
-                 large_text: bool = False,
-                 xtick_labels: tp.Optional[tp.List[str]] = None,
-                 ytick_labels: tp.Optional[tp.List[str]] = None,
-                 transpose: bool = False,
-                 interpolation: tp.Optional[str] = None) -> None:
-        # Required arguments
-        self.input_fpath = input_fpath
-        self.output_fpath = output_fpath
-        self.title = '\n'.join(textwrap.wrap(title, 40))
-        self.xlabel = xlabel if transpose else ylabel
-        self.ylabel = ylabel if transpose else xlabel
-
-        # Optional arguments
-        if large_text:
-            self.text_size = config.kGraphTextSizeLarge
-        else:
-            self.text_size = config.kGraphTextSizeSmall
-
-        self.transpose = transpose
-        self.zlabel = zlabel
-
-        if interpolation:
-            self.interpolation = interpolation
-        else:
-            self.interpolation = 'nearest'
-
-        if self.transpose:
-            self.xtick_labels = xtick_labels
-            self.ytick_labels = ytick_labels
-        else:
-            self.xtick_labels = ytick_labels
-            self.ytick_labels = xtick_labels
-
-        self.logger = logging.getLogger(__name__)
-
-    def generate(self) -> None:
-        if not utils.path_exists(self.input_fpath):
-            self.logger.debug(
-                "Not generating heatmap: %s does not exist", self.input_fpath)
-            return
-
-        # Read .csv and create raw heatmap pfrom default configuration
-        data_df = storage.DataFrameReader('storage.csv')(self.input_fpath)
-        self._plot_df(data_df, self.output_fpath)
-
-    def _plot_df(self, df: pd.DataFrame, opath: pathlib.Path) -> None:
-        """
-        Given a dataframe read from a file, plot it as a heatmap.
-        """
-        fig, ax = plt.subplots(figsize=(config.kGraphBaseSize,
-                                        config.kGraphBaseSize))
-
-        # Transpose if requested
-        if self.transpose:
-            df = df.transpose()
-
-        # Plot heatmap
-        plt.imshow(df, interpolation=self.interpolation, aspect='auto')
-
-        # Add labels
-        plt.xlabel(self.xlabel, fontsize=self.text_size['xyz_label'])
-        plt.ylabel(self.ylabel, fontsize=self.text_size['xyz_label'])
-
-        # Add X,Y ticks
-        self._plot_ticks(ax)
-
-        # Add graph title
-        plt.title(self.title, fontsize=self.text_size['title'])
-
-        # Add colorbar
-        self._plot_colorbar(ax)
-
-        # Output figure
-        self.set_graph_size(df, fig)
-        fig = ax.get_figure()
-
-        fig.savefig(opath, bbox_inches='tight', dpi=config.kGraphDPI)
-        # Prevent memory accumulation (fig.clf() does not close everything)
-        plt.close(fig)
-
-    def _plot_colorbar(self, ax) -> None:
-        """
-        Put the Z-axis colorbar on the plot.
-        """
-        divider = mpl_toolkits.axes_grid1.make_axes_locatable(ax)
-        cax = divider.append_axes('right', size='5%', pad=0.05)
-        bar = plt.colorbar(cax=cax)
-
-        if self.zlabel is not None:
-            bar.ax.set_ylabel(self.zlabel)
-
-    def _plot_ticks(self, ax) -> None:
-        """
-        Plot X,Y ticks and their corresponding labels.
-        """
-        ax.tick_params(labelsize=self.text_size['tick_label'])
-
-        if self.xtick_labels is not None:
-            ax.set_xticks(np.arange(len(self.xtick_labels)))
-            ax.set_xticklabels(self.xtick_labels, rotation='vertical')
-
-        if self.ytick_labels is not None:
-            ax.set_yticks(np.arange(len(self.ytick_labels)))
-            ax.set_yticklabels(self.ytick_labels)
-
-
-class DualHeatmap:
-    """Generates a side-by-side plot of two heataps from two CSV files.
+    hv.extension(backend)
+
+    input_fpath = pathset.input_root / (input_stem + ext)
+    output_fpath = pathset.output_root / "HM-{0}.{1}".format(
+        output_stem, _ofile_ext(backend)
+    )
+    if not utils.path_exists(input_fpath):
+        _logger.debug(
+            "Not generating <batchroot>/%s: <batchroot>/%s does not exist",
+            output_fpath.relative_to(pathset.batchroot.resolve()),
+            input_fpath.relative_to(pathset.batchroot.resolve()),
+        )
+        return False
+
+    title = "\n".join(textwrap.wrap(title, 40))
+
+    if large_text:
+        text_size = config.kGraphs["text_size_large"]
+    else:
+        text_size = config.kGraphs["text_size_small"]
+
+    # Read .csv and create raw heatmap from default configuration
+    df = storage.df_read(input_fpath, medium)
+    dataset = hv.Dataset(df, kdims=[colnames[0], colnames[1]], vdims=colnames[2])
+
+    # Transpose if requested
+    if transpose:
+        dataset.data = dataset.data.transpose()
+
+    # Plot heatmap, without showing the Z-value in each cell, which generally
+    # obscures things more than it helps. Plus, statistical significance isn't
+    # observable from a heatmap, so numerical values are kind of moot.
+    if backend == "matplotlib":
+        plot = hv.HeatMap(
+            dataset, kdims=[colnames[0], colnames[1]], vdims=[colnames[2]]
+        ).opts(show_values=False)
+    elif backend == "bokeh":
+        plot = hv.HeatMap(
+            dataset, kdims=[colnames[0], colnames[1]], vdims=[colnames[2]]
+        )
+
+    xticks = dataset.data[colnames[0]]
+    yticks = dataset.data[colnames[1]]
+
+    # Add X,Y ticks
+    if xticklabels:
+        plot.opts(xformatter=lambda x: xticklabels[xticks.index(x)])
+    if yticklabels:
+        plot.opts(yformatter=lambda y: yticklabels[yticks.index(y)])
+
+    # Add labels
+    plot.opts(xlabel=xlabel)
+    plot.opts(ylabel=ylabel)
+
+    # Set fontsizes
+    plot.opts(
+        fontsize={
+            "title": text_size["title"],
+            "labels": text_size["xyz_label"],
+            "ticks": text_size["tick_label"],
+        }
+    )
+
+    # Add title
+    plot.opts(title=title)
+
+    if backend == "matplotlib":
+        # Add colorbar.
+        # 2025-07-08 [JRH]: backend_opts is a mpl-specific Workaround; doing
+        # colorbar_opts={"label": ...} doesn't work for unknown reasons.
+        plot.opts(colorbar=True, backend_opts={"colorbar.label": zlabel})
+
+    _save(plot, output_fpath, backend)
+
+    _logger.debug(
+        "Graph written to <batchroot>/%s",
+        output_fpath.relative_to(pathset.batchroot),
+    )
+    return True
+
+
+def _save(plot: hv.Overlay, output_fpath: pathlib.Path, backend: str) -> None:
+    if backend == "matplotlib":
+        hv.save(
+            plot.opts(fig_inches=config.kGraphs["base_size"]),
+            output_fpath,
+            fig=config.kStaticImageType,
+            dpi=config.kGraphs["dpi"],
+        )
+        plt.close("all")
+
+    elif backend == "bokeh":
+        fig = hv.render(plot)
+        fig.width = int(config.kGraphs["dpi"] * config.kGraphs["base_size"])
+        fig.height = int(config.kGraphs["dpi"] * config.kGraphs["base_size"])
+        html = bokeh.embed.file_html(fig, resources=bokeh.resources.INLINE)
+        with open(output_fpath, "w") as f:
+            f.write(html)
+
+
+def generate2(
+    pathset: _pathset.PathSet,
+    ipaths: types.PathList,
+    output_stem: pathlib.Path,
+    medium: str,
+    title: str,
+    xlabel: tp.Optional[str] = None,
+    ylabel: tp.Optional[str] = None,
+    zlabel: tp.Optional[str] = None,
+    large_text: bool = False,
+    xticklabels: tp.Optional[tp.List[str]] = None,
+    yticklabels: tp.Optional[tp.List[str]] = None,
+) -> bool:
+    """Generate a side-by-side plot of two heataps from two CSV files.
 
     ``.mean`` files must be named as ``<input_stem_fpath>_X.mean``, where `X` is
     non-negative integer. Input ``.mean`` files must be 2D grids of the same
@@ -165,192 +194,84 @@ class DualHeatmap:
     If there are not exactly two file paths passed, the graph is not generated.
 
     """
-    kCardinality = 2
-
-    def __init__(self,
-                 ipaths: types.PathList,
-                 output_fpath: pathlib.Path,
-                 title: str,
-                 xlabel: tp.Optional[str] = None,
-                 ylabel: tp.Optional[str] = None,
-                 zlabel: tp.Optional[str] = None,
-                 large_text: bool = False,
-                 xtick_labels: tp.Optional[tp.List[str]] = None,
-                 ytick_labels: tp.Optional[tp.List[str]] = None,
-                 legend: tp.Optional[tp.List[str]] = None) -> None:
-        self.ipaths = ipaths
-        self.output_fpath = output_fpath
-        self.title = title
-
-        self.legend = legend
-        self.xlabel = xlabel
-        self.ylabel = ylabel
-        self.zlabel = zlabel
-
-        self.xtick_labels = xtick_labels
-        self.ytick_labels = ytick_labels
-
-        # Optional arguments
-        if large_text:
-            self.text_size = config.kGraphTextSizeLarge
-        else:
-            self.text_size = config.kGraphTextSizeSmall
-
-        self.logger = logging.getLogger(__name__)
-
-    def generate(self) -> None:
-        reader = storage.DataFrameReader('storage.csv')
-        dfs = [reader(f) for f in self.ipaths]
-
-        if not dfs or len(dfs) != DualHeatmap.kCardinality:
-            self.logger.debug(("Not generating dual heatmap: wrong # files "
-                               "(must be %s"),
-                              DualHeatmap.kCardinality)
-            return
-
-        # Scaffold graph. We can use either dataframe for setting the graph
-        # size; we assume they have the same dimensions.
-        #
-        fig, axes = plt.subplots(nrows=1, ncols=2)
-        Heatmap.set_graph_size(dfs[0], fig)
-
-        y = np.arange(len(dfs[0].columns))
-        x = dfs[0].index
-        ax1, ax2 = axes
-
-        # Find min, max so the shared colorbar makes sense
-        minval = min(dfs[0].min().min(), dfs[1].min().min())
-        maxval = max(dfs[0].max().max(), dfs[1].max().max())
-
-        # Plot heatmaps
-        im1 = ax1.matshow(dfs[0],
-                          interpolation='none',
-                          vmin=minval,
-                          vmax=maxval)
-        im2 = ax2.matshow(dfs[1],
-                          interpolation='none',
-                          vmin=minval,
-                          vmax=maxval)
-
-        # Add titles
-        fig.suptitle(self.title, fontsize=self.text_size['title'])
-        ax1.xaxis.set_ticks_position('bottom')
-        ax1.yaxis.set_ticks_position('left')
-        ax2.xaxis.set_ticks_position('bottom')
-        ax2.yaxis.set_ticks_position('left')
-
-        if self.legend is not None:
-            ax1.set_title("\n".join(textwrap.wrap(self.legend[0], 20)),
-                          size=self.text_size['legend_label'])
-            ax2.set_title("\n".join(textwrap.wrap(self.legend[1], 20)),
-                          size=self.text_size['legend_label'])
-
-        # Add colorbar.
-        #
-        # Add, then remove the colorbar for the heatmap on the left so that they
-        # both end up the same size. Not pythonic, but it works.
-        self._plot_colorbar(fig, im1, ax1, remove=True)
-        self._plot_colorbar(fig, im2, ax2, remove=False)
-
-        # Add X,Y,Z labels:
-        #
-        # - X labels are needed on both heatmaps.
-        # - Y label only needed on left heatmap.
-        self._plot_labels(ax1, xlabel=True, ylabel=True)
-        self._plot_labels(ax2, xlabel=True, ylabel=False)
-
-        # Add X,Y ticks:
-        #
-        # - X tick labels needed on both heatmaps
-        # - Y tick labels only needed on left heatmap.
-        self._plot_ticks(ax1, x, y, xlabels=True, ylabels=True)
-        self._plot_ticks(ax2, x, y, xlabels=True, ylabels=False)
-
-        # Output figures
-        fig.subplots_adjust(wspace=0.0, hspace=0.0)
-        fig.savefig(self.output_fpath, bbox_inches='tight',
-                    dpi=config.kGraphDPI)
-        # Prevent memory accumulation (fig.clf() does not close everything)
-        plt.close(fig)
-
-    def _plot_colorbar(self, fig, im, ax, remove: bool) -> None:
-        """
-        Plot the Z-axis color bar on the dual heatmap.
-        """
-        divider = mpl_toolkits.axes_grid1.make_axes_locatable(ax)
-        cax = divider.append_axes('right', size='5%', pad=0.05)
-
-        bar = fig.colorbar(im, cax=cax)
-        if remove:
-            fig.delaxes(fig.axes[2])
-
-        # p0 = axes[0].get_position().get_points().flatten()
-        # p1 = axes[1].get_position().get_points().flatten()
-        # ax_cbar = fig.add_axes([p0[0], , p1[2] - p0[0], 0.05])
-        # bar = fig.colorbar(im, cax=ax_cbar, orientation='horizontal')
-
-        if self.zlabel is not None:
-            bar.ax.set_ylabel(self.zlabel, fontsize=self.text_size['xyz_label'])
-
-    def _plot_ticks(self, ax, xvals, yvals, xlabels: bool, ylabels: bool) -> None:
-        """Plot ticks and tick labels.
-
-        If the labels are numerical and the numbers are too large, force
-        scientific notation (the ``rcParam`` way of doing this does not seem to
-        work...)
-
-        """
-        ax.tick_params(labelsize=self.text_size['tick_label'])
-
-        if xlabels:
-            ax.set_xticks(yvals)
-            ax.set_xticklabels(self.ytick_labels, rotation='vertical')
-        else:
-            ax.set_xticks([])
-            ax.set_xticklabels([])
-
-        if ylabels:
-            ax.set_yticks(xvals)
-            ax.set_yticklabels(self.xtick_labels, rotation='horizontal')
-        else:
-            ax.set_yticks([])
-            ax.set_yticklabels([])
-
-    def _plot_labels(self, ax, xlabel: bool, ylabel: bool) -> None:
-        """
-        Plot X,Y axis labels.
-        """
-        if xlabel:
-            ax.set_xlabel(self.ylabel, fontsize=self.text_size['xyz_label'])
-
-        if ylabel:
-            ax.set_ylabel(self.xlabel, fontsize=self.text_size['xyz_label'])
-
-
-class HeatmapSet():
-    """
-    Generates a :class:`Heatmap` plot for each of the specified I/O path pairs.
-    """
-
-    def __init__(self,
-                 ipaths: types.PathList,
-                 opaths: types.PathList,
-                 titles: tp.List[str],
-                 **kwargs) -> None:
-        self.ipaths = ipaths
-        self.opaths = opaths
-        self.titles = titles
-        self.kwargs = kwargs
-
-    def generate(self) -> None:
-        for ipath, opath, title in zip(self.ipaths, self.opaths, self.titles):
-            hm = Heatmap(input_fpath=ipath, output_fpath=opath,
-                         title=title, **self.kwargs)
-            hm.generate()
-
-
-__api__ = [
-    'Heatmap',
-    'DualHeatmap',
-    'HeatmapSet'
-]
+    hv.extension("matplotlib")
+
+    output_fpath = pathset.output_root / "HM-{0}.{1}".format(
+        output_stem, config.kStaticImageType
+    )
+    # Optional arguments
+    if large_text:
+        text_size = config.kGraphs["text_size_large"]
+    else:
+        text_size = config.kGraphs["text_size_small"]
+
+    dfs = [storage.df_read(f, medium) for f in ipaths]
+
+    if not dfs or len(dfs) != 2:
+        _logger.debug(
+            ("Not generating dual heatmap: wrong # files %s (must be 2)"), len(dfs)
+        )
+        return False
+
+    # Scaffold graph. We can use either dataframe for setting the graph
+    # size; we assume they have the same dimensions.
+    #
+    # fig, axes = plt.subplots(nrows=1, ncols=2)
+    # DualHeatmap.set_graph_size(dfs[0], fig)
+
+    yticks = np.arange(len(dfs[0].columns))
+    xticks = dfs[0].index
+
+    # Plot heatmaps
+    plot = hv.Image(dfs[0]) + hv.Image(dfs[1])
+
+    # Add X,Y ticks
+    if xticklabels:
+        plot.opts(xformatter=lambda x: xticklabels[xticks.index(x)])
+    if yticklabels:
+        plot.opts(yformatter=lambda y: yticklabels[yticks.index(y)])
+
+    # Add labels
+    plot.opts(xlabel=xlabel)
+    plot.opts(ylabel=ylabel)
+
+    # Set fontsizes
+    plot.opts(
+        fontsize={
+            "title": text_size["title"],
+            "labels": text_size["xyz_label"],
+            "ticks": text_size["tick_label"],
+        }
+    )
+    # Add title
+    plot.opts(title=title)
+
+    # Add colorbar.
+    plot.opts(
+        hv.opts.Layout(shared_axes=False),
+        hv.opts.Image(
+            colorbar=True,
+            colorbar_position="right",
+            backend_opts={"colorbar.label": zlabel},
+        ),
+    )
+
+    # Output figures
+    plot.opts(fig_inches=config.kGraphs["base_size"])
+
+    hv.save(
+        plot,
+        output_fpath,
+        fig=config.kStaticImageType,
+        dpi=config.kGraphs["dpi"],
+    )
+    plt.close("all")
+
+    _logger.debug(
+        "Graph written to <batchroot>/%s",
+        output_fpath.relative_to(pathset.batchroot),
+    )
+    return True
+
+
+__all__ = ["generate", "generate2"]

sierra/core/graphs/pathset.py

@@ -0,0 +1,27 @@
+#
+# Copyright 2025 John Harwell, All rights reserved.
+#
+# SPDX-License Identifier: MIT
+#
+
+# Core packages
+from dataclasses import dataclass
+import pathlib
+import typing as tp
+
+# 3rd party packages
+
+# Project packages
+
+
+@dataclass
+class PathSet:
+    """The set of paths relevant/needed when creating graphs."""
+
+    input_root: pathlib.Path
+    output_root: pathlib.Path
+    batchroot: pathlib.Path
+    model_root: tp.Optional[pathlib.Path]
+
+
+__all__ = ["PathSet"]