@qe-libs/rena-wasm 0.1.6 → 0.1.8

package/README.md

@@ -91,6 +91,26 @@ const model = ena.fit(rows, { codes, units, conversations, window: 4, weightMode
 
 ---
 
+## 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.
+
+```js
+// 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.
+
+---
+
 ## Reduced-Code Search (PRIA)
 
 `pria()` finds the largest set of codes (up to `removeNum`, never leaving
@@ -136,7 +156,13 @@ columns in the data.
 // 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: true,   // directed (n² connections); also works without a tensor.
+                   // Ordered models follow ona::model(): zero-network units are
+                   // left out of the centring mean but shifted by it, 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qe-libs/rena-wasm",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "JavaScript/WebAssembly ENA pipeline — thin orchestration layer over @qe-libs/libqe-wasm",
   "main": "src/index.js",
   "type": "module",

package/src/data.js

@@ -24,6 +24,10 @@ export function rowKey(row, cols) {
  * @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'])
+ * @param {string[]|null} [unitsUsed=null] - Unit keys (rowKey format) to model
+ *   (= R's `units.used`). Rows of other units stay in their conversations, so
+ *   they still count as context in the included units' windows, but they get
+ *   no unit (unitOf = -1) and so produce no network. null = every unit.
  *
  * @returns {{
  *   codeMatrix:  Float64Array,            // n_rows × n_codes, row-major
@@ -31,14 +35,14 @@ export function rowKey(row, cols) {
  *   nCodes:      number,
  *   nUnits:      number,
  *   unitLabels:  string[],                // unit key for each unit index
- *   unitOf:      Int32Array,              // unit index for each row
+ *   unitOf:      Int32Array,              // unit index for each row (-1 = not a modeled unit)
  *   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) {
+export function parseData(rows, codes, unitCols, convoCols, unitsUsed = null) {
     const nRows  = rows.length;
     const nCodes = codes.length;
 
@@ -58,6 +62,8 @@ export function parseData(rows, codes, unitCols, convoCols) {
     // Per-unit metadata rows — populated on first occurrence of each unit.
     const metaData = [];
 
+    const used = unitsUsed ? new Set(unitsUsed.map(String)) : null;
+
     for (let i = 0; i < nRows; i++) {
         const row = rows[i];
 
@@ -68,7 +74,9 @@ export function parseData(rows, codes, unitCols, convoCols) {
 
         // Unit index
         const uKey = rowKey(row, unitCols);
-        if (!unitIndex.has(uKey)) {
+        if (used && !used.has(uKey)) {
+            unitOf[i] = -1;
+        } else if (!unitIndex.has(uKey)) {
             const uIdx = unitIndex.size;
             unitIndex.set(uKey, uIdx);
             // First row for this unit → representative metadata
@@ -76,7 +84,7 @@ export function parseData(rows, codes, unitCols, convoCols) {
             for (const col of metaCols) meta[col] = row[col];
             metaData[uIdx] = meta;
         }
-        unitOf[i] = unitIndex.get(uKey);
+        if (unitOf[i] !== -1) unitOf[i] = unitIndex.get(uKey);
 
         // Conversation index
         const cKey = rowKey(row, convoCols);
@@ -90,6 +98,9 @@ export function parseData(rows, codes, unitCols, convoCols) {
 
     const unitLabels = Array.from(unitIndex.keys());
     const nUnits     = unitLabels.length;
+    if (used && nUnits === 0) {
+        throw new Error('opts.unitsUsed matched no units in the data');
+    }
 
     return { codeMatrix, nRows, nCodes, nUnits, unitLabels, unitOf, convoOf, convoGroups,
              metaData, metaCols };

package/src/index.js

@@ -90,19 +90,45 @@ function computeVariance(points, nUnits, dims) {
 
 /**
  * Build the adjacency key — list of [codeA, codeB] pairs for each connection.
- * Matches R's enadata$adjacency.matrix (column-major upper triangle order).
+ * Matches R's rotation$adjacency.key.
+ *
+ * Unordered: the upper triangle in column-major order (choose_two(n) pairs).
+ * Ordered: all n² directed connections in column-major order — column
+ * j*n + i is [codes[i], codes[j]], ground codes[i] → response codes[j]
+ * (as R names it "codes[i] & codes[j]").
  *
  * @param {string[]} codes
+ * @param {boolean}  [ordered=false]
  * @returns {string[][]}  length nConnections, each entry is [codeI, codeJ]
  */
-function buildAdjacencyKey(codes) {
+function buildAdjacencyKey(codes, ordered = false) {
     const key = [];
+    if (ordered) {
+        for (let j = 0; j < codes.length; j++)
+            for (let i = 0; i < codes.length; i++)
+                key.push([codes[i], codes[j]]);
+        return key;
+    }
     for (let j = 1; j < codes.length; j++)
         for (let i = 0; i < j; i++)
             key.push([codes[i], codes[j]]);
     return key;
 }
 
+/**
+ * Connection names, "codeA & codeB" per connection, in network column order
+ * (= R's colnames(set$connection.counts)).
+ *
+ * @param {object}   qe
+ * @param {string[]} codes
+ * @param {boolean}  [ordered=false]
+ * @returns {string[]}
+ */
+function connectionNamesFor(qe, codes, ordered = false) {
+    if (!ordered) return qe.connection_names(codes);
+    return buildAdjacencyKey(codes, true).map(([a, b]) => `${a} & ${b}`);
+}
+
 // ── ENA result object ─────────────────────────────────────────────────────────
 
 class ENAModel {
@@ -250,16 +276,18 @@ function applyCodeMask(networks, codeMask, nCodes, nUnits, nConnections, ordered
 
 function runPipeline(qe, rawNetworks, nUnits, nConnections, codes, unitLabels,
                      metaData, rotMethod, groupA, groupB, dims, gParams,
-                     rowConnectionCounts = null, directedNodes = false) {
-    const connectionNames = qe.connection_names(codes);
+                     rowConnectionCounts = null, ordered = false) {
+    const connectionNames = connectionNamesFor(qe, codes, ordered);
 
     // 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)
+    // Ordered (ONA) models follow ona::model(): zero-network units are left
+    // out of the mean but still shifted by it.
     const { centered: pointsForProjection, centerVec } =
-        center(qe, lineWeights, nUnits, nConnections);
+        center(qe, lineWeights, nUnits, nConnections, ordered);
 
     // Rotate
     let rot;
@@ -298,17 +326,30 @@ function runPipeline(qe, rawNetworks, nUnits, nConnections, codes, unitLabels,
     // Matches rENA's lws.positions.sq, which regresses the projected points onto
     // the SPHERE-normed line weights (enaset$line.weights) — not the centered
     // networks.  Verified node-for-node against R rENA on rs.data.new.csv.
-    // `directedNodes` (ordered networks, used by pria()) solves with libqe's
-    // directed_node_positions, as rENA's optimize() does for ordered sets.
+    // Ordered (ONA) models use libqe's directed_node_positions, as
+    // ona::model() does (via rENA's optimize()).
     const { nodes, centroids } = nodePositions(
-        qe, lineWeights, nUnits, nConnections, points, dims, directedNodes
+        qe, lineWeights, nUnits, nConnections, points, dims, ordered
     );
 
+    // ONA: translate points and nodes so the points' mean is at the origin
+    // (ona::model's center_to_origin; centroids are left as computed, as in R).
+    if (ordered) {
+        const nCodes = nodes.length / dims;
+        for (let d = 0; d < dims; d++) {
+            let mean = 0;
+            for (let u = 0; u < nUnits; u++) mean += points[u * dims + d];
+            mean /= nUnits;
+            for (let u = 0; u < nUnits; u++) points[u * dims + d] -= mean;
+            for (let c = 0; c < nCodes; c++) nodes[c * dims + d] -= mean;
+        }
+    }
+
     // Variance explained (= R's model$variance)
     const variance = computeVariance(points, nUnits, dims);
 
     // Adjacency key (= R's rotation$adjacency.key)
-    const adjacencyKey = buildAdjacencyKey(codes);
+    const adjacencyKey = buildAdjacencyKey(codes, ordered);
 
     return new ENAModel({
         // top-level
@@ -366,6 +407,8 @@ export default async function loadENA() {
          * @param {number[]} [opts.groupB]         - Unit indices for means rotation group B
          * @param {object}   [opts.gParams]        - Pre-built GMR parameters for 'generalized' rotation
          * @param {number}   [opts.dims=2]         - Number of dimensions to return
+         * @param {string[]} [opts.unitsUsed]      - Unit keys to model (= R's units.used);
+         *                                           other units' rows remain as context
          *
          * @returns {ENAModel}
          */
@@ -385,6 +428,7 @@ export default async function loadENA() {
                 dims                 = 2,
                 codeMask,
                 weightModel,
+                unitsUsed,
             } = opts;
 
             if (!codes?.length)         throw new Error('opts.codes is required');
@@ -401,7 +445,7 @@ export default async function loadENA() {
 
             const { codeMatrix, nRows, nCodes, nUnits, unitLabels,
                     unitOf, convoGroups, metaData } =
-                parseData(rows, codes, units, conversations);
+                parseData(rows, codes, units, conversations, unitsUsed);
 
             // Every model accumulates through the tensor path; a plain moving
             // window is expressed as defaultTensor(window).
@@ -416,7 +460,7 @@ export default async function loadENA() {
 
             return runPipeline(qe, rawNetworks, nUnits, nConnections, codes,
                                unitLabels, metaData, rotMethod, groupA, groupB,
-                               dims, gParams, rowConnectionCounts);
+                               dims, gParams, rowConnectionCounts, ordered);
         },
 
         /**
@@ -445,11 +489,12 @@ export default async function loadENA() {
                 tensor:  tensorDef,
                 codeMask,
                 weightModel,
+                unitsUsed,
             } = opts;
 
             const { codeMatrix, nRows, nCodes, nUnits, unitLabels,
                     unitOf, convoGroups, metaData } =
-                parseData(rows, codes, units, conversations);
+                parseData(rows, codes, units, conversations, unitsUsed);
 
             const { networks, rowConnectionCounts } = accumulateTensor(
                 qe, rows, codeMatrix, nRows, nCodes, nUnits,
@@ -460,7 +505,7 @@ export default async function loadENA() {
 
             applyCodeMask(networks, codeMask, codes.length, nUnits, nConnections, ordered);
 
-            const connectionNames = qe.connection_names(codes);
+            const connectionNames = connectionNamesFor(qe, codes, ordered);
             return {
                 connectionCounts: networks, rowConnectionCounts, unitLabels, connectionNames,
                 metaData, nUnits, nConnections,
@@ -468,7 +513,7 @@ export default async function loadENA() {
                 // (= R's ENAAccumulation$`_function.call`).
                 _call: { rows, codes, units, conversations,
                          window: windowSize, binary, ordered, tensor: tensorDef,
-                         weightModel },
+                         weightModel, unitsUsed },
             };
         },
 
@@ -506,12 +551,12 @@ export default async function loadENA() {
                 'maxSize must be greater than minSize to compare windows.'
             );
 
-            const { rows, codes, units, conversations, binary, ordered, weightModel } = call;
+            const { rows, codes, units, conversations, binary, ordered, weightModel, unitsUsed } = call;
 
             // Parse once; only the window size changes between iterations.
             const { codeMatrix, nRows, nCodes, nUnits, unitLabels,
                     unitOf, convoGroups, metaData } =
-                parseData(rows, codes, units, conversations);
+                parseData(rows, codes, units, conversations, unitsUsed);
             const nConnections = ordered ? nCodes * nCodes : qe.choose_two(nCodes);
 
             // 1. Rebuild + fit at each window, collecting unit points.
@@ -525,7 +570,8 @@ export default async function loadENA() {
                 );
                 const model = runPipeline(
                     qe, raw, nUnits, nConnections, codes,
-                    unitLabels, metaData, 'svd', undefined, undefined, dims
+                    unitLabels, metaData, 'svd', undefined, undefined, dims,
+                    undefined, null, ordered
                 );
                 allPoints.push(model.points);
             }
@@ -548,7 +594,7 @@ export default async function loadENA() {
             // 4. Rebuild the accumulation at the selected window size.
             return api.accumulate(rows, {
                 codes, units, conversations, window: bestWindow, binary, ordered,
-                weightModel,
+                weightModel, unitsUsed,
             });
         },
 
@@ -680,7 +726,8 @@ export default async function loadENA() {
          * @param {Object[]} rows
          * @param {object}   opts  - fit() options (codes, units, conversations,
          *                           window, binary, ordered, tensor, weightModel,
-         *                           codeMask, rotation, groupA, groupB, gParams)
+         *                           codeMask, rotation, groupA, groupB, gParams,
+         *                           unitsUsed)
          *                           plus removeNum (default 3) and threshold
          *                           (default 0.95). `dims` is ignored: scoring
          *                           uses dims 1:2 and the variance uses all dims.
@@ -693,7 +740,7 @@ export default async function loadENA() {
                 window: windowSize = 4, binary = true, ordered = false,
                 tensor: tensorDef, weightModel, codeMask,
                 rotation = 'svd', gParams, groupA, groupB,
-                removeNum = 3, threshold = 0.95,
+                removeNum = 3, threshold = 0.95, unitsUsed,
             } = opts;
             if (!codes?.length)         throw new Error('opts.codes is required');
             if (!units?.length)         throw new Error('opts.units is required');
@@ -707,7 +754,7 @@ export default async function loadENA() {
             // Accumulate once, exactly as fit() would for these options.
             const { codeMatrix, nRows, nCodes, nUnits, unitLabels,
                     unitOf, convoGroups, metaData } =
-                parseData(rows, codes, units, conversations);
+                parseData(rows, codes, units, conversations, unitsUsed);
             const { networks: raw } = accumulateTensor(
                 qe, rows, codeMatrix, nRows, nCodes, nUnits,
                 unitOf, convoGroups, tensorDef ?? defaultTensor(windowSize),
@@ -745,8 +792,6 @@ export default async function loadENA() {
                             networks[u * nConn + c] = raw[u * nConnections + cols[c]];
                     keptCodes = codes.filter((_, i) => keep(i));
                 }
-                // Ordered models are scored with directed node positions (R's
-                // ordered pipeline), independent of how fit() places nodes.
                 return runPipeline(qe, networks, nUnits, nConn, keptCodes,
                                    unitLabels, metaData, rotation, groupA, groupB,
                                    nConn, gParams, null, ordered);

package/src/pipeline.js

@@ -133,11 +133,15 @@ export function sphereNorm(qe, networks, nUnits, nConnections) {
  * Subtract column means (center the network space).
  * Excludes all-zero rows from the mean calculation (zero-network exclusion).
  *
+ * @param {boolean} [shiftZeroRows=false]  Also subtract the mean from all-zero
+ *   rows, as rENA's center(exclude_zero_networks = TRUE) does -- the ONA
+ *   convention (ona::model). By default zero-network rows stay at zero, as in
+ *   rENA's ena.make.set().
  * @returns {{ centered: Float64Array, centerVec: Float64Array }}
- *   centered  — mean-subtracted networks (zero-network rows left at zero)
+ *   centered  — mean-subtracted networks
  *   centerVec — the column means used for centering (= R's rotation$center.vec)
  */
-export function center(qe, networks, nUnits, nConnections) {
+export function center(qe, networks, nUnits, nConnections, shiftZeroRows = false) {
     // Identify non-zero rows
     const active = [];
     for (let u = 0; u < nUnits; u++) {
@@ -160,7 +164,7 @@ export function center(qe, networks, nUnits, nConnections) {
     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
+        if (!shiftZeroRows && !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];
         }

package/src/tensor.js

@@ -197,10 +197,13 @@ export function accumulateTensor(qe, rows, codeMatrix, nRows, nCodes, nUnits,
             ? buildContextLookupWithTimes(rows, rowIndices, factors, factorLevels, timesCol)
             : buildContextLookup(rows, rowIndices, factors, factorLevels);
 
-        // Group response rows by unit (within this conversation)
+        // Group response rows by unit (within this conversation). Rows with
+        // no unit (unitOf = -1, excluded via unitsUsed) are never responses,
+        // but stay in convoCodes as context for the other units' windows.
         const unitConvoRows = new Map();
         for (let r = 0; r < nConvo; r++) {
             const unit = unitOf[rowIndices[r]];
+            if (unit < 0) continue;
             if (!unitConvoRows.has(unit)) unitConvoRows.set(unit, []);
             unitConvoRows.get(unit).push(r);  // local (conversation-relative) index
         }