guidepost 0.3.1__tar.gz → 0.3.3__tar.gz

guidepost-0.3.3/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.1 → guidepost-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: guidepost
-Version: 0.3.1
+Version: 0.3.3
 Summary: Guidepost. An overview visualization for understanding supercomputer queue data.
 Home-page: https://github.com/cscully-allison/guidepost
 Author: Connor Scully-Allison
@@ -50,22 +50,13 @@ import pandas as pd
 gp = Guidepost()
 gp.load_data(pd.read_parquet("data/jobs_data.parquet"))
 
-gp.vis_configs = {
-    'x':           'start_time',       # x-axis (numeric or datetime)
-    'y':           'queue_wait',       # y-axis (numeric)
-    'color':       'nodes_requested',  # cell color (numeric)
-    'color_agg':   'avg',              # aggregation for color
-    'categorical': 'user',             # bar chart / filter
-    'facet_by':    'partition'         # splits the data into groups
-}
-
 gp   # display in a notebook cell
 ```
 
 Brush the heatmap or its histograms, then pull the selected rows back into Python:
 
 ```python
-df = gp.retrieve_selected_data()   # or: gp.selection.dataframe
+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).

{guidepost-0.3.1 → guidepost-0.3.3}/README.md

@@ -19,22 +19,13 @@ import pandas as pd
 gp = Guidepost()
 gp.load_data(pd.read_parquet("data/jobs_data.parquet"))
 
-gp.vis_configs = {
-    'x':           'start_time',       # x-axis (numeric or datetime)
-    'y':           'queue_wait',       # y-axis (numeric)
-    'color':       'nodes_requested',  # cell color (numeric)
-    'color_agg':   'avg',              # aggregation for color
-    'categorical': 'user',             # bar chart / filter
-    'facet_by':    'partition'         # splits the data into groups
-}
-
 gp   # display in a notebook cell
 ```
 
 Brush the heatmap or its histograms, then pull the selected rows back into Python:
 
 ```python
-df = gp.retrieve_selected_data()   # or: gp.selection.dataframe
+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).

{guidepost-0.3.1 → guidepost-0.3.3}/guidepost/guidepost.py

@@ -77,6 +77,16 @@ class Guidepost(anywidget.AnyWidget):
         # identifiers the name heuristic misses, or to override an unwanted
         # auto-classification. Mirrors list_columns; pulled before super().
         categorical_columns = kwargs.pop("categorical_columns", None)
+        # Optional override for list-column x-axis ordering, replacing the
+        # built-in node-layout / seriation heuristics — for ordinal-but-not-
+        # hierarchical values the heuristics can't order (e.g. nodes named
+        # "1","2","3"). Either a single callable applied to every list column,
+        # or a {column: callable} dict for per-column control. Each callable is
+        # a full-list transform: it receives the list of distinct category
+        # values and returns them reordered. A callable can't be JSON-synced,
+        # so like list_columns this is a plain Python attribute (not a trait);
+        # it runs in load_data and only its *result* ships to the frontend.
+        sort_by = kwargs.pop("sort_by", None)
         super().__init__(*args, **kwargs)
         self._categorical_columns = set(categorical_columns) if categorical_columns else set()
         self._list_columns = list(list_columns) if list_columns else []
@@ -85,6 +95,20 @@ class Guidepost(anywidget.AnyWidget):
         # before the first load don't fail.
         self._effective_list_columns = list(self._list_columns)
         self._list_delimiter = list_delimiter or ","
+        # Validate up front so a bad sort_by fails at construction, not silently
+        # at render. None | callable | {str: callable} are the only valid shapes.
+        if sort_by is not None:
+            if isinstance(sort_by, dict):
+                bad = [k for k, v in sort_by.items() if not callable(v)]
+                if bad:
+                    raise TypeError(
+                        "sort_by dict values must be callables; non-callable "
+                        f"value(s) for column(s): {bad}")
+            elif not callable(sort_by):
+                raise TypeError(
+                    "sort_by must be a callable or a {column: callable} dict, "
+                    f"got {type(sort_by).__name__}")
+        self._sort_by = sort_by
         # DuckDB-backed aggregator. Lazily created when the first DataFrame
         # is loaded — keeping it None until then so widgets constructed
         # without data don't pay the import/registration cost.
