guidepost 0.3.2__tar.gz → 0.3.3__tar.gz

{guidepost-0.3.2/guidepost.egg-info → guidepost-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: guidepost
-Version: 0.3.2
+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

{guidepost-0.3.2 → 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.2 → 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.
-
-    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 _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]
+
+
+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:

{guidepost-0.3.2 → guidepost-0.3.3}/guidepost/static/guidepost.js

@@ -16630,15 +16630,23 @@ var JSModel = class {
     return data;
   }
   /**
-   * Sanitizes data for log scale by replacing zero values with one.
+   * Sanitizes data for a log scale by clamping any value below the log floor
+   * up to the floor. A log axis starts at `log_values_floor`, so a value in
+   * [0, floor) can't be placed on it — binValues would drop it entirely (no
+   * bin matches `val < thresholds[0]`), silently losing real records (e.g.
+   * sub-1-Wh energy for standby/short jobs). Clamping puts them in bin 0 so
+   * cells, the right histogram, the count strip and brush/pin selection all
+   * agree. null/NaN are guarded (note `null < 1` is true in JS) so genuine
+   * missing values stay unbinned rather than masquerading as floor values.
    * @param {Array} data - The data to sanitize.
    * @param {string} col - The column to sanitize.
    * @returns {Array} - The sanitized data.
    */
   sanitize_data_for_log(data, col) {
     data.forEach((element, i, arr) => {
-      if (element[col] == 0) {
-        arr[i][col] = 1;
+      const v = element[col];
+      if (v != null && !Number.isNaN(v) && v < this.log_values_floor) {
+        arr[i][col] = this.log_values_floor;
       }
     });
     return data;
@@ -17864,6 +17872,14 @@ var JSModel = class {
    * displayed cells whose column is in col_range (empty = all columns) and
    * whose row is in y_range (empty = all rows). Grouped columns carry
    * lo/hi (node-index overlap); scalar columns are matched by array index.
+   *
+   * A column's `bins` only hold rows with a non-null, in-range y value, so
+   * summing bin indices silently drops null/NaN-y rows — common for e.g.
+   * Failed jobs that never recorded a runtime metric. When the brush spans
+   * the FULL y extent (or sets no y restriction), the user is selecting whole
+   * columns, so use `col.indices` (the column's full membership) to match the
+   * displayed "(N records)" count and column-pin selection. A partial y-brush
+   * still restricts to the covered cells (null-y rows have no cell to brush).
    */
   _band_box_indices(facet) {
     const cols = this.current_detail_columns(facet) || [];
@@ -17871,6 +17887,8 @@ var JSModel = class {
     const yr = this.brushed_ranges[facet].y_range;
     const has_col = cr.length === 2;
     const has_y = yr.length === 2;
+    const nbins = cols[0] && cols[0].bins && cols[0].bins.length || 0;
+    const y_covers_all = !has_y || yr[1] <= 0 && yr[0] >= nbins - 1;
     const ids = /* @__PURE__ */ new Set();
     for (let ci = 0; ci < cols.length; ci++) {
       const col = cols[ci];
@@ -17880,8 +17898,13 @@ var JSModel = class {
         in_col = col.lo != null ? col.lo <= cr[1] && col.hi >= cr[0] : ci >= cr[0] && ci <= cr[1];
       }
       if (!in_col) continue;
+      if (y_covers_all) {
+        const idx = col.indices;
+        if (idx) for (let i = 0; i < idx.length; i++) ids.add(idx[i]);
+        continue;
+      }
       for (let row = 0; row < col.bins.length; row++) {
-        if (has_y && !(row >= yr[1] && row < yr[0])) continue;
+        if (!(row >= yr[1] && row < yr[0])) continue;
         const idx = col.bins[row].indices;
         if (!idx) continue;
         for (let i = 0; i < idx.length; i++) ids.add(idx[i]);
@@ -18626,20 +18649,13 @@ var Heatmap = class {
     let x_offset = X_VARIABLE_OFFSET + OVERVIEW_LAYOUT.outer_margin;
     let y_offset = Y_VARIABLE_OFFSET + OVERVIEW_LAYOUT.outer_margin + TOP_MARGIN;
     let view = this.parent.append("g").attr("class", "heatmap").attr("transform", (d, i) => `translate(${x_offset},${y_offset})`).attr("width", this.width).attr("height", this.height);
+    this.view = view;
     let axis_left = d32.axisLeft().scale(this.scale_y_inverse);
     if (this.model.scale_types[this.facet].y.linear) {
       axis_left.tickFormat(d32.format(".2s"));
     }
     view.append("g").attr("class", "left-axis").call(axis_left).attr("transform", `translate(${OVERVIEW_LAYOUT.inner_padding},${0})`);
-    if (this.x_is_band) {
-      const domain = this.scale_x.domain();
-      const max_labels = 40;
-      const step = Math.max(1, Math.ceil(domain.length / max_labels));
-      const tick_vals = domain.filter((d, i) => i % step === 0);
-      view.append("g").attr("class", "bottom-axis").call(d32.axisBottom(this.scale_x).tickValues(tick_vals)).attr("transform", `translate(${0},${OVERVIEW_LAYOUT.height - OVERVIEW_LAYOUT.inner_padding})`).selectAll("text").attr("text-anchor", "start").attr("transform", "rotate(45)").text((d) => typeof d === "string" && d.length > MAX_NODE_LABEL_CHARS ? d.slice(0, MAX_NODE_LABEL_CHARS) + "\u2026" : d);
-    } else {
-      view.append("g").attr("class", "bottom-axis").call(d32.axisBottom().scale(this.scale_x.scale).ticks(this.scale_x.get_ticks())).attr("transform", `translate(${0},${OVERVIEW_LAYOUT.height - OVERVIEW_LAYOUT.inner_padding})`);
-    }
+    this.draw_x_axis();
     const facet_stats = this.model.feature_summary_stats[this.model.vars.facet_by];
     const synthetic_facet = !!(facet_stats && facet_stats.is_synthetic);
     if (!synthetic_facet) {
@@ -18651,7 +18667,25 @@ var Heatmap = class {
       }
       return this.model.vars.y + "(log)";
     }).attr("text-anchor", "middle").attr("transform", `translate(${-10},${this.height / 2}) rotate(270)`);
-    this.view = view;
+  }
+  /** Draws (or redraws) the bottom x-axis. Idempotent — selects the existing
+   *  `.bottom-axis` group or creates it — so it can be re-called on detail-zoom
+   *  re-renders to keep a grouped/list (band) x-axis in sync with the columns. */
+  draw_x_axis() {
+    let axis_g = this.view.select(".bottom-axis");
+    if (axis_g.empty()) {
+      axis_g = this.view.append("g").attr("class", "bottom-axis");
+    }
+    axis_g.attr("transform", `translate(${0},${OVERVIEW_LAYOUT.height - OVERVIEW_LAYOUT.inner_padding})`);
+    if (this.x_is_band) {
+      const domain = this.scale_x.domain();
+      const max_labels = 40;
+      const step = Math.max(1, Math.ceil(domain.length / max_labels));
+      const tick_vals = domain.filter((d, i) => i % step === 0);
+      axis_g.call(d32.axisBottom(this.scale_x).tickValues(tick_vals)).selectAll("text").attr("text-anchor", "start").attr("transform", "rotate(45)").text((d) => typeof d === "string" && d.length > MAX_NODE_LABEL_CHARS ? d.slice(0, MAX_NODE_LABEL_CHARS) + "\u2026" : d);
+    } else {
+      axis_g.call(d32.axisBottom().scale(this.scale_x.scale).ticks(this.scale_x.get_ticks()));
+    }
   }
   /**
    * Draws sparklines (placeholder function).
@@ -19137,6 +19171,7 @@ var Heatmap = class {
     this.model.detail_range[this.facet] = range;
     this._cols_cache = null;
     this.update_scales();
+    this.draw_x_axis();
     this.render();
   }
   /**
@@ -19611,17 +19646,22 @@ var Heatmap = class {
     const ranges = this.model.brushed_ranges[this.facet];
     if (this.x_is_band) {
       const cr = ranges.col_range, yr2 = ranges.y_range;
+      const has_col = cr.length === 2, has_y = yr2.length === 2;
+      if (!has_col && !has_y) {
+        g.call(this.cell_brush.move, null);
+        return;
+      }
       const cols = this.current_columns();
-      const covered = cr.length === 2 ? cols.filter((c) => c.lo != null ? c.lo <= cr[1] && c.hi >= cr[0] : true) : cols;
-      const idxCovered = cr.length === 2 && cols.length && cols[0].lo == null ? cols.filter((c, i) => i >= cr[0] && i <= cr[1]) : covered;
-      if (yr2.length !== 2 || !idxCovered.length) {
+      const covered = has_col ? cols.filter((c) => c.lo != null ? c.lo <= cr[1] && c.hi >= cr[0] : true) : cols;
+      const idxCovered = has_col && cols.length && cols[0].lo == null ? cols.filter((c, i) => i >= cr[0] && i <= cr[1]) : covered;
+      if (!idxCovered.length) {
         g.call(this.cell_brush.move, null);
         return;
       }
       const cw = this.col_width();
       const px0 = Math.min(...idxCovered.map((c) => this.x_pos(c.threshold)));
       const px1 = Math.max(...idxCovered.map((c) => this.x_pos(c.threshold))) + cw;
-      const py = [this.scale_y_blocks(yr2[0]), this.scale_y_blocks(yr2[1])];
+      const py = has_y ? [this.scale_y_blocks(yr2[0]), this.scale_y_blocks(yr2[1])] : [OVERVIEW_LAYOUT.inner_padding, OVERVIEW_LAYOUT.height - OVERVIEW_LAYOUT.inner_padding];
       g.call(this.cell_brush.move, [[px0, Math.min(...py)], [px1, Math.max(...py)]]);
       return;
     }
@@ -19676,9 +19716,13 @@ var Heatmap = class {
           hi = Math.max(hi, ci);
         }
       }
+      const full_y0 = OVERVIEW_LAYOUT.inner_padding;
+      const full_y1 = OVERVIEW_LAYOUT.height - OVERVIEW_LAYOUT.inner_padding;
+      const tol = this._cell_row_height(cols);
+      const covers_full_y = y0 <= full_y0 + tol && y1 >= full_y1 - tol;
       ranges.x_range = [];
       ranges.col_range = lo !== Infinity ? [lo, hi] : [];
-      ranges.y_range = y_range;
+      ranges.y_range = covers_full_y ? [] : y_range;
     } else {
       const xa = this.scale_x.scale.invert(x0);
       const xb = this.scale_x.scale.invert(x1);