@qe-libs/qeviz 0.7.0 → 0.8.0
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 +87 -5
- package/dist/qeviz.es.js +2214 -1445
- package/dist/qeviz.es.js.map +1 -1
- package/dist/qeviz.umd.js +5 -5
- package/dist/qeviz.umd.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -122,6 +122,8 @@ model data (checked by the shared fixtures in `tests/golden/`):
|
|
|
122
122
|
| Operation | R | Python | Julia |
|
|
123
123
|
|---|---|---|---|
|
|
124
124
|
| Create | `qe_plot(set, title=, range=, scale_points=, point_scale=, center=, palette=, view_padding=)` | `qeviz.plot(model, title=, range=, ...)` | `qe_plot(model; title=, range=, ...)` |
|
|
125
|
+
| Third dimension (2.5D) | `qe_plot(set, dims = c("SVD1", "SVD2", "SVD3"))`, `qe_model_data(..., z_col=)` | `qeviz.from_ena(model, dims=(0, 1, 2))`, `qeviz.model_data(..., z_col=)` | `model_data(...; z_col=)` |
|
|
126
|
+
| 2.5D view | `qe_3d(p, azimuth=, elevation=, perspective=, edge_perspective=)` | `p.view_3d(azimuth=, ...)` | `qe_3d(p; azimuth=, ...)` |
|
|
125
127
|
| Group means | `qe_group(p, ...)` | `p.group(...)` | `qe_group(p, ...)` |
|
|
126
128
|
| Mean of a subset | `qe_group(p, points=, label=, color=, shape=, intervals=, outlier=)` | `p.group(points=, ...)` | `qe_group(p; points=, ...)` |
|
|
127
129
|
| Edge network | `qe_edges(p, group=, unit=, compare=, also=)` | `p.edges(group=, unit=, ...)` | `qe_edges(p; group=, unit=, ...)` |
|
|
@@ -129,7 +131,8 @@ model data (checked by the shared fixtures in `tests/golden/`):
|
|
|
129
131
|
| Unit points | `qe_points(p)` | `p.points()` | `qe_points(p)` |
|
|
130
132
|
| Point set | `qe_points(p, units=/points=, color=, shape=, labels=, name=)` | `p.points(units=/points=, ...)` | `qe_points(p; units=/points=, ...)` |
|
|
131
133
|
| Nodes | `qe_nodes(p, show, unconnected=, positions=, labels=, sizes=, fixed_size=)` | `p.nodes(show, positions=, labels=, sizes=, fixed_size=)` | `qe_nodes(p; show=, positions=, labels=, sizes=, fixed_size=)` |
|
|
132
|
-
| Axes | `qe_axes(p, x=, y=, fixed_size=)` | `p.axes(x=, y=, fixed_size=)` | `qe_axes(p; x=, y=, fixed_size=)` |
|
|
134
|
+
| Axes | `qe_axes(p, x=, y=, z=, fixed_size=)` | `p.axes(x=, y=, z=, fixed_size=)` | `qe_axes(p; x=, y=, z=, fixed_size=)` |
|
|
135
|
+
| Trajectories | `qe_trajectories(p, units=, smooth=, max_degree=, degree_selection=, playhead=, time_col=, fit_time=, line_style=)` | `p.trajectories(units, smooth=, ...)` | `qe_trajectories(p; units=, smooth=, ...)` |
|
|
133
136
|
| Labels | `qe_labels(p, nodes=, means=, points=, font_size=, font_family=, font_color=, font_weight=)` | `p.labels(...)` | `qe_labels(p; ...)` |
|
|
134
137
|
| Group colours | `qe_colors(p, A = "#hex")` | `p.colors(A="#hex")` | `qe_colors(p, "A" => "#hex")` |
|
|
135
138
|
| Axis range | `qe_range(p, range)` | `p.range(range)` | `qe_range(p, range)` |
|
|
@@ -144,7 +147,7 @@ model data (checked by the shared fixtures in `tests/golden/`):
|
|
|
144
147
|
| `group` | Group name whose **mean** edge network to draw |
|
|
145
148
|
| `unit` | Unit ID for an **individual** network (e.g. `"FirstGame::alice"`). Mutually exclusive with `group`. |
|
|
146
149
|
| `compare` | Second group to subtract (`group − compare`). Positive differences use the primary colour. |
|
|
147
|
-
| `also` |
|
|
150
|
+
| `also` | Same as `compare` (kept for compatibility). Two nodes are joined by one line, so two groups are drawn as their subtraction. |
|
|
148
151
|
| `weights` | A network from data instead of a name: a named vector / Series / Dict of edge weights, an unnamed vector in the model's edge-column order, or a matrix / data frame (averaged over rows). Each call adds a layer. |
|
|
149
152
|
| `colors` | One or two colours (positive, negative); with one, negative weights use its complement. |
|
|
150
153
|
| `threshold` | `min` or `c(min, max)`: \|weight\| < min is not drawn, \|weight\| > max is drawn at max (sign kept). |
|
|
@@ -166,6 +169,14 @@ vector / dict for some of them (`c(nodes = "bold")`, `{"nodes": "bold"}`,
|
|
|
166
169
|
keeps node diameters constant on screen when zoomed. `qe_plot(view_padding =)`
|
|
167
170
|
is how far the view extends beyond `range` (default 1.2; `1` matches it).
|
|
168
171
|
|
|
172
|
+
`qe_trajectories()` draws the rows of the model's trajectories frame (else its
|
|
173
|
+
points) as one path per unit, smoothed by a polynomial with `smooth = "poly"`.
|
|
174
|
+
`time_col` names the column holding each row's time (default: the first of
|
|
175
|
+
`time`, `ActivityNumber`, `RowID`), which `playhead` reads. `fit_time = "time"`
|
|
176
|
+
spaces each unit's points along the curve by that time, so the curve follows
|
|
177
|
+
gaps in time; the default `"index"` spaces them evenly, one step per row. A
|
|
178
|
+
`color` column in the trajectories frame sets each unit's colour.
|
|
179
|
+
|
|
169
180
|
### `qe_axes` / `.axes()` parameters
|
|
170
181
|
|
|
171
182
|
Axes are **opt-in**: a plot draws the x/y axis cross only when `qe_axes()` is in the
|
|
@@ -176,8 +187,9 @@ draws the lines with no labels. Each label is controlled independently:
|
|
|
176
187
|
|---|---|
|
|
177
188
|
| `x` | `FALSE` (default) omits the x-axis label, `TRUE` labels it with its dimension name (e.g. `SVD1`), a string sets custom text. |
|
|
178
189
|
| `y` | Same as `x`, for the y-axis. |
|
|
190
|
+
| `z` | Same as `x`, for the depth axis of a 2.5D plot (`qe_3d()`), whose axes are an x/y/z tripod. |
|
|
179
191
|
| `show` / `show=false` | Suppress the axes entirely. |
|
|
180
|
-
| `fixed_size` | `TRUE` keeps the axis lines
|
|
192
|
+
| `fixed_size` | `TRUE` keeps the axis lines at their zoom-1 on-screen width when the plot is zoomed. Axis labels keep their zoom-1 size either way. |
|
|
181
193
|
|
|
182
194
|
```r
|
|
183
195
|
qe_plot(set) |> qe_edges("FirstGame") |> qe_axes(x = "Task focus", y = TRUE)
|
|
@@ -288,8 +300,16 @@ and the plot size) at any zoom level, as webENA's sigma plots do:
|
|
|
288
300
|
- `<qe-means fixed-size>` also keeps the confidence-interval boxes and
|
|
289
301
|
crosshairs and the outlier boxes at their zoom-1 stroke width and dash
|
|
290
302
|
lengths.
|
|
291
|
-
- `<qe-axes fixed-size>`: the axis lines
|
|
292
|
-
size on
|
|
303
|
+
- `<qe-axes fixed-size>`: the axis lines keep their zoom-1 width on screen.
|
|
304
|
+
Axis titles, like node, mean and point labels, keep their zoom-1 size on
|
|
305
|
+
screen at any zoom without it.
|
|
306
|
+
- `<qe-means interval-width="1" interval-dash="10 10 5 10" outlier-dash="5 1">`:
|
|
307
|
+
interval lines (CI boxes, crosshairs, outlier boxes) at a fixed on-screen
|
|
308
|
+
width and dash pattern, in CSS px, at any plot size or zoom; `interval-dash`
|
|
309
|
+
styles the CI marks and `outlier-dash` the outlier boxes. Without a dash
|
|
310
|
+
attribute a mark keeps its own pattern in proportion to the width. With
|
|
311
|
+
`intervals="both"` (box and crosshairs) this reproduces webENA's original
|
|
312
|
+
confidence intervals.
|
|
293
313
|
|
|
294
314
|
Labels sized with `label-font-size` (CSS px) are constant on screen at any
|
|
295
315
|
zoom already; without it they scale with the plot. Trajectory strokes still
|
|
@@ -453,6 +473,7 @@ DOM. Each event's `detail` also carries the `originalEvent`.
|
|
|
453
473
|
| `qe-edge-click` / `qe-edge-hover` / `qe-edge-unhover` | `{ source, target, weight, directed, self, group?, unit? }` |
|
|
454
474
|
| `qe-node-click` / `qe-node-hover` / `qe-node-unhover` | `{ id, kind: "node" \| "mean" \| "point", name, x, y, group?, unit? }` |
|
|
455
475
|
| `qe-label-move` | `{ id, transform: { x, y } }` — a label was dragged (offset in graph-space units) |
|
|
476
|
+
| `qe-camera-change` | `{ azimuth, elevation }` — the 2.5D view was drag-rotated (see [2.5D projection](#25d-projection-experimental)) |
|
|
456
477
|
|
|
457
478
|
Labels are **draggable** (drag to reposition; the label pins open and stays
|
|
458
479
|
visible), emitting `qe-label-move` on drop so the host can persist the position
|
|
@@ -632,6 +653,67 @@ graph.clearHighlight();
|
|
|
632
653
|
<qe-graph id="primary" plot-group="comparison" …></qe-graph>
|
|
633
654
|
```
|
|
634
655
|
|
|
656
|
+
### 2.5D projection (experimental)
|
|
657
|
+
|
|
658
|
+
With a third dimension (`z_col` in the model data) and `projection="2.5d"`,
|
|
659
|
+
`<qe-graph>` draws the plot in 3D, still as plain SVG (so `toSVG()`, `toPNG()`
|
|
660
|
+
and headless `renderSVG()` keep working). Without a third dimension the
|
|
661
|
+
attribute is ignored and the 2D plot is unchanged.
|
|
662
|
+
|
|
663
|
+
```html
|
|
664
|
+
<qe-graph projection="2.5d" azimuth="35" elevation="22" perspective="3">
|
|
665
|
+
<qe-nodes></qe-nodes><qe-points></qe-points><qe-edges group="A"></qe-edges>
|
|
666
|
+
<qe-axes x="" y="" z=""></qe-axes>
|
|
667
|
+
</qe-graph>
|
|
668
|
+
```
|
|
669
|
+
|
|
670
|
+
| Attribute | Meaning |
|
|
671
|
+
|---|---|
|
|
672
|
+
| `azimuth`, `elevation` | Camera angles in degrees (defaults 35, 22). |
|
|
673
|
+
| `perspective` | Camera distance in scene radii (default 3; smaller is stronger). `none` or `0` = orthographic. |
|
|
674
|
+
| `edge-perspective` | By default an edge's width is its weight × the perspective magnification, so near edges draw wider. `none` keeps width = weight (as in 2D), comparable across depths, while nodes and points keep their perspective size. Edge colour is the same as in 2D at every depth. |
|
|
675
|
+
| `<qe-axes z>` | Label for the depth axis, like `x` / `y` (empty = the dimension name). |
|
|
676
|
+
|
|
677
|
+
From R, Python and Julia, extract the model with a third dimension and add
|
|
678
|
+
`qe_3d()` (`.view_3d()` in Python):
|
|
679
|
+
|
|
680
|
+
```r
|
|
681
|
+
qe_plot(set, dims = c("SVD1", "SVD2", "SVD3")) |>
|
|
682
|
+
qe_edges("FirstGame") |>
|
|
683
|
+
qe_3d(azimuth = 40, elevation = 20) |>
|
|
684
|
+
qe_axes(x = TRUE, y = TRUE, z = TRUE)
|
|
685
|
+
```
|
|
686
|
+
|
|
687
|
+
`qe_3d(perspective = "none")` is orthographic, `edge_perspective = FALSE`
|
|
688
|
+
keeps edge width = weight at every depth, and `qe_3d(show = FALSE)` goes back
|
|
689
|
+
to 2D. Group means get their depth interval from the unit points, and
|
|
690
|
+
`qe_group(points =)`, `qe_points(points =)` and `qe_nodes(positions =)` take
|
|
691
|
+
the depth column by name (or, for unnamed columns, the third numeric one).
|
|
692
|
+
|
|
693
|
+
Dragging the plot rotates it (shift-drag pans; one-finger touch rotates), which
|
|
694
|
+
updates `azimuth` / `elevation` and emits `qe-camera-change`. Every mark
|
|
695
|
+
(nodes, points, means, edges and the x / y / z axis tripod) is drawn in one
|
|
696
|
+
group sorted far → near. Edges are split along their length, undirected lines
|
|
697
|
+
into short segments and directed triangles into slices (the chevron sorted
|
|
698
|
+
on its own), so an edge passes in front of a node where it is nearer and
|
|
699
|
+
behind where it is farther. A directed triangle's split point is placed on
|
|
700
|
+
the 3D edge, and its width follows the perspective along it. Depth cues: perspective size and edge width,
|
|
701
|
+
and nodes and points drawn as opaque balls lit from the upper left (other
|
|
702
|
+
point shapes fade slightly with distance). Edges don't fade: their colour
|
|
703
|
+
encodes weight, so it matches 2D at every depth. Square group means are
|
|
704
|
+
drawn as cubes with their edges along the data axes, so they turn with the
|
|
705
|
+
plot, their faces shaded by the same light.
|
|
706
|
+
|
|
707
|
+
Mean intervals are drawn in data space around the cube: the CI box
|
|
708
|
+
(`confidence` / `intervals="box"`) and outlier box are dashed boxes spanning
|
|
709
|
+
the interval on all three axes, and `crosshairs` are three arms through the
|
|
710
|
+
mean. Their edges are split into pieces that join the far → near sort, so the
|
|
711
|
+
near side of a box passes in front of its cube. When the means come from the
|
|
712
|
+
unit points, the depth interval is computed like the other two; a groups
|
|
713
|
+
frame needs the third dimension's bounds too (`{dim}.low` / `.high`,
|
|
714
|
+
`.olow` / `.ohigh`), and draws no interval without them. Trajectories are not
|
|
715
|
+
yet projected.
|
|
716
|
+
|
|
635
717
|
### Build
|
|
636
718
|
|
|
637
719
|
```sh
|