epic-capybara 1.0.0__tar.gz

epic_capybara-1.0.0/.github/workflows/build.yml

@@ -0,0 +1,17 @@
+name: "Test capybara installation"
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Build and install epic-capybara
+        run: |
+          pip install hatch
+          hatch build
+          pip install dist/*.whl

epic_capybara-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build
+        run: python -m pip install --upgrade build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/epic-capybara
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

epic_capybara-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/

epic_capybara-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Electron-Ion Collider (EIC) Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

epic_capybara-1.0.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: epic-capybara
+Version: 1.0.0
+Summary: Track and visualize multi-dimensional CI metrics
+Project-URL: Documentation, https://github.com/eic/epic-capybara#readme
+Project-URL: Issues, https://github.com/eic/epic-capybara/issues
+Project-URL: Source, https://github.com/eic/epic-capybara
+Author-email: Dmitry Kalinkin <dmitry.kalinkin@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.7
+Requires-Dist: awkward
+Requires-Dist: bokeh>=3.0.0
+Requires-Dist: click
+Requires-Dist: hist
+Requires-Dist: pygithub
+Requires-Dist: requests
+Requires-Dist: scipy
+Requires-Dist: uproot
+Provides-Extra: rntuple
+Requires-Dist: uproot>=5.7.0; extra == 'rntuple'
+Description-Content-Type: text/markdown
+
+# epic-capybara
+
+epic-capybara is a collection of tools for comparison and presentation of
+differences between [ROOT](https://root.cern) TTree files. The available tools
+are:
+
+- `capybara capy` fetches CI artifacts either for a single revision of for the PR branch and its reference branch
+- `capybara bara` projects each TTree leaf onto a histogram, render it as an html report using Bokeh
+- `capybara cate` upload report to a github repo
+
+See `capybara --help` or `capybara <tool-name> --help` for options.
+
+### Installing
+
+You will need to obtain epic-capybara itself and [Hatch](https://hatch.pypa.io/latest/).
+
+```
+git clone git@github.com:eic/epic-capybara.git
+pip install hatch
+cd epic-capybara
+```
+
+You can then either run the development version:
+```
+hatch env run -- capybara capy pr 123
+```
+
+Or build a wheel and install it locally
+```
+hatch build
+pip install dist/*.whl
+```
+
+### Legacy scripts
+
+This repository contains scripts for ROOT file comparisons in CI.
+- `capy.py`: obtain ROOT files from previous CI pipelines
+- `bara.py`: compare two ROOT files

epic_capybara-1.0.0/README.md

@@ -0,0 +1,38 @@
+# epic-capybara
+
+epic-capybara is a collection of tools for comparison and presentation of
+differences between [ROOT](https://root.cern) TTree files. The available tools
+are:
+
+- `capybara capy` fetches CI artifacts either for a single revision of for the PR branch and its reference branch
+- `capybara bara` projects each TTree leaf onto a histogram, render it as an html report using Bokeh
+- `capybara cate` upload report to a github repo
+
+See `capybara --help` or `capybara <tool-name> --help` for options.
+
+### Installing
+
+You will need to obtain epic-capybara itself and [Hatch](https://hatch.pypa.io/latest/).
+
+```
+git clone git@github.com:eic/epic-capybara.git
+pip install hatch
+cd epic-capybara
+```
+
+You can then either run the development version:
+```
+hatch env run -- capybara capy pr 123
+```
+
+Or build a wheel and install it locally
+```
+hatch build
+pip install dist/*.whl
+```
+
+### Legacy scripts
+
+This repository contains scripts for ROOT file comparisons in CI.
+- `capy.py`: obtain ROOT files from previous CI pipelines
+- `bara.py`: compare two ROOT files

epic_capybara-1.0.0/epic_capybara/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2023-present Dmitry Kalinkin <dmitry.kalinkin@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+__version__ = '1.0.0'

epic_capybara-1.0.0/epic_capybara/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2023-present Dmitry Kalinkin <dmitry.kalinkin@gmail.com>
+#
+# SPDX-License-Identifier: MIT

epic_capybara-1.0.0/epic_capybara/__main__.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: 2023-present Dmitry Kalinkin <dmitry.kalinkin@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+import sys
+
+if __name__ == '__main__':
+    from .cli import capybara
+
+    sys.exit(capybara())

epic_capybara-1.0.0/epic_capybara/cli/__init__.py

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: 2023-present Dmitry Kalinkin <dmitry.kalinkin@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+import click
+
+from ..__about__ import __version__
+from .capy import capy
+from .bara import bara
+from .cate import cate
+
+@click.group(context_settings={'help_option_names': ['-h', '--help']}, invoke_without_command=False)
+@click.version_option(version=__version__, prog_name='capybara')
+@click.pass_context
+def capybara(ctx: click.Context):
+    pass
+
+capybara.add_command(capy)
+capybara.add_command(bara)
+capybara.add_command(cate)

epic_capybara-1.0.0/epic_capybara/cli/bara.py

@@ -0,0 +1,506 @@
+import gzip
+import os
+import re
+
+import awkward as ak
+import click
+import numpy as np
+import uproot
+from bokeh.events import DocumentReady
+from bokeh.io import curdoc
+from bokeh.layouts import gridplot
+from bokeh.models import ColumnDataSource
+from bokeh.models import CustomJSExpr
+from bokeh.models import Range1d
+from bokeh.models import PrintfTickFormatter
+from bokeh.plotting import figure, output_file, save
+from hist import Hist
+from scipy.stats import kstest
+
+from ..util import skip_common_prefix
+
+_MIDPOINT_EXPR_CODE = """
+const y1 = this.data.y1;
+const y2 = this.data.y2;
+return y1.map((v, i) => (v + y2[i]) / 2);
+"""
+
+
+def _is_leaf(obj):
+    """Check if an uproot branch/field object is a leaf (has no sub-branches/sub-fields).
+
+    Supports both TTree TBranch objects (which use `.branches`) and
+    RNTuple RField objects (which use `.fields`).
+    """
+    if hasattr(obj, 'branches'):
+        return len(obj.branches) == 0
+    if hasattr(obj, 'fields'):
+        return len(obj.fields) == 0
+    return True
+
+
+def _normalize_key(key):
+    """Normalize uproot key format between TTree and RNTuple styles.
+
+    TTree EDM4hep keys follow 'CollectionName/CollectionName.fieldPath' pattern.
+    RNTuple EDM4hep keys follow 'CollectionName.fieldPath' pattern.
+    This function converts TTree-style keys to the RNTuple-style format so that
+    the same physics quantity has the same key regardless of the input file format.
+
+    TTree keys for fixed-size array branches include a trailing '[N]' size
+    annotation (e.g. 'covariance.covariance[21]') which is absent in RNTuple
+    keys; this suffix is stripped so the two formats match.
+
+    >>> _normalize_key('MCParticles/MCParticles.momentum.x')
+    'MCParticles.momentum.x'
+    >>> _normalize_key('MCParticles.momentum.x')
+    'MCParticles.momentum.x'
+    >>> _normalize_key('EventHeader/EventHeader.eventNumber')
+    'EventHeader.eventNumber'
+    >>> _normalize_key('CentralCKFTrackParameters/CentralCKFTrackParameters.covariance.covariance[21]')
+    'CentralCKFTrackParameters.covariance.covariance'
+    """
+    if "/" in key:
+        _, field_part = key.split("/", 1)
+    else:
+        field_part = key
+    return re.sub(r'\[\d+\]$', '', field_part)
+
+
+def match_filter(key, match, unmatch):
+    accept = True
+    if match:
+        accept = False
+        for regex in match:
+            if regex.match(key):
+                accept = True
+    for regex in unmatch:
+        if regex.match(key):
+            accept = False
+    return accept
+
+
+@click.command()
+@click.argument("files", type=click.File('rb'), nargs=-1)
+@click.option(
+    "-m", "--match", multiple=True,
+    help="Only include collections with names matching a regex"
+)
+@click.option(
+    "-M", "--unmatch", multiple=True,
+    help="Exclude collections with names matching a regex"
+)
+@click.option(
+    "--serve", is_flag=True,
+    default=False,
+    help="Run a local HTTP server to view the report"
+)
+def bara(files, match, unmatch, serve):
+    arr = {}
+
+    match = list(map(re.compile, match))
+    unmatch = list(map(re.compile, unmatch))
+
+    for _file in files:
+        tree = uproot.open(_file)["events"]
+
+        sort_by_evtnum = None
+        for evtnum_key in ["EventHeader/EventHeader.eventNumber", "EventHeader.eventNumber"]:
+            if evtnum_key in tree.keys(recursive=True):
+                evtnum = tree[evtnum_key].array()
+                sort_by_evtnum = ak.argsort(ak.flatten(evtnum))
+                break
+
+        for key in tree.keys(recursive=True):
+            if not key.startswith("PARAMETERS") and _is_leaf(tree[key]):
+                normalized = _normalize_key(key)
+                if match_filter(normalized, match, unmatch):
+                    val = tree[key].array()
+                    if sort_by_evtnum is not None:
+                        val = val[sort_by_evtnum]
+                    arr.setdefault(normalized, {})[_file] = val
+
+    paths = skip_common_prefix([_file.name.split("/") for _file in files])
+    paths = skip_common_prefix([reversed(list(path)) for path in paths])
+    labels = ["/".join(reversed(list(reversed_path))) for reversed_path in paths]
+
+    collection_figs = {}
+    collection_with_diffs = {}
+    collection_matching_count = {}
+    collection_step_exprs = {}
+
+    for key in sorted(arr.keys()):
+        if any("string" in str(ak.type(a)) for a in arr[key].values()):
+            click.echo(f"String value detected for key \"{key}\". Skipping...")
+            continue
+        x_min = min(filter(
+            lambda v: v is not None,
+            map(lambda a: ak.min(ak.mask(a, np.isfinite(a))), arr[key].values())
+        ), default=None)
+        if x_min is None:
+            continue
+        x_range = max(filter(
+            lambda v: v is not None,
+            map(lambda a: ak.max(ak.mask(a - x_min, np.isfinite(a))), arr[key].values())
+        ), default=None)
+        nbins = 10
+
+        if (any("* uint" in str(ak.type(a)) for a in arr[key].values())
+           or any("* int" in str(ak.type(a)) for a in arr[key].values())):
+            x_range = x_range + 1
+            nbins = int(min(100, np.ceil(x_range)))
+        else:
+            x_range = x_range * 1.1
+
+        if x_range == 0:
+            x_range = 1
+
+        if "." in key:
+            branch_name = key.split(".", 1)[0]
+            leaf_name = key
+        else:
+            branch_name = key
+            leaf_name = key
+
+        midpoint_expr = collection_step_exprs.setdefault(
+            branch_name,
+            CustomJSExpr(code=_MIDPOINT_EXPR_CODE),
+        )
+        fig = figure(x_axis_label=leaf_name, y_axis_label="Entries")
+        if x_range < 1.:
+            fig.xaxis.formatter = PrintfTickFormatter(format="%.2g")
+        collection_figs.setdefault(branch_name, []).append(fig)
+        y_max = 0
+
+        prev_file_arr = None
+        vis_params = [
+          ("green", 1.5, "solid", " "),
+          ("red", 3, "dashed", ","),
+          ("blue", 2, "dotted", "."),
+        ]
+
+        leaf_min_pvalue = 1.0
+        if set(arr[key].keys()) != set(files):
+            # not every file has the key
+            collection_with_diffs[branch_name] = 0.0
+            leaf_min_pvalue = 0.0
+
+        for _file, label, (color, line_width, line_dash, hatch_pattern) in zip(files, labels, vis_params):
+            if _file not in arr[key]:
+                continue
+            file_arr = arr[key][_file]
+
+            # diff and KS test
+            pvalue = None
+            if prev_file_arr is not None:
+                if ((ak.num(file_arr, axis=0) != ak.num(prev_file_arr, axis=0))
+                   or ak.any(ak.num(file_arr, axis=1)
+                             != ak.num(prev_file_arr, axis=1))
+                   or ak.any(ak.nan_to_none(file_arr)
+                             != ak.nan_to_none(prev_file_arr))):
+                    if (ak.num(ak.flatten(file_arr, axis=None), axis=0) > 0 and
+                        ak.num(ak.flatten(prev_file_arr, axis=None), axis=0) > 0):
+                        # We can only apply the KS test on non-empty arrays
+                        pvalue = kstest(
+                                ak.to_numpy(ak.flatten(file_arr, axis=None)),
+                                ak.to_numpy(ak.flatten(prev_file_arr, axis=None))
+                            ).pvalue
+                    else:
+                        pvalue = 0
+                    print(key, f"p = {pvalue:.3f}")
+                    print(prev_file_arr)
+                    print(file_arr)
+                    collection_with_diffs[branch_name] = min(pvalue, collection_with_diffs.get(branch_name, 1.))
+                    leaf_min_pvalue = min(leaf_min_pvalue, pvalue)
+
+            # Figure
+            h = (
+                Hist.new
+                .Reg(nbins, 0, x_range, name="x", label=key)
+                .Int64()
+            )
+            h.fill(x=ak.flatten(file_arr - x_min, axis=None))
+
+            ys, edges = h.to_numpy()
+            y0 = np.concatenate([ys, [ys[-1]]])
+            legend_label=label + (f"\n{100*pvalue:.0f}%CL KS" if pvalue is not None else "")
+            source = ColumnDataSource(
+                {
+                    "x": edges + x_min,
+                    "y1": y0 - np.sqrt(y0),
+                    "y2": y0 + np.sqrt(y0),
+                }
+            )
+            step_r = fig.step(
+                x="x",
+                y={"expr": midpoint_expr},
+                mode="after",
+                source=source,
+                legend_label=legend_label,
+                line_color=color,
+                line_width=line_width,
+                line_dash=line_dash,
+            )
+            step_r.nonselection_glyph = step_r.glyph
+            varea_r = fig.varea_step(
+                x="x",
+                y1="y1",
+                y2="y2",
+                step_mode="after",
+                source=source,
+                legend_label=legend_label,
+                fill_color=color if hatch_pattern == " " else None,
+                fill_alpha=0.25,
+                hatch_color=color,
+                hatch_alpha=0.5,
+                hatch_pattern=hatch_pattern,
+            )
+            varea_r.nonselection_glyph = varea_r.glyph
+            fig.legend.background_fill_alpha = 0.5 # make legend more transparent
+
+            y_max = max(y_max, np.max(y0 + np.sqrt(y0)))
+            prev_file_arr = file_arr
+
+        if leaf_min_pvalue == 1.0:
+            collection_matching_count[branch_name] = collection_matching_count.get(branch_name, 0) + 1
+
+        x_bounds = (x_min - 0.05 * x_range, x_min + 1.05 * x_range)
+        y_bounds = (- 0.05 * y_max, 1.05 * y_max)
+        # Set y range for histograms
+        if np.all(np.isfinite(x_bounds)):
+            try:
+                fig.x_range = Range1d(
+                    *x_bounds,
+                    bounds=x_bounds)
+            except ValueError as e:
+                click.secho(str(e), fg="red", err=True)
+        else:
+            click.secho(f"overflow while calculating x bounds for \"{key}\"", fg="red", err=True)
+        if np.all(np.isfinite(y_bounds)):
+            try:
+                fig.y_range = Range1d(
+                    *y_bounds,
+                    bounds=y_bounds)
+            except ValueError as e:
+                click.secho(str(e), fg="red", err=True)
+        else:
+            click.secho(f"overflow while calculating y bounds for \"{key}\"", fg="red", err=True)
+
+    def to_filename(branch_name):
+        return branch_name.replace("#", "__pound__")
+
+    def option_key(item):
+        collection_name, figs = item
+        key = ""
+        if collection_name in collection_with_diffs:
+            if collection_with_diffs[collection_name] > 0.99:
+                key += " 0.99"
+            elif collection_with_diffs[collection_name] > 0.95:
+                key += " 0.95"
+            elif collection_with_diffs[collection_name] > 0.67:
+                key += " 0.67"
+            else:
+                key += " 0.00"
+        key += collection_name.lstrip("_")
+        return key
+
+    options = [("", "")]
+    for collection_name, figs in sorted(collection_figs.items(), key=option_key):
+        marker = ""
+        if collection_name in collection_with_diffs:
+            if collection_with_diffs[collection_name] > 0.99:
+                marker = " (*)"
+            elif collection_with_diffs[collection_name] > 0.95:
+                marker = " (**)"
+            elif collection_with_diffs[collection_name] > 0.67:
+                marker = " (***)"
+            else:
+                marker = " (****)"
+        options.append((to_filename(collection_name), collection_name + marker))
+
+    from bokeh.models import CustomJS, Select, DataTable, TableColumn, HTMLTemplateFormatter, NumberFormatter, StringFormatter
+
+    def mk_summary_table():
+        rows = []
+        for collection_name, figs in sorted(
+            collection_figs.items(),
+            key=lambda item: item[0].lstrip("_"),
+        ):
+            if collection_name in collection_with_diffs:
+                pvalue = collection_with_diffs[collection_name]
+                if pvalue > 0.99:
+                    color = "#28a745"  # green
+                elif pvalue > 0.95:
+                    color = "#ffc107"  # yellow
+                elif pvalue > 0.67:
+                    color = "#fd7e14"  # orange
+                else:
+                    color = "#dc3545"  # red
+                pvalue_str = f"{pvalue:.3f}"
+            else:
+                color = "transparent"
+                pvalue_str = ""
+            n_total = len(figs)
+            n_match = collection_matching_count.get(collection_name, 0)
+            n_diff = n_total - n_match
+            rows.append((collection_name, color, pvalue_str, n_match, n_diff, n_total))
+
+        source = ColumnDataSource({
+            "collection": [r[0] for r in rows],
+            "filename":   [to_filename(r[0]) for r in rows],
+            "color":      [r[1] for r in rows],
+            "pvalue":     [r[2] for r in rows],
+            "nmatch":     [r[3] for r in rows],
+            "ndiff":      [r[4] for r in rows],
+            "nplots":     [r[5] for r in rows],
+        })
+        square_style = (
+            'display:inline-block;width:0.9em;height:0.9em;'
+            'margin-right:6px;vertical-align:middle;'
+            'border:1px solid #999;background-color:<%= color %>;'
+        )
+        link_fmt = HTMLTemplateFormatter(
+            template=f'<span style="{square_style}"></span>'
+                     '<a href="#<%= filename %>"><%= value %></a>'
+        )
+        right_str = StringFormatter(text_align="right")
+        right_num = NumberFormatter(text_align="right")
+        columns = [
+            TableColumn(field="collection", title="Collection", formatter=link_fmt, width=500),
+            TableColumn(field="pvalue", title="min KS p-value", formatter=right_str, width=120),
+            TableColumn(field="nmatch", title="# matching", formatter=right_num, width=80),
+            TableColumn(field="ndiff", title="# differing", formatter=right_num, width=80),
+            TableColumn(field="nplots", title="# plots", formatter=right_num, width=80),
+        ]
+        table = DataTable(
+            source=source,
+            columns=columns,
+            width=800,
+            sizing_mode="stretch_height",
+            index_position=None,
+            sortable=True,
+            selectable=True,
+        )
+        source.selected.js_on_change("indices", CustomJS(args={"source": source}, code="""
+          const idx = cb_obj.indices;
+          if (idx.length > 0) {
+            const filename = source.data["filename"][idx[0]];
+            window.location.hash = "#" + filename;
+            fetchAndReplaceBokehDocument(filename);
+          }
+        """))
+        return table
+
+    def mk_dropdown(value=""):
+        dropdown = Select(title="Select branch (**** < 67% CL, ..., * > 99% CL stat. equiv.):", value=value, options=options)
+        dropdown.js_on_change("value", CustomJS(code="""
+          console.log('dropdown: ' + this.value, this.toString())
+          if (this.value != "") {
+            window.location.hash = "#" + this.value;
+            fetchAndReplaceBokehDocument(this.value);
+          } else {
+            // Empty option selected: navigate back to the index page.
+            window.location.hash = "";
+          }
+        """))
+        return dropdown
+
+    def mk_dropdown_minimal(value=""):
+        # Embed only the currently selected option; the full list is stored once
+        # in index.html's JavaScript and restored client-side after each load.
+        # This avoids repeating a ~54 KB options list in every .json.gz file.
+        label = next((lbl for val, lbl in options if val == value), value)
+        minimal_options = [("", "")] + ([(value, label)] if value else [])
+        dropdown = Select(title="Select branch (**** < 67% CL, ..., * > 99% CL stat. equiv.):", value=value, options=minimal_options)
+        dropdown.js_on_change("value", CustomJS(code="""
+          console.log('dropdown: ' + this.value, this.toString())
+          if (this.value != "") {
+            window.location.hash = "#" + this.value;
+            fetchAndReplaceBokehDocument(this.value);
+          } else {
+            // Empty option selected: navigate back to the index page.
+            window.location.hash = "";
+          }
+        """))
+        return dropdown
+
+    from bokeh.layouts import column
+    from bokeh.embed import json_item
+    import json
+
+    os.makedirs("capybara-reports", exist_ok=True)
+
+    for collection_name, figs in collection_figs.items():
+        item = column(
+          mk_dropdown_minimal(collection_name),
+          gridplot(figs, ncols=3, width=400, height=300),
+        )
+
+        with gzip.open(f"capybara-reports/{to_filename(collection_name)}.json.gz", "wt") as fp:
+            json.dump(json_item(item), fp, separators=(',', ':'))
+
+    curdoc().js_on_event(DocumentReady, CustomJS(args={"all_options": options}, code="""
+      window._bokehSelectOptions = all_options;
+
+      function fetchAndReplaceBokehDocument(location) {
+        fetch(location + '.json.gz')
+          .then(async function(response) {
+            if (!response.ok) {
+                throw new Error('Network response was not ok');
+            }
+
+            const ds = new DecompressionStream('gzip');
+            const decompressedStream = response.body.pipeThrough(ds);
+            const decompressedResponse = new Response(decompressedStream);
+            const item = await decompressedResponse.json();
+
+            Bokeh.documents[0].replace_with_json(item.doc);
+
+            // Restore the full options list to the newly loaded Select widget.
+            for (const [, model] of Bokeh.documents[0]._all_models) {
+              if (model.options instanceof Array) {
+                model.options = window._bokehSelectOptions;
+                model.value = location;
+                break;
+              }
+            }
+          })
+          .catch(function(error) {
+            console.error('Fetch or decompression failed:', error);
+          });
+      }
+
+      window.onhashchange = function() {
+        var location = window.location.hash.replace(/^#/, "");
+        if (location == "") {
+          // No hash: return to the index page. Since there is no index.json.gz,
+          // just reload the page to get a fresh index.html.
+          if (typeof window.current_location !== 'undefined') {
+            window.location.reload();
+          }
+          return;
+        }
+        if ((typeof current_location === 'undefined') || (current_location != location)) {
+          fetchAndReplaceBokehDocument(location);
+          window.current_location = location;
+        }
+      }
+      window.onhashchange();
+    """))
+    output_file(filename="capybara-reports/index.html", title="ePIC capybara report")
+    save(column(
+        mk_dropdown(),
+        mk_summary_table(),
+        sizing_mode="stretch_height",
+    ))
+
+    if serve:
+        os.chdir("capybara-reports/")
+        from http.server import SimpleHTTPRequestHandler
+        from socketserver import TCPServer
+        with TCPServer(("127.0.0.1", 24535), SimpleHTTPRequestHandler) as httpd:
+            print("Serving report at http://127.0.0.1:24535")
+            try:
+                httpd.serve_forever()
+            except KeyboardInterrupt:
+                pass

epic_capybara-1.0.0/epic_capybara/cli/capy.py

@@ -0,0 +1,148 @@
+import click
+from github import Auth, Github, GithubException
+
+from ..github import download_artifact
+
+
+@click.command()
+@click.option('--artifact-name', default="rec_dis_18x275_minQ2=1000_craterlake_18x275.edm4eic.root")
+@click.option('--token', envvar="GITHUB_TOKEN", required=True, help="GitHub access token (defaults to GITHUB_TOKEN environment variable)")
+@click.option('--owner', default="eic", help="Owner of the target repository")
+@click.option('--repo', default="EICrecon", help="Name of the target repository")
+@click.argument('pr_number', type=int)
+@click.pass_context
+def pr(ctx: click.Context, artifact_name: str, owner: str, pr_number: int, repo: str, token: str):
+    gh = Github(auth=Auth.Token(token))
+    repo = gh.get_user(owner).get_repo(repo)
+
+    click.secho(f'Fetching metadata for #{pr_number}...', fg='green', err=True)
+    try:
+        pr = repo.get_pull(pr_number)
+    except GithubException as e:
+        click.secho("Pull Request is not accessible", fg="red", err=True)
+        click.secho(e)
+        ctx.exit(1)
+    click.echo(f"Title: {pr.title}", err=True)
+    other_repo_message = ""
+    if pr.head.repo != repo:
+       other_repo_message = click.style(f"{pr.head.repo.owner.login}/{pr.head.repo.name}", italic=True) + "/"
+    click.echo(f"PR head: {other_repo_message}{click.style(pr.head.ref, bold=True)}@{pr.head.sha}, targets {click.style(pr.base.ref, bold=True)}@{pr.base.sha}", err=True)
+
+    workflow_head = None
+    workflow_base = None
+    messages = []
+
+    def item_show_func(workflow):
+       workflow_id = str(workflow.id) if hasattr(workflow, "id") else "?"
+       head_found = "no" if workflow_head is None else "yes"
+       base_found = "no" if workflow_base is None else "yes"
+       return f"{workflow_id} head:{head_found} base:{base_found}"
+
+    with click.progressbar(
+            repo.get_workflow_runs(),
+            label="Loading workflows",
+            item_show_func=item_show_func,
+    ) as workflows_bar:
+        for workflow in workflows_bar:
+            # workflow.head_commit.sha is not available, so we take the latest
+            # TODO check if PR is the latest by parsing log files?
+            if workflow.head_repository == pr.head.repo and workflow.head_branch == pr.head.ref and workflow_head is None:
+                if workflow.get_artifacts().totalCount == 0:
+                    messages.append(dict(message=f"Skipping workflow {workflow.html_url} on {workflow.head_branch} with no artifacts", fg="red", err=True))
+                    continue
+                workflow_head = workflow
+            if workflow.head_repository == repo and workflow.head_branch == pr.base.ref and workflow_base is None:
+                if workflow.get_artifacts().totalCount == 0:
+                    messages.append(dict(message=f"Skipping workflow {workflow.html_url} on {workflow.head_branch} with no artifacts", fg="red", err=True))
+                    continue
+                workflow_base = workflow
+            if workflow_head is not None and workflow_base is not None:
+                break
+
+    if workflow_head is None:
+        click.secho("No completed workflow found for head branch", fg="red")
+        ctx.exit(1)
+    if workflow_base is None:
+        click.secho("No completed workflow found for base branch", fg="red")
+        ctx.exit(1)
+
+    for message in messages:
+        click.secho(**message)
+
+    click.echo(f"PR base workflow: {workflow_base.html_url}")
+    click.echo(f"PR head workflow: {workflow_head.html_url}")
+
+    click.echo(download_artifact(workflow_base, artifact_name, token=token, click=click))
+    click.echo(download_artifact(workflow_head, artifact_name, token=token, click=click))
+
+
+@click.command()
+@click.option('--artifact-name', default="rec_dis_18x275_minQ2=1000_craterlake_18x275.edm4eic.root")
+@click.option('--token', envvar="GITHUB_TOKEN", required=True, help="GitHub access token (defaults to GITHUB_TOKEN environment variable)")
+@click.option('--owner', default="eic", help="Owner of the target repository")
+@click.option('--repo', default="EICrecon", help="Name of the target repository")
+@click.argument('ref', type=str)
+@click.pass_context
+def rev(ctx: click.Context, artifact_name: str, owner: str, ref: str, repo: str, token: str):
+    gh = Github(auth=Auth.Token(token))
+    repo = gh.get_user(owner).get_repo(repo)
+
+    rev = repo.get_commit(ref)
+
+    def item_show_func(workflow):
+       workflow_id = str(workflow.id) if hasattr(workflow, "id") else "?"
+       head_found = "no" if workflow_head is None else "yes"
+       return f"{workflow_id} head:{head_found}"
+
+    workflow_head = None
+    messages = []
+
+    with click.progressbar(
+            repo.get_workflow_runs(),
+            label="Loading workflows",
+            item_show_func=item_show_func,
+    ) as workflows_bar:
+        for workflow in workflows_bar:
+            # workflow.head_commit.sha is not available, so we take the latest
+            # TODO check if PR is the latest by parsing log files?
+            if workflow.head_repository == repo and workflow.head_sha == rev.sha and workflow_head is None:
+                if workflow.get_artifacts().totalCount == 0:
+                    messages.append(dict(message=f"Skipping workflow {workflow.html_url} on {workflow.head_branch} with no artifacts", fg="red", err=True))
+                    continue
+                workflow_head = workflow
+            if workflow_head is not None:
+                break
+
+    if workflow_head is None:
+        click.secho("No completed workflow found for head branch", fg="red")
+        ctx.exit(1)
+
+    for message in messages:
+        click.secho(**message)
+
+    click.echo(f"PR head workflow: {workflow_head.html_url}")
+
+    click.echo(download_artifact(workflow_head, artifact_name, token=token, click=click))
+
+
+class ForwardGroup(click.Group):
+    def resolve_command(self, ctx, args):
+        try:
+            cmd_name, cmd, args = super().resolve_command(ctx, args)
+        except click.exceptions.UsageError as e:
+            click.secho(f"Invoking `capy' without subcommand is deprecated. Use `capy pr'.", fg="yellow", err=True)
+            args = ["pr"] + args
+            cmd_name, cmd, args = super().resolve_command(ctx, args)
+        return cmd_name, cmd, args
+
+@click.group(cls=ForwardGroup, context_settings={'help_option_names': ['-h', '--help']})
+@click.option('--artifact-name', default="rec_dis_18x275_minQ2=1000_craterlake_18x275.edm4eic.root")
+@click.option('--token', envvar="GITHUB_TOKEN", required=True, help="GitHub access token (defaults to GITHUB_TOKEN environment variable)")
+@click.option('--owner', default="eic", help="Owner of the target repository")
+@click.option('--repo', default="EICrecon", help="Name of the target repository")
+def capy(**kwargs):
+    pass
+
+
+capy.add_command(pr)
+capy.add_command(rev)

epic_capybara-1.0.0/epic_capybara/cli/cate.py

@@ -0,0 +1,64 @@
+import shutil
+import subprocess
+from github import Auth, Github, GithubException
+from pathlib import Path
+
+import click
+from urllib.parse import urlparse
+
+from ..filesystem import hashdir
+from ..util import get_cache_dir
+
+
+@click.command()
+@click.option('--token', envvar="GITHUB_TOKEN", required=True, help="GitHub access token (defaults to GITHUB_TOKEN environment variable)")
+@click.option('--owner', help="Owner of the target repository (token owner by default)")
+@click.option('--repo', default="capybara-reports", help="Name of the target repository")
+@click.argument('report-dir', type=click.Path(exists=True, file_okay=False, dir_okay=True))
+@click.pass_context
+def cate(ctx: click.Context, owner: str, repo: str, report_dir: str, token: str):
+    gh = Github(auth=Auth.Token(token))
+
+    if owner is not None:
+        user = gh.get_user(owner)
+    else:
+        user = gh.get_user()
+
+    try:
+        repo = user.get_repo(repo)
+    except GithubException:
+        click.secho(f"Repository {user.login}/{repo.name} is not available. Attempting to create...", fg="yellow", err=True)
+        repo = user.create_repo(repo)
+
+    report_dir = Path(report_dir)
+
+    prefix = hashdir(report_dir)
+
+    clone_url = urlparse(repo.clone_url)
+    # Add authentication information
+    clone_url = clone_url._replace(
+        netloc=f"{user.login}:{token}@{clone_url.netloc}",
+    )
+    local_repo = get_cache_dir() / user.login / repo.name
+
+    if not local_repo.exists():
+        subprocess.check_output(["git", "clone", clone_url.geturl(), str(local_repo)])
+    else:
+        subprocess.check_output(["git", "-C", str(local_repo), "pull"])
+    shutil.copytree(report_dir, local_repo / prefix)
+    subprocess.check_output(["git", "-C", str(local_repo), "add", prefix])
+    subprocess.check_output(["git", "-C", str(local_repo), "commit", "-m", f"Adding {prefix}/"])
+    subprocess.check_output(["git", "-C", str(local_repo), "push"])
+
+    try:
+        file = repo.get_contents(".nojekyll")
+    except GithubException.UnknownObjectException:
+        # file does not exist
+        repo.create_file(
+            ".nojekyll",
+            f"Adding .nojekyll", # commit message
+            "",
+            branch="gh-pages",
+        )
+
+    click.echo(f"https://{user.login}.github.io/{repo.name}/{prefix}/")

epic_capybara-1.0.0/epic_capybara/filesystem.py

@@ -0,0 +1,21 @@
+import hashlib
+from pathlib import Path
+
+
+def hashdir(path):
+    digest = hashlib.md5()
+
+    def recurse(cur_path, digest=None):
+        paths = cur_path.iterdir()
+        for file_ in sorted([p for p in paths if p.is_file()]):
+            digest.update(str(file_.relative_to(path)).encode())
+            with open(file_, "rb") as fp:
+                digest.update(fp.read())
+
+        paths = cur_path.iterdir()
+        for dir_ in sorted([p for p in paths if p.is_dir()]):
+            recurse(dir_, digest)
+
+    recurse(path, digest)
+
+    return digest.hexdigest()

epic_capybara-1.0.0/epic_capybara/github.py

@@ -0,0 +1,53 @@
+import io
+from pathlib import Path
+from zipfile import ZipFile
+
+import requests
+
+
+def download_artifact(workflow, artifact_name, token=None, click=None):
+    artifacts = [artifact for artifact in workflow.get_artifacts() if artifact.name == artifact_name]
+    if not artifacts:
+        if click is not None:
+            click.secho(f"Can not obtain {artifact_name}", fg="red", err=True)
+            if workflow.get_artifacts().totalCount:
+                click.secho(f"Available artifacts:", fg="red", err=True)
+                for artifact in workflow.get_artifacts():
+                    click.echo(artifact.name)
+            else:
+                click.secho(f"No artifacts available", fg="red", err=True)
+        return None
+
+    outdir = Path(workflow.created_at.isoformat().replace(":", "-") + "_" + workflow.head_sha)
+    outpath = outdir / artifact_name
+    if outpath.exists():
+        return outpath
+
+    if not outpath.parent.exists():
+        outdir.mkdir()
+
+    artifact, = artifacts
+    req = requests.get(artifact.archive_download_url, headers={"Authorization": f"token {token}"} if token else {})
+    zfp = ZipFile(io.BytesIO(req.content))
+
+    # Check if this is a single file zip
+    zip_filename = None
+    if artifact_name in zfp.namelist():
+        zip_filename = artifact_name
+    elif len(zfp.namelist()) == 1:
+        zip_filename, = zfp.namelist()
+        if click is not None:
+            click.secho(f"Can't locate {artifact_name} in the artifact ZIP archive, using {zip_filename} instead", fg="orange", err=True)
+
+    if zip_filename is not None:
+        # Extract a single file
+        with zfp.open(zip_filename) as fp_zip:
+            with open(outpath, "wb") as fp_out:
+                fp_out.write(fp_zip.read())
+    else:
+        # Extract all files
+        if click is not None:
+            click.secho(f"Can't locate {artifact_name} in the artifact ZIP archive, extracting all", fg="green", err=True)
+        zfp.extractall(path=outpath)
+
+    return outpath

epic_capybara-1.0.0/epic_capybara/util.py

@@ -0,0 +1,43 @@
+import os
+from pathlib import Path
+from itertools import chain, cycle, dropwhile, starmap, tee
+
+
+def get_cache_dir():
+    if "XDG_CACHE_HOME" in os.environ:
+        return os.environ["XDG_CACHE_HOME"] / "epic-capybara"
+    elif "HOME" in os.environ:
+        return Path(os.environ["HOME"]) / ".cache" / "epic-capybara"
+    elif "TMPDIR" in os.environ:
+        return Path(os.environ["TMPDIR"]) / "epic-capybara"
+    else:
+        raise RuntimeError("Unable to fine a suitable cache location")
+
+
+def skip_common_prefix(iters: list):
+    """Given a list of iterators, skips values until at least one iterator differs from the others. Returns the remaining iterators.
+
+    >>> [list(iter) for iter in skip_common_prefix(["hello"])]
+    [['h', 'e', 'l', 'l', 'o']]
+    >>> [list(iter) for iter in skip_common_prefix(["hello", "world!"])]
+    [['h', 'e', 'l', 'l', 'o'], ['w', 'o', 'r', 'l', 'd', '!']]
+    >>> [list(iter) for iter in skip_common_prefix([[3, 2, 1], [1, 2, 3, 4]])]
+    [[3, 2, 1], [1, 2, 3, 4]]
+    >>> [list(iter) for iter in skip_common_prefix([[1, 2, 3], [1, 2, 3, 4]])]
+    [[], [4]]
+    """
+    # ensure that we have iterators, so that we can chain unconsumed tail in the end
+    iters = list(map(iter, iters))
+    if len(iters) == 0:
+        raise ValueError("iters must not be empty")
+    elif len(iters) == 1:
+        tuple_iters = [zip(*iters)]
+    else:
+        tuple_iters = tee(
+            dropwhile(lambda vals: all(val == vals[0] for val in vals), zip(*iters)),
+            len(iters),
+        )
+    return list(starmap(
+        lambda ix, tuple_iter: chain(map(lambda t: t[ix], tuple_iter), iters[ix]),
+        enumerate(tuple_iters)
+    ))

epic_capybara-1.0.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "epic-capybara"
+description = 'Track and visualize multi-dimensional CI metrics'
+readme = "README.md"
+requires-python = ">=3.7"
+license = "MIT"
+keywords = []
+authors = [
+  { name = "Dmitry Kalinkin", email = "dmitry.kalinkin@gmail.com" },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.7",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Programming Language :: Python :: Implementation :: PyPy",
+  "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+  "awkward",
+  "bokeh>=3.0.0",
+  "click",
+  "hist",
+  "PyGithub",
+  "requests",
+  "scipy",
+  "uproot",
+]
+dynamic = ["version"]
+
+[project.optional-dependencies]
+rntuple = [
+  "uproot>=5.7.0",
+]
+
+[project.urls]
+Documentation = "https://github.com/eic/epic-capybara#readme"
+Issues = "https://github.com/eic/epic-capybara/issues"
+Source = "https://github.com/eic/epic-capybara"
+
+[project.scripts]
+capybara = "epic_capybara.cli:capybara"
+capy = "epic_capybara.cli:capy"
+bara = "epic_capybara.cli:bara"
+cate = "epic_capybara.cli:cate"
+
+[tool.hatch.version]
+path = "epic_capybara/__about__.py"
+
+[tool.hatch.envs.default]
+dependencies = [
+  "pytest",
+  "pytest-cov",
+]
+[tool.hatch.envs.default.scripts]
+cov = "pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=epic_capybara --cov=tests {args}"
+no-cov = "cov --no-cov {args}"
+
+[[tool.hatch.envs.test.matrix]]
+python = ["37", "38", "39", "310", "311"]
+
+[tool.coverage.run]
+branch = true
+parallel = true
+omit = [
+  "epic_capybara/__about__.py",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+  "no cov",
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+]

epic_capybara-1.0.0/tests/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2023-present Dmitry Kalinkin <dmitry.kalinkin@gmail.com>
+#
+# SPDX-License-Identifier: MIT

epic_capybara-1.0.0/tests/test_doctest.py

@@ -0,0 +1,7 @@
+import doctest
+
+import epic_capybara.util
+
+def test_docstrings():
+    doctest_results = doctest.testmod(m=epic_capybara.util)
+    assert doctest_results.failed == 0