@qe-libs/rena-wasm 0.1.4 → 0.1.5

package/README.md

@@ -34,8 +34,8 @@ const model = ena.fit(rows, {
 
 model.model.centroids  // Float64Array  nUnits × dims
 model.lineWeights      // Float64Array  nUnits × nConnections (normed)
-model.connectionCounts // Float64Array  nUnits × nConnections (raw unit counts)
-model.rowConnectionCounts // Float64Array nRows × nConnections (raw row counts)
+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.rotation.nodes   // Float64Array  nCodes × dims
 model.connectionNames  // ['Data & Technical.Constraints', ...]
 model.model.unitLabels // ['UserName1_ConditionA', ...]
@@ -67,6 +67,30 @@ const model = ena.fit(rows, {
 
 ---
 
+## 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()`.
+
+```js
+const model = ena.fit(rows, { codes, units, conversations, window: 4, weightModel: 'sqrt' });
+```
+
+---
+
 ## Accumulation Only
 
 Returns raw (un-normalised) network vectors without running the full pipeline.
@@ -92,7 +116,7 @@ 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) when using tensors
+  ordered: true,   // directed (n² connections); also works without a tensor
   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.4",
+  "version": "0.1.5",
   "description": "JavaScript/WebAssembly ENA pipeline — thin orchestration layer over @qe-libs/libqe-wasm",
   "main": "src/index.js",
   "type": "module",
@@ -31,7 +31,7 @@
     "resolver": "<rootDir>/jest-resolver.cjs"
   },
   "dependencies": {
-    "@qe-libs/libqe-wasm": "^0.1.4"
+    "@qe-libs/libqe-wasm": "^0.1.5"
   },
   "devDependencies": {
     "jest": "^29.0.0"

package/src/index.js

@@ -190,21 +190,22 @@ class ENAModel {
 // ── weight models (= R's `weight.by`) ────────────────────────────────────────
 
 /**
- * Map a weight-model name to its element-wise transform, matching the webtool's
- * server.js mapping to R weight.by functions:
- *   'sqrt'    → Math.sqrt          (R "sqrt")
- *   'log'     → Math.log1p         (R "log1p", i.e. log(x+1); guards log(0))
- *   'product' → identity           (raw non-binary counts; R's "product" string
- *                                    is not a function, so no transform)
- * A falsy value or 'binary' returns null (binary accumulation, no transform).
+ * Map a rena-wasm weight-model name to the libqe weight model applied per line
+ * (before the per-unit sum) by libqe's finalize_row_connections:
+ *   'sqrt'          → 'sqrt'     (R weight.by = sqrt)
+ *   'log' | 'log1p' → 'log1p'    (log(x+1); guards log(0))
+ *   'product'       → 'product'  (the raw, non-binarized line counts)
+ * A falsy value, 'binary' or an unknown name returns null (binary / `binary`
+ * flag accumulation, no weight model).
  * @param {string|false|undefined} name
- * @returns {((x:number)=>number)|null}
+ * @returns {'sqrt'|'log1p'|'product'|null}
  */
-function weightModelTransform(name) {
+function weightModelName(name) {
     switch (name) {
-        case 'sqrt':    return Math.sqrt;
-        case 'log':     return Math.log1p;
-        case 'product': return (x) => x;
+        case 'sqrt':    return 'sqrt';
+        case 'log':
+        case 'log1p':   return 'log1p';
+        case 'product': return 'product';
         default:        return null;   // binary / off / unknown
     }
 }
@@ -318,7 +319,7 @@ export default async function loadENA() {
          * @param {boolean}  [opts.binary=true]    - Binarise each line's co-occurrences (unordered; ignored when weightModel is set)
          * @param {boolean}  [opts.ordered=false]  - Directed networks
          * @param {object}   [opts.tensor]         - Context tensor definition (overrides window)
-         * @param {string}   [opts.weightModel]    - 'product' | 'sqrt' | 'log' (per-line, before the unit sum)
+         * @param {string}   [opts.weightModel]    - 'product' | 'sqrt' | 'log' (alias 'log1p'); per line, before the unit sum
          * @param {string}   [opts.rotation='svd'] - 'svd', 'mean', or 'generalized'
          * @param {number[]} [opts.groupA]         - Unit indices for means rotation group A
          * @param {number[]} [opts.groupB]         - Unit indices for means rotation group B
@@ -353,12 +354,9 @@ export default async function loadENA() {
             // "product" co-occurrence counts) BEFORE summing per unit, mirroring
             // accumulate.data.R (lapply(.SD, weight.by) over the per-line
             // co-occurrence table, then per-unit aggregation). Because
-            // sqrt(Σ) ≠ Σsqrt, the transform is applied to each row's counts
-            // inside accumulateTensor, not to the unit-summed network.
-            // `product` is the non-binarized row counts themselves (identity);
-            // any weight model therefore forces non-binary accumulation.
-            const weightFn = weightModelTransform(weightModel);
-            const effBinary = weightFn ? false : binary;
+            // sqrt(Σ) ≠ Σsqrt, libqe applies it to each row's counts inside
+            // accumulateTensor, not to the unit-summed network.
+            const weight = weightModelName(weightModel);
 
             const { codeMatrix, nRows, nCodes, nUnits, unitLabels,
                     unitOf, convoGroups, metaData } =
@@ -369,7 +367,7 @@ export default async function loadENA() {
             const { networks: rawNetworks, rowConnectionCounts } = accumulateTensor(
                 qe, rows, codeMatrix, nRows, nCodes, nUnits,
                 unitOf, convoGroups, tensorDef ?? defaultTensor(windowSize),
-                ordered, effBinary, weightFn
+                ordered, binary, weight
             );
             const nConnections = ordered ? nCodes * nCodes : qe.choose_two(nCodes);
 
@@ -412,7 +410,7 @@ export default async function loadENA() {
          * Returns raw (un-normalised) network vectors.
          *
          * @param {Object[]} rows
-         * @param {object}   opts  - codes, units, conversations, window, binary, ordered, tensor
+         * @param {object}   opts  - codes, units, conversations, window, binary, ordered, tensor, weightModel
          * @returns {{
          *   connectionCounts: Float64Array,
          *   rowConnectionCounts: Float64Array | null,
@@ -432,6 +430,7 @@ export default async function loadENA() {
                 ordered              = false,
                 tensor:  tensorDef,
                 codeMask,
+                weightModel,
             } = opts;
 
             const { codeMatrix, nRows, nCodes, nUnits, unitLabels,
@@ -441,7 +440,7 @@ export default async function loadENA() {
             const { networks, rowConnectionCounts } = accumulateTensor(
                 qe, rows, codeMatrix, nRows, nCodes, nUnits,
                 unitOf, convoGroups, tensorDef ?? defaultTensor(windowSize),
-                ordered, binary
+                ordered, binary, weightModelName(weightModel)
             );
             const nConnections = ordered ? nCodes * nCodes : qe.choose_two(nCodes);
 
@@ -481,7 +480,8 @@ export default async function loadENA() {
                 // Retained so tuneWindowSize() can rebuild at other window sizes
                 // (= R's ENAAccumulation$`_function.call`).
                 _call: { rows, codes, units, conversations,
-                         window: windowSize, binary, ordered, tensor: tensorDef },
+                         window: windowSize, binary, ordered, tensor: tensorDef,
+                         weightModel },
             };
         },
 
@@ -519,7 +519,7 @@ export default async function loadENA() {
                 'maxSize must be greater than minSize to compare windows.'
             );
 
-            const { rows, codes, units, conversations, binary, ordered } = call;
+            const { rows, codes, units, conversations, binary, ordered, weightModel } = call;
 
             // Parse once; only the window size changes between iterations.
             const { codeMatrix, nRows, nCodes, nUnits, unitLabels,
@@ -533,7 +533,8 @@ export default async function loadENA() {
             for (const w of windowRange) {
                 const { networks: raw } = accumulateTensor(
                     qe, rows, codeMatrix, nRows, nCodes, nUnits,
-                    unitOf, convoGroups, defaultTensor(w), ordered, binary
+                    unitOf, convoGroups, defaultTensor(w), ordered, binary,
+                    weightModelName(weightModel)
                 );
                 const model = runPipeline(
                     qe, raw, nUnits, nConnections, codes,
@@ -560,6 +561,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,
             });
         },
 

package/src/tensor.js

@@ -119,54 +119,6 @@ export function inferFactorLevels(rows, factors) {
     return levels;
 }
 
-/**
- * Weighted aggregation of a unit's per-response-row directed connection counts.
- *
- * Mirrors the kernel's aggregate_row_connections but applies a weight-model
- * transform (R's weight.by) per LINE before the per-unit sum, so weight models
- * behave identically on the tensor path and the windowed path. Non-binary by
- * construction (the weight replaces the binarize step).
- *
- *   unordered: fold each directed row (m + mᵀ, upper triangle, column-major —
- *              the same order as choose_two/connection_names), weight each
- *              folded cell, then sum across rows.
- *   ordered:   weight each directed cell, then sum across rows.
- *
- * @param {Float64Array|number[]} data  Row-major (nRccRows × nCodes²) counts.
- * @param {number}   nRccRows           Number of response rows for this unit.
- * @param {number}   nCodes
- * @param {boolean}  ordered
- * @param {(x:number)=>number} weightFn
- * @returns {Float64Array}  length nCodes² (ordered) or choose_two(nCodes).
- */
-function aggregateRowConnectionsWeighted(data, nRccRows, nCodes, ordered, weightFn) {
-    const nSq = nCodes * nCodes;
-    if (ordered) {
-        const out = new Float64Array(nSq);
-        for (let r = 0; r < nRccRows; r++) {
-            const base = r * nSq;
-            for (let c = 0; c < nSq; c++) out[c] += weightFn(data[base + c]);
-        }
-        return out;
-    }
-    const nTri = (nCodes * (nCodes - 1)) / 2;
-    const out = new Float64Array(nTri);
-    for (let r = 0; r < nRccRows; r++) {
-        const base = r * nSq;
-        let k = 0;
-        for (let col = 1; col < nCodes; col++) {
-            for (let row = 0; row < col; row++) {
-                // fold: m(row,col) + m(col,row), column-major reshape of the row
-                const folded = data[base + col * nCodes + row] +
-                               data[base + row * nCodes + col];
-                out[k] += weightFn(folded);
-                k++;
-            }
-        }
-    }
-    return out;
-}
-
 /**
  * Accumulate tensor networks for all units across all conversations.
  *
@@ -184,8 +136,11 @@ function aggregateRowConnectionsWeighted(data, nRccRows, nCodes, ordered, weight
  * @param {Map}         convoGroups    convoIdx → [rowIdx, ...]
  * @param {object}      tensorDef      Tensor definition (see module docstring)
  * @param {boolean}     ordered        true → directed (n²); false → undirected
- * @param {boolean}     [binary=true]  binarize each folded row (unordered only)
- * @param {((x:number)=>number)|null} [weightFn=null]  per-line weight transform
+ * @param {boolean}     [binary=true]  binarize each folded row (unordered only);
+ *                                     used when no weight model is given
+ * @param {string|null} [weight=null]  libqe weight model applied per line before
+ *                                     the unit sum: 'binary' | 'product' |
+ *                                     'sqrt' | 'log1p'
  *
  * @returns {{ networks: Float64Array, rowConnectionCounts: Float64Array }}
  *   networks            nUnits × nConnections, row-major
@@ -195,7 +150,7 @@ function aggregateRowConnectionsWeighted(data, nRccRows, nCodes, ordered, weight
  */
 export function accumulateTensor(qe, rows, codeMatrix, nRows, nCodes, nUnits,
                                   unitOf, convoGroups, tensorDef, ordered = false,
-                                  binary = true, weightFn = null) {
+                                  binary = true, weight = null) {
     const {
         dims,
         dimsSender   = [],
@@ -216,6 +171,9 @@ export function accumulateTensor(qe, rows, codeMatrix, nRows, nCodes, nUnits,
     const networks            = new Float64Array(nUnits * nConnections);
     const rowConnectionCounts = new Float64Array(nRows * nConnections);
 
+    // libqe weight argument: a weight-model name, or the legacy binary flag.
+    const kernelWeight = weight ?? binary;
+
     const dimsArr    = new Int32Array(dims);
     const senderArr  = new Int32Array(dimsSender);
     const receiverArr = new Int32Array(dimsReceiver);
@@ -267,24 +225,23 @@ export function accumulateTensor(qe, rows, codeMatrix, nRows, nCodes, nUnits,
                 true
             );
 
-            // Finalise each raw per-response-row connection vector exactly as
-            // tma does in R: fold to the upper triangle and binarize per row
-            // (unordered), or keep the directed row (ordered). A weight model
-            // (R's weight.by) replaces the binarize step with its transform,
-            // applied per line before the per-unit sum. Unweighted rows go
-            // through the libqe kernel so fold/binarize semantics are shared
-            // across every binding. Row i of rcc is local row localRows[i].
+            // Finalise each raw per-response-row connection vector with libqe's
+            // shared kernel, exactly as tma does in R: fold to the upper
+            // triangle (unordered) or keep the directed row (ordered), then
+            // apply the weight model per line (binary clamp, product, sqrt,
+            // log1p) before the per-unit sum. Row i is local row localRows[i].
             const rcc = result.row_connection_counts;
-            for (let i = 0; i < rcc.rows; i++) {
-                const one = rcc.data.slice(i * rcc.cols, (i + 1) * rcc.cols);
-                const rowVec = weightFn
-                    ? aggregateRowConnectionsWeighted(one, 1, nCodes, ordered, weightFn)
-                    : qe.aggregate_row_connections(one, 1, rcc.cols, nCodes, ordered, binary);
-                const rowOff  = rowIndices[localRows[i]] * nConnections;
-                const unitOff = unit * nConnections;
+            const fin = qe.finalize_row_connections(
+                rcc.data, rcc.rows, rcc.cols, nCodes, ordered, kernelWeight
+            );
+            const unitOff = unit * nConnections;
+            for (let i = 0; i < fin.rows; i++) {
+                const rowOff = rowIndices[localRows[i]] * nConnections;
+                const finOff = i * fin.cols;
                 for (let c = 0; c < nConnections; c++) {
-                    rowConnectionCounts[rowOff + c] = rowVec[c];
-                    networks[unitOff + c] += rowVec[c];
+                    const v = fin.data[finOff + c];
+                    rowConnectionCounts[rowOff + c] = v;
+                    networks[unitOff + c] += v;
                 }
             }
         }