@qe-libs/qeviz 0.6.1 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -205,6 +205,53 @@ The `<qe-visual>` and `<qe-graph>` elements can be used directly in any HTML pag
205
205
  </script>
206
206
  ```
207
207
 
208
+ On [qe-libs.org/npm/qe-libs-qeviz/](https://qe-libs.org/npm/qe-libs-qeviz/)
209
+ the `js run` examples have a **Run** button and draw under the example;
210
+ `demo.show(element)` puts an element there and exists only on that page. This
211
+ one fits an ENA model in the browser with
212
+ [`@qe-libs/rena-wasm`](https://qe-libs.org/npm/qe-libs-rena-wasm/) (WebAssembly)
213
+ on its demo copy of rENA's `RS.data`, and plots it:
214
+
215
+ ```js run
216
+ import '@qe-libs/qeviz'; // defines <qe-visual>, <qe-graph>, ...
217
+ import loadENA from '@qe-libs/rena-wasm';
218
+
219
+ const ena = await loadENA();
220
+ const rows = await demo.csv('@qe-libs/rena-wasm/demo/RS.csv');
221
+ const m = ena.fit(rows, {
222
+ codes: ['Data', 'Technical.Constraints', 'Performance.Parameters',
223
+ 'Client.and.Consultant.Requests', 'Design.Reasoning', 'Collaboration'],
224
+ units: ['Condition', 'UserName'], conversations: ['Condition', 'GroupName'], window: 4,
225
+ });
226
+
227
+ // rena-wasm model → ModelData (as qeviz.from_ena does in Python)
228
+ const frame = data => ({ data, types: Object.fromEntries(Object.entries(data[0])
229
+ .map(([k, v]) => [k, typeof v === 'number' ? 'numeric' : 'character'])) });
230
+ const d = m.dims, nc = m.nConnections, units = m.model.unitLabels;
231
+ const condition = u => u.split('__')[0];
232
+ const cols = m.connectionNames.map(n => n.replace(' & ', '.'));
233
+ const model = {
234
+ nodes: frame(m.rotation.codes.map((code, i) =>
235
+ ({ code, x: m.rotation.nodes[i * d], y: m.rotation.nodes[i * d + 1] }))),
236
+ points: frame(units.map((unit, i) =>
237
+ ({ unit, x: m.points[i * d], y: m.points[i * d + 1], Condition: condition(unit) }))),
238
+ edges: frame(units.map((unit, i) => Object.fromEntries([['unit', unit],
239
+ ...cols.map((c, j) => [c, m.lineWeights[i * nc + j]]), ['Condition', condition(unit)]]))),
240
+ id_col: 'unit', node_id_col: 'code', group_col: 'Condition',
241
+ };
242
+
243
+ const vis = document.createElement('qe-visual');
244
+ vis.innerHTML = `
245
+ <qe-graph width="100%" height="440">
246
+ <qe-nodes label="on"></qe-nodes>
247
+ <qe-means confidence label="on"></qe-means>
248
+ <qe-points></qe-points>
249
+ <qe-edges group="FirstGame" also="SecondGame"></qe-edges>
250
+ <qe-axes x y></qe-axes>
251
+ </qe-graph>`;
252
+ demo.show(vis).setModelData(model);
253
+ ```
254
+
208
255
  By default, all marks (nodes, mean markers, unit dots) size in graph-coordinate
209
256
  units and scale with the data extent and wheel-zoom. Add `fixed-size` to
210
257
  `<qe-points>` or `<qe-means>` to keep those markers a constant on-screen pixel
@@ -243,6 +290,13 @@ and the plot size) at any zoom level, as webENA's sigma plots do:
243
290
  lengths.
244
291
  - `<qe-axes fixed-size>`: the axis lines and axis labels keep their zoom-1
245
292
  size on screen.
293
+ - `<qe-means interval-width="1" interval-dash="10 10 5 10" outlier-dash="5 1">`:
294
+ interval lines (CI boxes, crosshairs, outlier boxes) at a fixed on-screen
295
+ width and dash pattern, in CSS px, at any plot size or zoom; `interval-dash`
296
+ styles the CI marks and `outlier-dash` the outlier boxes. Without a dash
297
+ attribute a mark keeps its own pattern in proportion to the width. With
298
+ `intervals="both"` (box and crosshairs) this reproduces webENA's original
299
+ confidence intervals.
246
300
 
247
301
  Labels sized with `label-font-size` (CSS px) are constant on screen at any
248
302
  zoom already; without it they scale with the plot. Trajectory strokes still
@@ -321,6 +375,23 @@ vis.setModelData({
321
375
  // <qe-graph><qe-nodes></qe-nodes><qe-edges network="n1"></qe-edges></qe-graph>
322
376
  ```
323
377
 
