← QE npm index — QE Package Index
# Add to .npmrc once:
@qe-libs:registry=https://gitlab.com/api/v4/projects/22522458/packages/npm/
# Then install:
npm install @qe-libs/rena-wasm
npm install @qe-libs/rena-wasm@dev # latest dev build
Browse on GitLab Package Registry →
JavaScript/WebAssembly ENA pipeline.
Handles data parsing, unit/conversation grouping, and the full
accumulate → normalize → center → rotate → project → node-positions pipeline.
The math runs in WebAssembly: the ENA model code (rotations, node positions,
window estimation) is libena, rENA's C++ layer, compiled into this package
(dist/libena.*), and generic numerics and accumulation come from
@qe-libs/libqe-wasm.
npm install @qe-libs/rena-wasm
On qe-libs.org/npm/qe-libs-rena-wasm/
the examples marked js run have a Run button: they run in your browser,
on the WebAssembly build, against demo/RS.csv (rENA's RS.data, shipped in
this package without its text column). There, console.log prints under the
example, demo.csv(url) loads a CSV into row objects and demo.plot(model, opts)
draws the model with @qe-libs/qeviz;
demo exists only on that page.
The fitted model:
model.model.centroids // Float64Array nUnits × dims
model.lineWeights // Float64Array nUnits × nConnections (normed)
model.connectionCounts // Float64Array nUnits × nConnections (unit counts, before normalisation)
model.rowConnectionCounts // Float64Array nRows × nConnections (each row's counts after binarize / weight; rows sum to connectionCounts)
model.points // Float64Array nUnits × dims (projected positions)
model.rotation.nodes // Float64Array nCodes × dims
model.connectionNames // ['Data & Technical.Constraints', ...]
model.model.unitLabels // ['FirstGame__steven z', ...] — unit column values joined with '__'
model.rotation.columnNames // ['SVD1', 'SVD2']
// Per-unit helpers
model.centroid('FirstGame__steven z') // number[] length = dims
model.network('FirstGame__steven z') // number[] length = nConnections
| Method | `rotation` option | Extra options |
|---|---|---|
| SVD (default) | `'svd'` | — |
| Means | `'mean'` | `groupA: [unitIdx, ...]`, `groupB: [unitIdx, ...]` |
weightModel (= R's weight.by / tma's weight_by) is applied to each line's
co-occurrence counts before they are summed into the unit network, by
libqe's shared finalize_row_connections kernel — the same stage and results
as rENA's ena.accumulate.data() and tma::accumulate().
| `weightModel` | Per line |
|---|---|
| — (default) | binary: each positive count becomes 1 (`binary: false` keeps raw counts) |
| `'product'` | the raw, non-binarized counts |
| `'sqrt'` | square root of each line's count |
| `'log'` (alias `'log1p'`) | `log(1 + x)` of each line's count |
weightModel works in fit(),
accumulate() and tuneWindowSize().
const model = ena.fit(rows, { codes, units, conversations, window: 4, weightModel: 'sqrt' });
unitsUsed (= R's units.used) lists the units to model, as unit keys (the
unit column values joined with __, as in model.unitLabels). Every row
stays in the data: rows of other units still count as context in the modeled
units' windows, but those units get no network and never reach sphere
normalization, centering or rotation. Omit it to model every unit.
// Students' connections to what teachers said are kept; teachers aren't units.
const model = ena.fit(rows, { codes, units: ['Role', 'Name'], conversations,
window: 4, unitsUsed: studentKeys });
unitsUsed works in fit(), accumulate(), tuneWindowSize() and pria().
This differs from dropping the other units' rows, which also removes them from
everyone's windows.
window: Infinity (= R's window.size.back = Inf) connects each line to
every earlier line in its conversation. It also works as a window in a
context tensor.
const model = ena.fit(rows, { codes, units, conversations, window: Infinity });
sphereNorm (default true, = R's norm.by = fun_sphere_norm) scales each
unit's network to length 1. With false (= fun_skip_sphere_norm) every
network is scaled by the longest network's length instead, keeping relative
magnitudes; for ordered (ONA) models this is
ona::model(normalize = skip_sphere_norm). centerAlignToOrigin (default
true, = ena.make.set's center.align.to.origin and rENA model()'s
exclude_zero_networks) leaves zero-network units out of the centring mean
and the node fit, at the origin with a zero centroid; with false the mean is
taken over, and subtracted from, every unit, and every unit is fitted. It
applies to ordered (ONA) models too, as in ONA 0.1.1. Both work in fit() and
pria().
const model = ena.fit(rows, { codes, units, conversations, window: 4,
sphereNorm: false, centerAlignToOrigin: false });
rotationSet (= R's rotation.set in ena.make.set()) projects a model into
another model's space instead of rotating it: the units are centred on the
rotation set's centerVec and projected with its rotationMatrix, and the
nodes are the rotation set's. Pass codes (the rotation set's code order) to
have it reordered to the model's codes; a rotation set built from other codes
is rejected. Centroids use the pinned nodes, so goodness of fit is measured
against the nodes shown. Ordered models keep their own centring, as
rENA.api's ordered pipeline does.
const source = ena.fit(rowsA, { codes, units, conversations, window: 4 });
const model = ena.fit(rowsB, { codes, units, conversations, window: 4,
rotationSet: {
rotationMatrix: source.rotationMatrix, rotationCols: source.dims,
nodes: source.rotation.nodes,
centerVec: source.rotation.centerVec,
codes,
},
});
rotationMatrix and nodes may also be arrays of rows (one per connection
and per code), as R stores them. pria() ignores rotationSet: it cannot
rotate the reduced models.
moveNodesToUnitCircle() (= R's move_nodes_to_unit_circle_with_equal_space()
and move_nodes_to_unit_circle()) is a post-fit display transform: it moves a
fitted model's nodes onto a circle in the plane of two dimensions, with the
radius of the longest node there, and recomputes the centroids for the moved
nodes, so goodness of fit and exports match the plot. Nothing is refit and
the points stay put. Unordered and ordered models.
const model = ena.fit(rows, { codes, units, conversations, window: 4 });
const circle = ena.moveNodesToUnitCircle(model, { dims: [0, 1], mode: 'equal' });
// circle.rotation.nodes, circle.model.centroids: moved; everything else shared
dims — the plane's two 0-based dimensions, x then y (default [0, 1]).mode — 'equal' (default): the nodes keep their order around the origin'radial': each node
moves out along its own ray.
Nodes of length zero in the plane, and the nodes' other dimensions, are left
as they are. It returns a copy and leaves model unchanged: when the plotted
dimensions change, call it again on the fitted model. The math is libena's
move_nodes_to_unit_circle, also on ena.qe.
pria() finds the largest set of codes (up to removeNum, never leaving
fewer than 3) whose removal keeps the model within threshold of the full
model — the same search, gates and tie-break as R's PRIA::pria(). It takes
the same options as fit() (rotation, weightModel, tensor, codeMask,
…), so it scores the model you display.
const { removed, k, variance } = ena.pria(rows, {
codes, units, conversations, window: 4,
rotation: 'mean', groupA, groupB,
removeNum: 3, threshold: 0.95,
});
// removed → code names to drop (most codes first, then highest dim-1 variance)
// variance → dim-1 share of variance in the chosen reduced model
Returns raw (un-normalised) network vectors without running the full pipeline.
const { connectionCounts, rowConnectionCounts, unitLabels, connectionNames, nUnits, nConnections } =
ena.accumulate(rows, { codes, units, conversations, window: 4 });
Context tensors give per-factor-combination control over window sizes and
weights — the JS equivalent of tma::accumulate_contexts() with HOO rules.
The tensor is a multi-dimensional array whose last axis is always size 2 (index 0 = weight, index 1 = window). Earlier axes correspond to factor columns in the data.
// Example: sender role (T=Teacher, S=Student) controls the window size.
// dims = [nRoleValues, 2] → Teacher uses window=4, Student uses window=2.
const model = ena.fit(rows, {
codes, units, conversations,
ordered: true, // directed (n² connections); also works without a tensor.
// Ordered models follow ona::model(): zero-network units stay
// at the origin (centerAlignToOrigin), nodes use directed
// positions, and points/nodes are centred on the origin.
// connectionNames / rotation.adjacencyKey list all n² directed
// connections as R names them: column j*n + i is
// "codes[i] & codes[j]", ground codes[i] → response codes[j].
tensor: {
dims: [2, 2], // [nRoleValues=2, weight/window=2]
dimsSender: [0], // axis 0 is a sender factor
dimsReceiver: [],
dimsMode: [],
factors: ['Role'], // column in the data
// Optional: explicit value → index mapping. Inferred automatically if omitted.
factorLevels: { Role: { 'Teacher': 0, 'Student': 1 } },
// Flat column-major: [weight_T, weight_S, window_T, window_S]
data: Float64Array.of(1, 1, 4, 2),
},
});
The data array is column-major with shape dims. The last axis
selects weight (0) or window (1). For dims = [nA, nB, 2]:
data[a + nA*b + nA*nB*0] → weight for factor combination (a, b)
data[a + nA*b + nA*nB*1] → window for factor combination (a, b)
| Option | Meaning |
|---|---|
| `dimsSender` | These axes use the *ground* row's factor values when looking up the window |
| `dimsReceiver` | These axes use the *response* row's factor values (overrides ground) |
| `dimsMode` | These axes use a shared mode value |
Set timesCol to measure windows in time instead of lines, and timeUnit
('secs' (default), 'mins', 'hours', 'days', 'weeks') to give the tensor's
windows in that unit. Numeric time columns are used as-is; otherwise each
value is parsed as elapsed time (MM:SS, HH:MM:SS) or a date-time, in
seconds, as rENA.api's parse_date does. timesEndCol uses each row's end
time instead: a numeric column is a duration added to the start, anything
else is the end timestamp.
const tensor = { ...modalityTensor, timesCol: 'Timestamp', timeUnit: 'mins' };
horizons gives every unit its own horizon of observation (= tma
contexts() with HOO rules, as rENA.api builds them for flexible horizons).
by is the discriminator column and rules maps each of its values to the
columns that define that value's horizon: a row is in unit U's horizon when
each of those columns holds a value U has. Each horizon is split on the rules'
columns — not on the discriminator, which only picks the rule — and windows
run within each piece. Rows whose discriminator value has no rule are left
out.
const model = ena.fit(rows, {
codes, units, conversations: ['Modality'], tensor,
horizons: { by: 'Modality', rules: { chat: ['GroupName'], log: ['UserName'] } },
});
horizons works in fit(), accumulate(), tuneWindowSize() and pria().
defaultTensor helperExpress simple windowed accumulation as a tensor (IS_DEFAULT path):
import { defaultTensor } from '@qe-libs/rena-wasm/src/tensor.js';
const tensor = defaultTensor(4); // window=4, weight=1
const tensor = defaultTensor(4, 0.5); // window=4, weight=0.5
Two pure-JS helpers, exported synchronously (no loadENA() needed), look at a
parsed table and suggest how to model it.
detectParams(rows) suggests the code, unit and conversation columns:
import { detectParams } from '@qe-libs/rena-wasm';
const r = detectParams(rows);
// r.codes / r.suggestedUnits / r.suggestedConversations / r.groups
// r.recommended / r.confidence / r.reason
detectNesting(rows, codes, opts) (async) suggests nested codes — a code B
that is a subcode of A (B ⊆ A) — so a codebook hierarchy need not be rebuilt by
hand. A code is present on a row when its value is > 0 (missing or NA =
absent). Three signals, strongest first:
opts.codebook is [{ name, parent }], with parent thenull). Confidence high.
<parent><delim><rest> with the parentA > B, A / B, A: B, A - B, A/B, A:B, A.B, A_B
or A (B). Confidence medium.
threshold (default 0.95) over at least minRows (default 5) lines of the
sub, and the parent occurs on at least one row without the sub. Confidence
medium with a matching name, low on its own.
import { detectNesting } from '@qe-libs/rena-wasm';
const { pairs, duplicates, notes } = await detectNesting(rows, codes, {
threshold: 0.95, minRows: 5,
codebook: [{ name: 'Reasoning', parent: null }, { name: 'Reasoning: Causal', parent: 'Reasoning' }],
});
// pairs → [{ sub, parent, confidence: 'high'|'medium'|'low',
// signals: ['codebook'|'name'|'data', ...], lines, withParent,
// alternatives: [{ parent, withParent }], notes: [...] }]
// duplicates → [{ a, b, lines }] codes present on exactly the same rows
// notes → general remarks, e.g. codebook names not among `codes`
The data signal — per-code line counts, co-occurrence, the pairs that reach
the threshold and the duplicates — is libqe's nesting_candidates()
(@qe-libs/libqe-wasm ≥ 0.2.6), loaded on the first call; pass an already
loaded module as opts.qe to reuse it. Nesting is applied to the code matrix
before accumulation, so that step is shared by every model and lives in libqe;
the codebook and name signals, and how they combine, stay here.
One pair per sub, by strongest signal, then highest containment, then the
parent with most rows; other parents that pass the data threshold are listed
as alternatives. lines and withParent are reported for every pair, so a
codebook or name pair whose containment is below threshold still shows the
numbers, with a note. Chains (C under B under A) are flattened to the top-most
ancestor, with a note. Two codes that contain each other are a duplicate, not
a pair, and a code never nests under itself. Pairs are sorted by confidence,
then by the order of codes. The cost is one pass over the rows plus a count
per pair of codes present on a row (20 000 rows x 50 codes in well under a
second).
rows is an array of plain objects — one per utterance/event.
const rows = [
{ UserName: 'Alice', Condition: 'A', GroupName: 'G1', Role: 'Teacher', Data: 1, Reasoning: 0 },
...
];
Code column values should be numeric (0/1 for binary codes). Factor column
values can be any string or number — they are mapped to 0-based indices
automatically unless factorLevels is provided explicitly.
npm install
npm run build # compiles dist/libena.* — needs emscripten (emcc) and conan
npm test
npm run build (scripts/build.sh) vendors the libena and libqe headers into
include/ (../scripts/sync-headers.sh: libena from inst/include, libqe from
Conan), gets Armadillo from Conan, and builds with emcmake.
test/libena.test.js checks that this module and libqe-wasm's own copy of the
ENA functions give identical results.
Tests cover the simple windowed pipeline (test/ena.test.js) and the
context-tensor path (test/tensor.test.js), and check against R: infinite and
time-based windows, flexible horizons and custom rotations
(test/windows-horizons-rotation.test.js), the normalization and centring
options against ena.make.set() (test/norm-center.test.js), and ordered
models with and without sphere normalization against ona::model()
(test/ona-model.test.js, test/ona-sphere-norm.test.js).
Powered by GitLab CI — Package registry — QE Package Index