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

sierra/plugins/prod/graphs/collate.py

@@ -0,0 +1,279 @@
+# Copyright 2018 John Harwell, All rights reserved.
+#
+#  SPDX-License-Identifier: MIT
+"""Collation functionality for stage3 outputs according to configuration."""
+
+# Core packages
+import multiprocessing as mp
+import queue
+import typing as tp
+import logging
+import pathlib
+import json
+import re
+
+# 3rd party packages
+import pandas as pd
+
+# Project packages
+from sierra.core import utils, config, types, storage, batchroot
+import sierra.core.variables.batch_criteria as bc
+from sierra.plugins.prod.graphs import targets
+from sierra.core import plugin as pm
+
+_logger = logging.getLogger(__name__)
+
+
+class GraphCollationInfo:
+    """Container for :term:`Collated Output Data` files for a particular graph.
+
+    This is one of the focal points for the magic of SIERRA: here is where time
+    series data is transformed into different dataframe formats so as to make
+    generation of different types of graphs seamless when you want to look at
+    some data *across* the batch.  The for dataframes by graph type is as
+    follows:
+
+        - :func:`~sierra.core.graphs.stacked_line` : Columns are the raw time
+          series data.  Column names are the names of the experiments.
+
+        - :func:`~sierra.core.graphs.summary_line`: Columns are a single time
+          slice of time series data.  Column names are the names of the
+          experiments.  Indexed by (exp name, summary column).
+
+        - :func:`~sierra.core.graphs.heatmap`: X,Y columns are the indices in
+          the multidimensional array defining the experiment space, parsed out
+          from the exp dirnames for the batch.  Z values are a single time slice
+          of time series data for the specified column in each experiment in the
+          batch.
+    """
+
+    def __init__(
+        self, df_ext: str, exp_names: tp.List[str], graph_type: str, summary_col: str
+    ) -> None:
+        self.df_ext = df_ext
+
+        if graph_type == "summary_line":
+            self.df = pd.DataFrame(index=exp_names, columns=[summary_col])
+            self.df.index.name = "Experiment ID"
+        elif graph_type == "stacked_line":
+            self.df = pd.DataFrame(columns=exp_names)
+        elif graph_type == "heatmap":
+            self.df = pd.DataFrame(columns=["x", "y", "z"])
+
+        self.graph_type = graph_type
+        self.summary_col = summary_col
+        self.all_srcs_exist = True
+        self.some_srcs_exist = False
+
+
+class GraphCollator:
+    """For a single graph gather needed data from experiments in a batch.
+
+    Results are put into a single :term:`Collated Output Data` file.
+    """
+
+    def __init__(
+        self,
+        main_config: types.YAMLDict,
+        cmdopts: types.Cmdopts,
+        pathset: batchroot.PathSet,
+    ) -> None:
+        self.main_config = main_config
+        self.cmdopts = cmdopts
+        self.pathset = pathset
+        self.logger = logging.getLogger(__name__)
+
+    def __call__(self, criteria, target: types.YAMLDict) -> None:
+        self.logger.info(
+            "Files from univariate experiment in <batch_root>/%s for graph '%s'",
+            self.pathset.output_root.relative_to(self.pathset.root),
+            target["src_stem"],
+        )
+        self.logger.trace(json.dumps(target, indent=4))  # type: ignore
+
+        exp_dirs = utils.exp_range_calc(
+            self.cmdopts["exp_range"],
+            self.pathset.output_root,
+            criteria.gen_exp_names(),
+        )
+
+        # Always do the mean, even if stats are disabled
+        stat_config = config.kStats["mean"].exts
+
+        if self.cmdopts["dist_stats"] in ["conf95", "all"]:
+            stat_config.update(config.kStats["conf95"].exts)
+
+        if self.cmdopts["dist_stats"] in ["bw", "all"]:
+            stat_config.update(config.kStats["bw"].exts)
+
+        stats = [
+            GraphCollationInfo(
+                df_ext=suffix,
+                exp_names=[e.name for e in exp_dirs],
+                summary_col="{0}+{1}".format(
+                    self.cmdopts["controller"], self.cmdopts["scenario"]
+                ),
+                graph_type=target["type"],
+            )
+            for suffix in stat_config.values()
+        ]
+
+        for diri in exp_dirs:
+            self._collate_exp(target, diri.name, stats)
+
+        for stat in stats:
+            if stat.all_srcs_exist:
+                storage.df_write(
+                    stat.df,
+                    self.pathset.stat_interexp_root
+                    / (target["dest_stem"] + stat.df_ext),
+                    "storage.csv",
+                    index=stat.graph_type == "summary_line",
+                )
+
+            elif not stat.all_srcs_exist and stat.some_srcs_exist:
+                self.logger.warning(
+                    "Not all experiments in '%s' produced '%s%s'",
+                    self.pathset.output_root,
+                    target["src_stem"],
+                    stat.df_ext,
+                )
+            else:
+                self.logger.warning(
+                    "No experiments in <batchroot>/%s produced %s%s",
+                    self.pathset.output_root.relative_to(self.pathset.root),
+                    target["src_stem"],
+                    stat.df_ext,
+                )
+
+    def _collate_exp(
+        self, target: dict, exp_dir: str, stats: tp.List[GraphCollationInfo]
+    ) -> None:
+        exp_stat_root = self.pathset.stat_root / exp_dir
+
+        for stat in stats:
+            csv_ipath = pathlib.Path(exp_stat_root, target["src_stem"] + stat.df_ext)
+            if not utils.path_exists(csv_ipath):
+                stat.all_srcs_exist = False
+                continue
+
+            stat.some_srcs_exist = True
+
+            data_df = storage.df_read(csv_ipath, "storage.csv")
+
+            # 2025-07-08 [JRH]: This is the ONE place in all the graph
+            # generation code which is a procedural switch on graph type.
+            if target["type"] == "summary_line":
+                idx = target.get("index", -1)
+                assert "col" in target, "'col' key is required"
+                assert (
+                    target["col"] in data_df.columns.values
+                ), "{0} not in columns of {1}".format(
+                    target["col"], target["src_stem"] + stat.df_ext
+                )
+                datapoint = data_df.loc[data_df.index[idx], target["col"]]
+                stat.df.loc[exp_dir, stat.summary_col] = datapoint
+            elif target["type"] == "stacked_line":
+                assert "cols" in target, "'cols' key is required"
+
+                assert (
+                    target["cols"] in data_df.columns.values
+                ), "{0} not in columns of {1}".format(
+                    target["cols"], target["src_stem"] + stat.df_ext
+                )
+                stat.df[exp_dir] = data_df[target["cols"]]
+            elif target["type"] == "heatmap":
+                idx = target.get("index", -1)
+
+                regex = r"c1-exp(\d+)\+c2-exp(\d+)"
+                res = re.match(regex, exp_dir)
+
+                assert (
+                    res and len(res.groups()) == 2
+                ), f"Unexpected directory name '{exp_dir}': does not match regex {regex}"
+
+                row = pd.DataFrame(
+                    [
+                        {
+                            # group 0 is always the whole matched string
+                            "x": int(res.group(1)),
+                            "y": int(res.group(2)),
+                            "z": data_df.loc[data_df.index[idx], target["col"]],
+                        }
+                    ]
+                )
+
+                stat.df = pd.concat([stat.df, row])
+
+
+def proc_batch_exp(
+    main_config: types.YAMLDict,
+    cmdopts: types.Cmdopts,
+    pathset: batchroot.PathSet,
+    criteria: bc.XVarBatchCriteria,
+) -> None:
+    """
+    Generate :term:`Collated Output Data` files from :term:`Batch Summary Data` files.
+
+    """
+    utils.dir_create_checked(pathset.stat_interexp_root, exist_ok=True)
+
+    q = mp.JoinableQueue()  # type: mp.JoinableQueue
+
+    loader = pm.module_load_tiered(project=cmdopts["project"], path="pipeline.yaml")
+
+    graphs_config = loader.load_config(cmdopts, config.kYAML.graphs)
+
+    if "inter-exp" not in graphs_config:
+        _logger.warning(
+            "Cannot collate data: 'inter-exp' key not found in graphs YAML config"
+        )
+        return
+
+    controller_config = loader.load_config(cmdopts, config.kYAML.controllers)
+
+    # For each category of graphs we are generating
+    for category in targets.inter_exp_calc(
+        graphs_config["inter-exp"], controller_config, cmdopts
+    ):
+        # For each graph in each category
+        for graph in category:
+            q.put(graph)
+
+    parallelism = cmdopts["processing_parallelism"]
+
+    for _ in range(0, parallelism):
+        p = mp.Process(
+            target=_thread_worker,
+            args=(q, main_config, cmdopts, pathset, criteria),
+        )
+        p.start()
+
+    q.join()
+
+
+def _thread_worker(
+    q: mp.Queue,
+    main_config: types.YAMLDict,
+    cmdopts: types.Cmdopts,
+    pathset: batchroot.PathSet,
+    criteria,
+) -> None:
+
+    collator = GraphCollator(main_config, cmdopts, pathset)
+
+    while True:
+        # Wait for 3 seconds after the queue is empty before bailing
+        try:
+            graph = q.get(True, 3)
+            collator(criteria, graph)
+            q.task_done()
+        except queue.Empty:
+            break
+
+
+__all__ = [
+    "GraphCollator",
+    "GraphCollationInfo",
+    "proc_batch_exp",
+]

