@qe-libs/rena-wasm 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qe-libs/rena-wasm",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "JavaScript/WebAssembly ENA pipeline — thin orchestration layer over @qe-libs/libqe-wasm",
   "main": "src/index.js",
   "type": "module",
@@ -13,7 +13,12 @@
   "publishConfig": {
     "registry": "https://gitlab.com/api/v4/projects/22522458/packages/npm/"
   },
-  "keywords": ["wasm", "ena", "epistemic-network-analysis", "quantitative-ethnography"],
+  "keywords": [
+    "wasm",
+    "ena",
+    "epistemic-network-analysis",
+    "quantitative-ethnography"
+  ],
   "license": "GPL-3.0-only",
   "repository": {
     "type": "git",

package/src/detect.js

@@ -0,0 +1,325 @@
+/**
+ * detect.js — heuristic ENA model-parameter detection.
+ *
+ * Given parsed tabular rows (array of plain objects, one per row, keyed by
+ * column name), suggest which columns are ENA codes, units, and conversations
+ * (a.k.a. horizons), plus a likely group/comparison column.
+ *
+ * Pure JS heuristics — no WASM required, so this is exported synchronously
+ * alongside the async `loadENA()` factory. Parse data however you like
+ * (PapaParse, d.ply, etc.), then pass the rows:
+ *
+ *   import { detectParams } from '@qe-libs/rena-wasm';
+ *   const r = detectParams(rows);
+ *   // r.codes / r.units / r.conversations / r.groups / r.columns
+ *   // r.recommended / r.confidence / r.reason
+ */
+
+// Helper to split a column name into lowercase alphanumeric tokens.
+// Handles camelCase, snake_case, dot.case, hyphen-case, etc.
+function getTokens(str) {
+    const camelSplit = str.replace(/([a-z])([A-Z])/g, '$1 $2');
+    return camelSplit.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+}
+
+// ── name-hint vocabularies ──────────────────────────────────────────────────────
+
+const UNIT_HINTS  = new Set(['user', 'student', 'participant', 'speaker', 'person',
+                             'author', 'subject', 'respondent', 'id', 'name', 'who',
+                             'group', 'condition', 'class', 'team',
+                             'player', 'character', 'actor', 'agent']);
+const CONVO_HINTS = new Set(['group', 'condition', 'session', 'conversation', 'convo',
+                             'episode', 'class', 'team', 'day', 'week', 'period',
+                             'context', 'case', 'trial', 'horizon', 'activity', 'task',
+                             'problem', 'scenario', 'phase', 'stage', 'run', 'round',
+                             'turn', 'half',
+                             'play', 'act', 'scene', 'chapter', 'section']);
+// Names implying free text, scores, or metadata — never codes/units/conversations.
+const EXCLUDE = new Set([
+    'timestamp', 'timestamps', 'time', 'times', 'date', 'dates', 'text', 'texts',
+    'utterance', 'utterances', 'message', 'messages', 'content', 'contents',
+    'line', 'lines', 'row', 'rows', 'index', 'indices', 'notes', 'note',
+    'score', 'scores', 'grade', 'grades', 'level', 'levels', 'change', 'changes',
+    'pre', 'post', 'confidence', 'values', 'value', 'vals', 'val', 'rates', 'rate',
+    'rating', 'ratings'
+]);
+
+// ── column classifiers ──────────────────────────────────────────────────────────
+
+/** A code column: every non-empty value is 0 or 1. */
+export function isBinary(rows, col) {
+    const vals = new Set(rows.map(r => r[col]).filter(v => v !== '' && v != null));
+    return vals.size > 0 && [...vals].every(v => v === '0' || v === '1' || v === 0 || v === 1);
+}
+
+/** Score a column as a UNIT-of-analysis candidate (0–1). 0 = not a candidate. */
+export function scoreUnit(col, nUnique, nRows) {
+    const tokens = getTokens(col);
+    if (nUnique < 2 || nUnique > Math.min(nRows * 0.8, 1000)) return 0;
+    let s = 0.3;
+    if (tokens.some(t => UNIT_HINTS.has(t))) s += 0.5;
+    if (nUnique >= 2 && nUnique <= 200) s += 0.2;
+    return Math.min(s, 1.0);
+}
+
+/** Score a column as a CONVERSATION / horizon (segmentation) candidate (0–1). */
+export function scoreConvo(col, nUnique, nRows) {
+    const tokens = getTokens(col);
+    if (nUnique < 2 || nUnique > Math.min(nRows * 0.5, 500)) return 0;
+    let s = 0.2;
+    if (tokens.some(t => CONVO_HINTS.has(t))) s += 0.6;
+    if (nUnique >= 2 && nUnique <= 100) s += 0.2;
+    return Math.min(s, 1.0);
+}
+
+const round2 = v => Math.round(v * 100) / 100;
+
+// ── main entry point ────────────────────────────────────────────────────────────
+
+/**
+ * Detect ENA model parameters from parsed rows.
+ *
+ * @param {Object[]} rows  Array of row objects keyed by column name.
+ * @returns {{
+ *   recommended: boolean,
+ *   confidence: 'high'|'medium'|'low',
+ *   reason: string,
+ *   nRows: number,
+ *   nCols: number,
+ *   codes: string[],
+ *   units: {column:string,nUnique:number,score:number}[],
+ *   conversations: {column:string,nUnique:number,score:number}[],
+ *   groups: Record<string,string[]>,
+ *   columns: {name:string,nUnique:number,role:string}[],
+ * }}
+ */
+export function detectParams(rows) {
+    const nRows   = Array.isArray(rows) ? rows.length : 0;
+    const headers = nRows > 0 ? Object.keys(rows[0]) : [];
+
+    const codeCols   = [];
+    const columnsData = {};
+
+    // First pass: identify roles, compute nUnique, basic unit/convo scores
+    for (const col of headers) {
+        const tokens = getTokens(col);
+        const vals      = rows.map(r => r[col]).filter(v => v !== '' && v != null);
+        const nUnique   = new Set(vals).size;
+
+        // Calculate variance of string lengths to identify free-text/dialogue columns
+        let lenVar = 0;
+        if (vals.length > 1) {
+            const lengths = vals.map(v => String(v).length);
+            const mean = lengths.reduce((a, b) => a + b, 0) / lengths.length;
+            lenVar = lengths.reduce((a, b) => a + Math.pow(b - mean, 2), 0) / lengths.length;
+        }
+
+        if (tokens.some(t => EXCLUDE.has(t)) || lenVar > 100) {
+            columnsData[col] = { role: 'metadata', nUnique, uScore: 0, cScore: 0 };
+            continue;
+        }
+
+        if (isBinary(rows, col)) {
+            codeCols.push(col);
+            columnsData[col] = { role: 'code', nUnique, uScore: 0, cScore: 0 };
+            continue;
+        }
+
+        const uScore = scoreUnit(col, nUnique, nRows);
+        const cScore = scoreConvo(col, nUnique, nRows);
+        columnsData[col] = { role: 'candidate', nUnique, uScore, cScore };
+    }
+
+    // Find the primary unit column (highest uScore, tie-break by nUnique)
+    let primaryUnitCol = null;
+    let maxUScore = -1;
+    let maxUnique = -1;
+
+    for (const col of headers) {
+        const data = columnsData[col];
+        if (data.role !== 'candidate') continue;
+        if (data.uScore > maxUScore || (data.uScore === maxUScore && data.nUnique > maxUnique)) {
+            maxUScore = data.uScore;
+            maxUnique = data.nUnique;
+            primaryUnitCol = col;
+        }
+    }
+
+    // Second pass: apply split penalty for units, and nesting penalty for conversations
+    const unitCands  = [];   // [score, col, nUnique]
+    const convoCands = [];
+    const columns    = [];
+
+    // Identify which columns are valid conversation candidates to check nesting
+    const convoCandidateCols = headers.filter(col => {
+        const data = columnsData[col];
+        return data && data.role === 'candidate' && data.cScore > 0;
+    });
+
+    for (const col of headers) {
+        const data = columnsData[col];
+        if (data.role === 'metadata') {
+            columns.push({ name: col, nUnique: data.nUnique, role: 'metadata' });
+            continue;
+        }
+        if (data.role === 'code') {
+            columns.push({ name: col, nUnique: data.nUnique, role: 'code' });
+            continue;
+        }
+
+        let uScore = data.uScore;
+        let cScore = data.cScore;
+
+        if (col === primaryUnitCol) {
+            uScore = data.uScore;
+        } else if (primaryUnitCol) {
+            // Check if combining col with primaryUnitCol increases the number of unique units
+            const combinedVals = rows.map(r => `${r[primaryUnitCol]}|||${r[col]}`).filter(v => !v.includes('null') && !v.includes('undefined'));
+            const nCombinedUnique = new Set(combinedVals).size;
+
+            if (nCombinedUnique > maxUnique) {
+                // Splits the primary unit into multiple smaller units. Penalize the score.
+                uScore = Math.max(0, uScore - 0.25);
+            }
+        }
+
+        // Conversation nesting penalty: B is nested under A if B has more unique values,
+        // and combining A + B doesn't increase unique combinations beyond soft-nesting limit.
+        if (cScore > 0) {
+            let nParents = 0;
+            for (const parentCol of convoCandidateCols) {
+                if (parentCol === col) continue;
+                const parentData = columnsData[parentCol];
+
+                if (parentData.nUnique < data.nUnique) {
+                    const combinedVals = rows.map(r => `${r[parentCol]}|||${r[col]}`).filter(v => !v.includes('null') && !v.includes('undefined'));
+                    const nCombinedUnique = new Set(combinedVals).size;
+                    const ratio = nCombinedUnique / data.nUnique;
+
+                    if (ratio <= 2.5) {
+                        nParents++;
+                    }
+                }
+            }
+            if (nParents > 0) {
+                cScore = Math.max(0.1, cScore - nParents * 0.15);
+            }
+        }
+
+        if (uScore > 0 || cScore > 0) {
+            const role = uScore >= cScore ? 'unit_candidate' : 'conversation_candidate';
+            if (uScore > 0) unitCands.push([uScore, col, data.nUnique]);
+            if (cScore > 0) convoCands.push([cScore, col, data.nUnique]);
+            columns.push({ name: col, nUnique: data.nUnique, role });
+        } else {
+            columns.push({ name: col, nUnique: data.nUnique, role: 'other' });
+        }
+    }
+
+    unitCands.sort((a, b) => b[0] - a[0] || b[2] - a[2]);
+    convoCands.sort((a, b) => b[0] - a[0] || a[2] - b[2]);
+
+    const units = unitCands.slice(0, 5).map(([s, c, u]) =>
+        ({ column: c, nUnique: u, score: round2(s) }));
+    const conversations = convoCands.slice(0, 5).map(([s, c, u]) =>
+        ({ column: c, nUnique: u, score: round2(s) }));
+
+    // Compute suggested combined selections in the correct nesting order
+    const suggestedUnits = [];
+    if (primaryUnitCol) {
+        // Find other unit columns that don't split the primary unit
+        const nestingUnitCols = [];
+        for (const [score, col, nUnique] of unitCands) {
+            if (col === primaryUnitCol) continue;
+            if (score >= 0.5) {
+                const combinedVals = rows.map(r => `${r[primaryUnitCol]}|||${r[col]}`).filter(v => !v.includes('null') && !v.includes('undefined'));
+                const nCombinedUnique = new Set(combinedVals).size;
+                if (nCombinedUnique === maxUnique) {
+                    nestingUnitCols.push({ col, nUnique });
+                }
+            }
+        }
+        // Sort nesting columns by nUnique ascending (broadest first)
+        nestingUnitCols.sort((a, b) => a.nUnique - b.nUnique);
+        nestingUnitCols.forEach(x => suggestedUnits.push(x.col));
+        suggestedUnits.push(primaryUnitCol);
+    }
+
+    const suggestedConversations = [];
+    if (convoCands.length > 0) {
+        const convo1 = convoCands[0][1];
+        const nUnique1 = convoCands[0][2];
+        let convo2 = null;
+        for (let i = 1; i < convoCands.length; i++) {
+            const score = convoCands[i][0];
+            const col = convoCands[i][1];
+            const nUniqueCol = convoCands[i][2];
+            if (score >= 0.5 && nUniqueCol > nUnique1) {
+                const combinedVals = rows.map(r => `${r[convo1]}|||${r[col]}`).filter(v => !v.includes('null') && !v.includes('undefined'));
+                const nCombinedUnique = new Set(combinedVals).size;
+                const ratio = nCombinedUnique / nUniqueCol;
+                if (ratio > 1.01) { // Orthogonal/crosses
+                    convo2 = col;
+                    break;
+                }
+            }
+        }
+        suggestedConversations.push(convo1);
+        if (convo2) suggestedConversations.push(convo2);
+    }
+
+    // First convo candidate with a small, discrete value set → a comparison variable.
+    const groups = {};
+    for (const [, col, nUnique] of convoCands.slice(0, 3)) {
+        if (nUnique >= 2 && nUnique <= 8) {
+            groups[col] = [...new Set(rows.map(r => String(r[col])).filter(Boolean))].sort();
+            break;
+        }
+    }
+
+    const nCodes   = codeCols.length;
+    const hasUnits = unitCands.length  > 0 && unitCands[0][0]  >= 0.3;
+    const hasConvo = convoCands.length > 0 && convoCands[0][0] >= 0.2;
+
+    let recommended, confidence, reason;
+    if (nCodes >= 3 && hasUnits && hasConvo) {
+        recommended = true;
+        confidence  = nCodes >= 5 && unitCands[0][0] >= 0.7 ? 'high' : 'medium';
+        reason = `Found ${nCodes} binary code columns, a likely unit column ` +
+            `('${unitCands[0][1]}', ${unitCands[0][2]} unique values), and a likely ` +
+            `conversation column ('${convoCands[0][1]}', ${convoCands[0][2]} unique values).`;
+    } else if (nCodes >= 2 && (hasUnits || hasConvo)) {
+        recommended = true;
+        confidence  = 'low';
+        reason = `Found ${nCodes} binary code column(s) and partial structure. ENA may be applicable.`;
+    } else if (nCodes >= 2) {
+        recommended = true;
+        confidence  = 'low';
+        reason = `Found ${nCodes} binary code columns but no clear unit/conversation columns by name.`;
+    } else if (nCodes === 1) {
+        recommended = false;
+        confidence  = 'low';
+        reason = `Only 1 binary code column was detected. ENA needs at least 2 (ideally 4+).`;
+    } else {
+        recommended = false;
+        confidence  = 'low';
+        reason = `No binary (0/1) code columns were detected. ENA requires presence/absence code columns.`;
+    }
+
+    return {
+        recommended,
+        confidence,
+        reason,
+        nRows,
+        nCols: headers.length,
+        codes: codeCols,
+        units,
+        conversations,
+        groups,
+        columns,
+        suggestedUnits,
+        suggestedConversations,
+    };
+}
+
+export default detectParams;

package/src/index.js

@@ -42,11 +42,15 @@ import loadLibQE from '@qe-libs/libqe-wasm';
 import { parseData } from './data.js';
 import {
     accumulate, sphereNorm, center,
-    rotateSVD, rotateMeans,
-    project, nodePositions,
+    rotateSVD, rotateMeans, rotateGeneralized,
+    project, nodePositions, spaceDistCorr,
 } from './pipeline.js';
 import { accumulateTensor, defaultTensor } from './tensor.js';
 
+// Heuristic model-parameter detection (units / conversations / codes).
+// Pure JS — re-exported synchronously so callers don't need to load WASM.
+export { detectParams, isBinary, scoreUnit, scoreConvo } from './detect.js';
+
 // ── helpers ───────────────────────────────────────────────────────────────────
 
 /**
@@ -182,7 +186,7 @@ class ENAModel {
 // ── shared pipeline (post-accumulation) ──────────────────────────────────────
 
 function runPipeline(qe, rawNetworks, nUnits, nConnections, codes, unitLabels,
-                     metaData, rotMethod, groupA, groupB, dims) {
+                     metaData, rotMethod, groupA, groupB, dims, gParams) {
     const connectionNames = qe.connection_names(codes);
 
     // Sphere norm → lineWeights (= R's set$line.weights)
@@ -195,7 +199,12 @@ function runPipeline(qe, rawNetworks, nUnits, nConnections, codes, unitLabels,
 
     // Rotate
     let rot;
-    if (rotMethod === 'mean') {
+    if (rotMethod === 'generalized') {
+        if (!gParams) throw new Error(
+            'opts.gParams is required for generalized (GMR) rotation'
+        );
+        rot = rotateGeneralized(qe, pointsForProjection, nUnits, nConnections, gParams);
+    } else if (rotMethod === 'mean') {
         if (!groupA || !groupB) throw new Error(
             'opts.groupA and opts.groupB are required for means rotation'
         );
@@ -267,7 +276,7 @@ function runPipeline(qe, rawNetworks, nUnits, nConnections, codes, unitLabels,
 export default async function loadENA() {
     const qe = await loadLibQE();
 
-    return {
+    const api = {
         /**
          * Run the full ENA pipeline.
          *
@@ -280,9 +289,10 @@ export default async function loadENA() {
          * @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 {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
+         * @param {object}   [opts.gParams]        - Pre-built GMR parameters for 'generalized' rotation
          * @param {number}   [opts.dims=2]         - Number of dimensions to return
          *
          * @returns {ENAModel}
@@ -299,7 +309,9 @@ export default async function loadENA() {
                 rotation: rotMethod  = 'svd',
                 groupA,
                 groupB,
+                gParams,
                 dims                 = 2,
+                codeMask,
             } = opts;
 
             if (!codes?.length)         throw new Error('opts.codes is required');
@@ -326,8 +338,37 @@ export default async function loadENA() {
                 nConnections = qe.choose_two(nCodes);
             }
 
+            // Apply code masking by zeroing out the masked connection columns across all units
+            if (codeMask && codeMask.length === codes.length) {
+                console.log('[rena-wasm] Applying code mask to raw networks...');
+                if (ordered) {
+                    for (let j = 0; j < codes.length; j++) {
+                        for (let i = 0; i < codes.length; i++) {
+                            if (codeMask[j] && codeMask[j][i] === 0) {
+                                const k = i * codes.length + j;
+                                for (let u = 0; u < nUnits; u++) {
+                                    rawNetworks[u * nConnections + k] = 0;
+                                }
+                            }
+                        }
+                    }
+                } else {
+                    let k = 0;
+                    for (let col = 1; col < codes.length; col++) {
+                        for (let row = 0; row < col; row++) {
+                            if ((codeMask[row] && codeMask[row][col] === 0) || (codeMask[col] && codeMask[col][row] === 0)) {
+                                for (let u = 0; u < nUnits; u++) {
+                                    rawNetworks[u * nConnections + k] = 0;
+                                }
+                            }
+                            k++;
+                        }
+                    }
+                }
+            }
+
             return runPipeline(qe, rawNetworks, nUnits, nConnections, codes,
-                               unitLabels, metaData, rotMethod, groupA, groupB, dims);
+                               unitLabels, metaData, rotMethod, groupA, groupB, dims, gParams);
         },
 
         /**
@@ -343,6 +384,7 @@ export default async function loadENA() {
          *   metaData:         Object[],
          *   nUnits:           number,
          *   nConnections:     number,
+         *   _call:            object,   // args used to build this accumulation (for tuneWindowSize)
          * }}
          */
         accumulate(rows, opts = {}) {
@@ -352,6 +394,7 @@ export default async function loadENA() {
                 binary               = true,
                 ordered              = false,
                 tensor:  tensorDef,
+                codeMask,
             } = opts;
 
             const { codeMatrix, nRows, nCodes, nUnits, unitLabels,
@@ -374,9 +417,122 @@ export default async function loadENA() {
                 nConnections = qe.choose_two(nCodes);
             }
 
+            // Apply code masking by zeroing out the masked connection columns across all units
+            if (codeMask && codeMask.length === codes.length) {
+                console.log('[rena-wasm] Applying code mask to accumulated networks...');
+                if (ordered) {
+                    for (let j = 0; j < codes.length; j++) {
+                        for (let i = 0; i < codes.length; i++) {
+                            if (codeMask[j] && codeMask[j][i] === 0) {
+                                const k = i * codes.length + j;
+                                for (let u = 0; u < nUnits; u++) {
+                                    networks[u * nConnections + k] = 0;
+                                }
+                            }
+                        }
+                    }
+                } else {
+                    let k = 0;
+                    for (let col = 1; col < codes.length; col++) {
+                        for (let row = 0; row < col; row++) {
+                            if ((codeMask[row] && codeMask[row][col] === 0) || (codeMask[col] && codeMask[col][row] === 0)) {
+                                for (let u = 0; u < nUnits; u++) {
+                                    networks[u * nConnections + k] = 0;
+                                }
+                            }
+                            k++;
+                        }
+                    }
+                }
+            }
+
             const connectionNames = qe.connection_names(codes);
-            return { connectionCounts: networks, unitLabels, connectionNames,
-                     metaData, nUnits, nConnections };
+            return {
+                connectionCounts: networks, unitLabels, connectionNames,
+                metaData, nUnits, nConnections,
+                // 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 },
+            };
+        },
+
+        /**
+         * Tune the stanza window size (= R's ena.tune.window.size).
+         *
+         * Rebuilds the accumulation and fits a default SVD model for every
+         * window from `minSize` to `maxSize`, correlates the unit-distance
+         * geometry of adjacent window sizes via spaceDistCorr, and selects the
+         * smallest window whose adjacent correlation reaches
+         * `cutoff * max(correlation)`. Mirrors R by returning a fresh
+         * accumulation rebuilt at the selected window size.
+         *
+         * @param {object} accum  - an accumulation returned by accumulate()
+         * @param {object} [opts]
+         * @param {number} [opts.minSize=1]
+         * @param {number} [opts.maxSize=20]
+         * @param {number} [opts.cutoff=0.95]
+         * @returns {object}  accumulation rebuilt at the selected window
+         *                    (selected size available as result._call.window)
+         */
+        tuneWindowSize(accum, opts = {}) {
+            const { minSize = 1, maxSize = 20, cutoff = 0.95 } = opts;
+            const call = accum && accum._call;
+            if (!call) throw new Error(
+                'accum has no stored _call; build it with accumulate() to enable tuning.'
+            );
+            if (call.tensor) throw new Error(
+                'window-size tuning is only supported for the simple (window) accumulation path.'
+            );
+
+            const windowRange = [];
+            for (let w = minSize; w <= maxSize; w++) windowRange.push(w);
+            if (windowRange.length < 2) throw new Error(
+                'maxSize must be greater than minSize to compare windows.'
+            );
+
+            const { rows, codes, units, conversations, binary } = call;
+
+            // Parse once; only the window size changes between iterations.
+            const { codeMatrix, nRows, nCodes, nUnits, unitLabels,
+                    unitOf, convoGroups, metaData } =
+                parseData(rows, codes, units, conversations);
+            const nConnections = qe.choose_two(nCodes);
+
+            // 1. Rebuild + fit at each window, collecting unit points.
+            const dims = 2;
+            const allPoints = [];
+            for (const w of windowRange) {
+                const raw = accumulate(
+                    qe, codeMatrix, nRows, nCodes, nUnits,
+                    unitOf, convoGroups, w, binary
+                );
+                const model = runPipeline(
+                    qe, raw, nUnits, nConnections, codes,
+                    unitLabels, metaData, 'svd', undefined, undefined, dims
+                );
+                allPoints.push(model.points);
+            }
+
+            // 2. Adjacent-window distance-space correlations.
+            const nSteps = windowRange.length - 1;
+            const corr = new Array(nSteps);
+            for (let i = 0; i < nSteps; i++) {
+                corr[i] = spaceDistCorr(allPoints[i], allPoints[i + 1], nUnits, dims);
+            }
+
+            // 3. Smallest window crossing cutoff * max correlation.
+            const finite = corr.filter(v => !Number.isNaN(v));
+            const maxCorr = finite.length ? Math.max(...finite) : NaN;
+            const threshold = cutoff * maxCorr;
+            let bestIdx = corr.findIndex(v => v >= threshold);
+            if (bestIdx < 0) bestIdx = 0;
+            const bestWindow = windowRange[bestIdx];
+
+            // 4. Rebuild the accumulation at the selected window size.
+            return api.accumulate(rows, {
+                codes, units, conversations, window: bestWindow, binary,
+            });
         },
 
         /**
@@ -430,4 +586,6 @@ export default async function loadENA() {
          */
         defaultTensor,
     };
+
+    return api;
 }

