← QE npm index — QE Package Index

@qe-libs/rena-wasm

v0.1.18 · dev 0.1.19-dev.9019 — JavaScript/WebAssembly ENA pipeline — libena (ENA rotations, node positions) compiled to WASM, over @qe-libs/libqe-wasm

Depends on: @qe-libs/libqe-wasm

Install
# 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 →

@qe-libs/rena-wasm

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.


Installation

npm install @qe-libs/rena-wasm

Quick Start

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.

⌘/Ctrl + Enter

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

Rotation Methods

Method`rotation` optionExtra options
SVD (default)`'svd'`—
Means`'mean'``groupA: [unitIdx, ...]`, `groupB: [unitIdx, ...]`
⌘/Ctrl + Enter

Weight Models

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
For ordered (directed) networks the weight is applied to each directed cell, and the default keeps the raw directed counts. weightModel works in fit(), accumulate() and tuneWindowSize().

const model = ena.fit(rows, { codes, units, conversations, window: 4, weightModel: 'sqrt' });

Modeling a Subset of Units

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.


Infinite 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 });

Normalization and Centring

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 });

Projecting Into Another Model (Custom Rotation)

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.


Nodes on a Circle

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
and are spaced 2π/n apart, the longest one fixed; '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.


Reduced-Code Search (PRIA)

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

Accumulation Only

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 });

Advanced: Context Tensor Accumulation

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),
  },
});

Tensor layout

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)

Factor axis roles

OptionMeaning
`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

Time-based windows

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' };

Flexible horizons

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 helper

Express 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

Suggesting Model Parameters and Nested Codes

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:

column name of the nearest codable ancestor (or null). Confidence high. itself a code: A > 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).


Input Format

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.


Testing

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