sierra/plugins/prod/graphs/inter/__init__.py

@@ -0,0 +1,13 @@
+#
+# Copyright 2024 John Harwell, All rights reserved.
+#
+# SPDX-License Identifier: MIT
+#
+"""Container module for inter-experiment graph generation in stage 4."""
+
+# Core packages
+
+# 3rd party packages
+
+# Project packages
+from . import generate as generate

sierra/plugins/prod/graphs/inter/generate.py

@@ -0,0 +1,83 @@
+# Copyright 2018 John Harwell, All rights reserved.
+#
+#  SPDX-License-Identifier: MIT
+#
+
+"""
+Generate graphs across experiments in a batch.
+"""
+
+# Core packages
+import logging
+
+# 3rd party packages
+
+# Project packages
+from sierra.core import types, utils, batchroot, config
+from sierra.plugins.prod.graphs import targets
+from sierra.core import plugin as pm
+from sierra.core.variables import batch_criteria as bc
+from . import line, heatmap
+
+_logger = logging.getLogger(__name__)
+
+
+def proc_batch_exp(
+    main_config: types.YAMLDict,
+    cmdopts: types.Cmdopts,
+    pathset: batchroot.PathSet,
+    criteria: bc.XVarBatchCriteria,
+) -> None:
+    """Generate graphs from :term:`Collated Output Data` files.
+
+    Performs the following steps:
+
+        #. :func:`~sierra.plugins.prod.graphs.inter.line.generate()` to
+           generate linegraphs (univariate batch criteria only).
+
+        #. :func:`~sierra.plugins.prod.graphs.inter.heatmap.generate()`
+           to generate heatmaps (bivariate batch criteria only).
+
+    Which graphs are generated can be controlled by YAML configuration files
+    parsed in stage 4.
+
+    Arguments:
+        main_config: Parsed dictionary of main YAML configuration
+
+        cmdopts: Dictionary of parsed cmdline attributes.
+
+        targets: A list of dictionaries, where each dictionary defines an
+                 inter-experiment graph to generate.
+    """
+    utils.dir_create_checked(pathset.graph_interexp_root, exist_ok=True)
+
+    loader = pm.module_load_tiered(project=cmdopts["project"], path="pipeline.yaml")
+
+    graphs_config = loader.load_config(cmdopts, config.kYAML.graphs)
+
+    if "inter-exp" not in graphs_config:
+        _logger.warning(
+            "Cannot generate graphs: 'inter-exp' key not found in YAML config"
+        )
+        return
+
+    controller_config = loader.load_config(cmdopts, config.kYAML.controllers)
+
+    info = criteria.graph_info(cmdopts, batch_output_root=pathset.output_root)
+
+    if criteria.cardinality() == 1:
+        if not cmdopts["project_no_LN"]:
+            graph_targets = targets.inter_exp_calc(
+                graphs_config["inter-exp"], controller_config, cmdopts
+            )
+            line.generate(cmdopts, pathset, graph_targets, info)
+    else:
+        graph_targets = targets.inter_exp_calc(
+            graphs_config["inter-exp"], controller_config, cmdopts
+        )
+        heatmap.generate(cmdopts, pathset, graph_targets, info)
+
+
+__all__ = [
+    "proc_batch_exp",
+]