package/src/pipeline.js

@@ -35,6 +35,87 @@ export function sliceCols(data, nRows, nCols, nDims) {
     return out;
 }
 
+/**
+ * Pearson correlation of two paired numeric vectors.
+ * Returns NaN if either vector has zero variance.
+ */
+function pearson(x, y) {
+    const n = x.length;
+    if (n === 0) return NaN;
+    let mx = 0, my = 0;
+    for (let i = 0; i < n; i++) { mx += x[i]; my += y[i]; }
+    mx /= n; my /= n;
+    let sxy = 0, sxx = 0, syy = 0;
+    for (let i = 0; i < n; i++) {
+        const dx = x[i] - mx, dy = y[i] - my;
+        sxy += dx * dy; sxx += dx * dx; syy += dy * dy;
+    }
+    const denom = Math.sqrt(sxx * syy);
+    return denom === 0 ? NaN : sxy / denom;
+}
+
+/**
+ * Pearson correlation between the pairwise distances of two ENA spaces.
+ *
+ * Computes the Euclidean distance between every pair of points within `A` and
+ * within `B` (same pairing for both), then correlates the two distance vectors.
+ * Because pairwise distances are invariant to rotation/reflection of a space,
+ * this measures configuration similarity up to an orthogonal transform — the
+ * right tool for comparing ENA solutions across window sizes whose SVD axes may
+ * flip sign. Mirrors R's ena_space_dist_corr: exact for small spaces, sampled
+ * (with replacement, self-pairs dropped) once unique pairs exceed the limit.
+ *
+ * @param {Float64Array} A               m × d, row-major
+ * @param {Float64Array} B               m × d, row-major
+ * @param {number}       m               number of points (rows)
+ * @param {number}       d               dimensions (cols)
+ * @param {number}       [maxSampleSize=100000]
+ * @param {() => number} [rand=Math.random]  RNG for the sampled path
+ * @returns {number}  Pearson correlation of the paired distance vectors
+ */
+export function spaceDistCorr(A, B, m, d, maxSampleSize = 100000, rand = Math.random) {
+    if (!m || m === 0) throw new Error('The spaces must have a non-zero number of rows.');
+
+    const dist = (M, p, q) => {
+        let s = 0;
+        for (let c = 0; c < d; c++) {
+            const diff = M[p * d + c] - M[q * d + c];
+            s += diff * diff;
+        }
+        return Math.sqrt(s);
+    };
+
+    const totalPairs = (m * (m - 1)) / 2;
+
+    let distA, distB;
+    if (totalPairs <= maxSampleSize) {
+        // Exact: all unique i<j pairs.
+        distA = new Float64Array(totalPairs);
+        distB = new Float64Array(totalPairs);
+        let k = 0;
+        for (let i = 0; i < m; i++)
+            for (let j = i + 1; j < m; j++) {
+                distA[k] = dist(A, i, j);
+                distB[k] = dist(B, i, j);
+                k++;
+            }
+    } else {
+        // Sample pairs with replacement, drop self-pairs.
+        const a = [], b = [];
+        for (let s = 0; s < maxSampleSize; s++) {
+            const i = Math.floor(rand() * m);
+            const j = Math.floor(rand() * m);
+            if (i === j) continue;
+            a.push(dist(A, i, j));
+            b.push(dist(B, i, j));
+        }
+        distA = Float64Array.from(a);
+        distB = Float64Array.from(b);
+    }
+
+    return pearson(distA, distB);
+}
+
 // ── accumulation ─────────────────────────────────────────────────────────────
 
 /**
@@ -181,6 +262,89 @@ export function rotateMeans(qe, centered, nUnits, nConnections, groupA, groupB)
     };
 }
 
+/**
+ * Generalized Means Rotation (GMR).
+ *
+ * Mirrors R's ena.rotate.by.generalized() / libqe::generalized_means_rotation().
+ * Handles Lasso-adjusted OLS covariate control, between-group scatter for
+ * categorical targets, optional Y axis, and SVD completion.
+ *
+ * All matrix inputs are row-major Float64Arrays; all index arrays are Int32Arrays.
+ *
+ * @param {object}       qe
+ * @param {Float64Array} centered         nUnits × nConnections, row-major
+ * @param {number}       nUnits
+ * @param {number}       nConnections
+ * @param {object}       p                Pre-built GMR parameters
+ * @param {Float64Array} p.xModelMatrix   nUnits × xmCols row-major model matrix
+ *                                        (treatment coding, reference = level[0])
+ * @param {number}       p.xmRows         must equal nUnits
+ * @param {number}       p.xmCols         number of dummy columns (nGroups - 1)
+ * @param {Float64Array} p.xTarget        nUnits — 0-based integer codes for target
+ * @param {Int32Array}   p.x1Cols         0-based column indices in xModelMatrix for the target
+ * @param {boolean}      p.xCategorical
+ * @param {number}       p.xNGroups       number of distinct levels
+ * @param {Int32Array}   p.xSubset        0-based unit-row indices used for GMR fit
+ * @param {boolean}      [p.hasY=false]   whether a Y-axis GMR target is provided
+ * @param {Float64Array} [p.yModelMatrix] (ignored when hasY=false)
+ * @param {number}       [p.ymRows]
+ * @param {number}       [p.ymCols]
+ * @param {Float64Array} [p.yTarget]
+ * @param {Int32Array}   [p.y1Cols]
+ * @param {boolean}      [p.yCategorical=false]
+ * @param {number}       [p.yNGroups=0]
+ * @param {number}       [p.nLambda=50]
+ * @param {number}       [p.kFolds=5]
+ * @param {number}       [p.lassoEps=0.01]
+ * @returns {{ rotation, rotRows, rotCols, eigenvalues, columnNames }}
+ */
+export function rotateGeneralized(qe, centered, nUnits, nConnections, p) {
+    const hasY    = !!p.hasY;
+    const nLambda = (p.nLambda  ?? 50)   | 0;
+    const kFolds  = (p.kFolds   ?? 5)    | 0;
+    const lassoEps = p.lassoEps ?? 0.01;
+
+    // Stub Y params when hasY=false — C++ ignores them but still needs valid arrays.
+    const yMM   = hasY ? p.yModelMatrix : new Float64Array(nUnits);
+    const ymR   = hasY ? (p.ymRows | 0) : nUnits;
+    const ymC   = hasY ? (p.ymCols | 0) : 1;
+    const yTgt  = hasY ? p.yTarget      : new Float64Array(nUnits);
+    const y1C   = hasY ? p.y1Cols       : new Int32Array([0]);
+    const yCat  = hasY ? !!p.yCategorical : false;
+    const yNGrp = hasY ? ((p.yNGroups || 0) | 0) : 0;
+
+    let r;
+    try {
+        r = qe.generalized_means_rotation(
+            centered,        nUnits,        nConnections,
+            p.xModelMatrix,  p.xmRows | 0,  p.xmCols | 0,
+            p.xTarget,
+            p.x1Cols,
+            !!p.xCategorical, (p.xNGroups | 0),
+            p.xSubset,
+            hasY,
+            yMM,  ymR,  ymC,
+            yTgt,
+            y1C,
+            yCat,  yNGrp,
+            nLambda, kFolds, lassoEps
+        );
+    } catch (err) {
+        throw new Error(
+            'Rotation by Regression failed: the target variable or group selection ' +
+            'has zero variance or insufficient rank across units.'
+        );
+    }
+
+    return {
+        rotation:    r.rotation.data,
+        rotRows:     r.rotation.rows,
+        rotCols:     r.rotation.cols,
+        eigenvalues: r.eigenvalues,
+        columnNames: r.column_names,
+    };
+}
+
 // ── projection & node positions ───────────────────────────────────────────────
 
 /**