378
+ Runnable:
379
+
380
+ ```js run
381
+ import '@qe-libs/qeviz';
382
+
383
+ const vis = document.createElement('qe-visual');
384
+ vis.innerHTML = `<qe-graph width="100%" height="320">
385
+ <qe-nodes label="on"></qe-nodes><qe-edges network="n1"></qe-edges></qe-graph>`;
386
+ demo.show(vis).setModelData({
387
+ nodes: { data: [{ code: "A", x: 0.9, y: 0.3 }, { code: "B", x: -0.6, y: 0.8 },
388
+ { code: "C", x: -0.2, y: -0.9 }],
389
+ types: { code: "character" } },
390
+ networks: { data: [{ name: "n1", "A.B": 0.8, "A.C": 0.3, "B.C": -0.5 }],
391
+ types: { name: "character" } },
392
+ });
393
+ ```
394
+
324
395
  With the default `color-scale="model"`, the colour range comes from the `edges`
325
396
  frame when the model has one, and otherwise from every row of `networks`.
326
397
 
@@ -358,6 +429,23 @@ radius (as webENA's sigma plots do), so the self weight only sets its colour;
358
429
  a number is that fraction of the node radius. Without it the dot is sized by
359
430
  its weight.
360
431
 
432
+ Single edges and nodes in their own colour, e.g. to highlight a selection:
433
+
434
+ ```html
435
+ <qe-nodes>
436
+ <qe-node node="Data" color="#EE9621"></qe-node>
437
+ </qe-nodes>
438
+ <qe-edges network="n1">
439
+ <qe-edge source="Data" target="Design" color="#EE9621"></qe-edge>
440
+ </qe-edges>
441
+ ```
442
+
443
+ Only the edges and nodes that differ need a child. A `<qe-edge>` colour is
444
+ drawn exactly as given, in place of the layer's `colors` and weight ramps; in
445
+ an undirected model either order of `source` / `target` matches, in a directed
446
+ one only source → target. A `<qe-node>` colours its node and its label.
447
+ Adding, changing or removing a child redraws the plot.
448
+
361
449
  Pixel sizes (`size`, like `label-font-size`) are converted against the range,
362
450
  so with the default `view-padding` they come out at size ÷ 1.2.
363
451
 
@@ -490,10 +578,57 @@ graph.toSVG(); // standalone SVG string
490
578
  await graph.toPNG(2); // PNG data URL (2× resolution)
491
579
  ```
492
580
 
581
+ ### Static SVG without a browser
582
+
583
+ `renderSVG()` draws the plot a `<qe-graph>` and its layer elements would draw
584
+ for a model, as a standalone SVG string, with no `window`, `document` or
585
+ `customElements`: qeviz brings its own browser-free element tree. It runs in
586
+ Node and Cloudflare Workers (nothing Node-specific is used), so a server, a
587
+ CLI or a language adapter can export the same plot the web component shows,
588
+ without jsdom or a headless browser.
589
+
590
+ ```js
591
+ import { renderSVG } from '@qe-libs/qeviz';
592
+
593
+ const svg = renderSVG(modelData, {
594
+ width: 600, height: 600, // CSS px; default 600 × width
595
+ graph: { 'edge-width': 0.04, 'plot-title': 'FirstGame' }, // <qe-graph> attributes
596
+ layers: [ // child elements, in markup order
597
+ 'qe-nodes',
598
+ ['qe-means', { confidence: true, label: 'on' }],
599
+ ['qe-points', { label: 'auto' }],
600
+ ['qe-edges', { group: 'FirstGame', also: 'SecondGame' }],
601
+ ['qe-axes', { x: true, y: true }],
602
+ ],
603
+ });
604
+ ```
605
+
606
+ A layer is a tag name, or `[tag, attributes]`; an attribute of `true` is a bare
607
+ attribute (`<qe-means confidence>`), `false` / `null` leaves it out, and other
608
+ values are stringified. The result is the same SVG the browser produces for the
609
+ same markup and `setModelData()` call (checked element by element against
610
+ jsdom by `tools/headless-parity/check.mjs`), with the plot's `width` / `height`
611
+ on the root. Pixel-sized settings (`label-font-size`, `fixed-size`, `size`
612
+ columns) are converted at the given `width`.
613
+
614
+ Two things a browser does that a headless render cannot: measure text, and
615
+ animate. Label boxes are estimated from the font size and text length (an
616
+ average sans-serif glyph is 0.6 em wide), so a label that a browser nudges
617
+ inside the plot is nudged by that estimate instead. `animate`, events,
618
+ tooltips and zoom / pan do not exist headless; the output is the final frame at
619
+ zoom 1.
620
+
621
+ `renderHeadless(modelData, options)` returns the (unconnected) `<qe-graph>`
622
+ element itself instead of the string, for the resolved plot data (`getNodes()`,
623
+ `getEdges()`, `getPoints()`) or `toSVG()`. In a browser, use the element and
624
+ `toSVG()` instead; `renderSVG` is for environments without a DOM.
625
+
493
626
  ### Selection / highlight
494
627
 
495
628
  Drive selection styling from the host without touching qeviz's internal DOM. The
496
- highlight is an overlay that survives model updates and follows zoom and pan:
629
+ highlight is an overlay (rings and a glow line) that survives model updates and
630
+ follows zoom and pan; to colour the marks themselves instead, use `<qe-edge>` /
631
+ `<qe-node>` children (above):
497
632
 
498
633
  ```js
499
634
  graph.setHighlight({ edges: [{ source: "Data", target: "Design" }], nodes: ["Data"] });