sierra/plugins/prod/graphs/inter/heatmap.py

@@ -0,0 +1,86 @@
+#
+# Copyright 2024 John Harwell, All rights reserved.
+#
+# SPDX-License Identifier: MIT
+#
+"""Generate heatmaps *across* multiple :term:`Experiments <Experiment>`."""
+
+# Core packages
+import typing as tp
+import logging
+
+# 3rd party packages
+import json
+import yaml
+import strictyaml
+
+# Project packages
+from sierra.core import types, batchroot, graphs
+from sierra.core.graphs import bcbridge, schema
+
+_logger = logging.getLogger(__name__)
+
+
+def generate(
+    cmdopts: types.Cmdopts,
+    pathset: batchroot.PathSet,
+    targets: tp.List[types.YAMLDict],
+    info: bcbridge.GraphInfo,
+) -> None:
+    """
+    Generate heatmaps from: term:`Processed Output Data` files.
+    """
+    large_text = cmdopts["plot_large_text"]
+
+    _logger.info(
+        "Heatmaps from <batch_root>/%s",
+        pathset.stat_interexp_root.relative_to(pathset.root),
+    )
+
+    # For each category of heatmaps we are generating
+    for category in targets:
+
+        # For each graph in each category
+        for graph in category:
+            # Only try to create heatmaps (duh)
+            if graph["type"] != "heatmap":
+                continue
+
+            _logger.trace("\n" + json.dumps(graph, indent=4))  # type: ignore
+
+            try:
+                graph = strictyaml.load(yaml.dump(graph), schema.heatmap).data
+
+            except strictyaml.YAMLError as e:
+                _logger.critical("Non-conformant heatmap YAML: %s", e)
+                raise
+
+            graph_pathset = graphs.PathSet(
+                input_root=pathset.stat_interexp_root,
+                output_root=pathset.graph_interexp_root,
+                batchroot=pathset.root,
+                model_root=None,
+            )
+            # 2025-06-05 [JRH]: We always write stage {3,4} output data files as
+            # .csv because that is currently SIERRA's 'native' format; this may
+            # change in the future.
+            graphs.heatmap(
+                pathset=graph_pathset,
+                input_stem=graph["dest_stem"],
+                output_stem=graph["dest_stem"],
+                medium="storage.csv",
+                title=graph.get("title", None),
+                xlabel=graph.get("xlabel", ""),
+                ylabel=graph.get("ylabel", ""),
+                zlabel=graph.get("zlabel", ""),
+                backend=graph.get("backend", cmdopts["graphs_backend"]),
+                colnames=(
+                    graph.get("x", "x"),
+                    graph.get("y", "y"),
+                    graph.get("z", "z"),
+                ),
+                large_text=large_text,
+            )
+
+
+__all__ = ["generate"]