@@ -194,7 +218,8 @@ class Guidepost(anywidget.AnyWidget):
         # that retains every node); arbitrary categories fall back to spectral
         # seriation (ships `category_score` for the column cap). Both share
         # `category_order` for the kept/ordered sequence.
-        ordering = compute_category_ordering(o_df, self._effective_list_columns)
+        ordering = compute_category_ordering(
+            o_df, self._effective_list_columns, sort_overrides=self._sort_by)
         for col, info in ordering.items():
             if col not in summary_stats:
                 continue

{guidepost-0.3.1 → guidepost-0.3.3}/guidepost/seriation.py

@@ -15,31 +15,84 @@ Both derive from the same node x node co-occurrence matrix. sklearn/scipy are
 imported lazily so the cost is only paid when a list column is present.
 """
 
+import warnings
+
 import numpy as np
 
 from .node_layout import compute_node_layout
 
 
-def compute_category_ordering(o_df, list_columns):
-    """Dispatch ordering per list column: prefer structure-aware node-name
-    layout, fall back to spectral co-occurrence seriation.
+def _resolve_override(sort_overrides, col):
+    """Resolve the user sort override applicable to *col*, if any. A bare
+    callable applies to every column; a dict maps column name -> callable."""
+    if sort_overrides is None:
+        return None
+    if callable(sort_overrides):
+        return sort_overrides
+    if isinstance(sort_overrides, dict):
+        return sort_overrides.get(col)
+    return None
+
+
+def _apply_override(fn, names):
+    """Run a user override (full-list transform) over the distinct category
+    names, coercing the result to the String() keys the frontend uses. Raises
+    on a non-iterable return so the caller can fall back to the heuristics."""
+    ordered = fn(list(names))
+    return [str(k) for k in ordered]
+
 
-    Returns ``{col: info}`` where *info* is either the structured shape
-    ``{"order", "hierarchy", "levels"}`` (node names follow a hardware-layout
-    convention) or the seriation shape ``{"order", "score"}`` (arbitrary
-    categories). The frontend treats both uniformly via ``category_order`` and
-    branches on the presence of ``category_hierarchy``.
+def compute_category_ordering(o_df, list_columns, sort_overrides=None):
+    """Dispatch ordering per list column: a user override (if provided) wins,
+    else prefer structure-aware node-name layout, else fall back to spectral
+    co-occurrence seriation.
+
+    Returns ``{col: info}`` where *info* is one of:
+    - ``{"order"}`` — a user ``sort_overrides`` transform for this column,
+    - ``{"order", "hierarchy", "levels"}`` — node names follow a hardware-layout
+      convention, or
+    - ``{"order", "score"}`` — arbitrary categories (seriation).
+    The frontend treats all three uniformly via ``category_order`` and branches
+    on the presence of ``category_hierarchy``.
+
+    *sort_overrides* is ``None``, a single callable applied to every list
+    column, or a ``{column: callable}`` dict. Each callable receives the list
+    of distinct category values and returns them reordered. A callable that
+    raises (or returns a non-iterable) falls back to the heuristics for that
+    column with a warning, so a bad override never aborts data loading.
     """
     if not list_columns:
         return {}
 
+    # Warn on dict keys that don't name a list column (typo / out of scope):
+    # they'd otherwise be silently ignored.
+    if isinstance(sort_overrides, dict):
+        unknown = [c for c in sort_overrides if c not in list_columns]
+        if unknown:
+            warnings.warn(
+                "sort_by names column(s) that are not list columns and will be "
+                f"ignored: {unknown}. Custom sort applies to list columns only.")
+
     out = {}
     fallback_cols = []
     for col in list_columns:
         if col not in o_df.columns:
             continue
         names = _distinct_node_names(o_df[col])
-        layout = compute_node_layout(names) if names else None
+        if not names:
+            continue
+
+        override = _resolve_override(sort_overrides, col)
+        if override is not None:
+            try:
+                out[col] = {"order": _apply_override(override, names)}
+                continue
+            except Exception as exc:  # noqa: BLE001 - fall back, never abort load
+                warnings.warn(
+                    f"sort_by override for column '{col}' raised {exc!r}; "
+                    "falling back to the default ordering heuristic.")
+
+        layout = compute_node_layout(names)
         if layout is not None:
             out[col] = layout
         else:
@@ -167,11 +220,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)