@qe-libs/qeviz 0.7.1 → 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 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` | Second group to overlay alongside `group`. |
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 and labels at their zoom-1 on-screen size when the plot is zoomed. |
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,9 @@ 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 and axis labels keep their zoom-1
292
- size on screen.
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.
293
306
  - `<qe-means interval-width="1" interval-dash="10 10 5 10" outlier-dash="5 1">`:
294
307
  interval lines (CI boxes, crosshairs, outlier boxes) at a fixed on-screen
295
308
  width and dash pattern, in CSS px, at any plot size or zoom; `interval-dash`
@@ -460,6 +473,7 @@ DOM. Each event's `detail` also carries the `originalEvent`.
460
473
  | `qe-edge-click` / `qe-edge-hover` / `qe-edge-unhover` | `{ source, target, weight, directed, self, group?, unit? }` |
461
474
  | `qe-node-click` / `qe-node-hover` / `qe-node-unhover` | `{ id, kind: "node" \| "mean" \| "point", name, x, y, group?, unit? }` |
462
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)) |
463
477
 
464
478
  Labels are **draggable** (drag to reposition; the label pins open and stays
465
479
  visible), emitting `qe-label-move` on drop so the host can persist the position
@@ -639,6 +653,67 @@ graph.clearHighlight();
639
653
  <qe-graph id="primary" plot-group="comparison" …></qe-graph>
640
654
  ```
641
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
+
642
717
  ### Build
643
718
 
644
719
  ```sh