sierra/plugins/prod/graphs/inter/line.py

@@ -0,0 +1,134 @@
+#
+# Copyright 2024 John Harwell, All rights reserved.
+#
+# SPDX-License Identifier: MIT
+#
+"""Inter-experiment linegraph generation in stage 4."""
+
+# Core packages
+import typing as tp
+import logging
+
+# 3rd party packages
+import json
+import yaml
+import strictyaml
+
+# Project packages
+from sierra.core import types, batchroot, graphs
+from sierra.core.graphs import bcbridge, schema
+
+_logger = logging.getLogger(__name__)
+
+
+def generate(
+    cmdopts: types.Cmdopts,
+    pathset: batchroot.PathSet,
+    targets: tp.List[types.YAMLDict],
+    info: bcbridge.GraphInfo,
+) -> None:
+    """Generate linegraphs from :term:`Collated Output Data` files.
+
+    The graphs generated by this module respect the ``--exp-range`` cmdline
+    option.
+    """
+
+    _logger.info(
+        "Linegraphs from <batchroot>/%s",
+        pathset.stat_interexp_root.relative_to(pathset.root),
+    )
+
+    # For each category of linegraphs we are generating
+    for category in targets:
+
+        # For each graph in each category
+        for graph in category:
+            if graph["type"] not in ["summary_line", "stacked_line"]:
+                continue
+
+            _logger.trace("\n" + json.dumps(graph, indent=4))  # type: ignore
+
+            if graph["type"] == "summary_line":
+                try:
+                    graph = strictyaml.load(yaml.dump(graph), schema.summary_line).data
+                except strictyaml.YAMLError as e:
+                    _logger.critical("Non-conformant summary_line YAML: %s", e)
+                    raise
+                _gen_summary_linegraph(graph, pathset, cmdopts, info)
+            elif graph["type"] == "stacked_line":
+                try:
+                    graph = strictyaml.load(yaml.dump(graph), schema.stacked_line).data
+                except strictyaml.YAMLError as e:
+                    _logger.critical("Non-conformant stacked_line YAML: %s", e)
+                    raise
+                _gen_stacked_linegraph(graph, pathset, cmdopts, info)
+
+
+def _gen_summary_linegraph(
+    graph: types.YAMLDict,
+    pathset: batchroot.PathSet,
+    cmdopts: types.Cmdopts,
+    info: bcbridge.GraphInfo,
+) -> None:
+    legend = "{0}+{1}".format(cmdopts["controller"], cmdopts["scenario"])
+
+    paths = graphs.PathSet(
+        input_root=pathset.stat_interexp_root,
+        output_root=pathset.graph_interexp_root,
+        batchroot=pathset.root,
+        model_root=pathset.model_interexp_root,
+    )
+
+    # 2025-06-05 [JRH]: We always write stage {3,4} output data files as .csv
+    # because that is currently SIERRA's 'native' format; this may change in the
+    # future.
+    graphs.summary_line(
+        paths=paths,
+        input_stem=graph["dest_stem"],
+        output_stem=graph["dest_stem"],
+        medium="storage.csv",
+        legend=[legend],
+        stats=cmdopts["dist_stats"],
+        title=graph["title"],
+        xlabel=info.xlabel,
+        ylabel=graph.get("ylabel", None),
+        backend=graph.get("backend", cmdopts["graphs_backend"]),
+        xticks=info.xticks,
+        xticklabels=info.xticklabels,
+        logyscale=graph.get("logy", cmdopts["plot_log_yscale"]),
+        large_text=cmdopts["plot_large_text"],
+    )
+
+
+def _gen_stacked_linegraph(
+    graph: types.YAMLDict,
+    pathset: batchroot.PathSet,
+    cmdopts: types.Cmdopts,
+    info: bcbridge.GraphInfo,
+) -> None:
+
+    paths = graphs.PathSet(
+        input_root=pathset.stat_interexp_root,
+        output_root=pathset.graph_interexp_root,
+        model_root=None,
+        batchroot=pathset.root,
+    )
+
+    graphs.stacked_line(
+        paths=paths,
+        input_stem=graph["dest_stem"],
+        output_stem=graph["dest_stem"],
+        stats=cmdopts["dist_stats"],
+        medium="storage.csv",
+        title=graph["title"],
+        backend=graph.get("backend", cmdopts["graphs_backend"]),
+        xticks=None,
+        xlabel=graph.get("xlabel", "Time"),
+        ylabel=graph.get("ylabel", None),
+        logyscale=graph.get("logy", cmdopts["plot_log_yscale"]),
+        large_text=cmdopts["plot_large_text"],
+        legend=graph.get("legend", [f"exp{i}" for i in range(0, len(info.exp_names))]),
+    )
+
+
+__all__ = ["generate"]

sierra/plugins/prod/graphs/intra/__init__.py

@@ -0,0 +1,15 @@
+#
+# Copyright 2024 John Harwell, All rights reserved.
+#
+# SPDX-License Identifier: MIT
+#
+"""Container module for intra-experiment graph generation in stage 4."""
+
+# Core packages
+
+# 3rd party packages
+
+# Project packages
+from . import generate as generate
+from . import line as line
+from . import heatmap as heatmap