@scope-profiler/plotly 0.1.0 → 0.1.1

package/README.md

@@ -4,6 +4,12 @@ Pure, framework-neutral Plotly figure builders for JSON written by
 `scope-profiler export plot-data --format json`. The package does not import
 Plotly; applications choose their own Plotly bundle.
 
+Install the builder and a Plotly bundle:
+
+```sh
+npm install @scope-profiler/plotly plotly.js-dist-min
+```
+
 ```js
 import Plotly from "plotly.js-dist-min";
 import { buildGanttFigure, renderFigure } from "@scope-profiler/plotly";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scope-profiler/plotly",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Framework-neutral Plotly figure builders for scope-profiler plot-data JSON.",
   "license": "MIT",
   "repository": {

package/src/index.d.ts

@@ -5,4 +5,8 @@ export function buildGanttFigure(payload: object, options?: BuildOptions): Figur
 export function buildFlameFigure(payload: object, options?: BuildOptions): Figure;
 export function buildDurationsFigure(payload: object, options?: BuildOptions): Figure;
 export function buildSpeedupFigure(payload: object, options?: BuildOptions): Figure;
+export function buildDurationTimeseriesFigure(payload: object, options?: BuildOptions): Figure;
+export function buildHistogramFigure(payload: object, options?: BuildOptions): Figure;
+export function buildRankHeatmapFigure(payload: object, options?: BuildOptions & { valueKey?: string; colorscale?: string }): Figure;
+export function buildImbalanceFigure(payload: object, options?: BuildOptions): Figure;
 export function renderFigure(plotly: PlotlyLike, element: Element | string, figure: Figure, config?: object): unknown;

package/src/index.js

@@ -20,8 +20,23 @@ function values(payload, key) {
 
 function baseLayout(overrides = {}) {
   return {
-    paper_bgcolor: "transparent", plot_bgcolor: "transparent", font: { family: "system-ui, sans-serif" },
-    margin: { l: 100, r: 24, t: 32, b: 56 }, legend: { orientation: "h" }, ...overrides,
+    paper_bgcolor: "transparent", plot_bgcolor: "transparent",
+    font: { family: "Inter, ui-sans-serif, system-ui, sans-serif", size: 12 },
+    hovermode: "closest", hoverlabel: { namelength: -1 },
+    margin: { l: 100, r: 24, t: 32, b: 64 },
+    legend: { orientation: "h", y: -0.2, x: 0 }, ...overrides,
+  };
+}
+
+function axis(overrides = {}) {
+  return { automargin: true, gridcolor: "rgba(128, 128, 128, 0.2)", zeroline: false, ...overrides };
+}
+
+function withEmptyState(layout, hasData) {
+  if (hasData) return layout;
+  return {
+    ...layout,
+    annotations: [{ text: "No data to display.", showarrow: false, xref: "paper", yref: "paper", x: 0.5, y: 0.5 }],
   };
 }
 
@@ -40,12 +55,13 @@ export function buildGanttFigure(payload, options = {}) {
     return { type: "bar", orientation: "h", name: region,
       y: rows.map((row) => `${row.file ?? "run"} / rank ${row.rank ?? 0}`),
       x: rows.map((row) => row.end_seconds - row.start_seconds), base: rows.map((row) => row.start_seconds),
-      marker: { color: colors.get(region) },
+      marker: { color: colors.get(region), line: { color: "rgba(0, 0, 0, 0.28)", width: 0.5 } },
       customdata: rows.map((row) => [row.file, row.rank]),
       hovertemplate: `<b>${region}</b><br>%{customdata[0]} / rank %{customdata[1]}<br>start: %{base:.6g} s<br>duration: %{x:.6g} s<extra></extra>`,
     };
   });
-  return { data, layout: baseLayout({ barmode: "overlay", height: Math.max(280, 48 * lanes.length + 150), xaxis: { title: "Time (s)" }, yaxis: { categoryorder: "array", categoryarray: lanes, autorange: "reversed" }, ...options.layout }) };
+  const layout = baseLayout({ barmode: "overlay", height: Math.max(280, 48 * lanes.length + 150), showlegend: regions.length > 1, xaxis: axis({ title: "Time (s)" }), yaxis: axis({ categoryorder: "array", categoryarray: lanes, autorange: "reversed", showgrid: false }), ...options.layout });
+  return { data, layout: withEmptyState(layout, intervals.length > 0) };
 }
 
 /** Build an icicle flame chart using scope-profiler's explicit call IDs. */
@@ -64,7 +80,8 @@ export function buildFlameFigure(payload, options = {}) {
     markerColors.push(colors.get(call.region));
     hovertext.push(`<b>${call.region}</b><br>${call.file ?? "run"} / rank ${call.rank ?? 0}<br>start: ${call.start_seconds.toPrecision(6)} s<br>inclusive: ${(call.inclusive_duration_seconds ?? call.end_seconds - call.start_seconds).toPrecision(6)} s`);
   }
-  return { data: [{ type: "icicle", ids, labels, parents, values: [rootDuration, ...calls.map((call) => call.inclusive_duration_seconds ?? call.end_seconds - call.start_seconds)], branchvalues: "total", tiling: { orientation: "h" }, marker: { colors: markerColors }, hovertext, hoverinfo: "text" }], layout: baseLayout({ height: 500, margin: { l: 24, r: 24, t: 24, b: 24 }, ...options.layout }) };
+  const layout = baseLayout({ height: 500, margin: { l: 24, r: 24, t: 24, b: 24 }, ...options.layout });
+  return { data: [{ type: "icicle", ids, labels, parents, values: [rootDuration, ...calls.map((call) => call.inclusive_duration_seconds ?? call.end_seconds - call.start_seconds)], branchvalues: "total", tiling: { orientation: "h" }, marker: { colors: markerColors, line: { color: "rgba(255, 255, 255, 0.55)", width: 1 } }, hovertext, hoverinfo: "text" }], layout: withEmptyState(layout, calls.length > 0) };
 }
 
 export function buildDurationsFigure(payload, options = {}) {
@@ -79,9 +96,10 @@ export function buildDurationsFigure(payload, options = {}) {
   const data = groups.map((group) => {
     const rows = bars.filter((bar) => (stacked ? bar.segment : bar.rank == null ? bar.file : `rank ${bar.rank}`) === group);
     const byRegion = new Map(rows.map((bar) => [bar.region, bar.value_seconds]));
-    return { type: "bar", name: group, x: regions, y: regions.map((region) => byRegion.get(region) ?? null), marker: { color: colors.get(group) }, hovertemplate: `<b>%{x}</b><br>${group}: %{y:.6g} s<extra></extra>` };
+    return { type: "bar", name: group, x: regions, y: regions.map((region) => byRegion.get(region) ?? null), marker: { color: colors.get(group), line: { color: "rgba(0, 0, 0, 0.22)", width: 0.5 } }, hovertemplate: `<b>%{x}</b><br>${group}: %{y:.6g} s<extra></extra>` };
   });
-  return { data, layout: baseLayout({ barmode: stacked ? "stack" : "group", height: Math.max(360, 34 * regions.length + 180), xaxis: { tickangle: -35 }, yaxis: { title: `${metric} duration (s)` }, ...options.layout }) };
+  const layout = baseLayout({ barmode: stacked ? "stack" : "group", height: Math.max(360, 34 * regions.length + 180), showlegend: groups.length > 1, xaxis: axis({ tickangle: -35 }), yaxis: axis({ title: `${metric} duration (s)` }), ...options.layout });
+  return { data, layout: withEmptyState(layout, bars.length > 0) };
 }
 
 export function buildSpeedupFigure(payload, options = {}) {
@@ -91,10 +109,67 @@ export function buildSpeedupFigure(payload, options = {}) {
   const colors = colorMap(regions, options.colors ?? payload.colors);
   const xValues = [...new Set(points.map((point) => point[xField]))].sort((a, b) => typeof a === "number" && typeof b === "number" ? a - b : String(a).localeCompare(String(b)));
   const numeric = xValues.every((value) => typeof value === "number");
-  const data = regions.map((region) => { const rows = points.filter((point) => point.region === region).sort((a, b) => xValues.indexOf(a[xField]) - xValues.indexOf(b[xField])); return { type: "scatter", mode: "lines+markers", name: region, x: rows.map((row) => row[xField]), y: rows.map((row) => row.speedup), line: { color: colors.get(region) }, marker: { color: colors.get(region) }, hovertemplate: `<b>%{x}</b><br>${region}: %{y:.3g}×<extra></extra>` }; });
+  const data = regions.map((region) => { const rows = points.filter((point) => point.region === region).sort((a, b) => xValues.indexOf(a[xField]) - xValues.indexOf(b[xField])); return { type: "scatter", mode: "lines+markers", name: region, x: rows.map((row) => row[xField]), y: rows.map((row) => row.speedup), line: { color: colors.get(region), width: 2.4 }, marker: { color: colors.get(region), size: 7 }, hovertemplate: `<b>%{x}</b><br>${region}: %{y:.3g}×<extra></extra>` }; });
   const baseline = payload.options?.baseline ?? xValues[0];
   if (numeric && options.ideal !== false) data.push({ type: "scatter", mode: "lines", name: "Ideal speedup", x: xValues, y: xValues.map((value) => value / baseline), line: { color: "#777", dash: "dash" }, hoverinfo: "skip" });
-  return { data, layout: baseLayout({ height: 420, xaxis: { title: payload.options?.x_label ?? xField, tickvals: xValues }, yaxis: { title: "Speedup" }, ...options.layout }) };
+  const layout = baseLayout({ height: 420, showlegend: data.length > 1, xaxis: axis({ title: payload.options?.x_label ?? xField, tickvals: xValues }), yaxis: axis({ title: "Speedup", rangemode: "tozero" }), ...options.layout });
+  return { data, layout: withEmptyState(layout, points.length > 0) };
+}
+
+/** Build mean call duration over time, one trace per region. */
+export function buildDurationTimeseriesFigure(payload, options = {}) {
+  const points = filtered(values(payload, "points"), options);
+  const regions = [...new Set(points.map((point) => point.region))];
+  const colors = colorMap(regions, options.colors ?? payload.colors);
+  const data = regions.map((region) => {
+    const rows = points.filter((point) => point.region === region).sort((a, b) => a.time_seconds - b.time_seconds);
+    return { type: "scatter", mode: "lines+markers", name: region, x: rows.map((row) => row.time_seconds), y: rows.map((row) => row.mean_duration_seconds), line: { color: colors.get(region), width: 2.2 }, marker: { color: colors.get(region), size: 5 }, customdata: rows.map((row) => [row.min_duration_seconds, row.max_duration_seconds, row.call_index]), hovertemplate: `<b>${region}</b><br>time: %{x:.6g} s<br>mean: %{y:.6g} s<br>min–max: %{customdata[0]:.4g}–%{customdata[1]:.4g} s<extra></extra>` };
+  });
+  const layout = baseLayout({ height: 420, showlegend: regions.length > 1, xaxis: axis({ title: "Time (s)" }), yaxis: axis({ title: "Mean call duration (s)" }), ...options.layout });
+  return { data, layout: withEmptyState(layout, points.length > 0) };
+}
+
+/** Build duration distributions from histogram bin records. */
+export function buildHistogramFigure(payload, options = {}) {
+  const bins = filtered(values(payload, "bins"), options);
+  const regions = [...new Set(bins.map((bin) => bin.region))];
+  const colors = colorMap(regions, options.colors ?? payload.colors);
+  const data = regions.map((region) => {
+    const rows = bins.filter((bin) => bin.region === region).sort((a, b) => a.bin_center_seconds - b.bin_center_seconds);
+    return { type: "bar", name: region, x: rows.map((bin) => bin.bin_center_seconds), y: rows.map((bin) => bin.count), width: rows.map((bin) => bin.bin_high_seconds - bin.bin_low_seconds), marker: { color: colors.get(region), line: { color: "rgba(0, 0, 0, 0.2)", width: 0.5 } }, hovertemplate: `<b>${region}</b><br>%{x:.6g} s: %{y} calls<extra></extra>` };
+  });
+  const layout = baseLayout({ barmode: "overlay", height: 400, showlegend: regions.length > 1, xaxis: axis({ title: "Call duration (s)" }), yaxis: axis({ title: "Calls" }), ...options.layout });
+  return { data, layout: withEmptyState(layout, bins.length > 0) };
+}
+
+/** Build a rank × region heatmap from duration records. */
+export function buildRankHeatmapFigure(payload, options = {}) {
+  const points = filtered(values(payload, "points"), options);
+  const regions = [...new Set(points.map((point) => point.region))];
+  const ranks = [...new Set(points.map((point) => point.rank))].sort((a, b) => a - b);
+  const inferredValueKey = points[0] ? Object.keys(points[0]).find((key) => key.endsWith("_duration_seconds")) : undefined;
+  const valueKey = options.valueKey ?? inferredValueKey ?? "total_duration_seconds";
+  const byCell = new Map(points.map((point) => [`${point.rank}:${point.region}`, point[valueKey]]));
+  const data = [{ type: "heatmap", x: regions, y: ranks.map(String), z: ranks.map((rank) => regions.map((region) => byCell.get(`${rank}:${region}`) ?? null)), colorscale: options.colorscale ?? "Viridis", colorbar: { title: "Seconds" }, hovertemplate: "rank %{y}<br>%{x}: %{z:.6g} s<extra></extra>" }];
+  const layout = baseLayout({ height: Math.max(320, 44 * ranks.length + 150), xaxis: axis({ title: "Region" }), yaxis: axis({ title: "Rank", autorange: "reversed", showgrid: false }), ...options.layout });
+  return { data, layout: withEmptyState(layout, points.length > 0) };
+}
+
+/** Build per-rank duration lines, with a dashed rank mean for each region. */
+export function buildImbalanceFigure(payload, options = {}) {
+  const points = filtered(values(payload, "points"), options);
+  const regions = [...new Set(points.map((point) => point.region))];
+  const colors = colorMap(regions, options.colors ?? payload.colors);
+  const data = regions.flatMap((region) => {
+    const rows = points.filter((point) => point.region === region).sort((a, b) => a.rank - b.rank);
+    const color = colors.get(region);
+    return [
+      { type: "scatter", mode: "lines+markers", name: region, x: rows.map((row) => row.rank), y: rows.map((row) => row.value_seconds), line: { color, width: 2.2 }, marker: { color, size: 7 }, hovertemplate: `<b>${region}</b><br>rank %{x}: %{y:.6g} s<extra></extra>` },
+      { type: "scatter", mode: "lines", name: `${region} mean`, x: rows.map((row) => row.rank), y: rows.map((row) => row.mean_over_ranks_seconds), line: { color, dash: "dot", width: 1.3 }, hoverinfo: "skip", showlegend: false },
+    ];
+  });
+  const layout = baseLayout({ height: 420, showlegend: regions.length > 1, xaxis: axis({ title: "Rank", dtick: 1 }), yaxis: axis({ title: `${payload.metric ?? "Duration"} (s)` }), ...options.layout });
+  return { data, layout: withEmptyState(layout, points.length > 0) };
 }
 
 /** Render a figure with any Plotly-compatible bundle. */