guidepost 0.3.0__tar.gz → 0.3.2__tar.gz

guidepost-0.3.2/MANIFEST.in

@@ -0,0 +1,4 @@
+# `python -m build` builds the wheel from the sdist, so the compiled frontend
+# bundles must be in the sdist for them to reach the installed wheel. They are
+# gitignored (built by esbuild.config.js), so include them explicitly here.
+recursive-include guidepost/static *.js *.js.map

guidepost-0.3.2/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: guidepost
+Version: 0.3.2
+Summary: Guidepost. An overview visualization for understanding supercomputer queue data.
+Home-page: https://github.com/cscully-allison/guidepost
+Author: Connor Scully-Allison
+Author-email: cscullyallison@sci.utah.edu
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scikit-learn
+Requires-Dist: anywidget
+Requires-Dist: traitlets
+Requires-Dist: pyarrow>=14
+Requires-Dist: duckdb>=0.10
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Guidepost
+
+Guidepost is a Python library for visualizing High Performance Computing (HPC) job data in Jupyter notebooks. It turns a `pandas` DataFrame of job records into a single, linked, interactive overview — faceted heatmaps framed by histograms, a categorical bar chart, and a brushable color legend — so you can spot patterns in runtimes, queue waits, and resource usage, then export the exact records you care about back into Python.
+
+![Annotated Guidepost visualization showing the data grouping name, color-by-categorical bar chart, and the current selection of records for export](https://i.postimg.cc/vTDMX2b3/temp-Image-MVb5ui.avif)
+
+## Installation
+
+```bash
+pip install guidepost
+```
+
+## Quick start
+
+```python
+from guidepost import Guidepost
+import pandas as pd
+
+gp = Guidepost()
+gp.load_data(pd.read_parquet("data/jobs_data.parquet"))
+
+gp   # display in a notebook cell
+```
+
+Brush the heatmap or its histograms, then pull the selected rows back into Python:
+
+```python
+df = gp.selection.dataframe
+```
+
+Input is a `pandas` DataFrame with at least three numeric and two categorical columns (datetime columns are supported on the x-axis).
+
+## Documentation
+
+Full documentation lives in the **[Guidepost Wiki](https://github.com/cscully-allison/guidepost/wiki)**:
+
+- [Getting Started](https://github.com/cscully-allison/guidepost/wiki/Getting-Started)
+- [Data Requirements and Type Detection](https://github.com/cscully-allison/guidepost/wiki/Data-Requirements-and-Type-Detection)
+- [Configuration](https://github.com/cscully-allison/guidepost/wiki/Configuration)
+- [Understanding the Views](https://github.com/cscully-allison/guidepost/wiki/Understanding-the-Views) — and the per-view interaction guides
+- [Selecting and Exporting Data](https://github.com/cscully-allison/guidepost/wiki/Selecting-and-Exporting-Data)
+- [API Reference](https://github.com/cscully-allison/guidepost/wiki/API-Reference)
+- [FAQ and Troubleshooting](https://github.com/cscully-allison/guidepost/wiki/FAQ-and-Troubleshooting)
+
+## Contributing
+
+Contributions are welcome. Fork the repository, create a branch for your feature or bugfix, and open a pull request with a description of your changes.
+
+## License
+
+Guidepost is licensed under the MIT License. See the `LICENSE` file for details.
+
+## Acknowledgments
+
+Guidepost was developed under the auspices and with funding provided by the National Renewable Energy Laboratory (NREL), the National Science Foundation under NSF IIS-1844573 and IIS-2324465, and the Department of Energy under DE-SC0022044 and DE-SC0024635.
+
+## Contact
+
+For questions or feedback, reach out to the maintainer at [cscullyallison@sci.utah.edu].

guidepost-0.3.2/README.md

@@ -0,0 +1,59 @@
+# Guidepost
+
+Guidepost is a Python library for visualizing High Performance Computing (HPC) job data in Jupyter notebooks. It turns a `pandas` DataFrame of job records into a single, linked, interactive overview — faceted heatmaps framed by histograms, a categorical bar chart, and a brushable color legend — so you can spot patterns in runtimes, queue waits, and resource usage, then export the exact records you care about back into Python.
+
+![Annotated Guidepost visualization showing the data grouping name, color-by-categorical bar chart, and the current selection of records for export](https://i.postimg.cc/vTDMX2b3/temp-Image-MVb5ui.avif)
+
+## Installation
+
+```bash
+pip install guidepost
+```
+
+## Quick start
+
+```python
+from guidepost import Guidepost
+import pandas as pd
+
+gp = Guidepost()
+gp.load_data(pd.read_parquet("data/jobs_data.parquet"))
+
+gp   # display in a notebook cell
+```
+
+Brush the heatmap or its histograms, then pull the selected rows back into Python:
+
+```python
+df = gp.selection.dataframe
+```
+
+Input is a `pandas` DataFrame with at least three numeric and two categorical columns (datetime columns are supported on the x-axis).
+
+## Documentation
+
+Full documentation lives in the **[Guidepost Wiki](https://github.com/cscully-allison/guidepost/wiki)**:
+
+- [Getting Started](https://github.com/cscully-allison/guidepost/wiki/Getting-Started)
+- [Data Requirements and Type Detection](https://github.com/cscully-allison/guidepost/wiki/Data-Requirements-and-Type-Detection)
+- [Configuration](https://github.com/cscully-allison/guidepost/wiki/Configuration)
+- [Understanding the Views](https://github.com/cscully-allison/guidepost/wiki/Understanding-the-Views) — and the per-view interaction guides
+- [Selecting and Exporting Data](https://github.com/cscully-allison/guidepost/wiki/Selecting-and-Exporting-Data)
+- [API Reference](https://github.com/cscully-allison/guidepost/wiki/API-Reference)
+- [FAQ and Troubleshooting](https://github.com/cscully-allison/guidepost/wiki/FAQ-and-Troubleshooting)
+
+## Contributing
+
+Contributions are welcome. Fork the repository, create a branch for your feature or bugfix, and open a pull request with a description of your changes.
+
+## License
+
+Guidepost is licensed under the MIT License. See the `LICENSE` file for details.
+
+## Acknowledgments
+
+Guidepost was developed under the auspices and with funding provided by the National Renewable Energy Laboratory (NREL), the National Science Foundation under NSF IIS-1844573 and IIS-2324465, and the Department of Energy under DE-SC0022044 and DE-SC0024635.
+
+## Contact
+
+For questions or feedback, reach out to the maintainer at [cscullyallison@sci.utah.edu].

{guidepost-0.3.0 → guidepost-0.3.2}/guidepost/guidepost.py

@@ -21,6 +21,22 @@ from .aggregation import AggregationEngine
 SYNTHETIC_FACET_COL = "__gp_no_grouping__"
 SYNTHETIC_FACET_VALUE = "All records"
 
+
+class Selection:
+    """Wrapper around the records selected in the widget.
+
+    The selected DataFrame is exposed as `.dataframe`. This indirection
+    leaves room to attach further selection metadata in the future without
+    changing the `gp.selection` access pattern.
+    """
+
+    def __init__(self, dataframe):
+        self.dataframe = dataframe
+
+    def __repr__(self):
+        return f"Selection(dataframe={self.dataframe!r})"
+
+
 class Guidepost(anywidget.AnyWidget):
 
     _esm = os.path.join(os.path.dirname(__file__), "static",  "guidepost.js")
@@ -37,7 +53,6 @@ class Guidepost(anywidget.AnyWidget):
     
     selected_records = traitlets.Unicode("[]").tag(sync=True)
     records_df = pd.DataFrame()
-    selection = None
 
     _summary_stats = traitlets.Dict({}).tag(sync=True)
 
@@ -272,7 +287,10 @@ class Guidepost(anywidget.AnyWidget):
 
     @property
     def selection(self):
-        return self.retrieve_selected_data()
+        # `selection` is intentionally an object wrapper rather than the bare
+        # DataFrame so additional selection metadata can be hung off it later
+        # without breaking callers. The DataFrame lives on `.dataframe`.
+        return Selection(self.retrieve_selected_data())
 
     def retrieve_selected_data(self):
         if self.cached_records_df is None:

{guidepost-0.3.0 → guidepost-0.3.2}/guidepost/seriation.py

@@ -167,11 +167,49 @@ def _seriate_component(members, A, node_list, SpectralEmbedding):
         return sorted(members, key=lambda i: node_list[i])
 
     sub = A[members][:, members].toarray()
+
+    # On symmetric structures (e.g. a clique) the smallest non-zero Laplacian
+    # eigenvalue is degenerate, so the 1-D spectral coordinate is not unique:
+    # the eigensolver returns an arbitrary basis vector from that eigenspace,
+    # which varies across runs, platforms, and BLAS threading. There is no
+    # canonical order in that case, so fall back to deterministic name order.
+    # (EigenVALUES are stable even when the corresponding eigenVECTORS are not,
+    # so this test is itself reproducible.)
+    if _spectral_order_is_degenerate(sub):
+        return sorted(members, key=lambda i: node_list[i])
+
     emb = SpectralEmbedding(n_components=1, affinity="precomputed", random_state=0)
     coords = emb.fit_transform(sub)[:, 0]
-    local = sorted(range(len(members)), key=lambda t: (coords[t], node_list[members[t]]))
+    # Round so any residual floating-point noise on near-tied nodes collapses and
+    # the name-based secondary key decides their order deterministically.
+    local = sorted(
+        range(len(members)),
+        key=lambda t: (round(float(coords[t]), 9), node_list[members[t]]),
+    )
     seq = [members[t] for t in local]
     # Eigenvectors carry a sign ambiguity; canonicalize orientation by name.
     if node_list[seq[0]] > node_list[seq[-1]]:
         seq.reverse()
     return seq
+
+
+def _spectral_order_is_degenerate(sub, tol=1e-9):
+    """True when the 1-D spectral embedding of ``sub`` is ill-defined.
+
+    The seriation uses the eigenvector of the smallest non-zero eigenvalue of
+    the symmetric normalized Laplacian. When that eigenvalue is (near-)repeated,
+    the eigenvector — and hence the node order — is not unique. We detect that
+    from the eigenvalue *spectrum*, which ``eigvalsh`` returns deterministically
+    regardless of solver/threading, unlike the eigenvectors themselves.
+    """
+    deg = sub.sum(axis=1)
+    if np.any(deg <= 0):
+        return True  # an isolated node has no meaningful spectral position
+    d_inv_sqrt = 1.0 / np.sqrt(deg)
+    laplacian = np.eye(sub.shape[0]) - (d_inv_sqrt[:, None] * sub * d_inv_sqrt[None, :])
+    evals = np.linalg.eigvalsh(laplacian)  # ascending; evals[0] ~ 0 (connected)
+    if len(evals) < 3:
+        return False
+    # Degenerate iff the 2nd and 3rd smallest eigenvalues coincide, i.e. the
+    # smallest non-zero eigenvalue has multiplicity > 1.
+    return bool((evals[2] - evals[1]) < tol)