@qe-libs/rena-wasm 0.1.0

package/README.md

@@ -0,0 +1,164 @@
+# @qe-libs/rena-wasm
+
+JavaScript/WebAssembly ENA pipeline — thin orchestration layer over
+[`@qe-libs/libqe-wasm`](../../libqe/wasm/README.md).
+
+Handles data parsing, unit/conversation grouping, and the full
+accumulate → normalize → center → rotate → project → node-positions pipeline.
+All math is delegated to the libqe WASM module; no C++ compilation required here.
+
+---
+
+## Installation
+
+```bash
+npm install @qe-libs/rena-wasm
+```
+
+---
+
+## Quick Start
+
+```js
+import loadENA from '@qe-libs/rena-wasm';
+
+const ena = await loadENA();
+
+const model = ena.fit(rows, {
+  codes:         ['Data', 'Technical.Constraints', 'Performance.Parameters'],
+  units:         ['UserName', 'Condition'],
+  conversations: ['Condition', 'GroupName'],
+  window:        4,
+  dims:          2,
+});
+
+model.centroids        // Float64Array  nUnits × dims
+model.networks         // Float64Array  nUnits × nConnections (normed)
+model.positions        // Float64Array  nCodes × dims
+model.connectionNames  // ['Data & Technical.Constraints', ...]
+model.unitLabels       // ['UserName1_ConditionA', ...]
+model.columnNames      // ['SVD1', 'SVD2']
+
+// Per-unit helpers
+model.centroid('Alice_A')  // number[]  length = dims
+model.network('Alice_A')   // number[]  length = nConnections
+```
+
+---
+
+## Rotation Methods
+
+| Method | `rotation` option | Extra options |
+|---|---|---|
+| SVD (default) | `'svd'` | — |
+| Means | `'mean'` | `groupA: [unitIdx, ...]`, `groupB: [unitIdx, ...]` |
+
+```js
+// Means rotation — groupA/groupB are unit indices (position in unitLabels)
+const model = ena.fit(rows, {
+  codes, units, conversations,
+  rotation: 'mean',
+  groupA: [0, 1, 2],
+  groupB: [3, 4, 5],
+});
+```
+
+---
+
+## Accumulation Only
+
+Returns raw (un-normalised) network vectors without running the full pipeline.
+
+```js
+const { networks, 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.
+
+```js
+// 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) when using tensors
+  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
+
+| 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 |
+
+### `defaultTensor` helper
+
+Express simple windowed accumulation as a tensor (IS_DEFAULT path):
+
+```js
+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
+```
+
+---
+
+## Input Format
+
+`rows` is an array of plain objects — one per utterance/event.
+
+```js
+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
+
+```bash
+npm install
+npm test
+```
+
+Tests cover the simple windowed pipeline (`test/ena.test.js`) and the
+context-tensor path (`test/tensor.test.js`).

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@qe-libs/rena-wasm",
+  "version": "0.1.0",
+  "description": "JavaScript/WebAssembly ENA pipeline — thin orchestration layer over @qe-libs/libqe-wasm",
+  "main": "src/index.js",
+  "type": "module",
+  "files": [
+    "src/"
+  ],
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/.bin/jest"
+  },
+  "publishConfig": {
+    "registry": "https://gitlab.com/api/v4/projects/22522458/packages/npm/"
+  },
+  "keywords": ["wasm", "ena", "epistemic-network-analysis", "quantitative-ethnography"],
+  "license": "GPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/epistemic-analytics/qe-packages/rENA",
+    "directory": "wasm"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "transform": {},
+    "resolver": "<rootDir>/jest-resolver.cjs"
+  },
+  "dependencies": {
+    "@qe-libs/libqe-wasm": "^0.1.0"
+  },
+  "devDependencies": {
+    "jest": "^29.0.0"
+  }
+}

package/src/data.js

@@ -0,0 +1,96 @@
+/**
+ * data.js — Data parsing and unit/conversation grouping for ENA.
+ *
+ * Converts an array of row objects (e.g. parsed CSV rows) into the flat
+ * Float64Array code matrix and unit/conversation index structures that the
+ * pipeline needs.  Also extracts per-unit metadata (non-code, non-unit,
+ * non-conversation columns), mirroring R's enadata$metadata / set$meta.data.
+ */
+
+/**
+ * Build a composite key from multiple column values.
+ * @param {Object} row
+ * @param {string[]} cols
+ * @returns {string}
+ */
+export function rowKey(row, cols) {
+    return cols.map(c => row[c]).join('__');
+}
+
+/**
+ * Parse tabular data into ENA-ready structures.
+ *
+ * @param {Object[]} rows       - Array of row objects (one per utterance/event)
+ * @param {string[]} codes      - Code column names
+ * @param {string[]} unitCols   - Column(s) that identify a unit (e.g. ['UserName', 'Condition'])
+ * @param {string[]} convoCols  - Column(s) that identify a conversation (e.g. ['Condition', 'GroupName'])
+ *
+ * @returns {{
+ *   codeMatrix:  Float64Array,            // n_rows × n_codes, row-major
+ *   nRows:       number,
+ *   nCodes:      number,
+ *   nUnits:      number,
+ *   unitLabels:  string[],                // unit key for each unit index
+ *   unitOf:      Int32Array,              // unit index for each row
+ *   convoOf:     Int32Array,              // conversation index for each row
+ *   convoGroups: Map<number, number[]>,   // convoIdx → [rowIdx, ...]
+ *   metaData:    Object[],               // one metadata object per unit (first-row representative)
+ *   metaCols:    string[],               // names of metadata columns
+ * }}
+ */
+export function parseData(rows, codes, unitCols, convoCols) {
+    const nRows  = rows.length;
+    const nCodes = codes.length;
+
+    const codeMatrix  = new Float64Array(nRows * nCodes);
+    const unitOf      = new Int32Array(nRows);
+    const convoOf     = new Int32Array(nRows);
+
+    const unitIndex   = new Map();   // key → index
+    const convoIndex  = new Map();   // key → index
+    const convoGroups = new Map();   // convoIdx → [rowIdx, ...]
+
+    // Metadata columns: every column that is NOT a code, unit, or convo column.
+    const excludedCols = new Set([...codes, ...unitCols, ...convoCols]);
+    const allCols      = nRows > 0 ? Object.keys(rows[0]) : [];
+    const metaCols     = allCols.filter(c => !excludedCols.has(c));
+
+    // Per-unit metadata rows — populated on first occurrence of each unit.
+    const metaData = [];
+
+    for (let i = 0; i < nRows; i++) {
+        const row = rows[i];
+
+        // Code values
+        for (let c = 0; c < nCodes; c++) {
+            codeMatrix[i * nCodes + c] = Number(row[codes[c]]) || 0;
+        }
+
+        // Unit index
+        const uKey = rowKey(row, unitCols);
+        if (!unitIndex.has(uKey)) {
+            const uIdx = unitIndex.size;
+            unitIndex.set(uKey, uIdx);
+            // First row for this unit → representative metadata
+            const meta = {};
+            for (const col of metaCols) meta[col] = row[col];
+            metaData[uIdx] = meta;
+        }
+        unitOf[i] = unitIndex.get(uKey);
+
+        // Conversation index
+        const cKey = rowKey(row, convoCols);
+        if (!convoIndex.has(cKey)) convoIndex.set(cKey, convoIndex.size);
+        const cIdx = convoIndex.get(cKey);
+        convoOf[i] = cIdx;
+
+        if (!convoGroups.has(cIdx)) convoGroups.set(cIdx, []);
+        convoGroups.get(cIdx).push(i);
+    }
+
+    const unitLabels = Array.from(unitIndex.keys());
+    const nUnits     = unitLabels.length;
+
+    return { codeMatrix, nRows, nCodes, nUnits, unitLabels, unitOf, convoOf, convoGroups,
+             metaData, metaCols };
+}

package/src/index.js

@@ -0,0 +1,433 @@
+/**
+ * @qe-libs/rena-wasm
+ *
+ * JavaScript/WebAssembly ENA pipeline.
+ * Thin orchestration layer over @qe-libs/libqe-wasm — handles data parsing,
+ * unit/conversation grouping, and the full accumulate→normalize→center→
+ * rotate→project→node-positions pipeline.
+ *
+ * Output structure mirrors R's ena.set object (without R-specific S3 class
+ * attributes and without metadata columns prepended to every matrix).
+ * Metadata lives in metaData / model.metaData instead.
+ *
+ * Top-level fields (= R's set$...):
+ *   connectionCounts  Float64Array  (nUnits × nConnections) — raw accumulation
+ *   lineWeights       Float64Array  (nUnits × nConnections) — sphere-normed
+ *   points            Float64Array  (nUnits × dims)         — projected positions
+ *   rotationMatrix    Float64Array  (nConnections × dims)   — rotation vectors
+ *   metaData          Object[]      one object per unit, non-code/unit/convo cols
+ *   connectionNames   string[]
+ *   columnClasses     Object        matrix name → R column class string
+ *   nUnits            number
+ *   nConnections      number
+ *   dims              number
+ *
+ * model sub-object (= R's set$model$...):
+ *   model.centroids           Float64Array  (nUnits × dims) — LWS centroids
+ *   model.variance            number[]      variance explained per dim
+ *   model.unitLabels          string[]
+ *   model.pointsForProjection Float64Array  (nUnits × nConnections) — centered normed
+ *
+ * rotation sub-object (= R's set$rotation$...):
+ *   rotation.rotationMatrix  Float64Array  same reference as top-level rotationMatrix
+ *   rotation.nodes           Float64Array  (nCodes × dims) — code positions
+ *   rotation.columnNames     string[]      axis labels e.g. ['SVD1','SVD2']
+ *   rotation.eigenvalues     number[]
+ *   rotation.centerVec       Float64Array  (nConnections) — centering vector
+ *   rotation.codes           string[]
+ *   rotation.adjacencyKey    string[][]    [[codeA,codeB], ...] per connection
+ */
+
+import loadLibQE from '@qe-libs/libqe-wasm';
+import { parseData } from './data.js';
+import {
+    accumulate, sphereNorm, center,
+    rotateSVD, rotateMeans,
+    project, nodePositions,
+} from './pipeline.js';
+import { accumulateTensor, defaultTensor } from './tensor.js';
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Compute per-dimension variance explained from projected unit positions.
+ * Matches R: diagonal(var(points)) / sum(diagonal(var(points)))
+ *
+ * @param {Float64Array} points  nUnits × dims, row-major
+ * @param {number}       nUnits
+ * @param {number}       dims
+ * @returns {number[]}  length dims, sums to 1
+ */
+function computeVariance(points, nUnits, dims) {
+    if (nUnits < 2) return Array.from({ length: dims }, () => 1 / dims);
+
+    // Column means
+    const means = new Float64Array(dims);
+    for (let u = 0; u < nUnits; u++)
+        for (let d = 0; d < dims; d++)
+            means[d] += points[u * dims + d];
+    for (let d = 0; d < dims; d++) means[d] /= nUnits;
+
+    // Sample variance (n-1 denominator, matching R's var())
+    const variances = new Float64Array(dims);
+    for (let u = 0; u < nUnits; u++)
+        for (let d = 0; d < dims; d++) {
+            const diff = points[u * dims + d] - means[d];
+            variances[d] += diff * diff;
+        }
+    for (let d = 0; d < dims; d++) variances[d] /= (nUnits - 1);
+
+    const total = Array.from(variances).reduce((a, b) => a + b, 0);
+    if (total === 0) return Array.from({ length: dims }, () => 1 / dims);
+    return Array.from(variances).map(v => v / total);
+}
+
+/**
+ * Build the adjacency key — list of [codeA, codeB] pairs for each connection.
+ * Matches R's enadata$adjacency.matrix (column-major upper triangle order).
+ *
+ * @param {string[]} codes
+ * @returns {string[][]}  length nConnections, each entry is [codeI, codeJ]
+ */
+function buildAdjacencyKey(codes) {
+    const key = [];
+    for (let j = 1; j < codes.length; j++)
+        for (let i = 0; i < j; i++)
+            key.push([codes[i], codes[j]]);
+    return key;
+}
+
+// ── ENA result object ─────────────────────────────────────────────────────────
+
+class ENAModel {
+    constructor(opts) {
+        // ── top-level fields (= R's set$...) ────────────────────────────────
+        this.connectionCounts = opts.connectionCounts;  // raw networks
+        this.lineWeights      = opts.lineWeights;       // sphere-normed networks
+        this.points           = opts.points;            // projected unit positions
+        this.rotationMatrix   = opts.rotationMatrix;    // n_connections × dims
+        this.metaData         = opts.metaData;          // array of unit metadata objects
+        this.connectionNames  = opts.connectionNames;
+        this.nUnits           = opts.nUnits;
+        this.nConnections     = opts.nConnections;
+        this.dims             = opts.dims;
+
+        // ── model sub-object (= R's set$model$...) ───────────────────────────
+        this.model = {
+            centroids:           opts.centroids,           // LWS positions
+            variance:            opts.variance,            // variance explained
+            unitLabels:          opts.unitLabels,
+            pointsForProjection: opts.pointsForProjection, // centered normed networks
+        };
+
+        // ── rotation sub-object (= R's set$rotation$...) ────────────────────
+        this.rotation = {
+            rotationMatrix: opts.rotationMatrix,  // same reference as top-level
+            nodes:          opts.nodes,           // code positions
+            columnNames:    opts.columnNames,     // axis labels ['SVD1','SVD2']
+            eigenvalues:    opts.eigenvalues,
+            centerVec:      opts.centerVec,
+            codes:          opts.codes,
+            adjacencyKey:   opts.adjacencyKey,
+        };
+
+        // ── column class annotations (mirrors R's S3 class tags) ─────────────
+        this.columnClasses = {
+            connectionCounts:    'ena.co.occurrence',
+            lineWeights:         'ena.co.occurrence',
+            points:              'ena.dimension',
+            pointsForProjection: 'ena.co.occurrence',
+            rotationMatrix:      'ena.dimension',
+            nodes:               'ena.dimension',
+        };
+    }
+
+    /**
+     * Projected position for a single unit (= R's set$points[unit,]).
+     * @param {string} unitLabel
+     * @returns {number[]}
+     */
+    point(unitLabel) {
+        const idx = this.model.unitLabels.indexOf(unitLabel);
+        if (idx < 0) throw new Error(`Unknown unit: ${unitLabel}`);
+        return Array.from(this.points.subarray(idx * this.dims, (idx + 1) * this.dims));
+    }
+
+    /**
+     * LWS centroid for a single unit (= R's set$model$centroids[unit,]).
+     * @param {string} unitLabel
+     * @returns {number[]}
+     */
+    centroid(unitLabel) {
+        const idx = this.model.unitLabels.indexOf(unitLabel);
+        if (idx < 0) throw new Error(`Unknown unit: ${unitLabel}`);
+        if (!this.model.centroids) throw new Error('LWS centroids not available from libqe');
+        return Array.from(this.model.centroids.subarray(idx * this.dims, (idx + 1) * this.dims));
+    }
+
+    /**
+     * Normed network vector for a single unit (= R's set$line.weights[unit,]).
+     * @param {string} unitLabel
+     * @returns {number[]}
+     */
+    network(unitLabel) {
+        const idx = this.model.unitLabels.indexOf(unitLabel);
+        if (idx < 0) throw new Error(`Unknown unit: ${unitLabel}`);
+        return Array.from(this.lineWeights.subarray(
+            idx * this.nConnections, (idx + 1) * this.nConnections
+        ));
+    }
+}
+
+// ── shared pipeline (post-accumulation) ──────────────────────────────────────
+
+function runPipeline(qe, rawNetworks, nUnits, nConnections, codes, unitLabels,
+                     metaData, rotMethod, groupA, groupB, dims) {
+    const connectionNames = qe.connection_names(codes);
+
+    // Sphere norm → lineWeights (= R's set$line.weights)
+    const lineWeights = sphereNorm(qe, rawNetworks, nUnits, nConnections);
+
+    // Center → pointsForProjection (= R's model$points.for.projection)
+    //          centerVec             (= R's rotation$center.vec)
+    const { centered: pointsForProjection, centerVec } =
+        center(qe, lineWeights, nUnits, nConnections);
+
+    // Rotate
+    let rot;
+    if (rotMethod === 'mean') {
+        if (!groupA || !groupB) throw new Error(
+            'opts.groupA and opts.groupB are required for means rotation'
+        );
+        rot = rotateMeans(qe, pointsForProjection, nUnits, nConnections, groupA, groupB);
+    } else {
+        rot = rotateSVD(qe, pointsForProjection, nUnits, nConnections);
+    }
+
+    // Truncate rotation matrix to dims columns (= R's set$rotation.matrix)
+    const rotationMatrix = new Float64Array(rot.rotRows * dims);
+    for (let r = 0; r < rot.rotRows; r++)
+        for (let d = 0; d < dims; d++)
+            rotationMatrix[r * dims + d] = rot.rotation[r * rot.rotCols + d];
+
+    const columnNames = rot.columnNames.slice(0, dims);
+
+    // Project → points (= R's set$points)
+    const points = project(
+        pointsForProjection, nUnits, nConnections,
+        rot.rotation, rot.rotRows, rot.rotCols, dims
+    );
+
+    // Node positions (LWS) → rotation.nodes + model.centroids
+    // libqe.node_positions expects centered-normed networks (pointsForProjection),
+    // not sphere-normed (lineWeights). Using lineWeights places code nodes in wrong locations.
+    const { nodes, centroids } = nodePositions(
+        qe, pointsForProjection, nUnits, nConnections, points, dims
+    );
+
+    // Variance explained (= R's model$variance)
+    const variance = computeVariance(points, nUnits, dims);
+
+    // Adjacency key (= R's rotation$adjacency.key)
+    const adjacencyKey = buildAdjacencyKey(codes);
+
+    return new ENAModel({
+        // top-level
+        connectionCounts:     rawNetworks,
+        lineWeights,
+        points,
+        rotationMatrix,
+        metaData,
+        connectionNames,
+        nUnits,
+        nConnections,
+        dims,
+        // model sub
+        centroids,
+        variance,
+        unitLabels,
+        pointsForProjection,
+        // rotation sub
+        nodes,
+        columnNames,
+        eigenvalues:  rot.eigenvalues,
+        centerVec,
+        codes,
+        adjacencyKey,
+    });
+}
+
+// ── main factory ─────────────────────────────────────────────────────────────
+
+/**
+ * Load the ENA module.  Returns an object with `fit()` and `accumulate()`.
+ *
+ * @returns {Promise<{fit: Function, accumulate: Function}>}
+ */
+export default async function loadENA() {
+    const qe = await loadLibQE();
+
+    return {
+        /**
+         * Run the full ENA pipeline.
+         *
+         * @param {Object[]} rows  - Tabular data (array of row objects)
+         * @param {object}   opts
+         * @param {string[]} opts.codes            - Code column names
+         * @param {string[]} opts.units            - Unit identifier column(s)
+         * @param {string[]} opts.conversations    - Conversation identifier column(s)
+         * @param {number}   [opts.window=4]       - Backward window (simple path; ignored when tensor provided)
+         * @param {boolean}  [opts.binary=true]    - Binarise co-occurrences (simple path only)
+         * @param {boolean}  [opts.ordered=false]  - Directed networks (tensor path only)
+         * @param {object}   [opts.tensor]         - Context tensor definition
+         * @param {string}   [opts.rotation='svd'] - 'svd' or 'mean'
+         * @param {number[]} [opts.groupA]         - Unit indices for means rotation group A
+         * @param {number[]} [opts.groupB]         - Unit indices for means rotation group B
+         * @param {number}   [opts.dims=2]         - Number of dimensions to return
+         *
+         * @returns {ENAModel}
+         */
+        fit(rows, opts = {}) {
+            const {
+                codes,
+                units,
+                conversations,
+                window:   windowSize = 4,
+                binary               = true,
+                ordered              = false,
+                tensor:   tensorDef,
+                rotation: rotMethod  = 'svd',
+                groupA,
+                groupB,
+                dims                 = 2,
+            } = opts;
+
+            if (!codes?.length)         throw new Error('opts.codes is required');
+            if (!units?.length)         throw new Error('opts.units is required');
+            if (!conversations?.length) throw new Error('opts.conversations is required');
+
+            const { codeMatrix, nRows, nCodes, nUnits, unitLabels,
+                    unitOf, convoGroups, metaData } =
+                parseData(rows, codes, units, conversations);
+
+            let rawNetworks, nConnections;
+
+            if (tensorDef) {
+                rawNetworks  = accumulateTensor(
+                    qe, rows, codeMatrix, nRows, nCodes, nUnits,
+                    unitOf, convoGroups, tensorDef, ordered
+                );
+                nConnections = ordered ? nCodes * nCodes : qe.choose_two(nCodes);
+            } else {
+                rawNetworks  = accumulate(
+                    qe, codeMatrix, nRows, nCodes, nUnits,
+                    unitOf, convoGroups, windowSize, binary
+                );
+                nConnections = qe.choose_two(nCodes);
+            }
+
+            return runPipeline(qe, rawNetworks, nUnits, nConnections, codes,
+                               unitLabels, metaData, rotMethod, groupA, groupB, dims);
+        },
+
+        /**
+         * Run only the accumulation step (= R's ena.accumulate.data()).
+         * Returns raw (un-normalised) network vectors.
+         *
+         * @param {Object[]} rows
+         * @param {object}   opts  - codes, units, conversations, window, binary, ordered, tensor
+         * @returns {{
+         *   connectionCounts: Float64Array,
+         *   unitLabels:       string[],
+         *   connectionNames:  string[],
+         *   metaData:         Object[],
+         *   nUnits:           number,
+         *   nConnections:     number,
+         * }}
+         */
+        accumulate(rows, opts = {}) {
+            const {
+                codes, units, conversations,
+                window:  windowSize = 4,
+                binary               = true,
+                ordered              = false,
+                tensor:  tensorDef,
+            } = opts;
+
+            const { codeMatrix, nRows, nCodes, nUnits, unitLabels,
+                    unitOf, convoGroups, metaData } =
+                parseData(rows, codes, units, conversations);
+
+            let networks, nConnections;
+
+            if (tensorDef) {
+                networks     = accumulateTensor(
+                    qe, rows, codeMatrix, nRows, nCodes, nUnits,
+                    unitOf, convoGroups, tensorDef, ordered
+                );
+                nConnections = ordered ? nCodes * nCodes : qe.choose_two(nCodes);
+            } else {
+                networks     = accumulate(
+                    qe, codeMatrix, nRows, nCodes, nUnits,
+                    unitOf, convoGroups, windowSize, binary
+                );
+                nConnections = qe.choose_two(nCodes);
+            }
+
+            const connectionNames = qe.connection_names(codes);
+            return { connectionCounts: networks, unitLabels, connectionNames,
+                     metaData, nUnits, nConnections };
+        },
+
+        /**
+         * Per-dimension t-based confidence intervals around the column means.
+         * Matches R's conf.ints / libqe::mean_ci.
+         *
+         * @param {Float64Array} points     nUnits × dims, row-major
+         * @param {number}       nUnits
+         * @param {number}       dims
+         * @param {number}       [confLevel=0.95]
+         * @returns {{ data: Float64Array, rows: number, cols: number }}
+         *   rows=dims, cols=3 — columns: mean, lower CI, upper CI
+         */
+        confInts(points, nUnits, dims, confLevel = 0.95) {
+            return qe.mean_ci(points, nUnits, dims, confLevel);
+        },
+
+        /**
+         * Per-dimension Tukey-fence outlier intervals (Q1-k*IQR, Q3+k*IQR).
+         * Matches R's outlier.ints / libqe::outlier_ci.
+         *
+         * @param {Float64Array} points     nUnits × dims, row-major
+         * @param {number}       nUnits
+         * @param {number}       dims
+         * @param {number}       [iqrFactor=1.5]
+         * @returns {{ data: Float64Array, rows: number, cols: number }}
+         *   rows=dims, cols=2 — columns: lower fence, upper fence
+         */
+        outlierInts(points, nUnits, dims, iqrFactor = 1.5) {
+            return qe.outlier_ci(points, nUnits, dims, iqrFactor);
+        },
+
+        /**
+         * Per-dimension parametric and non-parametric two-group statistics.
+         * Matches R's set$tests / libqe::group_stats.
+         *
+         * @param {Float64Array} g1Points  group 1 points, nG1 × dims, row-major
+         * @param {number}       nG1
+         * @param {Float64Array} g2Points  group 2 points, nG2 × dims, row-major
+         * @param {number}       nG2
+         * @param {number}       dims
+         * @returns {{ n1, n2, t, df, pvalue_t, cohens_d, means, sds,
+         *             U, pvalue_u, effect_r, medians }}
+         */
+        compareGroups(g1Points, nG1, g2Points, nG2, dims) {
+            return qe.group_stats(g1Points, nG1, dims, g2Points, nG2, dims);
+        },
+
+        /**
+         * Helpers re-exported for consumers who want to build their own pipeline.
+         */
+        defaultTensor,
+    };
+}

package/src/pipeline.js

@@ -0,0 +1,212 @@
+/**
+ * pipeline.js — ENA pipeline steps backed by @qe-libs/libqe-wasm.
+ *
+ * All functions take a libqe module instance (`qe`) as first argument so
+ * they work in both Node and browser contexts without global state.
+ */
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Multiply two row-major matrices: A (m×k) @ B (k×n) → C (m×n).
+ * Used for projection (networks @ rotation_matrix).
+ */
+export function matmul(A, m, k, B, n) {
+    const C = new Float64Array(m * n);
+    for (let r = 0; r < m; r++) {
+        for (let c = 0; c < n; c++) {
+            let sum = 0;
+            for (let i = 0; i < k; i++) sum += A[r * k + i] * B[i * n + c];
+            C[r * n + c] = sum;
+        }
+    }
+    return C;
+}
+
+/**
+ * Extract the first `nDims` columns of a row-major matrix.
+ */
+export function sliceCols(data, nRows, nCols, nDims) {
+    if (nDims >= nCols) return data;
+    const out = new Float64Array(nRows * nDims);
+    for (let r = 0; r < nRows; r++)
+        for (let c = 0; c < nDims; c++)
+            out[r * nDims + c] = data[r * nCols + c];
+    return out;
+}
+
+// ── accumulation ─────────────────────────────────────────────────────────────
+
+/**
+ * Accumulate windowed co-occurrences for all units across all conversations.
+ *
+ * For each conversation group, runs qe.accumulate_stanza() on the conversation's
+ * rows to get per-row connection vectors, then folds each row's vector into its
+ * owning unit's running sum.
+ *
+ * @param {object}      qe            libqe WASM module
+ * @param {Float64Array} codeMatrix   n_rows × n_codes, row-major
+ * @param {number}      nRows
+ * @param {number}      nCodes
+ * @param {number}      nUnits
+ * @param {Int32Array}  unitOf        unit index per row
+ * @param {Map}         convoGroups   convoIdx → [rowIdx, ...]
+ * @param {number}      windowSize    backward window (rows)
+ * @param {boolean}     binary        binarise co-occurrences
+ *
+ * @returns {Float64Array}  nUnits × nConnections, row-major
+ */
+export function accumulate(qe, codeMatrix, nRows, nCodes, nUnits,
+                            unitOf, convoGroups, windowSize = 4, binary = true) {
+    const nConnections = qe.choose_two(nCodes);
+    const networks     = new Float64Array(nUnits * nConnections);
+
+    for (const [, rowIndices] of convoGroups) {
+        const nConvo = rowIndices.length;
+
+        // Extract code rows for this conversation (contiguous sub-matrix)
+        const convoCodes = new Float64Array(nConvo * nCodes);
+        for (let r = 0; r < nConvo; r++) {
+            const src = rowIndices[r];
+            convoCodes.set(
+                codeMatrix.subarray(src * nCodes, src * nCodes + nCodes),
+                r * nCodes
+            );
+        }
+
+        // Windowed accumulation — returns per-row connection vectors
+        const stanza = qe.accumulate_stanza(
+            convoCodes, nConvo, nCodes, windowSize, 0, binary
+        );
+        // stanza.data: nConvo × nConnections, row-major
+
+        // Fold each row into its unit's accumulator
+        for (let r = 0; r < nConvo; r++) {
+            const unit   = unitOf[rowIndices[r]];
+            const offset = r * nConnections;
+            for (let c = 0; c < nConnections; c++) {
+                networks[unit * nConnections + c] += stanza.data[offset + c];
+            }
+        }
+    }
+
+    return networks;
+}
+
+// ── normalization (sphere norm) ───────────────────────────────────────────────
+
+/**
+ * L2-normalize each row (sphere normalization).
+ * Rows with zero norm are left as zero.
+ */
+export function sphereNorm(qe, networks, nUnits, nConnections) {
+    const result = qe.normalize_networks(networks, nUnits, nConnections);
+    return new Float64Array(result.data);
+}
+
+// ── centering ─────────────────────────────────────────────────────────────────
+
+/**
+ * Subtract column means (center the network space).
+ * Excludes all-zero rows from the mean calculation (zero-network exclusion).
+ *
+ * @returns {{ centered: Float64Array, centerVec: Float64Array }}
+ *   centered  — mean-subtracted networks (zero-network rows left at zero)
+ *   centerVec — the column means used for centering (= R's rotation$center.vec)
+ */
+export function center(qe, networks, nUnits, nConnections) {
+    // Identify non-zero rows
+    const active = [];
+    for (let u = 0; u < nUnits; u++) {
+        let rowSum = 0;
+        for (let c = 0; c < nConnections; c++) rowSum += Math.abs(networks[u * nConnections + c]);
+        if (rowSum > 0) active.push(u);
+    }
+
+    // Compute column means over active rows only (= R's rotation$center.vec)
+    const means = new Float64Array(nConnections);
+    for (const u of active) {
+        for (let c = 0; c < nConnections; c++) means[c] += networks[u * nConnections + c];
+    }
+    if (active.length > 0) {
+        for (let c = 0; c < nConnections; c++) means[c] /= active.length;
+    }
+
+    // Subtract means from non-zero rows only.
+    // Zero-network rows remain at zero (R: center.align.to.origin = TRUE default).
+    const activeSet = new Set(active);
+    const centered  = new Float64Array(networks.length);
+    for (let u = 0; u < nUnits; u++) {
+        if (!activeSet.has(u)) continue;          // leave zero-network row as zero
+        for (let c = 0; c < nConnections; c++) {
+            centered[u * nConnections + c] = networks[u * nConnections + c] - means[c];
+        }
+    }
+
+    return { centered, centerVec: means };
+}
+
+// ── rotation ──────────────────────────────────────────────────────────────────
+
+/**
+ * SVD rotation (default ENA rotation).
+ * @returns {{ rotation: Float64Array, rotRows: number, rotCols: number,
+ *             eigenvalues: number[], columnNames: string[] }}
+ */
+export function rotateSVD(qe, centered, nUnits, nConnections) {
+    const r = qe.ena_svd(centered, nUnits, nConnections);
+    return {
+        rotation:    r.rotation.data,
+        rotRows:     r.rotation.rows,
+        rotCols:     r.rotation.cols,
+        eigenvalues: r.eigenvalues,
+        columnNames: r.column_names,
+    };
+}
+
+/**
+ * Means rotation.
+ * @param {Int32Array[]} groupA  Row indices of group A
+ * @param {Int32Array[]} groupB  Row indices of group B
+ */
+export function rotateMeans(qe, centered, nUnits, nConnections, groupA, groupB) {
+    const groupPairs = [{ a: new Int32Array(groupA), b: new Int32Array(groupB) }];
+    const r = qe.means_rotation(centered, nUnits, nConnections, groupPairs);
+    return {
+        rotation:    r.rotation.data,
+        rotRows:     r.rotation.rows,
+        rotCols:     r.rotation.cols,
+        eigenvalues: r.eigenvalues,
+        columnNames: r.column_names,
+    };
+}
+
+// ── projection & node positions ───────────────────────────────────────────────
+
+/**
+ * Project centered networks into the rotated ENA space.
+ * @returns {Float64Array}  nUnits × nDims, row-major
+ */
+export function project(centered, nUnits, nConnections, rotation, rotRows, rotCols, nDims) {
+    const fullPoints = matmul(centered, nUnits, nConnections, rotation, rotCols);
+    return sliceCols(fullPoints, nUnits, rotCols, nDims);
+}
+
+/**
+ * Compute code node positions via least-squares (LWS).
+ *
+ * @returns {{ nodes: Float64Array, nodeRows: number, nodeCols: number,
+ *             centroids: Float64Array|null }}
+ *   nodes     — code positions in ENA space (= R's rotation$nodes)
+ *   centroids — LWS unit centroid positions (= R's model$centroids), or null
+ *               if libqe does not expose them
+ */
+export function nodePositions(qe, networks, nUnits, nConnections, points, nDims) {
+    const r = qe.node_positions(networks, nUnits, nConnections, points, nUnits, nDims, nDims);
+    return {
+        nodes:     new Float64Array(r.nodes.data),
+        nodeRows:  r.nodes.rows,
+        nodeCols:  r.nodes.cols,
+        centroids: r.centroids ? new Float64Array(r.centroids.data) : null,
+    };
+}

package/src/tensor.js

@@ -0,0 +1,232 @@
+/**
+ * tensor.js — Context-tensor accumulation for rENA WASM.
+ *
+ * Maps tma's apply_tensor() semantics to the JS/WASM layer.  Each unit's
+ * network is accumulated by calling qe.accumulate_tensor_unit() with a
+ * multi-dimensional tensor that encodes per-factor-combination window sizes
+ * and weights.
+ *
+ * Tensor definition (passed as `opts.tensor` to fit/accumulate):
+ *
+ *   {
+ *     // Tensor shape.  Last entry is always 2 (index 0 = weight, index 1 = window).
+ *     // Earlier entries correspond to the factor columns in order.
+ *     dims: [nValsFactor0, nValsFactor1, ..., 2],
+ *
+ *     // Which factor axes (0-based, NOT including the last weight/window axis)
+ *     // act as sender / receiver / mode dimensions.
+ *     dimsSender:   [0],      // e.g. axis 0 is a sender factor
+ *     dimsReceiver: [1],      // e.g. axis 1 is a receiver factor
+ *     dimsMode:     [],
+ *
+ *     // Column names in the data — one per factor axis, matching dims[0..n-2].
+ *     factors: ['SenderType', 'ReceiverType'],
+ *
+ *     // Maps each factor column's string values to 0-based integer indices.
+ *     // If omitted, values are encoded in order of first appearance.
+ *     factorLevels: {
+ *       SenderType:   { 'A': 0, 'B': 1, 'C': 2 },
+ *       ReceiverType: { 'X': 0, 'Y': 1, 'Z': 2 },
+ *     },
+ *
+ *     // Flat column-major tensor data: weight and window for every factor
+ *     // combination.  Length must equal product(dims).
+ *     // Index 0 along last axis = weight; index 1 along last axis = window.
+ *     data: new Float64Array([...]),
+ *
+ *     // Optional column name for per-row timestamps.
+ *     // Defaults to row index (0, 1, 2, ...) — equivalent to unit-step time.
+ *     timesCol: 'timestamp',
+ *   }
+ *
+ * Simple windowed accumulation (IS_DEFAULT path):
+ *   Pass `{ dims: [2], dimsSender: [], dimsReceiver: [], dimsMode: [],
+ *            factors: [], data: Float64Array.of(weight, window) }`
+ *   or just use the `window` shorthand on the outer opts instead.
+ */
+
+/**
+ * Build the context_lookup matrix and times vector from row data.
+ *
+ * @param {Object[]}        rows          All data rows (full dataset)
+ * @param {number[]}        rowIndices    Indices into rows for this conversation
+ * @param {string[]}        factors       Factor column names
+ * @param {Object}          factorLevels  { colName: { value: index } }
+ * @returns {{ contextLookup: Int32Array, clRows: number, clCols: number,
+ *             times: Float64Array }}
+ */
+export function buildContextLookup(rows, rowIndices, factors, factorLevels) {
+    const nRows   = rowIndices.length;
+    const nFactor = factors.length;
+
+    const contextLookup = new Int32Array(nRows * nFactor);
+    const times         = new Float64Array(nRows);
+
+    for (let i = 0; i < nRows; i++) {
+        const row = rows[rowIndices[i]];
+        times[i] = i;  // default: row index as time
+        for (let f = 0; f < nFactor; f++) {
+            const col = factors[f];
+            contextLookup[i * nFactor + f] = factorLevels[col][row[col]] ?? 0;
+        }
+    }
+
+    return { contextLookup, clRows: nRows, clCols: nFactor, times };
+}
+
+/**
+ * Build the context_lookup with explicit timestamp column.
+ */
+export function buildContextLookupWithTimes(rows, rowIndices, factors, factorLevels, timesCol) {
+    const nRows   = rowIndices.length;
+    const nFactor = factors.length;
+
+    const contextLookup = new Int32Array(nRows * nFactor);
+    const times         = new Float64Array(nRows);
+
+    for (let i = 0; i < nRows; i++) {
+        const row = rows[rowIndices[i]];
+        times[i] = Number(row[timesCol]) || i;
+        for (let f = 0; f < nFactor; f++) {
+            const col = factors[f];
+            contextLookup[i * nFactor + f] = factorLevels[col][row[col]] ?? 0;
+        }
+    }
+
+    return { contextLookup, clRows: nRows, clCols: nFactor, times };
+}
+
+/**
+ * Auto-build factorLevels from data when not explicitly provided.
+ * Scans all rows and assigns integer indices in order of first appearance.
+ *
+ * @param {Object[]} rows
+ * @param {string[]} factors
+ * @returns {Object}  { colName: { value: index, ... }, ... }
+ */
+export function inferFactorLevels(rows, factors) {
+    const levels = {};
+    for (const col of factors) {
+        levels[col] = {};
+        let idx = 0;
+        for (const row of rows) {
+            const v = row[col];
+            if (v !== undefined && !(v in levels[col])) {
+                levels[col][v] = idx++;
+            }
+        }
+    }
+    return levels;
+}
+
+/**
+ * Accumulate tensor networks for all units across all conversations.
+ *
+ * @param {object}      qe             libqe WASM module
+ * @param {Object[]}    rows           Full dataset
+ * @param {Float64Array} codeMatrix   n_rows × n_codes, row-major
+ * @param {number}      nRows
+ * @param {number}      nCodes
+ * @param {number}      nUnits
+ * @param {Int32Array}  unitOf         unit index per row
+ * @param {Map}         convoGroups    convoIdx → [rowIdx, ...]
+ * @param {object}      tensorDef      Tensor definition (see module docstring)
+ * @param {boolean}     ordered        true → directed (n²); false → undirected
+ *
+ * @returns {Float64Array}  nUnits × nConnections, row-major
+ */
+export function accumulateTensor(qe, rows, codeMatrix, nRows, nCodes, nUnits,
+                                  unitOf, convoGroups, tensorDef, ordered = false) {
+    const {
+        dims,
+        dimsSender   = [],
+        dimsReceiver = [],
+        dimsMode     = [],
+        factors      = [],
+        data:   tensorData,
+        timesCol,
+    } = tensorDef;
+
+    // Resolve factor levels (infer if not provided)
+    const factorLevels = tensorDef.factorLevels ?? inferFactorLevels(rows, factors);
+
+    const nConnections = ordered
+        ? nCodes * nCodes
+        : qe.choose_two(nCodes);
+
+    const networks = new Float64Array(nUnits * nConnections);
+
+    const dimsArr    = new Int32Array(dims);
+    const senderArr  = new Int32Array(dimsSender);
+    const receiverArr = new Int32Array(dimsReceiver);
+    const modeArr    = new Int32Array(dimsMode);
+
+    for (const [, rowIndices] of convoGroups) {
+        const nConvo = rowIndices.length;
+
+        // Extract code rows for this conversation
+        const convoCodes = new Float64Array(nConvo * nCodes);
+        for (let r = 0; r < nConvo; r++) {
+            const src = rowIndices[r];
+            convoCodes.set(
+                codeMatrix.subarray(src * nCodes, src * nCodes + nCodes),
+                r * nCodes
+            );
+        }
+
+        // Build context_lookup and times for this conversation
+        const { contextLookup, clRows, clCols, times } = timesCol
+            ? buildContextLookupWithTimes(rows, rowIndices, factors, factorLevels, timesCol)
+            : buildContextLookup(rows, rowIndices, factors, factorLevels);
+
+        // Group response rows by unit (within this conversation)
+        const unitConvoRows = new Map();
+        for (let r = 0; r < nConvo; r++) {
+            const unit = unitOf[rowIndices[r]];
+            if (!unitConvoRows.has(unit)) unitConvoRows.set(unit, []);
+            unitConvoRows.get(unit).push(r);  // local (conversation-relative) index
+        }
+
+        // Accumulate per unit
+        for (const [unit, localRows] of unitConvoRows) {
+            const unitRowsArr = new Int32Array(localRows);
+
+            const result = qe.accumulate_tensor_unit(
+                tensorData, dimsArr,
+                senderArr, receiverArr, modeArr,
+                contextLookup, clRows, clCols,
+                unitRowsArr,
+                convoCodes, nConvo, nCodes,
+                times,
+                ordered
+            );
+
+            // Add connection counts to this unit's accumulator
+            for (let c = 0; c < nConnections; c++) {
+                networks[unit * nConnections + c] += result.connection_counts[c];
+            }
+        }
+    }
+
+    return networks;
+}
+
+/**
+ * Build an IS_DEFAULT tensor definition from a simple window + weight.
+ * Use this to express simple windowed accumulation through the tensor path.
+ *
+ * @param {number} windowSize
+ * @param {number} [weight=1]
+ * @returns {object} tensorDef
+ */
+export function defaultTensor(windowSize, weight = 1) {
+    return {
+        dims:         [2],
+        dimsSender:   [],
+        dimsReceiver: [],
+        dimsMode:     [],
+        factors:      [],
+        factorLevels: {},
+        data:         Float64Array.of(weight, windowSize),
+    };
+}